Workers — 灵活的执行器模型

概览

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

两种方式：

Dashboard UI：Repo 列表 → 点进 repo 设置 → Runners 多选 → Save Settings
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 = running`	`clawflow worktree create` 或 SaaS runner 开始执行
`status = success` + `pr_url`	`clawflow pr create` 或 SaaS runner 成功提交 PR
`status = failed` / `skipped`	CLI 或 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。

​概览

​三种场景对照

​任务调度流程

​注册 Worker（本机）

​把仓库绑定到特定 Worker

​精确分发：X-Agent-Id

​计费规则

​上报与 Dashboard 可见性

​未登录 SaaS = 零影响

​常见问题

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

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

​worker 离线了会怎样？

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

​部署进度

概览