Connecting External Messengers with RPC Adapters

Ever tried to glue two different tools together only to find they don’t speak the same language? It is a common headache when you need a core system to talk to external messaging CLIs. I have spent too much time dealing with brittle integrations that break the moment a process restarts or a connection drops.

OpenClaw handles this by using JSON-RPC adapters. Instead of messy workarounds, it uses two specific patterns to keep communication clean and reliable. I will show you how these work so you can get your messaging setup running without the usual friction.

What You’ll Need

• OpenClaw gateway installed
• signal-cli (for Signal integration)
• imsg (only for legacy iMessage setups)
• BlueBubbles (recommended for new iMessage setups)

Quick Start

OpenClaw uses two main patterns to talk to external tools. Here is how to get moving with them.

Pattern A: Signal via HTTP Daemon

If you are using Signal, OpenClaw talks to signal-cli running as a daemon. It uses JSON-RPC over HTTP.

1. Enable Auto-Start: In your configuration, set channels.signal.autoStart=true. This lets OpenClaw own the lifecycle of the process.
2. Monitor Events: OpenClaw listens to the SSE stream at /api/v1/events.
3. Check Health: You can verify the connection at the /api/v1/check endpoint.

Pattern B: Legacy iMessage via stdio

For older iMessage setups using imsg, OpenClaw spawns a child process.

1. Start the Process: OpenClaw runs imsg rpc.
2. Communication: It sends line-delimited JSON objects over stdin and stdout.
3. Core Methods: The integration uses these specific methods:
   • watch.subscribe: Starts receiving “message” notifications.
   • watch.unsubscribe: Stops notifications.
   • send: Dispatches a new message.
   • chats.list: Used for diagnostics and probing.

Troubleshooting

Integration issues usually fall into two categories. Here is how to handle them based on the official guidelines.

Using the wrong tool for iMessage If you are starting a fresh iMessage setup, do not use the legacy imsg adapter. I recommend using BlueBubbles instead for better results.

Unreliable message routing If messages are not reaching the right place, check your identifiers. You should prefer stable IDs like chat_id over display strings, which can change and break your logic.

Process exits The gateway is designed to own the process. If a connection drops, ensure your RPC clients are resilient. They should handle timeouts and be ready to restart as soon as a process exits.

If you hit a wall with your specific configuration, check out the AI Setup Assistant for help.

What’s Next

• Signal Setup Guide
• BlueBubbles Integration
• Legacy iMessage Docs