Codex config.toml 配置详解：常用配置项
2026-08-22 14:30:28阅读 5
Codex 的默认行为很好用，但它不是"定死的"——通过配置文件可以改模型、调权限、加钩子。这一篇讲清配置文件在哪、长什么样、最常用的配置项是什么，先会改，再谈精通。
配置文件在哪
Codex 的主目录默认是 ~/.codex（可用 CODEX_HOME 环境变量改）。核心配置文件：
~/.codex/config.toml # 主配置
~/.codex/config.toml.example # 官方示例（第一次装可能就有）官方把配置文档拆成三档（按需阅读）：
| 档位 | 内容 |
|---|---|
| 配置基础 | 最常用的设置，新手够用 |
| 高级配置 | 更细的调优项 |
| 配置参考 | 全字段速查（写配置时翻） |
最常用的配置项（先会这几个）
# 默认模型
model = "gpt-5.6"
# 模型提供商设置（自建/第三方端点时用）
[model_providers.xxx]
name = "xxx"
base_url = "https://..."
env_key = "xxx_API_KEY"
# 权限模式
sandbox_mode = "read-only" # read-only / workspace-write / danger-full-access
# 网络
network_access = true # 是否允许 Codex 联网新手最值得改的：
| 配置 | 默认 | 改什么 |
|---|---|---|
model | gpt-5.6 | 换模型（详见价格详解） |
sandbox_mode | 视版本 | 收紧权限更安全（详见权限与安全篇） |
network_access | — | 需要联网工具时打开 |
改配置的两个原则
- 改前先备份——配置错了 Codex 可能起不来，留个副本好回滚
- 改后看生效——很多配置重启会话才生效；不确定就用
codex /status看当前实际值（见exec 模式篇）
进阶配置：给未来的你
- 模型提供商：想接自建服务或第三方模型，配
[model_providers]（官方有专门文档，社区也常见多提供商配置教程） - 生命周期钩子：配置里可以挂 hooks（详见规则与 Hooks 篇）
- MCP 服务器：MCP 配置也在这里管理（详见MCP 集成篇）
常见问题
| 问题 | 解答 |
|---|---|
| 改了配置没生效？ | 重启会话；或检查是不是改错了文件/字段名 |
| 不知道有哪些字段？ | 看官方示例配置（config.toml.example） |
| 配置能按项目区分吗？ | 项目级配置/AGENTS.md 配合使用（见项目指令篇） |
| 自建模型怎么配？ | 官方有模型提供商文档，按[model_providers] 结构填 |
一句话总结
配置文件的本质是"把默认行为改成你的习惯"。 新手改模型和权限两个就够；剩下的等真需要了再翻参考。
接下来读什么
← 上一篇：4.3 MCP 集成 | 下一篇：4.5 规则与 Hooks →
↑ 返回 教程总目录
