OpenAI-Codex-CLI-智能体编程实战指南-八-

OpenAI Codex CLI 智能体编程实战指南（八）

原文：Agentic Coding with OpenAI Codex CLI

译者：飞龙

协议：CC BY-NC-SA 4.0

  1. 原始 SWE-bench 论文（“SWE-bench: Can Language Models Resolve Real-World GitHub Issues?”）由普林斯顿研究人员发表，并被 ICLR 2024 接收。https://arxiv.org/abs/2310.06770↩︎

  2. HumanEval 基准测试在“Evaluating Large Language Models Trained on Code”（Chen 等人，2021）中引入，确立了用于代码生成的 pass@k 评估指标。https://arxiv.org/abs/2107.03374↩︎

  3. SWE-bench Verified 由 OpenAI 于 2024 年 8 月推出，是原始 SWE-bench 中经人工验证的 500 个任务的子集。https://openai.com/index/introducing-swe-bench-verified/↩︎

  4. Scale AI SEAL 排行榜使用相同的工具和 250 轮限制来托管标准化的 SWE-bench Pro 分数，以将模型能力与脚手架质量隔离开来。https://labs.scale.com/leaderboard/swe_bench_pro_public↩︎

  5. Terminal-Bench 2.0 是 Laude Institute 和斯坦福大学的联合项目，在 Docker 容器化的终端环境中评估 89 个精选任务。https://www.tbench.ai/↩︎

  6. GPT-5.5 Terminal-Bench 2.0 得分 82.7%，由 OpenAI 于 2026 年 4 月 23 日宣布，以微弱优势击败 Anthropic 的 Claude Mythos Preview。这是供应商测量的数据；独立的 Terminal-Bench 2.0 排行榜显示 Codex CLI + GPT-5.5 得分 82.2%，落后于 NexAU-AHE + GPT-5.5 的 84.7%（https://www.tbench.ai/leaderboard/terminal-bench/2.0）。SWE-bench Pro 得分 58.6%，SWE-bench 得分 88.7%。https://openai.com/index/gpt-5-5/↩︎

  7. 脚手架效应对基准测试分数的影响记录在 SWE-bench Pro 排行榜的讨论中，不同的代理框架运行同一模型显示出 4 到 12 分的差异。https://www.morphllm.com/swe-bench-pro↩︎

  8. SWE-bench 排行榜及相关研究凸显了 Verified 分数与在更抗污染评估上的表现之间的显著差距。https://www.swebench.com/↩︎

  9. “The Amazing Agent Race: Strong Tool Users, Weak Navigators”（AAR），arXiv:2604.10261，2026 年 4 月。最佳代理得分 37.2% 的准确率，导航错误占试验的 27% 到 52%。该基准使用基于谜题和检索的导航，而非源代码库；将这一发现应用于代码库导航是本书的类比。https://arxiv.org/abs/2604.10261↩︎

