Home

深色模式

Codex 配置 ​

概述 ​

Codex 的本地配置由多种文件和扩展机制组成。config.toml 控制客户端运行方式，AGENTS.md 提供项目指令，MCP 接入外部工具，Rules 和 Hooks 负责机械约束，Skills 与 Plugins 封装可复用能力。

截至 2026 年 8 月 19 日，CLI、IDE extension 和 ChatGPT desktop app 共用同一套 Codex 配置层。旧文章里常见的 [profiles.<name>] 写法已经失效，当前 profile 必须使用独立文件。新的 permission profiles 也已经进入 beta，但不能与旧式 sandbox_mode 混用。

配置位置 ​

用户级配置默认位于：

text
~/.codex/config.toml

项目或子目录可以增加：

text
.codex/config.toml

Codex 会从项目根目录走到当前工作目录，加载沿途所有 .codex/config.toml，离当前目录最近的同名配置值优先。项目必须被标记为 trusted，否则项目内的 config、hooks 和 rules 都会被跳过。

项目配置不能覆盖提供方、认证、通知和遥测等机器级设置。例如 model_provider、model_providers、openai_base_url、notify 和 otel 应放在用户级配置中。项目配置包含这些字段时，Codex 会忽略它们并给出启动警告。

本地状态默认保存在 CODEX_HOME，也就是 ~/.codex。除了 config.toml，这里还可能出现 auth.json、history、日志和缓存。它们不是应该提交到仓库的团队配置。

配置优先级 ​

官方当前给出的优先级如下，数字越小优先级越高：

requirements.toml 不是普通覆盖层。它由组织管理员下发，用于禁止高风险值或限制可用 permission profiles。即使命令行优先级最高，也不能越过管理策略。

基础配置 ​

官方 Config basics 当前使用下面的模型示例：

toml
model = "gpt-5.6"
model_provider = "openai"
model_reasoning_effort = "high"
personality = "pragmatic"

实际可用模型取决于账号、客户端版本和工作区策略。TUI 中 /model 展示的目录应作为当前环境的准确信息源。

审批策略 ​

approval_policy 控制 Codex 何时提出人工审批：

  • untrusted：只自动运行已知安全的读取命令
  • on-request：由 Agent 在需要越界时申请
  • never：不弹审批，无法执行的动作直接返回给模型

日常交互配置通常使用：

toml
approval_policy = "on-request"

on-failure 已经弃用。交互任务使用 on-request，无人值守任务根据风险选择 never 和足够严格的 sandbox。

旧式沙箱 ​

稳定且兼容性最广的配置仍然是：

toml
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
writable_roots = []
network_access = false

可选值是 read-only、workspace-write 和 danger-full-access。本地 Codex 默认关闭 shell 命令的网络访问；workspace-write 也会保护 .git、.codex 等敏感路径。

Web 搜索 ​

Web 搜索不使用 shell 网络权限。当前可选模式有四种：

toml
web_search = "cached"
# web_search = "indexed"
# web_search = "live"
# web_search = "disabled"
  • cached：默认值，使用 OpenAI 维护的缓存索引
  • indexed：只有搜索索引允许时才进行外部访问
  • live：获取最新网页，与 CLI 的 --search 相同
  • disabled：移除 Web 搜索工具

旧的 [features] 下 web_search、web_search_cached 和 web_search_request 开关已经弃用，应迁移到顶层 web_search。

Permission Profiles ​

Permission profiles 是 beta 功能，用一个名字同时描述文件系统和网络边界。Codex 内置：

  • :read-only
  • :workspace
  • :danger-full-access

它与旧式沙箱是两套互斥系统：

不要在同一配置链中同时写 sandbox_mode 和 default_permissions。只要任一加载层包含 sandbox_mode，或命令行传入 --sandbox，Codex 就会回到旧式 sandbox 设置。

一个基于内置 :workspace 的自定义示例：

toml
default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit]
description = "允许修改工作区，只访问 OpenAI API"
extends = ":workspace"

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"

network.enabled = true 只负责开放命令网络。要让 domains 规则真正限制目标域名，还必须启用 features.network_proxy；否则命令得到的是不受该域名表约束的直接网络访问。

Profiles ​

Codex 0.134.0 起不再读取 config.toml 中的 [profiles.<name>]，顶层 profile = "..." 也不再支持。每个 profile 现在使用独立文件：

