Codex config.toml / auth.json 配置完全指南（Codex 桌面端最新版）

主关键词：codex config.toml、codex auth.json、codex 配置文件、codex 怎么配置、codex gpt-5.5、codex 配置

一、为什么配置文件总是配错

上周在技术群看到有人问：「Codex 装好了一直 Reconnecting 1/5，是哪里配错了？」我让他贴一下 ~/.codex/config.toml 的内容，发现 5 个字段里有 3 个用了老教程里写过但新版已经废弃/重命名的字段——比如 provider、base_url。

Codex 的配置文件体系对新人不太友好，原因有三：

• 配置文件分散在两个文件：config.toml（行为配置）和 auth.json（认证配置）
• 字段名严格区分大小写：model_provider 写错成 modelProvider 或 model-provider 都直接报错
• profiles 已独立成单独文件：config.toml 里只放全局行为，所有 profiles.xxx（开发档案 / 远程环境）都迁到了 config.toml 同目录的独立 .toml 文件，老教程照搬会报 unknown field

这篇就把这两个文件讲透，并给出完整的 Mac / Windows 双平台配置示例。文末会介绍一种不需要手写 config.toml 的替代路径——如果你只是想「装上就用」，可以直接跳到最后一节。

1.1 两个文件的分工

文件	控制什么	关键字段
config.toml	Codex 怎么工作	model、model_provider、openai_base_url、approval_policy、sandbox_mode
auth.json	Codex 用哪个账号调用 API	API key 登录：单字段 api_key；ChatGPT 登录：嵌套 tokens

两者必须配套，缺一个就报 unconfigured。

1.2 双平台路径

平台	config.toml	auth.json
macOS / Linux	~/.codex/config.toml	~/.codex/auth.json
Windows	%USERPROFILE%\.codex\config.toml	%USERPROFILE%\.codex\auth.json
自定义（任意平台）	$CODEX_HOME/config.toml	$CODEX_HOME/auth.json

Windows 下 PowerShell 等价命令：$env:USERPROFILE\.codex\config.toml。

---

二、config.toml 完整字段说明

下面是一份生产可用的 config.toml 模板，每个字段都加了注释。请注意新版字段命名：

# 默认使用的模型。Codex 桌面端最新默认 gpt-5.5（早期版本默认 gpt-5-codex）
# 也可以写 "gpt-5" / "o4-mini" 等，看你订阅档位覆盖哪些
model = "gpt-5.5"

# 模型提供方（不是 "provider"）。Codex 自带三个内置 provider：
#   - "openai"        → 直连 OpenAI 官方 API
#   - "openai-chatgpt" → 用 ChatGPT 登录态调用（默认走 OAuth）
#   - 你也可以自定义 provider，见下方「自定义 provider」一节
model_provider = "openai"

# OpenAI 兼容网关地址。注意这是顶级 openai_base_url，不是 base_url
# 默认留空走 https://api.openai.com/v1
# 如果用第三方 OpenAI 兼容网关，改这里
openai_base_url = "https://api.openai.com/v1"

# 命令执行审批策略。可选值：
#   "untrusted"   → 危险操作全部拒绝（最严）
#   "on-request"  → 每次命令前问你（推荐）
#   "never"       → 直接执行，不问（最危险，慎用）
#   "granular"    → 按 sandbox 级别授权
approval_policy = "on-request"

# 沙箱模式。可选值：
#   "workspace-write"    → 只能写当前工作区（推荐）
#   "danger-full-access" → 完全访问（仅调试用）
sandbox_mode = "workspace-write"

# 是否在任务完成时发桌面通知
notify = true

# 启动时检查更新
check_for_update_on_startup = true

# 历史记录最大 token 数（影响上下文窗口）
history_max_chars = 50000

版本断点：旧版桌面端教程里常见字段名是 provider 和 base_url。新版这两个名字都不存在——必须是 model_provider 和 openai_base_url，否则直接报 unknown field。

2.1 自定义 model_provider（接入第三方网关）

如果你用第三方 OpenAI 兼容网关，需要在 config.toml 里新增一个 provider 配置块：

# 默认 provider 改成 "third-party-gateway"（中性命名，不要用品牌名）
model_provider = "third-party-gateway"

