# OpenClaw 集成方案设计

> 状态: 讨论中，尚未开始实现
> 日期: 2026-03-07

---

## 一、OpenClaw 是什么

- **GitHub**: https://github.com/openclaw/openclaw
- **定性**: 开源自主 AI Agent，2026年初爆火，前身为 Clawdbot/Moltbot
- **完全开源**: 有完整源码 + Dockerfile，可以 fork 定制
- **核心架构**:

```
Gateway 进程 (ws://127.0.0.1:18789)
  ├── CLI 客户端          ← WebSocket RPC
  ├── Web UI             ← WebSocket RPC
  ├── channel 插件        ← WebSocket RPC (WhatsApp/Telegram/Slack/Discord 等)
  ├── native 节点         ← WebSocket RPC (macOS/iOS/Android)
  └── HTTP POST /tools/invoke  ← 直接调用工具
```

Gateway 是唯一的控制平面，所有子系统通过它通信，没有子系统直接互相通信。

- **卷挂载**:
  - `~/.openclaw` → `/home/node/.openclaw` (配置目录)
  - `~/openclaw/workspace` → `/home/node/.openclaw/workspace` (工作区/用户数据)
- **关键环境变量**:
  - `OPENCLAW_GATEWAY_TOKEN` — 内部 API 认证 token
  - `CLAUDE_AI_SESSION_KEY` / Anthropic API Key

---

## 二、集成目标

用户在 IT0 App 里对话，iAgent 帮用户：
1. 在指定服务器上部署一个属于用户自己的真实 OpenClaw 实例
2. iAgent 可以管理（启动/停止/监控）用户的 OpenClaw 实例
3. 用户可以通过 IT0 App 直接向自己的 OpenClaw 下发任务，看到结果
4. 计费、用量、状态监控全部打通到 IT0 平台

---

## 三、技术方案

### 3.1 自定义 Docker 镜像 (openclaw-bridge)

基于 OpenClaw 官方源码 (`openclaw/openclaw`) 构建我们自己的镜像，**单容器，两进程共存**（不用 sidecar，便于多租户在同一物理服务器上并发部署）：

```
容器内进程：
  ├── openclaw gateway (原生，端口 18789 内部，不对外暴露)
  └── it0-bridge (新增 Node/NestJS 服务，端口 3000 对外)
        ├── 连接 OpenClaw Gateway WebSocket RPC (ws://127.0.0.1:18789)
        ├── 对外暴露 IT0 标准 REST API
        ├── 接收 iAgent 下发的任务 → 转发给 OpenClaw
        ├── 订阅 OpenClaw 输出 → 回传给 IT0 agent-service
        └── 上报健康状态 / 用量统计
```

镜像名: `it0hub/openclaw-bridge:latest`

多租户并发部署示例（同一台物理服务器）：
```bash
docker run -d --name openclaw-{userId1} -p 3101:3000 -v /data/openclaw/{userId1}:/home/node/.openclaw ...
docker run -d --name openclaw-{userId2} -p 3102:3000 -v /data/openclaw/{userId2}:/home/node/.openclaw ...
```
每个实例端口独立、数据目录隔离，iAgent 通过容器名管理生命周期。

### 3.2 部署流程

iAgent（我们的 Claude Code 智能体）通过已有的 SSH 工具执行：

```bash
docker run -d \
  --name openclaw-{userId} \
  -p {port}:3000 \
  -v /data/openclaw/{userId}:/home/node/.openclaw \
  -e OPENCLAW_GATEWAY_TOKEN={token} \
  -e IT0_AGENT_SERVICE_URL=https://it0api.szaiai.com \
  -e IT0_TENANT_ID={tenantId} \
  -e IT0_INSTANCE_ID={instanceId} \
  -e IT0_AUTH_TOKEN={authToken} \
  -e CLAUDE_API_KEY={claudeKey} \
  it0/openclaw-bridge:latest
```

### 3.3 IT0 后台记录 (agent_instances 表)

```sql
-- 记录每个用户的 OpenClaw 实例
agent_instances (
  id, tenant_id, user_id,
  server_host,       -- 部署在哪台服务器
  container_name,    -- docker 容器名
  port,              -- 对外暴露端口
  status,            -- running/stopped/error
  gateway_token,     -- OpenClaw gateway token (加密存储)
  claude_api_key,    -- 用户的 Anthropic key (加密存储)
  config,            -- JSONB，OpenClaw 配置
  created_at, updated_at
)
```

### 3.4 iAgent 可执行的管理操作

通过 SSH 工具调用：
- `docker start/stop/restart openclaw-{userId}`
- `docker logs openclaw-{userId}`
- `docker stats openclaw-{userId}`

通过 IT0 Bridge REST API 调用：
- `POST /task` — 向 OpenClaw 提交任务
- `GET /status` — 查询实例运行状态
- `GET /sessions` — 查询对话历史
- `GET /metrics` — 获取用量数据

---

## 四、已确认决策

1. **目标服务器来源** ✅
   - 两种都支持：
     - IT0 公司提供统一服务器池（用户购买套餐，自动分配实例）
     - 用户自带服务器（用户在 IT0 中录入 SSH 凭证，iAgent 登录部署）

