ChatClaw

ChatClaw 是一个持久运行的后台桥接组件，用于将本地 OpenClaw 代理连接至 ChatClaw 云控制台。安装并启用后，它会随 OpenClaw 自动启动，使您能够通过任意浏览器或移动设备与代理进行对话、监控 token 使用量以及管理任务——无需暴露任何端口，也无需配置防火墙。

功能说明

透明度说明：云中继端点（api.sumeralabs.com）由 ChatClaw 背后的公司 SumeraLabs 运营。chatclaw.sumeralabs.com 是产品域名；sumeralabs.com 是基础设施域名。二者均由同一团队拥有并运营。

启用 ChatClaw 后，将建立两条连接：

1. 云中继（Cloud relay） —— 一条出站 WebSocket 连接，目标为 wss://api.sumeralabs.com/ws/agent/{api_key}。这是控制台与技能通信的通道，为纯出站连接，无需配置入站端口转发。
2. 本地网关（Local gateway） —— 一条仅用于 Ed25519 认证的 WebSocket 连接（ws://localhost:18789），以及所有聊天流量所用的 HTTP SSE 请求（http://localhost:18789/v1/chat/completions）。该 HTTP 端点在首次启动时会自动在 openclaw.json 中启用。

消息双向实时流动：控制台发送的用户消息通过 HTTP SSE 流式传输至 OpenClaw 代理；代理响应的每个 token 在生成后即刻回传至控制台，实现类似打字机效果的实时流式输出。

权限与能力

本节完整披露该技能在收到云中继消息后可执行的所有操作。所有操作均需有效的 ChatClaw API 密钥；未通过身份验证的连接会在消息抵达技能前即被中继服务拒绝。

为何需要 operator 级别凭据：
网关使用带 operator 权限范围（operator.admin、operator.approvals、operator.pairing）的 Ed25519 设备认证。这是 OpenClaw 网关握手协议所要求的，用于建立已认证连接——技能桥接器不存在更低权限的连接模式。operator token 从 device-auth.json 中读取，仅用于初始 WebSocket 握手，绝不会传输至云中继服务。

安全缓解措施：

• 所有能力均需在云中继层通过有效 API 密钥认证后，消息才可抵达技能
• 文件访问为只读，且通过网关 RPC（agentId: "main"）严格限定于代理工作区
• 技能启用/禁用与重新安装操作在每次调用时均被本地记录
• 不执行含用户可控参数的 shell 命令——技能名称与文件名作为位置参数传递给受控子进程调用，而非拼接进 shell 字符串
• 禁用该技能将自动还原其对 openclaw.json 所做的全部修改

架构图

ChatClaw 控制台（浏览器 / 移动端）
        ↕  wss://api.sumeralabs.com
  ChatClaw 云中继（FastAPI）
        ↕  wss://api.sumeralabs.com/ws/agent/{api_key}
  ChatClaw 技能  ←── 本包
        ↕  ws://localhost:18789（认证握手，Ed25519）
        ↕  http://localhost:18789/v1/chat/completions（SSE 流式聊天）
  OpenClaw 网关
        ↕
  OpenClaw 代理（LLM）

系统要求

• OpenClaw：v2026.3.28 或更高版本
• Python：3.8+
• 依赖项：websockets、cryptography、aiohttp

重要提示：ChatClaw v0.3.0+ 因认证机制变更，要求 OpenClaw v2026.3.28 或更高版本。若您使用旧版 OpenClaw，请升级 OpenClaw，或改用 ChatClaw v0.2.9（旧版）。

安装方式

通过 OpenClaw 控制 UI 安装（推荐）

1. 在 http://localhost:18789 打开控制 UI
2. 进入 Skills → Marketplace
3. 搜索 ChatClaw
4. 点击 Install，输入您的 API 密钥，再点击 Enable

注意：首次启用时，该技能会自动在您的 openclaw.json 中设置 gateway.http.endpoints.chatCompletions.enabled = true。若技能执行了该修改，禁用时将自动还原。若 chatCompletions 在安装前已启用，则禁用时不会改动您的配置。

技能立即启动，并在后续每次 OpenClaw 启动时自动加载。

通过 OpenClaw CLI 安装

npx clawhub install chatclaw
openclaw skills enable chatclaw
openclaw skills logs chatclaw

启用前，请先将您的 API 密钥添加至 openclaw.json 的 skills.entries.chatclaw.config 下：

"skills": {
  "entries": {
    "chatclaw": {
      "enabled": true,
      "config": {
        "apiKey": "ck_your_key_here",
        "cloud_url": "wss://api.sumeralabs.com"
      }
    }
  }
}

代理辅助安装

您的 OpenClaw 代理可为您全自动完成 ChatClaw 的安装与配置，无需任何手动操作。

请访问 app.chatclaw.sumeralabs.com/setup 获取一键安装提示——其中已预填您的 API 密钥，并附有完整说明，可直接复制粘贴至聊天窗口。

配置项

环境变量

生命周期钩子

重连行为

云中继与本地网关均支持自动重连，采用指数退避策略（5 秒 → 10 秒 → 20 秒 … 最高至 60 秒）。连接中断时，技能进程永不退出。

验证是否正常运行

openclaw skills logs chatclaw

预期输出：

Connected to cloud relay ✓
Gateway authenticated ✓
Both connections established — relaying messages ✓

故障排查

文件访问

本技能读写以下本地文件：

$OPENCLAW_DATA_DIR 在 Docker/VPS 安装中默认为 /data/.openclaw，在标准安装中默认为 ~/.openclaw。可通过 OPENCLAW_DATA_DIR 环境变量覆盖。本技能不访问该目录以外的任何文件。

外部网络连接

本技能发起以下出站网络连接：

• wss://api.sumeralabs.com —— ChatClaw 云中继（用于身份验证与消息中继）
• ws://localhost:18789 —— OpenClaw 网关 WebSocket（仅用于 Ed25519 认证握手）
• http://localhost:18789/v1/chat/completions —— OpenClaw 网关 HTTP（SSE 流式聊天）

不开启任何入站端口。本技能自身不存储用户数据——消息由 ChatClaw 后端（Supabase）持久化保存，用于维护聊天历史。

更新日志

v0.3.0（2026-03-30）

• 破坏性变更：现要求 OpenClaw v2026.3.28+ 版本
• 修复 OpenClaw v2026.3.28 的认证逻辑（补充必需的作用域请求头）
• 修复模型字段校验（由 "auto" 改为 "openclaw"）
• 新增跨平台路径解析支持（Docker/VPS/macOS）
• 增强错误信息，提升问题定位效率
• 新增审批工作流支持（operator.approvals 作用域）

v0.2.9（2026-03-12）

• 首次发布至 ClawHub

许可证

MIT-0（无需署名）