OpenClaw Claude Codex Workflow

OpenClaw Claude Codex 工作流

概述

• 架构：Claude Code 作为 planner/reviewer，Codex 作为具备 PTY 的后端执行器，Gemini 作为前端/UX 生成器；所有阶段通过 .claude/ 工件与 scripts/ccg_orchestrator.sh 协同串联。
• 保障机制：所有写操作均由 Codex/Gemini 在本地工作树中执行，Claude 仅负责生成文本或 plan；每个阶段均在 Git 干净状态下启动，并严格遵循 [references/workflow-checklist.md](references/workflow-checklist.md) 所列检查项。
• 交付成果：不仅包含可运行代码，还涵盖 plan、hooks、测试矩阵（test matrix）、review memo 等完整工件，满足 ccg-workflow 所定义的高标准交付规范。

Quick Start

前置条件

• 安装 Node.js 20+、jq、GNU coreutils；执行 git status 必须返回干净状态，或显式设置环境变量 ALLOW_DIRTY=1。
• 安装并验证 CLI 工具可用性：claude --version（Claude Code CLI）、codex --version（Codex CLI）、gemini --version（Gemini CLI）；各 CLI 官方安装方式请参考对应厂商文档。
• 配置认证凭据：CLAUDE_API_KEY、CODEX_API_KEY、GOOGLE_API_KEY 等；需在 shell profile（如 ~/.bashrc 或 ~/.zshrc）中通过 export 声明，确保脚本可继承。

安装 / 挂载

1. 确保当前仓库位于 /root/.openclaw/workspace 或其他可写工作树路径下。
2. 将用户需求或 OPSX ticket 内容粘贴至 .claude/context.md。

3. 运行主控脚本：

   scripts/ccg_orchestrator.sh .claude/plan.md \
     --plan-prompt "" \
     --backend "" \
     --frontend "" \
     --review "" \
     --context .claude/context.md

4. 根据脚本输出的日志，切换至对应模型 CLI 执行；必要时使用 --dry-run 参数先行审阅拟执行命令。

Git 规则

• 禁止外部模型直接修改工作区：仅允许 Codex/Gemini 通过本地 shell 执行文件变更。
• 每个阶段结束前，必须运行 git status 与 git diff --stat，并将结果记录至 .claude/log_backend.md 或 .claude/log_frontend.md。
• 为 Gemini 分配独立空间：使用 git worktree add ../frontend 创建专用工作树，避免与 Codex 操作冲突。

Workflow Decision Tree

更多启发式路由规则详见 [references/model-routing.md](references/model-routing.md)。

Phase 0：Context Capture（上下文采集）

• 依据 [references/workflow-checklist.md](references/workflow-checklist.md) 填写 .claude/context.md 与 .claude/questions.md。
• 汇总 OPSX ticket、现有 spec / ADR 文档，并明确标注机密信息与不可修改目录（如 vendor/, .env.*）。
• 若资料缺口显著，可先调用 Claude 生成问题清单（question list），再反馈至请求方补充。

Phase 1：OPSX / Scope Alignment（范围对齐）

• 运行：claude run --input .claude/context.md --output .claude/scope.md；或通过 orchestrator 的 --plan-prompt 参数驱动 Claude 输出 scope。

• Scope 文档必须清晰界定：

  • backend/frontend 职责边界；
  • 需创建的工作树（worktree）名称与用途；
  • 所有安全约束（如合规要求、权限限制）。
• 若 OPSX 明确要求引用既有 spec 或 OPSX 模板，请在 scope 中注明对应章节编号（如 “Section 3.2”）。

Phase 2：Plan（计划制定）

• 执行 orchestrator：

  scripts/ccg_orchestrator.sh .claude/plan.md \
    --plan-prompt "" \
    --backend "..." \
    --frontend "..." \
    --context .claude/context.md

• 在 .claude/plan.md 中以表格形式列出详细任务清单，每行应包含：

  • owner（Codex 或 Gemini）；
  • command draft（如 codex exec --prompt "add payment webhook"）；
  • expected output files（如 src/api/webhook.ts, tests/webhook.test.ts）。
• 更新 .claude/hooks.md，记录 CLAUDE_CLI / CODEX_CLI / GEMINI_CLI 的实际路径替换规则，以及所需环境变量（如 NODE_ENV=staging）。
• 若该 plan 需 OPSX 审批，请将 .claude/plan.md 全文粘贴至 ticket，并等待显式 ACK（如 “APPROVED”），方可进入 Phase 3。

Phase 3：Execute（执行）

• Codex：必须启用 PTY（codex exec --pty）；严格按 plan 执行命令；新增脚本一律置于可写区域（如 scripts/ 或 tmp/）；对 orchestrator 生成的命令建议先用 --dry-run 验证。
• Gemini：仅限在独立工作树（如 ../-frontend）或 frontend/ 目录中运行 gemini run --prompt ...；输出严格限定于 UI 相关文件（.tsx, .css, .stories.tsx 等）；严禁写入 backend 目录。
• 每次模型切换前，须记录操作日志，并同步更新 .claude/log_backend.md 与 .claude/log_frontend.md。

