@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 实现：

1. pion（主力）— 通过 @coclaw/pion-node SDK 驱动 Go 侧 pion-ipc 进程，实现完整 WebRTC 能力。
2. werift（回退）— 纯 JavaScript 实现，作为 pion 加载失败时的兜底。

选择结果通过 bridge.started / coclaw.env impl=... 日志上报。

ndc-preloader.js（node-datachannel 路径）的代码仍保留但已摘除 node-datachannel 依赖和 vendor 预编译包（2026-04-19）——运行时必然走 fallback 到 werift，待 pion 在全部线上平台稳定观察期结束后与 werift 一并移除。

运行与排障日志

日志级别建议

• 默认（生产推荐）：仅保留 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。