Codex
适用版本
最后验证：2026-10-06 · Codex CLI 0.160.0
OpenAI 官方 CLI。通过自定义 provider，可以把 Codex 指向任何兼容网关。
本文以 KunCode 为例演示，把示例中的地址、Key 和模型名替换成你自己的服务即可。占位符与替换规则见通用占位符说明。
1. 安装
npm install -g @openai/codexbrew install codex验证安装：
codex --version能打印版本号即可，例如 codex-cli 0.144.6。
2. 准备 API Key
见 准备 API Key。记下两样东西：
- API Key：常见形如
sk-...，以你的服务商为准 - API 节点：你的服务地址，例如
https://kuncode.120403.xyz
3. 找到配置文件
Codex 的配置文件位于用户目录下的 .codex/config.toml：
| 系统 | 路径 |
|---|---|
| macOS / Linux | ~/.codex/config.toml |
| Windows | %USERPROFILE%\.codex\config.toml |
Windows 上可以直接在资源管理器地址栏输入 %USERPROFILE%\.codex 打开目录：
如果文件不存在，新建一个 config.toml 即可。
4. 填写配置
用编辑器打开 config.toml，写入以下内容：
model_provider = "custom"
model = "deepseek-flash"
model_reasoning_effort = "xhigh"
[model_providers.custom]
name = "KunCode"
base_url = "https://kuncode.120403.xyz/v1"
wire_api = "responses"
requires_openai_auth = true
experimental_bearer_token = "sk-xxxxxxxx"
需要改的只有这几处：
| 字段 | 说明 |
|---|---|
model | 你要用的模型名，必须是服务支持的模型 |
base_url | 你的 API 节点 + /v1 |
experimental_bearer_token | 替换成你自己的 API Key |
name | provider 的显示名，随意填，不影响功能 |
base_url 必须带 /v1
base_url 要写成 https://kuncode.120403.xyz/v1。
Codex 会在它后面自动拼接 /responses，所以不要写成 /v1/responses。
密钥写在配置文件里
这种方式密钥是明文存在 config.toml 里的，注意：
- 不要把
config.toml提交到 Git - 共享屏幕或截图时记得打码
如果你更希望用环境变量管理密钥，可以改用 env_key 字段（见下方「进阶」）。
截图里多出来的两行
截图中的 disable_response_storage 和 model_catalog_json 是 CC Switch 导入时附加的字段，手动配置可以不加。
5. 验证
在任意目录执行：
codex exec "print hello"
看到 codex 正常回复内容就说明配置成功了。上面的输出里也会回显当前使用的 model、provider 和 reasoning effort，可以用来确认配置是否生效。
6. 常用配置
切换模型
改 model 字段即可：
model = "gpt-5"可用的模型名可以通过接口查询：
curl https://kuncode.120403.xyz/v1/models \
-H "Authorization: Bearer sk-xxxxxxxx"调整思考强度
model_reasoning_effort 控制推理强度，可选值：
| 值 | 说明 |
|---|---|
minimal | 最少思考，最快 |
low | 低强度 |
medium | 中等 |
high | 高强度 |
xhigh | 最高强度 |
model_reasoning_effort = "xhigh"不是所有模型都支持
只有推理模型才认这个字段。普通模型会忽略它。
7. 排障
按状态码系统排查见错误码与排障。
| 现象 | 可能原因 | 处理 |
|---|---|---|
401 Unauthorized | Key 错误或未生效 | 确认 experimental_bearer_token 填的是完整密钥 |
404 Not Found | base_url 写错 | 确认以 /v1 结尾，且服务支持 Responses 入口 |
| 模型不存在 | 模型名未开放 | 换成 /v1/models 返回列表中的模型 |
| 连接超时 | 网络或代理问题 | 检查 DNS、代理、防火墙 |
| 配置不生效 | 文件路径错误 | 确认是 ~/.codex/config.toml，不是 codex.toml |
进阶：用环境变量管理密钥
不想把密钥写进配置文件，可以改成从环境变量读取：
[model_providers.custom]
name = "KunCode"
base_url = "https://kuncode.120403.xyz/v1"
wire_api = "responses"
env_key = "KUNCODE_API_KEY"然后设置环境变量：
export KUNCODE_API_KEY="sk-xxxxxxxx"$env:KUNCODE_API_KEY = "sk-xxxxxxxx"需要持久化的话，macOS / Linux 写进 ~/.zshrc 或 ~/.bashrc，Windows 用系统环境变量设置。
进阶：用 CC Switch 一键导入
如果你已经在用 CC Switch 管理多个服务商，可以跳过手写配置：
- 在服务的 API 密钥 页面，找到目标令牌
- 点击「导入到 CC Switch」
- 选择应用 Codex，填写模型名
- 点击「打开 CC Switch」，配置会自动写入
config.toml
导入后配置内容和上面手动写的一致，只是省去了手写步骤。
进阶：Codex++ 桌面端增强（第三方）
非官方工具，先审计源码
Codex++ 不是 OpenAI 官方产品，也不是独立的 AI 编程客户端。它面向 Codex Desktop，通过修改或注入桌面应用、运行本地脚本、安装更新 watcher 等方式扩展界面、账号和 provider 配置。只从有可审计源码的仓库安装，不要使用来源不明或只提供预编译包的版本。
Codex++ 项目信息核对：2026-10-07。OpenAI 官方文档目前没有说明支持这类 Codex Desktop 注入接口。接入 KunCode 仍优先使用上面的 Codex CLI config.toml 方式；只有明确需要桌面端中文界面、账号切换或图形化管理时，才考虑 Codex++。
使用前先备份
- 退出 Codex Desktop。
- 备份
~/.codex/config.toml和~/.codex/auth.json；Windows 对应%USERPROFILE%\.codex\config.toml和%USERPROFILE%\.codex\auth.json。 - 记录当前 Codex Desktop 版本、provider 和模型配置。
- 保留备份，直到确认桌面端和新 provider 都能正常工作。
xianyu110/CodexPlusPlus 文档称，其“清除 API 模式”可切回官方登录态；原版 Codex++ 文档提供 codexplusplus safe-mode、repair 和 uninstall。不要把这些命令当作唯一备份，先自行备份配置和登录文件。
CLI 成功不等于桌面端成功
上面的 codex exec 验证的是 Codex CLI。Codex Desktop 是否读取同一份 ~/.codex/config.toml、是否被 Codex++ 改写，取决于桌面端版本和具体实现。接入后要在桌面端再单独发一条消息，并确认实际请求走了目标 provider。
目前可研究的项目：
| 项目 | 平台 / 状态 | 说明 |
|---|---|---|
| xianyu110/CodexPlusPlus | Windows / macOS，活跃 | 通过外部 launcher 和 CDP 注入增强桌面端，宣称不改 app.asar；提供“中转注入”，会把自定义 provider 写入 ~/.codex/config.toml |
| b-nnett/codex-plusplus | 原项目，已归档 | 早期 tweak 系统，会修改 app.asar；最后代码更新为 2026-06-08，不建议新装 |
不要使用不可信发行包
不要使用宣称“跳过官方登录”“解锁插件市场”的不可信发行包。这类功能可能违反服务条款、暴露账号凭据或破坏 Codex 更新。不要把 API Key 提交到 Git、粘贴到 Issue，或交给未审计的第三方脚本。
发现错误或有内容过期？
文档会随工具版本更新。欢迎提交 Issue 反馈问题，或直接点击页脚的「在 GitHub 上编辑此页」提交修改。