1. 引言

在前几篇文章里，博主已经编写了Codex相关的文章，有兴趣的童鞋可以先阅读：

• 《Codex 完整指南（一）：快速入门｜工程级 AI 编程代理》
• 《Codex 完整指南（二）：核心概念详解｜工程级 AI 编程智能体》
• 《Codex 完整指南（三）：OpenAI 官方实战指南整理｜251 篇（最新）》
• 《Codex 完整指南（四）：多端使用全景图｜IDE、CLI、Cloud 与团队集成》
• 《Codex 完整指南（五）：config.toml 配置详解｜模型、审批与沙箱机制》

在本文中，博主继续整理Codex配置部分的内容，将围绕 Rules、AGENTS.md、自定义提示词 以及 MCP 四个核心主题展开，深入解析 Codex 在安全控制、指令发现、提示复用与工具扩展方面的设计哲学与最佳实践，从而让大家更好地去了解codex。

2. 规则

描述：控制 Codex 在沙箱外可以运行哪些命令
原文地址：https://developers.openai.com/codex/rules

可以使用规则（Rules）来控制 Codex 在沙箱（sandbox）之外可以运行的命令。

2.1 创建规则文件

Step1：首先在 ~/.codex/rules 目录下创建一个 .rules 文件（例如：~/.codex/rules/default.rules）。

Step2：添加一条规则，下面这个示例会在 允许 gh pr view 在沙箱外运行之前进行提示确认。

# 在沙箱外运行以 `gh pr view` 为前缀的命令前进行提示。
prefix_rule(
    # 要匹配的命令前缀。
    pattern = ["gh", "pr", "view"],

    # 当 Codex 请求运行匹配的命令时采取的动作。
    decision = "prompt",

    # 该规则存在的可选说明理由。
    justification = "在获得批准的情况下允许查看 PR",

    # `match` 和 `not_match` 是可选的“内联单元测试”，
    # 用于提供应该（或不应该）匹配该规则的命令示例。
    match = [
        "gh pr view 7888",
        "gh pr view --repo openai/codex",
        "gh pr view 7888 --json title,body,comments",
    ],
    not_match = [
        # 不匹配，因为 `pattern` 必须是一个精确的前缀。
        "gh pr --repo openai/codex view 7888",
    ],
)

Step3：重启，Codex在启动时加载 ~/.codex/rules 目录下的所有 *.rules 文件，当你在 TUI（终端交互界面）中将某个命令加入允许列表时，Codex 会自动把对应规则追加到~/.codex/rules/default.rules，这样以后运行时就可以跳过提示。

---

2.2 理解规则字段

prefix_rule() 支持以下字段：

pattern（必填）：一个非空列表，用于定义要匹配的命令前缀，列表中的每个元素可以是：

• 一个字面量字符串（例如 "pr"）
• 一个字面量联合（例如 ["view", "list"]），用于在该参数位置匹配多种可能

decision（默认值为 "allow"）：当规则匹配时采取的动作，当有多条规则同时匹配时，Codex 会选择限制性最强的决策（forbidden > prompt > allow）。可选值包括：

• allow：无需提示，直接在沙箱外运行命令
• prompt：每次匹配时都进行提示确认
• forbidden：不提示，直接阻止该请求

justification（可选）：一段非空的、对人类可读的规则说明，Codex 可能会在审批提示或拒绝信息中展示该内容。当你使用 forbidden 时，建议在说明中给出可替代方案，例如：“请使用 rg 代替 grep。”

match 和 not_match（默认值为 []）：用于在加载规则时由 Codex 验证的示例命令，它们可以帮助你在规则生效前发现错误配置。

当 Codex 判断是否运行某条命令时，会将该命令的参数列表与 pattern 进行比较。在内部，Codex 会把命令当作一个参数数组处理（类似 execvp(3) 接收到的形式）。

---

2.3 Shell 包装器与复合命令

有些工具会把多个 shell 命令包装成一次调用，例如：

["bash", "-lc", "git add . && rm -rf /"]

由于这种形式可能在一个字符串中隐藏多个操作，
Codex 会对 bash -lc、bash -c 以及它们在 zsh / sh 中的等价形式进行特殊处理。

---

① 当 Codex 拆分脚本

如果 shell 脚本是一个简单、线性的命令链，并且只包含：

• 普通单词（不包含变量展开、VAR=...、$FOO、* 等）
• 使用安全操作符连接（&&、||、; 或 |）

那么 Codex 会使用 tree-sitter 对脚本进行解析，并在应用规则之前将其拆分为多个独立命令。

例如，上面的脚本会被拆分为两个命令：

["git", "add", "."]
["rm", "-rf", "/"]

Codex 会分别对每个命令应用规则，并最终采用限制性最强的结果。因此，即使你允许了：

pattern = ["git", "add"]

Codex 也不会自动允许：

