Gateway
Giao thức cầu nối
Lý do từng tồn tại
- Ranh giới bảo mật: chỉ cung cấp 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 tiếp nhận Node do Gateway quản lý và gắn với token riêng cho từng Node.
- Trải nghiệm khám phá: các Node có thể khám phá Gateway qua Bonjour trên mạng LAN hoặc kết nối trực tiếp qua tailnet.
- WebSocket local loopback: toàn bộ mặt phẳng điều khiển WebSocket được giữ 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 (
bridge.tls.enabled: true). - Cổng lắng nghe mặc định là
18790.
Khi TLS được bật, các 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. Các bản ghi TXT Bonjour/mDNS không được xác thực; máy khách không thể coi dấu vân tay được quảng bá là mã ghim có thẩm quyền nếu không có phương thức xác minh ngoài băng khác.
Bắt tay và ghép cặp
- Máy khách gửi
hellokèm siêu dữ liệu Node và token (nếu đã ghép cặp). - Nếu chưa ghép cặp, Gateway phản hồi
error(NOT_PAIRED/UNAUTHORIZED). - Máy khách gửi
pair-request. - Gateway chờ phê duyệt, sau đó 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 trên giao thức Gateway hiện tại (Canvas/A2UI sử dụng pluginSurfaceUrls.canvas).
Khung
Từ máy khách đến Gateway:
req/res: RPC Gateway có phạm vi giới hạn (trò chuyện, phiên, cấu hình, tình trạng, đánh thức bằng giọng nói, skills.bins).event: tín hiệu Node (bản chép lời giọng nói, yêu cầu tác tử, đăng ký nhận trò chuyện, vòng đời thực thi).
Từ Gateway đến máy khách:
invoke/invoke-res: lệnh Node (canvas.*,camera.*,screen.record,location.get,sms.send).event: cập nhật trò chuyện cho các phiên đã đăng ký.ping/pong: duy trì kết nối.
Việc thực thi danh sách cho phép từng nằm trong src/gateway/server-bridge.ts (đã loại bỏ).
Sự kiện vòng đời thực thi
Các Node phát exec.finished để hiển thị hoạt động system.run đã hoàn tất, được Gateway ánh xạ thành sự kiện hệ thống (các Node cũ cũng có thể phát exec.started). exec.denied đánh dấu một lần thử system.run bị từ chối là trạng thái từ chối kết thúc mà không xếp hàng sự kiện hệ thống hoặc đánh thức công việc của tác tử.
Các trường dữ liệu tải (tất cả đều tùy chọn trừ khi có ghi chú):
| Trường | Ghi chú |
|---|---|
sessionKey |
Bắt buộc. Phiên tác tử để tương quan sự kiện và, đối với exec.finished, chuyển phát sự kiện hệ thống. |
runId |
Mã định danh thực thi duy nhất để nhóm. |
command |
Chuỗi lệnh thô hoặc đã định dạng. |
exitCode, timedOut, 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 sử dụng tailnet trước đây
- Liên kết cầu nối với một địa chỉ IP tailnet:
bridge.bind: "tailnet"trong~/.openclaw/openclaw.json(chỉ mang tính lịch sử;bridge.*không còn là cấu hình hợp lệ). - Máy khách kết nối qua tên MagicDNS hoặc địa chỉ IP tailnet.
- Bonjour không hoạt động xuyên mạng; nếu không, cần DNS-SD diện rộng hoặc máy chủ/cổng được chỉ định thủ công.
Quản lý phiên bản
Cầu nối ngầm định là phiên bản 1, không có thương lượng phiên bản tối thiểu/tối đa. Các máy khách Node/người vận hành hiện tại sử dụng giao thức Gateway WebSocket, có thương lượng phạm vi phiên bản giao thức.
