Codex 环境变量怎么配(0.167 实测):API Key 写哪里、代理、CODEX_HOME、CI 注入与冲突排错

用 AI Code With 接入 Codex 不需要设 API Key 环境变量:全局 config.toml 用 experimental_bearer_token 写 Key 即可。本文在 Codex CLI 0.167.0 上逐项实测:auth.json 写法、CI 里用 auth.command 从环境变量取 Key、HTTPS_PROXY 和 NO_PROXY 是否生效、CODEX_HOME 切换配置、环境变量和 config.toml 冲突谁生效、项目级配置为什么被忽略、怎么不让 Codex 运行的命令读到你的密钥,以及 401 和改完不生效的排错。

10 分钟阅读
Codex 环境变量怎么配(0.167 实测):API Key 写哪里、代理、CODEX_HOME、CI 注入与冲突排错

先说结论:用 AI Code With 接入 Codex,不需要设置任何 API Key 环境变量。 把地址和 Key 一起写进全局配置文件 ~/.codex/config.toml,换终端、换编辑器、重启电脑都能直接用。旧的 OPENAI_API_KEY、OPENAI_BASE_URL 留着也不会抢走请求,实测 config.toml 优先。

环境变量在 Codex 里仍然有用:走代理、公司证书、在 CI 里注入 Key、切换整套配置目录,以及控制 Codex 运行的命令能看到哪些变量。这篇按「你要做什么」给出直接写法,每一项都附上我们这次跑出来的结果。

2026 年 11 月 12 日(北京时间,UTC+8),我们在 Linux x64 上用 Codex CLI 0.167.0 重新跑了全部场景。每个场景都用一个全新的 HOME 目录,互不影响;请求头和请求地址用本机的一个记录服务抓取,真实对话用 AI Code With 的测试 Key。Windows 部分的命令按 PowerShell 官方写法给出,这次的测试机是 Linux。配置文件的完整字段见《Codex config.toml 配置指南》。

创建 API Key →

先看结论:你要做的事和对应写法

你想做的事直接这样写本次结果
日常在本机用 Codexconfig.toml 里写 experimental_bearer_token5.55 秒返回 OK
沿用控制台教程的 auth.jsonconfig.toml 加 requires_openai_auth = true请求头带上 auth.json 的 Key
CI 或密钥管理器只给环境变量auth.command 从环境变量里读 Key4.10 秒返回 OK
本机要走代理HTTPS_PROXY,例外地址放 NO_PROXY代理日志能看到 api.aicodewith.ai
一台机器放两套配置CODEX_HOME 指向另一个目录请求发到另一套配置的地址
不让命令读到你的密钥shell_environment_policy默认会传,改配置后不传

推荐写法:全局 config.toml 里直接写 Key

第一步,在 AI Code With 控制台创建一个 Key(步骤见创建 API Key 文档)。

第二步,打开(没有就新建)~/.codex/config.toml,写入下面这段完整配置,把 sk-你的Key 换成刚创建的 Key:

toml
model_provider = "aicodewith"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "sk-你的Key"

几个字段的含义:

  • model_provider:让 Codex 默认使用下面这段 aicodewith 配置,要写在文件最上面,不能放进任何 [ ] 小节。
  • base_url:AI Code With 给 Codex 用的专用地址,末尾是 /chatgpt/v1,不要改成别的路径。
  • wire_api = "responses":Codex 走 Responses 接口。
  • experimental_bearer_token:Codex 每次请求都会把它放进 Authorization: Bearer 请求头。

第三步,在终端里运行 codex,能正常对话就说明接通了。也可以用一句命令验证:

bash
codex exec --skip-git-repo-check "reply OK"

实测结果:全新 HOME、只写上面这段配置,codex exec 用时 5.55 秒,输出 OK。用记录服务抓到的请求头是 Authorization: Bearer 加 config.toml 里的那个 Key。

文件位置:macOS、Linux 是 ~/.codex/config.toml,Windows 是 %USERPROFILE%\.codex\config.toml。Key 是明文保存的,不要把这个文件提交到 Git 仓库,也不要同步到公开的 dotfiles。更多接入细节见《Codex 接入 AICodeWith》,还没装 Codex 的先看《Codex 安装教程》。

备选写法:Key 放进 auth.json

如果你是照着 AI Code With 控制台里的 Codex 教程配的,会看到另一种写法:Key 放在 ~/.codex/auth.json,config.toml 里不写 Key。两种写法选一种即可。

