Bridge protocol

Bridge protocol 문서는 OpenClaw 공식 문서(gateway/bridge-protocol)를 한국어로 정리한 가이드입니다. Historical bridge protocol (legacy nodes): TCP JSONL, pairing, scoped RPC 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Historical bridge protocol (legacy nodes): TCP JSONL, pairing, scoped RPC

한국어 가이드 범위: gateway/bridge-protocol 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Why it existed
Transport
Handshake and pairing
Frames
Exec lifecycle events
Historical tailnet usage
Versioning
관련 문서

상세 내용

본문

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 historical reference only. Use the Gateway protocol for all node/operator clients.

Why it existed

주요 항목:

Security boundary: exposed a small allowlist instead of the full gateway API surface.
Pairing + node identity: node admission was owned by the gateway and tied to a per-node token.
Discovery UX: nodes could discover gateways via Bonjour on LAN, or connect directly over a tailnet.
Loopback WS: the full WS control plane stayed local unless tunneled via SSH.

Transport

When TLS was enabled, discovery TXT records included bridgeTls=1 plus bridgeTlsSha256 as a non-secret hint. Bonjour/mDNS TXT records are unauthenticated; clients could not treat the advertised fingerprint as an authoritative pin without other out-of-band verification.

주요 항목:

TCP, one JSON object per line (JSONL).
Optional TLS (bridge.tls.enabled: true).
Default listener port was 18790.

Handshake and pairing

Client sends hello with node metadata plus token (if already paired). 2. If not paired, gateway replies error (NOT_PAIRED / UNAUTHORIZED). 3. Client sends pair-request. 4. Gateway waits for approval, then sends pair-ok and hello-ok.

Frames

Allowlist enforcement lived in src/gateway/server-bridge.ts (removed).

주요 항목:

req / res: scoped gateway RPC (chat, sessions, config, health, voicewake, skills.bins).
event: node signals (voice transcript, agent request, chat subscribe, exec lifecycle).
invoke / invoke-res: node commands (canvas.*, camera.*, screen.record, location.get, sms.send).
event: chat updates for subscribed sessions.
ping / pong: keepalive.

Exec lifecycle events

Nodes emitted exec.finished to surface completed system.run activity, mapped to system events by the gateway (legacy nodes could also emit exec.started). exec.denied marked a denied system.run attempt as a terminal denial without enqueuing a system event or waking agent work.

Field	Notes
`sessionKey`	Required. Agent session for event correlation and, for `exec.finished`, system event delivery.
`runId`	Unique exec id for grouping.
`command`	Raw or formatted command string.
`exitCode`, `timedOut`, `output`	Completion details (finished only).
`reason`	Denial reason (denied only).

Historical tailnet usage

주요 항목:

Bind the bridge to a tailnet IP: bridge.bind: "tailnet" in ~/.openclaw/openclaw.json (historical only; bridge.* is no longer valid config).
Clients connected via MagicDNS name or tailnet IP.
Bonjour does not cross networks; wide-area DNS-SD or a manual host/port was required otherwise.

Versioning

The bridge was implicit v1, with no min/max negotiation. Current node/operator clients use the WebSocket Gateway protocol, which does negotiate a protocol version range.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/bridge-protocol
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Bridge protocol

핵심 요약

Historical bridge protocol (legacy nodes): TCP JSONL, pairing, scoped RPC

한국어 가이드 범위: gateway/bridge-protocol 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Why it existed
Transport
Handshake and pairing
Frames
Exec lifecycle events
Historical tailnet usage
Versioning
관련 문서

상세 내용

본문

Why it existed

주요 항목:

Security boundary: exposed a small allowlist instead of the full gateway API surface.
Pairing + node identity: node admission was owned by the gateway and tied to a per-node token.
Discovery UX: nodes could discover gateways via Bonjour on LAN, or connect directly over a tailnet.
Loopback WS: the full WS control plane stayed local unless tunneled via SSH.

Transport

주요 항목:

TCP, one JSON object per line (JSONL).
Optional TLS (bridge.tls.enabled: true).
Default listener port was 18790.

Handshake and pairing

Client sends hello with node metadata plus token (if already paired). 2. If not paired, gateway replies error (NOT_PAIRED / UNAUTHORIZED). 3. Client sends pair-request. 4. Gateway waits for approval, then sends pair-ok and hello-ok.

Frames

Allowlist enforcement lived in src/gateway/server-bridge.ts (removed).

주요 항목:

req / res: scoped gateway RPC (chat, sessions, config, health, voicewake, skills.bins).
event: node signals (voice transcript, agent request, chat subscribe, exec lifecycle).
invoke / invoke-res: node commands (canvas.*, camera.*, screen.record, location.get, sms.send).
event: chat updates for subscribed sessions.
ping / pong: keepalive.

Exec lifecycle events

Field	Notes
`sessionKey`	Required. Agent session for event correlation and, for `exec.finished`, system event delivery.
`runId`	Unique exec id for grouping.
`command`	Raw or formatted command string.
`exitCode`, `timedOut`, `output`	Completion details (finished only).
`reason`	Denial reason (denied only).

Historical tailnet usage

주요 항목:

Bind the bridge to a tailnet IP: bridge.bind: "tailnet" in ~/.openclaw/openclaw.json (historical only; bridge.* is no longer valid config).
Clients connected via MagicDNS name or tailnet IP.
Bonjour does not cross networks; wide-area DNS-SD or a manual host/port was required otherwise.

Versioning

The bridge was implicit v1, with no min/max negotiation. Current node/operator clients use the WebSocket Gateway protocol, which does negotiate a protocol version range.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/bridge-protocol
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Bridge protocol

핵심 요약

문서 구성

상세 내용

본문

Why it existed

Transport

Handshake and pairing

Frames

Exec lifecycle events

Historical tailnet usage

Versioning

관련 문서

실습 체크리스트

관련 링크

관련 가이드

Bridge protocol

핵심 요약

문서 구성

상세 내용

본문

Why it existed

Transport

Handshake and pairing

Frames

Exec lifecycle events

Historical tailnet usage

Versioning

관련 문서

실습 체크리스트

관련 링크

관련 가이드