Codex CLI 配置教程

Codex CLI 是 OpenAI 开源的命令行 AI 工具，可通过配置接入 Drivecode API。

协议要求：Codex CLI 当前要求 Responses API（/v1/responses），不再使用 Chat Completions。中转站须支持 Responses API 方可完整兼容。

安装 Codex CLI

Windows PowerShell（推荐 npm）

npm.cmd install -g @openai/codex

Windows（官方二进制）

# 从 GitHub Release 下载预编译版本：
# https://github.com/openai/codex/releases

# 下载后将 codex.exe 加入 PATH

验证安装：

codex --version

---

配置 Drivecode API

Codex CLI 接入第三方中转站时，需要在 config.toml 中声明自定义模型提供商，并通过环境变量提供 API Key。

创建配置文件

配置文件路径：

Windows: %USERPROFILE%\.codex\config.toml
macOS/Linux: ~/.codex/config.toml

创建或编辑配置文件：

$configPath = "$env:USERPROFILE\.codex\config.toml"
$configDirectory = Split-Path -LiteralPath $configPath -Parent
$null = [System.IO.Directory]::CreateDirectory($configDirectory)

$toml = @'
model = "<MODEL_ID>"
model_provider = "drivecode"

[model_providers.drivecode]
name = "Drivecode"
base_url = "https://fast.drivecode.top/v1"
env_key = "DRIVECODE_API_KEY"
wire_api = "responses"
requires_openai_auth = false
'@

[System.IO.File]::WriteAllText(
    $configPath,
    $toml,
    [System.Text.UTF8Encoding]::new($false)
)

然后设置 API Key 环境变量：

$env:DRIVECODE_API_KEY = "sk-xxxxxxxxxxxxxxxx"
codex "写一个 Python 脚本计算斐波那契数列"

不要只设置 OPENAI_BASE_URL

自定义中转站应使用上面的 model_provider 配置。仅设置 OPENAI_BASE_URL 不能替代完整的自定义 Provider 配置。

---

使用 Codex CLI

发送一次性指令

codex "解释 Python 的装饰器"

指定模型

codex --model "<MODEL_ID>" "写一个快速排序"

---

完整兼容性验证

Codex CLI 要求 Responses API 同时支持 文本应答、流式和工具调用三项能力。以下冒烟测试逐一验证：

1. 文本应答

$body = @{
    model = "<MODEL_ID>"
    input = "你好，请用一句话介绍自己"
} | ConvertTo-Json -Depth 10 -Compress

curl.exe https://fast.drivecode.top/v1/responses `
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" `
  -H "Content-Type: application/json" `
  -d $body

2. 流式应答

$body = @{
    model = "<MODEL_ID>"
    input = "从 1 数到 5"
    stream = $true
} | ConvertTo-Json -Depth 10 -Compress

curl.exe https://fast.drivecode.top/v1/responses `
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" `
  -H "Content-Type: application/json" `
  -d $body

3. 工具调用请求

$toolRequestBody = @{
    model = "<MODEL_ID>"
    input = "北京现在几点？请调用 get_current_time 工具查询"
    tools = @(
        @{
            type = "function"
            name = "get_current_time"
            description = "获取指定城市的当前时间"
            parameters = @{
                type = "object"
                properties = @{
                    city = @{ type = "string" }
                }
                required = @("city")
                additionalProperties = $false
            }
            strict = $true
        }
    )
} | ConvertTo-Json -Depth 10 -Compress

$toolResponseJson = curl.exe https://fast.drivecode.top/v1/responses `
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" `
  -H "Content-Type: application/json" `
  -d $toolRequestBody

if ($LASTEXITCODE -ne 0) {
    throw "工具调用请求失败，curl 退出码：$LASTEXITCODE"
}

$toolResponse = $toolResponseJson | ConvertFrom-Json
$functionCall = @($toolResponse.output) |
    Where-Object { $_.type -eq "function_call" } |
    Select-Object -First 1

if ($null -eq $functionCall) {
    throw "响应中没有 function_call，当前模型或中转站不支持工具调用"
}

4. 工具结果回传

继续使用上一步返回的 response.id 和 function_call.call_id，验证中转站能完成工具调用闭环：

$toolOutputBody = @{
    model = "<MODEL_ID>"
    previous_response_id = $toolResponse.id
    input = @(
        @{
            type = "function_call_output"
            call_id = $functionCall.call_id
            output = '{"city":"北京","time":"2026-07-24T12:00:00+08:00"}'
        }
    )
} | ConvertTo-Json -Depth 10 -Compress

curl.exe https://fast.drivecode.top/v1/responses `
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" `
  -H "Content-Type: application/json" `
  -d $toolOutputBody

四项均返回正确结果后，才能确认中转站覆盖 Codex CLI 的基础 Responses 工作流。实际使用仍需通过一次真实 Codex 会话验证长连接、上下文续接和工具循环。

成功后前往 使用记录 确认请求已被记录。

---

查询可用模型

curl.exe https://fast.drivecode.top/v1/models `
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"

/v1/models 通常只返回模型 ID，不能据此确认模型是否支持 Responses。选择候选 id 后，逐个运行上面的 /v1/responses 三项冒烟测试；通过后再填入 config.toml 或 --model。

---

常见问题

401 — API Key 无效

检查 $env:DRIVECODE_API_KEY 是否已正确设置，并确认变量名与 config.toml 中的 env_key 完全一致。

404 — Base URL 错误

确认 config.toml 中的 base_url 为 https://fast.drivecode.top/v1（含 /v1）。

模型不支持 Responses API

如果 /v1/responses 路由存在，但候选模型在文本、流式或工具调用测试中失败，说明该模型或中转站尚未完整兼容 Codex。请更换模型测试，或将完整错误信息提交给客服。