config.toml 这样写,注意多了一行 requires_openai_auth = true,并且没有 experimental_bearer_token:

toml
model_provider = "aicodewith"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
requires_openai_auth = true

然后在同一个目录下的 ~/.codex/auth.json 里写 Key:

json
{
  "OPENAI_API_KEY": "sk-你的Key"
}

requires_openai_auth = true 这一行不能省。0.167.0 上我们两种都跑了:只放 auth.json、不加这一行时,Codex 发出的请求不带 Authorization 头,服务端返回 401;加上之后,请求头里带的就是 auth.json 里的 Key。auth.json 本身的位置和风险见《Codex auth.json 是什么》。

CI 或密钥管理器:用 auth.command 从环境变量取 Key

GitHub Actions、GitLab CI、Docker 这类场景,Key 通常只以环境变量的形式给你,不方便提前写进文件。Codex 的自定义 Provider 支持 auth 配置:Codex 需要 Key 时运行一条命令,把命令打印出来的内容当作 Bearer Key。让这条命令去读环境变量,Key 就不用落进 config.toml。

toml
model_provider = "aicodewith"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
auth = { command = "sh", args = ["-c", "printf %s \"$ACW_API_KEY\""] }

运行前把 Key 放进 ACW_API_KEY(变量名可以自己定,和上面保持一致即可):

bash
export ACW_API_KEY="sk-你的Key"
codex exec --skip-git-repo-check "reply OK"

实测结果:config.toml 里没有任何 Key,只设了 ACW_API_KEY,codex exec 用时 4.10 秒,输出 OK。在记录服务上,这种写法的请求头同样是 Authorization: Bearer 加变量里的值;服务端返回 401 后,Codex 会重新运行一次这条命令取 Key 再试。

GitHub Actions 里可以这样写(Key 存在仓库的 Secrets 里,名字叫 ACW_API_KEY):

yaml
- name: Run Codex
  env:
    ACW_API_KEY: ${{ secrets.ACW_API_KEY }}
  run: |
    mkdir -p ~/.codex
    cat > ~/.codex/config.toml <<'TOML'
    model_provider = "aicodewith"

    [model_providers.aicodewith]
    name = "aicodewith"
    base_url = "https://api.aicodewith.ai/chatgpt/v1"
    wire_api = "responses"
    auth = { command = "sh", args = ["-c", "printf %s \"$ACW_API_KEY\""] }
    TOML
    codex exec --skip-git-repo-check "检查最近一次提交有没有明显的问题"

使用时注意三点:

  • 按官方配置说明,auth 不要和 experimental_bearer_token、requires_openai_auth 写在同一个 Provider 里,三选一。
  • 命令默认最多运行 5 秒(timeout_ms),默认每 5 分钟重新取一次(refresh_interval_ms)。
  • sh -c 适用于 macOS、Linux 和 CI 的 Linux 环境。Windows 本机日常使用,直接用上面的 config.toml 写法更省事。

用 cron 每天定时跑 codex exec 的完整例子见《一个 cron + codex exec 每天自动出 GitHub Trending》,自动化场景的权限设置见《Codex 自动化权限配置》。

哪些环境变量真正有用

变量作用什么时候需要
HTTPS_PROXY / HTTP_PROXY让 Codex 的网络请求走代理本机访问外网需要代理时
NO_PROXY指定不走代理的地址某些地址要直连时
CODEX_CA_CERTIFICATE指定公司根证书(PEM)公司网络有 TLS 代理、报证书错误时
SSL_CERT_FILE通用证书路径,没设 CODEX_CA_CERTIFICATE 时使用同上
CODEX_HOMECodex 配置和本地数据的目录,默认 ~/.codex一台机器要放两套配置时
自己起名的 Key 变量配合 auth.command 给 Codex 提供 KeyCI、容器、密钥管理器

OPENAI_API_KEY 和 OPENAI_BASE_URL 不在这张表里:用本站时,这两个变量既不需要,也不会改变请求去向,下文有实测。

代理:HTTPS_PROXY 和 NO_PROXY

Codex 发往 https://api.aicodewith.ai 的请求会读取 HTTPS_PROXY。我们在本机起了一个会记录连接目标的代理,再分两次运行 codex exec:

设置结果代理日志里的 api.aicodewith.ai
HTTPS_PROXY=http://127.0.0.1:188883.10 秒返回 OK有 1 条 CONNECT
再加 NO_PROXY=api.aicodewith.ai4.23 秒返回 OK没有,改为直连

