本文面向第一次使用 Terminal、第一次配置 Codex CLI，或者需要通过第三方 AI Gateway 使用 Codex CLI 的用户。

完成本文后，你将能够：

  • 安装并确认 Codex CLI；
  • 安全输入 AI Gateway 的 Base URL 和 API Key；
  • 查询自己的 API Key 可以看到的模型；
  • 判断不同厂商模型适用的请求协议；
  • 用 OpenAI Responses 验证目标模型；
  • 将通过验证的模型写入 
    ~/.codex/config.toml
    ~/.codex/config.toml
    ；
  • 用 
    codex doctor
    codex doctor
    和 
    codex exec
    codex exec
    确认连接；
  • 根据错误信息判断是网络、认证、协议、配置还是上游问题。

本文以 macOS、zsh 和以下 AI Gateway 为例：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1>

如果你的中转站地址不同，只需要替换 Base URL、API Key 和模型 ID。不要把真实 API Key 发到聊天、工单、截图、Git 仓库或公开网页。

本文示例环境与验证范围：

适用系统：macOS、zsh 验证版本：Codex CLI 0.148.0-alpha.9 最后验证：2026-08-19（Asia/Shanghai） 基础协议：OpenAI Responses 基础验收：/models、/responses 和 codex exec 文本调用

Codex CLI 和 AI Gateway 会持续更新。本文聚焦协议识别、配置步骤和实际验证，不把某一时刻的模型状态当作永久保证。

先看结论：模型厂商和请求协议是两件事

Codex CLI 通过自定义 provider 接入 AI Gateway 时，配置中的 

wire_api
wire_api
决定请求格式。模型名称中的厂商前缀不会自动切换协议。

本文推荐使用一个自定义 provider：

Codex 配置项
wire_api
wire_api
AI Gateway 端点什么时候使用
model_providers.clickzetta
model_providers.clickzetta
responses
responses
/responses
/responses
目标模型的 Responses curl 成功，并准备给 Codex 使用
OpenAI Chat CompletionsCodex 自定义 provider 不支持
/chat/completions
/chat/completions
仅用于其他客户端或诊断模型是否有 Chat 路由
Anthropic MessagesCodex 自定义 provider 不支持
/messages
/messages
仅用于其他 Anthropic 客户端；Codex 需要额外转换层

官方配置中，自定义 provider 的 

wire_api
wire_api
只有 
responses
responses
一个有效值。也就是说：

  1. Codex 对该 provider 发送 
    POST /responses
    POST /responses
    ；
  2. Codex 不会根据 
    anthropic/
    anthropic/
    、
    deepseek/
    deepseek/
    或 
    qwen/
    qwen/
    前缀切换协议；
  3. Chat 或 Anthropic 请求成功，不代表同一个模型可以给 Codex 使用；
  4. Claude 如果只有 
    /messages
    /messages
    路由，必须通过中转站或本地代理转换成 
    /responses
    /responses
    ；
  5. /models
    /models
    中出现模型，只说明当前 API Key 可以看到它，不代表 
    /responses
    /responses
    一定有上游。

按模型厂商选择协议

下面的矩阵用于选择验证路径，不是固定模型清单。具体模型必须以自己的 

/models
/models
结果和对应端点测试为准：

模型厂商或系列OpenAI Chat CompletionsOpenAI ResponsesAnthropic MessagesCodex 配置建议
OpenAI GPT、Codex 系列网关提供时可用常见兼容路径，但必须单独测试通常不是首选只有 Responses 测试成功才能直接配置
Anthropic Claude只有网关提供兼容路由时使用需要单独测试，不能从名称推断原生接入路径，通常优先测试Codex 需要 Responses 兼容层
DeepSeek 系列网关提供时可用需要单独测试网关提供时可用只选择实际通过 Responses 的模型
Qwen 系列网关提供时可用需要单独测试网关提供时可用先验证 Responses，再确认 reasoning 参数
Gemini、Grok、Mistral、Meta 及其他系列由网关适配决定由网关适配决定由网关适配决定以实际端点测试结果为准

最重要的规则是：

模型厂商 ≠ 请求协议 模型出现在目录中 ≠ 模型可以通过 Codex 使用 Responses curl 成功 ≠ 文件、工具、搜索和多模态全部可用

只使用 Codex 时，先配置一个 Responses provider 即可；不需要为了测试 Chat 或 Anthropic 协议而在 

config.toml
config.toml
中创建不存在的 
wire_api
wire_api
值。

0. 完整操作路线

第一次配置时，请按以下顺序操作：

1. 第 2 节：安装或确认 Codex CLI 2. 第 3 节：安全输入 API Key 3. 第 4 节：查询自己的模型目录并选择完整模型 ID 4. 第 5 节：用 Responses curl 验证目标模型 5. 第 6 节：备份并写入 ~/.codex/config.toml 6. 第 7 节：运行 strict config 和 doctor 7. 第 8 节：用 codex exec 返回第一条真实文本 8. 第 18 节：确认配置完成后的效果和检查清单

完成第 8 步后，你已经具备 Codex 的基础文本和编码能力。工具调用、文件修改、流式、多模态和搜索能力见第 9、12、13 节，需要按实际场景继续验证。

如果只需要基础文本接入，可以直接执行第 2–8 节；只有在以下情况才需要详细阅读第 9–12 节：

  • 想确认某个厂商模型为什么不能给 Codex 使用；
  • 想使用 Claude 或其他 Anthropic 模型；
  • 想使用 CC Switch 或其他协议转换层；
  • 想判断工具、流式、搜索或多模态能力是否兼容。

配置完成的最基本验收标准是：

  1. 对应 API Key 能看到目标模型；
  2. 目标协议的请求端点返回 HTTP 200；
  3. 响应中存在最终文本；
  4. codex exec
    codex exec
    返回实际模型文本；
  5. 如果要使用工具或修改文件，再单独验证权限和工具调用。

只看到模型名称，不能直接说明模型可以在 Codex 中使用。

配置完成后可以得到什么效果

完成第 8 节后，你将能够：

  • 在项目目录中运行 
    codex
    codex
    ，进入交互式编码会话；
  • 使用配置中的默认模型发送任务；
  • 使用 
    codex exec --model YOUR_MODEL_ID
    codex exec --model YOUR_MODEL_ID
    临时切换到另一个已验证模型；
  • 让 Codex 在配置的审批策略和沙箱范围内读取文件、修改工作区并运行命令；
  • 在需要时通过 
    codex doctor
    codex doctor
    和标准 curl 区分客户端、网络、权限和上游问题。

本指南默认验收的是“Responses 文本调用”。文件修改、工具调用、流式、多模态和搜索能力仍受模型、provider、沙箱和上游实现共同影响，不能因为第一条文本回复成功就自动视为全部支持。

Codex CLI 是本机命令行客户端，不是常驻 Gateway 服务。本文只适用于 Codex CLI；OpenClaw、Claude Code、OpenCode 等工具的 provider 配置不能直接复制到 Codex。

1. 准备信息

1.1 Base URL

本示例使用：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1>

地址已经包含 

/v1
/v1
。不要写成：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/v1>

Codex 会在 Base URL 后面追加 

/responses
/responses
，最终请求类似：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/responses>

不要把 Base URL 直接写到 

/responses
/responses
，否则客户端可能重复追加路径。

1.2 API Key

请到 AI Gateway 后台创建 API Key，并确认：

  • API Key 没有过期；
  • API Key 有目标模型权限；
  • API Key 与 Base URL 属于同一个环境；
  • API Key 对 OpenAI Responses 路由有权限；
  • 复制时没有多余空格或换行。

同一个 Token 能访问 Chat 或 Anthropic 路由，不代表一定有 Responses 路由权限。

1.3 模型 ID

模型 ID 必须从当前 API Key 的 

