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 plugin install @onethum/openclaw-plugin-chatbuddy

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

"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

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