Codex

整理时间：2026-05-15
来源：OpenAI 官方文档、GitHub 仓库（82.8k ⭐）、社区讨论、一线用户经验
分类：AI / Codex

一、AGENTS.md 配置原则

核心原则：保持简短、精准

• 控制在 100 行以内，硬上限 300 行
• Codex 系统提示已占用大量上下文，AGENTS.md 只放 Codex 可能忽略的信息
• 能从代码推断的内容不要写进去（如：export default function 是 React 组件——Codex 知道）
• 规则太多？拆分到子目录的 AGENTS.md 中，按作用域加载
• 关键规则用标签或编号防止被忽略

AGENTS.md 作用域规则

直接用户指令 > 嵌套更深的 AGENTS.md > 浅层 AGENTS.md

• 每个 AGENTS.md 的作用域是包含它的文件夹的整个目录树
• 嵌套更深的文件优先级更高
• 直接的系统/开发者/用户指令优先级最高

示例：好的 AGENTS.md 结构

# 项目名

## 工作流
- 每次代码变更后运行 `npm test`
- 使用 Conventional Commits（feat:, fix:, refactor:, docs:）
- 完成后通过 `gh pr create` 创建 PR

## 技术栈
- Node.js 18+, Express 4.x, PostgreSQL 16
- 测试：Jest + React Testing Library
- 认证：JWT + bcrypt

## 代码规范
- 组件文件不超过 300 行，超过则拆分
- 禁止使用 `any` 类型
- 所有公开 API 必须有 JSDoc 注释

## 必须运行的检查
修改完成后，按顺序运行：
1. `npm run lint` - Linter 修复
2. `npm test` - 运行相关测试
3. `npm run typecheck` - 类型检查

AGENTS.md 中的程序化检查

如果 AGENTS.md 中包含程序化检查命令，Codex 必须运行所有检查并验证通过：

## 必须运行的检查
修改完成后，按顺序运行：
1. `just fmt` - 代码格式化
2. `just fix -p ` - Linter 修复
3. `cargo test -p ` - 运行相关测试
4. `just bazel-lock-check` - 依赖锁文件检查

二、工作流最佳实践

1. 分阶段工作流

• 理解代码库 → 修改
• 先规划 → 再实现
• 生成 → 验证
• 不要把所有步骤压缩到一个大提示词里

2. 小任务别用复杂工作流

• 3-5 分钟能完成的事，直接一句话
• 复杂工作流适用于多文件、多步骤的大任务
• 重命名变量这种小事，一句话就行

3. 让 Codex 先理解代码库

# 先让 Codex 理解项目结构
codex exec "请解释 src/ 目录的整体结构，包括：
1. 核心模块有哪些
2. 依赖关系是怎样的
3. 入口文件在哪里"

4. 并行任务策略

• 将独立任务分配给不同的 Codex 实例
• 利用后台处理保持工作流连续
• 避免任务之间的依赖阻塞
• 社区建议：分配 well-scoped 任务给多个代理同时运行

三、调试与纠错

1. 粘贴 bug，说"fix"

• 把错误信息粘贴给 Codex，说一个字："fix"
• 不要指导怎么修，不要猜测原因，不要指定解决方案
• Codex 的调试能力比想象中强，管得越多越容易带偏
• 直接让 Codex 修的成功率 80%+

2. 两次失败 = 重新开始

• 同一个问题修正超过两次，开新会话重新开始
• 上下文污染会降低性能
• 建议：修正超过两次就重启

3. 要求重写平庸方案

• 当 Codex 给出能工作但不优雅的解决方案时，不要修补
• 说："知道你现在知道的一切，抛弃这个，实现优雅的解决方案"
• 重写版本通常比修补版本好得多

四、上下文管理

1. 长会话性能下降

• Codex Web 云端代理的上下文窗口有限
• 长时间会话后，上下文会被反复压缩，导致 AI 理解能力下降
• 社区提案（#22642）：auto_new_session_after_compactions = N，N 次压缩后自动刷新

2. 实践建议

• 复杂任务分阶段进行，每阶段开启新会话
• 将关键决策和上下文写入 AGENTS.md，而非依赖对话记忆
• 新会话携带关键上下文摘要，而非在超长会话中继续

3. 会话刷新策略