# 自定义 provider 必须放在 [model_providers.<id>] 表里
# 注意这里是复数 model_providers，不是单数 model_provider
[model_providers.third-party-gateway]
# 关键字段：base_url 在这里（provider 块里），不是顶级
base_url = "https://your-gateway.example.com/v1"
# 这个 provider 用的协议族，必须是 openai 兼容
wire_api = "openai"
# 请求头（如果网关需要特殊 header 才填，否则可以删）
http_headers = { "X-Subscription-Tier" = "pro" }

# 如果这个 provider 支持多模型，可以列出来给 Tab 补全用
[model_providers.third-party-gateway.models]
gpt-5.5 = { name = "gpt-5.5" }
gpt-5 = { name = "gpt-5" }

2.2 profiles：新版的迁移

老教程经常这么写（已经废弃）：

# ❌ 新版失效
[profiles.work]
model = "gpt-5.5"
approval_policy = "on-request"

新版本必须这么做：

# 每个 profile 一个独立文件
# 路径 ~/.codex/<profile-name>.config.toml

例如 ~/.codex/work.config.toml：

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

然后在桌面端启动时用 --profile work 指定。老教程里的 [profiles.work] 写法直接报 unknown field profiles。

---

三、auth.json 完整结构说明

auth.json 在新版有两种完全不同的结构，取决于你的登录方式。

3.1 API Key 登录（最简单）

适合：自己有 OpenAI API Key，或用第三方兼容 key。

{
  "api_key": "sk-proj-REPLACE_WITH_YOUR_KEY"
}

字段说明：

• api_key：OpenAI 项目 key（sk-proj-… 开头）或用户 key（sk-… 开头）。项目 key 计费归属 project，用户 key 归属 user（legacy），Codex 端不区分前缀

⚠️ 安全提示：auth.json 权限必须设成 600（仅当前用户可读写），否则 Codex 启动时会拒绝加载。

# macOS / Linux
chmod 600 ~/.codex/auth.json

# Windows（PowerShell）
icacls "$env:USERPROFILE\.codex\auth.json" /inheritance:r /grant:r "$env:USERNAME:(R,W)"

3.2 ChatGPT 登录（OAuth）

适合：用 ChatGPT Plus / Pro 订阅登录 Codex。

{
  "tokens": {
    "id_token": "eyJhbGciOiJSUzI1NiIs...",
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "rt_58G...",
    "account_id": "user_abc123"
  }
}

字段说明：

• id_token：JWT 格式，包含用户身份信息
• access_token：调用 API 用的短期凭证（通常 1 小时过期）
• refresh_token：用来换新的 access_token（有效期长一些）
• account_id：用户 ID，OpenAI 用它做审计

通常你不需要手写这个文件——codex login 命令会自动生成。

3.3 环境变量替代

不想写 auth.json？可以直接设环境变量，Codex 启动时会自动识别：

# macOS / Linux（也适用于 WSL）
export OPENAI_API_KEY="sk-proj-..."

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-proj-..."

3.4 常见 auth.json 错误对照表

现象	真实原因	修正
auth file not found	文件路径错	检查 ~/.codex/auth.json 是否存在
auth file mode is too permissive	权限不是 600	chmod 600 ~/.codex/auth.json
OPENAI_API_KEY invalid	key 被删或填错	重新从 dashboard 复制
tokens.expired	OAuth token 过期	跑 codex login 重新登录
同时写了 OPENAI_API_KEY 和 api_key 字段	二选一即可	删掉一个

---

四、Mac 完整配置流程

# 1. 创建配置目录
mkdir -p ~/.codex

# 2. 写 config.toml
cat > ~/.codex/config.toml <<'EOF'
model = "gpt-5.5"
model_provider = "openai"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
notify = true
EOF

# 3. 写 auth.json
cat > ~/.codex/auth.json <<'EOF'
{
  "api_key": "sk-proj-REPLACE_WITH_YOUR_KEY"
}
EOF

# 4. 收紧权限
chmod 600 ~/.codex/auth.json
chmod 644 ~/.codex/config.toml

# 5. 验证
codex --version
codex /status

---

五、Windows 完整配置流程（PowerShell）

# 1. 创建配置目录
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex"

# 2. 写 config.toml
@'
model = "gpt-5.5"
model_provider = "openai"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
notify = true
'@ | Set-Content -Path "$env:USERPROFILE\.codex\config.toml" -Encoding UTF8

# 3. 写 auth.json
@'
{
  "api_key": "sk-proj-REPLACE_WITH_YOUR_KEY"
}
'@ | Set-Content -Path "$env:USERPROFILE\.codex\auth.json" -Encoding UTF8

