> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 02-config.toml配置

> 系统理解 Codex 的用户、项目与系统配置，掌握信任条件、优先级、模型、推理、沙箱、审批、搜索、MCP、profiles、命令行覆盖和配置诊断。

# config.toml 配置指南

`config.toml` 是 Codex 的机器可读配置文件。它决定默认模型、推理强度、沙箱和审批策略，也可以注册 MCP 服务器、保存命令行之外的常用选项。它不替代 `AGENTS.md`：前者控制工具行为，后者提供项目规则和工作上下文。

本页按“位置 -> 信任 -> 优先级 -> 字段 -> 验证 -> 诊断 -> 安全边界”的顺序展开。Codex CLI、桌面应用和账号能力会持续更新，模型名、实验开关和部分 profile 语法可能变化。每次排查时都以本机 `codex --help`、子命令帮助和官方 Config Reference 为最终依据。

## 先记住四条规则

1. 用户配置通常位于 `CODEX_HOME/config.toml`；未设置 `CODEX_HOME` 时，`CODEX_HOME` 默认是用户主目录下的 `.codex`。
2. 项目配置位于仓库或项目目录的 `.codex/config.toml`，只有项目处于可信状态时才会加载。
3. 越具体、越接近当前启动命令的设置通常优先级越高；命令行覆盖只影响这次运行。
4. 配置可以放宽行为，但不能把不可信项目变成可信项目，也不能替代人工审查、凭据隔离和备份。

## 1. 配置文件在哪里

### 1.1 用户级配置

用户级配置是个人默认值，适用于当前用户启动的多个项目：

```text theme={null}
Unix/macOS:  ~/.codex/config.toml
Windows:     %USERPROFILE%\\.codex\\config.toml
自定义目录:   $CODEX_HOME/config.toml
```

例如 Windows PowerShell：

```powershell theme={null}
$env:CODEX_HOME
Join-Path $HOME ".codex"
Test-Path (Join-Path $HOME ".codex\\config.toml")
```

例如 macOS 或 Linux：

```bash theme={null}
printf '%s\n' "${CODEX_HOME:-$HOME/.codex}"
ls -la "${CODEX_HOME:-$HOME/.codex}/config.toml"
```

文件不存在时可以创建。首次编辑前先备份已有文件，避免把登录、历史、MCP 或个人设置一并覆盖：

```bash theme={null}
cp ~/.codex/config.toml ~/.codex/config.toml.bak
```

```powershell theme={null}
Copy-Item "$HOME\\.codex\\config.toml" "$HOME\\.codex\\config.toml.bak"
```

用户级配置适合放：

* 个人常用的 `model` 和 `model_reasoning_effort`；
* 默认的 `sandbox_mode`、`approval_policy`；
* 自己管理的 MCP 服务器；
* 自己的 `profiles` 或 profile 文件；
* 通知、日志和模型提供方等机器级设置。

不要把 API key、OAuth 刷新令牌、SSH 私钥或数据库密码写进配置文件。需要凭据时使用 Codex 支持的登录机制、环境变量或系统密钥存储，并检查文件权限。

### 1.2 项目级配置

项目级配置通常是：

```text theme={null}
<项目根目录>/.codex/config.toml
```

它适合表达“这个项目的默认行为”，例如项目只允许只读分析，或该项目需要一个特定模型。项目文件可能进入 Git，因此任何提交者都能影响它；只写团队确实需要共享、且不会泄露环境信息的设置。

```toml theme={null}
# <repo>/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = false
```

项目配置不是“无条件自动执行的项目脚本”。Codex 会先判断工作区是否可信；不可信时会跳过项目 `.codex/` 层，包括其中的配置、hooks 和 rules。这样可以避免 clone 一个陌生仓库就被它的配置主动放宽权限。

判断项目是否可信时，不要只看仓库名。确认来源、提交者、依赖和构建脚本，检查是否含有可疑的 `AGENTS.md`、hooks、安装脚本或要求外发数据的指令。只有在你完成检查后才接受信任提示。

