Appearance
Codex CLI 接入第三方 API：API Key 与配置教程
Codex CLI 默认的登录方式适合直接使用官方服务。如果你需要在自己的产品、团队网关或 API 服务中调用模型，就需要配置一个兼容的 API Provider。
这篇文章讲清楚接入时最容易出错的几个部分：API Key 放在哪里、Base URL 怎么确认、模型名从哪里获取、auth.json 和 config.toml 分别负责什么，以及为什么配置完成后仍然会出现 401。
不同 Codex 版本和 API 服务商的配置字段可能不同。本文展示的是排查思路和通用结构，具体字段、endpoint 和模型列表请以你正在使用的 API 控制台文档为准。
接入前先确认 5 件事
开始配置前，先从服务商文档确认以下信息：
- API Base URL，例如
https://api.example.com/v1。 - 认证方式，是
Authorization: Bearer，还是其他 Header。 - 可用模型的完整名称，模型名通常区分大小写。
- 使用的是 Responses、Chat Completions，还是服务商自己的协议。
- 是否支持 Codex 所需要的工具调用、流式响应或其他能力。
如果只拿到一串 API Key，却没有 Base URL 和协议说明，不要直接猜配置。先打开服务商文档或控制台确认，否则最常见的结果就是 401、404 或请求格式错误。
需要 API 入口时，可以先查看 api.clawsocket.com 的服务说明和当前配置要求。
API Key 不要写进项目文件
API Key 应该保存在服务端环境变量或密钥管理系统中。不要把它写进前端代码、提交到 Git、放进截图，也不要粘贴到公开的 issue。
macOS 和 Linux 可以先在当前终端设置环境变量：
export OPENAI_API_KEY="your-api-key"
Windows PowerShell 的写法是：
$env:OPENAI_API_KEY = "your-api-key"
变量名是否必须叫 OPENAI_API_KEY，取决于 Codex 版本和 Provider 配置方式。某些服务商会要求自己的变量名，例如 CLAWSOCKET_API_KEY。以服务商文档为准，并确认 Codex 配置引用的是同一个变量。
设置后，可以只检查变量是否存在，不要把完整内容打印出来：
test -n "$OPENAI_API_KEY" && echo "API key is set"
auth.json 和 config.toml 的区别
在很多 Codex CLI 配置中，可以把两个文件理解成不同职责：
auth.json：保存认证信息或登录状态。config.toml：保存 Provider、Base URL、默认模型和工作方式等配置。
它们的位置通常在用户目录下的 .codex 文件夹中，例如 macOS 和 Linux 的 ~/.codex/。Windows 通常对应当前用户目录下的 .codex 文件夹。
不要从网上复制一份完整的 auth.json 覆盖自己的配置。认证文件可能包含敏感信息，也可能因为版本不同而使用不同字段。更稳妥的做法是先备份，再根据当前版本和服务商文档添加最少字段。
配置 Base URL 和模型名
Provider 配置通常至少需要三类信息：Provider 名称、Base URL 和默认模型。概念结构类似下面这样：
toml
# 示例结构，字段名请以当前 Codex 版本文档为准
model = "your-model-name"
[model_providers.your_provider]
name = "your_provider"
base_url = "https://api.example.com/v1"
env_key = "OPENAI_API_KEY"这个示例的重点不在于直接复制，而在于检查三者是否一致：
model必须是服务商实际提供的模型名。base_url必须包含服务商要求的路径版本，例如/v1。env_key必须对应你真正设置的环境变量。
如果服务商文档要求使用不同配置层级，请使用它的官方结构，不要为了匹配示例而强行改写。
先用 curl 验证 API
在让 Codex 读取配置之前，先单独验证 API 网络、鉴权和响应格式。示例：
curl https://api.clawsocket.com/v1/responses -H "Authorization: Bearer $CLAWSOCKET_API_KEY" -H "Content-Type: application/json" -d '{"model":"codex","input":"只返回 OK"}'
如果请求成功，再把相同的 Base URL、模型名和密钥变量配置到 Codex。这样可以把问题拆成两层：
- curl 失败：优先检查 API Key、Base URL、网络、额度和协议。
- curl 成功但 Codex 失败：优先检查 Codex 版本、配置文件格式和 Provider 映射。
不要一开始同时更换模型、修改 Base URL 和重写配置文件，否则出现错误时无法知道是哪一步导致的。
配置完成后的最小验证
完成配置后，按顺序做一次最小验证：
- 运行
codex --version，确认当前调用的是预期版本。 - 确认 API Key 环境变量存在，但不打印完整值。
- 用一个只读任务启动 Codex，例如“读取 package.json，只告诉我测试命令，不修改文件”。
- 观察请求是否使用了预期的模型和 Provider。
- 再让 Codex 执行一个可以通过 Git diff 和测试验证的小任务。
第一次验证不要直接让 Codex 写完整应用。最小任务更容易判断配置是否真的生效。
401、403、404 和 429 怎么区分
401 Unauthorized
通常表示认证凭据无效、过期、变量名不对，或者请求没有带上正确的 Authorization Header。检查 API Key 是否有空格、是否已经撤销、配置引用的变量名是否正确。
403 Forbidden
通常表示密钥有效，但账户、项目或模型没有权限。检查账户权限、模型访问范围、来源限制和组织配置。不要只换一把 Key，先确认权限规则。
404 Not Found
通常和 Base URL、路径版本或 endpoint 不匹配有关。例如服务商要求 /v1/responses，但配置拼出了 /responses。把最终请求 URL 和服务商文档逐段对照。
429 Too Many Requests
通常表示速率限制、并发过高或额度不足。降低并发，使用指数退避，并给用户一个可理解的降级响应。不要在客户端无限重试。
常见配置错误
把完整 endpoint 填进 Base URL
有些配置需要的是 https://api.example.com/v1，而不是完整的 /responses 地址。Base URL 和具体 endpoint 由客户端拼接时，重复路径会导致 404。
模型名称写成展示名称
控制台显示的商品名称不一定是 API 模型 ID。复制 API 文档中的精确模型名，注意大小写、连字符和版本后缀。
把 API Key 提交到 Git
一旦密钥进入 Git 历史，就不能只删除当前文件。立即撤销旧 Key，清理历史记录，并检查 CI、日志和构建产物中是否也出现过。
修改了配置却没有生效
确认 Codex 读取的是当前用户目录下的配置，终端是否加载了旧环境变量，以及是否有项目级配置覆盖了全局配置。可以先备份配置，再临时移动无关配置，使用最小文件验证。
生产环境接入建议
本地跑通后，还需要补齐生产环境措施：
- API Key 使用密钥管理系统，不写入镜像和仓库。
- 为连接和整体请求设置超时。
- 只对可重试的 429 和部分 5xx 做有限重试。
- 记录 request id、状态码、耗时和 token 用量。
- 对敏感输入脱敏，不把完整提示词写入普通日志。
- 为用户、任务和团队设置配额。
- 用固定样例做提示词和模型回归测试。
更多上线检查可以阅读 Codex API 生产环境接入清单。
FAQ
Codex 可以直接使用任意 OpenAI 兼容 API 吗？
不能只看“兼容”三个字。除了请求格式，还要确认 endpoint、认证方式、工具调用、流式响应和模型能力是否满足 Codex 的实际要求。
auth.json 里应该放什么？
取决于当前 Codex 版本和认证方式。不要复制陌生来源的完整认证文件，也不要把自己的认证文件发给别人。按照当前官方文档或服务商文档添加必要字段。
为什么 curl 成功，Codex 仍然报 401？
常见原因是 Codex 没有读取同一个环境变量，配置引用了错误的变量名，或者 Codex 使用了另一套认证文件。先确认实际生效的 Provider 和环境，再检查配置覆盖关系。
第三方 API 的 Base URL 应该怎么填？
填写服务商文档明确提供的 Base URL，不要自行猜测是否需要 /v1。如果文档同时给出了完整请求地址和 Base URL，优先使用 Base URL 字段。
API Key 放在 Codex 配置文件里安全吗？
只要文件权限、备份和访问范围得到控制，仍然比写进代码安全，但生产环境更推荐使用密钥管理系统或环境变量。无论放在哪里，都不要提交到 Git。
继续阅读
如果你已经确认需要一个 API 入口，可以访问 api.clawsocket.com 查看当前的账户和接入信息。