@openclaw/mobile

OpenClaw channel plugin for the Mobile app. Routes messages through a Cloudflare Worker relay.

Architecture

Mobile App ←WS→ [CF Worker / Durable Object] ←WS→ [OpenClaw Plugin] → Gateway Pipeline

1. Plugin registers an openclaw-app channel with the Gateway
2. Gateway manages the channel lifecycle (start, stop, health monitoring)
3. The plugin connects outbound to the CF Worker relay via WebSocket
4. User messages from the mobile app flow through the relay into the Gateway's inbound pipeline
5. AI replies go through outbound.sendText — Gateway automatically filters security markers and thinking blocks
6. Filtered replies are forwarded to the mobile app via the relay
7. A 30-second ping keepalive prevents the Cloudflare Durable Object from hibernating and dropping the connection

Prerequisites

• OpenClaw Gateway installed and running (npm install -g openclaw@latest)
• A deployed Cloudflare Worker relay (see ../relay/)
• Node.js 22+

Install

From npm (when published):

openclaw plugins install @openclaw/mobile

For local development:

openclaw plugins install -l ./plugin

Quick Start

1. Deploy the relay

cd relay
npm install
npx wrangler deploy

Note the deployed URL (e.g. wss://openclaw-relay.your-name.workers.dev).

If you want relay authentication, set a secret:

npx wrangler secret put RELAY_TOKEN

2. Install the plugin

openclaw plugins install -l ./plugin

3. Configure

Add to ~/.openclaw/openclaw.json:

{
  "channels": {
    "openclaw-app": {
      "accounts": {
        "default": {
          "enabled": true,
          "relayUrl": "wss://openclaw-relay.your-name.workers.dev",
          "relayToken": "your-secret-token",
          "roomId": "default"
        }
      }
    }
  }
}

4. Restart the Gateway

openclaw gateway stop
openclaw gateway --port 18789

5. Verify

Open the Control UI at http://127.0.0.1:18789/ and navigate to the OpenClaw App channel page. You should see:

• Running: Yes
• Configured: Yes
• Connected: Yes

You can also check logs:

tail -f ~/.openclaw/logs/gateway.log | grep openclaw-app

Configuration

All config lives under channels.openclaw-app.accounts.<accountId> in ~/.openclaw/openclaw.json.

| Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | enabled | boolean | No | true | Enable/disable this account | | relayUrl | string | Yes | — | CF Worker relay WebSocket URL | | relayToken | string | No | "" | Shared secret for relay authentication (must match the Worker's RELAY_TOKEN secret) | | roomId | string | No | "default" | Room ID for relay routing (isolates conversations) |

You can also edit these fields directly in the Control UI config form.

Control UI

The plugin integrates with the OpenClaw Control UI:

• Status panel — shows Running, Configured, Connected, Last inbound, and error details
• Config form — editable fields for Relay URL, Relay Token, Room ID, and an Enable/Disable toggle
• Enable/Disable — the toggle in the UI writes enabled: true/false to the config and restarts the channel

How the relay works

The relay is a Cloudflare Worker with a Durable Object (RelayRoom):

• Each "room" is a named DO instance that bridges two WebSocket roles: plugin (the Gateway) and app (the mobile client)
• Messages from one role are forwarded to all peers of the opposite role
• The DO uses setWebSocketAutoResponse("ping", "pong") for keepalive without waking from hibernation
• The plugin sends a ping every 30 seconds to prevent idle disconnection
• Optional RELAY_TOKEN secret gates access to the relay

Message Protocol

App → Plugin (via relay)

{
  "type": "message",
  "content": "Hello",
  "sessionKey": "relay-session",
  "senderId": "openclaw-app-user",
  "senderName": "openclaw-app-user"
}

• sessionKey — the app's local session identifier; the plugin echoes it back in replies so the app can match them
• senderId / senderName — optional; defaults to "openclaw-app-user" / "openclaw-app-user"

Plugin → App (via relay)

{
  "type": "message",
  "role": "assistant",
  "content": "AI reply text",
  "sessionKey": "relay-session"
}

The plugin echoes back the exact sessionKey it received from the app, so the Flutter client can route the reply to the correct chat session.

Troubleshooting

| Problem | Cause | Fix | |---------|-------|-----| | "Channel config schema unavailable" in Control UI | Gateway loaded before plugin was installed | Restart the Gateway: openclaw gateway stop && openclaw gateway | | Running: No | startAccount returned early (old plugin version) | Update the plugin and restart Gateway | | Connected: No | Relay URL wrong or Worker not deployed | Check relayUrl in config; verify Worker is live with curl https://your-relay.workers.dev/health | | Relay keeps disconnecting | Ping keepalive not working or network issue | Check logs for "WebSocket error"; ensure relay Worker is deployed with Durable Objects enabled | | "relayUrl not configured" in logs | Missing relayUrl in account config | Add relayUrl under channels.openclaw-app.accounts.default | | Enable toggle in UI doesn't match JSON | Missing setAccountEnabled adapter (old plugin version) | Update the plugin and restart Gateway | | relayToken mismatch | Token in config doesn't match Worker secret | Ensure relayToken matches the RELAY_TOKEN secret set on the Worker | | App stuck loading, no reply shown | sessionKey mismatch between app and plugin | Ensure app sends sessionKey in message payload and plugin version ≥ current |

Useful commands

# Check plugin is loaded
openclaw plugins list

# Check channel status
openclaw channels status --probe

# Live logs
tail -f ~/.openclaw/logs/gateway.log | grep openclaw-app

# Verify relay is reachable
curl https://openclaw-relay.your-name.workers.dev/health