Neura Market Logo

RPC Adapters for External CLIs and Gateway Patterns

This page covers JSON-RPC adapters for external command-line tools like signal-cli and imsg. Developers integrating Signal or iMessage into OpenClaw need this reference.

Read this when

  • Adding or changing external CLI integrations
  • Debugging RPC adapters (signal-cli, imsg)

OpenClaw communicates with external command-line tools through JSON-RPC. Currently, two distinct approaches are in use.

Pattern A: HTTP daemon (signal-cli)

  • signal-cli functions as a background service that listens for JSON-RPC requests over HTTP.
  • Server-sent events (/api/v1/events) deliver the event stream.
  • Endpoint for health checks: /api/v1/check.
  • OpenClaw manages the daemon's lifecycle when channels.signal.transport.kind="managed-native" is enabled (this is the default).

Refer to Signal for configuration details and available endpoints.

Pattern B: stdio child process (imsg)

  • For iMessage, OpenClaw launches imsg rpc as a child process.
  • Communication uses line-delimited JSON-RPC across stdin and stdout, with one JSON object per line.
  • No TCP port or daemon is needed.

The essential methods are:

  • watch.subscribe → used for notifications (method: "message")
  • watch.unsubscribe
  • send
  • chats.list (for probing and diagnostics)

Consult iMessage for setup instructions and addressing, where chat_id is recommended over display strings.

Adapter guidelines

  • The gateway controls the process, starting and stopping it according to the provider's lifecycle.
  • Ensure RPC clients are resilient: implement timeouts and restart on process exit.
  • Use stable identifiers such as chat_id instead of display strings.