两次的代理日志里还都出现了 chatgpt.com、ab.chatgpt.com 和 github.com 的连接,它们不是模型对话请求,NO_PROXY 只让你列出的地址直连。所以如果你的代理软件只放行部分域名,看到这几个地址失败也不影响和 AI Code With 的对话;如果对话请求本身连不上,先检查代理地址和端口。

下面是三个系统的设置方法。代理地址和端口以你本机代理软件显示的为准,127.0.0.1:7890 只是示例。

macOS

macOS 默认 shell 是 zsh。只对当前终端生效:

bash
export HTTPS_PROXY="http://127.0.0.1:7890"
codex

想每个新终端都自动生效,写进 ~/.zshrc,再让当前终端重新加载:

bash
echo 'export HTTPS_PROXY="http://127.0.0.1:7890"' >> ~/.zshrc
source ~/.zshrc

不想要了就清除当前终端里的值;写进 ~/.zshrc 的那一行也要手动删掉,否则新终端还会加载:

bash
unset HTTPS_PROXY

Linux

临时设置和清除的命令和 macOS 一样。大多数发行版默认用 bash,永久保存写进 ~/.bashrc:

bash
echo 'export HTTPS_PROXY="http://127.0.0.1:7890"' >> ~/.bashrc
source ~/.bashrc

通过 systemd、cron 运行 codex exec 时,这些场景不一定读取 ~/.bashrc,需要在服务或脚本里显式设置变量。接入配置写在 config.toml 里,这类后台任务能直接读到,不用额外传 Key。

Windows

只对当前 PowerShell 窗口生效:

powershell
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
codex

永久保存到当前用户。已经打开的窗口不会生效,要关掉 PowerShell、VS Code 等程序后重新打开:

powershell
[Environment]::SetEnvironmentVariable('HTTPS_PROXY', 'http://127.0.0.1:7890', 'User')

清除时,第一条只清当前窗口,第二条删除永久保存的值:

powershell
Remove-Item Env:HTTPS_PROXY
[Environment]::SetEnvironmentVariable('HTTPS_PROXY', $null, 'User')

在 VS Code 里用 Codex 插件的 Windows 用户,代理和登录的排错见《Codex VS Code 怎么用》。

CODEX_HOME:一台机器放两套配置

CODEX_HOME 决定 Codex 去哪个目录找 config.toml、auth.json 和本地记录,默认是 ~/.codex。日常接入 AI Code With 不需要改它。

它适合的场景是:同一台机器要保留两套完全独立的配置,比如个人和公司各一套,或者 CI 里想把配置放在工作目录下。用法是启动前指向另一个目录:

bash
mkdir -p ~/codex-work
# 在 ~/codex-work/config.toml 里写另一套配置
CODEX_HOME=~/codex-work codex

实测结果:~/.codex/config.toml 指向记录服务 A,CODEX_HOME 目录里的 config.toml 指向记录服务 B。设了 CODEX_HOME 之后,请求全部发到 B,带的也是 B 那份配置里的 Key,~/.codex 里的配置完全没被读取。

反过来,这也是最常见的「明明改了 config.toml 却不生效」的原因之一:终端里残留了一个 CODEX_HOME,Codex 根本没读你改的那个文件。用 echo $CODEX_HOME 检查,空的才是默认目录。只是想在一个目录里切换模型或 Key,用 Profile 更轻,见《Codex 多项目怎么管理》。

环境变量和 config.toml 冲突时谁生效

很多人以前设过 OPENAI_API_KEY 或 OPENAI_BASE_URL,改成 config.toml 写法后担心互相打架。我们在 0.167.0 上把它们同时设上,看 Codex 实际发出的请求:

同时存在实际生效的
环境变量 OPENAI_API_KEY + config.toml 里的 experimental_bearer_tokenconfig.toml 里的 Key,环境变量被忽略
环境变量 OPENAI_BASE_URL + config.toml 里的 base_urlconfig.toml 里的地址,环境变量指向的地址收不到请求
auth.json 里的 Key,但没写 requires_openai_auth = true都不生效,请求不带 Key
环境变量 CODEX_HOME + ~/.codex/config.tomlCODEX_HOME 目录里的配置
项目里的 .codex/config.toml 改 model_providers被忽略,仍用全局配置

结论:model_provider 指向 aicodewith 时,以全局 config.toml 为准。旧的 OPENAI_API_KEY、OPENAI_BASE_URL 留着不会干扰,但为了以后排查省事,建议清掉。

