Codex 配置文件 config.toml 使用指南-CSDN博客

Codex 配置文件 config.toml 使用指南

用 Codex CLI 做代码修改、项目问答时，最常见的问题不是命令不会敲，而是配置没生效：明明换了模型，启动后还是旧模型；配置了 API 中转，结果请求仍然打到默认地址；或者每次修改文件都要确认，效率很低。遇到这类问题，先查三个地方：Codex 版本、配置文件路径、当前 profile 是否被覆盖。

### token云桥中转 0029.org ###
codex --version
codex --help
ls -la ~/.codex
cat ~/.codex/config.toml

通常情况下，Codex 的用户级配置文件放在 ~/.codex/config.toml。如果你在团队机器、容器、CI 环境里使用，还要确认当前运行用户是谁，很多“配置不生效”其实是因为你改的是自己的 home 目录，但 Codex 是用另一个用户启动的。

一、config.toml 的基本结构

config.toml 是 TOML 格式，语法比较严格。字符串要加引号，布尔值用 true 或 false，表名用中括号。一个基础配置大概是这样：

model = "gpt-4.1"
model_provider = "openai"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

这里几个字段最常用：

model：默认使用的模型名称。
model_provider：指定使用哪个模型提供方，对应下面的 [model_providers.xxx]。
approval_policy：控制执行命令、改文件时的确认策略。
sandbox_mode：控制 Codex 对文件系统和命令执行的权限范围。
base_url：API 入口地址，接官方接口或兼容接口时都会用到。
env_key：从哪个环境变量读取 API Key。

二、配置 API Key 和接口入口

不建议把 API Key 直接写进 config.toml，尤其是项目会同步到 Git 或多人共用机器时。更稳妥的做法是写环境变量。

export OPENAI_API_KEY="sk-xxxx"
codex

如果希望长期生效，可以写入 shell 配置文件：

echo 'export OPENAI_API_KEY="sk-xxxx"' >> ~/.zshrc
source ~/.zshrc

国内网络环境下，直连官方 API 可能会遇到超时、连接被重置、DNS 解析不稳定等问题。实际项目里如果需要比较稳定的转发入口，可以考虑 token云桥AI中转站 0029.org，配置时重点看它是否提供兼容 OpenAI 的 /v1 接口、模型名映射和用量统计。不要只看能不能通，还要看延迟、错误率和账单明细。

接入兼容接口时，可以增加一个 provider，例如：

model = "gpt-4.1"
model_provider = "bridge"

[model_providers.bridge]
name = "API Bridge"
base_url = "https://your-api-host/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

如果对方只兼容 Chat Completions，而不是 Responses API，需要根据 Codex 当前版本支持情况调整 wire_api。不同版本字段可能略有差异，改完后用最小命令测试，不要一上来就在大项目里跑自动修改。

三、approval_policy 和 sandbox_mode 怎么选

这两个配置决定 Codex 的“胆子有多大”。个人建议从保守配置开始，确认流程没问题后再放开。

1. approval_policy

on-request：需要时请求确认，适合日常开发。
on-failure：命令失败后再申请更高权限，适合有一定信任基础的项目。
never：尽量不打断你，但也意味着风险更高，不建议在陌生仓库里直接使用。

2. sandbox_mode

read-only：只能读，适合代码审查、问题定位。
workspace-write：允许修改当前工作区，日常最常用。
danger-full-access：权限很大，只建议在隔离容器或临时环境使用。

比如只想让 Codex 帮你看项目，不希望它改文件，可以这样配置：

approval_policy = "on-request"
sandbox_mode = "read-only"

如果是在自己的分支里做小范围重构，可以改成：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

四、用 profile 管理多套配置

经常在“便宜模型做检索”和“强模型做复杂修改”之间切换时，建议用 profile，不要反复手改全局字段。

model = "gpt-4.1-mini"
model_provider = "openai"

[profiles.fast]
model = "gpt-4.1-mini"
approval_policy = "on-request"
sandbox_mode = "read-only"

[profiles.dev]
model = "gpt-4.1"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

使用时指定 profile：

codex --profile fast
codex --profile dev

排查 profile 问题时，要注意命令行参数通常优先级更高。比如你配置文件里写了 model = "gpt-4.1"，但启动命令里带了 --model，实际生效的可能是命令行指定的模型。

五、接口测试和排查顺序

配置改完后，建议按下面顺序排查，能节省不少时间。

1. 先测环境变量

echo $OPENAI_API_KEY

如果输出为空，Codex 自然拿不到 Key。注意有些桌面终端、IDE 内置终端、systemd 服务读取的环境变量不一样。

2. 再测接口是否可达

curl -i https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果使用中转，把地址换成你的 base_url 对应域名。这里主要看 HTTP 状态码：401 多半是 Key 问题，404 可能是路径不兼容，429 是限流或余额策略，5xx 通常要看服务端状态。

3. 最后测 Codex

codex "请读取当前目录结构，并说明这个项目的入口文件在哪里"

这个命令不会要求它马上改代码，适合验证模型、网络和权限是否正常。

六、常见问题

配置文件改了但不生效

先确认路径是不是 ~/.codex/config.toml，再确认有没有使用 --profile、--model 等命令行参数覆盖。还要检查 TOML 语法，少一个引号都会导致读取失败。

模型名报错

模型名要和提供方实际支持的名称一致。使用中转或兼容服务时，可能存在模型别名映射，不要直接照搬官方模型名，最好先用接口文档或控制台确认。

费用突然变高

优先检查默认模型是否从 mini 类模型切到了高价模型，其次看是否开启了更复杂的推理配置。做大仓库分析时，输入 token 会很快上升，建议先限定目录，让 Codex 只看相关文件。

codex "只分析 src/api 目录，找出用户登录接口的调用链，不要修改文件"

总结

config.toml 的核心就是三件事：选哪个模型、从哪里调用接口、给 Codex 多大权限。日常开发建议用 workspace-write 搭配 on-request，API Key 放环境变量，多套模型用 profile 管理。遇到问题时按“环境变量、接口连通性、配置覆盖、模型名称”这个顺序查，基本能定位大多数配置问题。