8.5 KiB

Raw Blame History

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 帮用户：

在指定服务器上部署一个属于用户自己的真实 OpenClaw 实例
iAgent 可以管理（启动/停止/监控）用户的 OpenClaw 实例
用户可以通过 IT0 App 直接向自己的 OpenClaw 下发任务，看到结果
计费、用量、状态监控全部打通到 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

多租户并发部署示例（同一台物理服务器）：

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 工具执行：

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 表)

-- 记录每个用户的 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 — 获取用量数据

四、已确认决策

目标服务器来源 ✅
- 两种都支持：
  - IT0 公司提供统一服务器池（用户购买套餐，自动分配实例）
  - 用户自带服务器（用户在 IT0 中录入 SSH 凭证，iAgent 登录部署）
用户访问 OpenClaw 的方式 ✅
- OpenClaw 自身支持多 channel（Telegram、WhatsApp、Line 等），用户直接用这些 channel 与自己的 OpenClaw 实例交互
- IT0 的职责是管理层：部署、启停、监控、保障稳定运行，而不是成为主要对话入口
- IT0 App 展示实例状态、日志、用量，并提供各 channel 的接入配置引导
Claude API Key 归属 ✅
- 用户购买 IT0 套餐，IT0 统一承担 Anthropic API 费用
- IT0 的 CLAUDE_API_KEY 注入到每个 OpenClaw 容器，用量计入对应 tenant 的配额
openclaw-bridge 镜像托管 ✅
- 同时支持两种：
  - Docker Hub 公开仓库（it0hub/openclaw-bridge:latest）——方便外部服务器拉取
  - 我们自己的私有 Registry——内网/自有服务器池使用
- 镜像本身不含任何密钥，所有凭证通过环境变量运行时注入
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 数据结构

-- 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个）
实例健康监控 + 自动重启（心跳检测）

8.5 KiB Raw Blame History Unescape Escape