跳至主要內容

手动配置 Codex

GoodCode2026/7/8大约 3 分钟

提示

推荐直接在后台密钥列表点击 使用密钥，复制自动生成的配置，无需手写！

前置条件

请先创建一个 OpenAI 分组 的 API Key，见 API 密钥管理。

1. 安装 Codex

Codex CLI

如果你使用命令行版本（Codex CLI），先运行下面命令安装：

npm i -g @openai/codex@latest

Codex CLI 包地址：
https://www.npmjs.com/package/@openai/codex

安装完成后先检查版本：

codex --version

2. 找到 Codex 的配置文件夹

打开终端，根据系统执行下面的命令。目录不存在时先创建目录，再打开。

Windows

CMD 命令行：

if not exist "%USERPROFILE%\.codex" mkdir "%USERPROFILE%\.codex"
start "" "%USERPROFILE%\.codex"

如目录不存在，可按 Win+R 输入 %userprofile% 后手动创建 .codex 文件夹。

3. 写入 config.toml 并配置 API Key

手动创建 config.toml 文件，并通过环境变量提供 API Key。

注意

请确保以下内容位于 config.toml 文件的开头部分。

config.toml
model_provider = "goodcode"
model = "gpt-5.5"
review_model = "gpt-5.5"
model_reasoning_effort = "xhigh"
disable_response_storage = true
windows_wsl_setup_acknowledged = true

[model_providers.goodcode]
name = "GoodCode"
base_url = "https://goodcode.store/v1"
wire_api = "responses"
env_key = "GOODCODE_API_KEY"

[features]
goals = true

将 GOODCODE_API_KEY 替换为你在后台生成的 OpenAI 分组 API Key。上面的环境变量只对当前终端会话生效；长期使用时，可以写入 shell 配置文件或系统环境变量。

相关信息

Codex 的自定义 provider 通过 model_providers.<id> 配置。手动配置推荐使用 env_key 读取 API Key，不建议手写 ~/.codex/auth.json；如果使用 Codex 官方登录/API Key 登录流程，则让 Codex 自己生成和维护认证缓存。

可选：Codex 命令沙箱联网

network_access 控制的是 Codex 执行 shell 命令时的沙箱联网权限，不是模型 API 调用开关。只有需要让 Codex 在 workspace-write 沙箱里执行联网命令时，才需要加入：

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

4. 重启并验证

关闭当前 Codex 会话，重新打开终端后运行：

codex

如果能进入 Codex 交互界面并正常对话，说明配置生效。若启动后仍走默认 OpenAI 官方服务，优先检查 config.toml 是否放在 ~/.codex/config.toml，文件开头是否包含 model_provider = "goodcode"，以及启动 Codex 的终端是否能读取到 GOODCODE_API_KEY。

WebSocket 模式（可选）

GoodCode 网关支持 Codex 的 Responses WebSocket 模式，长会话下连接更稳定。将 config.toml 替换为：

model_provider = "goodcode"
model = "gpt-5.5"
review_model = "gpt-5.5"
model_reasoning_effort = "xhigh"
disable_response_storage = true
windows_wsl_setup_acknowledged = true

[model_providers.goodcode]
name = "GoodCode"
base_url = "https://goodcode.store/v1"
wire_api = "responses"
supports_websockets = true
env_key = "GOODCODE_API_KEY"

[features]
goals = true

相关信息

supports_websockets = true 是 provider 的 WebSocket 能力声明。不要额外添加未公开的 feature flag；如果当前 Codex 版本未使用 WebSocket，会自动回退到普通 Responses 请求。

配置生效提醒

  • 每次修改 config.toml 或 API Key 环境变量后，都需要重启 codex 才会生效。
  • 怎么重启：先 Ctrl + C 退出当前 codex，再重新运行 codex。
  • 适用范围：VSCode 插件版 Codex 同样读取 ~/.codex/config.toml；如果插件无法读取环境变量，请从带有 GOODCODE_API_KEY 的环境启动 VSCode，或改用 Codex 官方登录/API Key 登录流程。

多账号 / 粘性会话提醒

Codex 会通过 session_id 请求头维持粘性会话。如果你自己在 GoodCode 前面又套了一层 Nginx 反代，需要在 Nginx 的 http 块中加上 underscores_in_headers on;，否则该请求头会被丢弃，导致多账号环境下会话粘性失效。直连 goodcode.store 则无需关心。

最近更新: