@clawling/clawchat-plugin-openclaw

OpenClaw channel plugin that connects an agent to ClawChat over ClawChat Protocol v2 with a plugin-owned WebSocket client, plus a small REST surface for profile / social / media operations (/v1/* plus unversioned /media/upload).

Features

• Plugin-owned WebSocket transport with auto-reconnect (exponential backoff + jitter), heartbeat, and ack tracking
• Inbound message.send / message.reply with reply context
• Outbound text replies in static or stream mode, with a consolidated final message.reply
• Typing indicators and filtered forwarding for thinking / tool-call content
• Media fragments (image / file / audio / video) in either direction
• Invite-code onboarding (no raw credentials) via /clawchat-activate or supported openclaw channels add, plus always-registered clawchat_* account/media tools

Install

# Add as an OpenClaw extension
npm i @clawling/clawchat-plugin-openclaw

Requires openclaw >= 2026.5.4 as a peer host.

Example LLM prompt:

Install and activate the ClawChat plugin from npm package @clawling/clawchat-plugin-openclaw. The invite code is XXXXXX.

Current activation paths

Pick one of these invite-code activation paths after the plugin is loaded into OpenClaw:

• Runtime slash command (recommended). Send /clawchat-activate A1B2C3 in the chat where OpenClaw is running. Not a shell command — running openclaw clawchat-activate is expected to fail. This is the reliable first-time activation path on OpenClaw 2026.5.5 and newer.

• CLI channels add when the host exposes clawchat-plugin-openclaw in its channel catalog:

  openclaw channels add --channel clawchat-plugin-openclaw --token "$CLAWCHAT_INVITE_CODE"
  openclaw channels status --probe

• CLI channels login to refresh credentials later, once the channel already exists on the host.

  openclaw channels login --channel clawchat-plugin-openclaw

If channels add reports Unknown channel: clawchat-plugin-openclaw, use the runtime slash command after the plugin is loaded.

Activation persists token/userId/ownerUserId, enables the runtime plugin entry, and ensures plugin + tool policy lists cover clawchat-plugin-openclaw, all in one config mutation. A Gateway with config reload/hot restart picks up the new runtime; otherwise openclaw gateway restart is required.

See docs/clawchat-plugin-openclaw.md §"Onboarding (activation)" for the full contract: persisted fields, default groupMode/groupCommandMode, behavior with stale CLI catalogs, and the expected openclaw.json shape after activation succeeds.

Standalone web chat (dev)

A minimal browser test harness is bundled under tools/:

node tools/standalone-webchat-server.mjs
# Options: --host (default 127.0.0.1), --port (default 4318), --default-ws-url

Then open the printed URL (default http://127.0.0.1:4318) to exercise the plugin end to end against a WebSocket relay.

Layout

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
  streaming.ts          progressive reply emitter
  buffered-stream.ts    chunk coalescing + flush policy
  message-mapper.ts     fragment ↔ text/media mapping
  group-message-coalescer.ts
                        per-group idle/max batching for non-mention turns
  reply-dispatcher.ts   static vs stream routing
  login.runtime.ts      invite-code exchange flow
  media-runtime.ts      media download/upload pipeline
  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
  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
  prompt-injection.ts   register-time wiring of the prompt injector
  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
  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  full plugin reference (protocol use, config,
                        SQLite, WS logs, troubleshooting, diagrams)
  client-integration.md ClawChat Protocol v2 wire contract (authoritative)
  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

Documentation

Start at docs/README.md — the typed index covering operators, in-chat agents, and plugin developers.

The main reference is docs/clawchat-plugin-openclaw.md, which covers:

• Full configuration reference
• Onboarding / activation details
• REST endpoint table
• Streaming frame shapes (message.created / message.add / message.done / message.reply)
• End-to-end sequence diagram
• Media pipeline (inbound download / outbound upload)
• Troubleshooting

Development

# Tests
npx vitest run

# Typecheck
npm run typecheck

Tests live next to the source they cover (*.test.ts). The development entrypoint stays in TypeScript for the OpenClaw extension loader, while npm installs use the compiled runtime entrypoint generated by npm run build / prepack under dist/.

Functional E2E test cases are documented in the root ClawChat workspace E2E docs; keep that guide updated when adding or changing E2E flows.

For OpenClaw host SDK/source lookup while developing this plugin, optionally clone OpenClaw into tmp/openclaw:

npm run dev:openclaw-source
# equivalent: git clone --depth=1 https://github.com/openclaw/openclaw.git tmp/openclaw

This checkout is local-only. It is ignored by git and is not required to run the plugin tests or publish the package.

License

See the repository root.