Codex CLI 配置指南

Codex CLI 是 OpenAI 官方的终端编程助手。Zivv 提供 Responses API 兼容端点，可通过 Codex 的自定义 Model Provider 接入。

最近核验：2026-07-24。安装方式和配置字段已对照 OpenAI 官方 Codex 文档；模型 ID 以 Zivv 模型广场 为准。

配置原则

Codex 使用用户级配置目录 ~/.codex/。已有配置只需合并 Zivv Provider，不要删除整个目录，也不要把 API Key 写进项目仓库。

准备工作

• 已在 令牌管理 创建 API Key
• 已在 模型广场 确认可用模型 ID
• Windows 用户已安装 PowerShell 5.1+；如果原生环境兼容性不理想，可改用 WSL

建议为 Codex 单独创建 Key，并设置额度、有效期和模型分组。更多说明见 API Key 管理与安全。

1. 安装 Codex CLI

独立安装脚本（官方推荐）

Windows PowerShell

irm https://chatgpt.com/codex/install.ps1 | iex

macOS / Linux / WSL

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

npm 安装（旧版安装方式，仍受支持）

npm install -g @openai/codex@latest

验证安装：

codex --version

官方目前把独立安装脚本作为推荐方式，npm 属于 legacy installation。升级安装方式前请查看 Codex CLI 官方页面。

2. 设置 API Key 环境变量

将 sk-你的Key 替换为控制台生成的真实 Key。

Windows PowerShell

[Environment]::SetEnvironmentVariable("ZIVV_API_KEY", "sk-你的Key", "User")

macOS / Linux（zsh）

echo 'export ZIVV_API_KEY="sk-你的Key"' >> ~/.zshrc
source ~/.zshrc

Linux（Bash）

echo 'export ZIVV_API_KEY="sk-你的Key"' >> ~/.bashrc
source ~/.bashrc

重新打开客户端

设置用户环境变量后，请关闭并重新打开终端。已经运行的 Codex CLI、IDE 扩展或桌面应用也要完全退出后重启。

3. 配置 Zivv Provider

配置文件位置：

• Windows：%USERPROFILE%\.codex\config.toml
• macOS / Linux：~/.codex/config.toml
• 自定义过 CODEX_HOME 时：$CODEX_HOME/config.toml

如果文件已经存在，请先备份，然后把下面字段合并进去：

model_provider = "zivv"
model = "模型广场中的模型 ID"

[model_providers.zivv]
name = "Zivv"
base_url = "https://zivv.pro/v1"
env_key = "ZIVV_API_KEY"
wire_api = "responses"

字段说明：

字段	说明
model_provider	选择上面定义的 zivv Provider
model	从模型广场复制的精确模型 ID，不使用文档中的固定版本名
base_url	Zivv OpenAI 兼容 Base URL，不要追加 /responses
env_key	Codex 从该环境变量读取 Key
wire_api	Codex 当前自定义 Provider 使用 responses

如果你已有 [projects.*]、[features]、MCP 或其他 Provider，请保留原配置。无需单独创建 auth.json。

完整字段定义见 OpenAI Codex 配置参考。

4. 验证连接

进入任意项目目录执行：

codex exec "只回复 pong"

收到 pong 或正常模型响应后，再运行交互模式：

codex

切换模型

永久切换可修改 config.toml：

model = "模型广场中的模型 ID"

临时切换：

codex --model "模型广场中的模型 ID"

客户端升级后，默认模型和可用能力可能变化。请重新检查模型 ID、Responses API 支持和 Key 分组。

常见问题

401 Unauthorized

1. 在新终端中确认能读取 ZIVV_API_KEY。
2. 检查 Key 是否完整、有效且未过期。
3. 确认 env_key 严格写成 ZIVV_API_KEY。
4. 完全退出并重启 Codex。

404、协议错误或响应解析失败

确认：

base_url = "https://zivv.pro/v1"
wire_api = "responses"

不要把 Base URL 写成完整的 https://zivv.pro/v1/responses。

模型不存在或无权限

从 模型广场 重新复制模型 ID，并检查 Key 分组、模型白名单和余额。

请求体压缩相关错误

Zivv 当前支持 Codex 的压缩请求。只有代理链或调试环境不能处理压缩时，才在已有 [features] 配置块中关闭：

[features]
enable_request_compression = false

如果文件里已经存在 [features]，只添加字段，不要重复创建同名配置块。

CLI 和其他 Codex 客户端配置不一致

检查是否设置了不同的 CODEX_HOME，以及其他客户端是否读取同一个用户级 ~/.codex/config.toml。桌面端读取环境变量还有差异，见 Codex 桌面端配置。

官方资料

• Codex CLI
• Codex 配置参考
• Codex Windows 指南
• 文档版本维护策略