npm.io
0.27.0 • Published 3d ago

@coclaw/openclaw-coclaw

Licence
Apache-2.0
Version
0.27.0
Deps
2
Size
587 kB
Vulns
0
Weekly
0
Stars
9
SummaryDependencyVersions

@coclaw/openclaw-coclaw

CoClaw 的 OpenClaw 插件（npm: @coclaw/openclaw-coclaw，plugin id: openclaw-coclaw），运行在 OpenClaw gateway 进程中，是 CoClaw 与 OpenClaw 之间的核心连接层。

主要模块：

  • realtime bridge — CoClaw server 与 OpenClaw gateway 之间的 WebSocket 实时消息桥接，支持 RPC 转发和事件广播
  • WebRTC peer — 与 CoClaw UI 建立 WebRTC DataChannel 直连，提供 RPC 和文件传输两类通道
  • session manager — 会话列表/读取能力（nativeui.sessions.listAll / nativeui.sessions.get）
  • chat history manager — 跟踪和管理 chat reset 产生的孤儿 session（coclaw.chatHistory.list）
  • topic manager — 独立话题的创建、列表、标题生成与删除（coclaw.topics.*）
  • file manager — 工作区文件管理，支持通过 WebRTC DataChannel 流式传输和 gateway RPC 回退（coclaw.files.*）
  • auto-upgrade — 从 npm 安装的插件自动检查并升级到最新版本
  • device identity — Ed25519 密钥对管理，用于 gateway WebSocket 连接的设备认证

安装与模式切换

插件支持两种安装模式，可随时切换（脚本会自动处理卸载→重装）：

本地开发（link 模式，日常开发推荐）

pnpm run link

link 后代码更新只需 openclaw gateway restart，无需重新安装。

从 npm 安装
pnpm run install:npm
卸载
pnpm run unlink          # 卸载 link 模式
pnpm run uninstall:npm   # 卸载 npm 模式

卸载仅移除插件元数据和代码，不清理绑定信息（bindings.json 独立保留）。

预发布验证与发布

预发布验证

发布前验证 tarball 能正确安装到 OpenClaw 中：

pnpm run release:pre              # 全新安装验证（交互式，含手动功能验证）
pnpm run release:pre -- --upgrade # 升级验证（先装 npm 旧版，再用本地包覆盖）
发布到 npm
pnpm run release                 # 默认：verify → 发布 → 轮询确认
pnpm run release -- --prerelease # 含预发布验证（pack + 安装测试 + 发布，等同于先手动 release:pre 再 release）
检查发布状态
pnpm run release:check                     # 显示各 registry 最新版本
pnpm run release:check -- 0.1.7            # 对比指定版本
WAIT=1 pnpm run release:check -- 0.1.7     # 轮询直到版本生效
pnpm run release:versions                  # 显示所有已发布版本

Gateway RPC 方法

插件注册的所有 gateway method（通过 openclaw gateway call <method> 或 WebRTC DC 调用）：

方法 说明
coclaw.bind 绑定 Claw 到 CoClaw server
coclaw.unbind 解绑并停止 bridge
coclaw.enroll 生成认领码，等待用户完成绑定
coclaw.info / coclaw.info.get 获取插件版本、claw 版本、capabilities、名称、主机名
coclaw.info.patch 修改 claw 显示名称，广播 coclaw.info.updated 事件
coclaw.topics.create 创建话题
coclaw.topics.list 列出指定 agent 的话题
coclaw.topics.get 获取单个话题
coclaw.topics.getHistory 获取话题对话记录
coclaw.topics.update 更新话题标题
coclaw.topics.generateTitle 通过 agent RPC 自动生成话题标题
coclaw.topics.delete 删除话题及其 .jsonl 文件
coclaw.chatHistory.list 列出 chat 的历史（孤儿）session
coclaw.sessions.getById 按 sessionId 获取消息记录
coclaw.upgradeHealth 返回当前插件版本（升级健康检查）
coclaw.files.list 列出工作区文件（RPC 回退）
coclaw.files.delete 删除工作区文件/目录
coclaw.files.mkdir 创建工作区目录
coclaw.files.create 创建空文件
nativeui.sessions.listAll 列出所有 session（分页）
nativeui.sessions.get 获取 session 原始 JSONL 行（分页）

Gateway Services

Service ID 说明
coclaw-realtime-bridge CoClaw server WebSocket 桥接 + WebRTC peer 管理
coclaw-auto-upgrade npm 安装模式下的自动升级调度器

绑定 / 解绑

绑定码从 CoClaw Web 端生成，有效期有限。

方式一：OpenClaw CLI 子命令（推荐）
openclaw coclaw bind <binding-code> [--server <url>]
openclaw coclaw unbind [--server <url>]
openclaw coclaw enroll [--server <url>]
  • bind/unbind/enroll 均为瘦 CLI，通过 gateway RPC（coclaw.bind/coclaw.unbind/coclaw.enroll）在 gateway 内执行，由 gateway 内部管理 bridge 生命周期。若 gateway 未运行，CLI 会自动尝试重启一次再重试；若仍不可用，操作失败。
  • unbind 是强制操作：server 不可达时操作失败（不清理本地 config，避免产生孤儿 bot）。server 返回 401/404/410 视为 bot 已不存在，允许继续。
  • enroll 由 OpenClaw 侧主动发起，生成认领码和链接供用户点击完成绑定。已绑定时需先 unbind 再发起。