/models
/models
返回值中原样复制。下面的 
YOUR_MODEL_ID
YOUR_MODEL_ID
只是占位符，必须替换成你自己的完整模型 ID：

YOUR_MODEL_ID

Codex 的 

--model
--model
参数填写上游模型 ID，不需要再拼接 Codex provider ID。

正确：

--model YOUR_MODEL_ID

不要写成：

--model clickzetta/YOUR_MODEL_ID

clickzetta
clickzetta
是本地 provider ID，
YOUR_MODEL_ID
YOUR_MODEL_ID
才是发送给 AI Gateway 的模型 ID。

1.4 在哪里操作

本文命令都在 macOS Terminal 执行。

按 Command + Space，输入 Terminal，按回车打开。

终端提示符可能类似：

a123@Mac ~ %

不要复制提示符，只复制代码框中的命令。

1.5 是否需要 VPN

AI Gateway 本身是否需要 VPN，以本机网络测试为准。

执行：

curl -I --connect-timeout 10 \ https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/models

只要能收到 HTTP 响应，就说明域名和网络链路基本可达。401 或 403 也说明网络已经连通，只是还没有正确鉴权。

以下情况才需要检查代理、VPN、防火墙或 DNS：

  • Could not resolve host
    Could not resolve host
    ；
  • Connection timed out
    Connection timed out
    ；
  • TLS 握手持续失败；
  • 公司网络阻止安装脚本或登录页面。

如果上面的检查能收到 HTTP 响应，Codex 调用中转站本身不需要额外 VPN。官方 ChatGPT 登录页和安装源能否直连，则取决于你所在的网络和地区。

2. 安装或确认 Codex CLI

2.1 检查基础工具

执行：

command -v curl command -v jq

看到两个文件路径即可继续。

如果 macOS 没有 

jq
jq
，并且已经安装 Homebrew：

brew install jq jq --version

2.2 检查 Codex CLI

执行：

command -v codex codex --version

正常返回类似：

/path/to/codex codex-cli 0.148.0-alpha.9

版本不同不一定是问题，只要命令能够执行即可。配置字段会随版本更新，正式修改配置前建议查看当前版本的 

codex --help
codex --help
。

2.3 检查是否安装了多个 Codex

执行：

type -a codex

如果返回多个路径，Terminal 实际使用排在第一位的版本。

常见来源包括：

独立安装的 Codex CLI npm 或 Homebrew 安装的 Codex CLI ChatGPT/Codex 桌面应用内置的 CLI

桌面应用内置版本的路径可能类似：

/Applications/ChatGPT.app/Contents/Resources/codex

如果“同一个命令在两个 Terminal 表现不同”，优先执行 

type -a codex
type -a codex
和 
codex --version
codex --version
，确认实际运行的是哪一份。

2.4 没有安装时

官方文档提供 macOS/Linux 独立安装脚本示例：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

安装后关闭 Terminal，再重新打开，然后执行：

codex --version

官方安装和更新方式可能变化，请以 Codex CLI 官方文档 为准。

2.5 更新 Codex

独立 CLI 可以先尝试：

codex update

如果使用的是桌面应用内置版本，通常应更新桌面应用。更新后再次执行：

command -v codex codex --version

3. 认识 Codex 的认证方式

3.1 官方 OpenAI/ChatGPT 登录

直接使用官方 OpenAI 服务时，可以执行：

codex login

然后在浏览器中完成登录。

使用官方 OpenAI API Key 时，可以执行：

printenv OPENAI_API_KEY | codex login --with-api-key

查看当前登录状态：

codex login status

清除登录凭据：

codex logout

3.2 中转站推荐使用 
env_key
env_key

第三方 AI Gateway 更适合使用自定义 provider 的 

env_key
env_key
：

[model_providers.clickzetta] env_key = "CLICKZETTA_API_KEY"

这表示 Codex 从名为 

CLICKZETTA_API_KEY
CLICKZETTA_API_KEY
的环境变量读取 Token，而不是把 Token 明文写进 
config.toml
config.toml
。

3.3 在当前 Terminal 安全输入 API Key

zsh 中执行：

read -s "CLICKZETTA_API_KEY?请输入 API Key：" echo export CLICKZETTA_API_KEY

输入时屏幕不会显示字符，这是正常的。输入完成后按回车。

确认变量已经存在，但不要打印 Token：

if [ -n "${CLICKZETTA_API_KEY:-}" ]; then echo "API Key 已加载" else echo "API Key 未加载" fi

不要执行：

echo "$CLICKZETTA_API_KEY"

3.4 临时变量和长期保存的区别

使用 

read
read
和 
export
export
设置的变量只在当前 Terminal 有效。关闭 Terminal 后需要重新设置。

生产环境建议把 Token 放入：

  • macOS Keychain；
  • 企业密钥管理服务；
  • CI/CD Secret；
  • 权限受控的启动环境。

不要把真实 Token 直接提交到 

.zshrc
.zshrc
、
config.toml
config.toml
或 Git 仓库。

3.5 macOS Keychain 示例（可选）

把 Token 写入 Keychain。下面的 

-w
-w
位于命令最后，因此 Terminal 会提示输入，不需要把 Token 直接写在命令中：

security add-generic-password \ -U \ -a "$USER" \ -s "clickzetta-codex-api-key" \ -w

测试能否读取，但不要把结果打印到公开终端记录：

CLICKZETTA_API_KEY="$(security find-generic-password \ -a "$USER" \ -s "clickzetta-codex-api-key" \ -w)" export CLICKZETTA_API_KEY

需要每次打开 Terminal 自动加载时，可以把读取命令加入个人 shell 启动配置。企业环境应优先使用公司统一的密钥管理方案。

3.6 不要混用两套认证

本文推荐只使用：

env_key = "CLICKZETTA_API_KEY"

不要同时再配置：

requires_openai_auth = true experimental_bearer_token = "..."

requires_openai_auth = true
requires_openai_auth = true
更适合复用 Codex 已保存的 OpenAI 登录凭据。中转站使用独立 Token 时，
env_key
env_key
更清晰，也更容易排查。

4. 查询模型并判断协议

4.1 查询你的模型目录

模型目录用于确认 API Key 的权限范围和完整模型 ID。它不是协议能力证明，也不是 Codex 的固定模型清单。

确保当前 Terminal 已设置 

CLICKZETTA_API_KEY
CLICKZETTA_API_KEY
，然后执行：

export CLICKZETTA_BASE_URL="https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1" curl -sS -o /tmp/codex-models-openai.json \ --max-time 30 \ -w 'HTTP %{http_code}\n' \ "$CLICKZETTA_BASE_URL/models" \ -H "Authorization: Bearer $CLICKZETTA_API_KEY" jq -r ' if (.data | type) == "array" then .data[]?.id else .error.message // .message // "没有读取到模型目录" end ' /tmp/codex-models-openai.json

根据命令输出的 HTTP 状态决定下一步：

结果说明下一步
HTTP 200
HTTP 200
模型目录可访问从返回结果原样复制目标模型 ID，继续第 5 节
HTTP 000
HTTP 000
或 curl 报连接错误		网络、DNS、代理或 VPN 路径有问题回到第 1.5 节检查网络，不要先改模型 ID
HTTP 401
HTTP 401
/ 
403
403
API Key、鉴权头或权限有问题回到第 1.2、3.3 节检查 Token 和当前 Terminal
HTTP 404
HTTP 404
Base URL 或路径不正确检查 Base URL 是否多写或漏写 
/v1
/v1
HTTP 429
HTTP 429
当前 API Key 或上游被限流等待后重试，或联系 AI Gateway 支持团队确认额度
HTTP 5xx
HTTP 5xx
网关或上游暂时异常记录时间、模型和 request ID 后重试

如果你的中转站同时提供 Anthropic 兼容端点，再使用 Anthropic 鉴权头查询：

