> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawflow.daboluo.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Workers — 灵活的执行器模型

> 类 GitLab Runner 的执行器架构：SaaS 默认跑，也能绑定到你自己的机器、VPN 内网、GPU 集群。

## 概览

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（本机）

```bash theme={null}
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 直接改：

```bash theme={null}
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](/billing)） |
| 任何注册的外部 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](https://github.com/daboluocc/clawflow-saas/issues/43)。