ClawSpec + OpenSpec 入门：让项目自动地、持续地推进，避免中断和人工干预

难度：入门 | 时长：20 分钟 | 收获：在聊天窗口里用 OpenSpec 管理项目全流程，让 AI 持续开工不卡壳

---

目标读者

你已经跑起了 OpenClaw，开始用它处理日常任务。用的过程中，你可能已经遇到这个问题：

需求聊得挺明白，agent 也答应开工了，但过一会儿你再看，它停在那儿了，不继续推进，等你催。

尤其是长期任务、需求变更、边聊边做的场景，这个问题尤其明显。你需要的不只是一个会聊天的 AI，而是一个能把需求理顺、持续推进、不靠人盯着还能自动恢复的执行系统。

本文的目标读者：

• 已在用 OpenClaw，希望在聊天内完成完整项目周期（需求 → 规划 → 代码 → 归档）
• 有过 agent 开工后停滞的经历，想找到可控的持续执行方案
• 对 OpenSpec 工作流感兴趣，想把它直接嵌进 OpenClaw

---

核心依赖与环境

GitHub 仓库：https://github.com/bytegh/clawspec

---

完整项目结构

ClawSpec 插件目录结构（安装后）：

clawspec/
├── index.ts                    # 插件入口
├── src/                       # 核心源码
│   ├── service/               # 服务层
│   ├── watcher/               # 后台 watcher 管理
│   ├── stores/                # 状态存储
│   └── hooks/                 # OpenClaw hooks
├── skills/                    # OpenSpec skill 文本（内置）
├── test/                      # 测试用例
├── openclaw.plugin.json       # 插件配置
├── package.json
└── tsconfig.json

运行时，每个 repo 下会生成 OpenClaw 管理文件：

<repo>/
├── .openclaw/clawspec/        # ClawSpec 运行时状态
│   ├── state.json             # 当前项目状态
│   ├── execution-control.json # cs-work 执行控制
│   ├── execution-result.json  # 执行结果
│   ├── worker-progress.jsonl  # 后台进度日志
│   ├── planning-journal.jsonl  # 需求讨论记录
│   ├── planning-journal.snapshot.json  # journal 快照
│   ├── rollback-manifest.json # 回滚清单
│   ├── snapshots/             # change 快照基线
│   │   └── <change-name>/
│   │       └── baseline/
│   └── archives/              # 已归档的 change
├── openspec/                  # OpenSpec 规范目录
│   └── changes/<change-name>/
│       ├── .openspec.yaml
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/

---

手把手步骤

Step 1：安装 ClawSpec 插件

ClawSpec 提供三种安装方式，推荐第一种：

方式 A：通过 OpenClaw 插件安装器（推荐）

openclaw plugins install clawspec@latest

方式 B：通过 ClawHub CLI

npx clawhub@latest install clawspec

方式 C：npm 包手工安装（兜底）

$pkg = npm pack clawspec@latest
openclaw plugins install $pkg

@latest 会始终解析到 npm 上最新发布的 ClawSpec 版本。如果你要安装一个还未发布到 npm 的开发中提交，请改用本地 checkout 或下载好的 .tgz 包安装。

---

Step 2：配置 OpenClaw

安装完成后，需要在 ~/.openclaw/openclaw.json 里启用 ACP 并配置 ClawSpec：

{
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "claude"
  },
  "plugins": {
    "entries": {
      "clawspec": {
        "enabled": true,
        "config": {
          "defaultWorkspace": "~/clawspec/workspace",
          "openSpecTimeoutMs": 120000,
          "watcherPollIntervalMs": 4000
        }
      }
    }
  }
}

关键配置项说明：

如果你的 OpenClaw 没有自带 ACPX，ClawSpec 会自动安装一份插件本地的副本，不需要你手工处理。ACPX 的命令路径由 ClawSpec 自己管理，不需要额外配置。

配置完成后，重启 gateway：

openclaw gateway restart
openclaw gateway status

---

Step 3：绑定 workspace 与项目

ClawSpec 按 chat channel 记忆 workspace，每个 channel 可以绑定不同的项目根目录。

/clawspec workspace "D:\clawspec\workspace"
/clawspec use "demo-app"

预期结果：

• ClawSpec 把 workspace 路径记到当前 chat channel 上
• 如果 demo-app 目录不存在，会自动创建
• 第一次选中这个 repo 时，会自动执行 openspec init

---

