本文迁移自 mindcarver/91ai · 原始位置 docs/ai-coding/openai-codex.md · 由 @阿新聊ai 整理。

OpenAI Codex 资料与项目索引

更新日期：2026-05-25
范围：OpenAI Codex、Codex CLI、Codex IDE、Codex Cloud、Codex App、Codex SDK / Action / MCP，以及围绕 Codex CLI 的学习资料和社区项目。

Codex 不应该只被理解成一个“写代码工具”。从当前生态看，它更像一套面向软件工程的 agent 工作台：

• CLI：本地终端里的 coding agent，适合读代码、改代码、跑测试、做小到中型任务。
• IDE Extension：在 VS Code、Cursor、Windsurf、JetBrains 等 IDE 里和 Codex 协作。
• Cloud / Web：把较长任务交给云端执行，适合异步开发、修 bug、开 PR、跑验证。
• App：桌面工作台，适合并行管理多个 agent 线程、查看 diff、跟踪长任务。
• GitHub / CI：通过 GitHub 集成或 Action，把 Codex 放进 PR review、自动修复和流水线。
• SDK / MCP / Plugins / Skills：把 Codex 扩展成可编排、可自动化、可接入工具链的工程系统。

推荐阅读顺序

如果你刚开始了解 Codex，建议按这个顺序看：

1. Codex CLI 官方文档
2. OpenAI Codex 官方介绍
3. Codex IDE 官方文档
4. Codex use cases
5. AGENTS.md 官方指南
6. openai/codex GitHub 仓库
7. Codex changelog

官方资料

官方项目

学习资料

入门教程

进阶学习

生态项目与能带来的东西

1. 工作流增强

2. 客户端与远程控制

3. 认证、账号与运行管理

4. API / MCP / 集成层

5. Fork 与实验性变体

研究与评测资料

使用场景分类

适合优先尝试

• 读懂陌生代码库
• 小到中型功能开发
• 重构和迁移
• 写测试、补测试覆盖
• PR review
• 文档更新
• 前端页面按截图或设计稿实现
• 生成评测脚本和回归检查

适合谨慎尝试

• 大规模自动重构
• 涉及生产数据库、密钥、部署权限的任务
• 自动合并 PR
• 没有测试覆盖的核心业务逻辑修改
• 长时间无人看管的全自动任务
• 自动审批所有命令和网络访问

不建议直接交给 Codex

• 高风险权限操作
• 涉及真实用户数据的批量修改
• 没有回滚方案的生产变更
• 法务、安全、财务等高风险判断
• 需要明确责任归属的最终决策

评测维度建议

后续评测 Codex 时，建议从这些维度打分：

当前判断

Codex 最值得关注的地方不是“代码生成”，而是它正在把 AI Coding 从聊天框推进到完整工程工作流：

• 本地 CLI 负责贴近真实仓库。
• IDE extension 负责减少上下文切换。
• Cloud / GitHub 负责异步任务和 PR 流程。
• App 负责并行管理多个 agent 线程。
• AGENTS.md、Skills、MCP、Action 负责把经验沉淀成可复用工作流。

因此，Codex 适合放在 AI Coding 工具评测的高优先级位置。它的核心评测问题应该是：

Codex 能否在真实代码库里稳定完成可审查、可测试、可回滚的软件工程任务？

补充调研结果

Codex 与 Claude Code、Cursor、Cline、Gemini CLI 的横向评测

目前没有找到一个同时覆盖 Codex、Claude Code、Cursor、Cline、Gemini CLI 且公开完整任务集、评分规则、原始输出的高质量同任务评测。可参考资料如下：

当前结论：

• 横向评测应该自己设计一套可复现任务，不建议直接采用第三方榜单结论。
• 评测任务要覆盖：bug fix、测试补全、重构、文档更新、前端 UI、依赖升级、CI 失败修复。
• 每个工具应固定模型、版本、上下文、预算、允许命令、运行次数，并保留 diff、日志和测试结果。
• Cline 相关的高质量公开基准较少，后续需要单独补充。

Codex CLI / IDE / App / Cloud 的场景边界