参考文献

  1. ^(10) “CocoaBench：评估真实环境中的统一数字代理”，Hao 等人，arXiv:2604.11201，2026 年 4 月。由视觉、搜索和代码组成的长时程任务；评估的最佳系统达到 45.1% 的成功率。 arxiv.org/abs/2604.11201↩︎

  2. ^(11) “HiL-Bench（人在回路基准）：代理知道何时寻求帮助吗？”，arXiv:2604.09408，2026 年 4 月。任务包含仅通过探索才会浮现的人工验证阻碍因素（信息缺失、歧义、矛盾）；一旦必须决定是否升级，没有前沿模型能恢复其完整信息性能的很大一部分。 arxiv.org/abs/2604.09408↩︎

  3. ^(12) “SlopCodeBench：基准测试编码代理在长时程迭代任务中的性能退化”，arXiv:2603.24755，2026 年 3 月。20 个问题和 93 个检查点，代理在不断演变的规格下反复扩展其先前的解决方案；它追踪冗长度和结构侵蚀，而非一次性完成。最高检查点解决率为 17.2%，且质量稳步下降（80% 的轨迹中侵蚀上升，89.8% 中冗长度上升）。 arxiv.org/abs/2603.24755↩︎

  4. ^(13) Fu 等人，“通过代理驱动的标注和评估自动对 LLM 代码代理进行基准测试”（引入 PRDBench），arXiv:2510.24358，2025 年 10 月 28 日；被 AAMAS 2026 接受。来自上海交通大学/美团团队（PRDBench，AGI-Eval）。PRDBench 包含跨 20 个领域的 50 个真实世界 Python 项目，每个项目都有结构化的 PRD。各模型排名在项目的实时 AGI-Eval 排行榜上报告，而非固定在论文中，因此请将具体分数视为时间点数据。 arxiv.org/abs/2510.24358 和 github.com/AGI-Eval-Official/PRDBench。↩︎

  5. ^(14) MAESTRO（用于测试、可靠性和可观测性的多代理评估套件），arXiv:2601.00481，2026 年 1 月。架构与模型选择对多代理性能的影响。 arxiv.org/abs/2601.00481。↩︎

  6. ^(15) Opsera，2026 年 AI 编码影响基准报告，2026 年 1 月。对 60 多家企业组织中 250,000 多名开发者的分析。 opsera.ai/resources/report/ai-coding-impact-2026-benchmark-report/↩︎

  7. ^(16) Sourcery Intel，2026 年 AI 编码代理现状。跨 AI 编码代理领域的市场分析、基准数据和安全发现。 sourceryintel.com/reports/the-state-of-ai-coding-agents-2026↩︎

  8. ^(17) Gong 等人，“分析 AI 编码代理撰写的 Pull Request 中的消息-代码不一致性”，arXiv:2601.04886，2026 年 1 月，被 MSR 2026 Mining Challenge Track 接受。 arxiv.org/abs/2601.04886↩︎

  9. ^(18) CodeRabbit，“AI 与人工代码生成现状报告”，2025 年 12 月。在逻辑、质量、安全性和可读性类别中，AI PR 包含的问题比人工 PR 多 1.7 倍。 www.coderabbit.ai/blog/state-of-ai-vs-human-code-generation-report↩︎

  10. ^(1) “代码即代理线束”，arXiv 2605.18747。一项由 42 位作者参与的调查，确立了编码代理架构的三层框架（接口、机制、多代理扩展）。核心论点：“线束拥有循环控制权。” arxiv.org/abs/2605.18747↩︎

  11. ^(2) Anthropic，Claude Code 文档。 docs.anthropic.com/en/docs/claude-code↩︎

  12. ^(3) 终端代理与 IDE 代理之间的独立 Token 效率对比反映了视觉脚手架和更丰富的编辑器上下文的开销；CLI 到 CLI 的对比报告称相同任务存在数倍差异。请将该倍数视为依赖任务的，并根据您自己的团队规模仪表盘进行验证。↩︎

  13. ^(4) Google 的终端代理及其继任平台记录在 ai.google.dev/gemini-api/docs↩︎

  14. ^(5) OpenCode，一个支持许多模型提供商且采用宽松许可证的开源 CLI 代理。 github.com/anomalyco/opencode↩︎

  15. ^(6) Cursor，原生 IDE 编码代理。 cursor.com↩︎

  16. 终端代理与 IDE 代理之间的独立 Token 效率对比反映了视觉脚手架和更丰富的编辑器上下文的开销；CLI 到 CLI 的对比报告称相同任务存在数倍差异。请将该倍数视为依赖任务的，并根据您自己的团队规模仪表盘进行验证。↩︎

  17. [8] GitHub Copilot 代理模式（交互式、异步编码代理和 CLI）记录在 docs.github.com/copilot↩︎

  18. ^(9) AGENTS.md 由 OpenAI 于 2025 年 8 月开源，并于 2025 年 12 月捐赠给 Linux 基金会下的 Agentic AI 基金会 (AAIF)，使其成为由中立机构管理的开放标准，创始支持者包括 Anthropic、Block 和 OpenAI。 www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation↩︎

  19. ^(10) Microsoft，“APM：Agent Package Manager”，GitHub，2026 年。 github.com/microsoft/apm↩︎

  20. ^(11) Google，“Gemini CLI 停止维护通知”，I/O 2026，2026 年 5 月 19 日。Gemini CLI 已弃用，截止日期为 2026 年 6 月 18 日。建议迁移至 Antigravity CLI。 developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/↩︎

  21. ^(12) 双工具审查工作流，即用一个代理构建并用另一个代理审计，是一种有文档记录的从业者模式；其原则是绝不对仅经过一个模型审查的代码发布。↩︎

  22. ^(1) Ryan Lopopolo，“线束工程：在代理优先的世界中利用 Codex”，OpenAI，2026 年 2 月，openai.com/index/harness-engineering/，访问于 2026 年 3 月。该文章描述了一项为期五个月的内部实验，一支小团队构建并交付了约一百万行生产代码，且没有编写一行人工源代码，实现了每人 3 到 10 个工程师等效的吞吐量。↩︎