Phase 4：Stabilize / Verification（稳定化与验证）

• Claude 汇总测试矩阵：claude run --context .claude/log_backend.md --output .claude/test_matrix.md。
• Codex 执行对应测试命令（如 npm test / pytest / go test），并将结果写入 .claude/test_matrix.md；Gemini 补充 UI 验收描述或截图路径（如 screenshots/modal-open.png）。
• 若任一模型缺席或触发 fallback，须在 .claude/test_matrix.md 中注明，并同步更新 OPSX ticket。

Phase 5：Review / Handoff（评审与交付）

• 通过 orchestrator 的 --review "" 参数，或手动执行：

  claude run --context .claude/plan.md --output .claude/review.md

  生成 review memo。

• Review 内容须涵盖：

  • diff 引入的风险点；
  • 回滚方案（rollback plan）；
  • 需人工复核的 TODO 列表；
  • 推荐合并策略（如 squash merge、rebase merge）。
• Codex 在合并前执行最终 git status 检查，并准备 PR 或 patch；若 OPSX 要求提供证据（evidence），须将 .claude/plan.md、.claude/test_matrix.md、.claude/review.md 一并附至 ticket。

模型执行细则

Claude Code CLI

• 职责边界：仅用于生成 plan、scope、review、test matrix 等文本工件；绝不修改仓库文件。
• claude run --prompt "..." --output file --context file 由 orchestrator 自动封装；必要时为其注入 .claude/context.md 作为上下文。
• 若 Claude CLI 执行失败，应回退至 [references/model-routing.md](references/model-routing.md) 中定义的 fallback 流程，并手动生成 plan。

Codex CLI

• PTY 强制要求：符合 OpenClaw coding-agent 规范；示例：

  codex exec --prompt "refactor payment API" --pty

• 写入限制：仅允许在已授权工作区或批准的工作树中写入文件；禁止在未经用户明确许可的目录中执行任意命令。
• 执行纪律：执行 patch 前必须通读 plan 全文；禁止脱离 plan 自行发挥。

Gemini CLI

• 作用域隔离：仅操作前端目录（如 frontend/, src/, public/）；默认不启用 PTY；如需 shell 能力，须先创建虚拟任务交由 Codex 协助完成。

• 常用命令示例：

  gemini run --prompt "build React modal" --plan .claude/plan.md

• 输出审查：所有 Gemini 生成文件须经 Codex 或人工二次审查，防范格式错误、依赖缺失或路径越界等问题。

Git / Worktree 策略

• 主分支（如 main）始终保持 clean；每个大型功能需新建分支 feature/，并同步创建附属工作树：

  git worktree add ../-frontend feature/

  专供 Gemini 使用。

• Codex 操作主工作树，Gemini 操作附属工作树；同步采用 git fetch + git merge 方式，禁止直接 push/fetch 覆盖对方工作树。
• 所有阶段日志（.claude/log_*.md）及 .claude/ 下全部工件（plan.md, hooks.md, test_matrix.md 等）均需纳入 commit，确保可追溯。

OPSX / Spec 集成

• Phase 0–2 中，必须将 OPSX ticket 链接、spec 版本号、关键假设完整写入 .claude/context.md 与 .claude/scope.md。
• 凡涉及数据库 schema 变更、Infra 配置等需审批操作，须先在 OPSX 中发表 comment 提出申请，并在 .claude/hooks.md 中标记为 “waiting for approval”。
• 当 OPSX 发布新约束（如新增合规字段、禁用某协议），须先更新 .claude/plan.md，再重新运行 orchestrator 触发模型重分配。

故障排查与安全护栏

• 使用 scripts/ccg_orchestrator.sh --dry-run 快速验证参数与流程；若报错 “command not found”，请按 Quick Start 补全 CLI 安装。
• 遇模型超时（timeout）：依据 [references/model-routing.md](references/model-routing.md) 的 fallback 规则重分配模型，并在 .claude/log_* 中留痕。
• 推送权限控制：Claude / Codex / Gemini 均不得直接执行 git push；仅允许 Codex 在本地执行 git commit 与 git push。
• 破坏性命令禁令：严禁执行未获显式授权的 destructive 命令（如 git reset --hard, rm -rf, chmod -R 777）；若业务确需，必须在 OPSX 中备注并取得书面同意。
• Patch 二次校验：所有自动生成的 patch 在合并前，必须经人工或 Claude Review 进行 diff 对比确认。

附加参考

• [references/model-routing.md](references/model-routing.md)：模型选择启发式规则与 fallback 机制说明。
• [references/workflow-checklist.md](references/workflow-checklist.md)：六阶段逐项检查清单（含安全、Git、合规、交付物等维度）。
• scripts/ccg_orchestrator.sh：核心协调脚本，封装 plan / execute / review 全流程；具体用法详见 Quick Start 及 Phase 2 / Phase 5。