高级配置怎么读

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

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

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

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

配置参考

查看 Codex config.toml 的完整字段、类型和默认行为。

高级配置

查看 profiles、project config、hooks、providers 等高级能力的官方说明。

自定义能力

理解 instructions、rules、skills、subagents 和 hooks 的分工。

高级配置的四层

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

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

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"

启动时选择：

codex --profile readonly

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

用 `-c` 做一次性覆盖

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

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。这让项目可以声明自己的规则，但也带来安全边界问题。

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。

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

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

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 生命周期的特定事件上运行命令。它们适合做检查、记录、策略判断，但不适合塞入不透明的大型流程。

[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 的分工

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

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。
只影响一次任务的偏好用命令行覆盖。

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

安全检查清单

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

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

配置变更的验收方式

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

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