curl -sS -o /tmp/codex-models-anthropic.json \ --max-time 30 \ -w 'HTTP %{http_code}\n' \ "$CLICKZETTA_BASE_URL/models" \ -H "x-api-key: $CLICKZETTA_API_KEY" \ -H 'anthropic-version: 2023-06-01' jq -r ' if (.data | type) == "array" then .data[]?.id else .error.message // .message // "没有读取到 Anthropic 模型目录" end ' /tmp/codex-models-anthropic.json

配置模型时必须从返回结果中原样复制完整 ID。例如，

openai/...
openai/...
、
anthropic/...
anthropic/...
、
deepseek/...
deepseek/...
或 
qwen/...
qwen/...
都只是模型 ID 的命名方式，不是 Codex 的协议开关。

4.2 不同厂商模型的协议边界

厂商的原生 API 与 AI Gateway 暴露的兼容协议可能不同。同一个模型可能同时出现在多个协议目录，也可能只出现在其中一个目录。

判断时分成三层：

目录可见：API Key 能列出完整模型 ID 协议可用：指定端点返回 HTTP 200 和最终文字 Codex 可用：Responses 成功，并且 codex exec 能解析响应

例如，Claude 可以在 Anthropic Messages 中成功，但如果 

/responses
/responses
没有上游，仍然不能直接给 Codex 使用；DeepSeek 或 Qwen 也不能因为 Chat 成功就自动推断 Responses 成功。

工具调用、流式、图片、文件、搜索、结构化输出和长上下文属于更高一层的能力，需要在基础文本成功后单独验证。

4.3 选择模型的实际规则

如果目标是 Codex CLI，按以下规则选择：

1. 模型出现在自己的目录中； 2. 中转站为该模型提供 OpenAI Responses /responses 路由； 3. 用第 5 节的 Responses curl 得到 HTTP 200 和最终文本； 4. 再用第 8 节的 codex exec 验证； 5. 只有需要文件或工具时，再验证沙箱和工具调用。

模型只在 Chat Completions 成功，不能直接给 Codex；模型只在 Anthropic Messages 成功，也不能直接给 Codex。此时应使用支持对应协议的客户端，或者使用能把 Responses 转换为目标协议的代理层。

4.4 为什么不同协议会看到不同模型

中转站可能根据请求头和端点返回不同的模型视图：

Authorization: Bearer ... → OpenAI 兼容视图 x-api-key: ... anthropic-version: 2023-06-01 → Anthropic 兼容视图

因此，一个模型在 Anthropic 查询中可见，不代表它一定出现在 OpenAI Responses 查询中；反过来也一样。判断 Codex 能否使用时，只看 

/responses
/responses
的实际结果。

5. 先用标准 Responses curl 验证模型

5.1 为什么要先用 curl

curl 可以把问题拆成两层：

curl 失败 → Base URL、Token、模型、协议或上游路由问题 curl 成功但 Codex 失败 → Codex 配置、推理参数、流式响应、模型元数据或工具调用问题

不要跳过 curl 直接修改 Codex 配置，否则很难区分客户端问题和中转站问题。

5.2 最小 Responses 请求

执行：

export CLICKZETTA_MODEL="YOUR_MODEL_ID" curl -sS -o /tmp/codex-test-responses.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$CLICKZETTA_BASE_URL/responses" \ -H "Authorization: Bearer $CLICKZETTA_API_KEY" \ -H 'Content-Type: application/json' \ -d "$(jq -nc \ --arg model "$CLICKZETTA_MODEL" \ '{ model: $model, input: "请只回复：OK", max_output_tokens: 512, store: false }')"

随后执行：

jq . /tmp/codex-test-responses.json

正常结果应同时满足：

  • HTTP 200；
  • status
    status
    为完成状态；
  • output
    output
    中存在 
    output_text
    output_text
    ；
  • 最终文本是模型真实返回的内容。

5.3 只提取最终文本

执行：

jq -r ' ([.output[]?.content[]? | select(.type == "output_text" or .type == "text") | .text] | join("\n")) as $text | if ($text | length) > 0 then $text else .error.message // .message // "HTTP 已返回，但没有找到最终文字" end ' /tmp/codex-test-responses.json

正常返回：

OK

5.4 HTTP 200 仍然要检查最终文本

推理模型可能先产生 reasoning。如果输出预算太小，HTTP 可能是 200，但响应中没有最终文本。

验收时必须检查：

HTTP 状态 完成状态 最终 output_text

不能只检查 HTTP 200。

6. 把通过测试的模型写入 Codex CLI

6.1 Codex 配置文件位置

用户级配置文件：

~/.codex/config.toml

自定义 provider、认证来源和 Base URL 应写在用户级配置中。

项目目录也可以存在：

<项目目录>/.codex/config.toml

但官方明确限制：项目级配置不能覆盖 

model_provider
model_provider
、
model_providers
model_providers
等机器级 provider 配置。即使项目已被信任，也应把中转站 provider 写进 
~/.codex/config.toml
~/.codex/config.toml
。

6.2 修改前先备份

执行：

mkdir -p "$HOME/.codex" if [ -f "$HOME/.codex/config.toml" ]; then cp "$HOME/.codex/config.toml" \ "$HOME/.codex/config.toml.bak.$(date +%Y%m%d-%H%M%S)" fi

查看备份：

ls -lt "$HOME/.codex"/config.toml*

请记住最新备份文件的完整名称。如果后续配置无法加载，可以用该文件恢复。下面的 

备份文件完整路径
备份文件完整路径
必须替换为 
ls -lt
ls -lt
显示的实际文件：

cp "备份文件完整路径" "$HOME/.codex/config.toml" chmod 600 "$HOME/.codex/config.toml" codex --strict-config doctor \ --summary \ --no-color \ --ascii

恢复配置只恢复文件内容，不会恢复已经被 

unset
unset
、关闭 Terminal 或重启电脑清除的环境变量。恢复后仍需按第 3.3 节确认 
CLICKZETTA_API_KEY
CLICKZETTA_API_KEY
已加载。

6.3 新用户推荐配置

如果 

~/.codex/config.toml
~/.codex/config.toml
不存在或内容为空，执行：

nano "$HOME/.codex/config.toml"

粘贴以下内容：

model_provider = "clickzetta" model = "YOUR_MODEL_ID" model_reasoning_effort = "medium" model_verbosity = "low" model_reasoning_summary = "auto" approval_policy = "on-request" sandbox_mode = "workspace-write" [model_providers.clickzetta] name = "ClickZetta AI Gateway" base_url = "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1" env_key = "CLICKZETTA_API_KEY" wire_api = "responses" request_max_retries = 4 stream_max_retries = 5 stream_idle_timeout_ms = 300000

保存前必须把 

YOUR_MODEL_ID
YOUR_MODEL_ID
替换为第 4 节查询到的完整模型 ID。不要把 
clickzetta/
clickzetta/
这样的本地 provider 名称拼到模型 ID 前面。

上面的配置同时包含基础接入字段和一组保守的运行参数：

model_reasoning_effort = "medium"
model_reasoning_effort = "medium"
、
model_verbosity = "low"
model_verbosity = "low"
与 
model_reasoning_summary = "auto"
model_reasoning_summary = "auto"
。基础接入真正不能缺少的是 provider、模型 ID、Base URL、
env_key
env_key
和 
wire_api = "responses"
wire_api = "responses"
。如果第 5 节 curl 已成功，但某个模型拒绝 reasoning 或 verbosity 相关参数，可先临时删除 
model_reasoning_summary
model_reasoning_summary
与 
model_verbosity
model_verbosity
后重试；不要删除或改写 
wire_api
wire_api
。

在 nano 中：

  1. 按 Control + O 保存；
  2. 按回车确认文件名；
  3. 按 Control + X 退出。

配置文件保存后，至少应确认以下内容存在：

model_provider = "clickzetta" model = "你的完整模型 ID" wire_api = "responses" env_key = "CLICKZETTA_API_KEY"

