Macro Pipeline Skill v3
Architecture
Two files, two locations:
| File | Location | Purpose | Mutable? |
|---|
| INLINECODE0 | Project repo (~/Documents/proyectos/<project>/) | State + progress | ✅ Yes (subagents update directly) |
| INLINECODE2 |
Agent workspace (
~/.openclaw/workspace-<agent>/) | Instructions (read-only) | ❌ No (locked with
chflags uchg) |
Why PIPELINE in the repo?
- - Subagents work in the repo → can update status without cross-path issues
- Git-trackable (commits show when steps completed)
- Eliminates zombie steps from path access failures
Why HEARTBEAT in workspace?
- - Operational instructions for the OpenClaw agent
- Should not contaminate project code
- Locked to prevent agents from overwriting their own instructions
PIPELINE.md Format
CODEBLOCK0
Status values:
- -
[PENDING] — not started - INLINECODE6 — in progress (with timestamp)
- INLINECODE7 — done
- INLINECODE8 — failed (include error reason)
- INLINECODE9 — waiting on human or external dependency
Step fields:
- -
engine: — claude-code | human | INLINECODE13 - INLINECODE14 — list of step numbers that must be ✅ first
- INLINECODE15 — list of steps that can run simultaneously
- INLINECODE16 — shell command to validate completion
- INLINECODE17 — outputs passed to dependent steps
- INLINECODE18 — key files modified
HEARTBEAT.md Format
CODEBLOCK1
Cron Setup
Always use CLI, never edit openclaw.json:
CODEBLOCK2
Stagger schedules to avoid collisions:
- -
:00/:30 → Group A - INLINECODE20 → Group B
Subagent Task Template
Include in the task prompt:
Al terminar:
1. Actualiza <absolute-path-to-PIPELINE.md>: cambia Step X de [RUNNING] a [✅ COMPLETED] con output y artifacts
2. Si fallas, marca [FAILED] con el error
3. Notifica a Discord (action=send, channel=discord, target="channel:<id>") con resumen
Multiple Pipelines Per Project
An agent can have multiple pipeline files. HEARTBEAT specifies priority order:
Lee PIPELINE_ACTIVE.md (prioritario). Si todos completados, lee PIPELINE.md como fallback.
Parallel Execution
Steps sin dependencias cruzadas pueden ejecutarse en paralelo:
## Step 1: Task A [PENDING]
- parallel: [2, 3]
## Step 2: Task B [PENDING]
- parallel: [1, 3]
## Step 3: Task C [PENDING]
- parallel: [1, 2]
## Step 4: Task D [PENDING]
- depends_on: [1, 2, 3]
El heartbeat puede lanzar múltiples steps paralelos en un mismo ciclo si no hay dependencias.
Git Tagging
Cada step completado debe crear un commit taggeado:
git add . && git commit -m "pipeline/<project>/step-<N>: <step title>"
Esto da trazabilidad completa del progreso en git log.
Key Rules
- 1. PIPELINE.md siempre en el repo — nunca en workspace
- HEARTBEAT.md siempre en workspace — nunca en repo
- HEARTBEAT es immutable — locked con INLINECODE21
- Crons vía CLI —
openclaw cron add, nunca editar openclaw.json - Un step por heartbeat — evita saturación (salvo paralelos explícitos)
- verify: obligatorio — cada step debe tener comando de verificación
- Rutas absolutas — siempre usar
~/Documents/proyectos/... en HEARTBEAT - Git tag por step — commit con INLINECODE24
- Parallel explícito — steps sin dependencias pueden correr en paralelo si tienen INLINECODE25
Macro Pipeline Skill v3
架构
两个文件,两个位置:
| 文件 | 位置 | 用途 | 可变? |
|---|
| PIPELINE.md | 项目仓库 (~/Documents/proyectos/<project>/) | 状态 + 进度 | ✅ 是(子代理直接更新) |
| HEARTBEAT.md |
代理工作空间 (~/.openclaw/workspace-
/) | 指令(只读) | ❌ 否(使用 chflags uchg 锁定) |
为什么 PIPELINE 在仓库中?
- - 子代理在仓库中工作 → 可以更新状态而不会出现跨路径问题
- 可被 Git 追踪(提交记录显示步骤完成时间)
- 消除因路径访问失败导致的僵尸步骤
为什么 HEARTBEAT 在工作空间中?
- - OpenClaw 代理的操作指令
- 不应污染项目代码
- 锁定以防止代理覆盖自身指令
PIPELINE.md 格式
markdown
PIPELINE — <项目名称>: <管道标题>
项目: ~/Documents/proyectos/
目标: <一行目标>
创建日期: YYYY-MM-DD
步骤 1: <标题> [待处理]
- - 引擎: claude-code
- 描述: <要执行的操作>
- 文件: <要修改的关键文件>
- 验证: <证明步骤完成的命令>
- 产物: <供下一步使用的输出>
步骤 2: <标题> [待处理]
- - 引擎: claude-code
- 依赖: [1]
- 描述: <要执行的操作>
- 验证: <验证命令>
状态值:
- - [待处理] — 未开始
- [运行中 YYYY-MM-DDTHH:MM] — 进行中(带时间戳)
- [✅ 已完成] — 完成
- [失败] — 失败(包含错误原因)
- [阻塞] — 等待人工或外部依赖
步骤字段:
- - 引擎: — claude-code | human | deploy
- 依赖: — 必须首先 ✅ 的步骤编号列表
- 并行: — 可以同时运行的步骤列表
- 验证: — 用于验证完成的 shell 命令
- 产物: — 传递给依赖步骤的输出
- 文件: — 修改的关键文件
HEARTBEAT.md 格式
markdown
HEARTBEAT — <代理名称>
⚠️ 切勿修改此文件 (HEARTBEAT.md)。此为只读文件。
活动管道: ~/Documents/proyectos//PIPELINE.md
每次心跳协议:
- 1. 读取活动管道(上述绝对路径)
- 如果有 [待处理] 步骤且无阻塞依赖 → 执行它
- 标记为 [运行中 YYYY-MM-DDTHH:MM] 并附带当前时间戳
- 执行:sessions_spawn(task=..., thread=true)
- 每次心跳最多一个步骤
僵尸检测
如果某个步骤在 [运行中] 状态超过 2 小时,重置为 [待处理] 并报告。
与用户活跃会话中
优先回复。HEARTBEAT_OK。
Cron 设置
始终使用 CLI,切勿编辑 openclaw.json:
bash
openclaw cron add --name <项目> 管道 --agent --every 30m --message 心跳:读取 HEARTBEAT.md 并执行下一步
错开时间表以避免冲突:
- - :00/:30 → A 组
- :15/:45 → B 组
子代理任务模板
在任务提示中包含:
完成后:
- 1. 更新 :将步骤 X 从 [运行中] 改为 [✅ 已完成],包含输出和产物
- 如果失败,标记为 [失败] 并附带错误信息
- 通知 Discord(action=send, channel=discord, target=channel:)并附上摘要
每个项目多个管道
一个代理可以有多个管道文件。HEARTBEAT 指定优先级顺序:
读取 PIPELINE_ACTIVE.md(优先)。如果全部完成,则回退读取 PIPELINE.md。
并行执行
无交叉依赖的步骤可以并行执行:
markdown
步骤 1:任务 A [待处理]
步骤 2:任务 B [待处理]
步骤 3:任务 C [待处理]
步骤 4:任务 D [待处理]
如果无依赖关系,心跳可以在同一周期内启动多个并行步骤。
Git 标签
每个完成的步骤应创建一个带标签的提交:
bash
git add . && git commit -m pipeline//step-:
这提供了 git log 中完整的进度可追溯性。
关键规则
- 1. PIPELINE.md 始终在仓库中 — 绝不在工作空间中
- HEARTBEAT.md 始终在工作空间中 — 绝不在仓库中
- HEARTBEAT 不可变 — 使用 chflags uchg 锁定
- 通过 CLI 设置 Cron — openclaw cron add,切勿编辑 openclaw.json
- 每次心跳一个步骤 — 避免过载(除非显式并行)
- 验证:必填 — 每个步骤必须有验证命令
- 绝对路径 — 在 HEARTBEAT 中始终使用 ~/Documents/proyectos/...
- 每步 Git 标签 — 提交格式为 pipeline//step-:
- 显式并行 — 无依赖的步骤如果有 parallel: 字段则可以并行运行