会话 1：理解代码库结构 → 写入 AGENTS.md
会话 2：基于 AGENTS.md 实现功能
会话 3：独立验证

五、提示词工程

有效提示词的黄金结构

【任务类型】请修复/实现/重构...

【问题描述】
- 具体、清晰的问题描述
- 当前行为 vs 期望行为

【约束条件】
- 任何限制或要求
- 不要修改的文件/模块

【参考信息】
- 相关文件路径
- 错误信息或日志
- 参考代码示例

提示词最佳实践

1. 提供具体路径和行号

❌ "修复 auth 模块的 bug"
✅ "修复 src/auth/login.py 第 45-62 行中的 Token 验证逻辑"

2. 说明期望的输出格式

"请生成一个包含以下内容的 PR：
 - 代码变更
 - 单元测试（至少 3 个测试用例）
 - 更新 README 中的相关文档"

3. 指定要运行的测试命令

"修改完成后，运行以下命令验证：
 npm test -- --testPathPattern=auth
 npm run lint"

4. 包含错误信息或日志

"当前报错信息：
 TypeError: Cannot read property 'token' of undefined
     at validateToken (src/auth/middleware.js:23:15)
请定位并修复该问题。"

六、Subagents（子智能体）

1. 在提示词中加"use subagents"

• Codex 会自动拆分任务给多个子智能体并行处理
• 适合代码审查、大规模重构

2. 专用子智能体 > 通用 mega-agent

• 创建功能特定的子智能体（如"前端组件智能体"）
• 而不是通用的（如"QA 智能体"）
• 功能越具体，上下文越精准，效果越好

3. 子智能体有独立上下文窗口

• 研究、验证、审查隔离在独立上下文中
• 防止污染和偏见
• 不污染主上下文

4. 多 Agent 协作

社区讨论（#22749）提到：

对于跨项目的复杂任务，需要多个 Codex 实例之间的协调。建议：

每个实例负责独立的子任务 通过共享文件（如 AGENTS.md）协调上下文 使用 CI/CD 流水线串联多个代理的输出

七、Skills（技能）与 MCP 插件

1. MCP 服务器（Model Context Protocol）

MCP 是 Codex 扩展能力的核心协议，允许接入外部工具：

配置示例：

{
  "mcpServers": {
    "xlsx-for-ai": {
      "command": "xlsx-for-ai-mcp"
    }
  }
}

2. 技能应该是文件夹结构

skills/
  api-design/
    SKILL.md          # 主文件：核心规则和索引
    references/       # 语料库、参考资料
    scripts/          # 辅助脚本
    examples/         # 示例代码

• 主文件只包含核心规则和索引
• 语料库、检查表放在 references/
• 渐进式披露：Codex 只在需要时读取子目录内容

3. 添加 Gotchas（坑点记录）部分

这是长期最有价值的技术：每次 Codex 犯错时记录失败模式，长期积累成为信噪比最高的内容。

Gotchas 结构示例

# SKILL.md

## 核心规则
...

## Gotchas（坑点记录）

### 2026-05-10: API 分页参数遗漏
- **问题**：生成 API 时忘记添加分页参数
- **表现**：返回所有数据导致性能问题
- **修复**：在 SKILL.md 中添加分页规则
- **预防**：检查清单中增加"是否包含分页"

### 2026-05-12: 测试覆盖不足
- **问题**：只测试 happy path，忽略边缘情况
- **表现**：测试通过但实际运行报错
- **修复**：添加边界值测试规则
- **预防**：检查清单中增加"边缘情况覆盖"

Gotchas 维护原则

1. 每次犯错必记录：不要等，立即记录
2. 包含四个要素：问题描述、表现形式、修复方法、预防措施
3. 定期回顾：每周回顾一次，识别重复出现的模式
4. 转化为规则：如果某个坑点出现 3 次以上，转化为正式规则
5. 归档已解决的：超过 30 天未出现的问题，移到归档区

八、记忆与持久化

1. Codex 的记忆机制

Codex 本身没有跨会话的长期记忆，每次任务在独立的沙箱环境中运行。但可以通过以下方式实现"记忆"效果：

2. 实现记忆的方法

方法一：AGENTS.md 作为项目记忆

• 将项目知识、决策、规范写入 AGENTS.md
• Codex 每次执行任务都会读取

