Codex config.toml 怎么配置？.codex 文件夹、自定义接口与权限设置
用 Codex（命令行、桌面端或编辑器扩展）时，几乎所有个性化设置都集中在一个文件里：config.toml。想换模型、接第三方接口、调整审批和沙箱，都要碰它。这篇把位置、层级、常用项和排错顺序一次讲清。
配置文件只决定「Codex 怎么运行、请求发到哪里」，不会给账号增加权益，也不会让某个接口自动支持它没有的能力。不同版本支持的配置项会变化，下面的写法以你本机 codex --help 和 OpenAI 官方 Codex 文档 为准。
config.toml 放在哪#
| 位置 | 常见路径 | 作用范围 | 适合放什么 |
|---|---|---|---|
| 全局配置 | ~/.codex/config.toml（Windows 是 %USERPROFILE%\.codex\config.toml） | 这个用户的所有项目 | 默认模型、审批和沙箱偏好、常用接口 |
| 项目配置 | 仓库里的 .codex/config.toml | 仅当前项目 | 只对这个仓库有效的约定，提交前检查有没有敏感信息 |
| 环境变量 | 如 CODEX_HOME、接口密钥变量 | 当前进程或用户环境 | 切换配置目录、保存密钥 |
如果设置过环境变量 CODEX_HOME，配置目录就不再是默认的 ~/.codex。改了配置却没反应，先确认你改的是不是实际生效的那个目录。
一个安全的起步配置#
# ~/.codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"这两行的意思是：默认只在工作区内写文件，需要越界或执行有风险的命令时再询问你。刚开始用，保持这个最小配置就够了，不要照抄网上的「万能配置」。
接入自定义接口（第三方 API 或中转站）#
Codex 允许声明自己的「模型供应商」。以鹊桥为例：
model_provider = "queqiao"
model = "你的分组内的模型名"
[model_providers.queqiao]
name = "queqiao"
base_url = "https://cdn.5202828.xyz/v1"
env_key = "QUEQIAO_API_KEY"
wire_api = "responses"三个关键字段：
base_url：接口的根地址。OpenAI 系客户端通常要带/v1；填成网站首页或登录页是不行的。env_key：只写环境变量的名字，不要把sk-开头的密钥直接写进文件。然后在系统里设置同名环境变量。wire_api：接口协议，要和服务端一致。如果服务端只实现了旧的 Chat Completions，客户端却按 Responses 协议发请求，常见现象是 400 或 404。
设置好环境变量后，彻底退出并重新打开客户端才会生效。Windows 上注意右下角托盘里的进程。
用 CC Switch 导入，它会替你写好这些配置，见 CC Switch 是什么？一键配置 Claude Code、Codex 与 DeepSeek Harness。
权限和沙箱：先理解，再放宽#
审批和沙箱决定 Codex 能不能读写文件、跑命令、联网。配得越宽，出事的影响面越大。建议这样用：
- 先在练习仓库里试，不要直接在生产目录或用户主目录启动。
- 保持「工作区可写」，先看它准备改哪些文件。
- 命令被拒绝时，看清路径和原因，再决定要不要放行。
- 只给当前任务需要的权限，做完检查 Git diff。
- 不要接受陌生仓库自带的高权限项目配置，把
.codex/config.toml当成代码来审查。
配置不生效，按这个顺序查#
| 现象 | 常见原因 | 怎么办 |
|---|---|---|
| 改了没变化 | 改错目录，或 CODEX_HOME 指向别处 | 检查环境变量，确认文件实际位置 |
| 启动时报 TOML 解析错误 | 引号、缩进或键名不符合当前版本 | 缩减成最小配置，再逐行加回来 |
| 找不到供应商 | model_provider 和 [model_providers.xxx] 的名字对不上 | 两处名字保持完全一致 |
| 401 / 403 | 密钥无效，或环境变量没设置到客户端进程里 | 重新设置变量并重启客户端 |
| 400 / 404 | base_url、/v1 或 wire_api 不匹配 | 对照服务文档，看请求路径和协议 |
| 写文件被拦截 | 沙箱或审批策略限制 | 缩小任务范围，按提示逐次授权 |
可以先跑 codex --version 和 codex --help 确认版本与可用参数。新版本里还有 codex doctor 用来做环境诊断，是否可用以你的版本为准。分享日志之前，先删掉邮箱、路径、请求头和密钥。
常见问题#
.codex 文件夹能直接删掉吗？#
不建议把「删整个 .codex」当成通用修复。里面可能有配置、日志和登录状态，删了既丢排错线索，也未必解决网络或版本问题。更稳妥的做法是：先备份，只改名或移走明确相关的那个配置文件，重启后用一个小任务验证。
项目里的 .codex 能提交到 GitHub 吗？#
提交前一定检查：没有密钥，没有本地路径，没有登录状态相关内容。不确定就加进 .gitignore。
配置写错会影响所有项目吗？#
全局配置会影响这个用户下的多个项目；项目配置通常只影响所在仓库。改之前先备份，出现解析错误时把文件临时改名，确认是不是它导致的。
我只用官方账号，需要写供应商吗？#
通常不需要。供应商配置是给要接自定义 API 网关的人用的。