Step 4：创建 OpenSpec change，进入项目上下文

/clawspec proposal add-login-flow "Build login and session handling"

这行命令做了三件事：

1. 在 openspec/changes/add-login-flow/ 下创建标准脚手架（proposal.md、design.md、tasks.md、specs/）
2. ClawSpec 为当前已跟踪文件拍一份快照基线（用于后续 rollback）
3. 当前聊天进入 add-login-flow 这个 active change 上下文

之后所有聊天内容，只要处于 attached 状态，就会自动写入 planning journal。

---

Step 5：在聊天里描述需求

在聊天里正常描述你的需求，比如：

支持邮箱加密码登录。
需要 refresh token。
access token 15 分钟过期。

ClawSpec 会把这些内容自动追加到 planning-journal.jsonl 里。此时不会立刻刷新 artifacts，也不会开始写代码——这个阶段只记录，不行动。

如果你想让后台继续跑，但当前窗口先去聊别的事，可以用：

cs-detach

这会把普通聊天从 planning journal 中分离，但 watcher 的进度推送仍然继续。后面想接回来，用：

cs-attach

---

Step 6：cs-plan，可见式规划同步

当你觉得需求聊得差不多了，执行：

cs-plan

ClawSpec 会在当前可见聊天回合里，直接刷新这些 artifacts：

• proposal.md — 项目提案
• design.md — 架构设计
• specs/ — 详细规格
• tasks.md — 任务列表

cs-plan 不走后台 ACP worker，不依赖隐藏的 subagent——你能在主聊天窗口直接看到 AI 刷新 artifacts 的过程。

---

Step 7：cs-work，启动后台持续实现

Planning 刷新干净之后，启动后台实现：

cs-work

cs-work 不会在主聊天窗口里直接写代码，它走的是这条链路：

1. 验证 planning 状态干净（dirty journal 会被拦截）
2. 写入 execution-control.json，激活 watcher
3. watcher 通过 acpx 启动 ACP worker session
4. worker 按 tasks.md 逐 task 执行，更新进度，写入 worker-progress.jsonl
5. watcher 把 worker 的进度事件翻译成简短聊天消息推回给你

你的聊天窗口会陆续收到这类消息：

[Watcher] ACP worker connected...
[Worker] Preparing login-flow: loading context
[Worker] Loaded proposal.md
[Worker] Context ready for Task 1
[Worker] Task 1/5 complete: 用户认证模块
[Worker] Task 2/5 complete: Token 刷新逻辑
...
[Worker] All tasks complete.

---

Step 8：进度追踪与恢复

这是 ClawSpec 最核心的能力之一——gateway 重启后，worker 自动续接。

当 gateway 重启时，watcher manager 会：

• 扫描所有活动项目
• 优先尝试接管仍然存活的 ACP worker session
• 如果旧 worker 已死，自动重新 arm 并启动替代 worker
• 保留 task 进度和 worker progress offset

也就是说，你不需要在 gateway 重启后手动去催 cs-work。ClawSpec 会自动把断掉的工作接回来。

运行时查看 worker 状态：

/clawspec worker status

这会显示：

• 当前配置的 worker agent
• 传输层状态（connected / disconnected）
• Startup phase（loading context / ready / running）
• 实时 pid、heartbeat、下一步建议

ACP worker 失败时，ClawSpec 会区分"可恢复故障"和"真实 blocker"，对可恢复故障做有限次数、带退避的重试。超过重试上限（默认 10 次）后，项目标记为 blocked，需要你手动介入修复。

协作式暂停和继续：

cs-pause        # 让 worker 在安全边界暂停
cs-continue     # 恢复 planning 或 implementation

---

Step 9：归档与收尾

当所有 task 完成后，清理活动 change：

/clawspec archive

这会：

1. 校验 OpenSpec change 的完整性
2. 把已完成 change 移到 archives/ 目录
3. 清掉当前聊天里的 active change 状态

如果你想放弃当前 change（不保留代码变更）：

/clawspec cancel

ClawSpec 会从快照基线恢复它跟踪的文件，而不是做整仓库级别的 git reset --hard。

这是完整的工作循环：

聊需求 → cs-plan → cs-work → 等待进度 → cs-detach（可选）→ cs-attach（可选）
→ /clawspec archive（完成后）

---

常见问题排查

1. cs-work 提示"需要先 planning sync"

原因：

• planning journal 变 dirty（snapshot 之后又聊了新需求）
• planning artifacts 缺失或过期
• OpenSpec apply state 仍处于 blocked

