更好使用 Codex 问答

版本：2026-07-05

定位：这是一篇把“如何更稳定、更省上下文、更适合长期使用 Codex”整理成问答形式的学习文档。它参考 openclaw-learning/docs/openclaw-architecture-evolution-qa.md 的写法，用“遇到问题 -> 选择配置层级 -> 继续落地”的方式说明 Codex 配置应该怎么拆。

说明：本文不是 Codex 全量配置手册，而是一份长期使用建议。具体配置项仍以官方文档为准。

0. 先给一个结论

问：更好使用 Codex 的核心原则是什么？

答：把不同性质的约束放到不同层级里，不要把所有规则都塞进一个超长提示词。

一句话说就是：

用 AGENTS.md 放少量项目硬规则，用 ~/.codex/AGENTS.md 放个人偏好，用 config.toml 放运行配置，用 profiles 切换工作模式，用 skills 承接重复流程，用 MCP / connectors 连接外部系统，用 hooks / rules 做机械约束。

问：为什么不能只写一个很长的提示词？

答：因为长提示词一开始很方便，长期会变成维护负担。

它会带来几个问题：

• Codex 每次开工都要背很多不一定用得上的内容。
• 真正重要的红线被淹没在细节里。
• 重复流程无法复用，只能反复复制。
• 外部事实容易靠模型记忆猜，过期风险高。
• 机械约束靠自然语言提醒，稳定性不够。

更好的办法是分层：该前置的前置，该按需加载的按需加载，该由工具判断的交给工具。

问：分层之后有什么直接收益？

答：主要是四点：

• Codex 开工前只背必要规则，上下文更轻。
• 复杂流程按需加载，减少信息过载。
• 规则、配置、工具和自动化各司其职，长期更好维护。
• 出错后可以把“反复出现的问题”沉淀到合适的层级里。

启发

更好使用 Codex 的关键，不是把提示词写得越来越长，而是让规则、配置、流程和外部事实各回各家。

1. 第一个问题：规则到底应该放在哪里？

问：Codex 的配置和指导是不是都属于同一种东西？

答：不是。它们看起来都在影响 Codex 行为，但性质不一样。

有些是项目规则，比如架构边界和测试命令。有些是个人偏好，比如默认中文回复。有些是运行配置，比如模型、权限、沙箱和网络。有些是重复流程，比如提交前检查。有些是外部系统能力，比如 GitHub、Figma、Sentry、浏览器和 OpenAI Docs。

把它们混在一起，就会出现一个典型问题：

明明只是想改默认模型，却不得不翻一大段项目规范；明明只是想沉淀提交流程，却把 AGENTS.md 写成了百科全书。

问：有哪些常用层级？

答：可以先按下面这张表来分。

问：怎么判断一条规则应该放在哪？

答：先问几个问题：

• 它是不是每次进入这个仓库都必须知道？如果是，放 AGENTS.md。
• 它是不是你个人跨项目偏好？如果是，放 ~/.codex/AGENTS.md。
• 它是不是可重复执行的流程？如果是，优先做成 skill。
• 它是不是确定性动作或命令权限？如果是，考虑 hooks / rules。
• 它是不是来自外部系统的当前事实？如果是，接 MCP / connector。

这套判断不追求一步到位。它更像整理房间：先把最容易混的东西分开，后面再慢慢收纳。

启发

规则分层不是为了显得配置很多，而是为了让每一类约束出现在最合适的位置。放错地方的规则，时间一长就会从帮助变成噪音。

2. 第二个问题：项目硬规则怎么放？

问：`AGENTS.md` 是什么？

答：AGENTS.md 是项目级持久指导。Codex 会在一次 run、一个 TUI session 或一个新线程开始时构建 instruction chain，读取全局和项目内的 AGENTS.md / AGENTS.override.md。

项目内越靠近当前工作目录的文件优先级越高。换句话说，根目录可以放通用规则，子目录可以放更具体的规则。

问：仓库根目录的 `AGENTS.md` 应该写多长？

答：建议较短，只放每次都必须知道的内容。

适合放：

• 架构红线。
• 安全和脱敏要求。
• 常用验证命令入口。
• 文档索引和按需读取路线。
• 工作前后流程。