方式二：IM 渠道命令

在已注册 CoClaw channel 的 IM 渠道中发送：

/coclaw bind <binding-code> [--server <url>]
/coclaw unbind [--server <url>]
/coclaw enroll [--server <url>]

需要 gateway 运行中。

配置存储

绑定信息存储在 ~/.openclaw/coclaw/bindings.json（通过 resolveStateDir() + channel ID 组合路径），不存储在 openclaw.json 中。

文件结构：

{
  "default": {
    "serverUrl": "https://coclaw.net",
    "clawId": "claw-xxx",
    "token": "token-xxx",
    "boundAt": "2026-03-05T..."
  }
}

说明：

  • 这一设计是为了避免卸载插件后 channels.coclaw 节点残留导致 OpenClaw gateway schema 验证失败。
  • config.js 是读写绑定信息的唯一入口。
  • 绑定时不提交 bot name；server 通过 gateway WebSocket 获取 OpenClaw 实例名。若未设置实例名，前端回退显示 OpenClaw。

自动升级

从 npm 安装的插件（source: "npm"）会自动检查并升级。link 模式和 tarball 安装不触发自动升级。

  • 检查频率：gateway 启动后延迟 5~10 分钟首次检查，之后每 1 小时
  • 升级方式：独立 detached 进程执行，不阻塞 gateway
  • 安全机制：升级前物理备份；升级后验证 gateway + 插件状态；验证失败自动回滚
  • 状态文件：~/.openclaw/coclaw/upgrade-state.json（运行时状态）、upgrade-log.jsonl（升级历史）

可通过 gateway RPC 检查升级模块状态：

openclaw gateway call coclaw.upgradeHealth --json
# → {"version":"0.1.7"}

详见设计文档 docs/auto-upgrade.md。

WebRTC 实现

WebRTC 唯一实现为 pion——通过 @coclaw/pion-node SDK 驱动 Go 侧 pion-ipc 进程，实现完整 WebRTC 能力。pion 加载失败时不再兜底（impl=none）：所有依赖 WebRTC DataChannel 的远程功能（chat、UI RPC、文件传输）不可用；gateway 进程、本地 RPC 面与自动升级不受影响，可通过发布修复版本自动升级恢复。

加载结果通过 coclaw.env impl=... 日志上报。

历史：werift（纯 JS 兜底）与 ndc（node-datachannel）路径已于 2026-07-16 移除。werift 的 DataChannel 不触发 onbufferedamountlow 属性回调，而插件的 RPC 背压与文件下载恢复都挂在该回调上——werift 路径实为"能连上但文件/大流量必楔死"的负价值兜底。背景见 docs/webrtc-impl-strategy.md。

运行与排障日志

日志级别建议
  • 默认（生产推荐）：仅保留 info/warn，用于连接、绑定、解绑、鉴权失败等关键事件。
  • 深度排障：开启 COCLAW_WS_DEBUG=1，输出 rpc/event 透传细节。
开启 COCLAW_WS_DEBUG

临时开启（当前 shell）：

COCLAW_WS_DEBUG=1 openclaw gateway start

若通过 systemd/user service 运行 gateway，可在服务环境中追加：

Environment=COCLAW_WS_DEBUG=1

然后重启 gateway 生效。

常用排障命令
# 看 plugin 与 server 连接状态
openclaw logs --limit 300 --plain | rg -n "realtime bridge|coclaw/ws|bind success|unbind success" -i

# 看 gateway 握手/协议问题
openclaw logs --limit 300 --plain | rg -n "gateway connect failed|protocol mismatch|closed before connect|auth failed" -i

# 看 rpc/event 透传（需先开启 COCLAW_WS_DEBUG=1）
openclaw logs --limit 300 --plain | rg -n "ui->server req|bot->server res|bot->server event|gateway req" -i

设置

插件设置存储在 ~/.openclaw/coclaw/settings.json，独立于绑定信息，解绑后重新绑定不会丢失。

当前支持的设置项：

  • name — Claw 显示名称（可选，最长 63 字符），通过 coclaw.info.patch RPC 修改

settings.js 是读写设置的唯一入口。

设备身份

插件在首次运行时自动生成 Ed25519 密钥对，存储在 ~/.openclaw/coclaw/device-identity.json（mode 0o600）。deviceId 为公钥的 SHA-256 摘要，用于 gateway WebSocket 连接的设备认证（v3 auth payload）。

测试门禁

pnpm check        # lint + typecheck
pnpm test         # 测试 + 覆盖率检查

覆盖率阈值：lines/statements/functions 100%，branches ≥ 95%。未通过禁止接入 gateway。

Keywords

openclawopenclaw-plugincoclawchannelchatbotbridgewebchat