处理方式：

cs-plan
# 等 planning 完成
cs-work

---

2. Watcher 提示 ACPX 不可用

原因可能是：

• acp.enabled 未开启
• acp.backend 不是 acpx
• acp.defaultAgent 未配置
• OpenClaw 没有自带 ACPX，且 ClawSpec 也没找到可用副本

快速修复：

openclaw config set acp.backend acpx
openclaw config set acp.defaultAgent claude
openclaw gateway restart
cs-work

如果 ACPX 仍然不可用，ClawSpec 会自动尝试安装插件本地副本。首次安装可能需要一点时间和网络访问。

---

3. 普通聊天污染了 planning journal

正常聊天被记录进了 journal，后面 cs-work 被 dirty 拦截。

立即分离：

cs-detach

后续想继续讨论需求时：

cs-attach

---

4. Worker 已连接，但没有开始 task

这通常说明 ACP worker 已经活了，但还在消化 implementation prompt 或读取 planning artifacts。

优先检查这两类消息：

• Watcher 侧状态："starting worker", "ACP worker connected..."
• Worker 写出的加载状态："Preparing <task>: loading context", "Loaded proposal.md", "Context ready..."

如果已经看到 "Context ready for ..."，说明 worker 已经读完 artifacts，接下来就会进入第一个 task。

运行 /clawspec worker status，重点看 startup phase 和 startup wait 两个字段，判断 worker 当前卡在哪一步。

---

5. Worker 报错 "stdin is not a terminal" 或 session 创建无结果

原因：

• ~/.acpx/config.json 中存在自定义 agent 配置（例如 agents.codex 指向了本地 CLI 路径）
• acpx 在非交互式环境下无法通过 raw CLI 方式启动 agent

运行诊断：

/clawspec doctor

如果报告了自定义 agent 配置问题，运行自动修复：

/clawspec doctor fix

手动修复：编辑 ~/.acpx/config.json，将 "agents" 设为空对象：

{
  "agents": {}
}

---

6. /clawspec use 提示已有 unfinished change

这是预期行为。ClawSpec 不允许你在同一个 repo 上静默丢下一个 active change。

三选一：

/clawspec continue      # 继续当前 change
/clawspec archive       # 归档已完成 change
/clawspec cancel        # 放弃当前 change

---

扩展阅读 / 进阶方向

1. OpenSpec CLI 高级用法

ClawSpec 内置的 OpenSpec CLI 本身就是一个完整的项目规范管理系统。你可以直接在项目目录里运行：

openspec status        # 查看当前 change 状态
openspec diff          # 对比当前文件与快照基线
openspec validate      # 校验 OpenSpec 规范完整性

深入理解 OpenSpec 的 propose → design → spec → task → apply 链路，可以让你更好地规划 change 的粒度和范围。

2. ClawSpec 多 channel 多 project 并行管理

ClawSpec 的 workspace 是按 channel 记忆的，这意味着你可以：

• Telegram channel 管后端 API 项目
• Discord channel 管前端项目
• 同一个 repo 在不同 channel 里可以有不同的 active change（但同一 repo 全局只允许一个未完成的 change）

善用 cs-detach 让后台工作继续跑，而不需要在每个 channel 里持续盯着。

3. ACP worker 自定义 agent 配置

除了全局的 acp.defaultAgent，你还可以为特定 channel/project 切换 worker agent：

/clawspec worker codex    # 当前 channel/project 用 codex
/clawspec worker claude  # 切换回 claude

如果你有多个 agent 配置（比如不同能力级别的模型），这个功能可以让你针对不同复杂度的任务选择合适的 worker。

4. 与 OpenSpec 其他工具链协同

ClawSpec 输出的 tasks.md 和 proposal.md 可以被其他工具（如 Superpowers、自定义 CI 脚本）读取，形成更完整的项目管理闭环。OpenSpec 的规范文件是纯 Markdown，格式开放，不绑定特定 UI。

5. 自定义 ClawSpec 配置

plugins.entries.clawspec.config 还有这些高级选项：

{
  "clawspec": {
    "enabled": true,
    "config": {
      "archiveDirName": "archives",
      "allowedChannels": ["ch_xxx", "ch_yyy"]
    }
  }
}

allowedChannels 字段可以限制 ClawSpec 只在指定的 channel 里生效，适合团队里有部分 channel 不需要这个工作流的场景。