git add . && rm -rf /

因为 rm -rf / 会被单独评估，并阻止整个命令的自动执行。这种机制可以防止把危险命令“夹带”在安全命令中一起执行。

---

② 当Codex 不拆分脚本

如果脚本使用了更复杂的 shell 特性，例如：

• 重定向（>、>>、<）
• 命令替换（$(...)、...）
• 环境变量（FOO=bar）
• 通配符（*、?）
• 控制流（if、for、带赋值的 && 等）

那么 Codex 不会尝试解析或拆分脚本。在这种情况下，整个调用会被当作一个单独命令处理：

["bash", "-lc", "<完整脚本>"]

规则也只会应用在这一次调用上。通过这种特殊处理方式，在安全可解析时实现逐命令评估，在无法确定安全性时采取更保守的行为。

---

2.4 测试规则文件

可以使用以下命令来测试规则对某个命令的影响：

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 7888 --json title,body,comments

该命令会输出 JSON，展示：

• 最严格的决策结果
• 所有匹配到的规则
• 以及规则中包含的 justification 信息

可以使用多个 --rules 参数来组合多个规则文件，并使用 --pretty 让输出结果更易读。

---

2.5 理解规则语言

.rules 文件使用 Starlark 语言编写（可参考其语言规范）。它的语法类似 Python，但被设计为安全可执行，规则引擎可以运行它而不会产生副作用（例如访问或修改文件系统）。

3. AGENTS

描述：为你的项目向 Codex 提供额外的指令和上下文
原文链接：https://developers.openai.com/codex/guides/agents-md

Codex 在开始任何工作之前都会读取 AGENTS.md 文件，通过将全局指导与项目级别的覆盖规则分层组合，你可以在打开任何仓库时，都以一致的预期开始每一个任务。

3.1 Codex 如何发现指令

Codex 在启动时会构建一条指令链（每次运行一次，在 TUI 中通常意味着每次启动一个会话）。指令发现遵循以下优先级顺序：

---

全局作用域（Global scope）：在你的 Codex 主目录中（默认为 ~/.codex，除非你设置了 CODEX_HOME），Codex 会：

• 如果存在 AGENTS.override.md，则读取它
• 否则读取 AGENTS.md
• 在这一层级中，Codex 只会使用第一个非空文件

---

项目作用域（Project scope）：从项目根目录（通常是 Git 根目录）开始，Codex 会向下遍历到你当前的工作目录：

• 如果 Codex 无法找到项目根目录，则只检查当前目录

• 在路径上的每一个目录中，依次检查：

  1. AGENTS.override.md
  2. AGENTS.md
  3. project_doc_fallback_filenames 中配置的备用文件名

• 每个目录最多只会包含一个指令文件

---

合并顺序（Merge order）：

• Codex 会从根目录向下拼接这些文件，并用空行连接
• 越靠近当前工作目录的文件优先级越高，因为它们在合并后的提示中出现得更晚

Codex 会跳过空文件，并在合并内容达到 project_doc_max_bytes 定义的大小上限时停止（默认是 32 KiB）。有关这些参数的详细说明，请参阅 Project instructions discovery。当你触及大小上限时，可以提高限制，或将指令拆分到更深层的子目录中。

---

3.2 创建全局指引

在 Codex 主目录中创建持久化的默认规则，让每一个仓库都能继承你的工作约定。

Step1：需要确保目录存在：

mkdir -p ~/.codex

Step2： 创建 ~/.codex/AGENTS.md，写入可复用的偏好设置：

# ~/.codex/AGENTS.md

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

Step3：在任意位置运行 Codex，确认它加载了该文件：

codex --ask-for-approval never "Summarize the current instructions."

预期结果：Codex 会在提出工作建议之前，引用 ~/.codex/AGENTS.md 中的条目。

当你需要临时的全局覆盖规则而又不想删除基础文件时，可以使用~/.codex/AGENTS.override.md，删除该 override 文件即可恢复共享指引。

---

3.3 分层设置项目指令

仓库级别的文件可以让 Codex 了解项目规范，同时仍然继承你的全局默认规则。

Step1：在仓库根目录中添加 AGENTS.md，用于基础设置：

# AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

Step2：当特定团队需要不同规则时，在子目录中添加覆盖文件

例如，在 services/payments/ 目录下创建 AGENTS.override.md：

# services/payments/AGENTS.override.md

## Payments service rules

- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

Step3：从 payments 目录启动 Codex

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

预期结果：Codex 会依次报告 “全局指令文件” → “仓库根目录的 AGENTS.md” → “payments 目录下的 override 文件（最后加载）”

Codex 在到达当前工作目录后就会停止搜索，因此应尽量将 override 文件放在 最接近具体工作的目录中。添加了全局文件和 payments 专用 override 之后，一个示例仓库结构如下：

---

