Get Started

​

1. 前置条件

• clawflow CLI ≥ v0.15.0
  clawflow --version
  # 低于 v0.15.0 请先 `clawflow update`
  
• Claude Code 本地可用（worker 会调用 claude -p "ClawFlow run" 执行修复）
• 一个拥有管理员权限的 GitHub / GitLab 仓库（要能给 Issue 打标签、接收 Webhook）

​

2. 账号与登录

​

2.1 浏览器登录（用于仪表盘）

​

2.2 CLI 登录（用于 worker）

clawflow login --saas-url https://clawflow.daboluo.cc

1. CLI 启动一个本地回调端口（http://localhost:PORT/callback）
2. 浏览器打开 SaaS OAuth 页面，完成 GitHub 授权
3. SaaS 把一次性 code 发回本地端口
4. CLI 用 code 换 JWT，再用 JWT 调用 /api/v1/orgs/current/worker-token 获取 worker token
5. 最终写入 ~/.clawflow/config/worker.yaml

Login successful.
  saas_url:     https://clawflow.daboluo.cc
  worker_token: cfw_xxxxxxxx***
  config:       ~/.clawflow/config/worker.yaml

​

3. worker.yaml 详解

saas_url: https://clawflow.daboluo.cc
worker_token: cfw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​

4. 启动 worker

clawflow worker start
# 或调整轮询间隔
clawflow worker start --poll-interval 30

1. 每 poll-interval 秒 GET /api/v1/worker/tasks
2. 发现 pending 任务后 POST /api/v1/worker/tasks/{id}/claim
3. 把任务 payload 作为 stdin 喂给 claude -p "ClawFlow run"
4. 成功 → POST .../complete 带 {pr_url}；失败 → POST .../fail 带 {reason}

​

5. 添加仓库

​

5.1 仪表盘操作

1. https://clawflow.daboluo.cc/dashboard → Repos → Add Repo
2. 填写 owner/name、选平台（GitHub / GitLab）、粘贴仓库访问 token
   • GitHub：Personal Access Token（classic），勾选 repo + admin:repo_hook
   • GitLab：Personal Access Token，勾选 api
3. 保存。Token 以 AES-256-GCM 加密入库，不明文保存。
4. 点击 Test Connection 确认连通性。

​

5.2 配置 Webhook

• Payload URL: https://clawflow.daboluo.cc/api/v1/webhooks/github
• Content type: application/json
• Secret: 仪表盘添加仓库时复制的 webhook secret
• Events: 至少勾选 Issues（带 labeled action）

​

6. 触发一次流水线

1. 在你添加的仓库里选一个 Issue
2. 打上标签 ready-for-agent（首次使用若标签不存在，仪表盘添加仓库时会自动创建）
3. 回到仪表盘 Pipeline Runs 页，几秒内应看到一条 pending 记录
4. 本地 worker 在下次轮询时会认领并执行
5. 成功后 Issue 标签变为 agent-evaluated，自动提交一个 PR

​

标签状态机

​

7. 计费

• Outcome-based：只有 PR 成功提交（agent-evaluated）才扣 1 credit
• agent-failed / agent-skipped 不扣 credits
• 仪表盘 Billing 页可看实时余额、历史用量、充值记录

​

8. 常见错误排查

​

8.1 clawflow login 超时

Error: timed out waiting for OAuth callback

• 浏览器是否完成了 GitHub 授权？
• 回调地址 http://localhost:PORT/callback 是否被本机防火墙拦截？
• SaaS 侧是否能反向回访 localhost？—— CLI 流程只要求 GitHub 能访问 SaaS、SaaS 能 302 到 localhost，一般不会卡。

​

8.2 github exchange failed: error sending request

发生在 OAuth callback 阶段

​

8.3 worker start 报 401

status 401: invalid or missing worker token

• 看 ~/.clawflow/config/worker.yaml 的 worker_token 是否被截断
• 仪表盘 rotate 过后旧 token 就失效了，需要重跑 clawflow login
• 或直接 clawflow config set --saas-url ... --token cfw_... 手动写入

​

8.4 worker 一直轮询但不认领

• 确认 Issue 已被打上 ready-for-agent 标签
• 仪表盘 Pipeline Runs 有没有看到 pending 记录
  • 没有 → Webhook 没触发或 signature 校验失败，检查 webhook secret
  • 有 pending 但 worker 不认领 → worker 的 saas_url / worker_token 是否和仪表盘的 org 对齐

​

8.5 PR 没提交但任务显示 complete

• worker 的 Claude Code 会话里有没有报错
• 查看 worker 终端输出 [task <id>] complete, pr=<url> 的 URL 是否为空

​

9. Rotate worker token

• 仪表盘：https://clawflow.daboluo.cc/dashboard → Settings → Rotate Worker Token
• 命令行：重跑 clawflow login --saas-url https://clawflow.daboluo.cc，会自动完成 OAuth + rotate + 重写 worker.yaml

​

10. 托管 vs Self-Host

​

11. 下一步

• 邀请队友：仪表盘 Organization → Invite Member（支持 owner / admin / member 三级角色）
• 接入多个仓库：同一 org 下可配多仓库，worker 统一拉队列
• 查看分析报表：Analytics 页看成功率、平均修复时长、按仓库分布

​

反馈

• Bug / 需求：https://github.com/daboluocc/clawflow-saas/issues
• CLI 侧问题：https://github.com/zhoushoujianwork/clawflow/issues