# 4. 收紧权限
icacls "$env:USERPROFILE\.codex\auth.json" /inheritance:r /grant:r "$env:USERNAME:(R,W)"

# 5. 验证
codex --version
codex /status

---

六、/status 命令看什么

按官方 Slash Commands 文档，/status 在 Codex 桌面端里是内置命令，输出当前会话配置 + token 用量，包括：

• active model：当前会话用的模型
• approval policy：审批策略（on-request / untrusted / …）
• writable roots：沙箱允许写的目录
• current token usage：已消耗 / 上限
• （远程连接时附加）远端地址 + 服务端版本

在 Codex TUI 里按 /status 回车即可看到。没有 Model: Account: 这种字段名，看到像这样的回显通常是其它工具的输出。

配置加载成功后，/status 输出里 active model 应该跟你 config.toml 里 model = "..." 一致；不一致就是某个字段没读进去。

---

七、懒人路径：不想手写 config.toml 怎么办

写到这里，我自己得坦白一个事实：上面这些 config.toml 和 auth.json 配置，我过去 1 年调过不下 30 次。每次 Codex 大版本更新（尤其是 profiles 字段那次迁移），路径和字段名都会变，新人根本记不住。

如果你不想维护配置文件，市面上有三种替代路径，各有适用场景：

路径 A：保持手写 + 写完备份

把 config.toml 和 auth.json 备份到云笔记（或 dotfiles 仓库的加密分区），Codex 升级后只改增量字段。我自己前期用的就是这个方案，缺点是每次升级要排查 changelog。

路径 B：用第三方 OpenAI 兼容网关 + 手写 config.toml

OpenAI 兼容网关的好处是 base_url 和 API Key 都由网关服务提供，你只需要把 §2.1 那段 model_providers.<id> 块填到 config.toml 里即可，配置文件主体（approval_policy / sandbox_mode / notify）仍然由你控制。选网关时建议看 3 点：是否明示上游官方渠道、是否提供按量计费账单、是否有公开文档。缺点是多一道网络跳，出错时多排查一层。

路径 C：用图形界面客户端

Codex 官方目前只有命令行版（CLI），没有官方桌面 GUI。市面上有几款第三方增强客户端（GitHub 上能搜到 codex desktop / codex gui 类项目）把 config.toml 的字段映射成 UI 里的"模型下拉框 / 订阅档位 / 工作区设置"。好处是不用记字段名，坏处是依赖第三方客户端的字段映射是否准确，碰到 Codex 升级可能滞后。这条路径对纯命令行苦手（设计师 / 文案 / 学生）比较友好。

我现在的标准流程是路径 A + 偶尔用路径 B 做测试环境，配置文件多维护一份 macOS 备份 + Windows 备份，跨机同步靠 iCloud 私有目录。

---

八、FAQ

Q1：config.toml 用 provider 还是 model_provider？

A：model_provider。provider 在新版是无效字段名，写了会报 unknown field provider。

Q2：API Key 哪里申请？

A：在 platform.openai.com/api-keys 创建项目 key，会得到 sk-proj-... 字符串（项目 key）或 sk-... 字符串（用户 key）。Codex 端不区分前缀。

Q3：想把 openai_base_url 改成第三方网关地址，怎么填？

A：顶级字段 openai_base_url = "https://你的网关地址/v1"，或者走更稳的自定义 model_providers.<id> 块写法（见 §2.1），<id> 是任意名字。

Q4：为什么我改完 config.toml 后 /status 显示的还是旧模型？

A：Codex 启动时一次性读取配置，改完需要重启 TUI。如果重启后还不对，检查 TOML 语法（特别注意引号是 " 不是 “ ”）。

Q5：auth.json 默认会被 git 跟踪吗？

A：默认不会，~/.codex/ 在用户目录下，不在项目目录里。但如果你的工作流是 dotfiles 仓库，要把 auth.json 加进 .gitignore，只把 config.toml 提交。

---

参考资料

• Codex Config basics（OpenAI 官方）
• Codex Config Reference（OpenAI 官方）
• Slash Commands 文档
• Codex 官方文档（桌面端）
• DeepWiki: Authentication modes & account management
• Codex config.toml 配置说明（含 8 个常见错配图示）

---

作者：周逸凡 · 2026-07-03 首发于 CSDN
最后更新：2026-07-03（基于 Codex 桌面端最新稳定版；如版本更新请以官方文档为准）