在工程级 AI 编程代理 Codex 的生态中，强大的核心能力离不开精细化的配置。如果说模型是引擎，那么配置就是方向盘和导航系统，它决定了 AI 如何理解你的意图、在什么边界内行动，以及如何与外部世界交互。本文将深入探讨 Codex 配置体系中的四大支柱：安全规则（Rules）、智能体指令（AGENTS）、自定义提示词（Prompts）与模型上下文协议（MCP）。掌握这些配置，你将能真正驯服 AI 的创造力，使其成为安全、高效、贴合你工作流的智能编程伙伴。
一、 构筑安全防线：深入理解 Rules 规则引擎
在 AI 驱动的自动化中，安全是首要考量。Codex 的 Rules（规则） 系统正是为此而生，它允许你精确控制 AI 在沙箱之外可以执行哪些命令，有效防止误操作或恶意代码的执行。这类似于为 AI 助理设定了一份“行为守则”。
描述：控制 Codex 在沙箱外可以运行哪些命令
原文地址：https://developers.openai.com/codex/rules
规则文件创建于 ~/.codex/rules.rulespattern 和相应的 decision（允许、提示或禁止）。一个典型的规则示例如下：
# 在沙箱外运行以 `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",
],
)Codex 在启动时会加载所有规则文件。当你在终端界面（TUI）中将某个命令加入允许列表时，Codex 会自动将对应规则追加到 ~/.codex/rules/default.rules
一个高级特性是对 Shell 包装器和复合命令的处理。对于简单的线性命令链，Codex 会使用 tree-sitter 进行解析并拆分为独立命令，分别应用规则，并采用限制性最强的结果。这防止了将危险命令“夹带”在安全命令中执行。例如：
["bash", "-lc", "git add . && rm -rf /"]对于包含重定向、变量展开或控制流等复杂特性的脚本，Codex 则将其视为一个整体进行评估，采取更保守的策略。你可以使用 codex rules test 命令来测试规则对特定命令的影响，确保配置符合预期。
二、 塑造 AI 认知：分层指令系统 AGENTS
如何让 Codex 在不同的项目和场景下都保持一致的“工作风格”？答案在于 AGENTS.md 指令文件。这是一个基于 Markdown 的分层指令系统，让 AI 在开始工作前就能了解你的全局偏好和项目特定要求。
描述：为你的项目向 Codex 提供额外的指令和上下文
原文链接：https://developers.openai.com/codex/guides/agents-md
Codex 发现指令遵循明确的优先级顺序，从全局到局部：
- 全局作用域：在 Codex 主目录（如
~/.codexAGENTS.md或AGENTS.md - 项目作用域：从项目根目录向下遍历至当前工作目录，查找
AGENTS.md或配置的备用文件名。
指令文件会从根目录向下拼接，越靠近当前工作目录的文件优先级越高。这种设计实现了指令的继承与覆盖。例如，你可以在全局文件中定义通用的代码风格（如使用 TypeScript），在项目根目录的 AGENTS.md 中定义项目框架和依赖规范，在某个子目录（如 payments/）中进一步定义该模块的特定业务逻辑和测试要求。
创建全局指引只需在 Codex 主目录创建文件：
mkdir -p ~/.codex# ~/.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.项目级别的覆盖则通过在相应目录创建 AGENTS.md 实现。Codex 的这种分层认知模型，极大地提升了 AI 在不同上下文中的适应性和准确性，是机器学习工程化实践的重要体现。
三、 复用最佳实践：打造自定义提示词库
除了被自动加载的指令，Codex 还支持自定义提示词（Custom Prompts）。你可以将常用的、复杂的任务指令保存为 Markdown 文件，并通过斜杠命令（/）随时调用，实现提示的标准化和复用。
描述：定义可复用的提示，使其像斜杠命令一样工作
原文地址：https://developers.openai.com/codex/custom-prompts
自定义提示存放在本地的 ~/.codex
mkdir -p ~/.codex/prompts---
description: Prep a branch, commit, and open a draft PR
argument-hint: [FILES=] [PR_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.</code></pre>
<p>更强大的是，你可以为提示添加元数据和参数，使其像函数一样可调用。通过 YAML front matter 添加描述，在内容中使用占位符：</p><ul><li><strong>位置占位符</strong>：<code><code>$1</code></code> 到 <code><code>$9</code></code> 对应命令后空格分隔的参数。</li><li><strong>命名占位符</strong>：使用如 <code><code>$FILE</code></code> 的大写名称，通过 <code>NAME=value</code> 形式传值。</li></ul><p>这让你可以创建如“为 <code><code>$1</code></code> 函数编写单元测试，覆盖 <code><code>$FILE</code></code> 场景”这样的动态提示。通过 <code>codex prompts list</code> 和 <code>codex prompts show</code> 可以方便地管理你的提示库。</p><p>[AFFILIATE_SLOT_1]</p><h2>四、 扩展 AI 能力：连接外部工具的桥梁 MCP</h2><p>Codex 的真正威力在于其可扩展性，而 <strong>模型上下文协议（Model Context Protocol, MCP）</strong> 正是实现这一点的关键。MCP 是一个开放协议，允许 Codex 连接各种外部服务器（MCP 服务器），从而获取动态数据、执行特定操作或访问专用工具。</p><p><blockquote><p><strong>预期效果</strong>：Codex 会展开 的内容，用你提供的参数替换占位符，然后将结果作为一条消息发送。</p></blockquote></p><p>目前，Codex 主要支持 MCP 的 <strong>资源（Resources）</strong> 和 <strong>工具（Tools）</strong> 功能。资源让 Codex 能读取外部数据源（如数据库、API），工具则允许 Codex 调用外部函数（如发送通知、执行部署）。</p><p>连接 MCP 服务器有两种主要方式：</p><ol><li><strong>通过 CLI 临时配置</strong>：使用 <code>codex config mcp add</code> 命令。</li><li><strong>通过配置文件持久化</strong>：在 <code>config.toml</code> 中添加 <code>[[mcp_servers]]</code> 部分。</li></ol><p>一个连接 GitHub 议题查看器的配置示例如下：</p>
<pre style="white-space: pre !important; word-wrap: normal !important; overflow-x: auto !important;"><code class="prism language-text">/prompts:draftpr</code></pre>
<p>社区已经涌现了许多实用的 MCP 服务器，例如：</p><ul><li><strong>文件系统浏览器</strong>：让 AI 能“看到”并摘要本地文件。</li><li><strong>Git 历史查询器</strong>：提供代码变更上下文。</li><li><strong>网页抓取器</strong>：获取在线文档内容。</li><li><strong>日历/邮件集成</strong>：结合日程安排任务。</li></ul><p>通过 MCP，Codex 从一个封闭的代码生成器，进化成了一个能够利用<strong>深度学习</strong>和<strong>自然语言处理</strong>能力，与整个数字生态系统交互的<strong>中心化智能体</strong>。</p><h2>五、 配置实战与问题排查</h2><p>将上述配置组合使用，能构建出强大的个性化工作流。例如，你可以：</p><ol><li>用 <strong>Rules</strong> 禁止生产环境的直接数据库写操作。</li><li>用 <strong>AGENTS.md</strong> 在项目根目录定义代码审查清单，在组件目录定义具体实现模式。</li><li>用 <strong>自定义提示</strong> 封装“生成数据库迁移脚本”的复杂指令。</li><li>通过 <strong>MCP</strong> 连接内部文档服务器，让 Codex 在编写代码时参考最新的 API 规范。</li></ol><p>遇到问题时，可以按以下思路排查：</p><ul><li> <strong>指令未加载</strong>：检查工作目录、文件是否有内容、路径是否正确。</li><li>⚠️ <strong>规则未生效</strong>：使用 <code>codex rules test</code> 命令测试，检查规则文件语法和决策优先级。</li><li> <strong>MCP 连接失败</strong>：检查服务器是否运行、配置参数是否正确、网络是否通畅。</li><li>✅ 善用 <code>codex config validate</code> 和 <code>codex --debug</code> 命令进行验证和调试。</li></ul><p>[AFFILIATE_SLOT_2]</p><h2>结语：迈向工程化的 AI 协作</h2><p>通过对 Rules、AGENTS、Prompts 和 MCP 的深度配置，Codex 从一个通用的代码生成工具，转变为一个可预测、可控制、可扩展的工程级 AI 编程智能体。这不仅仅是工具的配置，更是一种<strong>人机协作范式</strong>的建立。它要求开发者像设计系统一样设计 AI 的交互流程，像编写文档一样编写 AI 的认知指令。这种将<strong>机器学习</strong>能力工程化、流程化的实践，正是 AI 真正融入核心生产环节的关键一步。开始定制你的 Codex，让它不仅仅是助手，更是你团队中一位理解规范、遵守安全、能力不断扩展的超级成员。</p><code>draftpr.md</code>
---
<div style='background:#ecfdf5;padding:20px;border-left:3px solid #10b981;border-radius:6px;margin-top:30px;'>
<h3 style='color:#047857;margin-top:0;font-size:16px;'> 推荐阅读</h3>
<p style='color:#666;font-size:13px;margin-bottom:12px;'>根据本文内容，精选以下优质课程：</p>
<ul style='line-height:2;font-size:14px;padding-left:20px;'>
<li><strong><a href='https://time.geekbang.org/column/intro/100541001?code=0vGatnUVCN3A8vOzLu2Iv8ZbE9RmumCZ4RpLIeMW-3k%3D' target='_blank' rel='nofollow' style='color:#059669;'>AI大模型之美</a></strong><br/>
<span style='color:#888;font-size:13px;'> 徐文浩 | 快速上手新一代AI应用开发，掌握大模型核心能力</span></li>
</ul>
</div>
浙公网安备 33010602011771号