### 1.3 系统级配置

受管理环境还可以提供系统级配置，用来给一台机器或一组用户设定基线。Unix 环境常见位置是：

```text theme={null}
/etc/codex/config.toml
```

实际支持的位置、Windows 的等价位置以及是否启用系统层，取决于当前 Codex 版本和安装方式。不要因为某个目录存在就假设 Codex 会读取它；使用官方 Config Reference 和启动日志确认。

系统级配置适合管理员设定组织基线，例如禁止完全访问、统一默认模型提供方或限制遥测出口。它不应保存个人令牌。系统管理员还可以通过设备策略、容器、网络防火墙和文件权限提供比 TOML 更高层的约束。

## 2. 信任条件和项目边界

### 2.1 为什么项目层需要信任

项目配置是仓库内容的一部分，而仓库内容可能来自不可信来源。假设项目配置可以无条件设置通知命令、遥测端点、模型服务地址或高权限行为，那么一次打开陌生项目就可能把数据发送到外部服务。因此 Codex 对项目层设置增加信任门槛，并对部分机器级字段直接忽略。

“不信任项目”并不等于不能阅读项目。通常仍可以在只读沙箱中检查文件、查看 Git 状态和分析代码；只是项目本地配置、规则和 hooks 不会作为可信行为加载。

### 2.2 哪些设置不应由项目控制

即使项目被信任，也不要把下面这些设置交给来自仓库的配置：

* `model_provider`、`model_providers`、`openai_base_url`、`chatgpt_base_url`；
* `notify`、`otel`、外部日志或遥测出口；
* `profile`、`profiles` 等影响全局配置选择的设置；
* 认证、账号、密钥、代理和本机路径；
* 会让工具访问整个文件系统或关闭所有审批的设置。

官方会忽略部分机器级键在项目本地 `.codex/config.toml` 中的值，并可能输出警告。看到“配置写了却没生效”时，先检查它是否属于项目层禁用字段，而不是重复修改文件。

## 3. 配置优先级

### 3.1 一张实用的优先级图

实际合并细节会随版本和入口变化，但排查时可以先按下面的原则理解：

| 层级 | 来源                    | 作用范围          | 典型用途      |
| -- | --------------------- | ------------- | --------- |
| 1  | 命令行专用选项、`-c/--config` | 当前进程          | 临时试验一个值   |
| 2  | 当前可信项目层               | 当前项目          | 项目共享默认    |
| 3  | `--profile` 选中的配置     | 当前进程或 profile | 切换一整套个人设置 |
| 4  | 用户级 `config.toml`     | 当前用户          | 跨项目默认     |
| 5  | 系统级配置                 | 机器或组织         | 管理员基线     |
| 6  | 内置默认值                 | 所有未设置场景       | 最终兜底      |

不要把这张表理解成“所有键都严格按同一套合并算法覆盖”。有些键只能在用户层设置，有些专用命令行选项会在解析阶段生效，有些表是合并而不是整表替换。遇到行为差异，应以启动时的诊断信息和当前版本文档为准。

一个键发生冲突时，先问四个问题：

1. 这是不是专用命令行参数直接指定的？
2. 当前项目是否可信，项目层是否真的被加载？
3. 是否通过 `--profile` 选择了另一份配置？
4. 该键是否属于只允许用户级的机器级设置？

### 3.2 根键和表的 TOML 顺序

TOML 中，根键必须放在表声明之前。把根键写到 `[mcp_servers.foo]` 后面，可能会让它被解释为表内字段或触发解析错误。

```toml theme={null}
# 正确：根键先写
model = "gpt-5.5"
approval_policy = "on-request"

[features]
memories = false
```

```toml theme={null}
# 容易出错：model 已经处在 features 表中
[features]
memories = false
model = "gpt-5.5"
```

同一个表或同一个键不要重复定义。字符串必须用引号，布尔值只能写 `true` 或 `false`，数组和内嵌表要使用合法 TOML 语法。

## 4. 常用顶层字段

### 4.1 `model`

