微軟 Foundry 模型中的 Codex 和 Azure OpenAI

OpenAI 的 Codex CLI 與支援 ChatGPT Codex 的編碼代理相同。您可以完全在 Azure 基礎結構上執行此編碼代理程式，同時將資料保留在合規性界限內，並具有企業級安全性、私人網路、角色型存取控制和可預測成本管理的額外優勢。 Codex 不僅僅是與您的程式碼代理程式聊天，它是一個非同步編碼代理程式，可以從您的終端機、VS Code 或 GitHub Actions 執行器觸發。 Codex 允許你自動開啟拉取請求、重構檔案，並利用你的 Foundry 專案和 Azure OpenAI 部署的憑證撰寫測試。

先決條件

Azure 訂用帳戶 - 建立免費帳戶
Microsoft Foundry 中的貢獻者權限。
homebrew 或 npm 來安裝 Codex CLI 或具有 Codex 擴充功能的 VS Code。

需求	詳細資訊
作業系統	macOS 12+、Ubuntu 20.04+/Debian 10+ 或 Windows 11 通過 WSL2
Git（可選，建議）	2.23 以上，才能使用內建的提取要求協助程式
RAM	最少 4 GB （建議 8 GB）

在 Foundry 中部署模型

到 Foundry 建立一個新專案。
從模型目錄中選擇一個推理模型，例如 gpt-5.1-codex-max、 gpt-5.1-codex、 gpt-5.1-codex-mini、 gpt-5-codexgpt-5gpt-5-minigpt-5-nano或。
若要從模型目錄部署模型，請選取 [ 使用此模型]，或者如果使用 [Azure OpenAI 部署] 窗格，請選取 [ 部署模型]。
複製端點 URL 和 API 金鑰。

安裝Codex CLI

從終端機中，執行下列命令以安裝 Codex CLI

npm
brew

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

brew install codex
codex --version # verify installation

建立和設定`config.toml`

若要搭配 Azure 使用 Codex CLI，您必須建立並設定檔案 config.toml 。

config.toml 檔案需要儲存在目錄中 ~/.codex 。在此目錄中建立檔案 config.toml ，或編輯現有檔案（如果已存在）：
```
cd ~/.codex
nano config.toml
```

複製以下文字以使用 v1 回應 API。使用 v1 API ，您不再需要傳遞 api-version，但必須在路徑中 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"

將更新儲存到檔案 config.toml 後，返回終端機並建立設定檔中引用的環境變數的實例。
```
# Linux, macOS, or WSL 
export AZURE_OPENAI_API_KEY="<your-api-key>"
```

現在，在終端機中執行下列其中一個命令，以測試您的Codex CLI配置是否成功：

Command	目標
codex	啟動互動式終端機使用者介面（TUI）
編碼集「初始提示」	啟動 TUI 並顯示初始提示
codex exec “初始提示”	以非互動式「自動化模式」啟動 TUI

在 Visual Studio Code 中使用編解碼器

使用 OpenAI Codex 延伸模組時，您也可以直接在 Visual Studio Code 中使用 Codex

如果您還沒有 Visual Studio Code，可以針對 macOS 和 Linux 安裝它。
安裝 OpenAI Codex 擴充功能。延伸模組會依靠針對 Codex CLI 所設定的 config.toml 檔案。
在新的終端機工作階段中，請設定環境變數AZURE_OPENAI_API_KEY：
```
export OPENAI_API_KEY="your-azure-api-key-here"
```
從相同的終端會話啟動 VS Code。 (從應用程式啟動器啟動可能會導致 Codex 延伸模組無法使用您的 API 金鑰環境變數。)
```
code .
```
您現在可以在 Visual Studio Code 中使用 Codex 來聊天、編輯和預覽變更，同時在三種核准模式之間切換。

核准模式

核准模式決定了您希望與 Codex 擁有多少自主權和互動。

核准模式	Description
Chat	與模型進行聊天和規劃。
代理人	Codex 可以自動讀取工作目錄中的檔案、進行編輯和執行命令。若為工作目錄之外的活動或網際網路存取，則 Codex 需要獲得核准。
代理（完整存取權）	在無需逐步審批的情況下，即可使用代理模式的所有功能。在未充分瞭解潛在風險並且沒有實作額外的保護措施（例如在受控沙箱環境中執行）的情況下，不應使用完整存取模式。

這很重要

我們建議檢閱 OpenAI 的 Codex 安全性指南。

透過 AGENTS.md 進行持續指導

使用 AGENTS.md 文件為 Codex 提供額外的說明和指引。 Codex 會在下列位置尋找 AGENTS.md 檔案，並由上而下合併檔案，為其提供有關您個人喜好設定、專案特定詳細資料和目前任務的背景資訊：

~/.codex/AGENTS.md– 個人全球指導。
您存放庫根目錄上的 AGENTS.md - 共用的專案附註。
AGENTS.md 在目前工作目錄中 – 子資料夾/功能細節。

例如，為了幫助 Codex 了解如何撰寫 Foundry Agents 程式碼，你可以在專案根建立 AGENTS.md 一個根目錄，內容來自 Azure AI Agents SDK 文件：

# Instructions for working with 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"

故障排除

癥狀	Solution
`401 Unauthorized` 或 `403 Forbidden`	正確匯出AZURE_OPENAI_API_KEY環境變數。確認您的金鑰具有專案/部署存取權。請確定您沒有將 API 金鑰作為字串直接傳遞到 `env_key` 中的 `config.toml` 檔案。您必須傳遞有效的環境變數。
`ENOTFOUND`、 `DNS error`或 `404 Not Found`	驗證 `base_url` 中的 `config.toml` 是否使用您的資源名稱、正確的網域，且包含 `/v1`。例如： `base_url = "https://<your-resource>.openai.azure.com/openai/v1"` 。
CLI 會忽略 Azure 設定	開放 `~/.codex/config.toml` 並確保： - `model_provider = "azure"` 已設定。 - `[model_providers.azure]` 區段存在。 - `env_key = "AZURE_OPENAI_API_KEY"` 符合您的環境變數名稱。
Entra ID 支援	Entra ID 支援目前不適用於 Codex。
`401 Unauthorized` 僅使用 WSL + VS Code Codex 延伸模組	從具有 Codex 延伸模組的 WSL 內部執行 VS Code 時，該延伸模組可能會檢查本機 Windows 主機上的 API 金鑰環境變數，而非在啟動了 VS Code 的終端機殼層內檢查。若要減輕此問題，請在本機 Windows 主機上設定環境變數，然後從 WSL 啟動新的終端機，並使用 `code .`啟動 VS Code。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-05