---
title: "参考配置样例"
description: "用少量 config.toml 配置让 Codex 行为稳定，而不是复制一整份巨型配置。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

`config.toml` 是 Codex 的长期偏好文件。它适合放模型默认值、沙箱、审批、MCP、profile 和少量 UI 行为。

> [!IMPORTANT]
> 配置样例不是推荐你照抄。模型名、provider、feature flags 和权限策略都应按当前官方文档、组织要求和项目风险决定。

<Cards>
  <Card title="Config basics" href="/docs/codex/official/02-config-security/06-basic-config">
    先理解配置加载位置、优先级和 trust 边界。
  </Card>
  <Card title="Config reference" href="/docs/codex/official/02-config-security/30-all-config-options">
    完整 key 去参考页查，不要复制巨型配置。
  </Card>
  <Card title="Sandbox boundaries" href="/docs/codex/official/02-config-security/49-sandbox-boundaries">
    配置最重要的是权限边界，而不是功能堆叠。
  </Card>
</Cards>

## 解决什么

```mermaid
flowchart LR
    Need["repeated behavior"] --> Config["config.toml"]
    Config --> Session["consistent sessions"]
    Session --> Verify["status / small task"]
```

配置文件解决的是“每次打开 Codex 都希望行为一致”的问题：

- 默认用哪个模型。
- 默认是否能改文件。
- 什么时候需要批准命令。
- 项目级规则和个人习惯如何分开。
- 哪些 MCP 或工具默认可用。

不要把配置文件当成“功能大全”。配置越多，排查越难。

## 最小起点

先从最小可解释配置开始：

```toml
model = "your-current-codex-model"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
```

含义：

- `model`：默认模型。写入前查官方 Models 或组织模型策略。
- `approval_policy = "on-request"`：越过边界时询问。
- `sandbox_mode = "workspace-write"`：允许在工作区内读写，仍保留边界。

这比 `danger-full-access` 更适合真实项目，也比纯 `read-only` 更适合日常开发。

## 配置放哪里

用户级 `~/.codex/config.toml`：

- 个人默认模型。
- 个人 UI 偏好。
- 个人常用 MCP。
- 不依赖某个仓库的习惯。

项目级 `.codex/config.toml`：

- 当前仓库的默认 sandbox。
- 当前仓库需要的 MCP。
- 当前仓库特定 profile。
- 团队希望共享的行为。

命令行参数和 `--config` 只适合一次性覆盖，不适合长期偏好。

## 先管安全边界

配置里最重要的是两类：

- `sandbox_mode`：Codex 能访问和修改哪里。
- `approval_policy`：Codex 什么时候停下来问你。

常见组合：

- 保守分析：`read-only` + `on-request`。
- 日常开发：`workspace-write` + `on-request`。
- 高风险全开：`danger-full-access` + `never`。

新手不要把高风险全开写进默认配置。只有在一次性、可信、可回滚的自动化环境中，才考虑这种组合。

## Profile 切场景

如果有多个固定场景，用 profile，不要反复改同一份配置。

```toml
[profiles.review]
sandbox_mode = "read-only"
approval_policy = "on-request"

[profiles.build]
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

这样可以把只读审查和动手开发分开。最常见的问题就是在该只读的时候用了动手模式。

## 不急着配置的项

这些配置官方支持，但新手不必急着写：

- 自定义 model provider。
- 复杂网络权限 profile。
- OTEL / telemetry。
- hooks。
- 自动审批 reviewer。
- 大量 MCP server。
- 自定义 compaction prompt。

等遇到真实问题，再加对应配置。配置应该来自痛点，不应该来自“看起来专业”。

## 怎么判断生效

改完配置后，用 `/status` 或启动后的状态信息确认：

- 当前模型是否符合预期。
- sandbox 是否是你想要的模式。
- approval policy 是否生效。
- 项目级配置是否被加载。

再用小任务验证：读文件、改一个测试文件、运行 `git status`。看它是否在该问你的时候问你，在不该越界时保持边界。

## 常见坑

- 整份复制配置样例，结果不知道哪个键影响行为。
- 把个人偏好写进项目级配置，污染团队仓库。
- 项目级配置写好后忘记 trust project，导致它没加载。
- 默认使用 `danger-full-access`。
- 配了 MCP 或 provider，却没有配置凭据来源。
- 把密钥、token 或 auth 文件路径写进可提交配置。

## 官方资料

- [Config Reference](https://developers.openai.com/codex/config-reference)
- [Best practices](https://developers.openai.com/codex/learn/best-practices)
- [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals)
