客户端配置
Codex Desktop / CLI
为 Codex 配置 Responses API 和本地认证。
Codex Desktop / CLI
Codex 使用 Responses wire API。先在 config.toml 中加入模型服务，再让官方登录命令把认证信息存入 Codex 配置的凭据存储。
开始前准备
- 一把已启用且分组正确的
<API_KEY>。 - 一个通过
GET /v1/models确认存在的<MODEL>。 - 已安装并至少启动过一次 Codex Desktop 或 CLI，使配置目录已经创建。
先用 cURL 验证 Key 和模型。若最小 cURL 请求失败，先不要修改 Codex 配置。
找到配置目录
默认配置目录是当前用户目录下的 .codex：
| 系统 | 常见位置 |
|---|---|
| Windows | %USERPROFILE%\.codex |
| macOS / Linux | ~/.codex |
如果设置过 CODEX_HOME，使用该变量指向的目录。修改前备份已有文件，不要覆盖其中与审批、沙箱或工具相关的其他设置。
配置模型服务
打开 .codex/config.toml，合并以下字段。已有同名字段时更新原值，不要重复创建两段同名 provider。
toml
model_provider = "custom"
model = "<MODEL>"
[model_providers.custom]
name = "Suoxie"
base_url = "https://suoxie.codes/v1"
wire_api = "responses"
requires_openai_auth = truemodel_provider 必须与 [model_providers.custom] 中的 custom 一致。base_url 已包含 /v1，不要再追加一次。
配置认证
使用官方的 stdin 登录流程。不要把 Key 直接写入命令参数，也不要手工修改 Codex 的凭据缓存文件。
macOS / Linux：
bash
read -rsp "API key: " OPENAI_API_KEY && printf '\n'
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login statusWindows PowerShell：
powershell
$secureKey = Read-Host "API key" -AsSecureString
$credential = [System.Net.NetworkCredential]::new("", $secureKey)
$credential.Password | codex login --with-api-key
Remove-Variable secureKey, credential
codex login statuscodex login status 应显示已经登录。Codex 会按配置将凭据放入操作系统凭据库，或回退到自己管理的本地缓存。两者都属于敏感信息，不要复制到共享目录或提交到 Git。
重启并验证
- 完全退出 Codex Desktop，或结束当前 CLI 会话。
- 重新启动，确认选择的模型是
<MODEL>。 - 在一个可丢弃目录中发送“只回复 OK”之类的短任务。
- 确认正常返回后，再打开真实项目。
成功标志： Codex 能建立会话并返回文本，控制台用量页出现对应 Responses 请求。
常见问题
| 现象 | 先检查什么 |
|---|---|
| 配置解析失败 | TOML 是否重复键、provider 段是否有效 |
| 401 / 未授权 | codex login status、Key 是否有效、API Key 登录是否完成 |
| 模型不存在 | <MODEL> 是否与当前 /v1/models 返回完全一致 |
| 请求到了错误地址 | base_url 是否恰好为 https://suoxie.codes/v1 |
| 修改后无变化 | 是否完全退出并重启，是否设置了另一个 CODEX_HOME |
如果旧配置还能正常工作而新配置失败，先恢复配置备份，再逐项加入 model_provider 和 provider 段，最后重新执行登录流程，找出具体差异。
安全与回退
- 不在任务提示、截图或终端输出中粘贴完整 Key。
- 多台设备分别创建 Key，便于单独撤销。
- 准备回退时保留原
config.toml，但不要导出或复制 Codex 的凭据缓存。 - 怀疑泄露时立即在控制台撤销 Key，创建新 Key 后重新执行登录流程。