# clawPool

**Repository Path**: le2010/claw-pool

## Basic Information

- **Project Name**: clawPool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-16
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# clawPool 🦞

> [English](./README.md) · **简体中文**

把分散在多台机器上的 OpenClaw Gateway（"龙虾"）聚合到一个浏览器面板里 —— 集中查看状态，远程发消息，实时看输出。

设计文档：[`docs/superpowers/specs/2026-05-16-clawPool-design.md`](./docs/superpowers/specs/2026-05-16-clawPool-design.md)
实现计划：[`docs/superpowers/plans/2026-05-16-clawpool-mvp.md`](./docs/superpowers/plans/2026-05-16-clawpool-mvp.md)

## MVP 已经能做的事

- **状态盘**：列出所有已注册的龙虾，显示在线 / 忙 / 闲 / 离线
- **远程发消息**：在浏览器选一只龙虾，写 prompt 发过去
- **实时看输出**：通过 Server-Sent Events 实时看 assistant 文本流、工具调用、回合结束
- **掉线兜底**：plugin 中途断开时，注入合成的 error + turn-end，UI 不会一直转圈

## v2+ 不在这一期

- 会话历史检索 / 搜索
- 中断进行中的 turn
- fan-out（同一 prompt 发给多只龙虾对比）
- 多用户 SaaS

## 快速上手

```bash
# 编译
make build

# 设定一个管理员密码
echo -n '随便挑一个密码' > admin.pass

# 设定一个共享接入 token —— 所有龙虾都用这同一个 token 连进来
echo -n '随便挑一个共享token' > clawpool.token

# 起服务
./clawpool --listen :8080 --db ./clawpool.db \
    --admin-pass-file ./admin.pass \
    --shared-token-file ./clawpool.token
```

浏览器打开 <http://localhost:8080>，用户名 `admin`，密码读 `admin.pass`。

让每一只龙虾的 `claw-pool-channel` plugin 连到 `ws://localhost:8080/ws`，token
统一填上面那串共享 token。龙虾首次握手成功后会自动落库，**不再需要**先跑
`provision`。

### 高级用法：每只龙虾独占 token

如果某只龙虾需要独立的 token（例如方便单独撤销），仍可用旧的 `provision`
子命令：

```bash
./clawpool provision --db ./clawpool.db --id macbook-le --name "我的 MacBook"
# 把打印出来的 token 贴进那只龙虾的 plugin 配置
```

被 provision 过的龙虾跟走共享 token 的龙虾可以并存；被 provision 的龙虾若
携带的 token 不对，服务端会**直接拒绝**，不允许回退到共享 token。

## 开发

```bash
make test        # 单元 + 集成
make test-e2e    # 端到端（用 fake-plugin 跑真协议栈）
make lint        # gofmt + go vet
```

## 删除龙虾

dashboard 上每只龙虾后面有"删除"按钮。点击并确认后，该龙虾会被**软删**：从
列表里消失、不能再接入，但**它名下的所有历史会话照常保留** —— 已有的
`/sessions/<id>` 链接仍可访问，`sessions` / `events` 表里的行一字不动。

如果该龙虾当时正在线，删除会立刻关闭它的 WS；之后无论它再用原来的独占
token 还是共享 token 重连，都会被服务端以 `UNAUTHORIZED` 拒绝。

UI 上没有"撤销删除"。若要恢复一只被软删的龙虾，直接改库：

```bash
sqlite3 ./clawpool.db "UPDATE lobsters SET deleted_at = NULL WHERE id = '龙虾id';"
```

## 运维注意

- **数据**：所有数据躺在一个 SQLite 文件里（默认 `./clawpool.db`）。直接 `cp` 就能备份。
- **WAL 模式**：会在主文件旁边看到 `clawpool.db-wal` 和 `clawpool.db-shm`，备份时三个文件都要带上。
- **日志**：默认写 stderr。生产环境建议重定向到文件或者交给 systemd。
- **认证强度**：MVP 是单用户设计，自带 Basic Auth 不是硬核公网认证。如果要暴露到公网，前面务必挂一层真正的反向代理（TLS + 真鉴权）。
- **共享 token 文件**：当成密钥对待 —— `chmod 600`、不要入版本控制、不要贴进日志或聊天。轮换 token 需要改文件并重启服务（所有已连接的 plugin 都要同步换新值）。

## 目录结构

```
cmd/clawpool/       服务端 + provision 子命令
cmd/fake-plugin/    e2e 测试用的协议桩
internal/bus/       进程内 pub/sub
internal/store/     SQLite 持久层
internal/proto/     WS 帧协议
internal/registry/  龙虾 WS 连接与状态机
internal/http/      路由、SSE、内嵌 HTMX 前端
e2e/                fake-plugin 驱动的端到端测试
```

## 与 OpenClaw 的关系

clawPool 通过实现一个 **OpenClaw channel plugin** 来接入每只龙虾 —— plugin 在 lobster 本机的 OpenClaw Gateway 里加载，反向 WS 连到 clawPool。从 Gateway 视角看，clawPool 就是另一个聊天频道（与 Slack / Discord / WhatsApp 同层）；从 clawPool 视角看，每一个连入的 plugin 就代表一只龙虾。

TS plugin 在独立仓库 `claw-pool-channel`（本仓库不含）。

## 协议要点

- WebSocket，每帧一个 JSON 对象，`type` 字段做判别
- 龙虾启动 → `hello{token}` → clawPool 验 token（被 provision 的走 bcrypt，其余走与共享 token 的常数时间比对） → 回 `hello-ok`
- 用户消息：`user-message{requestId, sessionId?, text}` → plugin 处理 → 回 `ack{requestId, sessionId, phase:"ingested"}`
- 流式输出：plugin 推 `turn-event` 序列（`assistant-text-delta` / `tool-event` / `turn-end` / `error`）→ clawPool 每帧落盘 + 发布 + 回 `ack{seq}`
- 失败语义：user-message 走"至多一次 + 让用户决定重试"；turn-event 走"至少一次 + DB 唯一索引去重"

详见 [设计文档 §3](./docs/superpowers/specs/2026-05-16-clawPool-design.md#3-协议plugin--clawpool-ws-帧)。