Codex 环境变量：管理密钥、代理和本地运行上下文

适用场景

这篇手册适合需要让 Codex 使用本地依赖、包管理器、代理、测试服务或凭证的用户。环境变量很有用，但也是最容易泄露敏感信息的地方。

OpenAI 官方文档提供了 Codex Environment variables 说明。具体变量名和支持范围应以官方页面为准。

步骤 1：先区分变量类型

环境变量大致分三类。

公开配置：

• NODE_ENV
• 测试环境开关。
• 非敏感功能开关。
• 本地路径说明。

敏感凭证：

• API key。
• token。
• 私有包 registry 凭证。
• 数据库连接串。
• 内部服务账号。

运行辅助：

• 代理配置。
• 包管理器缓存目录。
• 临时目录。
• CI 标识。

不同类型的变量，管理方式不一样。

步骤 2：不要把秘密值写进仓库

不要把真实值写进这些地方：

• .env 提交到 Git。
• AGENTS.md。
• config.toml。
• Markdown 教程正文。
• 构建日志。
• PR 评论。

可以提交的是示例文件：

OPENAI_API_KEY=replace-with-your-key
PRIVATE_REGISTRY_TOKEN=replace-with-your-token

示例文件只说明变量名和用途，不提供真实值。

步骤 3：在 AGENTS.md 中说明需要哪些变量

项目规则里可以写变量说明。

示例：

## 环境变量

- `OPENAI_API_KEY`：仅本地开发或测试环境使用，不要提交真实值。
- `NPM_TOKEN`：用于安装私有包，应通过安全凭证系统注入。

这样 Codex 能知道项目需要什么，但不会暴露秘密。

步骤 4：给 Codex 的任务里写清权限边界

如果任务会用到环境变量，要说明能做什么、不能做什么。

示例：

可以读取环境变量名来判断缺少哪些配置。
不要输出任何变量值，不要把变量写入文件。

对于敏感项目，可以更严格：

如果命令输出包含 token、key 或连接串，请停止并只说明发生了敏感输出。

步骤 5：云端任务使用平台 secret

Codex Cloud 或 CI 任务需要凭证时，优先使用平台提供的 secret 管理能力。

建议：

• 使用最小权限凭证。
• 使用测试环境凭证。
• 避免生产数据库。
• 限制凭证可访问域名。
• 定期轮换 token。

不要因为任务临时需要，就把 secret 写进项目文件。

常见错误

不要让 Codex 打印完整环境变量列表。里面可能包含敏感信息。

不要把 .env 当作普通配置文件提交。

不要在教程中写真实 token。即使截图里也要遮挡。

不要让云端任务使用生产凭证调试普通问题。

小结

环境变量适合传递本地运行上下文和安全凭证，但真实值必须留在安全位置。仓库里只放变量名、用途和示例，给 Codex 的任务中要明确不要输出或写入秘密值。