10. 环境变量

本节目标：搞清楚 Codex 读取哪些环境变量、各自管什么、什么时候该设，覆盖安装、认证、代理、诊断四大场景。

config.toml 是你「写进文件」的配置。环境变量是另一种控制方式—不写文件，通过系统环境变量临时控制 Codex 的行为。两者互补，有些东西只能用环境变量设。

核心位置变量

CODEX_HOME

CODEX_HOME=~/.codex

设置 Codex 的状态根目录，包括配置、认证、日志、会话、技能。默认是 ~/.codex。

什么时候需要改它？当你想完全隔离多套环境时。比如工作和个人用不同的账号、配置、历史：

# 工作环境
CODEX_HOME=~/.codex-work codex

# 个人环境
CODEX_HOME=~/.codex-personal codex

Warning

如果设置 CODEX_HOME，目录必须已经存在。Codex 不会自动帮你创建。

CODEX_SQLITE_HOME

CODEX_SQLITE_HOME=/path/to/sqlite

设置 SQLite 状态数据库的存储位置。sqlite_home 配置项优先于这个环境变量。默认跟 CODEX_HOME 一致。

安装器变量

这些变量适用于官方安装脚本。

CODEX_NON_INTERACTIVE

CODEX_NON_INTERACTIVE=1

设为 1、true 或 yes 可跳过安装器的交互提示。提示会使用默认回答，适合脚本化安装和更新，不适合首次设置。

无人值守安装：

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

# Windows
$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

CODEX_INSTALL_DIR

CODEX_INSTALL_DIR=/custom/path

改变 codex 命令的安装位置。默认 macOS/Linux 上是 ~/.local/bin，Windows 上是 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin。

认证变量

CODEX_API_KEY

CODEX_API_KEY=sk-xxx codex exec "检查一下这个文件"

为单次非交互运行提供 API key。只支持 codex exec，不支持交互式 CLI。

Warning

运行仓库可控代码时，请内联设置它（像上面那样跟在命令后面），而不是在整个 job 范围内 export。防止 key 泄露到不可信代码能读到的地方。

CODEX_ACCESS_TOKEN

CODEX_ACCESS_TOKEN=xxx codex login --with-access-token

为受信任自动化提供 ChatGPT 或 Codex 访问令牌。若要持久登录，把它通过管道传给 codex login --with-access-token。

网络与代理

国内用户最关心的一块。Codex 连的是 OpenAI 的服务器，网络不通什么都白搭。

代理设置

Codex 走标准的 HTTP 代理环境变量：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

设好后 Codex 的请求会走你指定的代理。这在无法直连 OpenAI 的网络环境里是必须的。

CODEX_CA_CERTIFICATE

CODEX_CA_CERTIFICATE=/path/to/ca-bundle.pem

指向 PEM CA 证书包，用于存在企业 TLS 拦截或私有根证书的环境。优先级高于 SSL_CERT_FILE。

Tip

公司网络有 TLS 拦截（中间人代理）？Codex 连不上、报证书错误？设这个变量指向你公司的 CA 证书包就能解决。

SSL_CERT_FILE

SSL_CERT_FILE=/path/to/ca-bundle.pem

当 CODEX_CA_CERTIFICATE 未设置时的备用 CA 证书路径。

诊断变量

RUST_LOG

RUST_LOG=debug codex

控制 Rust 日志的过滤和详细程度。Codex 是用 Rust 写的，这个变量管它的日志输出。

可选值从粗到细：error、warn、info、debug、trace。也接受更有针对性的过滤器：

RUST_LOG=codex_core=debug,codex_tui=debug codex

codex exec 默认输出 error 级别，除非你设了更详细的值。

Note

交互式 CLI 默认把诊断记录在有界本地存储中。需要明文日志用于排障时，显式设置 log_dir：

RUST_LOG=debug codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log

在非交互模式下，codex exec 会内联打印消息，而不是写入单独的日志文件。

环境变量速查表

把这一章的变量收成一张表：

变量	场景	作用
`CODEX_HOME`	多账号隔离	设置状态根目录
`CODEX_NON_INTERACTIVE`	脚本化安装	跳过安装器交互提示
`CODEX_INSTALL_DIR`	自定义安装位置	改变 codex 命令的安装路径
`CODEX_API_KEY`	CI/CD 非交互	为 codex exec 提供 API key
`CODEX_ACCESS_TOKEN`	受信任自动化	提供访问令牌
`HTTP_PROXY` / `HTTPS_PROXY`	代理上网	让请求走指定代理
`CODEX_CA_CERTIFICATE`	企业 TLS	指定 CA 证书包
`SSL_CERT_FILE`	企业 TLS 备用	备用 CA 证书路径
`RUST_LOG`	排障	控制日志详细程度

一个实战组合

国内开发者在 CI 里跑 Codex 的典型环境变量组合：

# 设代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 设 API key
export CODEX_API_KEY=sk-xxx

# 非交互运行
codex exec --sandbox workspace-write "跑一遍测试，修好失败的用例"

Warning

别把带 API key 的 Codex 跑在不可信或公开环境里。CI 里用 secrets 管理工具注入 key，别硬写在脚本里。

小结

核心位置：CODEX_HOME 管状态根目录，CODEX_SQLITE_HOME 管 SQLite 存储
安装器：CODEX_NON_INTERACTIVE 跳过提示，CODEX_INSTALL_DIR 改安装位置
认证：CODEX_API_KEY 给 exec 用，CODEX_ACCESS_TOKEN 给自动化用
网络：HTTP_PROXY / HTTPS_PROXY 设代理，CODEX_CA_CERTIFICATE 解决企业 TLS
诊断：RUST_LOG 控制日志详细程度，配 log_dir 输出明文日志

环境变量和 config.toml 互补—有些东西只能用环境变量设（比如代理、安装器行为），有些适合写进配置文件（比如模型、审批策略）。两者搭配使用，覆盖所有场景。

下一章讲交互式 TUI 模式—那个你启动 codex 后进入的全屏交互界面。