ChatBuddy Plugin for OpenClaw

Connect your ChatBuddy iOS app to your OpenClaw gateway — no VPN, no port forwarding, no tunnels.

How It Works

The ChatBuddy plugin establishes an outbound WebSocket connection from your OpenClaw server to the ChatBuddy relay service. Your iPhone talks to the relay over standard HTTPS, and the relay bridges messages to your server. Since the connection is outbound from your server, it works through NATs, firewalls, and consumer routers with zero configuration.

iPhone ──HTTPS──► ChatBuddy Relay ──WebSocket──► Your OpenClaw Server
iPhone ◄──SSE──── ChatBuddy Relay ◄──WebSocket── Your OpenClaw Server

Requirements

• OpenClaw v1.0.0 or later
• Node.js 18+
• ChatBuddy Pro subscription on your iPhone
• Internet connection on your server (outbound HTTPS/WSS only — no inbound ports needed)

Quick Start

1. Install the plugin

openclaw plugins install @onethum/openclaw-plugin-chatbuddy

Use openclaw plugins (plural) — the built-in plugins CLI. The singular openclaw plugin form is a bundled alias that can be disabled when you set a non-empty plugins.allow that omits "plugin".

The installer automatically:

• Enables the Chat Completions endpoint on your gateway
• Generates an auth token
• Registers your server with the ChatBuddy relay
• Establishes the relay connection

2. Pair your iPhone

openclaw chatbuddy pair

A QR code appears in your terminal. Scan it with your iPhone camera or the ChatBuddy app. Pairing completes in seconds.

3. Start chatting

Open ChatBuddy, select your server from the model picker, and chat. Messages are routed through the relay to your OpenClaw gateway and back — with no message content ever stored on the relay.

CLI Commands

| Command | Description | |---|---| | openclaw chatbuddy pair | Generate a QR code to connect your iPhone | | openclaw chatbuddy pair --web-only | Serve the pairing page on localhost only | | openclaw chatbuddy status | Show relay connection status and server info | | openclaw chatbuddy status --live | From the CLI, probes relay HTTP + local gateway (does not open a second WebSocket; see Troubleshooting) | | openclaw chatbuddy devices | List paired ChatBuddy devices | | openclaw chatbuddy revoke <name> | Revoke a specific device's access | | openclaw chatbuddy revoke --all | Revoke all paired devices | | openclaw chatbuddy reconnect | Force-reconnect to the relay | | openclaw chatbuddy config | View or edit plugin configuration |

Security

• No message persistence on the relay. Messages pass through in memory and are never written to disk or any database.
• One-time pairing tokens. Each QR code contains a single-use token that expires in 10 minutes and cannot be reused.
• Relay auth tokens are scoped to a specific (device, server) pair. A stolen token cannot access a different server.
• Server credentials are stored locally with restricted file permissions (chmod 600).
• All connections use TLS. The WebSocket connection to the relay uses WSS (TLS), and all iPhone-to-relay traffic is standard HTTPS.

Troubleshooting

The openclaw plugin command is unavailable... plugins.allow excludes "plugin"
Use the built-in plural command: openclaw plugins install @onethum/openclaw-plugin-chatbuddy (or openclaw plugins update …). That path does not require the meta "plugin" entry in plugins.allow. If you still use a strict plugins.allow list, add openclaw-plugin-chatbuddy (this plugin’s id) so the gateway can load it; only the singular openclaw plugin alias also needs "plugin".

Relay disconnected: replaced in gateway logs
The cloud relay only allows one WebSocket per registered server. A second OpenClaw process that authenticated the same serverId will kick off the first. The plugin also uses a local file lock under your plugin data directory so, on the same computer, a second openclaw run cannot open a parallel relay connection (you get a clear error and instructions instead of “replaced” in many cases). From the terminal, openclaw chatbuddy status --live does not open a second WebSocket; use the pairing page in the browser (http://127.0.0.1:<port>/chatbuddy/pair) or stop the gateway if you need terminal pairing while it is running.

"Not connected to relay"

• Check your server has internet access
• Run openclaw chatbuddy reconnect
• Check openclaw chatbuddy status for details

"QR code expired"

• Run openclaw chatbuddy pair to generate a fresh one

"Server offline" in ChatBuddy app

• Verify OpenClaw is running on your server
• Check openclaw chatbuddy status — relay should show "Connected"
• If relay shows "Disconnected", check internet and run openclaw chatbuddy reconnect

plugin already exists: .../extensions/openclaw-plugin-chatbuddy

• You already have a copy (e.g. a manual or linked install). Either install over it: openclaw plugins install @onethum/openclaw-plugin-chatbuddy --force, or remove that folder and run openclaw plugins install ... again. Ignore a follow-up “not a valid hook pack” line: OpenClaw may probe the same npm package as a hook pack after the plugin path conflict.

How the Relay Works

1. On startup, the plugin opens a WebSocket to relay.chatbuddyai.app
2. When you send a message from ChatBuddy, the app POSTs to api.chatbuddyai.app
3. The relay identifies your server and forwards the request over the WebSocket
4. The plugin receives the request, forwards it to your local OpenClaw gateway
5. The gateway streams the AI response back through the plugin → relay → your phone

The relay adds minimal latency (typically < 50ms) and never stores message content.

Data Storage

Plugin data is stored at ~/.openclaw/plugins/chatbuddy/:

| File | Contents | |---|---| | config.json | Plugin settings (server name, port, version) | | relay-credentials.json | Server ID and relay secret (chmod 600) | | store.json | Paired devices and pairing tokens |

Publishing (maintainers)

Releases use npm trusted publishing (OIDC). No tokens needed.

1. One-time setup on npmjs.com: Package → Settings → Trusted publishing → GitHub Actions

   • Organization/user: OneThum
   • Repository: chatbuddy
   • Workflow: publish.yml

2. To release: Bump version, commit, push tag:

   cd chatbuddy-openclaw-plugin
   npm version patch   # or minor/major
   git push origin main
   git push origin v$(node -p "require('./package.json').version")

License

MIT