Understanding the Legacy Bridge Protocol

Dealing with legacy code is a reality for most of us. You build a system that works, but then technology moves on, and you find yourself supporting an older transport layer while the rest of the world moves to something newer. It is important to know how these older pieces fit together so you don’t break things when you touch them.

I want to walk you through the Bridge protocol. It is a legacy node transport using TCP JSONL. While I recommend that you use the unified Gateway WebSocket protocol for new node clients, you might still encounter the Bridge protocol in older environments.

What You’ll Need

• An older OpenClaw build (current builds no longer ship the TCP bridge listener).
• A node client or operator setup.
• Access to the ~/.openclaw/openclaw.json configuration file.

Quick Start

If you are working with a system that still uses the Bridge protocol, here is the fastest way to understand the connection flow.

1. Transport Basics: The protocol runs over TCP and expects one JSON object per line (JSONL). The legacy default port is 18790.
2. Handshake: Your client must start by sending a hello frame containing node metadata and a token.
3. Pairing: If the node is not paired, the gateway returns an error (NOT_PAIRED). You then send a pair-request and wait for the gateway to send pair-ok.
4. Configuration: If you need to bind the bridge to a tailnet IP, update your ~/.openclaw/openclaw.json with:

   {
     "bridge.bind": "tailnet"
   }

5. Security: If you enable TLS (bridge.tls.enabled: true), nodes can pin the certificate using the bridgeTlsSha256 found in discovery TXT records.

Frame Types

Once connected, communication happens through specific frames. I have listed the core frames you will see:

• Client to Gateway:
  • req / res: Scoped RPC calls for chat, sessions, or health.
  • event: Signals like voice transcripts or agent requests.
• Gateway to Client:
  • invoke / invoke-res: Commands for the node, such as camera.* or screen.record.
  • ping / pong: Standard keepalive signals.

Exec Lifecycle Events

Nodes use specific events to report system.run activity. You can emit exec.finished or exec.denied with these fields:

{
  "sessionKey": "required-session-id",
  "runId": "unique-id",
  "command": "raw-command-string",
  "exitCode": 0,
  "success": true
}

Troubleshooting

I have found a few common hurdles when dealing with this legacy setup:

• Connection Refused: Current OpenClaw builds do not start the TCP bridge listener. This document is for historical reference.
• Discovery Fails: Bonjour does not cross networks. If you are not on the same LAN, you must use manual host/port settings or wide-area DNS-SD.
• Config Errors: Legacy bridge.* keys are no longer part of the current config schema.
• Pairing Failures: If you receive UNAUTHORIZED, ensure your per-node token is valid and the gateway has approved the pairing.

If you need help migrating to the newer protocol or setting up your environment, check out the AI Setup Assistant.

What’s Next

• Gateway Protocol Documentation
• Node Identity and Admission