Codex CLI 集成

在 ~/.codex/config.toml 里加一个自定义 model_provider,让 OpenAI Codex CLI 走本平台的 /v1/responses

Codex CLI 是 OpenAI 的命令行编程助手,通过 Responses API 调模型。本页按 Codex CLI 0.169.0(2026-11-13 发布)与官方配置参考核对。

准备 API Key#

在 qd.zsopc.com/dashboard/keys 创建 API Key,导出成环境变量(建议写进 ~/.zshrc / ~/.bashrc):

export PLATFORM_API_KEY="sk-gpushare-xxx"

配置#

编辑 ~/.codex/config.toml(设了 CODEX_HOME 时在 $CODEX_HOME/config.toml):

model_provider = "xiaozhan"
model = "gpt-6.1-sol"

[model_providers.xiaozhan]
name = "小战AIhub"
base_url = "https://qd.zsopc.com/v1"   # Codex 自己补 /responses
env_key = "PLATFORM_API_KEY"            # 从这个环境变量读 Key
wire_api = "responses"

然后直接运行 codex。不需要 codex login:自定义 provider 用 env_key 指定的环境变量作为 Key。

要点:

  • base_url 要带 /v1:Codex 把它与 /responses 拼起来,最终请求 https://qd.zsopc.com/v1/responses。
  • wire_api 只能写 responses:这是现在唯一支持的值,也是默认值;旧版本的 "chat" 已移除,写了会报错。
  • provider 配置只能放用户级 ~/.codex/config.toml:项目目录里的 .codex/config.toml 会忽略 model_provider 与 model_providers。
  • provider id 不能用 openai、ollama、lmstudio 等内置保留名。

选模型#

Codex 只走 /v1/responses,所以 model 要选支持 OpenAI Responses 协议的模型。Codex 的提示词按 GPT 模型调过,推荐:

用途模型
默认 / 复杂任务gpt-6.1-sol、gpt-5.6-sol
日常、省钱gpt-6-luna、gpt-6.1-terra

claude-opus-4-8、claude-sonnet-4-6 等少数非 GPT 模型也有 Responses 通道,支持情况见 兼容矩阵 的 OpenAI Responses 一列;没有通道的模型会返回 503 no_channel_available。

Codex 内置目录里没有的模型 ID 会按通用参数运行(启动时可能提示)。需要时可在顶层加 model_context_window = <窗口大小> 或 model_reasoning_effort = "high"。

可选:WebSocket 传输#

本平台在同一路径(GET /v1/responses)上提供 Responses API 的 WebSocket 传输。在 provider 里加一行:

supports_websockets = true

Codex 就会改用 WebSocket,长会话每轮只上传新增的内容,不再重发全部历史。

多套配置(profile)#

Codex 0.134.0 起,profile 是单独的文件:把上面的顶层键写进 ~/.codex/<名字>.config.toml,用 codex --profile <名字> 加载,它叠加在 config.toml 之上。

Codex 也能接 MCP 服务器,本平台的出图、视频、音乐工具见 MCP 媒体工具。

常见问题#

现象排查
401 invalid_api_key启动 codex 的终端里 echo $PLATFORM_API_KEY 是否有值;Key 是否复制完整(共 76 字符)
404base_url 是否以 /v1 结尾
配置不生效provider 写在了项目级 .codex/config.toml;挪到 ~/.codex/config.toml
503 no_channel_available该模型没有 Responses 通道,换上表里的模型
402 quota_exceeded余额不足。所有 Key 共享同一账户余额,到 充值页 充值

错误码完整说明见 错误码。长任务的超时与保活见 流式响应。

其他客户端#

  • Claude Code — Anthropic 的命令行编程助手
  • Gemini CLI — Google 的命令行编程助手
  • Cline — VS Code 编程插件