不适合放：

• 长篇设计规范全文。
• 大量历史背景。
• 过细的 UI 规则。
• 每次对话记录模板全文。

问：为什么要控制 `AGENTS.md` 长度？

答：因为它属于前置上下文。前置上下文越重，Codex 每次开工越容易慢、保守、注意力分散。

一个好的 AGENTS.md 更像路标，不像教科书。它告诉 Codex“哪些边界不能碰，去哪里读细节”，而不是把所有细节都塞到门口。

问：本项目现在适合怎么处理？

答：本项目当前采用的是“轻前置 + 重后置”。

• 开工前：只读少量硬红线，避免方向性错误。
• 工作中：优先读代码事实和现有实现。
• 交付前：按 docs/Codex工作规则/交付校准规则.md 做后置校准。

本项目把高频但不必每次前置加载的流程拆到了 docs/Codex工作规则/，例如提交并 push、交付人工验收、对话归档和必要记录。AGENTS.md 只保留入口，Codex 根据任务类型按需补读。

问：什么时候应该更新 `AGENTS.md`？

答：当问题反复出现时。

例如：

• Codex 总是跑错测试命令。
• Codex 总是误解某个目录的职责。
• PR review 总是指出同一类规范问题。
• Codex 总是读太多文档，却漏掉关键入口。

这时就可以把“重复纠正”变成“持久指导”。不要因为一次偶发问题就塞规则，否则 AGENTS.md 很快会膨胀。

启发

AGENTS.md 更像项目入口处的路标，不是项目百科。它应该告诉 Codex 哪些边界不能碰，以及真正需要细节时去哪里看。

3. 第三个问题：个人偏好应该放哪里？

问：`~/.codex/AGENTS.md` 和项目 `AGENTS.md` 有什么区别？

答：全局 ~/.codex/AGENTS.md 适合放你的个人工作习惯，让所有项目都继承。项目 AGENTS.md 则应该放当前仓库的团队规则和代码事实。

可以这样理解：

问：个人偏好可以写什么？

答：可以写这类内容：

1# 个人 Codex 偏好2 3- 默认使用中文回复。4- 提交信息使用中文，简洁说明改动目的。5- 解释代码时优先给文件路径和关键行。6- 简单问题直接回答，复杂改动先简述方案再执行。7- 未明确要求时，不主动做大范围重构。

问：临时想覆盖全局规则怎么办？

答：可以用 ~/.codex/AGENTS.override.md。

它适合临时改变全局指导。临时任务结束后删除 override 文件，就会恢复原来的 ~/.codex/AGENTS.md。

问：个人偏好里能不能写项目架构细节？

答：不建议。项目架构细节属于仓库上下文，应该跟着仓库走。放到个人全局文件里，换一个项目就可能误导 Codex。

4. 第四个问题：运行配置怎么管理？

问：`config.toml` 管什么？

答：config.toml 管 Codex 的运行配置。它不是写项目规范的地方，而是配置模型、权限、沙箱、网络、MCP、hooks、rules 等行为。

常见位置有两个：

• ~/.codex/config.toml：个人默认配置。
• .codex/config.toml：项目级配置，项目需要被信任后才会加载。

问：常见配置长什么样？

答：例如：

1model = "gpt-5.5"2model_reasoning_effort = "high"3approval_policy = "on-request"4sandbox_mode = "workspace-write"5web_search = "cached"6personality = "friendly"

常见含义是：

• model：默认模型。
• model_reasoning_effort：推理力度，越高越适合复杂任务，但更慢、更耗上下文和额度。
• approval_policy：什么时候需要用户批准。
• sandbox_mode：Codex 能读写和执行命令的边界。
• web_search：网页搜索模式。
• personality：默认沟通风格。

问：配置优先级是什么？

答：大致是：

1. CLI 参数和 --config。
2. 项目 .codex/config.toml，从项目根目录到当前工作目录，越近越优先。
3. --profile 指定的 profile 文件。
4. ~/.codex/config.toml。
5. 系统配置。
6. 内置默认值。

问：项目 `.codex/config.toml` 有什么安全边界？

