Skip to main content

​
概览

ClawFlow 采用类 GitLab Runner 的 worker 模型。每个仓库可以：
  • 不配置 worker（默认）→ 由 SaaS 托管的默认 runner 跑
  • 绑定一个或多个 worker → 只有被绑定的 worker 能抢到该仓库的任务
这样同一个平台能覆盖多种部署场景：公有云托管、自带机器、公司内网 VPN、GPU 集群 ……

​
三种场景对照

场景Repo 配置实际执行者
纯 SaaS 托管workers = []（默认）SaaS 默认 runner
本地笔记本跑workers = [你的 laptop]你本机的 clawflow CLI
公司内网仓库workers = [corp-vpn-runner]部署在 VPN 内的 worker
多台机器轮流抢workers = [worker-a, worker-b]谁空闲谁抢
词汇 — 抢占 (qiǎng zhàn) = first-come-first-served claim；默认 runner (mò rèn runner) = default runner。

​
任务调度流程

Webhook 收到 ready-for-agent 标签
      ↓
pipeline_runs 表插入一条 status=pending
      ↓
   ┌──────────────────────────────────────┐
   │  cardinality(repo.workers) == 0 ?    │
   └──────────────────────────────────────┘
            │ YES                  │ NO
            ↓                      ↓
     SaaS 默认 runner       repo.workers 里的
       抢任务                某个 worker 抢任务
            ↓                      ↓
     扣 credits（云端）       不扣 credits（本地）

​
注册 Worker（本机）

clawflow connect run \
  --url https://clawflow.daboluo.cc \
  --token <api-token> \
  --org-id <org-uuid> \
  --tags docker,gpu           # 可选：描述机器能力的标签

clawflow worker start         # 开始抢任务
注册后你的 worker 会出现在 Dashboard 的 Workers 列表里，带上 tags 和在线状态。

​
把仓库绑定到特定 Worker

两种方式：
  1. Dashboard UI：Repo 列表 → 点进 repo 设置 → Runners 多选 → Save Settings
  2. API 直接改：
curl -X PUT https://clawflow.daboluo.cc/api/v1/repos/<repo_id> \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"workers": ["<agent_uuid_1>", "<agent_uuid_2>"]}'
空数组 [] = SaaS 默认 runner 跑。

​
精确分发：X-Agent-Id

当你有多台 worker 绑定到不同 repo 时，每个 worker 拉任务时会带上 X-Agent-Id 头，SaaS 只返回 agent_id = ANY(repo.workers) 的任务。这样 worker-A 不会看到只绑定给 worker-B 的任务。 CLI 会自动从 ~/.clawflow/saas.json（connect run 后写入）读取 agent_id 并带上这个头，无需手动配置。

​
计费规则

按执行者归属划分：
执行者是否扣 credits
SaaS 默认 runner（agent_id IS NULL）✅ 扣（按 Plan markup）
任何注册的外部 worker❌ 不扣（你自己的机器、你自己的 API key）
外部 worker 仍然会上报 usage 到 Dashboard 用于统计（谁跑了多少任务），但不影响余额。

​
上报与 Dashboard 可见性

两种执行路径都走同一个上报接口，Dashboard 实时可见：
事件触发点
status = runningclawflow worktree create 或 SaaS runner 开始执行
status = success + pr_urlclawflow pr create 或 SaaS runner 成功提交 PR
status = failed / skippedCLI 或 SaaS runner 分别的失败/跳过路径

​
未登录 SaaS = 零影响

clawflow CLI 在未运行 clawflow login 时：
  • 所有上报动作静默跳过（无错误、无警告、无网络请求）
  • 本地执行完全不受影响
  • 即使网络临时中断，上报也不会阻塞 CLI
你的代码、你的 token，何时接入 SaaS 由你决定。

​
常见问题

​
怎么决定一个仓库用 SaaS 还是自己的 worker？

选它理由
SaaS 默认 runner省心、不用维护机器、适合公开 GitHub 仓库
自己的 worker代码 / token 不出本机、内网仓库、有特殊环境依赖（GPU、私有镜像）

​
一个 worker 能服务多个仓库吗？

能。绑定是多对多：同一个 worker 可以被多个 repo 的 workers 列表引用。

​
worker 离线了会怎样？

  • 若是唯一绑定的 worker：任务留在 pending 状态，等 worker 上线再抢
  • 若多个 worker 绑定到该 repo：其他在线的 worker 会抢走
  • 若全部 worker 离线且 workers 非空：不会 fallback 到 SaaS 默认 runner（避免用户原本想私有执行的仓库被意外上云）

​
从旧的 execution_mode=local 迁移需要做什么？

旧的 execution_mode 列保留作兼容层，但不再驱动调度。迁移时只需把你原来期望本地跑的仓库的 workers 设置为你自己 agent 的 UUID。未来某个大版本会删除 execution_mode 列。

​
部署进度

功能状态
后端调度（workers 字段驱动）✅ 已上线
Worker 注册带 tags✅ 已上线
Dashboard Workers 展示✅ 已上线
API PUT workers 字段✅ 已上线
Dashboard 仓库设置 Runners UI✅ 已上线
X-Agent-Id 精确任务分发✅ 已上线
删除旧 execution_mode 列🟡 规划中
跟进：#43。