Gateway
Giao thức cầu nối
Vì sao nó từng tồn tại
- Ranh giới bảo mật: cầu nối phơi bày một danh sách cho phép nhỏ thay vì toàn bộ bề mặt API Gateway.
- Ghép cặp + danh tính nút: việc chấp nhận nút do Gateway sở hữu và gắn với token riêng cho từng nút.
- UX khám phá: các nút có thể khám phá Gateway qua Bonjour trên LAN, hoặc kết nối trực tiếp qua tailnet.
- WS vòng lặp cục bộ: mặt phẳng điều khiển WS đầy đủ vẫn ở cục bộ trừ khi được tạo đường hầm qua SSH.
Truyền tải
- TCP, mỗi dòng một đối tượng JSON (JSONL).
- TLS tùy chọn (khi
bridge.tls.enabledlà true). - Cổng trình nghe mặc định trước đây là
18790(các bản dựng hiện tại không khởi động cầu nối TCP).
Khi TLS được bật, bản ghi TXT khám phá bao gồm bridgeTls=1 cùng với
bridgeTlsSha256 làm gợi ý không bí mật. Lưu ý rằng bản ghi TXT Bonjour/mDNS
không được xác thực; client không được xem vân tay được quảng bá là ghim có thẩm quyền
nếu không có chủ ý rõ ràng của người dùng hoặc cách xác minh ngoài băng khác.
Bắt tay + ghép cặp
- Client gửi
hellovới siêu dữ liệu nút + token (nếu đã ghép cặp). - Nếu chưa ghép cặp, Gateway trả lời
error(NOT_PAIRED/UNAUTHORIZED). - Client gửi
pair-request. - Gateway chờ phê duyệt, rồi gửi
pair-okvàhello-ok.
Trước đây, hello-ok trả về serverName; các bề mặt plugin được lưu trữ hiện được
quảng bá qua pluginSurfaceUrls. Canvas/A2UI dùng
pluginSurfaceUrls.canvas; alias không còn dùng canvasHostUrl không thuộc
giao thức đã được tái cấu trúc.
Khung
Client → Gateway:
req/res: RPC Gateway có phạm vi (chat, sessions, config, health, voicewake, skills.bins)event: tín hiệu nút (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 nút (canvas.*,camera.*,screen.record,location.get,sms.send)event: cập nhật chat cho các phiên đã đăng kýping/pong: keepalive
Việc thực thi danh sách cho phép cũ từng nằm trong src/gateway/server-bridge.ts (đã gỡ bỏ).
Sự kiện vòng đời exec
Các nút có thể phát sự kiện exec.finished để hiển thị hoạt động system.run đã hoàn tất.
Các sự kiện này được ánh xạ thành sự kiện hệ thống trong Gateway. (Các nút cũ vẫn có thể phát exec.started.)
Các nút có thể phát exec.denied cho các lần thử system.run bị từ chối; Gateway chấp nhận
sự kiện này như một từ chối kết thúc và không đưa sự kiện hệ thống vào hàng đợi hoặc đánh thức công việc agent.
Trường payload (tất cả đều tùy chọn trừ khi được ghi chú):
sessionKey(bắt buộc): phiên agent để tương quan sự kiện và, đối vớiexec.finished, chuyển phát sự kiện hệ thống.runId: id exec duy nhất để gom 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 đã hoàn tất).reason: lý do từ chối (chỉ khi bị từ chối).
Cách dùng tailnet trước đây
- Bind cầu nối vào IP tailnet:
bridge.bind: "tailnet"trong~/.openclaw/openclaw.json(chỉ là lịch sử;bridge.*không còn hợp lệ). - Client kết nối qua tên MagicDNS hoặc IP tailnet.
- Bonjour không đi qua các mạng; 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
Cầu nối là v1 ngầm định (không đàm phán min/max). Phần này chỉ là tham khảo lịch sử; các client nút/người vận hành hiện tại dùng WebSocket Giao thức Gateway.