答：项目级配置只有在项目被信任后才会加载。这个限制很重要，因为项目配置可能影响 hooks、rules、MCP 和沙箱行为。

另外，私密凭据不要明文写进项目配置。需要 token 时，优先通过环境变量或对应连接器的授权流程处理。

启发

config.toml 管的是运行边界，不是写给模型看的长篇叮嘱。凡是能用配置稳定表达的东西，就不要只靠自然语言提醒。

5. 第五个问题：不同任务能不能用不同模式？

问：Profiles 解决什么问题？

答：Profiles 适合把不同任务的模型、推理强度、速度和权限封装成命名模式。

比如：

• 小改动用 fast。
• 架构审查用 review。
• 只读评估用 safe。

这样你不用每次都记一长串参数，只要切换 profile。

问：Profile 文件放在哪里？

答：每个 profile 是一个单独的 TOML 文件：

1~/.codex/<profile-name>.config.toml

使用方式：

1codex --profile fast2codex --profile review3codex --profile safe

问：`fast` profile 适合什么？

答：适合低风险、短反馈任务。

例如：

• 小改动。
• 快速排查。
• 文档小修。
• 低风险 UI 调整。

示例：

1# ~/.codex/fast.config.toml2model = "gpt-5.4-mini"3model_reasoning_effort = "medium"4model_reasoning_summary = "auto"5service_tier = "fast"6 7[features]8fast_mode = true

问：`review` profile 适合什么？

答：适合复杂、高风险、需要更深入推理的任务。

例如：

• 架构评估。
• 复杂重构。
• 代码审查。
• 高风险排查。

示例：

1# ~/.codex/review.config.toml2model = "gpt-5.5"3model_reasoning_effort = "xhigh"4model_reasoning_summary = "detailed"5service_tier = "priority"

问：`safe` profile 适合什么？

答：适合只读评估。你希望 Codex 看代码、分析方案，但不希望它改文件。

示例：

1# ~/.codex/safe.config.toml2model = "gpt-5.5"3model_reasoning_effort = "high"4sandbox_mode = "read-only"5approval_policy = "on-request"

问：如果只是临时覆盖一项配置呢？

答：可以直接用命令行：

1codex --model gpt-5.52codex -c model_reasoning_effort='"xhigh"'3codex -c sandbox_mode='"read-only"'

这适合一次性任务。长期常用的组合还是建议沉淀成 profile。

6. 第六个问题：重复流程怎么复用？

问：什么时候应该用 skill？

答：当某件事会重复发生，而且每次都有相似流程时，就适合做成 skill。

Skills 的价值是按需加载。它们不会像长 AGENTS.md 一样每次挤占上下文，但当任务匹配时，Codex 可以加载完整说明、参考资料和脚本。

问：哪些流程适合做成 skill？

答：例如：

• 提交并 push 前检查。
• 前端 UI 验收。
• 文档更新检查。
• 对话归档。
• 发布前 smoke test。
• PR review checklist。

问：一个 skill 长什么样？

答：一个 skill 通常是一个目录，里面有 SKILL.md，也可以带脚本、引用资料和资源。

示例：

1---2name: project-commit3description: 在本项目提交代码前执行检查、整理变更、生成中文 commit 并 push。4---5 61. 检查 git status，确认变更范围。72. 按风险运行最小必要验证。83. 不提交本地忽略目录。94. 使用中文 commit message。105. push 后确认远端状态。

问：写 skill 有什么建议？

答：可以记住四点：

• 一个 skill 只做一类事。
• description 写清触发场景，方便 Codex 自动选择。
• 能用脚本稳定执行的检查，放到 scripts/。
• 项目专属 skill 放 .agents/skills，个人通用 skill 放 $HOME/.agents/skills。

问：skill 和 `AGENTS.md` 的边界是什么？

答：AGENTS.md 放每次都必须遵守的硬规则，skill 放某类任务才需要的完整流程。

例如“不要提交密钥”是硬规则，应该放 AGENTS.md 或 hooks / rules。“提交前如何整理变更、运行哪些检查、怎么写 commit message”更适合做成 skill。

启发