方法二：代码注释和文档

• 在代码中保留清晰的注释
• 维护 up-to-date 的 README 和架构文档

方法三：本地自动化记忆（社区方案）

GitHub 社区用户（#21728）提出了一个"Sentinel-AI"模式：

本地 Agent 检测到问题
  ↓
检查本地记忆/Playbook
  ↓
已知问题 → 执行本地方案
未知问题 → 升级给 Codex
  ↓
Codex 生成修复方案
  ↓
人工审核 + 批准
  ↓
保存为本地可复用工具
  ↓
下次自动使用，无需再次请求云端 AI

核心收益：

• 约 80% 的任务不需要调用云端 API
• 成本从 $75/月 降至 $15/月
• 形成"学习复利"效应 — 运行越久，需要的云端调用越少

方法四：结构化记忆文件

# .codex/memory.md
memory:
  append_only: true        # 只追加，不覆盖
  format: structured_markdown  # 结构化 Markdown 格式
  max_size: 10KB           # 自动清理最旧条目
  share_across_agents: true # 所有代理共享

九、权限与安全

1. 执行环境安全

• Codex 在隔离的云容器中运行
• 任务执行期间禁用互联网访问
• 只能访问 GitHub 仓库提供的代码和预配置依赖
• 无法访问外部网站、API 或其他服务

2. Prompt 注入风险

GitHub 社区讨论（#6162）指出：

当 Codex 读取包含隐藏指令的文件时，可能会执行非预期操作。例如，CV 文件中隐藏的白色文字指令可能影响 AI 判断。

防御措施：

1. 信任域分离：将不同来源的文本视为不同信任域
2. 用户输入（高信任）
3. 检索文档/网页（低信任）
4. 工具结果（中信任）
5. 生成的工具参数（需验证）
6. 策略映射：检索的文本可以"提供信息"，但不能"授权" shell/文件/网络操作
7. 人工审查：始终审查 Codex 生成的代码变更
8. 权限最小化：不要给 Codex 不必要的权限

3. 用户责任清单

• ✅ 必须手动审查和验证所有代理生成的代码
• ✅ 不要将敏感信息（密钥、密码、Token）存储在代码库中
• ✅ 定期更新 AGENTS.md 中的安全规范
• ✅ 在提交前仔细检查代码差异（diff）

十、Codex 常见陷阱（Gotchas）

陷阱 1：过早放弃

表现：

我已实现大部分功能。功能在 XX 情况下工作正常。
但 YY 情况下不工作。代码已充分测试，这是好的开始。

缓解：

• 拆分任务为更小、更隔离的单元
• 即使人类认为可以分组，Codex 也需要分离
• 示例：两个相似表 → 分两个 PR，每个 10 分钟完成

陷阱 2：上下文压缩后变笨

表现：

• 不知道之前看的文件
• 重复之前纠正的错误
• 性能明显下降

缓解：

• 复杂任务分阶段进行，每阶段开启新会话
• 将关键决策写入 AGENTS.md
• 必要时开新会话 + git reset --hard

陷阱 3：测试问题

表现：

• 生成看起来对但失败的测试
• 修改测试匹配错误代码
• 降低测试标准

缓解：

• TDD 模式：先写测试
• 仔细审查生成的测试
• 严格审查测试变更（比代码变更更严格）

陷阱 4：忘记编译

表现：

• 测试循环失败因为未编译
• 依赖变更后忘记重新编译

缓解：

• AGENTS.md 中明确编译步骤
• 测试前强制编译
• 注意：编译语言 vs 解释语言混合时特别容易出错

陷阱 5：工作目录混乱

表现：

• 留下测试脚本、数据库文件
• Git 操作错误导致 PR 混乱

缓解：

• 每次完成后 git status 检查
• 人工执行 Git 操作（分支、提交、推送）
• Codex 只修改文件，不操作 Git

陷阱 6：重写但不删除

表现：

• 创建新文件但不删除旧文件
• 新旧代码共存导致混淆

缓解：

• 审查 diff 确认删除
• 明确指示"删除旧实现"
• 检查文件列表确认清理

陷阱 7：Prompt 注入

表现：

• 读取包含隐藏指令的文件
• 执行非预期操作

缓解：

