---
title: "高级配置怎么读"
description: "把 Codex 高级配置按使用场景和风险边界拆开，而不是复制一整张会随版本变化的配置表。"
verifiedAt: "2026-05-06"
---

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

Codex 的高级配置不是“把所有 key 背下来”。更可靠的做法是先分清三件事：

1. 哪些配置影响当前会话的行为。
2. 哪些配置会进入项目或团队层。
3. 哪些配置会放大安全风险。

完整 key、默认值和实验状态以官方 Configuration Reference 为准。本页只负责建立阅读顺序和落地边界。

> [!IMPORTANT]
> 不要把高级配置页当成静态手册长期复制。模型名、feature flag、provider 参数、hook 事件和团队配置都可能变化；教程里只保留稳定判断方法，具体字段回到官方参考页核验。

<Cards>
  <Card title="配置参考" href="https://developers.openai.com/codex/config-reference">
    查看 Codex `config.toml` 的完整字段、类型和默认行为。
  </Card>
  <Card title="高级配置" href="https://developers.openai.com/codex/config-advanced">
    查看 profiles、project config、hooks、providers 等高级能力的官方说明。
  </Card>
  <Card title="自定义能力" href="https://developers.openai.com/codex/concepts/customization">
    理解 instructions、rules、skills、subagents 和 hooks 的分工。
  </Card>
</Cards>

## 高级配置的四层

先按“作用范围”读配置，比按字母顺序读 key 更稳。

```mermaid
flowchart TB
    User["User 层<br/>CODEX_HOME/config.toml"]
    Project["Project 层<br/>repo 内 .codex/config.toml"]
    Runtime["Runtime 覆盖<br/>CLI flags / -c overrides"]
    Team["Team / System 层<br/>组织默认值、共享规则、skills"]
    Session["本次 Codex session"]

    Team --> Session
    User --> Session
    Project --> Session
    Runtime --> Session

    Project -. "只在 trusted project 加载" .-> Session
    Runtime -. "只影响本次 invocation" .-> Session
```

这四层的判断方式：

- User 层适合个人长期偏好，例如默认审批策略、常用 provider、历史记录策略。
- Project 层适合项目规则，例如 repo 内的 instructions、hooks、project-scoped defaults。
- Runtime 覆盖适合临时实验，例如本次换模型、本次改 sandbox、本次禁用某个 feature。
- Team / System 层适合组织统一规则，例如共享默认配置、团队 skills、企业管理要求。

配置越靠近当前任务，越适合表达“本次怎么跑”；配置越靠近团队层，越应该表达“所有人都必须遵守什么”。

## 用 profiles 管“工作模式”

Profiles 是命名配置组，适合把常用工作模式固化下来，例如轻量问答、深度审查、只读诊断、自动化执行。

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

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

[profiles.ci]
approval_policy = "never"
sandbox_mode = "workspace-write"
```

启动时选择：

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

Profile 的价值不是省几行配置，而是降低误操作概率。比如“只读诊断”和“可改文件执行”不应该靠临场记忆区分，应该变成两个明确的 profile。

## 用 `-c` 做一次性覆盖

命令行的 `-c` / `--config` 适合临时覆盖配置。它不应该替代长期配置文件。

```bash
codex -c approval_policy='"on-request"'
codex -c sandbox_mode='"read-only"'
codex -c model_reasoning_effort='"high"'
```

使用时注意三点：

- 值按 TOML 解析，字符串通常需要显式引号。
- Nested key 可以用点号写法。
- 临时覆盖适合实验，不适合团队规则。

把 `-c` 当成“本次调参”，把 `config.toml` 当成“长期默认值”，把项目 `.codex/` 当成“这个 repo 的约束”。

## Project config 要先看 trust

Codex 可以读取项目内的 `.codex/config.toml`。这让项目可以声明自己的规则，但也带来安全边界问题。

```text
repo/
  .codex/
    config.toml
    hooks.json
  AGENTS.md