其中模型 ID 必须与第 4 节查询结果完全一致。不要只检查文件是否保存成功，还要继续执行第 7 节和第 8 节的实际验证。

6.4 已有配置的用户不要整文件覆盖

如果已有插件、MCP、项目信任记录或其他设置，不要把整个文件替换成上面的推荐模板。

迁移时只需要：

  1. 在第一个 
    [表名]
    [表名]
    之前设置顶层 
    model_provider = "clickzetta"
    model_provider = "clickzetta"
    ；
  2. 在同一顶层区域设置 
    model = "YOUR_MODEL_ID"
    model = "YOUR_MODEL_ID"
    ；
  3. 新增或修改 
    [model_providers.clickzetta]
    [model_providers.clickzetta]
    ；
  4. 保留已有 
    [plugins]
    [plugins]
    、
    [mcp_servers]
    [mcp_servers]
    、
    [projects]
    [projects]
    和其他 provider 表；
  5. 保存后运行第 7 节和第 8 节的完整验证。

原有 provider 可以保留作为回退路径。例如，文件中可以同时存在：

model_provider = "clickzetta" model = "YOUR_MODEL_ID" [model_providers.custom] name = "Existing Provider" base_url = "https://existing-provider.example/v1" wire_api = "responses" [model_providers.clickzetta] name = "ClickZetta AI Gateway" base_url = "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1" env_key = "CLICKZETTA_API_KEY" wire_api = "responses"

上面的两个 provider 表可以共存，但当前实际使用哪一个，由文件顶层的 

model_provider
model_provider
决定。不要在 
[model_providers.clickzetta]
[model_providers.clickzetta]
中添加 
requires_openai_auth = true
requires_openai_auth = true
，也不要把真实 API Key 写进该表。

如果旧配置在 

[projects."..."]
[projects."..."]
下出现 
model_provider
model_provider
，不要把它当作全局设置。Codex 会忽略项目级配置对 provider 的覆盖；请把有效的 
model_provider
model_provider
放在用户级 
~/.codex/config.toml
~/.codex/config.toml
顶层。

6.5 TOML 最容易踩坑：顶层字段的位置

以下字段属于顶层：

model_provider = "clickzetta" model = "YOUR_MODEL_ID" model_reasoning_effort = "medium"

它们必须出现在第一个 

[表名]
[表名]
之前。

错误示例：

[projects."/Users/example/project"] trust_level = "trusted" model_provider = "clickzetta"

上面的 

model_provider
model_provider
会被 TOML 解析成 
projects."/Users/example/project"
projects."/Users/example/project"
表中的字段，而不是全局 provider 选择，因此可能完全不生效。

正确示例：

model_provider = "clickzetta" model = "YOUR_MODEL_ID" [projects."/Users/example/project"] trust_level = "trusted"

不要简单地把顶层配置追加到文件最后。

6.6 不要重复定义 provider 表

一个文件中不要出现两次：

[model_providers.clickzetta]

如果已经存在，直接修改原表。重复表会导致 TOML 解析失败。

6.7 provider ID 不能使用保留名称

官方内置并保留以下 provider ID：

openai ollama lmstudio

自定义中转站不要命名为这些值。本文使用：

clickzetta

6.8 为什么推荐 
model_reasoning_effort = "medium"
model_reasoning_effort = "medium"

不同上游对推理档位的支持不同。

对第三方模型而言，

high
high
或 
xhigh
xhigh
可能会触发上游不接受的 thinking budget 参数，例如：

The thinking_budget parameter must be a positive integer and not greater than 131072

因此，面向多个模型的通用默认值建议使用 

medium
medium
。确认具体模型支持后，再单独调高。

6.9 
model_verbosity
model_verbosity
可能被忽略

Codex 会为不在内置模型目录中的第三方模型使用 fallback metadata。

某些第三方模型可能出现类似警告：

model_verbosity is set but ignored as the model does not support verbosity

这不一定代表请求失败，只说明当前模型元数据没有声明 verbosity 能力。

自定义 provider 默认不声明 Responses WebSocket 和独立 Web Search 支持。

只有中转站确实实现对应接口时，才考虑配置：

supports_websockets = true supports_standalone_web_search = true

配置为 

true
true
只是在客户端声明能力，不会让中转站自动拥有该接口。模型、provider、网关和运行时必须同时支持。

7. 检查配置是否正确

7.1 Codex 没有 
config validate
config validate

Codex CLI 没有 OpenClaw 那样的：

codex config validate

不要照搬其他工具的命令。

Codex 推荐通过以下三层验证：

严格配置加载 → doctor 检查 → codex exec 实际请求

7.2 使用 strict config 和 doctor

执行：

codex --strict-config doctor \ --summary \ --no-color \ --ascii

重点查看：

Configuration [ok] config [ok] auth Connectivity [ok] reachability

doctor
doctor
还会检查 Terminal、历史会话、MCP、Git 和沙箱。即使最后显示某些 warn/fail，也不一定代表 AI Gateway 失败。

例如：

  • TERM=dumb
    TERM=dumb
    是当前终端能力问题；
  • 历史 thread 文件缺失是本地历史记录问题；
  • 某个 MCP 403 是 MCP 服务问题；
  • reachability
    reachability
    成功才说明 provider endpoint 可达。

doctor
doctor
的最终退出码可能因为历史 thread、Terminal、MCP 或插件问题而不是 0。判断中转站基础接入是否完成时，不要只看最后的计数或退出码，必须同时检查以下关键项：

检查项基础接入要求说明
Configuration / config
Configuration / config
ok
ok
config.toml
config.toml
可以严格加载
Configuration / auth
Configuration / auth
ok
ok
活跃 provider 可以取得认证信息
Connectivity / reachability
Connectivity / reachability
ok
ok
活跃 provider 的端点可达
第 8 节 
codex exec
codex exec
退出码 0 且有最终文本这是最终的模型调用验收

如果前三项正常，但 

doctor
doctor
因无关检查返回非零，继续执行第 8 节；只有 
codex exec
codex exec
也失败时，才按第 15 节进一步排查。

7.3 查看登录状态

这是可选检查。使用 

env_key
env_key
接入中转站时，即使没有官方 OpenAI/ChatGPT 登录状态，也不影响后续中转站请求。

执行：

codex login status

如果 provider 使用 

env_key
env_key
，还需要单独确认当前 Terminal 已加载：

if [ -n "${CLICKZETTA_API_KEY:-}" ]; then echo "CLICKZETTA_API_KEY 已加载" else echo "CLICKZETTA_API_KEY 未加载" fi

codex login status
codex login status
只说明 Codex 保存的官方登录或 API Key 状态，不会代替自定义 
env_key
env_key
检查。已经使用过官方 Codex 的电脑，可能仍显示原有 OpenAI/ChatGPT 登录状态；这不代表当前中转站请求会走官方接口，也不代表中转站配置失败。

对 AI Gateway 用户，按以下顺序验收认证和实际路由：

CLICKZETTA_API_KEY 已加载 → 顶层 model_provider = "clickzetta" → doctor 的 auth 和 reachability 正常 → codex exec 输出 provider: clickzetta

环境变量只对当前 Terminal 及其启动的子进程生效。换一个 Terminal、关闭窗口或重启电脑后，需要重新加载 API Key，除非已经按第 3.4 或 3.5 节配置了持久化加载方式。

7.4 查看当前 CLI 参数

执行：

codex --help codex exec --help

不同版本的参数位置可能不同。遇到 

unexpected argument
unexpected argument
时，以当前版本帮助为准。

8. 用 Codex CLI 发送第一条消息

8.1 最小非交互测试

在任意目录测试时，可以执行：

codex --ask-for-approval never exec \ --ephemeral \ --skip-git-repo-check \ --sandbox read-only \ --model YOUR_MODEL_ID \ -c 'model_reasoning_effort="medium"' \ -c 'model_verbosity="low"' \ '不要调用任何工具，只回复：Codex 正常'

