Codex Skill

核心用法

Codex Agent Skill 是一套面向 OpenAI Codex CLI 的生产级自动化框架，将 AI 编码助手从交互式工具升级为可托管的 CI/CD 组件。

执行模式：

• Quick Mode：适用于单文件修改、简单分析等小型任务，使用 codex exec 非交互模式，配合 background=true + pty=true 执行，通过轮询机制实现自适应超时（5 分钟轮询间隔，12 小时静默上限），避免硬性超时杀死长任务
• Full Mode：适用于功能开发、Bug 修复等复杂任务，采用 git worktree 隔离分支、tmux 会话托管、日志文件持久化的完整工作流，支持中途干预与状态恢复

完整工作流（Task → Merged PR）：
1. 创建工作树隔离环境（git worktree add）
2. tmux 会话托管启动 Codex（关键顺序：session → pipe-pane → send-keys，确保不丢失早期输出）
3. JSON 注册表追踪任务状态
4. 日志文件监控（优于 tmux capture-pane，后者仅保留约 2000 行回滚）
5. 多模型代码评审（Claude 评审 Codex 产出，或不同 Codex 模型交叉评审）
6. Definition of Done 质量门禁（PR 创建、无冲突、CI 通过、AI 评审通过）
7. PR 合并后清理工作树

智能重试策略：分析失败类型（上下文溢出、方向错误、信息缺失、CI/构建失败），针对性调整 prompt，最多 3 次重试后升级人工。

显著优点

• 生产级隔离：git worktree 实现真正的分支隔离，避免开发冲突
• 可观测性：tmux pipe-pane + stdbuf 行缓冲实现实时日志追踪，ANSI 清洗后支持可靠检索
• 中途干预：通过 tmux send-keys 向运行中的 Agent 注入指令，无需重启
• 多模型协作：不同模型交叉评审，利用模型间的认知差异发现单一模型盲区
• 弹性执行：自适应超时机制兼顾短任务（5 分钟）与长任务（数小时）
• 并行支持：多 worktree + 多 tmux 会话实现任务级并行

潜在缺点与局限性

• 内存限制：Quick Mode 输出仅存于内存，OpenClaw 重启即丢失；超长输出受 PI_BASH_MAX_OUTPUT_CHARS 限制
• tmux 依赖：Full Mode 强制依赖 tmux，非标准环境需额外安装
• 容器安全：--dangerously-bypass-approvals-and-sandbox 仅在容器/沙箱环境安全，裸机运行存在风险
• JSON 评审限制：AI 评审可能产生误判，关键安全代码仍需人工终审
• 上下文窗口：超长任务仍需人工拆分，框架本身不自动处理上下文切割

适合人群

• 需要批量处理 PR、特性分支的平台工程/DevOps 团队
• 追求无人值守自动化的 AI 驱动开发团队
• 已有容器化 CI/CD 环境，可安全开启 sandbox bypass 的云原生团队
• 需要多任务并行的大型项目维护者

常规风险

• 权限升级：danger-full-access 或 dangerously-bypass-approvals-and-sandbox 模式下，Codex 可能执行任意代码，必须严格限制在隔离环境中
• 代码质量：AI 生成的代码可能存在边界条件遗漏、竞态条件，必须配置多模型评审与 CI 门禁
• 敏感信息泄露：Prompt 中可能意外包含凭据、内部架构信息，需建立 prompt 审查流程
• 无限循环/静默卡死：虽配置 12 小时静默检测，但复杂任务仍可能因逻辑错误长期占用资源
• 依赖污染：自动安装依赖可能引入漏洞包，建议预装固定版本依赖后启动 Agent

概述

Codex Agent Skill 是一套面向 OpenAI Codex CLI（GPT-5/GPT-5.1 系列模型）的生产级自动化编码工作流，将 Codex 从简单的命令行工具升级为完整的托管代理系统。

核心能力

双模式执行架构

Quick Mode（快速模式）：针对单文件修改、bug 修复等轻量任务，采用 codex exec 非交互执行，配合 background=true + pty=true 实现后台异步运行。独创轮询-延长（Poll-and-Extend）机制替代硬超时，避免任务被过早终止——通过每 5 分钟轮询进程状态，12 小时静默阈值才触发人工确认。

Full Mode（完整模式）：面向复杂功能开发，构建隔离工作流：

• Git worktree 隔离分支环境
• tmux 会话实现中途干预（send-keys 重定向而非 kill）
• pipe-pane + stdbuf 实现全量日志持久化
• JSON 任务注册表追踪多任务状态

智能质量 gates

定义明确的 DoD（Definition of Done）：PR 创建 → 无冲突 → CI 通过 → 跨模型代码审查 → UI 截图（如适用）。强制要求使用与编写代码不同的模型进行审查（Claude 审 Codex 或反之），以捕获单模型盲点。

自适应重试策略

非盲目重试，而是分类失败原因（上下文溢出/方向偏差/信息缺失/CI 失败）并针对性调整提示词，最多 3 次后人工介入。自动捕获失败日志、CI 状态注入重试上下文。

显著优势

1. 生产可靠性：日志持久化、退出码捕获、12 小时静默检测等细节处理，避免自动化常见陷阱
2. 人机协作设计：tmux send-keys 实现"轻推"而非"重启"，保留代理上下文的同时纠正方向
3. 并行扩展性：标准化 launch_codex 辅助函数支持多仓库并发开发
4. Codex 特性深度整合：reasoning effort 分级、danger-full-access 沙盒模式、JSON 输出、session resume 等

局限性与风险

| 维度 | 说明 |

|------|------|

| 环境依赖 | 强制要求 tmux、Codex CLI、gh CLI 预配置，Docker 化程度不足 |

| 上下文窗口 | 长任务仍可能触发 token 限制，需人工 `send-keys` 收窄范围 |

| 安全边界 | `--dangerously-bypass-approvals-and-sandbox` 在容器外使用存在风险 |

| 适用场景 | 适合有明确验收标准的编码任务，不适合探索性架构设计 |

| 监控成本 | 需要主动轮询，非事件驱动架构 |

适合人群

• 高级开发者：熟悉 tmux、git worktree、shell 自动化，追求规模化编码效率
• 平台工程师：构建内部 AI 编码平台的团队，需要可观测、可干预的代理系统
• 开源维护者：批量处理 issue、模板化功能开发

使用建议

务必在容器/VM/隔离工作目录中启用全自动化模式；生产代码库中禁用 --dangerously-bypass-approvals-and-sandbox 或配合 mandatory code review；首次使用建议用 read-only 模式验证 Codex 对代码库的理解程度。