解构 Codex agent loop：Codex CLI 如何通过 Responses API 编排模型、工具、提示与性能

核心机制：Responses API 驱动的闭环编排

Codex CLI 并非简单调用 LLM API，而是基于 OpenAI 的 Responses API 构建分阶段 agent loop——包括 prompt composition、tool selection、execution dispatch、response streaming 与 stateful retry。该 loop 显式分离 planning（LLM 输出结构化 action plan）与 acting（CLI 工具执行），支持对每个 step 的 token usage、latency、tool error 进行细粒度埋点。

关键组件协同方式

• 模型层：默认集成 GPT-4-turbo（gpt-4-turbo-2024-04-09），支持 runtime 切换至 Claude 3 Opus 或本地 Llama 3-70B via Ollama；所有请求经 Responses API 封装，强制启用 response_format={"type":"json_object"} 保障结构化输出。
• 工具层：内置 shell、curl、git、python-exec 等 CLI 工具适配器，每个工具注册为 ToolSpec，含 schema（JSON Schema 定义输入/输出）、execute() 方法及 timeout 控制；工具调用失败时自动触发 fallback prompt + max_retries=2。
• 提示工程：采用 multi-turn system prompt 模板（含 role definition、tool catalog、output constraints），prompt 版本固化于 codex-prompt-v2.1.yaml，支持 per-command override。
• 性能控制：通过 Responses API 的 stream=true + max_tokens=1024 + temperature=0.2 组合实现 sub-800ms P95 响应延迟；所有 streaming chunk 按 data: {"id":"...","delta":{"role":"assistant","content":"..."}} 格式解析，确保 CLI 实时渲染。

实际约束与可观测性设计

• Loop 最大迭代深度设为 8，防无限 tool-call 循环；每轮消耗 token 计入 codex_usage.jsonl，含 model, prompt_tokens, completion_tokens, tool_calls, wall_time_ms 字段。
• 所有 trace 数据兼容 OpenTelemetry，可导出至 Jaeger 或 Datadog；CLI 启动时自动生成 codex-trace-id-{timestamp}.log，用于 debug 复现。