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.

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

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

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:

"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

Environment variables

Lifecycle hooks

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

openclaw skills logs chatclaw

Expected output:

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

Troubleshooting

File access

This skill reads and writes the following local files:

$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)