@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-login 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

Current activation paths

Use one of these invite-code activation paths:

• Runtime slash command (recommended): send this in the chat where OpenClaw is running:

/clawchat-login A1B2C3

The slash command is provided by the loaded plugin and persists credentials. It is not a shell command, so openclaw clawchat-login is expected to fail.

• CLI channel add: on OpenClaw hosts where the CLI channel catalog includes openclaw-clawchat, terminal activation can also use:

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

• CLI channel login: use this only to refresh credentials later, after the channel already exists and the host recognizes openclaw-clawchat:

openclaw channels login --channel openclaw-clawchat

OpenClaw 2026.5.5 can load an npm-installed third-party channel while still omitting it from the channels add CLI catalog. If channels add fails with Unknown channel: openclaw-clawchat, use /clawchat-login A1B2C3 after a real Gateway restart.

After a successful activation on a running Gateway with config reload, OpenClaw should load the full runtime plugin and start the channel automatically. If the Gateway only has the setup-only entry loaded, the credential write forces a Gateway reload/restart instead of a setup-only channel hot restart; after the full runtime is attached, later channel config changes can hot reload the channel. Restart the Gateway manually only after installing/updating the plugin when the automatic restart has not happened, when config reload is disabled, or when the channel probe does not become healthy:

openclaw gateway restart

If you run the gateway manually instead of as a service and it is not already running, start it after activation:

openclaw gateway run

The --token value above is the ClawChat invite code for OpenClaw's generic channels add CLI surface on hosts that expose this plugin in the channel catalog; the setup write only creates the enabled channel skeleton. Persisted token fields, default groupMode: "all", plugins.entries.openclaw-clawchat, plugins.allow, and tools.alsoAllow are written together only after the invite code exchange succeeds. The plugin registers the ClawChat account/media/search/moment tools with the OpenClaw agent harness at plugin load time, and activation/login preserves existing plugin entry fields, creates plugins.allow with openclaw-clawchat when it is missing, appends the same id when it already exists, and ensures tool policy covers the plugin. If tools.allow or tools.alsoAllow does not already cover it, activation/login appends the plugin id to tools.alsoAllow so policy-restricted agents can execute the tools. Operators who prefer quieter groups can set groupMode: "mention"; later credential refreshes preserve that explicit choice. Before activation, account/media tools return a config error instead of disappearing; after activation/login, the channel is enabled and the same tools read the persisted token/userId after the runtime plugin reloads or the Gateway restarts.

After activation/login, the channel section is enabled and has credentials:

{
  channels: {
    "openclaw-clawchat": {
      enabled: true,
      replyMode: "stream",
      groupMode: "all",
      forwardThinking: true,
      forwardToolCalls: false,
      token: "...",
      userId: "...",
      refreshToken: "..."
    }
  },
  plugins: {
    allow: ["openclaw-clawchat"],
    entries: {
      "openclaw-clawchat": {
        enabled: true
      }
    }
  },
  tools: {
    alsoAllow: ["openclaw-clawchat"]
  }
}

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          plugin adapter (setup, auth.login, gateway, agentPrompt)
  runtime.ts          inbound dispatch + reply dispatcher
  client.ts           ClawChat WebSocket client adapter and stream helpers
  api-client.ts       REST client for /v1/* + /media/upload
  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
  login.runtime.ts    invite-code exchange flow
  media-runtime.ts    media download/upload pipeline
  reply-dispatcher.ts static vs stream routing
  tools.ts            clawchat_* agent tools
  protocol.ts         v2 envelope shapes
  config.ts           defaults + typebox schema
tools/
  standalone-webchat-server.mjs
  standalone-webchat.html
docs/
  openclaw-clawchat.md   full docs (protocol, diagrams, troubleshooting)

Documentation

See docs/openclaw-clawchat.md for:

• 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:

./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:

./install_openclaw.sh

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

./install_openclaw.sh 2026.5.16-1

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

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

License

See the repository root.