codex-howto

# Codex 使用指南 OpenAI Codex 工程优先指南——从您的第一个安全任务到可重用的技能、专业代理和有纪律的多代理工作流。 [](https://github.com/Phelan164/codex-howto/actions/workflows/validate.yml) [](LICENSE) [开始学习](modules/00-mental-model/README.md) · [选择学习路径](LEARNING-ROADMAP.md) · [浏览技能](#工程技能目录) · [尝试 playground](labs/engineering-playground/README.md) · [使用快速参考](QUICK_REFERENCE.md) > **状态：** 社区预览。内容已针对 2026-07-24 的官方 Codex 文档进行检查。Codex 变化迅速；请通过标有 **官方来源** 的链接验证设置和命令。 ## 为什么有这个仓库 官方文档是产品行为的真实来源。本仓库将产品表面转化为软件工程师的实用、可运行的课程。 您将学习如何： - 在不淹没对话的情况下为 Codex 提供足够的上下文； - 在 `AGENTS.md` 中编码仓库约定； - 将重复的前端、后端、DevOps、测试、审查和安全工作转化为技能； - 通过 MCP 连接外部系统； - 选择安全的沙盒和审批设置； - 将有界工作委托给专业代理； - 在不创建编辑冲突的情况下编排并行工作； - 减少浪费的上下文、重试和不必要的令牌使用； - 在稳定工作流可靠交互后自动执行。 ## 包含的内容 - **13 个渐进式模块**，涵盖安全性、提示、`AGENTS.md`、技能、MCP、子代理、编排、上下文效率、自动化和故障排除。 - **8 个可安装的工程技能**，适用于端到端工程循环、前端、后端、DevOps、测试、代码审查、安全审查和编排。 - **可复制的示例**，适用于项目配置、自定义代理、提示、钩子、MCP 和本地插件。 - **无依赖 playground**，包含种子缺陷，用于安全练习完整的实现-测试-审查循环。 ## 适用人群 - **初学者**：可以打开 Codex 但不确定如何构建真实任务的人。 - **在职工程师**：希望为生产仓库获取可重复工作流的人。 - **技术负责人**：希望共享代理指令和审查标准的人。 - **平台团队**：构建技能、插件、MCP 集成和 CI 自动化的人。 ## 选择您的路线 | 目标 | 从这里开始 | |---|---| | 学习安全的 Codex 基础知识 | [学习路径 A · 安全初学者](LEARNING-ROADMAP.md#track-a-safe-beginner) | | 构建和审查应用程序代码 | [学习路径 B · 应用程序工程师](LEARNING-ROADMAP.md#track-b-application-engineer) | | 使用交付和基础设施 | [学习路径 C · 平台和 DevOps 工程师](LEARNING-ROADMAP.md#track-c-platform-and-devops-engineer) | | 高效协调子代理 | [学习路径 D · 代理编排者](LEARNING-ROADMAP.md#track-d-agent-orchestrator) | | 通过修复小型项目学习 | [工程 playground](labs/engineering-playground/README.md) | ## 学习路径 | 阶段 | 模块 | 结果 | 时间 | |---|---|---|---:| | 基础 | [00 · 心理模型](modules/00-mental-model/README.md) | 选择正确的 Codex 表面和任务形状 | 25 分钟 | | 基础 | [01 · 沙盒和审批](modules/01-sandbox-and-approvals/README.md) | 在第一次写入之前设置安全自治边界 | 45 分钟 | | 基础 | [02 · CLI 和表面](modules/02-cli-and-surfaces/README.md) | 安全地安装、认证、导航和检查 | 35 分钟 | | 基础 | [03 · 提示和计划](modules/03-prompts-and-plans/README.md) | 编写具有可观察完成标准的范围提示 | 40 分钟 | | 基础 | [04 · AGENTS.md](modules/04-agents-md/README.md) | 使仓库指导持久且本地化 | 45 分钟 | | 工程 | [05 · 工程技能](modules/05-engineering-skills/README.md) | 构建和安装可重用的工程工作流 | 60 分钟 | | 工程 | [06 · MCP 和工具](modules/06-mcp-and-tools/README.md) | 在不增加指令负担的情况下添加实时数据和操作 | 45 分钟 | | 工程 | [07 · 测试和审查](modules/07-testing-and-review/README.md) | 关闭实现-验证-审查循环 | 55 分钟 | | 规模 | [08 · 子代理](modules/08-subagents/README.md) | 委托狭窄的独立工作 | 50 分钟 | | 规模 | [09 · 编排](modules/09-orchestration/README.md) | 使用明确的所有权协调并行代理 | 70 分钟 | | 规模 | [10 · 上下文和令牌效率](modules/10-context-and-token-efficiency/README.md) | 减少上下文污染和昂贵的重试 | 50 分钟 | | 规模 | [11 · 自动化、插件和钩子](modules/11-automation-plugins-hooks/README.md) | 打包和自动化稳定工作流 | 60 分钟 | | 操作 | [12 · 故障排除](modules/12-troubleshooting/README.md) | 按层诊断故障而不是猜测 | 35 分钟 | 完整路径：大约 **9–10 小时**。从模块 00-03 开始，然后遵循与您的工作最匹配的 shortest 路径。 ## 五分钟开始 1. 使用官方 [快速入门](https://developers.openai.com/codex/quickstart) 安装 Codex。 2. 打开一个小型版本控制仓库。 3. 询问 Codex： ```text 目标：解释此仓库如何构建和测试。 上下文：检查根配置和贡献者文档。 约束：只读；不要安装依赖或更改文件。 完成后：返回确切的构建、测试、 lint 和类型检查命令， 并引用定义它们的 文件。 ``` 4. 审查结果。 5. 使用 `/init` 生成启动 `AGENTS.md`，然后用验证的命令替换通用文本。 ## 工程技能目录 此仓库包括可安装的启动技能： | 技能 | 目的 | |---|---| | [`engineering-loop`](skills/engineering-loop/SKILL.md) | 通过基准、实现、测试、审查和证据驱动变更 | | [`build-frontend`](skills/build-frontend/SKILL.md) | 实现具有视觉和行为验证的无障碍 UI 更改 | | [`build-backend`](skills/build-backend/SKILL.md) | 安全地更改 API、服务、持久性和合约 | | [`operate-devops`](skills/operate-devops/SKILL.md) | 修改交付和基础设施，具有回滚验证 | | [`review-code`](skills/review-code/SKILL.md) | 查找重要缺陷、回归和缺失测试 | | [`test-software`](skills/test-software/SKILL.md) | 设计基于风险的测试并实现最高价值的覆盖 | | [`review-security`](skills/review-security/SKILL.md) | 跟踪信任边界并报告可利用的安全风险 | | [`orchestrate-engineering`](skills/orchestrate-engineering/SKILL.md) | 在保护上下文和避免编辑冲突的同时协调有界代理 | 将技能复制到 `.agents/skills/` 以适用于一个项目，或复制到 `~/.agents/skills/` 以供个人重复使用： ```bash mkdir -p .agents/skills cp -R /path/to/codex-howto/skills/review-code .agents/skills/ ``` 在安装之前检查每个技能，然后启动新的 Codex 任务并显式调用它： ```text $review-code 审查此分支与 main 的差异。优先显示重要发现， 并列出您无法运行的检查。 ``` 对于完整的本地开发-测试-审查循环，安装相关专家技能并启动： ```text $engineering-loop 从头到尾实现此更改。通过聚焦的测试、必需的检查、 差异审查和验证的修复。 在缺少权限或测试环境不明确时停止。 ``` ## 编排规则 默认情况下使用一个代理。只有当工作具有独立、有界的部分时才添加代理。 ```mermaid flowchart TD A["新任务"] --> B{"一个代理能否清楚地完成它？"} B -- 是 --> C["使用一个代理"] B -- 否 --> D{"部分是否独立？"} D -- 否 --> E["计划顺序阶段"] D -- 是 --> F{"主要是只读的？"} F -- 是 --> G["并行委托"] F -- 否 --> H["分配独家文件所有权或顺序运行"] G --> I["返回简洁的证据摘要"] H --> I I --> J["主代理集成和验证"] ``` 并行代理通常可以提高时间效率并保护主线程免受嘈杂日志的影响，但它们通常会使用 **更多令牌**。效率目标是减少失败循环和清理上下文，而不是最大化代理数量。 ## 仓库地图 ```text codex-howto/ ├── .github/ # 验证工作流和 PR 模板 ├── modules/ # 渐进式教程和实验室 ├── skills/ # 可安装的工程技能 ├── labs/ │ └── engineering-playground/ # 自成体系的实践项目 ├── examples/ │ ├── agents/ # 项目范围的自定义代理定义 │ ├── config/ # 谨慎的 Codex 配置 │ ├── prompts/ # 可复制的任务和编排提示 │ └── AGENTS.md # 启动仓库指导 ├── resources/ # 检查清单和比较材料 └── scripts/validate_repo.py # 离线结构验证 ``` 参见 [CATALOG.md](CATALOG.md) 获取完整索引，[LEARNING-ROADMAP.md](LEARNING-ROADMAP.md) 获取建议的学习路径。 对于无依赖的端到端练习，请将 [工程 playground](labs/engineering-playground/README.md) 复制到一个 disposable 目录中，并针对其种子缺陷练习后端、前端、DevOps、测试、审查、安全和编排工作流。 ## 源策略 - 产品行为和配置声明必须链接到官方 OpenAI 文档。 - 社区示例必须标记为社区材料。 - 版本敏感示例应包含验证日期。 - 绝不包含密钥、生产凭证和破坏性默认值。 - 诸如“10 倍生产力”之类的营销声明被故意避免。 ## 灵感和相关工作 渐进式模块的想法灵感来自 [luongnv89/claude-howto](https://github.com/luongnv89/claude-howto)。此仓库是原始的 Codex 焦点课程，不复制其教程文本或模板。 有用的相关社区项目： - [freestylefly/CodexGuide](https://github.com/freestylefly/CodexGuide) - [geekjourneyx/awesome-codex-guide](https://github.com/geekjourneyx/awesome-codex-guide) - [bozhouDev/codex-orange-book](https://github.com/bozhouDev/codex-orange-book) - [RoggeOhta/awesome-codex-cli](https://github.com/RoggeOhta/awesome-codex-cli) - [ComposioHQ/awesome-codex-skills](https://github.com/ComposioHQ/awesome-codex-skills) - [VoltAgent/awesome-codex-subagents](https://github.com/VoltAgent/awesome-codex-subagents) 权威的上游实现是 [openai/codex](https://github.com/openai/codex)。 ## 贡献 欢迎贡献。从 [CONTRIBUTING.md](CONTRIBUTING.md) 开始。新教程应包括具体成果、安全练习、验证步骤和官方来源。 ## 许可证和商标 在 [MIT License](LICENSE) 下发布。“OpenAI”和“Codex”是其各自所有者的商标。本项目是独立的社区项目，不受 OpenAI 或 Anthropic 认可或支持。