• 信任域分离
• 人工审查所有变更
• 不要将敏感信息存储在代码库中

陷阱 8：长会话质量下降

表现：

• 会话越长，Codex 表现越差
• 忘记之前的纠正
• 重复错误

缓解：

• 复杂任务分阶段进行
• 每阶段开启新会话
• 将关键上下文写入 AGENTS.md

十一、典型使用场景与示例

场景 1：日常 Bug 修复

codex exec "
修复 src/api/user.ts 中的分页查询 Bug。
当前行为：第 2 页返回空数据
期望行为：正确返回第 2 页的用户列表
参考：相关 Issue #1234
修改后运行：npm test -- user.test.ts
"

场景 2：批量重构

codex exec "
将所有 src/components/ 下的类组件重构为函数组件。
要求：
1. 使用 React Hooks 替代生命周期方法
2. 保持原有功能不变
3. 更新相关测试文件
4. 运行 npm test 验证
"

场景 3：测试覆盖

codex exec "
为 src/utils/ 目录下的所有工具函数补充单元测试。
要求：
1. 每个函数至少 2 个测试用例
2. 覆盖正常情况和边界情况
3. 测试文件命名：*.test.ts
4. 运行 npm test 验证通过
"

场景 4：代码库问答

codex exec "
请解释 src/auth/ 模块的认证流程。
包括：
1. 用户登录流程
2. Token 生成和验证
3. 权限检查机制
4. 相关的配置文件
"

十二、安装与快速上手

安装

# 方式一：npm 安装
npm install -g @openai/codex

# 方式二：Homebrew（macOS）
brew install --cask codex

# 启动交互式 TUI
codex

# 非交互式执行（一条命令完成）
codex exec "修复 src/auth.py 中的登录验证漏洞"

系统要求

• macOS 12+ / Ubuntu 20.04+ / Windows 11（WSL2）
• 4GB RAM（推荐 8GB）
• Git 2.23+（推荐）

登录 ChatGPT 账户

codex
# 选择 Sign in with ChatGPT
# 推荐使用 ChatGPT 账户登录，享受 Plus/Pro/Enterprise 计划的福利

调试与日志

# 查看详细日志
tail -F ~/.codex/log/codex-tui.log

# 自定义日志级别
RUST_LOG=codex_core=debug codex

# 自定义日志目录
codex -c log_dir=./.codex-log

---

十三、Codex 三种形态对比

十四、核心原则总结

上下文是宝贵资源

• 保持简洁、及时压缩、污染就重置
• 复杂任务分阶段进行，每阶段开启新会话
• 将关键决策写入 AGENTS.md

系统约束 > 提示词约束

• 用 AGENTS.md 配置代替"希望 Codex 记住"
• 关键规则用标签或编号
• 程序化检查必须运行并验证

分而治之

• 子智能体、分阶段工作流、规格与实现分离
• 专用子智能体 > 通用 mega-agent
• 小任务简单处理，复杂任务才需要完整工作流

不要过度工程

• 3-5 分钟能完成的事，直接一句话
• 复杂工作流适用于多文件、多步骤的大任务
• 重命名变量这种小事，一句话就行

持续改进

• 每次犯错必记录 Gotchas
• 定期回顾，识别重复模式
• 将高频问题转化为正式规则

安全优先

• 信任域分离
• 人工审查所有变更
• 权限最小化

参考资料

• OpenAI Codex 官方文档：https://platform.openai.com/docs/codex
• GitHub 仓库：https://github.com/openai/codex（82.8k ⭐）
• Codex App：https://chatgpt.com/codex
• 开发者文档：https://developers.openai.com/codex
• MCP 注册表：registry.modelcontextprotocol.io
• 社区讨论：https://github.com/openai/codex/discussions
• 远程控制中心（社区提案）：https://github.com/openai/codex/discussions/9200
• 本地自动化记忆（Sentinel-AI）：https://github.com/openai/codex/discussions/21728
• Prompt 注入风险：https://github.com/openai/codex/discussions/6162
• 会话刷新策略：https://github.com/openai/codex/discussions/22642

---

本文档基于 OpenAI 官方发布内容、GitHub 仓库（openai/codex）及社区讨论整理，截至 2026 年 5 月。Codex 仍在快速迭代中，建议持续关注官方更新。