`model` 设定默认模型：

```toml theme={null}
model = "gpt-5.5"
```

可用模型会随账号、入口和版本变化。不要照抄过时模型名；在会话中用 `/model` 查看可用列表，或使用当前 CLI 支持的模型帮助。模型选择不是权限边界：更强模型仍然受沙箱、审批、网络和账号限制约束。

模型选择建议与任务匹配：简单改名、格式化和批量机械操作可以选择更快的模型；跨模块重构、复杂调试和安全审查通常需要更强模型或更高推理强度。不要把“最强”配置成全局默认后忘记等待时间、成本和上下文规模。

### 4.2 `model_reasoning_effort`

`model_reasoning_effort` 控制支持推理的模型投入多少推理资源：

```toml theme={null}
model_reasoning_effort = "medium"
```

常见值包含 `minimal`、`low`、`medium`、`high`，部分模型支持 `none` 或 `xhigh`。可选值不是所有模型通用，当前模型不支持时会报错或回退。建议从 `medium` 开始，简单任务降到 `low`，复杂设计和难定位的 bug 再提高。

推理强度会影响延迟、额度和输出深度，但不会替你验证结果。无论强度多高，都应阅读 diff、运行测试并检查外部副作用。

### 4.3 `approval_policy`

审批策略控制 Codex 何时请求人工批准：

```toml theme={null}
approval_policy = "on-request"
```

常见策略如下：

| 值            | 含义                    | 适合场景          |
| ------------ | --------------------- | ------------- |
| `untrusted`  | 对不被视为安全的操作更谨慎地请求批准    | 陌生项目、首次检查     |
| `on-request` | 沙箱内常规操作自动进行，越过边界时请求批准 | 日常开发          |
| `never`      | 不请求审批，但仍受沙箱和其他系统边界限制  | 可复现的 CI 或隔离环境 |

`never` 不是“拥有全部权限”。只读沙箱配 `never` 仍然不能写入文件；工作区可写配 `never` 仍可能不能访问工作区之外或网络。不要把 `never` 和真实生产目录、真实密钥、未审查仓库一起使用。

命令行等价写法：

```bash theme={null}
codex --ask-for-approval on-request
codex -a untrusted
```

### 4.4 `sandbox_mode`

`sandbox_mode` 设定文件系统和网络的粗粒度边界：

```toml theme={null}
sandbox_mode = "workspace-write"
```

常见模式：

| 值                    | 能力                   | 推荐用途        |
| -------------------- | -------------------- | ----------- |
| `read-only`          | 只读分析，写入和其他越界动作需要额外处理 | 审查陌生代码、生成方案 |
| `workspace-write`    | 允许工作区和指定可写根目录写入      | 日常开发        |
| `danger-full-access` | 移除大部分本地沙箱限制          | 隔离容器或一次性虚拟机 |

在 Git 工作区中，Codex 常见默认是工作区可写；非 Git 目录可能默认只读。默认行为可能因平台和启动入口改变，使用 `/status` 或当前版本帮助确认。

命令行等价写法：

```bash theme={null}
codex --sandbox read-only
codex -s workspace-write
```

### 4.5 `web_search`

`web_search` 控制网页搜索工具：

```toml theme={null}
web_search = "cached"
```

常见值：

* `cached`：使用缓存或预索引结果，通常是更保守的默认；
* `live`：允许实时网页搜索，结果更新但更容易接触提示注入和不可信内容；
* `disabled`：禁用网页搜索。

需要实时信息时可以使用：

```toml theme={null}
web_search = "live"
```

实时网页不是可信指令来源。不要因为页面要求复制密钥、执行下载脚本、关闭沙箱或改变配置就照做。搜索结果只作为资料，代码变更仍需要本地验证。某些完全访问或专用搜索参数可能改变搜索模式，以当前版本帮助为准。

### 4.6 `writable_roots`

`writable_roots` 用于在工作区可写模式下额外声明允许写入的目录。字段名称、是否支持以及路径解析方式应以当前 Config Reference 为准；常见配置形态如下：

