在 Azure AI Foundry 模型中将 Codex 与 Azure OpenAI 配合使用

OpenAI 的 Codex CLI 是支持 ChatGPT Codex 的编码代理。 可以在 Azure 基础结构上完全运行此编码代理，同时将数据保留在合规性边界内，并具有企业级安全性、专用网络、基于角色的访问控制和可预测的成本管理等优势。 Codex 不仅仅是与代码代理聊天 - 它是一种异步编码代理，可以从终端、VS Code 或 GitHub Actions 运行程序触发。 Codex 允许使用 AI Foundry 项目和 Azure OpenAI 部署的凭据自动打开拉取请求、重构文件和编写测试。

先决条件

• Azure 订阅 - 免费创建订阅
• Azure AI Foundry 中的参与者权限。
• homebrew 或 npm，用于安装 Codex CLI 或 VS Code Codex 扩展。

在 Azure AI Foundry 中部署模型

1. 转到 Azure AI Foundry 并创建新项目。
2. 从模型目录中选择一个推理模型，例如gpt-5-codex，gpt-5或gpt-5-minigpt-5-nano。
3. 若要从模型目录部署模型，请选择“ 使用此模型”，或使用 Azure OpenAI 部署 窗格选择 部署模型。
4. 复制终结点 URL 和 API 密钥。

安装 Codex CLI

在终端中运行以下命令以安装 Codex CLI

npm install -g @openai/codex
codex --version # verify installation

brew install codex
codex --version # verify installation

创建和配置 config.toml

1. 若要将 Codex CLI 与 Azure 配合使用，需要创建和设置 config.toml 文件。

   config.toml 文件需要存储在 ~/.codex 目录中。 在此目录中创建文件 config.toml ，或者编辑现有文件（如果已存在）：

   cd ~/.codex
   nano config.toml
   

2. 复制以下文本以使用 v1 响应 API。 使用 v1 API ，不再需要传递 api 版本，但必须在路径中包含 base_url /v1。 不能将 API 密钥作为字符串直接传递给 env_key。 env_key 必须指向环境变量。 使用你的资源名称更新 base_url:

   model = "gpt-5-codex"  # Replace with your actual Azure model deployment name
   model_provider = "azure"
   model_reasoning_effort = "medium"
   
   [model_providers.azure]
   name = "Azure OpenAI"
   base_url = "https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1"
   env_key = "AZURE_OPENAI_API_KEY"
   wire_api = "responses"
   

3. 将更新 config.toml 保存到文件后，返回到终端，并创建配置文件中引用的环境变量实例。

   # Linux, macOS, or WSL 
   export AZURE_OPENAI_API_KEY="<your-api-key>"
   

4. 现在，在终端中运行以下命令之一，以测试 Codex CLI 配置是否成功：

   Command	目的
   编码集	启动交互式终端用户界面 （TUI）
   codex“初始提示”	使用初始提示启动 TUI
   codex exec “初始提示”	在非交互式“自动化模式”中启动 TUI

在 Visual Studio Code 中使用 Codex

使用 OpenAI Codex 扩展时，还可以直接在 Visual Studio Code 中使用 Codex

1. 如果还没有 Visual Studio Code，可以安装适用于 macOS 和 Linux 的 Visual Studio Code。

2. 安装 OpenAI Codex 扩展。 该扩展依赖于为 Codex CLI 配置的 config.toml 文件。

3. 如果您在新的终端会话中，请设置环境变量 AZURE_OPENAI_API_KEY：

   export OPENAI_API_KEY="your-azure-api-key-here"
   

4. 从同一终端会话启动 VS Code。 （从应用启动器启动可能会导致 API 密钥环境变量不适用于 Codex 扩展。

   code .
   

5. 现在，你将能够在 Visual Studio Code 中使用 Codex 聊天、编辑和预览更改，同时切换三种审批模式。

审批模式

审批模式决定了你想要与 Codex 拥有多少自治和交互。

使用 AGENTS.md 的持续指导

可以使用 AGENTS.md 文件为 Codex 提供额外的说明和指导。 Codex 在以下位置查找 AGENTS.md 文件，并从上到下合并这些文件，从而提供关于个人偏好、项目特定细节和当前任务的上下文。

• ~/.codex/AGENTS.md– 个人全球指导。
• AGENTS.md（位于存储库的根目录）- 共享项目备注。
• AGENTS.md（位于当前工作目录中）- 子文件夹/功能细节。

例如，为了帮助 Codex 了解如何为 Azure AI Foundry 代理编写代码，可以使用以下内容在项目根目录中创建一个 AGENTS.md ，这些内容派生自 Azure AI 代理 SDK 文档：

# Instructions for working with Azure AI Foundry Agents

You are an expert in the Azure AI Agents client library for Python.

## Key Concepts

- **Client Initialization**: Always start by creating an `AIProjectClient` or `AgentsClient`. The recommended way is via `AIProjectClient`.
- **Authentication**: Use `DefaultAzureCredential` from `azure.identity`.
- **Agent Creation**: Use `agents_client.create_agent()`. Key parameters are `model`, `name`, and `instructions`.
- **Tools**: Agents use tools to perform actions like file search, code interpretation, or function calls.
  - To use tools, they must be passed to `create_agent` via the `tools` and `tool_resources` parameters or a `toolset`.
  - Example: `file_search_tool = FileSearchTool(vector_store_ids=[...])`
  - Example: `code_interpreter = CodeInterpreterTool(file_ids=[...])`
  - Example: `functions = FunctionTool(user_functions)`

## Example: Creating a basic agent

\`\`\`python
import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

# 1. Create Project Client
project_client = AIProjectClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

# 2. Get Agents Client
with project_client:
    agents_client = project_client.agents

    # 3. Create Agent
    agent = agents_client.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-helpful-agent",
        instructions="You are a helpful agent that can answer questions.",
    )
    print(f"Created agent with ID: {agent.id}")
\`\`\`

在前面的示例中，Python 代码块中的反引号已转义，以确保正常呈现。 可移除 \。

尝试使用 “Codex CLI”

启动 Codex 时使用以下初始提示：

codex "write a python script to create an Azure AI Agent with file search capabilities"

其他建议的测试：

# generate a unit test for src/utils/date.ts

# refactor this agent to use the Code Interpreter tool instead

GitHub Actions 中的 Codex

Codex 可以作为持续集成（CI）管道的一部分执行。 将 API 密钥存储在存储库的机密存储 AZURE_OPENAI_KEY 中，并添加如下所示的作业，以在发布之前自动更新更改日志：

jobs:
  update_changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Update changelog via Codex
        run: |
          npm install -g @openai/codex
          export AZURE_OPENAI_API_KEY="${{ secrets.AZURE_OPENAI_KEY }}" 
          codex -p azure exec --full-auto "update CHANGELOG for next release"

Troubleshooting