正常最终文本：

Codex 正常

当前版本通常还会在运行信息中显示实际模型和 provider。请确认类似：

model: YOUR_MODEL_ID provider: clickzetta approval: never sandbox: read-only

成功标准不是进程启动，而是：

  • Codex 实际发出 Responses 请求；
  • 运行信息中的 
    provider
    provider
    是 
    clickzetta
    clickzetta
    ；
  • 运行信息中的 
    model
    model
    与本次指定的完整模型 ID 一致；
  • 最终退出码为 0；
  • 输出中有模型最终文本；
  • 没有在重试结束后返回 400/502。

8.2 参数位置限制

当前版本中，审批参数应放在 

exec
exec
之前：

正确：

codex --ask-for-approval never exec ...

错误：

codex exec --ask-for-approval never ...

错误写法可能返回：

unexpected argument '--ask-for-approval' found

8.3 为什么使用这些测试参数

参数用途
--ephemeral
--ephemeral
不持久化本次测试会话
--skip-git-repo-check
--skip-git-repo-check
允许在非 Git 目录测试
--sandbox read-only
--sandbox read-only
测试时禁止模型修改文件
--ask-for-approval never
--ask-for-approval never
最小文本测试不弹审批请求
--model
--model
临时指定模型，不必修改默认配置
-c
-c
只覆盖本次运行的配置

这些参数适合“只回复一段文字”的连通性测试，不代表日常开发应该永远关闭审批。

8.4 交互模式

进入项目目录：

cd /你的项目目录 codex

交互界面中常用命令：

/status 查看当前模型、目录和权限 /model 选择模型和推理档位 /permissions 查看或调整权限 /review 进行代码审查 /init 创建 AGENTS.md 项目说明

8.5 临时切换模型

不修改配置文件：

codex --model YOUR_MODEL_ID

非交互：

codex exec \ --model YOUR_MODEL_ID \ --skip-git-repo-check \ '请只回复：OK'

8.6 临时调整推理档位

codex exec \ --model YOUR_MODEL_ID \ --skip-git-repo-check \ -c 'model_reasoning_effort="medium"' \ '请只回复：OK'

9. 理解验证结果和能力范围

9.1 为什么要分协议验证

模型目录只回答“这个 API Key 能看到哪些模型”，不能回答“这个模型能否通过 Codex 使用”。要判断是否能在 Codex CLI 中使用，必须验证同一条协议链路：

模型目录 → OpenAI Responses /responses → Codex exec → 需要时再验证工具、流式和文件权限

Codex 使用的是 OpenAI Responses。即使同一个模型在 OpenAI Chat Completions 或 Anthropic Messages 中可以回复，也不能跳过 Responses 验证。

9.2 推荐验证顺序

验证层建议使用的状态名称通过标准可以说明什么
权限模型目录可见
/models
/models
返回目标模型		当前 API Key 可以看到该模型
协议Responses 路由可用
/responses
/responses
返回 HTTP 200		网关存在对应 Responses 路由
内容Responses 文本可用有完成状态和最终文本该模型可以完成基础 Responses 文本请求
Codex CLICodex 基础可用
codex exec
codex exec
退出码为 0，且 provider/model 正确		可以用于当前 Codex 基础文本和编码任务
能力Codex 工作流已验证文件、工具、流式等实际功能逐项通过可以用于已经验收的具体工作流

只有前四层都通过，才可以把该模型用于 Codex 的基本文本任务。第五层需要根据你的实际场景单独确认。

对外说明模型状态时，建议使用上表中的状态名称。不要把“模型目录可见”写成“Codex 已支持”，也不要把一次文本成功写成“所有高级能力均支持”。

9.3 如何阅读验证结果

结果对你的含义下一步
Responses 和 Codex 都成功可以进行基本文本和编码任务按第 13 节确认沙箱，再开始修改文件
Chat 或 Messages 成功，Responses 失败该模型属于其他协议可用范围使用对应协议的客户端，或增加转换层
Responses 返回 400 / 
No upstream candidates
No upstream candidates
网关没有为该模型配置 Responses 上游，或权限不足核对模型 ID、权限和路由，不要反复修改 Codex 参数
Responses 返回 502上游调用或网关路由发生故障保留时间、模型、协议和 request ID 后联系 AI Gateway 支持团队
HTTP 200 但没有最终文本输出预算或响应转换不完整增大输出预算并检查 
status
status
、
output
output
和 
incomplete_details
incomplete_details
Codex 能启动但请求失败本机配置、参数或流式解析可能有问题先对比第 5 节 curl，再检查第 6、7、12 节

9.4 各厂商模型在 Codex 中的判断方式

下表是配置规则，不是模型目录。模型名称可能变化，但协议判断方式不变：

厂商或模型类型通常可用的协议给 Codex 配置时的判断
OpenAI 模型OpenAI Chat 或 Responses，具体取决于网关只有 Responses 路由实际成功，才可直接配置
Anthropic ClaudeAnthropic MessagesCodex 不会自动发送 Messages；必须有 Responses 兼容层
DeepSeek常见为 OpenAI Chat，部分网关也提供 Anthropic 或 Responses不要从名称推断；必须实际验证 Responses
Qwen由网关决定，可出现 Chat、Responses 或 Anthropic 兼容路由先验证 Responses，再根据模型支持情况选择 reasoning effort
其他厂商或自定义别名由网关和上游适配决定只依据网关目录、接口文档和实际请求结果

同一厂商的不同模型可能走不同上游，不能把一个模型的成功结果套用到同厂商的其他模型。

9.5 基本文本支持和高级能力是两件事

Responses 文本调用成功，只说明 Codex 能完成基础对话。以下能力需要单独验证：

  • 流式输出和断线重连；
  • 工具调用和工具结果回传；
  • 图片、文件或其他多模态输入；
  • Web Search、MCP 和外部连接器；
  • JSON Schema 或结构化输出；
  • 长上下文、压缩和多轮会话；
  • 推理预算、verbosity 和上下文窗口。

本指南所说的“可用于 Codex”，是指 Responses 文本调用与 Codex 基本任务已经通过，不自动包含上述高级能力。

9.6 curl 成功但 Codex 失败时

按以下顺序排查：

  1. 确认 
    codex --version
    codex --version
    和 
    type -a codex
    type -a codex
    ；
  2. 确认 
    model_provider
    model_provider
    在用户级 
    ~/.codex/config.toml
    ~/.codex/config.toml
    ；
  3. 确认 provider 的 
    wire_api
    wire_api
    为 
    responses
    responses
    ；
  4. 确认模型 ID 与 curl 完全一致；
  5. 将 reasoning effort 暂时降到 
    medium
    medium
    ；
  6. 用第 8 节的只读 
    codex exec
    codex exec
    重试；
  7. 如果仍失败，保留脱敏错误和 request ID，联系中转站确认路由。

10. 请求协议边界

10.1 自定义 provider 只使用 Responses

官方配置参考规定，自定义 provider 的 

model_providers.<id>.wire_api
model_providers.<id>.wire_api
只有一个有效值：

responses

因此以下写法不受支持：

wire_api = "chat_completions" wire_api = "openai-completions" wire_api = "anthropic-messages" wire_api = "messages"

这不是更换字段名称的问题，而是 Codex 当前自定义 provider 没有这些协议选项。

10.2 三种协议不能混用

项目OpenAI Chat CompletionsOpenAI ResponsesAnthropic Messages
路径
/chat/completions
/chat/completions
/responses
/responses
/messages
/messages
主要输入
messages
messages
input
input
messages
messages
+ 顶层 
system
system
输出预算
max_tokens
max_tokens
max_output_tokens
max_output_tokens
max_tokens
max_tokens
工具结果
tool_calls
tool_calls
Responses function/tool items
tool_use
tool_use
/ 
tool_result
tool_result
流式事件Chat SSEResponses SSEAnthropic SSE
Codex 自定义 provider不支持支持不支持

