在 Azure 上运行 OpenAI Codex CLI 编程智能体

OpenAI 的 Codex CLI 与 ChatGPT 里内置的 Codex 是同一个编程智能体。它不只是”和代码对话”——它是一个异步的代理，能从终端、VS Code 或 GitHub Actions runner 触发，自动打开 PR、重构文件、编写测试。

把它接到 Azure，好处是数据不会离开你的合规边界，同时拿到企业级安全、私有网络、RBAC 权限控制和可预测的成本管理。本文是完整的上手教程，从部署模型到配置 CI 流水线，一步一步来。

前置条件

开始之前确认以下几项都准备好：

• Azure 订阅（没有可以免费创建）
• Microsoft Foundry 项目的 Contributor 权限
• Node.js + npm（用来安装 Codex CLI）；macOS 也可以用 Homebrew
• Windows 用户：需要先安装并配置好 WSL2

系统和硬件要求：

在 Foundry 部署模型

1. 打开 Foundry，创建一个新项目。
2. 进入模型目录，选择一个推理模型部署。支持的模型包括 gpt-5.3-codex、gpt-5.2-codex、gpt-5.1-codex-max、gpt-5.1-codex、gpt-5.1-codex-mini、gpt-5-codex、gpt-5、gpt-5-mini、gpt-5-nano 等。
3. 在模型目录页点击 Use this model，或在 Azure OpenAI 的 Deployments 面板里选 deploy model。
4. 部署完成后，复制 endpoint URL 和 API Key，后面配置时要用到。

安装 Codex CLI

在终端里执行以下命令安装 Codex CLI：

npm install -g @openai/codex
codex --version  # 验证安装成功

配置 config.toml

Codex CLI 用 ~/.codex/config.toml 文件读取 Azure 的连接信息。

第一步：创建或编辑配置文件

cd ~/.codex
nano config.toml

第二步：写入以下内容

model = "gpt-5-codex"  # 替换为你实际的 Azure 模型部署名称
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"

几个注意点：

• base_url 里的 YOUR_RESOURCE_NAME 换成你的 Azure OpenAI 资源名称
• 使用 v1 Responses API，路径里必须包含 /v1，不需要再传 api-version
• env_key 必须指向一个环境变量名，不能直接写 API Key 字符串

第三步：设置环境变量

# Linux、macOS 或 WSL
export AZURE_OPENAI_API_KEY="<你的 API Key>"

第四步：验证配置

运行 codex 能进入 TUI 说明配置正常。

在 VS Code 中使用 Codex

Codex 也有 VS Code 扩展，安装后就能直接在编辑器里调用。

1. 安装 OpenAI Codex 扩展，它会复用已有的 config.toml 配置。

2. 确保终端里设置了环境变量：

   export OPENAI_API_KEY="<你的 Azure API Key>"

   如果你用的是 WSL，Windows 宿主机上也需要设置同名环境变量，否则扩展可能读不到。

3. 从同一个终端会话启动 VS Code：

   code .

   不要从应用启动器打开，否则环境变量不会被扩展继承。

三种审批模式

用 AGENTS.md 给 Codex 加持久指令

Codex 会按照以下顺序读取 AGENTS.md 文件并合并内容，用于理解你的偏好和项目背景：

• ~/.codex/AGENTS.md：个人全局指令
• 仓库根目录的 AGENTS.md：项目共享说明
• 当前工作目录的 AGENTS.md：子目录或功能模块专用说明

举个例子，如果你的项目用到了 Azure AI Agents SDK，可以在项目根目录创建一个 AGENTS.md，里面写清楚如何初始化客户端、如何创建 Agent、Tools 的用法等，Codex 生成代码时就会遵循这些约定。

上手体验

配置完成后，可以用这条命令试试效果：

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

其他可以测试的场景：

# 为某个工具函数生成单元测试
codex "generate a unit test for src/utils/date.ts"

# 把某个 Agent 重构成使用 Code Interpreter 工具
codex "refactor this agent to use the Code Interpreter tool instead"

接入 GitHub Actions

Codex 可以作为 CI 流水线的一个 Job 运行。把 API Key 存到仓库的 Secrets 里（名称为 AZURE_OPENAI_KEY），然后在 workflow 文件里加一个类似这样的 Job：

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"

这样每次发版前就能自动更新 CHANGELOG，不需要手动维护。

常见问题排查

参考

• 原文：How to use OpenAI Codex with Azure AI Foundry
• Codex CLI GitHub 仓库
• OpenAI Codex VS Code 扩展
• Azure AI Foundry