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 字符) |
| 404 | base_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 编程插件