> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Giao thức Bridge

# Giao thức Bridge (vận chuyển node kế thừa)

The Bridge protocol is a **legacy** node transport (TCP JSONL). New node clients
should use the unified Gateway WebSocket protocol instead.

Nếu bạn đang xây dựng một operator hoặc client node, hãy dùng
[Giao thức Gateway](/gateway/protocol).

**Note:** Current OpenClaw builds no longer ship the TCP bridge listener; this document is kept for historical reference.
Legacy `bridge.*` config keys are no longer part of the config schema.

## Vì sao chúng tôi có cả hai

* **Ranh giới bảo mật**: bridge chỉ phơi bày một danh sách cho phép nhỏ thay vì
  toàn bộ bề mặt API của gateway.
* **Ghép cặp + danh tính node**: việc cho phép node được sở hữu bởi gateway và gắn với token theo từng node.
* **UX khám phá**: node có thể khám phá gateway qua Bonjour trên LAN, hoặc kết nối
  trực tiếp qua tailnet.
* **WS loopback**: mặt phẳng điều khiển WS đầy đủ được giữ cục bộ trừ khi được
  chuyển tiếp qua đường hầm SSH.

## Vận chuyển

* TCP, mỗi dòng là một đối tượng JSON (JSONL).
* TLS tùy chọn (khi `bridge.tls.enabled` là true).
* Cổng listener mặc định kế thừa là `18790` (các bản dựng hiện tại không khởi động TCP bridge).

Khi TLS được bật, bản ghi TXT discovery bao gồm `bridgeTls=1` cùng với
`bridgeTlsSha256` như một gợi ý không bí mật. Lưu ý rằng bản ghi TXT của Bonjour/mDNS là
không được xác thực; client không được coi fingerprint được quảng bá là
pin có thẩm quyền nếu không có chủ đích rõ ràng từ người dùng hoặc xác minh ngoài băng tần khác.

## Bắt tay + ghép cặp

1. Client gửi `hello` với metadata của node + token (nếu đã ghép cặp).
2. Nếu chưa ghép cặp, gateway trả lời `error` (`NOT_PAIRED`/`UNAUTHORIZED`).
3. Client gửi `pair-request`.
4. Gateway chờ phê duyệt, sau đó gửi `pair-ok` và `hello-ok`.

`hello-ok` trả về `serverName` và có thể bao gồm `canvasHostUrl`.

## Khung (Frames)

Client → Gateway:

* `req` / `res`: RPC của Gateway theo phạm vi (chat, sessions, config, health, voicewake, skills.bins)
* `event`: tín hiệu node (bản chép lời giọng nói, yêu cầu agent, đăng ký chat, vòng đời exec)

Gateway → Client:

* `invoke` / `invoke-res`: lệnh node (`canvas.*`, `camera.*`, `screen.record`,
  `location.get`, `sms.send`)
* `event`: cập nhật chat cho các phiên đã đăng ký
* `ping` / `pong`: duy trì kết nối (keepalive)

Việc thực thi danh sách cho phép kế thừa nằm trong `src/gateway/server-bridge.ts` (đã bị loại bỏ).

## Sự kiện vòng đời Exec

Nodes can emit `exec.finished` or `exec.denied` events to surface system.run activity.
These are mapped to system events in the gateway. (Các node legacy vẫn có thể phát ra `exec.started`.)

Các trường payload (tất cả đều tùy chọn trừ khi có ghi chú):

* `sessionKey` (bắt buộc): phiên agent để nhận sự kiện hệ thống.
* `runId`: id exec duy nhất để nhóm.
* `command`: chuỗi lệnh thô hoặc đã định dạng.
* `exitCode`, `timedOut`, `success`, `output`: chi tiết hoàn tất (chỉ khi finished).
* `reason`: lý do từ chối (chỉ khi denied).

## Sử dụng tailnet

* Gắn bridge vào IP tailnet: `bridge.bind: "tailnet"` trong
  `~/.openclaw/openclaw.json`.
* Client kết nối qua tên MagicDNS hoặc IP tailnet.
* Bonjour **không** hoạt động xuyên mạng; hãy dùng host/cổng thủ công hoặc DNS‑SD diện rộng
  khi cần.

## Phiên bản hóa

Bridge is currently **implicit v1** (no min/max negotiation). Backward‑compat
is expected; add a bridge protocol version field before any breaking changes.