参考文献

  1. Ryan Lopopolo, “Harness engineering: leveraging Codex in an agent-first world,” OpenAI, February 2026, https://openai.com/index/harness-engineering/, accessed March 2026. 确切引语“Agent 并不难；Harness 才难”概括了核心论点：围绕 Agent 的基础设施比模型本身更能决定其可靠性。

  2. “Code as Agent Harness,” arXiv 2605.18747, May 2026. 42 位作者联合调查，确立了编码 Agent 架构的三层框架（接口、机制、多 Agent 扩展）。核心论点：“Harness 掌控循环。” https://arxiv.org/abs/2605.18747

  3. htek.dev, “All Agent Harnesses: The Live Comparison,” https://dev.to/htekdev/all-agent-harnesses-the-live-comparison-1km5（亦发布于 https://htek.dev/articles/all-agent-harnesses-live-comparison）, accessed May 2026. 从业者持续维护的 Agent 平台对比，覆盖多个评估维度（包括工具使用、记忆、多 Agent 能力、沙箱、治理、可扩展性、IDE 集成、CLI 支持、部署、定价和开源状态），确认 Harness 的主导地位超过了模型选择。

  4. OpenAI, “Symphony,” https://github.com/openai/symphony, accessed March 2026. Symphony 的 README 和 SPEC.md 记录了面向 Harness 的代码库三大支柱（隔离测试、机器可读文档、模块化架构），作为高效 Agent 运行的前置条件。

  5. OpenAI, “Symphony: WORKFLOW.md specification,” https://github.com/openai/symphony, accessed March 2026. WORKFLOW.md 格式使用 YAML 前置元数据进行运行时配置（模型、轮次限制、工作量证明要求），并使用兼容 Liquid 的模板化 Markdown 正文作为 Agent 的系统提示词，将 Agent 策略视为版本化的仓库制品。

  6. OpenAI, “Symphony: Elixir implementation,” https://github.com/openai/symphony/blob/main/elixir/README.md, accessed March 2026. Symphony 通过 Ecto 使用 PostgreSQL 进行数据库支持的状态持久化，支持对大量并发 Agent 进行车队级监控。

  7. Ryan Lopopolo, “Harness engineering: leveraging Codex in an agent-first world,” OpenAI, February 2026, https://openai.com/index/harness-engineering/, accessed March 2026. 工作量证明要求、CI 状态、PR 评审反馈、复杂度分析和演示视频，被描述为确保 Agent 是负责任的行动者而非自我汇报完成的黑盒的一种机制。

  8. Docker, “Docker MCP Catalog: Discover and Run Secure MCP Servers,” Docker Blog, 2025, https://www.docker.com/blog/docker-mcp-catalog-secure-way-to-discover-and-run-mcp-servers/; Docker, “MCP Toolkit: Run MCP Servers Securely,” Docker Blog, 2025, https://www.docker.com/blog/mcp-toolkit-mcp-servers-that-just-work/. MCP Toolkit 将经过验证的 MCP 服务器打包为具有受限权限、资源上限、凭据注入和输出扫描的容器镜像。

  9. Docker, “Docker MCP Catalog: Discover and Run Secure MCP Servers,” Docker Blog, 2025, https://www.docker.com/blog/docker-mcp-catalog-secure-way-to-discover-and-run-mcp-servers/; Docker, “MCP Toolkit: Run MCP Servers Securely,” Docker Blog, 2025, https://www.docker.com/blog/mcp-toolkit-mcp-servers-that-just-work/. MCP Toolkit 将经过验证的 MCP 服务器打包为具有受限权限、资源上限、凭据注入和输出扫描的容器镜像。

  10. OpenAI Engineering Blog, “Unlocking the Codex harness: how we built the App Server,” 2026, https://openai.com/index/unlocking-the-codex-harness/; OpenAI Developers, “App Server, Codex,” 2026, https://developers.openai.com/codex/app-server. App Server 协议通过 stdio 或 WebSocket 使用双向 JSON-RPC 2.0，将 Agent 逻辑与客户端界面解耦。

  11. OpenAI Engineering Blog, “Unlocking the Codex harness: how we built the App Server,” 2026, https://openai.com/index/unlocking-the-codex-harness/; OpenAI Developers, “App Server, Codex,” 2026, https://developers.openai.com/codex/app-server. App Server 协议通过 stdio 或 WebSocket 使用双向 JSON-RPC 2.0，将 Agent 逻辑与客户端界面解耦。

  12. ProAlexUSC, “cc-plugin-to-codex,” https://github.com/ProAlexUSC/cc-plugin-to-codex, accessed April 2026. 跨工具插件桥接，实现 Harness 组件在 Claude Code 和 Codex 生态系统间的可移植性。

  13. Arnoud Kleinloog, “The Complete Landscape of CLI-Based AI Coding Agents,” 2026, https://www.kleinloog.ch/articles/the-5-ai-coding-agents-worth-embedding-in-your-saas/the-complete-landscape-of-cli-based-ai-coding-agents.pdf. SaaS 就绪矩阵从架构、SDK 可用性、会话管理、MCP 可扩展性、气隙能力和许可维度对十一款 CLI Agent 进行评分。Codex CLI 位于第 2 梯队，拥有强大的 SDK 和模型生态，但在会话持久化和开源许可方面存在不足。

  14. Arnoud Kleinloog, “The Complete Landscape of CLI-Based AI Coding Agents,” 2026, https://www.kleinloog.ch/articles/the-5-ai-coding-agents-worth-embedding-in-your-saas/the-complete-landscape-of-cli-based-ai-coding-agents.pdf. SaaS 就绪矩阵从架构、SDK 可用性、会话管理、MCP 可扩展性、气隙能力和许可维度对十一款 CLI Agent 进行评分。Codex CLI 位于第 2 梯队，拥有强大的 SDK 和模型生态，但在会话持久化和开源许可方面存在不足。

  15. OpenAI, “Symphony: turns project work into isolated, autonomous implementation runs,” https://github.com/openai/symphony, accessed March 2026. 基于 Apache 2.0 许可证发布，Symphony 被描述为用于评估的原型软件；OpenAI 建议基于 SPEC.md 实现一个强化版本。