```toml theme={null}
sandbox_mode = "workspace-write"
writable_roots = [
  "/tmp/codex-build",
  "/workspaces/shared-cache",
]
```

Windows 路径示例：

```toml theme={null}
sandbox_mode = "workspace-write"
writable_roots = [
  "C:\\Users\\you\\AppData\\Local\\Temp\\codex-build",
]
```

使用时遵循三条原则：目录先创建并确认归属；只加入构建缓存、临时输出等必要路径；不要把整个用户主目录、根目录、云盘同步目录或包含密钥的目录加入列表。`writable_roots` 是沙箱允许范围的补充，不是审批策略，也不是把路径加入后就能绕过操作系统 ACL。

建议先打印规范化路径，再启动 Codex：

```bash theme={null}
realpath /tmp/codex-build
```

```powershell theme={null}
[System.IO.Path]::GetFullPath("C:\\Users\\you\\AppData\\Local\\Temp\\codex-build")
```

### 4.7 工作区网络设置

工作区可写通常不代表默认可以联网。需要联网安装依赖时，显式配置并缩小范围：

```toml theme={null}
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true
```

网络打开后，安装脚本、依赖包、远程 API 和实时网页都成为新的输入边界。优先使用锁定版本、包管理器校验和公司代理；安装完成后关闭网络或恢复为 `false`。不要把网络访问误当作“只允许访问某个域名”，域名白名单需要更细粒度的权限配置或外部防火墙。

## 5. MCP 配置

### 5.1 MCP 是什么

MCP 服务器向 Codex 暴露工具或资源，例如文档查询、数据库只读检索或内部工单系统。MCP 的权限与 Codex 本身的沙箱、审批并不自动等价：MCP 服务器进程可能拥有它自己的文件、网络和凭据权限。

只连接你审查过的服务器。先确认启动命令、包来源、环境变量、网络目标、日志位置和服务器实际能做的操作，再决定是否启用。

### 5.2 一个 stdio MCP 示例

常见 TOML 结构如下，具体字段以当前版本 MCP 配置参考为准：

```toml theme={null}
[mcp_servers.docs]
command = "npx"
args = ["-y", "@example/docs-mcp", "--readonly"]
enabled = true
startup_timeout_ms = 10000
tool_timeout_ms = 30000

[mcp_servers.docs.env]
DOCS_BASE_URL = "https://docs.example.com"
```

使用绝对路径可以减少 PATH 差异：

```toml theme={null}
[mcp_servers.local_tools]
command = "/usr/local/bin/my-docs-mcp"
args = ["--readonly"]
enabled = true
```

不要把令牌直接写在 `args` 或 TOML 中：

```toml theme={null}
# 不要这样做
# args = ["--token", "sk-live-真实密钥"]
```

如果服务器需要凭据，使用 Codex 支持的环境变量注入方式或独立凭据存储，并确认日志不会打印环境变量。

### 5.3 MCP 调试顺序

MCP 不工作时按这个顺序缩小范围：

1. 用 `codex --help` 和当前文档确认表名、字段名和传输方式。
2. 在终端单独运行服务器命令，确认它能启动并输出预期协议内容。
3. 确认 `command` 在 Codex 进程的 PATH 中可见，工作目录和 Node/Python 版本一致。
4. 先设置 `enabled = false` 启动 Codex，确认基础配置正常，再单独启用一个服务器。
5. 查看 Codex 的 MCP 状态或日志，区分启动失败、握手失败、工具超时和权限拒绝。
6. 用只读、无真实数据的请求验证工具，确认服务器没有越权写入或外发。

多个 MCP 服务器应逐个加入。一个服务器的崩溃、超时或恶意工具不应阻塞整个工作流，也不应因为“方便”给所有服务器共享同一个高权限令牌。

## 6. profiles 与配置文件复用

### 6.1 profile 的用途

profile 适合保存几套个人配置，例如只读审查、日常开发和隔离自动化。常见做法是在 `CODEX_HOME` 下创建独立文件：