只修改 URL 或模型名称，不能让客户端自动切换协议。

10.3 模型前缀不是协议开关

例如：

anthropic/claude-opus-5

anthropic/
anthropic/
只是模型 ID 的一部分。把它交给 Codex 后，Codex 仍发送：

POST /responses

不会自动发送：

POST /messages

10.4 Chat 成功不代表 Codex 成功

如果某个 DeepSeek 或其他厂商模型出现以下情况：

OpenAI Chat Completions：成功 Anthropic Messages：成功 OpenAI Responses：无上游候选 Codex：失败

这不是 Codex 不认识 DeepSeek 名称，而是 Codex 所需的 Responses 路由不存在。

10.5 Anthropic 成功不代表 Codex 成功

如果 Claude 或其他 Anthropic 模型出现以下情况：

anthropic/claude-opus-5 POST /messages → HTTP 200，返回 OK POST /responses → HTTP 400，No upstream candidates

这说明模型和 API Key 可能可以通过 Anthropic 客户端使用，但不能通过该 Responses 路由直接给 Codex 使用。

10.6 目录视图不是协议能力证明

必须分别记录：

目录是否可见 Responses curl 是否成功 Codex 是否成功 工具调用是否成功

不能只保存一个“模型总列表”。

11. Claude、Anthropic 和 CC Switch

11.1 Claude 为什么不能直接配置

以下命令语法上可以执行：

codex exec \ --model anthropic/claude-opus-5 \ --skip-git-repo-check \ '请只回复：OK'

但 Codex 仍发送 Responses。如果网关只为该模型配置了 Anthropic Messages 上游，常见返回：

GATEWAY_NO_UPSTREAM_CANDIDATES path=/v1/responses protocol=open_ai

11.2 有两种解决方向

方向一：中转站提供 Responses 兼容层。

Codex Responses → 中转站协议转换 → Anthropic Messages → Claude

方向二：本地使用 CC Switch 等协议转换工具。

Codex Responses → 本地 CC Switch → Anthropic Messages → AI Gateway → Claude

11.3 使用转换层时 Codex 仍然配置 Responses

即使经过 CC Switch，Codex 侧仍应保持：

wire_api = "responses"

变化的是 

base_url
base_url
指向本地代理，例如：

<http://127.0.0.1:15721/v1>

本地代理负责把 Responses 转为 Anthropic Messages，再把 Anthropic 响应转换回 Codex 能理解的 Responses。

11.4 CC Switch 不等于模型自动可用

协议转换层不能解决：

  • Token 没有权限；
  • 模型 ID 不存在；
  • Anthropic 上游返回 5xx；
  • 模型被限流；
  • 上游上下文或思考预算超限；
  • 工具调用无法正确映射；
  • 图片、文件、缓存、搜索等能力不兼容。

11.5 转换后的高级能力必须逐项验收

文本返回成功后，还要分别验证：

  • Responses SSE 与 Anthropic SSE 的流式转换；
  • function call 与 
    tool_use/tool_result
    tool_use/tool_result
    的映射；
  • system 消息和多轮上下文；
  • reasoning/thinking 内容；
  • 图片和文件输入；
  • Web Search；
  • Prompt Cache；
  • 中断、重试和错误码转换。

只有在转换层完成相同场景的验证后，才能判断 Claude 是否适用于对应的 Codex 工作流。

11.6 CC Switch 可能改写 Codex 配置

使用“接管 Codex”前先备份：

cp "$HOME/.codex/config.toml" \ "$HOME/.codex/config.toml.before-cc-switch.$(date +%Y%m%d-%H%M%S)"

接管后重新检查：

rg -n '(model|model_provider|base_url|wire_api|env_key)' \ "$HOME/.codex/config.toml"

重点确认 Base URL 是否已经指向本机代理、代理是否正在运行，以及停止代理后是否需要恢复原配置。

12. 推理档位、模型元数据和输出限制

12.1 
model_reasoning_effort
model_reasoning_effort
的可选值

Codex 当前配置参考列出：

minimal low medium high xhigh

但 

xhigh
xhigh
是否可用取决于模型。配置字段允许，不代表上游模型一定接受。

12.2 第三方模型的推理参数

不同厂商和不同模型对 reasoning effort 的映射可能不同。某些模型在 

high
high
或 
xhigh
xhigh
下会拒绝 thinking budget，或者只返回 reasoning 而没有最终文本。

建议先使用 

medium
medium
完成文本验证，再根据该模型的接口说明逐步提高档位。出现 
thinking_budget
thinking_budget
、输出不完整或没有最终文本时，先降低档位并增大输出预算。

12.3 未知模型元数据警告

第三方模型可能出现：

Unknown model ... is used. This will use fallback model metadata.

含义是 Codex 内置目录中没有该模型的完整能力描述，因此会使用回退值。

可能影响：

  • 上下文窗口估算；
  • reasoning 支持判断；
  • verbosity 支持判断；
  • 工具和多模态能力声明；
  • token 截断和压缩策略。

这条警告本身不等于调用失败，但不能忽略长期影响。

12.4 不要随意猜上下文窗口

Codex 支持手动配置类似：

model_context_window = 128000

只有从中转站或上游获得准确数值后才应设置。写得比真实值大，可能导致上游拒绝；写得太小，会导致 Codex 过早压缩上下文。

12.5 HTTP 200 但没有最终文本

Responses 中可能先出现 reasoning item。输出预算不足时，可能没有 

output_text
output_text
。

排查：

  1. 增大 
    max_output_tokens
    max_output_tokens
    ；
  2. 检查 
    status
    status
    和 
    incomplete_details
    incomplete_details
    ；
  3. 检查是否只有 reasoning；
  4. 使用 Codex 实际请求再次验证；
  5. 不要只看 HTTP 状态码。

12.6 不能从文本成功推断的能力

以下能力不能由一次文本调用直接推断：

  • 长上下文稳定性；
  • 图片输入；
  • Web Search；
  • MCP 工具；
  • 多轮 function call；
  • JSON Schema 输出；
  • Prompt Cache；
  • Responses WebSocket；
  • 极长任务中的断线恢复。

使用这些能力前，应按第 9.5 节逐项验证，不要把一次文本成功理解为所有功能都兼容。

13. 沙箱和审批限制

13.1 模型连通与文件权限是两件事

AI Gateway 负责模型请求；Codex 沙箱负责模型生成的本地命令和文件操作。

出现“模型能回复但不能改文件”时，应检查 sandbox，而不是先怀疑 API Key。

13.2 三种沙箱模式

模式主要行为建议用途
read-only
read-only
只读文件，不能正常修改项目连通性测试、审查
workspace-write
workspace-write
可以写工作区，部分敏感路径仍受保护日常开发推荐
danger-full-access
danger-full-access
文件系统基本不受 Codex 沙箱限制只用于已有外部隔离的环境

推荐默认：

sandbox_mode = "workspace-write" approval_policy = "on-request"

13.3 审批策略

策略含义
untrusted
untrusted
只有受信命令直接运行，其余需要审批
on-request
on-request
Codex 根据操作风险请求审批
never
never
不请求审批，失败直接返回模型

approval_policy
approval_policy
决定什么时候询问，
sandbox_mode
sandbox_mode
决定命令能访问什么。两者互相独立。

13.4 
danger-full-access
danger-full-access
的风险

不要把以下配置作为默认配置：

sandbox_mode = "danger-full-access" approval_policy = "never"

这种组合允许模型在没有人工审批的情况下执行广泛的本地操作。

也不要在普通电脑上随意使用：

--dangerously-bypass-approvals-and-sandbox

13.5 workspace-write 的网络限制

Codex 自己访问模型 provider，与模型生成的 shell 命令访问外网不是完全同一层。

