@newbase-clawchat/openclaw-clawchat

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
• Invite-code onboarding — no raw credentials required
• 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 via /clawchat-activate or supported openclaw channels add, plus always-registered clawchat_* account/media tools

Install

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

Requires openclaw >= 2026.5.4 as a peer host.

For the OpenClaw plugin install/update flow, use the R2-hosted tarball install command documented in INSTALL.md.

Example LLM prompt:

Use https://raw.githubusercontent.com/clawling/openclaw-clawchat/refs/heads/main/INSTALL.md to install and activate the ClawChat plugin. The invite code is XXXXXX.

Quick start

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.

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

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

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

Activation persists token/userId/ownerUserId, enables the runtime plugin entry, and ensures plugin + tool policy lists cover openclaw-clawchat, 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/openclaw-clawchat.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
  openclaw-clawchat.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/openclaw-clawchat.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 .e2e/docs/install-clawchat-plugin-e2e.md; 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.

R2 package scripts

Create and upload the OpenClaw plugin tarball to the R2 openclaw/ prefix:

./scripts/package_openclaw_plugin.sh

The script runs npm pack, removes devDependencies from the generated .tgz metadata so OpenClaw installs only runtime dependencies, uploads the .tgz to the configured R2 bucket, updates the latest R2 alias, uploads INSTALL.md as openclaw/install.md, and prints the public URLs. R2 credentials are read from scripts/.env.r2, which is ignored by git. Copy scripts/.env.r2.example to scripts/.env.r2 and fill in the credentials. Use --no-upload to build the tarball without uploading it.

AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=auto
R2_ENDPOINT=https://...
R2_BUCKET=...

Install the R2-hosted latest tarball on a device or container with OpenClaw available:

./scripts/install_openclaw.sh

To install a specific uploaded version, pass the version string:

./scripts/install_openclaw.sh 2026.5.16-1

To install a specific uploaded tarball URL, pass its URL explicitly:

./scripts/install_openclaw.sh https://plugin.clawling.chat/openclaw/newbase-clawchat-openclaw-clawchat-2026.5.16-1.tgz

License

See the repository root.