```text theme={null}
~/.codex/review.config.toml
~/.codex/build.config.toml
```

```toml theme={null}
# ~/.codex/review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
approval_policy = "untrusted"
web_search = "cached"
```

```toml theme={null}
# ~/.codex/build.config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

启动时选择：

```bash theme={null}
codex --profile review
codex exec --profile build "运行测试并总结失败原因"
```

profile 文件仍然是机器级个人配置，不要提交到项目仓库，也不要把它当作项目可信声明。若多个 profile 之间差异很大，文件中明确写全关键安全字段，避免继承关系变化后出现意外放宽。

### 6.2 旧版 `[profiles]` 语法

不同版本对 `[profiles.name]`、顶层 `profile` 和独立 `<name>.config.toml` 文件的支持可能不同。新版本可能要求使用独立 profile 文件，并不再读取旧的嵌套写法。升级后发现 profile 不生效时，执行：

```bash theme={null}
codex --help
codex --profile review --help
```

不要同时在项目配置中设置 `profile` 来强迫每个人使用某套个人配置。项目可以共享安全的默认值，profile 选择应由启动者明确完成。

## 7. 命令行覆盖

### 7.1 专用参数

临时试验优先使用专用参数：

```bash theme={null}
codex --model gpt-5.4-mini \
  --sandbox read-only \
  --ask-for-approval untrusted
```

常见快捷方式包括 `-m`、`-s` 和 `-a`，但以 `codex --help` 为准。会话内也可能提供 `/model`、`/permissions` 和 `/status` 等命令；它们通常只影响当前会话。

### 7.2 `-c` / `--config`

没有专用参数时，可以用 `-c` 或 `--config` 指定键值：

```bash theme={null}
codex -c web_search='"live"'
codex -c model_reasoning_effort='"high"'
codex -c mcp_servers.docs.enabled=false
```

`-c` 的值按 TOML 解析，不是 JSON。字符串需要 TOML 双引号；上例外层单引号只是让 shell 把整段作为一个参数。在 PowerShell 中也要留意引号：

```powershell theme={null}
codex -c 'web_search="live"'
codex -c 'mcp_servers.docs.enabled=false'
```

命令行覆盖不会改写 `config.toml`。验证完成后，如果确实要长期使用，再把最小必要值写入合适层级。不要把包含令牌的完整命令复制到聊天记录、Issue 或 shell 历史。

### 7.3 覆盖后的验证

用三个层次确认覆盖确实生效：

```bash theme={null}
codex -c sandbox_mode='"read-only"'
```

进入会话后：

```text theme={null}
/status
```

再用普通 `codex` 启动一次，确认配置已恢复原值。若两次结果一样，检查参数位置、子命令继承方式和当前 CLI 版本，而不是直接把用户配置改成更宽松的值。

## 8. 一份安全的起步配置

下面是适合个人开发机的保守示例。模型名请替换为当前账号可用的值：

```toml theme={null}
# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
web_search = "cached"

[sandbox_workspace_write]
network_access = false

[features]
# 只显式设置你确认需要的开关；实验功能名称以当前版本为准。
memories = false
```

对陌生项目使用更严格的项目配置：

```toml theme={null}
# <repo>/.codex/config.toml
model_reasoning_effort = "high"
sandbox_mode = "read-only"
approval_policy = "untrusted"
web_search = "disabled"
```

需要生成构建产物到工作区之外时，先创建专用临时目录，再只加入它：

```toml theme={null}
sandbox_mode = "workspace-write"
writable_roots = ["/tmp/codex-build"]
```

不要把下面这组配置作为日常全局默认：

```toml theme={null}
# 高风险示例，仅适用于已隔离且可销毁的环境
sandbox_mode = "danger-full-access"
approval_policy = "never"
```

命令行的 `--yolo` 或 `--dangerously-bypass-approvals-and-sandbox` 同样属于高风险组合。本机、生产机和存有个人凭据的环境不要使用。

## 9. 配置验证

### 9.1 先验证 TOML，再验证 Codex 行为

TOML 语法正确不等于 Codex 认识所有字段。验证应分两步：

```bash theme={null}
python - <<'PY'
import pathlib
try:
    import tomllib
