> ## 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.

# Get Started

> 从零开始把 ClawFlow 接入自己的 GitHub / GitLab 仓库，完成第一次 Issue → PR 自动化

欢迎使用 ClawFlow 托管 SaaS（[https://clawflow.daboluo.cc](https://clawflow.daboluo.cc)）。
本文档指导你完成从账号登录到首次流水线触发的全流程。

***

## 1. 前置条件

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

***

## 2. 账号与登录

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

直接访问 [https://clawflow.daboluo.cc](https://clawflow.daboluo.cc) ，右上角选 **Login with GitHub** / **Login with GitLab**。
首次登录系统会自动为你创建一个 **Organization**，你是 Owner。

### 2.2 CLI 登录（用于 worker）

```bash theme={null}
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 详解

```yaml theme={null}
saas_url: https://clawflow.daboluo.cc
worker_token: cfw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

| 字段             | 含义                                                                           |
| -------------- | ---------------------------------------------------------------------------- |
| `saas_url`     | 你接入的 SaaS 根地址                                                                |
| `worker_token` | 以 `cfw_` 开头的机器凭据；`/api/v1/worker/tasks` 等接口用 `Authorization: Bearer cfw_...` |

Token 只在 rotate 时显示一次，妥善保管。丢了就去仪表盘 rotate 一个新的（旧的立刻失效）。

***

## 4. 启动 worker

```bash theme={null}
clawflow worker start
# 或调整轮询间隔
clawflow worker start --poll-interval 30
```

worker 会：

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}`

worker 在前台跑，建议用 `tmux` / `screen` / `systemd` 守护。

***

## 5. 添加仓库

### 5.1 仪表盘操作

1. [https://clawflow.daboluo.cc/dashboard](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

在 GitHub 仓库 **Settings → Webhooks → Add webhook**：

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

GitLab 对应路径为 `/api/v1/webhooks/gitlab`，方式类似。

***

## 6. 触发一次流水线

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

### 标签状态机

| 标签                | 含义                   | 是否扣 credits |
| ----------------- | -------------------- | ----------- |
| `ready-for-agent` | 用户触发，待评估             | 否           |
| `agent-evaluated` | 评估通过 + PR 已提交        | ✅ 成功时扣      |
| `agent-failed`    | 执行失败（构建 / 测试 / 提交错误） | 否           |
| `agent-skipped`   | 可行性预评分过低，跳过          | 否           |

***

## 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 阶段

**服务端** 无法访问 `github.com/login/oauth/access_token`。自建 SaaS 时常见，
在国内服务器需要配置 `HTTPS_PROXY` 环境变量。托管 SaaS 已配好，一般不会遇到。

### 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](https://clawflow.daboluo.cc/dashboard) → **Settings** → **Rotate Worker Token**
* **命令行**：重跑 `clawflow login --saas-url https://clawflow.daboluo.cc`，会自动完成 OAuth + rotate + 重写 `worker.yaml`

旧 token 在 rotate 的瞬间失效，正在运行的 worker 会在下一次轮询报 401，此时重启 worker 即可读到新 token。

***

## 10. 托管 vs Self-Host

| 维度        | 托管 SaaS               | Self-Host                 |
| --------- | --------------------- | ------------------------- |
| 部署        | 无                     | 需自建 Postgres + 部署 Rust 后端 |
| OAuth App | 内置                    | 要自己在 GitHub / GitLab 注册   |
| 升级        | 自动                    | 手动 `git pull` + 重新部署      |
| 数据主权      | 数据在我们                 | 完全自主                      |
| 定价        | outcome-based credits | 自付基础设施成本                  |
| 推荐人群      | 个人 / 小团队 / 先试用        | 大企业 / 合规强要求               |

自建走 [https://github.com/daboluocc/clawflow-saas](https://github.com/daboluocc/clawflow-saas) 仓库 README。

***

## 11. 下一步

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

***

## 反馈

* Bug / 需求：[https://github.com/daboluocc/clawflow-saas/issues](https://github.com/daboluocc/clawflow-saas/issues)
* CLI 侧问题：[https://github.com/zhoushoujianwork/clawflow/issues](https://github.com/zhoushoujianwork/clawflow/issues)