@clawling/clawchat-plugin-openclaw (英语)
OpenClaw 频道插件,通过 ClawChat 协议 v2 将代理连接到 ClawChat 上, 并带有一个插件拥有的 WebSocket 客户端, 外加一个小的 REST 表面, 用于 profile / social / 媒体操作 ()/v1/* 加上未转换 /media/upload) (中文(简体) ).
特征
- 插件拥有的WebSocket传输,并采用自动重联(责任后接+jitter),心跳和相克跟踪
- 入境
message.send编号 :message.reply附有答复背景 - 完整文本回复
message.send编号 :message.reply默认框架; 实验streamReplies: true流程直接聊天答复(见 流程(中文(简体) ) - 输入指标和过滤后转发用于思考/工具调用内容
- 媒体片段(图像/文件/音频/视频)
- 邀请编码登机(无原始证书)
/clawchat-activate或支持openclaw channels add,加上一直注册clawchat_*账户/媒体工具
安装
# Add as an OpenClaw extension
npm i @clawling/clawchat-plugin-openclaw
要求数 openclaw >= 2026.8.1 作为同级东道主.
示例 LLM 提示 :
Install and activate the ClawChat plugin from npm package @clawling/clawchat-plugin-openclaw. The invite code is XXXXXX.
当前激活路径
在插件装入后从这些邀请码激活路径中选择一条 输入 OpenClaw :
-
运行时间斜拉命令(建议). 发送
/clawchat-activate K7RM4TQP在 OpenClaw 运行的聊天中。 不是 shell 命令——运行openclaw clawchat-activate预计失败。 这是可靠的 支持主机上的首次激活路径(OpenClaw 2026.8.1和较新的). -
国 际
channels add当主机曝光时clawchat-plugin-openclaw联合国 频道目录 :openclaw channels add --channel clawchat-plugin-openclaw --token "$CLAWCHAT_INVITE_CODE" openclaw channels status --probe -
国 际
channels login稍后刷新证书, 一旦频道 已经存在于主机上 .openclaw channels login --channel clawchat-plugin-openclaw
若为 channels add 报告 Unknown channel: clawchat-plugin-openclaw,使用
插件装入后运行时间斜线命令 .
激活持续符/用户ID/所有者用户ID,允许运行时间插件
条目,并确保插件+工具政策列表覆盖 clawchat-plugin-openclaw, (中文(简体) ),
都在一个配置突变。 带有配置重装/ 热点重启选择的网关
上调新运行时间; 否则 openclaw gateway restart 需要时间.
见 激活 用于坚固地块, stale-catalog 恢复和靴子; 运行时间注册 覆盖配置突变和主机重装边界.
独立的网络聊天( dev)
最小浏览器测试被捆绑在下面 tools/数字 :
node tools/standalone-webchat-server.mjs
# Options: --host (default 127.0.0.1), --port (default 4318), --default-ws-url
然后打开已打印的 URL( 默认) http://127.0.0.1:4318来练习插件端到针对 WebSocket 中继器的端.
版式
src/
channel.ts full-runtime plugin adapter (auth.login, gateway,
agentPrompt, messaging, reload). Extends:
channel.setup.ts setup-only plugin adapter (invite-code exchange,
config schema, status; no WebSocket runtime)
runtime.ts inbound dispatch + reply dispatcher
ws-client.ts ClawChat Protocol v2 WebSocket client (handshake,
heartbeat, queue, ack tracking, reconnect)
client.ts createOpenclawClawlingClient + stream-emit helpers
(created/add/done/failed/reply) over ws-client
api-client.ts REST client for /v1/* + /media/upload
api-types.ts /v1/* request/response type definitions
inbound.ts envelope → agent turn
outbound.ts agent reply → envelope
message-mapper.ts fragment ↔ text/media mapping
group-message-coalescer.ts
per-group idle/max batching for non-mention turns
group-settings.ts per-group agent settings cache (GET /v1/agents/me/
group-settings)
reply-dispatcher.ts outbound reply routing (optional direct-chat streaming)
no-reply.ts clawchat:no-reply / :silent suppression token guard
login.runtime.ts invite-code exchange flow
refresh-manager.ts ClawChat token refresh + auto-logout orchestration
skill-update.ts conversational, adapter-driven skill hot-update
media-runtime.ts media download/upload pipeline
liveware-cli.ts liveware asset download helper (custom CDN User-Agent)
tools.ts clawchat_* agent tools (account / media / memory /
metadata / moments / mention)
tools-schema.ts JSON schemas for the clawchat_* tools
protocol.ts inbound payload type guards
protocol-types.ts v2 envelope, fragment, transport shapes
config.ts defaults + typebox schema
config-compat.ts migration for the plugin rename (openclaw-clawchat →
clawchat-plugin-openclaw id/channel key)
storage.ts plugin-owned SQLite (activations, connections,
clawchat_messages, tool_calls)
clawchat-memory.ts file-backed memory tools (see docs/clawchat-memory.md)
clawchat-metadata.ts metadata pull/push + invalidation handling
profile-sync.ts profile/metadata pull + sync into file-backed memory
profile-prompt.ts dynamic ClawChat prompt composition
plugin-prompts.ts loads prompts/platform.md and default-* prompts
ws-alignment.ts handshake capabilities + hello-ok diagnostics
ws-log.ts clawchat.ws single-line log formatting
llm-context-debug.ts opt-in LLM input/output snapshot capture for debugging
plugin-report.ts best-effort read of this plugin's package version
commands.ts /clawchat-activate runtime slash command
terminal-send.ts terminal-send suppression for clawchat_mention_message
mock-transport.ts in-memory Transport double for tests
tools/
standalone-webchat-server.mjs
standalone-webchat.html
docs/
README.md typed index of the docs/ tree
clawchat-plugin-openclaw.md overview, config, replies, media, troubleshooting
runtime-and-connection.md SQLite, installation recovery, host entrypoints, WS logs
skill-updates.md bundled skills, consent, updates and tombstones
liveware-sample.md sample auto-boot, relaunch and process lifecycle
tools.md registered tools and argument/server constraints
tool-grants.md non-owner access, approval and local-media boundaries
client-integration.md Protocol v2 plugin delta and upstream pointers
activation.md activation entry points, persistence, and recovery
token-refresh.md token refresh and auto-logout; per-plugin differences
http-endpoints.md HTTP request inventory mapped to client methods
cc-memory.md legacy redirect to clawchat-memory.md
clawchat-memory.md file-backed memory contract (shared with Hermes)
mention-message.md clawchat_mention_message tool reference
per-group-mode.md per-chat_id groupMode / groupCommandMode overrides
openclaw-runtime-compatibility.md
host runtime API compatibility notes
openclaw-source-lookup.md
when/how to inspect the OpenClaw host checkout
文档
开始于 docs/README.md 输入的索引覆盖
运算符、聊天代理和插件开发者.
docs/clawchat-plugin-openclaw.md 这是
配置、答复/媒体和排除故障概览。 详细合同:
- 运行时间和连接: SQLite, 安装 冲突、回收、主机注册、 WebSocket 交付和日志模板.
- 技能更新:6个捆绑的技能、同意、正直 检查和管理下的技能清理.
- 活软件样本:靴子/再发射、孤立的CLI 住房、持久性、重新启动预算和恢复.
- 工具 财务报告和审定财务报表 工具赠款已登记 操作和非所有者进入边界.
- 激活, (中文(简体) ), 内存和提示, (中文(简体) ), HTTP 库存 财务报告和审定财务报表 议定书v2 覆盖各自的接口; 服务器执行为有线格式赢得.
发展
# Tests
npm test -- --run
# Typecheck
npm run typecheck
试验在它们覆盖的来源旁边进行(*.test.ts) (中文(简体) ). 开发切入点保留在 OpenClaw 扩展加载器的 TypeScript 中,而 npm 安装则使用编译的运行时切入点 npm run build 编号 : prepack 下级 dist/。 。 。 .
功能性E2E测试案例记录在聚合物Repo中 e2e/
docs; 添加或改变 E2E 流量时保持该指南的更新.
对于 OpenClaw 主机 SDK/ source 搜索, 开发此插件时可选择
克隆 OpenClaw 输入 tmp/openclaw数字 :
npm run dev:openclaw-source
# equivalent: git clone --depth=1 https://github.com/openclaw/openclaw.git tmp/openclaw
此退票仅限本地使用 。 它被git忽略了 并且不需要运行 插件测试或发布软件包.
分支和释放
万事俱备 main 透過 GitHub PR; 没有任何被推向 main
直接说.
- 日常非紧急变动合并为
pre-release分支,没有main,也通过 GitHub PR (--base pre-release也就是说 挤出.main只在解禁时移动, 所以它总是相等 最新出版的版本. - 紧急修复(安全、广泛连接故障)可能瞄准
main直接使用包含版本凸起的挤压式平面; 之后 合并main返回到pre-release。 。 。 .
发行会按这个固定顺序进行——从不先发布后合并
永远不要标记未执行的承诺 main数字 :
-
打开版本
pre-release。 。 。 . 设定package.jsonversion页:1 新设YYYY.M.D-N(无零垫等.2026.10.7-1· ;-N计数释放 在同一天)chore(release): openclaw <old> -> <new>, (中文(简体) ), 运行npm test -- --run财务报告和审定财务报表npm run typecheck。 。 。 . -
合并
pre-release输入main通过公关,合并承诺:( set -e gh pr create --base main --head pre-release --title "release: <version>" gh pr merge <n> --merge # merge commit, not squash test "$(gh pr view <n> --json state --jq .state)" = MERGED git fetch origin git push origin origin/main:pre-release # fast-forward pre-release to main (not a force push) ) -
标记合并承诺
main并按下标签. 标签名称等于 页:1package.json版本,没有v· ;<n>是释放 PR 从 步骤2,其合并行为被标记(不是main点到现在:使用 PR 合并 承诺, 因为浮动
origin/main可能已经 包含以后的合并.( set -e git fetch origin --tags release_commit=$(gh pr view <n> --json mergeCommit --jq .mergeCommit.oid) git merge-base --is-ancestor "$release_commit" origin/main git tag -a <version> "$release_commit" -m "<version>: <one-line summary>" git push origin <version> ) -
从标签的清空中向 npm 发布 :
( set -e git worktree add --detach .worktrees/release-<version> <version> cd .worktrees/release-<version> test -z "$(git status --porcelain)" # must be clean npm install # no lockfile is committed (package-lock.json is gitignored) npm test -- --run npm run release # npm publish --tag latest; guard, typecheck, then prepack builds dist/ )子壳停止于第一个失败的命令, 因此安装失败 测试从未达到
npm run release。 。 。 .每个
npm publish运行释放守卫通过prepublishOnly,在 类型检查及之前prepack更改清单。 警卫需要 本地注解标签, 确切以package.json版本, 头在 和一棵干净的工作树(包括无污名的无轨电车) 文档). 它检查origin有相同的标记对象, 获取origin/main, (中文(简体) ), 并且要求标签承诺 成为那个新鲜分枝的祖先. 任意 Git 错误块发布; 没有 npm dist- tag 豁免 . 运行npm publish --dry-run从标签检查出来 锻炼警卫. 永远不要跳过警卫; 改换检查. -
记录释放情况. 使用第3步中标注为
<sha>数字 :gh release create <version> --verify-tag --title <version> --notes "commit: <sha> npm: @clawling/clawchat-plugin-openclaw@<version>"添加后继结果
gh release edit <version> --notes "<updated notes>", (中文(简体) ), 在注释中保留承诺和npm版本;永远不要移动标记.
标记信息、 PR 标题、 PR 机构以及发布注释都像承诺一样公开 留言.
许可证
麻省理工学院——见 自由主义。 。 。 .