3.4 自定义备用文件名

如果你的仓库已经使用了不同的文件名（例如 TEAM_GUIDE.md），可以将它加入备用列表，让 Codex 将其视为指令文件。

可以编辑 Codex 配置：

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

然后重启 Codex，或运行一条新命令，使更新后的配置生效，Codex 会按以下顺序检查每个目录：

• AGENTS.override.md ↓
• AGENTS.md ↓
• TEAM_GUIDE.md ↓
• .agents.md ↓

不在该列表中的文件名将被忽略，更大的字节限制允许在被截断之前合并更多指引内容。在配置了 fallback 列表后，Codex 会将这些替代文件当作指令文件处理：

如果需要使用不同的配置（例如：项目专用的自动化用户）时，可以设置 CODEX_HOME 环境变量：

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

预期结果：输出会列出相对于自定义 .codex 目录的指令文件。

---

3.5 验证配置

可以在仓库根目录运行如下命令，Codex 应按优先级顺序回显全局和项目指令：

codex --ask-for-approval never "Summarize the current instructions."

使用子目录验证覆盖规则：

codex --cd subdir --ask-for-approval never "Show which instruction files are active."

如果需要审计 Codex 加载了哪些指令文件：

• 查看 ~/.codex/log/codex-tui.log
• 或（如果启用了会话日志）查看最新的 session-*.jsonl 文件

如果指令看起来是旧的：

• 在目标目录中重启 Codex
• Codex 会在每次运行时（以及每个 TUI 会话开始时）重建指令链，因此无需手动清缓存

---

3.6 问题排查

① 什么都没加载

• 确认你在正确的仓库中
• 检查 codex status 是否显示了你期望的工作区根目录
• 确保指令文件中有内容（空文件会被忽略）

② 出现了错误的指引

• 检查目录树中更高层是否存在 AGENTS.override.md（包括 Codex 主目录）
• 重命名或删除 override 文件即可回退到普通文件

③ Codex 忽略了 fallback 文件名

• 确认你已正确配置 project_doc_fallback_filenames，且无拼写错误
• 重启 Codex 以使配置生效

④ 指令被截断

• 提高 project_doc_max_bytes
• 或将大型文件拆分到嵌套目录中

⑤ 配置档案混乱（Profile confusion）

• 在启动 Codex 前运行：

  echo $CODEX_HOME
  

• 非默认值意味着 Codex 正在使用与你编辑的不同主目录

4. 自定义提示词

描述：定义可复用的提示，使其像斜杠命令一样工作
原文地址：https://developers.openai.com/codex/custom-prompts

自定义提示允许你将 Markdown 文件 转换为可复用的提示，并且可以在 Codex CLI 和 Codex IDE 扩展中通过斜杠命令来调用。自定义提示需要 显式调用，并且存放在你本地的 Codex 主目录中（例如 ~/.codex），因此不会随着你的代码仓库共享，如果希望共享一个提示（或者希望 Codex 能够隐式调用它），请使用 skills。接下来看看如何自定义提示词。

4.1 创建文件

首先创建 prompts 目录：

mkdir -p ~/.codex/prompts

然后创建 ~/.codex/prompts/draftpr.md，并添加可复用的指导内容：

---
description: Prep a branch, commit, and open a draft PR
argument-hint: [FILES=<paths>] [PR_TITLE="<title>"]
---

Create a branch named `dev/<feature_name>` for this work.
If files are specified, stage them first: $FILES.
Commit the staged changes with a clear message.
Open a draft PR on the same branch. Use $PR_TITLE when supplied; otherwise write a concise summary yourself.

最后重启 Codex 以加载新的提示（重启 CLI 会话；如果你在使用 IDE 扩展，请重新加载扩展）。

预期效果：在斜杠命令菜单中输入 /prompts:draftpr，你会看到自定义命令，其描述来自 front matter，并提示文件和 PR 标题是可选参数。

---

4.2 添加元数据和参数

Codex 会在下次会话启动时读取提示元数据并解析占位符。

• Description：显示在弹出窗口中命令名称下方。通过 YAML front matter 中的 description: 设置。
• Argument hint：使用 argument-hint: KEY=<value> 来说明期望的参数。
• 位置占位符（Positional placeholders）：$1 到 $9 会从你在命令后提供的、以空格分隔的参数中展开，$ARGUMENTS 包含所有这些参数。
• 命名占位符（Named placeholders）：使用大写名称（如 $FILE 或 $TICKET_ID），并通过 KEY=value 形式提供值，包含空格的值需要加引号（例如：FOCUS="loading state"）。
• 字面量美元符号：使用 $$ 来输出一个单独的 $。
• 在编辑提示文件后，重启 Codex 或打开一个新的聊天以加载更新，Codex 会忽略 prompts 目录中非 Markdown 的文件。

---

4.3 调用和管理自定义命令