workspace-write
workspace-write
中，shell 工具的网络默认可能被限制。需要允许工具命令访问外网时，可以在确认风险后配置：

[sandbox_workspace_write] network_access = true

不要为了让模型 API 连通而盲目打开工具网络；先看 

codex doctor
codex doctor
的 provider reachability。

13.6 保护 API Key 不进入子进程

Codex provider 需要从父进程读取 

CLICKZETTA_API_KEY
CLICKZETTA_API_KEY
，但模型生成的 shell 命令通常不需要看到该变量。

可以评估使用 shell 环境过滤：

[shell_environment_policy] inherit = "core" ignore_default_excludes = false [shell_environment_policy.filters] "CLICKZETTA_API_KEY" = "exclude"

修改后必须重新运行 

codex doctor
codex doctor
和实际模型请求，确认 provider 认证仍正常。

14. 使用 Profile 管理多套配置

14.1 为什么使用 Profile

当你同时使用官方 OpenAI、中转站和本地模型时，不建议频繁覆盖同一个 

config.toml
config.toml
。

可以把公共 provider 放在：

~/.codex/config.toml

再创建：

~/.codex/clickzetta.config.toml

14.2 Profile 示例

~/.codex/config.toml
~/.codex/config.toml
中保留 provider：

[model_providers.clickzetta] name = "ClickZetta AI Gateway" base_url = "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1" env_key = "CLICKZETTA_API_KEY" wire_api = "responses"

~/.codex/clickzetta.config.toml
~/.codex/clickzetta.config.toml
中写选择项：

model_provider = "clickzetta" model = "YOUR_MODEL_ID" model_reasoning_effort = "medium" model_verbosity = "low"

启动交互模式：

codex --profile clickzetta

非交互模式：

codex exec --profile clickzetta \ --skip-git-repo-check \ '请只回复：OK'

14.3 Profile 仍不能切换 wire protocol

Profile 可以切换 provider、模型和推理档位，但 Codex 自定义 provider 的 wire protocol 仍然只能是 Responses。

Profile 不是 Anthropic 协议开关。

15. 常见问题排查

15.1 
codex: command not found
codex: command not found

执行：

type -a codex echo "$PATH"

如果刚安装，关闭并重新打开 Terminal。仍找不到时，重新执行官方安装步骤，并查看安装器提示的 PATH 路径。

15.2 两个 Terminal 的版本不同

执行：

type -a codex codex --version

Terminal 使用 PATH 中排在最前面的版本。桌面应用内置 CLI 与独立 CLI 可能不是同一个版本。

15.3 
unexpected argument
unexpected argument

先执行：

codex --help codex exec --help

当前版本中，

--ask-for-approval
--ask-for-approval
放在 
exec
exec
前：

codex --ask-for-approval never exec ...

15.4 配置字段不生效

重点检查：

  1. 顶层字段是否写在第一个 
    [表名]
    [表名]
    前；
  2. 是否误写到 
    [projects."..."]
    [projects."..."]
    表中；
  3. 是否在项目 
    .codex/config.toml
    .codex/config.toml
    中设置 provider；
  4. 是否重复定义 provider 表；
  5. 是否启动了另一份 Codex CLI；
  6. 是否被 
    --profile
    --profile
    或 
    -c
    -c
    临时覆盖。

执行：

codex --strict-config doctor --summary --no-color --ascii

15.5 API Key 环境变量不存在

执行：

if [ -n "${CLICKZETTA_API_KEY:-}" ]; then echo "已加载" else echo "未加载" fi

如果未加载，重新执行第 3.3 节。不要把真实 Token 打印出来。

15.6 HTTP 401/403

可能原因：

  • Token 错误或过期；
  • Authorization: Bearer
    Authorization: Bearer
    头缺失；
  • Token 没有模型权限；
  • 请求到了错误环境；
  • Base URL 对应另一套网关。

先用第 4 节 

/models
/models
请求验证鉴权。

15.7 
No upstream candidates
No upstream candidates

常见原因：

  • 目标模型没有 Responses 上游；
  • 模型 ID 写错；
  • API Key/租户没有该路由；
  • 把仅支持 Chat 或 Anthropic 的模型交给 Codex；
  • 上游已下线。

如果某个 DeepSeek、Claude 或其他厂商模型只在 Chat 或 Anthropic 路由成功，这属于协议路由不匹配，不是重装 Codex 可以解决。

15.8 HTTP 502 
[G2] Upstream failed
[G2] Upstream failed

网关已经识别模型，但上游请求失败。

处理方式：

  1. 保留模型 ID、协议、时间和 request ID；
  2. 等待后重试；
  3. 用裸 
    /responses
    /responses
    curl 对比；
  4. 查看 Codex 是否自动重试后成功；
  5. 持续失败时联系 AI Gateway 支持团队。

如果同一模型持续返回 502，应先按上游故障处理；不要仅凭一次重试成功就把它当作稳定可用。

15.9 
stream disconnected
stream disconnected
/ 
Reconnecting
Reconnecting

Codex Responses 默认使用流式传输时，网络或上游可能中途断开。Codex 会根据 

stream_max_retries
stream_max_retries
自动重试。

判断成功与否应看：

最终是否完成 最终退出码是否为 0 是否得到最终文本

一次 

Reconnecting
Reconnecting
后成功，可以记录为“成功但发生重试”；持续重试失败则不能视为可用。

15.10 
thinking_budget
thinking_budget
参数错误

把推理档位降到 

medium
medium
或更低：

codex exec \ --model YOUR_MODEL_ID \ --skip-git-repo-check \ -c 'model_reasoning_effort="medium"' \ '请只回复：OK'

15.11 
Unknown model ... fallback metadata
Unknown model ... fallback metadata

这表示 Codex 没有该第三方模型的内置元数据。

如果请求仍返回成功，可以继续进行基础文本测试，但要单独验证上下文、reasoning、工具和多模态能力。

15.12 
model_verbosity is set but ignored
model_verbosity is set but ignored

当前模型不支持或没有声明 verbosity 能力。

可以：

  • 忽略警告继续测试；
  • 临时删除 
    model_verbosity
    model_verbosity
    ；
  • 为不同模型建立 Profile。

15.13 MCP 403 或插件警告

MCP、插件目录和模型 provider 是不同链路。

如果模型已经返回 OK，但随后出现 MCP shutdown、插件清单或 ChatGPT 远程目录警告，先不要把它误判成模型失败。

排查时分别记录：

模型请求结果 MCP 启动结果 插件加载结果

还可能看到以下不直接等于模型失败的提示：

remote plugin bundle sync failed OutputTextDelta without active item

remote plugin bundle sync failed
remote plugin bundle sync failed
常见于本机存在需要官方 ChatGPT 登录的远程插件同步，而当前会话使用的是 Gateway API Key。
OutputTextDelta without active item
OutputTextDelta without active item
可能来自流式事件转换或解析。如果最终仍显示正确的 
provider
provider
、模型和最终文本，并且退出码为 0，应记录该警告并观察；如果持续出现丢字、无最终文本或非零退出码，再按流式兼容问题提交脱敏日志。

15.14 非 Git 目录无法执行

最小测试加入：

--skip-git-repo-check

正式项目建议在 Git 仓库中运行，方便审查和恢复模型修改。

15.15 
doctor
doctor
最后显示 fail

不要只看最后的计数。展开查看具体分组：

codex doctor --all --no-color --ascii

只要 

Configuration
Configuration
、
auth
auth
和 provider 
Connectivity
Connectivity
正常，Terminal、历史 thread、MCP 或插件警告不一定阻塞模型请求。

不要在脚本中仅用 

doctor
doctor
的退出码判断 Gateway 是否配置成功。最终还应执行第 8 节的只读 
codex exec
codex exec
：只有当 provider/model 正确、得到最终文本且退出码为 0，才能确认基础模型链路成功。