参考文献

  1. ^(17) OpenAI, “Symphony: Elixir/BEAM architecture,” github.com/openai/symphony/blob/main/elixir/README.md, accessed March 2026. The Elixir implementation note explains the choice of Erlang/BEAM: OTP supervision trees provide automatic agent restart on failure, hot code reloading supports development without stopping active subagents, and BEAM’s lightweight concurrency model makes running dozens of parallel agents operationally similar to running a handful.↩︎

  2. ^(18) NanoClaw, github.com/nanocoai/nanoclaw, accessed 2026. A lightweight, container-isolated agent orchestrator: a single host process routes messages from channels to per-session agents in sandboxed containers, backed by an SQLite task and session registry and scheduled jobs. Cited here as a reference for the persistent-orchestration pattern.↩︎

  3. ^(19) Vivek Trivedy, “Improving Deep Agents with Harness Engineering,” LangChain Blog, February 2026, www.langchain.com/blog/improving-deep-agents-with-harness-engineering. Documents a 30th-to-5th Terminal Bench 2.0 ranking improvement through harness middleware changes alone, with the model held constant.↩︎

  4. “Agent Harness for Large Language Model Agents: A Survey,” Preprints.org 202604.0428, April 2026, www.preprints.org/manuscript/202604.0428. First academic survey formalising harness engineering with labelled-transition-system semantics. Cites Meta-Harness (6× performance gap from harness changes alone) and CAAF (deterministic constraints beat model scale). Companion dataset at HuggingFace: GloriaaaM/LLM-Agent-Harness-Survey.↩︎

  5. ^(21) Addy Osmani, “The Factory Model: How Coding Agents Changed Software Engineering,” addyosmani.com, February 2026, addyosmani.com/blog/factory-model/. Frames the shift from artisan craftsmanship to managing production lines of AI agents, with practical recommendations for specification quality, verification bottlenecks, and developer skills in the factory model.↩︎

  6. Addy Osmani, “Agent Harness Engineering,” addyosmani.com, April 2026, addyosmani.com/blog/agent-harness-engineering/. Catalogues six load-bearing harness components, introduces the Ratchet Principle (every failure becomes a permanent harness fix), documents the “Skill Issue” reframe (most agent failures are configuration problems), and identifies Harness-as-a-Service as an emerging industry pattern. Cites Vivek Trivedy’s formula: “Agent = Model + Harness.”↩︎

  7. ^(24) Anthropic, “Claude Agent SDK overview,” code.claude.com/docs/en/agent-sdk/overview, accessed June 2026 (formerly the Claude Code SDK); OpenAI, “Codex SDK,” developers.openai.com/codex/sdk, accessed June 2026; OpenAI, “OpenAI Agents SDK,” openai.github.io/openai-agents-python/, accessed June 2026. Each packages an agent’s execution loop, built-in tools, and context management as a programmable library: the Claude Agent SDK gives you “the same tools, agent loop, and context management that power Claude Code”; the Codex SDK programmatically controls local Codex agents; the OpenAI Agents SDK supplies agents, tools, handoffs, and the agent runtime loop.↩︎

  8. ^(25) Arnaud Fournier, Head of Forward Deployed Engineering (EMEA & Global Verticals), OpenAI, on John Crickett’s Coding Chats podcast (Episode 77), 2026. Announcement: x.com/johncrickett/status/2054645470287597812; podcast home: www.youtube.com/@CodingChats. First-person account of enterprise agentic adoption patterns and the shift from raw code to harness engineering, drawn from work with clients across semiconductors, life sciences, and finance.↩︎

  9. ^(26) Andrej Karpathy, “From Vibe Coding to Agentic Engineering,” Sequoia Capital, April 29, 2026, www.youtube.com/watch?v=96jN2OCOfLs. Distinguishes vibe coding (raising the floor for everyone) from agentic engineering (preserving the professional quality bar while going faster). Introduces Software 3.0 (context window as lever, LLM as interpreter), describes agents as “intern entities,” and argues the ceiling for agentic engineers exceeds 10x.↩︎

  10. ^(27) Squintist, “Why Everyone Is Quietly Quitting OpenClaw,” YouTube, April 23, 2026, www.youtube.com/watch?v=urAMvpPhtqo. Documents OpenClaw’s 247,000-star growth and subsequent user attrition. Key failure modes: $86/month heartbeat token burn, context compaction dropping safety rules, prompt injection via email exfiltrating SSH keys, memory loss across upgrades. Surviving users converged on a harness-like playbook independently.↩︎

  11. ^(29) Hashnode, “Tech’s secret weapon: The complete 2026 guide to the forward deployed engineer,” hashnode.com/blog/a-complete-2026-guide-to-the-forward-deployed-engineer, accessed April 2026; OpenAI Careers, “Forward Deployed Engineer (FDE), NYC,” openai.com/careers/forward-deployed-engineer-(fde)-nyc-new-york-city/, accessed April 2026. Documents the FDE role’s growth, technical requirements, and the discovery-to-hardening lifecycle that maps directly to harness engineering practice.↩︎

  12. Hashnode, “Tech’s secret weapon: The complete 2026 guide to the forward deployed engineer,” hashnode.com/blog/a-complete-2026-guide-to-the-forward-deployed-engineer, accessed April 2026; OpenAI Careers, “Forward Deployed Engineer (FDE), NYC,” openai.com/careers/forward-deployed-engineer-(fde)-nyc-new-york-city/, accessed April 2026. Documents the FDE role’s growth, technical requirements, and the discovery-to-hardening lifecycle that maps directly to harness engineering practice.↩︎

  13. ^(30) Cursor, “Continually improving our agent harness,” 2026, cursor.com/blog/continually-improving-agent-harness. Industry convergence on harness-centric engineering: bespoke per-model prompts and tools, mixed offline and online evals (CursorBench), and the context window as the primary compute boundary.↩︎

  14. 30 Ben Thompson, “An Interview with OpenAI CEO Sam Altman and AWS CEO Matt Garman About Bedrock Managed Agents,” Stratechery, May 2026. stratechery.com/2026/an-interview-with-openai-ceo-sam-altman-and-aws-ceo-matt-garman-about-bedrock-managed-agents/↩︎

  15. ^(1) AGENTS.md 的层级结构、文件加载顺序及覆盖机制在 第 4 章 中有详细介绍。对于 Pod 使用而言，关键特性在于 Codex 会自动从层级结构中加载 AGENTS.md 文件，使其成为所有 Pod 代理会话天然的共享上下文层，且无需任何显式加载指令。↩︎

  16. ^(2) Git worktrees 作为并行代理会话的结构化机制，在 第 13 章 中有所介绍。每个价值工程师特性会话都应在专用 worktree 中运行。主分支仅接收来自已完成 worktree 的、经过审查且通过门控的输出，绝不接受直接的代理提交。↩︎

  17. ^(3) Hooks 系统（SessionStart、Stop 和 UserPromptSubmit hooks、其配置及执行语义）在 第 9 章 中有所介绍。本章前面所述的质量工程师会话后验证 hook 依赖于该处所述的 Stop hook 生命周期。↩︎

  18. ^(4) 插件安装策略（INSTALLED_BY_DEFAULT、AVAILABLE、NOT_AVAILABLE）及仓库市场治理模型在 第 10 章 中有所描述。INSTALLED_BY_DEFAULT 策略确保通过插件分发的 hooks 无法被个别开发者选择退出。↩︎

posted @ 2026-09-23 20:35  绝不原创的飞龙  阅读(8)  评论(0)    收藏  举报