2. **用户访问 OpenClaw 的方式** ✅
   - OpenClaw 自身支持多 channel（Telegram、WhatsApp、Line 等），用户直接用这些 channel 与自己的 OpenClaw 实例交互
   - IT0 的职责是**管理层**：部署、启停、监控、保障稳定运行，而不是成为主要对话入口
   - IT0 App 展示实例状态、日志、用量，并提供各 channel 的接入配置引导

3. **Claude API Key 归属** ✅
   - 用户购买 IT0 套餐，IT0 统一承担 Anthropic API 费用
   - IT0 的 `CLAUDE_API_KEY` 注入到每个 OpenClaw 容器，用量计入对应 tenant 的配额

4. **openclaw-bridge 镜像托管** ✅
   - 同时支持两种：
     - Docker Hub 公开仓库（`it0hub/openclaw-bridge:latest`）——方便外部服务器拉取
     - 我们自己的私有 Registry——内网/自有服务器池使用
   - 镜像本身不含任何密钥，所有凭证通过环境变量运行时注入

5. **OpenClaw 版本更新策略** ✅
   - 不存在复杂的版本跟踪问题：OpenClaw 发布新版时，我们拉取最新源码重新 build 一个包含 IT0 Bridge 的新镜像即可
   - CI/CD: 监听 openclaw/openclaw 上游 release → 自动触发我们的镜像 build → 推送到 Docker Hub + 私有 Registry

---

## 五、架构补充：服务器池

### 5.1 归属
- **inventory-service** 新增 `PoolServer` 实体（平台级，public schema，仅 platform_admin 可管理）

### 5.2 数据结构
```sql
-- public schema（非租户隔离）
CREATE TABLE pool_servers (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name        VARCHAR(100) NOT NULL,          -- 别名，如"训练服务器"
  host        VARCHAR(255) NOT NULL,          -- IP 或域名
  ssh_port    INT NOT NULL DEFAULT 22,
  ssh_user    VARCHAR(100) NOT NULL,
  ssh_key     TEXT NOT NULL,                  -- 加密存储的私钥内容
  max_instances INT NOT NULL DEFAULT 10,      -- 管理员手动设置上限
  status      VARCHAR(20) DEFAULT 'active',   -- active / maintenance / offline
  region      VARCHAR(100),                   -- 可选，地区标注
  notes       TEXT,
  created_at  TIMESTAMPTZ DEFAULT NOW(),
  updated_at  TIMESTAMPTZ DEFAULT NOW()
);
```

### 5.3 SSH 凭证存储
- SSH 私钥加密后存入 `pool_servers.ssh_key`（AES-256，密钥来自 agent-service 环境变量）
- agent-service 在部署时解密私钥，写入临时文件，SSH 连接后立即删除临时文件

### 5.4 容量分配逻辑
```
iAgent 部署新实例时：
  1. 查询 inventory-service: GET /api/v1/inventory/pool-servers?available=true
  2. 返回 current_instances < max_instances 的服务器列表
  3. 选用量最少的那台（最优分布）
  4. SSH 连接 → docker run → 成功后 current_instances + 1
```

---

## 六、实现阶段规划（已确认）

### Phase 1: 服务器池 + 基础部署能力

**inventory-service**
- [ ] DB 迁移: `pool_servers` 表（public schema）
- [ ] PoolServer 实体 + Repository + CRUD REST 接口
- [ ] Kong 路由: `/api/v1/inventory/pool-servers`（platform_admin only）

**agent-service**
- [ ] DB 迁移: `agent_instances` 表（tenant schema）
- [ ] AgentInstance 实体 + Repository + CRUD REST 接口
- [ ] SSH 私钥加解密工具（AES-256）
- [ ] 部署工具: 查询服务器池 → SSH → docker run → 记录实例

**openclaw-bridge 镜像**
- [ ] 基于 openclaw/openclaw 源码，新建 `packages/openclaw-bridge/` 目录
- [ ] 编写 it0-bridge 进程（Node.js，连接 OpenClaw Gateway WS 18789，对外 REST 3000）
- [ ] 编写 Dockerfile（两进程，supervisord 管理）
- [ ] 推送到 Docker Hub: `it0hub/openclaw-bridge:latest`

**Web Admin**
- [ ] 服务器池管理页面 `/server-pool`（列表 + 添加 + 删除 + 容量编辑）
- [ ] OpenClaw 实例列表页 `/openclaw-instances`（跨租户，platform_admin 视角）

### Phase 2: App 集成
- [ ] my_agents_page 展示真实实例列表 + 状态
- [ ] 实例详情页: 状态 / 日志 / channel 配置引导（Telegram/WhatsApp/Line 接入）
- [ ] iAgent 对话支持部署指令识别（"帮我创建一个 OpenClaw"）

### Phase 3: 计费与监控
- [ ] 用量上报到 billing-service（每个实例的 token 用量）
- [ ] 套餐限制（免费版: 0个实例，Pro: 1个，Enterprise: N个）
- [ ] 实例健康监控 + 自动重启（心跳检测）