最后一行单独说明一下。很多人想「每个项目用自己的 Key」,于是在仓库里放一个 .codex/config.toml 改 Provider。0.167.0 会直接跳过这部分,输出的原文是:

text
warning: Ignored unsupported project-local config keys in /path/to/repo/.codex/config.toml: model_providers. If you want these settings to apply, manually set them in your user-level config.toml.

即使把这个项目标记为受信任,结果也一样。地址和 Key 只能写在全局 config.toml(或 CODEX_HOME 指向的目录)里,项目级配置适合放模型、推理强度这类设置。这样也避免了把 Key 提交进仓库。

创建 API Key →

别让 Codex 运行的命令读到你的密钥

Codex 执行命令时,会把环境变量传给这些命令。很多人以为名字里带 KEY、SECRET、TOKEN 的变量会被自动过滤,0.167.0 默认并不会。我们在终端里设了 DEMO_API_KEY、DEMO_SECRET、DEMO_TOKEN、DEMO_COLOR 四个变量,让 Codex 运行 env | grep '^DEMO_':

shell_environment_policy 设置命令能看到的变量
不写(默认)四个全都能看到
ignore_default_excludes = false只剩 DEMO_COLOR
inherit = "core" + ignore_default_excludes = false一个都看不到

想过滤名字里带 KEY、SECRET、TOKEN 的变量,在 config.toml 里加:

toml
[shell_environment_policy]
ignore_default_excludes = false

想再收紧一点,只给命令一组基础变量(如 PATH、HOME),再按需补:

toml
[shell_environment_policy]
inherit = "core"
ignore_default_excludes = false
set = { NODE_ENV = "development" }

[shell_environment_policy.filters]
"AWS_*" = "exclude"

filters 的匹配不区分大小写,支持 * 和 ?。这里过滤的只是 Codex 运行的命令能看到的变量,不影响 Codex 自己读取 HTTPS_PROXY、CODEX_HOME,也不影响上面 auth.command 读 Key。更多安全设置见《Codex 沙盒与权限》。

排错

报 401:请在请求中提供有效的 API Key

直接按顺序检查这四项,大多数情况第一、二项就能解决:

  1. 用 experimental_bearer_token 写法的,确认引号里是完整的 Key,前后没有空格。
  2. 用 auth.json 写法的,确认 config.toml 里有 requires_openai_auth = true。
  3. 确认 model_provider = "aicodewith" 写在文件最上面,不在任何 [ ] 小节下面。
  4. Key 被删除或失效的,去控制台重新创建一个。

这次在 0.167.0 上,用了 auth.json 却没加 requires_openai_auth = true 时,Codex 先重连 5 次(约 7 秒),然后输出:

text
ERROR: unexpected status 401 Unauthorized: {"error":"请在请求中提供有效的 API Key。"}, url: https://api.aicodewith.ai/chatgpt/v1/responses

Key 填错或已经失效,也是同一条报错。更多 401 的情况见《Codex 401 Unauthorized 怎么解决》;如果报的是 429,见《Codex 429 Too Many Requests 怎么解决》。

改完不生效:先查三件事

  1. 重开终端:环境变量只在启动时读取一次。改了 ~/.zshrc、~/.bashrc 或 Windows 用户变量,已经打开的终端和编辑器拿不到新值。在 VS Code 等编辑器里用 Codex 的,要完全退出编辑器再打开,只关内置终端不够。
  2. 查 CODEX_HOME:echo $CODEX_HOME(PowerShell 用 $env:CODEX_HOME)。有值就说明 Codex 读的是那个目录里的 config.toml。
  3. 查配置是不是写在项目里:写在仓库 .codex/config.toml 里的 Provider 设置会被忽略,看启动时有没有 Ignored unsupported project-local config keys 的提示。

一条命令看清当前终端里和 Codex 相关的变量:

bash
env | grep -iE 'proxy|codex|openai|ssl_cert'
powershell
Get-ChildItem Env: | Where-Object Name -match 'PROXY|CODEX|OPENAI|SSL_CERT'

公司网络报证书错误

设置 CODEX_CA_CERTIFICATE 指向公司提供的 PEM 根证书,再启动 codex:

bash
export CODEX_CA_CERTIFICATE="/path/to/company-root.pem"

Windows 上用 $env:CODEX_CA_CERTIFICATE = 'C:\path\company-root.pem'。没设它时 Codex 会使用 SSL_CERT_FILE。

连不上或很久没有回应

