docs: refresh bridge removal mirrors

This commit is contained in:
Peter Steinberger
2026-04-04 21:24:09 +01:00
parent 79e8edc7bd
commit 4b5146921c
6 changed files with 26 additions and 13 deletions

View File

@@ -171,6 +171,10 @@
"source": "Network model",
"target": "网络模型"
},
{
"source": "Bridge protocol (legacy nodes, historical)",
"target": "Bridge protocol旧版节点历史参考"
},
{
"source": "Doctor",
"target": "Doctor"

View File

@@ -1,5 +1,5 @@
---
summary: "Bridge protocol (legacy nodes): TCP JSONL, pairing, scoped RPC"
summary: "Historical bridge protocol (legacy nodes): TCP JSONL, pairing, scoped RPC"
read_when:
- Building or debugging node clients (iOS/Android/macOS node mode)
- Investigating pairing or bridge auth failures
@@ -13,7 +13,7 @@ title: "Bridge Protocol"
The TCP bridge has been **removed**. Current OpenClaw builds do not ship the bridge listener and `bridge.*` config keys are no longer in the schema. This page is kept for historical reference only. Use the [Gateway Protocol](/gateway/protocol) for all node/operator clients.
</Warning>
## Why we have both
## Why it existed
- **Security boundary**: the bridge exposes a small allowlist instead of the
full gateway API surface.
@@ -27,7 +27,8 @@ The TCP bridge has been **removed**. Current OpenClaw builds do not ship the bri
- TCP, one JSON object per line (JSONL).
- Optional TLS (when `bridge.tls.enabled` is true).
- Legacy default listener port was `18790` (current builds do not start a TCP bridge).
- Historical default listener port was `18790` (current builds do not start a
TCP bridge).
When TLS is enabled, discovery TXT records include `bridgeTls=1` plus
`bridgeTlsSha256` as a non-secret hint. Note that Bonjour/mDNS TXT records are
@@ -41,7 +42,8 @@ authoritative pin without explicit user intent or other out-of-band verification
3. Client sends `pair-request`.
4. Gateway waits for approval, then sends `pair-ok` and `hello-ok`.
`hello-ok` returns `serverName` and may include `canvasHostUrl`.
Historically, `hello-ok` returned `serverName` and could include
`canvasHostUrl`.
## Frames
@@ -72,15 +74,16 @@ Payload fields (all optional unless noted):
- `exitCode`, `timedOut`, `success`, `output`: completion details (finished only).
- `reason`: denial reason (denied only).
## Tailnet usage
## Historical tailnet usage
- Bind the bridge to a tailnet IP: `bridge.bind: "tailnet"` in
`~/.openclaw/openclaw.json`.
`~/.openclaw/openclaw.json` (historical only; `bridge.*` is no longer valid).
- Clients connect via MagicDNS name or tailnet IP.
- Bonjour does **not** cross networks; use manual host/port or wide-area DNSSD
when needed.
## Versioning
Bridge is currently **implicit v1** (no min/max negotiation). Backwardcompat
is expected; add a bridge protocol version field before any breaking changes.
The bridge was **implicit v1** (no min/max negotiation). This section is
historical reference only; current node/operator clients use the WebSocket
[Gateway Protocol](/gateway/protocol).

View File

@@ -22,7 +22,9 @@ The design goal is to keep all network discovery/advertising in the **Node Gatew
- **Gateway WS (control plane)**: the WebSocket endpoint on `127.0.0.1:18789` by default; can be bound to LAN/tailnet via `gateway.bind`.
- **Direct WS transport**: a LAN/tailnet-facing Gateway WS endpoint (no SSH).
- **SSH transport (fallback)**: remote control by forwarding `127.0.0.1:18789` over SSH.
- **Legacy TCP bridge (deprecated/removed)**: older node transport (see [Bridge protocol](/gateway/bridge-protocol)); no longer advertised for discovery.
- **Legacy TCP bridge (removed)**: older node transport (see
[Bridge protocol](/gateway/bridge-protocol)); no longer advertised for
discovery and no longer part of current builds.
Protocol details:

View File

@@ -16,7 +16,8 @@ process that owns channel connections and the WebSocket control plane.
- One Gateway per host is recommended. It is the only process allowed to own the WhatsApp Web session. For rescue bots or strict isolation, run multiple gateways with isolated profiles and ports. See [Multiple gateways](/gateway/multiple-gateways).
- Loopback first: the Gateway WS defaults to `ws://127.0.0.1:18789`. The wizard creates shared-secret auth by default and usually generates a token, even for loopback. For non-loopback access, use a valid gateway auth path: shared-secret token/password auth, or a correctly configured non-loopback `trusted-proxy` deployment. Tailnet/mobile setups usually work best through Tailscale Serve or another `wss://` endpoint instead of raw tailnet `ws://`.
- Nodes connect to the Gateway WS over LAN, tailnet, or SSH as needed. The legacy TCP bridge is deprecated.
- Nodes connect to the Gateway WS over LAN, tailnet, or SSH as needed. The
legacy TCP bridge has been removed.
- Canvas host is served by the Gateway HTTP server on the **same port** as the Gateway (default `18789`):
- `/__openclaw__/canvas/`
- `/__openclaw__/a2ui/`

View File

@@ -22,7 +22,7 @@ Only clients that explicitly call `node.pair.*` use this flow.
- **Pending request**: a node asked to join; requires approval.
- **Paired node**: approved node with an issued auth token.
- **Transport**: the Gateway WS endpoint forwards requests but does not decide
membership. (Legacy TCP bridge support is deprecated/removed.)
membership. (Legacy TCP bridge support has been removed.)
## How pairing works

View File

@@ -16,7 +16,10 @@ devices across localhost, LAN, and tailnet.
Most operations flow through the Gateway (`openclaw gateway`), a single long-running process that owns channel connections and the WebSocket control plane.
- **Loopback first**: the Gateway WS defaults to `ws://127.0.0.1:18789`. Tokens are required for non-loopback binds.
- **Loopback first**: the Gateway WS defaults to `ws://127.0.0.1:18789`.
Non-loopback binds require a valid gateway auth path: shared-secret
token/password auth, or a correctly configured non-loopback
`trusted-proxy` deployment.
- **One Gateway per host** is recommended. For isolation, run multiple gateways with isolated profiles and ports ([Multiple Gateways](/gateway/multiple-gateways)).
- **Canvas host** is served on the same port as the Gateway (`/__openclaw__/canvas/`, `/__openclaw__/a2ui/`), protected by Gateway auth when bound beyond loopback.
- **Remote access** is typically SSH tunnel or Tailscale VPN ([Remote Access](/gateway/remote)).
@@ -54,7 +57,7 @@ Local trust:
## Nodes + transports
- [Nodes overview](/nodes)
- [Bridge protocol (legacy nodes)](/gateway/bridge-protocol)
- [Bridge protocol (legacy nodes, historical)](/gateway/bridge-protocol)
- [Node runbook: iOS](/platforms/ios)
- [Node runbook: Android](/platforms/android)