---
title: "配置 Codex 基础选项"
description: "梳理 Codex config.toml 的加载顺序、权限边界和新手最该先改的基础项。"
verifiedAt: "2026-05-06"
---

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

Codex 配置不是“偏好设置合集”，而是模型、权限、工具、网络和团队治理的控制面。新手只需要先掌握加载顺序和安全边界。

> [!IMPORTANT]
> 不要复制一整份别人机器上的 `config.toml`。先写最小配置，再按任务增加模型、权限、MCP、环境变量和 profile。

<Cards>
  <Card title="Config basics" href="https://developers.openai.com/codex/config-basic">
    官方基础配置入口，确认加载位置和优先级。
  </Card>
  <Card title="Advanced config" href="/docs/codex/official/02-config-security/29-advanced-config">
    需要 profile、`-c` 覆盖和 provider 时再读高级配置。
  </Card>
  <Card title="Config reference" href="/docs/codex/official/02-config-security/30-all-config-options">
    查完整 key 时看参考页，不把完整表格塞进基础教程。
  </Card>
</Cards>

## 配置从哪里来

用户级配置位于：

```text
~/.codex/config.toml
```

项目级配置位于：

```text
.codex/config.toml
```

CLI 和 IDE extension 共享同一套配置层。IDE 里可以从设置入口打开 `config.toml`，CLI 则直接读 `CODEX_HOME` 下的配置。

项目级 `.codex/` 只有在你 trust the project 后才加载。未信任项目会跳过项目本地 config、hooks 和 rules，但用户级、系统级配置仍会加载。

## 优先级怎么理解

```mermaid
flowchart TD
    Flags["CLI flags / --config"] --> Profile["--profile values"]
    Profile --> Project["trusted .codex/config.toml"]
    Project --> User["~/.codex/config.toml"]
    User --> System["/etc/codex/config.toml"]
    System --> BuiltIn["built-in defaults"]
```

越上层优先级越高：

1. CLI flags 和 `--config` 覆盖项。
2. `--profile <name>` 选中的 profile 值。
3. 受信任项目里的 `.codex/config.toml`，越靠近当前目录越优先。
4. 用户配置 `~/.codex/config.toml`。
5. 系统配置，例如 Unix 上的 `/etc/codex/config.toml`。
6. 内置默认值。

这个顺序决定了配置写在哪里：

- 个人长期偏好写用户级。
- 项目约定写项目级。
- 临时实验用 CLI flag 或 `--config`。
- 团队受控机器用系统级或 managed configuration。

## 新手先改哪些项

先改稳定、低风险、影响清楚的项。

### 模型

模型名变化快，不要把教程里的示例当成长期推荐。写配置前查官方 Models 或组织内部模型目录。

```toml
model = "your-current-codex-model"
```

如果团队有统一模型策略，把默认值放在用户级或系统级，不要在每个项目里散落一份。

### 审批策略

`approval_policy` 决定 Codex 什么时候暂停并向你请求确认。

```toml
approval_policy = "on-request"
```

新手默认保留可审批路径。只有隔离 CI、一次性审查或受管理环境里，才考虑更激进的策略。

### 沙箱

`sandbox_mode` 控制文件系统和网络访问。

```toml
sandbox_mode = "workspace-write"
```

基础原则：

- 读代码、审查 diff、写报告：只读。
- 修改仓库内文件：workspace-write。
- 访问网络或系统路径：明确任务、明确验证、明确隔离。
- 全权限：只放在你能重建的临时环境里。

### MCP 和外部工具

MCP server 是外部上下文和外部动作入口。先启用必要工具，再逐个验证：

- server 能启动。
- 超时合理。
- token 不进仓库。
- 工具输出被当作不可信输入。
- 写入型工具有审批或环境隔离。

### 命令环境

用 `shell_environment_policy` 控制命令能拿到哪些环境变量。

```toml
[shell_environment_policy]
include_only = ["PATH", "HOME"]
```

不要默认把所有环境变量转发给模型生成的命令，尤其是云服务 key、数据库地址和私有 token。

## Profile 怎么用

Profile 适合保存“同一个人不同任务”的配置组合。例如：

- 只读审查。
- 本地小修复。
- 深度 review。
- 隔离 CI 自动化。

不要为每篇教程、每个目录都建 profile。profile 数量越多，越难判断当前会话到底用了什么策略。

示意写法：

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

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

临时运行：

```bash
codex --profile readonly
```

## 一次性覆盖

短期实验优先用 CLI flag。没有专门 flag 时，用 `-c` 或 `--config` 覆盖任意 key：

```bash
codex --config sandbox_workspace_write.network_access=true
```

注意 `--config` 的值按 TOML 解析，不是 JSON。字符串和数组需要正确引用；写不准时先在一次性命令里验证，不要直接写进全局配置。

## 基础配置验收

- 当前会话能说清用了哪一层配置。
- 项目未信任时不会加载项目 `.codex/`。
- sandbox 和 approval 符合任务风险。
- 模型名来自官方或组织当前策略，不来自旧教程复制。
- MCP token、API key、访问令牌没有写进仓库。
- 命令环境没有默认泄露全部环境变量。
- 临时 `--config` 覆盖没有污染长期配置。

配置越基础，越要少写。最小配置跑稳后，再把真实重复需求沉淀进去。