toml
# ~/.codex/deep-review.config.toml
model = "gpt-5.6-terra"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"

调用方式：

sh
codex --profile deep-review
codex exec --profile deep-review "review this change"

profile 位于用户配置之上、项目配置之下，因此只需要保存与 ~/.codex/config.toml 不同的值。profile 由 CLI 的 --profile 选择，项目配置不能替使用者选择 profile。

AGENTS.md ​

AGENTS.md 提供持久项目指令，不负责模型、认证或 sandbox 参数。Codex 每次启动时构建一次指令链，TUI 中通常意味着每个新 session 读取一次。

发现顺序如下：

  1. 在 CODEX_HOME 中优先读取 AGENTS.override.md，否则读取 AGENTS.md
  2. 从项目根到当前目录逐层查找指令文件
  3. 每层依次尝试 AGENTS.override.md、AGENTS.md 和 fallback 文件名，只采用第一个非空文件
  4. 按根目录到当前目录的顺序拼接，较近目录中的后置指令优先

指令链默认受 32 KiB 总量限制。可以配置替代文件名和读取上限：

toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

建议按职责拆分：

  • ~/.codex/AGENTS.md：个人跨项目习惯
  • 仓库根 AGENTS.md：团队级构建、验证和边界
  • 子目录 AGENTS.md 或 AGENTS.override.md：模块级特殊要求

规则文件应保持简短。详细架构和流程可以放进仓库文档，再由 AGENTS.md 提供索引。

MCP ​

MCP 配置可以放在用户级或受信任项目的 config.toml，ChatGPT desktop app、CLI 和 IDE extension 在同一 Codex host 上共享。

CLI 添加 ​

sh
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

TOML 配置 ​

toml
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"
required = true
startup_timeout_sec = 10
tool_timeout_sec = 60
default_tools_approval_mode = "prompt"

当前常用字段包括：

  • stdio：command、args、env、env_vars、cwd
  • HTTP：url、auth、bearer_token_env_var、http_headers
  • 生命周期：enabled、required、startup_timeout_sec、tool_timeout_sec
  • 工具范围：enabled_tools、disabled_tools
  • 审批：default_tools_approval_mode 和单工具 approval_mode

required = true 表示服务初始化失败时，本次启动也失败，适合工作流无法缺少的工具。工具审批可使用 auto、prompt、writes 和 approve。

Hooks 与 Rules ​

Hooks 已是 stable 功能，可以从 hooks.json 或同层 config.toml 的 [hooks] 加载。项目 Hook 只在 trusted 项目中生效，用户级 Hook 不受项目 trust 状态影响。

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

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/check_command.py"'
timeout = 30
statusMessage = "检查命令"

同一配置层同时存在 hooks.json 和内联 [hooks] 时，两者都会加载并产生警告。每层选择一种表示方式更容易维护。

Rules 是针对 shell 命令的 execpolicy，决定匹配命令是允许、询问还是禁止。Hooks 则可以在生命周期事件上运行自定义检查。前者适合静态命令策略，后者适合需要执行脚本的机械验证。

Skills 与 Plugins ​

Skills 和 Plugins 不应塞进 AGENTS.md 或手工展开到 config.toml：

  • 个人 Skill 放在 ~/.agents/skills
  • 团队 Skill 可以提交到仓库的 .agents/skills
  • Plugin 可以打包 Skills、MCP servers、Hooks 和其他资源
  • CLI 使用 /skills、/plugins 或 codex plugin 浏览和管理

AGENTS.md 适合稳定的项目约束，Skill 适合可重复的方法，Plugin 适合可安装和分发的能力集合。

起步配置 ​

继续使用稳定的旧式 sandbox 时，一份简短配置已经足够：

toml
model = "gpt-5.6"
model_provider = "openai"
model_reasoning_effort = "high"
personality = "pragmatic"

approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

[sandbox_workspace_write]
network_access = false

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

项目约束继续写在仓库根的 AGENTS.md。需要细粒度文件和域名规则时，再整体迁移到 permission profiles，不要把两套权限配置叠在一起。

遇到配置问题时，优先使用：

sh
codex doctor

TUI 中的 /debug-config 可以显示配置层与管理要求，--strict-config 则会在当前版本无法识别字段时直接报错。

参考 ​