ChatClaw#

ChatClaw is a persistent background bridge that connects your local OpenClaw agent to the ChatClaw cloud dashboard. Once installed and enabled, it runs automatically with OpenClaw and allows you to chat with your agent, monitor token usage, and manage tasks from any browser or mobile device — without exposing any ports or configuring a firewall.

What it does#

Transparency note: The cloud relay endpoint ( api.sumeralabs.com) is operated by SumeraLabs, the company behind ChatClaw. chatclaw.sumeralabs.com is the product domain; sumeralabs.com is the infrastructure domain. Both are owned and operated by the same team.

ChatClaw opens two connections when enabled:

1. Cloud relay — an outbound WebSocket to wss://api.sumeralabs.com/ws/agent/{api_key}. This is how your dashboard communicates with the skill. It is a purely outbound connection and requires no inbound port forwarding.
2. Local gateway — a WebSocket connection to ws://localhost:18789 for Ed25519 authentication only, plus HTTP SSE calls to http://localhost:18789/v1/chat/completions for all chat traffic. The HTTP endpoint is auto-enabled in openclaw.json on first start.

Messages flow bidirectionally in real time. User messages sent from the dashboard are forwarded to the OpenClaw agent via HTTP SSE streaming. Each token of the agent's response is relayed back to the dashboard as it is generated, producing a live typewriter effect.

Permissions & Capabilities#

This section fully discloses every action the skill can perform in response to a cloud relay message. All operations require a valid ChatClaw API key; the relay rejects unauthenticated connections before any message reaches the skill.

CapabilityTrigger messageScopeNotesChat relayany message with text/ content fieldSends text to OpenClaw agent via HTTP SSE, streams response backCore featureFile listingfiles.listRead-only; returns file metadata for the agent workspace via gateway RPC ( agents.files.list)No file content returned at this stepFile readfiles.getRead-only; returns content of a named workspace file via gateway RPC ( agents.files.get); scoped to agentId: "main" workspaceEach request is logged with the filenameSkills listskills.listRuns openclaw skills list --json locally; returns skill metadataRead-onlyEnable/disable skillskills.set_enabledRuns openclaw config set skills.entries.<name>.enabled true/false; affects local OpenClaw configEach invocation is logged with skill name and new stateReinstall skillskills.reinstallRuns clawhub install <name> --force; replaces skill files from ClawHub registryEach invocation is logged with skill name

Why operator-level credentials are required: The gateway uses Ed25519 device authentication with operator scopes ( operator.admin, operator.approvals, operator.pairing). This is required by the OpenClaw gateway handshake protocol to establish an authenticated connection — there is no lower-privilege connection mode for skill bridges. The operator token is read from device-auth.json and used only for the initial WebSocket handshake; it is never transmitted to the cloud relay.

Security mitigations:

• All capabilities require a valid API key authenticated at the cloud relay layer before any message reaches the skill
• File access is read-only and scoped to the agent workspace via the gateway RPC ( agentId: "main")
• Skills enable/disable and reinstall are logged locally on every invocation
• No shell commands with user-controlled arguments are executed — skill names and file names are passed as positional arguments to controlled subprocess calls, not interpolated into shell strings
• Disabling this skill reverts any openclaw.json changes it made

Architecture#

text

ChatClaw Dashboard (browser / mobile)
        ↕  wss://api.sumeralabs.com
  ChatClaw Cloud Relay (FastAPI)
        ↕  wss://api.sumeralabs.com/ws/agent/{api_key}
  ChatClaw Skill  ←── this package
        ↕  ws://localhost:18789 (auth handshake, Ed25519)
        ↕  http://localhost:18789/v1/chat/completions (SSE streaming)
  OpenClaw Gateway
        ↕
  OpenClaw Agent (LLM)

Requirements#

• OpenClaw: v2026.3.28 or later
• Python: 3.8+
• Dependencies: websockets, cryptography, aiohttp

Important: ChatClaw v0.3.0+ requires OpenClaw v2026.3.28 or later due to authentication changes. If you're using an older OpenClaw version, please upgrade OpenClaw or use ChatClaw v0.2.9 (legacy).

Installation#

Via OpenClaw Control UI (recommended)#

1. Open the Control UI at http://localhost:18789
2. Go to Skills → Marketplace
3. Search for ChatClaw
4. Click Install, enter your API key, click Enable

Note: On first enable, the skill automatically sets gateway.http.endpoints.chatCompletions.enabled = true in your openclaw.json. If the skill made that change, disabling it will revert it automatically. If chatCompletions was already enabled before install, the skill leaves your config unchanged on disable.