15.16 修改配置后需要恢复

先查看可用备份：

ls -lt "$HOME/.codex"/config.toml*

选择修改前生成的备份，并替换下面的占位文本：

cp "备份文件完整路径" "$HOME/.codex/config.toml" chmod 600 "$HOME/.codex/config.toml"

然后重新加载 API Key，并再次执行：

codex --strict-config doctor \ --summary \ --no-color \ --ascii

恢复时不要删除整个 

~/.codex
~/.codex
目录，否则可能同时丢失登录状态、历史会话、插件、MCP 和项目配置。

16. API Key 和配置安全

16.1 需要保护的文件

常见敏感文件：

~/.codex/auth.json ~/.codex/config.toml ~/.zshrc CI/CD secret 配置

即使 

config.toml
config.toml
没有明文 Token，它也会暴露 Base URL、provider、MCP 和本机目录信息。

16.2 限制文件权限

执行：

chmod 600 "$HOME/.codex/config.toml" if [ -f "$HOME/.codex/auth.json" ]; then chmod 600 "$HOME/.codex/auth.json" fi

16.3 不要做这些操作

  • 不要上传完整 
    ~/.codex
    ~/.codex
    目录；
  • 不要把 
    auth.json
    auth.json
    发给客服；
  • 不要在公开录屏中执行 
    echo "$CLICKZETTA_API_KEY"
    echo "$CLICKZETTA_API_KEY"
    ；
  • 不要把真实 Token 写进文档示例；
  • 不要把 API Key 提交到 Git；
  • 不要让多人共用同一个 Token；
  • Token 泄露后不要只删除截图，应立即撤销并重建。

16.4 测试结束后清理临时变量

如果本次只做临时测试：

unset CLICKZETTA_API_KEY unset CLICKZETTA_BASE_URL unset CLICKZETTA_MODEL

清理后，新的 Codex 进程将无法通过 

env_key
env_key
获取 Token，直到重新设置环境变量。

16.5 对外发送错误信息前脱敏

可以发送：

  • 时间；
  • 模型 ID；
  • HTTP 状态；
  • request ID；
  • 协议路径；
  • 已脱敏错误 JSON。

必须删除：

  • API Key；
  • Authorization 头；
  • x-api-key
    x-api-key
    ；
  • 本机私密文件内容；
  • 不应公开的租户和个人信息。

17. 联系 AI Gateway 支持团队

17.1 联系前先完成这三项自查

不要只发送一张 Codex 报错截图。先完成以下检查，能显著缩短定位时间：

  1. 使用第 4 节确认 Base URL、API Key 和完整模型 ID；
  2. 使用第 5 节的标准 
    /responses
    /responses
    curl 复现问题；
  3. 使用第 8 节的只读 
    codex exec
    codex exec
    对比 curl 和 Codex 的结果。

若目标是 Claude 或其他只提供 Anthropic Messages 的模型，还应先阅读第 11 节，确认是否已有可用的 Responses 兼容层。Codex 仍然只能向该兼容层发送 

/responses
/responses
请求。

17.2 提交问题时需要提供什么

请提供以下脱敏信息：

操作系统和 Codex CLI 版本 请求协议和路径 完整模型 ID（不包含 Token） 错误时间和时区 HTTP 状态码 request ID（如果有） 是否能用同一 API Key 访问 /models 是否能用同一模型完成第 5 节 Responses curl

不要提供：

API Key Authorization 头 x-api-key auth.json 完整配置文件 本机项目源码或私密文件

17.3 支持团队可以协助确认什么

AI Gateway 支持团队可以协助确认：

  • API Key 是否有目标模型和协议权限；
  • 指定端点是否存在对应上游路由；
  • 模型 ID 是否需要完整前缀；
  • 网关是否返回 400、401、403、429 或 5xx；
  • 是否存在已知的参数和推理预算限制。

Codex CLI 的版本行为、本机网络、沙箱策略、第三方转换层以及模型高级能力，需要在你的实际环境中分别验证。

18. 完成检查清单

18.1 配置完成后可以实际使用什么

当第 18.2 节全部勾选后，你可以在自己的项目目录中使用：

codex

进入交互式编码会话，也可以使用：

codex exec \ --model YOUR_MODEL_ID \ '请检查当前项目并告诉我下一步建议'

执行非交互任务。

在不超过当前沙箱和审批范围的前提下，Codex 可以：

  • 读取项目文件并理解代码结构；
  • 根据用户指令生成修改；
  • 在允许的工作区中写入文件；
  • 运行被允许的本地命令；
  • 输出修改结果、测试结果和错误信息；
  • 使用 
    --model
    --model
    或 
    /model
    /model
    切换到其他已支持模型。

配置成功不代表所有模型和高级能力自动可用。是否能够使用 Claude、DeepSeek 或其他厂商模型，取决于它们是否有 Responses 路由；Web Search、MCP、工具调用、图片、文件、缓存和长上下文也需要按实际场景单独验证。

18.2 最终成功清单

确认 Codex CLI 接入完成前逐项检查：

[ ] curl 和 jq 可以执行 [ ] command -v codex 返回路径 [ ] codex --version 返回版本 [ ] type -a codex 已确认没有版本混淆 [ ] Base URL 正确，/v1 没有重复 [ ] API Key 已安全加载且未公开 [ ] provider 使用 env_key，不含明文 Token [ ] /models 查询成功 [ ] 模型 ID 从目录原样复制 [ ] 标准 /responses curl 返回 HTTP 200 [ ] Responses 中存在最终 output_text [ ] model_provider 顶层字段位置正确 [ ] [model_providers.clickzetta] 没有重复定义 [ ] wire_api = "responses" [ ] codex --strict-config doctor 能加载配置 [ ] doctor 的 config 和 auth 正常 [ ] doctor 的 provider reachability 正常 [ ] 没有仅凭 doctor 的最终计数或退出码判断失败 [ ] codex exec 返回最终文本 [ ] codex exec 显示 provider: clickzetta [ ] codex exec 显示预期的完整模型 ID [ ] Codex 进程最终退出码为 0 [ ] 推理档位已按模型验证 [ ] 流式重试结果已记录 [ ] 沙箱和审批策略符合实际使用环境 [ ] 工具调用需要使用时已单独验证 [ ] 如果选择 Anthropic 模型，已确认存在 Responses 兼容层 [ ] 错误日志已经脱敏 [ ] 已记录本次验证时间和 Codex CLI 版本

全部勾选后，即可确认 Codex CLI 已完成基础文本接入。文件修改、工具调用和其他高级能力仍按实际需求单独验收。

如果只有 

/models
/models
成功，不能视为模型可用；如果 curl 成功但 Codex 失败，应重点检查配置位置、推理档位、流式响应、模型元数据和 provider 实际路径。

19. 相关资料

需要查阅配置细节时，请以以下官方 OpenAI 文档为准：

官方文档确认的关键限制：

  1. 用户级配置位于 
    ~/.codex/config.toml
    ~/.codex/config.toml
    ；
  2. 自定义 provider 可以设置 Base URL、认证来源和额外请求头；
  3. 自定义 provider 的 
    wire_api
    wire_api
    当前仅支持 
    responses
    responses
    ；
  4. 项目级配置不能覆盖机器级 provider 和认证设置；
  5. reasoning effort 是否可用取决于模型；
  6. 自定义 provider 的 Web Search 和 WebSocket 能力默认不启用；
  7. API Key 登录与 ChatGPT 登录的功能范围不同。

本文中的模型名称仅用于说明模型 ID 和协议判断方法。实际配置应以你的 API Key、AI Gateway 提供的模型目录、目标端点和 Codex CLI 版本为准。

Openclaw配置指南
Trae配置指南
Yunqi © 2024 Yunqi, Inc. All Rights Reserved.
联系我们
预约咨询
微信咨询
电话咨询
邮件咨询