```

Project config 的关键原则：

- 只在项目受信任时加载 project-scoped config。
- 越靠近当前目录的 project config 越具体。
- 相对路径会相对包含该配置的 `.codex/` 目录解析。
- 不要在公开仓库写入个人 token、私有 endpoint、机器路径。

项目层适合放团队共同约束，不适合放个人偏好。个人偏好应留在 `CODEX_HOME/config.toml`。

## Providers 先区分“改 OpenAI endpoint”还是“新增 provider”

很多人把 provider 配置写复杂，是因为没有先区分目标。

如果只是让内置 OpenAI provider 走代理、router 或特定区域 endpoint，通常优先配置 OpenAI base URL，而不是新建 provider。

```toml
openai_base_url = "https://example.internal/v1"
```

如果你确实要接入额外模型服务，再定义 `model_providers.<id>`：

```toml
model_provider = "proxy"

[model_providers.proxy]
name = "Internal OpenAI-compatible proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"
```

Provider 配置的风险点：

- `base_url` 会改变请求去向，必须确认数据边界。
- `env_key` 只引用环境变量名，不要把密钥写进配置。
- 自定义 header 可能泄露内部信息，公开仓库要避免提交。
- 企业或团队环境应优先使用组织批准的 endpoint。

## Hooks 是自动化，不是装饰

Hooks 会在 Codex 生命周期的特定事件上运行命令。它们适合做检查、记录、策略判断，但不适合塞入不透明的大型流程。

```toml
[features]
codex_hooks = true

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "/usr/local/bin/check-codex-command"
timeout = 30
```

写 hooks 前先问四个问题：

- 这个 hook 是否必须自动运行。
- 失败时是否会阻断关键流程。
- 输出是否会暴露敏感路径、token 或用户数据。
- 团队成员是否能快速理解它为什么存在。

Hooks 一旦进入 project 层，就会影响所有使用该 repo 的人。规则越强，说明文档越要清楚。

## Rules、instructions、skills、subagents 的分工

高级配置经常和自定义能力混在一起。可以用下面这张图判断职责：

```mermaid
flowchart LR
    Goal["任务目标"] --> Instructions["Instructions / AGENTS.md<br/>告诉 Codex 怎么做"]
    Instructions --> Tools["Tools / MCP / shell<br/>让 Codex 能行动"]
    Instructions --> Skills["Skills<br/>复用稳定流程"]
    Instructions --> Subagents["Subagents<br/>拆分角色或并行任务"]
    Tools --> Verification["验证结果"]
    Skills --> Verification
    Subagents --> Verification
```

选择方式：

- 稳定规则写进 instructions。
- 高频流程沉淀为 skill。
- 需要不同角色或并行处理时使用 subagents。
- 涉及工具调用前后的硬性策略时考虑 hooks。
- 只影响一次任务的偏好用命令行覆盖。

不要把所有东西都塞进一个配置文件。可维护性来自边界清楚，而不是字段数量多。

## 安全检查清单

改高级配置前，至少检查这些点：

1. 是否把密钥、token、内部 URL 写进了 repo。
2. 是否把 sandbox 或 approval 调得过松。
3. 是否让 project hooks 在未充分说明的情况下自动运行。
4. 是否把个人机器路径写成团队默认值。
5. 是否复制了会随版本变化的模型、价格、限制或 feature flag 列表。
6. 是否能用官方 Configuration Reference 解释每个关键字段。

## 推荐落地顺序

第一次做高级配置，不要从完整字段表开始。按这个顺序更稳：

1. 先在 User 层配置个人默认 sandbox 和 approval。
2. 为常用工作模式建立 2-3 个 profiles。
3. 对单次实验使用 `-c`，确认有效后再固化。
4. 对项目规则使用 `.codex/`，并只提交可公开、可解释的内容。
5. 再考虑 providers、hooks、subagents、team config。

高级配置的目标不是“可调项最多”，而是让 Codex 在正确权限、正确上下文、正确验证方式下工作。

## 配置变更的验收方式

高级配置改完以后，不要只看 Codex 能不能启动。商业项目要验证三件事：只读模式是否真的不能写文件，常规实现模式是否只能修改预期 workspace，自动化模式是否不会请求人工输入。只要这三件事没有验过，配置就还停留在“看起来能用”的阶段。

团队还应保留一份最小回滚路径。配置变更如果影响 provider、hooks、sandbox、approval 或 project config，必须知道怎样退回上一版默认值。这样即使某个 hook 写错、某个 provider endpoint 不通，团队也能快速恢复工作，而不是让所有 agent 会话同时失败。