The skill starts immediately and auto-starts with OpenClaw on every subsequent boot.

Via OpenClaw CLI#

bash

npx clawhub install chatclaw
openclaw skills enable chatclaw
openclaw skills logs chatclaw

Before enabling, add your API key to openclaw.json under skills.entries.chatclaw.config:

json

"skills": {
  "entries": {
    "chatclaw": {
      "enabled": true,
      "config": {
        "apiKey": "ck_your_key_here",
        "cloud_url": "wss://api.sumeralabs.com"
      }
    }
  }
}

Agent-assisted setup#

Your OpenClaw agent can install and configure ChatClaw for you without any manual steps.

Get the one-click setup prompt from app.chatclaw.sumeralabs.com/setup — it includes your API key pre-filled and full instructions to paste directly into chat.

Configuration#

KeyRequiredDefaultDescriptionapiKeyYes—ChatClaw API key from app.chatclaw.sumeralabs.comcloud_urlNowss://api.sumeralabs.comWebSocket relay URL (leave default unless self-hosting)

Environment variables#

VariableDescriptionOPENCLAW_DATA_DIROverride the OpenClaw data directory. Defaults to /data/.openclaw on Docker/VPS or ~/.openclaw on standard installs.CHATCLAW_CLOUD_URLOverride the cloud relay URL. Defaults to wss://api.sumeralabs.com. Leave unset unless self-hosting the relay.

Lifecycle hooks#

HookBehaviouron_enablePatches openclaw.json to enable the /v1/chat/completions endpoint, then starts the cloud ↔ gateway relay loopon_disableCloses both WebSocket connections, stops the relay loop, and reverts the chatCompletions patch in openclaw.json if the skill was the one that enabled it

Reconnection behaviour#

Both the cloud relay and the local gateway implement automatic reconnection with exponential backoff (5 s → 10 s → 20 s … up to 60 s). The skill never exits on a connection drop.

Verify it is working#

bash

openclaw skills logs chatclaw

Expected output:

text

Connected to cloud relay ✓
Gateway authenticated ✓
Both connections established — relaying messages ✓

Troubleshooting#

SymptomCauseFixCloud connection failedWrong API key or relay unreachableVerify key at app.chatclaw.sumeralabs.com; check network connectivityOpenClaw identity files not foundOpenClaw not initialised or non-default install pathRun openclaw wizard or set OPENCLAW_DATA_DIR``Gateway HTTP 403``chatCompletions endpoint not enabledRestart skill — on_enable auto-patches openclaw.json``Gateway auth rejectedOperator token expiredRe-pair device via openclaw devices approveStreaming works but token count shows 0sessions.json not yet writtenSend one message first; counts appear after the first completion

File access#

This skill reads and writes the following local files:

PathAccessPurpose$OPENCLAW_DATA_DIR/openclaw.jsonRead + WriteReads gateway auth token; enables chatCompletions HTTP endpoint on first start$OPENCLAW_DATA_DIR/identity/device.jsonReadEd25519 device identity for gateway authentication$OPENCLAW_DATA_DIR/identity/device-auth.jsonReadOperator token for gateway authentication$OPENCLAW_DATA_DIR/agents/main/sessions/sessions.jsonReadToken usage counts (input/output/context) per session

$OPENCLAW_DATA_DIR defaults to /data/.openclaw on Docker/VPS installs and ~/.openclaw on standard installs. It can be overridden via the OPENCLAW_DATA_DIR environment variable. No files outside this directory are accessed.

External connections#

This skill makes the following outbound network connections:

• wss://api.sumeralabs.com — ChatClaw cloud relay (authentication and message relay)
• ws://localhost:18789 — OpenClaw gateway WebSocket (Ed25519 auth handshake only)
• http://localhost:18789/v1/chat/completions — OpenClaw gateway HTTP (SSE streaming chat)

No inbound ports are opened. No user data is stored by the skill itself — messages are persisted by the ChatClaw backend (Supabase) for chat history.

Changelog#

v0.3.0 (2026-03-30)#

• Breaking: Now requires OpenClaw v2026.3.28+
• Fixed authentication for OpenClaw v2026.3.28 (added required scope headers)
• Fixed model field validation (changed from "auto" to "openclaw")
• Added cross-platform path resolution (Docker/VPS/macOS)
• Improved error messages for troubleshooting
• Added support for approval workflows (operator.approvals scope)

v0.2.9 (2026-03-12)#

• Initial ClawHub release

License#

MIT-0 (No Attribution Required)