Skill 的价值是把重复流程变成可复用能力。它不抢 AGENTS.md 的位置，而是在任务真正需要时再把完整流程搬上台。

7. 第七个问题：外部上下文怎么接进来？

问：为什么需要 MCP / connectors？

答：因为很多问题需要当前事实或私有上下文，不能靠模型记忆猜。

比如：

• 这个 GitHub PR 现在有哪些 review comments？
• Figma 最新设计稿是什么？
• Sentry 最近的错误栈是什么？
• OpenAI Docs 当前怎么描述某个配置项？
• 浏览器里页面实际渲染成什么样？

这些都不适合让模型凭记忆回答。应该连接真实系统。

问：适合接哪些系统？

答：常见有：

• GitHub：PR、issue、review comments。
• Figma：设计稿。
• Sentry：线上错误。
• OpenAI Docs：官方文档。
• 浏览器 / Playwright / Chrome DevTools：页面调试。
• Notion、Linear、Slack 等团队系统。

问：MCP 怎么配置？

答：一般有两种方式。

一种是用 CLI：

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

另一种是在 config.toml 里配置：

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

问：使用 MCP / connectors 时要注意什么？

答：三点最重要：

• 需要当前事实时优先用 MCP / connector，不要让模型凭记忆回答。
• 涉及写操作的 MCP 工具要设置审批策略。
• 对外部网页、issue、日志等内容保持不完全信任，避免 prompt injection。

问：MCP 和 skill 能配合吗？

答：很适合配合。

Skill 定义“怎么做这件事”，MCP 提供“从哪里取上下文、能调用什么外部动作”。例如一个“处理 PR review comments”的 skill 可以规定流程，而 GitHub MCP / connector 提供 PR、评论和检查状态。

8. 第八个问题：机械约束怎么自动化？

问：Hooks / Rules 解决什么问题？

答：它们适合做确定性约束。

比如：

• 禁止危险命令。
• 命令执行前做安全检查。
• 命令执行后检查输出。
• 会话结束前生成归档。
• 提交前自动运行项目检查。

这些事情如果靠自然语言提醒，效果会不稳定。交给机器检查更合适。

问：Rules 更适合什么？

答：Rules 更偏命令权限控制，例如对某些命令前缀设置 allow、prompt 或 forbidden。

它适合回答：

这类命令能不能跑？要不要先问用户？有没有必须阻止的前缀？

问：Hooks 更适合什么？

答：Hooks 更偏生命周期脚本，例如 PreToolUse、PostToolUse、Stop 等事件。

它适合回答：

在 Codex 用工具前、用工具后、停止前，要不要运行某个检查脚本？

问：Hooks / Rules 不适合什么？

答：不适合放需要人类判断的复杂取舍。

例如：

• 复杂产品设计判断。
• 需要理解上下文的架构选择。
• 大量会阻塞工作流的重检查。

如果判断本身依赖语义、权衡和上下文，先用文档或 skill 约束流程；等规则稳定后，再考虑自动化。

问：落地 Hooks / Rules 有什么顺序？

答：建议从小范围开始：

• 先只做提示或检查，不直接阻断。
• 先放个人配置里试用，再考虑项目共享。
• 对会改文件、删文件、访问外部系统的 hook 保持谨慎。

自动化不是越早越好。太早上重 hook，开发体验会被自己绊住。

启发

Hooks 和 Rules 适合管确定性的事。越需要人类判断的取舍，越不应该太早写成会硬拦路的自动化。

9. 第九个问题：应该按什么顺序落地？

问：如果从零开始整理 Codex 配置，先做什么？

答：推荐顺序是：

1. 整理 AGENTS.md

只保留硬规则和文档入口。

1. 补 ~/.codex/AGENTS.md

固化个人偏好，例如中文回复、中文 commit、回答风格。

1. 整理 ~/.codex/config.toml

设定默认模型、权限、沙箱、网络、风格。

1. 建立 profiles

至少准备 fast、review、safe 三种。

1. 把重复流程做成 skills

先做提交检查、前端验收、归档这类高频流程。

1. 按需要接 MCP / connectors

先接 OpenAI Docs、GitHub、浏览器，再考虑 Figma、Sentry。

