核心用法
OpenClaw Swarm Layer 是一个 spec-driven 的工作流编排引擎，专为 AI 驱动的复杂任务设计。其核心工作流遵循 Write Spec → Plan → Run → Review 的闭环模式：用户以 Markdown 格式编写包含目标与阶段的工作流规范，系统通过 swarm plan 生成任务依赖图，随后以 manual/acp/subagent 三种运行器之一执行任务，并在关键节点设置审查门禁（review gates）。
关键操作包括：
- 初始化：
swarm init创建项目结构 - 计划执行：
swarm plan解析规范 →swarm run调度任务（支持--dry-run预演） - 会话管理：
session *系列命令实现持久会话复用、任务注入与异常取消 - 诊断修复：
swarm doctor检测 bridge 健康状态，自动提供 remediation 建议 - 报告生成：自动输出 Markdown 报告至本地或 Obsidian 仓库，包含 attention items、review queue、session reuse 分析等
显著优点
1. 多运行器架构：原生支持人工执行（manual）、外部 AI Harness（ACP/Codex/Claude Code）、OpenClaw 子代理三种模式，灵活适配不同安全与自动化需求
2. 持久会话策略：create_persistent/reuse_if_available 等策略显著降低多轮任务冷启动开销
3. 故障自愈能力：自动重试、dead letter 识别、stale session 清理、bridge 版本漂移检测
4. 可观测性完善：结构化 JSON 输出、Obsidian 双向同步、运行日志与审查日志自动归档
5. 声明式规范：Markdown 格式的 spec 降低使用门槛，同时保持机器可解析性
潜在缺点与局限性
- Node.js 22+ 硬依赖：运行时版本要求较激进，旧环境迁移成本高
- Bridge 配置复杂度：ACP/bridge 的 JSON 配置涉及路径变量、版本白名单，初次 setup 易出错
- 审查门禁人工瓶颈：
review环节默认可阻断自动化流，大规模任务需批量 approve 机制 - Obsidian 同步为异步：非实时镜像，关键场景需确认本地报告完整性
适合人群
- AI 工程团队：需将 Codex/Claude Code 等工具纳入可审计、可回滚的工作流
- 平台运维/SRE：管理多项目 AI 任务，需统一会话生命周期与故障诊断入口
- 合规敏感组织：要求人机协同审查（human-in-the-loop）与完整操作审计链
常规风险
| 风险场景 | mitigation |
|---------|-------------|
| Bridge 版本漂移导致执行阻塞 | 升级后执行 `doctor --json`，按 remediation 更新 `versionAllow` |
| 持久会话泄漏资源 | 配置 `--stale-minutes` 自动清理，或 cron 执行 `session cleanup` |
| 子代理权限越界 | 严格配置 `allowedAgents` 白名单，配合 `review` 门禁 |
| 敏感数据落入 Obsidian 日志 | 审计 `obsidianJournal` 配置项，必要时禁用 `enableRunLog` |