先确认 HTTPS_PROXY 的地址和端口和代理软件一致,再用 NO_PROXY 排除不该走代理的地址。超时问题分几种,见《Codex timeout 怎么排查》;国内网络环境的完整说明见《国内使用 Codex》。

常见问题

用 AI Code With 还要设置 OPENAI_API_KEY 环境变量吗?

不用。Key 写在 config.toml 的 experimental_bearer_token 里,或者放进 auth.json 并加 requires_openai_auth = true,二选一即可。实测中,model_provider 指向 aicodewith 时,环境变量 OPENAI_API_KEY 会被忽略。

我只想把 Key 放在环境变量里,可以吗?

可以,用 auth.command 让 Codex 运行 printf %s "$ACW_API_KEY" 取 Key,config.toml 里不出现 Key,适合 CI 和容器。

experimental_bearer_token 和 auth.json 选哪个?

推荐 experimental_bearer_token,地址和 Key 都在一个文件里,少一个出错点。如果你已经按控制台教程用了 auth.json,也可以继续用,记得 config.toml 里要有 requires_openai_auth = true。

设了 OPENAI_BASE_URL 会把请求发到别的地址吗?

不会。实测中,config.toml 里写了 base_url 时,OPENAI_BASE_URL 指向的地址一个请求都没收到。

能不能每个项目用不同的 Key?

不能靠项目里的 .codex/config.toml,Provider 设置会被忽略。可以用 CODEX_HOME 指向不同目录,或者在全局配置里用 Profile 切换,见《Codex 多项目怎么管理》。

Codex 运行的命令会读到我终端里的密钥吗?

默认会。在 config.toml 里加 [shell_environment_policy] 和 ignore_default_excludes = false,名字带 KEY、SECRET、TOKEN 的变量就不会再传给命令。

换了 Key 为什么还在用旧的?

先看 config.toml 或 auth.json 里是不是已经换成新 Key,再检查 CODEX_HOME 有没有指向别的目录,最后重开终端或编辑器重新启动 codex。

用 Codex、Claude Code 或 Cursor 都可以用同一个 AI Code With 账号,先拿一个 Key 按上面的写法配好:

创建 API Key →

相关阅读

资料来源

相关文章

UI SDK 是什么、怎么用?Vercel + shadcn 给 Agent 的行为库,在 Claude Code / Codex / Cursor 里安装与实测(0.1.0-beta.1)

UI SDK 是什么、怎么用?Vercel + shadcn 给 Agent 的行为库,在 Claude Code / Codex / Cursor 里安装与实测(0.1.0-beta.1)

UI SDK 是 Vercel 在 2026 年 11 月 12 日发布的、给 Agent 用的行为(behaviors)库,版本 0.1.0-beta.1。行为写在与框架无关的 @ui-sdk/core 里,再由 React、Vue、Svelte、Solid 和 Web Components 适配器渲染。本文按官方文档整理它是什么、怎么安装、怎么给 Claude Code / Codex / Cursor 装 skill,并记录我们在测试机上的真实命令、耗时和输出。

AWS Emulator 是什么、怎么装?让 Claude Code / Codex 在本地测 AWS 应用(1.0.322 实测)

AWS Emulator 是什么、怎么装?让 Claude Code / Codex 在本地测 AWS 应用(1.0.322 实测)

AWS Emulator 是 AWS 官方 2026 年 11 月 12 日(北京时间)正式发布的本地 AWS 模拟器,没有额外服务费、源码开放,不需要 AWS 账号,覆盖 200 多个服务。本文在 Debian 13 上实测 1.0.322:安装命令、AWS CLI 指向本地 endpoint 建 S3 桶和 DynamoDB 表、常见报错,以及让 Claude Code、Codex、Cursor 对着模拟器写代码跑测试的接法。

T3 Code 是什么、怎么装?接入 Claude Code 和 Codex、配置第三方 API Key 与常见报错(0.1.9 实测)

T3 Code 是什么、怎么装?接入 Claude Code 和 Codex、配置第三方 API Key 与常见报错(0.1.9 实测)

T3 Code 是 pingdotgg 开源的编码 Agent 控制台,本身不带模型,调用你机器上已装好的 Claude Code、Codex、Cursor 等 CLI。本文在 Linux 上实测 T3 Code 0.1.9:讲清安装命令,Claude Code 和 Codex 先各自接上 AICodeWith API Key、再由 T3 Code 调用的配置方法,用 t3 thread 命令行跑通两端的过程,以及我们实际遇到的报错和解法。