在 Codex（CLI 或 IDE 扩展）中，输入 / 打开斜杠命令菜单。输入 prompts: 或直接输入提示名称，例如：

/prompts:draftpr

提供所需参数：

/prompts:draftpr FILES="src/pages/index.astro src/lib/api.ts" PR_TITLE="Add hero animation"

按 Enter 发送展开后的指令（当不需要某个参数时，可以省略它）。

预期效果：Codex 会展开 draftpr.md 的内容，用你提供的参数替换占位符，然后将结果作为一条消息发送。

可以通过编辑或删除 ~/.codex/prompts/ 目录下的文件来管理提示，Codex 只扫描该文件夹顶层的 Markdown 文件，因此请将每个自定义提示直接放在 ~/.codex/prompts/ 下，而不要放在子目录中。

5. MCP

描述：为 Codex 提供对第三方工具和上下文的访问能力
原文地址：https://developers.openai.com/codex/mcp

模型上下文协议（Model Context Protocol，简称 MCP）用于将模型连接到工具和上下文，你可以使用它让 Codex 访问第三方文档，或让它与开发者工具（如浏览器或 Figma）进行交互，Codex 在 CLI 和 IDE 扩展中都支持 MCP 服务器。

---

5.1 支持的 MCP 功能

• STDIO 服务器：作为本地进程运行的服务器（通过命令启动）

• 可流式的 HTTP 服务器：通过地址访问的服务器

  • Bearer Token 认证
  • OAuth 认证（对于支持 OAuth 的服务器，运行 codex mcp login <server-name>）

5.2 连接 MCP 服务器

Codex 会将 MCP 配置存储在 ~/.codex/config.toml 中，与其他 Codex 配置项放在一起，CLI 与 IDE 扩展 共享同一份配置，一旦配置好了 MCP 服务器，就可以在两个 Codex 客户端之间切换，而无需重新设置。

要配置 MCP 服务器，可以选择以下方式之一：

• 使用 CLI：运行 codex mcp 来添加和管理服务器。
• 编辑 config.toml：直接修改 ~/.codex/config.toml。

---

5.2.1 CLI 配置 MCP

添加一个 MCP 服务器

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

例如，要添加 Context7（一个免费的开发者文档 MCP 服务器），可以运行以下命令：

codex mcp add context7 -- npx -y @upstash/context7-mcp

要查看所有可用的 MCP 命令，可以运行：

codex mcp --help

5.2.2 config.toml 配置 MCP

如果需要对 MCP 服务器选项进行更精细的控制，可以编辑 ~/.codex/config.toml，在 IDE 扩展中，可以通过齿轮菜单选择 MCP settings > Open config.toml 来打开该文件。

在配置文件中，为每个 MCP 服务器使用一个 [mcp_servers.<server-name>] 表进行配置。相关参数配置如下：

---

STDIO 服务器

• command（必填）：启动服务器的命令。
• args（可选）：传递给服务器的参数。
• env（可选）：为服务器设置的环境变量。
• env_vars（可选）：允许并转发的环境变量。
• cwd（可选）：启动服务器时使用的工作目录。

---

可流式的 HTTP 服务器

• url（必填）：服务器地址。
• bearer_token_env_var（可选）：用于在 Authorization 中发送 Bearer Token 的环境变量名。
• http_headers（可选）：请求头名称到静态值的映射。
• env_http_headers（可选）：请求头名称到环境变量名的映射（值从环境变量中读取）。

---

其他配置选项

• startup_timeout_sec（可选）：服务器启动超时时间（秒），默认值：10；
• tool_timeout_sec（可选）：服务器运行工具的超时时间（秒），默认值：60；
• enabled（可选）：设置为 false 可在不删除服务器的情况下禁用它；
• enabled_tools（可选）：允许使用的工具白名单；
• disabled_tools（可选）：禁止使用的工具黑名单（在 enabled_tools 之后生效）。

---

config.toml 示例

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # 在 enabled_tools 之后生效
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

---

5.3 常用的 MCP 服务器示例

MCP 服务器的列表仍在不断增长，以下是一些常见示例：

• OpenAI Docs MCP：搜索并阅读 OpenAI 开发者文档。
• Context7：连接到最新的开发者文档。
• Figma Local 和 Remote：访问你的 Figma 设计。
• Playwright：使用 Playwright 控制和检查浏览器。
• Chrome Developer Tools：控制和检查 Chrome。
• Sentry：访问 Sentry 日志。
• GitHub：管理 GitHub（超出 git 本身支持的能力，例如拉取请求和 Issue）。

6. 文末

本文主要整理了 Codex 的 Rules（规则控制）、AGENTS.md（分层指令）、自定义提示词（Custom Prompts）与 MCP（工具扩展）等关键能力。希望能帮助到大家，谢谢大家的阅读，本文完。