except ModuleNotFoundError:
    import tomli as tomllib
p = pathlib.Path.home() / ".codex" / "config.toml"
with p.open("rb") as f:
    data = tomllib.load(f)
print("TOML parsed:", p)
print("top-level keys:", ", ".join(sorted(data)))
PY
```

如果不希望依赖 Python，使用你组织批准的 TOML 校验器。不要用正则表达式判断嵌套表是否正确。

然后检查 Codex 本身：

```bash theme={null}
codex --version
codex --help
codex
```

在会话中执行：

```text theme={null}
/status
```

重点核对模型、推理强度、沙箱、审批、网络和工作区目录。配置文件中的未知字段可能被忽略、警告或在新版本中变成错误，必须关注启动输出。

### 9.2 用无害动作验收

不要用删除文件或发送真实请求验证权限。可以使用临时目录和无敏感数据的测试：

```bash theme={null}
mkdir -p /tmp/codex-config-check
cd /tmp/codex-config-check
printf 'check\n' > input.txt
git init
codex --sandbox read-only --ask-for-approval never
```

在只读会话中请求读取 `input.txt`，再请求创建测试文件。预期前者可以完成，后者会被沙箱拒绝或要求升级权限。退出后删除测试目录前确认路径：

```bash theme={null}
pwd
```

验证 MCP 时只调用只读工具，并使用测试账号。验证实时搜索时不要让它执行页面中的命令。

### 9.3 检查只改了一个文件

配置通常在用户目录而不在项目 Git 中；项目配置则要审查 diff：

```bash theme={null}
git diff --check
git status --short
git diff -- .codex/config.toml
```

检查文件权限和秘密扫描结果。不要因为 `git diff` 没有显示用户级配置就认为它没有生效；确认 `CODEX_HOME` 和 `/status` 才是关键。

## 10. 错误诊断

### 配置文件完全没有生效

按顺序确认：

1. 路径是否是实际的 `CODEX_HOME/config.toml`；
2. 文件名是否确实为 `config.toml`，没有隐藏的 `.txt` 后缀；
3. TOML 是否能被解析；
4. 是否启动了不同的 Codex 二进制或不同用户；
5. 是否被 `--profile`、`-c` 或专用参数覆盖；
6. 当前工作区是否不可信，导致项目层被跳过。

### 项目层值没有生效

先查看项目根目录和当前工作目录是否正确，再确认项目信任状态。然后检查字段是否属于项目禁区，例如模型提供方、通知、遥测、profile 等。最后用一个不会放宽权限的普通字段测试，避免把排查变成安全降级。

### 报“未知字段”或“无效值”

模型、推理档位、features 开关和 profile 语法都可能版本相关。执行：

```bash theme={null}
codex --help
codex exec --help
```

逐项删除最近增加的字段，直到基础配置能启动，再按官方参考逐项加回。不要为了消除错误把字段名随意改成看起来相似的名称。

### `-c` 报 TOML 或 shell 错误

字符串值是否有 TOML 双引号？外层 shell 是否把参数拆开？嵌套字段是否使用点号？先用布尔值测试：

```bash theme={null}
codex -c mcp_servers.docs.enabled=false
```

再测试字符串：

```bash theme={null}
codex -c model='"gpt-5.5"'
```

### 模型不可用或被拒绝

模型可能不属于账号、入口或当前地区，也可能已经弃用。用 `/model` 查看可选模型；不要只根据旧文章中的模型名编辑配置。若切换模型后推理强度无效，选择该模型支持的档位。

### MCP 启动失败

先单独运行 `command`，再核对 PATH、Node/Python 环境、参数、超时和环境变量。把服务器设为 `enabled = false` 后确认 Codex 本身能启动。若服务器能启动但工具失败，区分协议握手、工具权限、网络和业务 API 错误，分别处理。

### 网络搜索或依赖安装失败

`web_search = "live"` 只影响搜索工具，不等于所有 shell 命令都能联网。`workspace-write` 下网络也可能默认关闭，需要检查 `[sandbox_workspace_write]`。公司代理、防火墙、证书和包管理器配置仍然可能阻断请求。

### 配置修改后仍表现为旧值

关闭并重新启动会话，确认没有复用旧进程。检查 profile、命令行覆盖、环境变量和项目层。用 `/status` 记录有效值，比较“普通启动”和“带覆盖启动”的差异。

## 11. 安全边界

### 不要把配置当成信任系统

`approval_policy = "never"` 只是不弹审批；它不验证提示内容，也不阻止恶意依赖、网页提示注入或 MCP 工具执行危险操作。`danger-full-access` 更不会自动识别“安全命令”。权限越宽，人工审查和环境隔离越重要。

### 保护凭据和外发数据

不要让 Codex 读取包含令牌的目录，也不要把 `.env`、SSH 目录、浏览器配置、云凭据目录加入 `writable_roots`。实时搜索、MCP、通知和遥测都可能把上下文或元数据送到外部系统；确认数据去向、保留期和访问主体。

### 生产环境和自动化

生产目录优先使用 `read-only`，发布动作由独立 CI 或人工审批完成。CI 若使用 `approval_policy = "never"`，应在一次性容器中运行，使用最小权限令牌、固定依赖和出站网络限制。不要把全局 `danger-full-access` 写入开发机配置后再期待每个项目都安全。

### 项目配置的提交策略

提交 `.codex/config.toml` 前检查：没有密钥、个人路径、内部域名、通知命令和未经团队批准的权限放宽。团队共享配置应倾向：`read-only` 或 `workspace-write`、`on-request`、关闭不需要的网络，并在项目 README 中说明如何验证和回滚，而不是偷偷依赖个人机器状态。

## 12. 速查表

| 需求         | 配置或命令                               | 注意                                   |
| ---------- | ----------------------------------- | ------------------------------------ |
| 设置默认模型     | `model = "..."`                     | 模型以 `/model` 实际列表为准                  |
| 调整推理       | `model_reasoning_effort = "medium"` | 支持档位随模型变化                            |
| 工作区内开发     | `sandbox_mode = "workspace-write"`  | 网络不一定默认开启                            |
| 只读审查       | `sandbox_mode = "read-only"`        | 可配 `approval_policy = "never"` 做安静分析 |
| 出圈时询问      | `approval_policy = "on-request"`    | 不等于允许越界                              |
| 关闭网页搜索     | `web_search = "disabled"`           | 不影响其他网络工具                            |
| 临时改一个值     | `codex -c key=value`                | 值按 TOML 解析                           |
| 查看有效设置     | 会话内 `/status`                       | 以当前会话为准                              |
| 切换 profile | `codex --profile name`              | profile 文件在 `CODEX_HOME`             |
| 增加可写目录     | `writable_roots = ["..."]`          | 只加入最小必要目录                            |
| 注册 MCP     | `[mcp_servers.name]`                | 先审查命令、凭据和网络                          |

## 小结

`config.toml` 的正确用法不是把所有开关都打开，而是让配置层级和安全边界清晰：用户级放个人默认和机器级设置，可信项目层放项目共享行为，系统层提供组织基线，命令行用于一次性试验。模型和推理决定“用多少能力”，沙箱和 `writable_roots` 决定“能碰哪里”，审批决定“什么时候问人”，`web_search` 和 MCP 决定“哪些外部信息或工具进入流程”。

遇到不生效时，不要先放宽权限。先确认 `CODEX_HOME`、项目是否可信、优先级、字段是否被项目层禁止、TOML 是否有效，以及 `/status` 显示的实际值。配置验证通过后仍要审查 diff、测试结果、网络请求和凭据边界。

参考资料：`参考/codex/18-config.md`、`参考/codex/30-models.md`、`参考/codex/15-permissions.md`。动态字段和默认值以本地 Codex 版本及官方 Config Reference 为准。