一句话判断：

• CLI 贴近本地工程。
• IDE 贴近日常编辑。
• App 适合监督多个 agent。
• Cloud 适合异步委派。
• GitHub / CI 适合把 Codex 放进 review 和自动化流程。

AGENTS.md 最佳实践模板

可参考资料：

• AGENTS.md 官方指南
• openai/codex 自身的 AGENTS.md
• AGENTS.md best practices - agentexperience.ax
• AGENTS.md Best Practices for Teams
• Evaluating AGENTS.md
• On the Impact of AGENTS.md Files

建议原则：

• 保持短而准，不要把工程手册全文塞进去。
• 写 agent 无法安全推断的信息：测试命令、构建命令、目录边界、风险操作、提交规范。
• 和代码一起维护。构建流程、测试命令、目录结构变化时，同步更新 AGENTS.md。
• 链接详细文档，不复制长文档。
• 针对子目录放局部 AGENTS.md，用范围而不是大而全的全局文件解决上下文问题。

推荐模板：

# AGENTS.md

## Project Context

- This repository is ...
- Primary language/framework:
- Main entry points:
- Important directories:

## Commands

- Install:
- Lint:
- Type check:
- Test:
- Build:

## Working Rules

- Keep changes scoped to the requested task.
- Prefer existing patterns and local helper APIs.
- Do not introduce new dependencies without explaining why.
- Update documentation when behavior or public APIs change.

## Testing Expectations

- Run the smallest relevant test first.
- Add or update tests when changing behavior.
- If tests cannot be run, explain why and list the unverified risk.

## Safety Boundaries

- Do not touch production secrets, credentials, tokens, or deployment configs.
- Do not run destructive commands unless explicitly requested.
- Do not modify generated files unless the generation source is also updated.

## Review Checklist

- Summary of changes
- Tests run
- Known risks
- Files that need human attention

Codex 用于 PR review 的真实案例

公开可验证资料：

当前结论：

• Codex PR review 可以作为第一道自动检查，但不应该替代人工 review。
• 更合理的定位是：提前发现明显 bug、遗漏测试、风险变更、文档不一致、可维护性问题。
• 真实落地时要保留：Codex comment、diff、测试结果、人工处理结果，后续才能形成评测数据集。

Codex Action 在 GitHub Actions 中的安全配置模板

可参考资料：

• openai/codex-action
• codex-action security.md
• GitHub Actions secrets docs

基础模板：

name: Codex PR Review

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: write

jobs:
  codex-review:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest

    steps:
      - name: Checkout pull request
        uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Run Codex review
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            Review this pull request for:
            - correctness bugs
            - missing tests
            - security risks
            - breaking changes
            - unclear behavior

            Do not make changes. Return concise findings with file references.

安全注意：

• 默认先只做 read/review，不自动 push 修复。
• 不要在不受信 PR 上使用高权限 pull_request_target 执行代码。
• permissions 要最小化，能读就不要写，能评论就不要给 contents write。
• 不要把 secret 拼进 prompt、日志或命令行输出。
• 对 fork PR、外部贡献者 PR、自动生成 PR 使用更严格策略。
• 让 Codex Action 尽量作为 job 的最后一步运行，减少它影响后续 action 的机会。

Codex + MCP 的典型工具组合

当前判断：

• 最稳的第一组 MCP 是 GitHub + 文档检索 + 浏览器验证。
• 不建议一开始接太多 MCP server。工具越多，权限面、prompt injection 面和调试成本越高。
• MCP server 应按生产依赖审查：来源、权限、更新频率、日志、secret 处理、失败行为。

Codex 中文资料质量筛选

目前找到的中文资料不算多，质量差异较大。建议优先收录“基于官方资料、有更新时间、能说明版本边界”的内容。

筛选标准：

• 是否标注更新时间。
• 是否区分 Codex CLI、IDE、App、Cloud。
• 是否引用官方文档或 GitHub 仓库。
• 是否说明审批模式、sandbox、secret、GitHub 权限等安全边界。
• 是否有真实命令、配置、失败处理，而不是只复述产品介绍。