Appearance
Codex API Key 配置教程：环境变量与安全实践
很多 Codex 接入问题并不是模型调用本身造成的，而是 API Key 没有被正确读取：变量名写错、终端没有重新加载、Base URL 不匹配，或者密钥已经失效。
本文给出一套通用配置方法。它适用于 Codex CLI、后端脚本和服务端 API 调用，但具体变量名和 endpoint 仍然要以 API 服务商的当前文档为准。
API Key 应该放在哪里
开发环境可以暂时放在本机环境变量中，生产环境建议使用密钥管理系统。不要把密钥放在以下位置：
- 前端 JavaScript、浏览器 Local Storage 或公开网页
- Git 仓库、
.env文件提交记录或 issue - CI 构建日志、截图和异常日志
- 分享给同事的完整配置文件
如果一串密钥已经进入 Git 历史，不要只删除当前文件。先撤销旧密钥，再创建新密钥，并检查日志、构建产物和备份。
macOS 和 Linux 设置环境变量
在当前终端设置变量：export CLAWSOCKET_API_KEY="your-api-key"。
变量名只是示例。服务商可能要求使用 OPENAI_API_KEY 或自定义名称，关键是 Codex 或你的脚本读取的变量名必须和这里保持一致。
确认变量存在，但不要打印完整内容：test -n "$CLAWSOCKET_API_KEY" && echo "API key is set"。
如果希望新终端自动加载，可以把变量放进 shell 的本地配置文件，但要确保该文件没有被 Git 跟踪，也不要把密钥复制到团队共享配置中。
Windows PowerShell 设置变量
当前 PowerShell 会话可以运行：$env:CLAWSOCKET_API_KEY = "your-api-key"。
设置后用 if ($env:CLAWSOCKET_API_KEY) { "API key is set" } 检查是否存在。关闭终端后，临时环境变量可能会消失，这是正常行为。
如果使用 Windows 的持久环境变量，确认只有当前用户或密钥管理工具可以读取，并重新打开使用 Codex 的终端。
Base URL 和模型名必须成对确认
一个 API Key 不能自动告诉客户端请求应该发送到哪里。接入前至少要确认：
- API Base URL 是否需要
/v1等版本路径。 - 认证 Header 是否使用
Authorization: Bearer。 - 模型的精确 ID，而不是控制台里的营销名称。
- 使用 Responses、Chat Completions 还是其他协议。
- 是否支持 Codex 需要的工具调用、流式响应和上下文能力。
建议把这些信息记录在私有的部署文档中，但不要把真实密钥记录进去。
用 curl 做第一次验证
在配置 Codex 前，先单独测试 API。以 api.clawsocket.com 的示例结构为例：
curl https://api.clawsocket.com/v1/responses -H "Authorization: Bearer $CLAWSOCKET_API_KEY" -H "Content-Type: application/json" -d '{"model":"codex","input":"只返回 OK"}'
实际 endpoint、模型和请求字段请以 api.clawsocket.com 当前文档为准。不要因为某个服务商使用 OpenAI 兼容协议，就假设所有路径和模型名完全相同。
把结果分成三类：
- 401：优先检查 Key、Header 和变量名。
- 404：优先检查 Base URL、版本路径和 endpoint。
- 200 但内容错误：检查模型名、协议和请求体字段。
在 JavaScript 服务端使用
服务端代码只读取环境变量，不把 Key 写进源代码。基本结构如下：
js
const response = await fetch('https://api.clawsocket.com/v1/responses', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CLAWSOCKET_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ model: 'codex', input: '只返回 OK' })
})
if (!response.ok) throw new Error(`API request failed: ${response.status}`)
const data = await response.json()
console.log(data)生产代码还应该加入超时、错误分类、响应校验和日志脱敏。不要把完整的请求体和 Authorization Header 一起写入日志。
在 Codex CLI 中配置
Codex CLI 的 Provider 配置通常需要把默认模型、Base URL 和环境变量关联起来。config.toml 的真实字段会随版本和 Provider 变化，概念结构可以理解为：
toml
model = "your-model-id"
[model_providers.your_provider]
name = "your_provider"
base_url = "https://api.example.com/v1"
env_key = "CLAWSOCKET_API_KEY"这段内容是结构示意，不应该盲目复制。先确认当前 Codex 版本支持的字段，再对照服务商文档填写。
认证状态可能保存在用户目录下的 ~/.codex/auth.json。不要从陌生网站下载认证文件，也不要把自己的文件发给别人。关于两个配置文件的职责，可以阅读 Codex CLI 接入第三方 API。
密钥轮换和权限控制
建议给开发、预发布和生产环境使用不同的 Key。每把 Key 都应该有清晰的拥有者、用途和撤销方式。
发生以下情况时应立即轮换：
- Key 出现在 Git、日志或截图中
- 团队成员离开或权限变化
- 供应商后台出现异常调用
- 不确定 Key 是否已经泄露
轮换时先创建新 Key 并验证服务，再撤销旧 Key，避免出现不必要的中断。
FAQ
API Key 应该叫 OPENAI_API_KEY 还是其他名字？
取决于 Codex 版本和 Provider 配置。服务商如果要求自定义变量名，就使用文档给出的名字，并确保配置文件引用同一个变量。
为什么变量设置了，Codex 仍然说没有 Key？
常见原因是变量只设置在另一个终端、终端没有重启、变量名拼错，或者项目使用了另一套配置覆盖全局设置。
能不能把 API Key 放进 config.toml？
是否支持取决于工具版本，但生产环境不推荐把密钥硬编码在配置文件中。优先使用环境变量或密钥管理系统。
API Key 有效但返回 403 是什么原因？
403 通常表示账号或项目没有访问当前模型、endpoint 或组织资源的权限。检查权限和额度，不要只重复创建 Key。
API Key 配置成功后如何验证？
先用最小 curl 请求验证，再用 Codex 做一个只读任务，最后才执行小范围代码修改。每一步都保留状态码和验证结果。