1. 最后再加 hooks / rules

把确定性的安全和验证动作自动化。

问：为什么 hooks / rules 放最后？

答：因为它们会直接影响工作流。如果流程还没稳定，过早自动化容易把错误流程固定下来。

先让 Codex 人工执行 checklist，观察哪些步骤真的重复、稳定、可判断，再把它们升级为 hooks / rules。

10. 第十个问题：日常怎么用？

问：小改动怎么启动？

答：可以用：

1codex --profile fast --cd <project>

适合直接说：

1帮我修这个样式问题，改完跑最小验证。

问：深度审查怎么启动？

答：可以用：

1codex --profile review --cd <project>

适合直接说：

1帮我 review 最近一次提交，重点看架构边界、数据流和缺失测试。

问：只读评估怎么启动？

答：可以用：

1codex --profile safe --cd <project>

适合直接说：

1只评估，不改代码。帮我判断这个方案会不会破坏现有架构。

问：复杂任务应该怎么描述？

答：复杂任务尽量给 Codex 清晰完成标准。

例如：

1目标：修复移动端文章页侧栏错误。2要求：3- 不改服务端接口。4- 保持现有主题风格。5- 改完跑 client:type-check。6- 最后说明改了哪些文件。

问：为什么完成标准这么重要？

答：因为 Codex 做事不是只看“任务标题”，还要判断边界、验证方式和交付形式。

你给得越清楚，它越能少猜一点，少绕一点。

11. 第十一个问题：常见误区有哪些？

问：把 `AGENTS.md` 写成百科全书有什么问题？

答：上下文膨胀，模型回答变慢、变保守，还容易错过真正重要的硬规则。

建议：只放硬规则和索引，细则拆文档或 skill。

问：所有任务都用最高推理有什么问题？

答：小任务会变慢，成本也更高。

建议：小改用 fast，复杂任务再用 review。

问：让模型凭记忆回答当前事实有什么问题？

答：模型可能过期或猜错。

建议：产品文档、库 API、线上错误、PR 状态都尽量用 MCP / connector / 官方文档。

问：过早上 hooks 有什么问题？

答：hook 写得太重会让开发体验变差，还可能把不成熟流程固定下来。

建议：先让 Codex 人工执行 checklist，稳定后再自动化。

问：把安全要求写成“请注意安全”够吗？

答：不够。

自然语言提醒适合表达原则，但真正的安全边界要靠权限、沙箱、审批、rules、hooks、外部系统授权和代码检查一起承担。

12. 官方资料

问：想继续查官方资料，从哪里开始？

答：可以从这些入口开始：

• Custom instructions with AGENTS.md
• Customization
• Config basics
• Codex models
• Agent Skills
• Model Context Protocol
• Hooks
• Rules

13. 本项目当前建议

问：本项目现在已经做到哪一步？

答：本项目已经完成了第一步：AGENTS.md 保持短入口，细节拆到规则文档。

这个方向是对的。它让 Codex 开工时先看到硬规则和入口，真正需要细节时再读 docs/Codex工作规则/。

问：下一步可以继续做什么？

答：可以按这个顺序推进：

• 建立 safe profile，用于只读评估。
• 将 docs/Codex工作规则/提交规则.md 进一步沉淀为“提交并 push 前检查”skill。
• 将 docs/Codex工作规则/功能落地后自测和人工验收规则.md 进一步沉淀为“功能落地后自测和人工验收”skill。
• 把“对话归档”从人工规则逐步改成 hook 或 skill。
• 为常用外部系统配置 MCP / connectors。

问：最终希望达到什么状态？

答：希望 Codex 使用体验变成这样：

1少量硬规则前置2  -> 任务中按需读取文档和 skill3  -> 需要当前事实时调用 MCP / connector4  -> 确定性安全和验证交给 hooks / rules5  -> 交付前按项目规则校准

这不是为了把配置做复杂，而是为了让每一层只承担自己该承担的责任。用久以后，Codex 会更像一个熟悉项目边界的协作者，而不是每次都从一大段提示词里重新找方向。

14. 术语说明

按本文中首次出现的大致顺序排列。