Chuyển đến nội dung chính
Giao thức WS của Gateway là mặt phẳng điều khiển duy nhất và phương thức truyền tải node cho OpenClaw. Các máy khách vận hành và node (CLI, giao diện web, ứng dụng macOS, node iOS/Android, node không giao diện) kết nối qua WebSocket và khai báo vai trò cùng phạm vi tại thời điểm bắt tay.

​
Các gói npm

Các gói này được phát hành cùng các đợt phát hành OpenClaw. Trong quá trình triển khai ban đầu, npm có thể trả về E404 cho đến khi bản phát hành đầu tiên chứa gói được xuất bản.
  • @openclaw/gateway-protocol cung cấp các schema, trình xác thực, kiểu TypeScript, trình trợ giúp nhẹ cho frame và lỗi, cùng các hằng số phiên bản. Tarball của gói bao gồm hợp đồng có thể đọc bằng máy protocol.schema.json đã được tạo.
  • @openclaw/gateway-client cung cấp máy khách Node tham chiếu và một điểm vào an toàn cho trình duyệt tại @openclaw/gateway-client/browser.
Để xem hướng dẫn về vòng đời ứng dụng, hãy xem Xây dựng máy khách Gateway. Đối với các ứng dụng giám sát Gateway dưới dạng tiến trình con, hãy xem Nhúng OpenClaw.

​
Phương thức truyền tải và tạo frame

  • WebSocket, frame văn bản, payload JSON.
  • Frame đầu tiên phải là một yêu cầu connect.
  • Các frame trước khi kết nối bị giới hạn ở 64 KiB (MAX_PREAUTH_PAYLOAD_BYTES). Sau khi bắt tay, tuân theo hello-ok.policy.maxPayload và hello-ok.policy.maxBufferedBytes. Khi bật chẩn đoán, các frame đến quá kích thước và bộ đệm đi chậm sẽ phát sự kiện payload.large trước khi gateway đóng kết nối hoặc loại bỏ frame. Các sự kiện này chứa surface, kích thước byte, giới hạn và mã lý do an toàn, tuyệt đối không chứa nội dung thông điệp, nội dung tệp đính kèm, byte frame thô, token, cookie hoặc bí mật.
Các dạng frame:
  • Yêu cầu: {type:"req", id, method, params}
  • Phản hồi: {type:"res", id, ok, payload|error}
  • Sự kiện: {type:"event", event, payload, seq?, stateVersion?}
Lỗi phản hồi sử dụng { code, message, details?, retryable?, retryAfterMs? }. Máy khách nên phân nhánh theo code và details.code; message vẫn ở dạng con người có thể đọc và có thể thay đổi, ngoại trừ trường hợp ghi chú tương thích quy định khác. Lỗi ủy quyền ở cấp phương thức sử dụng code: "FORBIDDEN" cấp cao nhất với chi tiết có cấu trúc về phạm vi còn thiếu:
  • Phạm vi còn thiếu: { code: "MISSING_SCOPE", missingScope, requiredScopes }. requiredScopes là tập hợp đầy đủ các phạm vi đã biết cho thao tác được yêu cầu. Thông báo missing scope: <scope> cũ được giữ lại cho các máy khách cũ hơn.
Máy khách nên đọc details trước và chỉ sử dụng thông báo cũ làm phương án dự phòng tương thích. readMissingScopeError và readMissingScopeErrorDetails được xuất từ @openclaw/gateway-protocol/gateway-error-details; máy khách Gateway an toàn cho trình duyệt tái xuất chúng từ @openclaw/gateway-client/browser. Các schema được xuất dưới dạng GatewayErrorDetailsSchema, MissingScopeErrorDetailsSchema từ @openclaw/gateway-protocol/schema. Lỗi phạm vi HTTP phản ánh đối tượng MISSING_SCOPE bên dưới error.details và sử dụng trạng thái HTTP 403. Các phương thức gây tác dụng phụ yêu cầu khóa idempotency (xem schema).

​
Bắt tay

Gateway gửi một thử thách trước khi kết nối:
Máy khách phản hồi bằng connect:
Gateway phản hồi bằng hello-ok:
server, features, snapshot, policy và auth đều được HelloOkSchema (packages/gateway-protocol/src/schema/frames.ts) yêu cầu. auth báo cáo vai trò/phạm vi đã thương lượng ngay cả khi không cấp token thiết bị (dạng ở trên). pluginSurfaceUrls là tùy chọn và ánh xạ tên bề mặt Plugin (ví dụ: canvas) đến các URL được lưu trữ có giới hạn phạm vi; mục này có thể hết hạn, vì vậy các node gọi node.pluginSurface.refresh với { "surface": "canvas" } để lấy mục mới. Đường dẫn canvasHostUrl / canvasCapability / node.canvas.capability.refresh đã lỗi thời không được hỗ trợ; hãy sử dụng các bề mặt Plugin. appliedConfigHash tùy chọn của snapshot là bản sửa đổi cấu hình nguồn đã phân giải được runtime Gateway đang hoạt động chấp nhận. Máy khách có thể so sánh giá trị đó với config.get.configRevisionHash để xác định liệu một cấu hình mới hơn đã lưu có còn cần khởi động lại hay không. config.get.hash vẫn là bản sửa đổi tệp gốc thô được các cơ chế bảo vệ xung đột ghi cấu hình sử dụng. Trong khi gateway vẫn đang hoàn tất các sidecar khởi động, connect có thể trả về lỗi UNAVAILABLE có thể thử lại với details.reason: "startup-sidecars" và retryAfterMs. Hãy thử lại trong ngân sách kết nối thay vì coi đây là lỗi bắt tay kết thúc. Khi token thiết bị được cấp, hello-ok.auth thêm token đó:
Cơ chế khởi tạo tích hợp bằng mã QR/mã thiết lập là một đường dẫn bàn giao cho thiết bị di động. Một kết nối mã thiết lập cơ sở thành công trả về một token node chính cùng với một token vận hành có giới hạn:
Việc bàn giao cho bên vận hành này được giới hạn có chủ đích: đủ để khởi động vòng lặp vận hành trên thiết bị di động và thiết lập gốc, bao gồm operator.talk.secrets để đọc cấu hình Talk, nhưng không có phạm vi thay đổi ghép nối và không có operator.admin. Quyền truy cập ghép nối/quản trị rộng hơn cần một luồng ghép nối hoặc token được phê duyệt riêng. Chỉ duy trì hello-ok.auth.deviceTokens khi xác thực khởi tạo chạy qua một phương thức truyền tải đáng tin cậy (wss:// hoặc ghép nối loopback/cục bộ). Các máy khách backend cùng tiến trình đáng tin cậy (client.id: "gateway-client", client.mode: "backend") có thể bỏ qua device trên các kết nối loopback trực tiếp khi xác thực bằng token/mật khẩu Gateway dùng chung. Đường dẫn này chỉ dành riêng cho các RPC mặt phẳng điều khiển nội bộ (ví dụ: cập nhật phiên tác nhân phụ) và tránh việc đường cơ sở ghép nối CLI/thiết bị cũ chặn công việc backend cục bộ. Các máy khách từ xa, có nguồn gốc trình duyệt, node và máy khách sử dụng rõ ràng token thiết bị/danh tính thiết bị vẫn phải trải qua quy trình kiểm tra ghép nối và nâng cấp phạm vi thông thường.

​
Vai trò worker và giao thức đóng

Worker đám mây sử dụng một cổng vào loopback chuyên dụng qua đường hầm SSH do Gateway sở hữu và ghim khóa máy chủ. Cổng này chỉ chấp nhận danh tính worker và tuyệt đối không điều phối xác thực chung, sự kiện node, RPC vận hành hoặc phương thức Plugin. Một connect nghiêm ngặt xác minh thông tin xác thực ngắn hạn, được băm khi lưu trữ, gắn với môi trường, hàm băm bundle, epoch chủ sở hữu, phiên bản tập RPC, thời hạn và một phiên có thể null; nó kiểm tra riêng phiên bản và tập tính năng hiện tại. Thành công trả về worker-hello-ok tối thiểu; thương lượng tính năng độc lập với phiên bản giao thức chung. Các frame luôn dưới 64 KiB, ngoại trừ frame worker.inference.start đã thương lượng có thể lên đến 25 MiB. Danh sách cho phép đóng chứa worker.heartbeat, worker.transcript.commit, worker.live-event, worker.inference.start và worker.inference.cancel. Các lần commit bản chép lời sử dụng hàng rào epoch chủ sở hữu, liên kết phiên do Gateway sở hữu, cơ chế so sánh-và-hoán đổi lá cơ sở và phát lại chuỗi bền vững; Gateway tạo ID mục bản chép lời và ID cha thông qua trình ghi phiên thông thường. Quyền sở hữu và thời hạn được kiểm tra lại trên mỗi RPC.

​
Khả năng của máy khách

Máy khách vận hành có thể quảng bá các khả năng tùy chọn trong connect.params.caps:
  • tool-events: chấp nhận các sự kiện vòng đời công cụ có cấu trúc.
  • inline-widgets: có thể hiển thị kết quả công cụ tiện ích nội tuyến được lưu trữ.
Khả năng của máy khách mô tả máy khách đang kết nối, không phải quyền hạn. Công cụ tác nhân có thể khai báo các khả năng bắt buộc; Gateway bỏ qua các công cụ đó trừ khi mọi yêu cầu đều xuất hiện trong caps của máy khách khởi nguồn. Các lượt chạy bắt nguồn từ kênh không có khả năng máy khách Gateway, vì vậy các công cụ bị giới hạn theo khả năng không khả dụng ngay cả khi chính sách công cụ cho phép chúng một cách rõ ràng.

​
Ví dụ kết nối node

Các node khai báo tuyên bố khả năng tại thời điểm kết nối:
  • caps: các danh mục cấp cao như camera, canvas, screen, location, voice, talk.
  • commands: danh sách lệnh được phép gọi.
  • permissions: các nút bật/tắt chi tiết (ví dụ: screen.record, camera.capture).
Gateway coi đây là các tuyên bố và thực thi danh sách cho phép ở phía máy chủ.

​
Vai trò và phạm vi

Để xem đầy đủ mô hình phạm vi vận hành, các bước kiểm tra tại thời điểm phê duyệt và ngữ nghĩa bí mật dùng chung, hãy xem Phạm vi vận hành. Vai trò:
  • operator: máy khách mặt phẳng điều khiển (CLI/giao diện người dùng/tự động hóa).
  • node: máy chủ khả năng (camera/màn hình/canvas/system.run).
  • worker: máy chủ thực thi đám mây trên giao thức worker chuyên dụng, đóng.
Các phạm vi vận hành (src/gateway/operator-scopes.ts), tập hợp đóng đầy đủ:
  • operator.read
  • operator.write
  • operator.admin
  • operator.approvals
  • operator.pairing
  • operator.talk.secrets
talk.config với includeSecrets: true yêu cầu operator.talk.secrets (hoặc operator.admin). Khi bao gồm bí mật, hãy đọc thông tin xác thực của nhà cung cấp Talk đang hoạt động từ talk.resolved.config.apiKey; talk.providers.<id>.apiKey giữ nguyên dạng nguồn và có thể là một đối tượng SecretRef hoặc chuỗi đã che. Các phương thức RPC Gateway do Plugin đăng ký có thể yêu cầu phạm vi vận hành riêng, nhưng các tiền tố lõi dành riêng này luôn phân giải thành operator.admin (src/shared/gateway-method-policy.ts): config.*, exec.approvals.*, wizard.*, update.*. Phạm vi phương thức chỉ là cổng kiểm tra đầu tiên. Một số lệnh gạch chéo được truy cập qua chat.send áp dụng các bước kiểm tra nghiêm ngặt hơn ở cấp lệnh: các thao tác ghi /config set và /config unset bền vững yêu cầu operator.admin, ngay cả đối với máy khách Gateway đã có phạm vi vận hành thấp hơn. node.pair.approve có thêm một bước kiểm tra phạm vi tại thời điểm phê duyệt bên cạnh phạm vi phương thức cơ sở (operator.pairing), dựa trên commands (src/infra/node-pairing-authz.ts) được khai báo trong yêu cầu đang chờ xử lý:

​
Khả năng/lệnh/quyền (Node)

Các Node khai báo các xác nhận về khả năng tại thời điểm kết nối:
  • caps: các danh mục khả năng cấp cao như camera, canvas, screen, location, voice và talk.
  • commands: danh sách lệnh được phép gọi.
  • permissions: các tùy chọn bật/tắt chi tiết (ví dụ: screen.record, camera.capture).
Gateway coi đây là các xác nhận và thực thi danh sách cho phép ở phía máy chủ. Sau khi kết nối hoặc kết nối lại thành công, các Node đã kết nối có thể công bố những bộ mô tả Plugin hoặc công cụ MCP tùy chọn mà agent có thể thấy bằng node.pluginTools.update. Máy chủ Node không có giao diện sẽ khởi động lại để áp dụng các thay đổi khai báo đối với danh mục MCP. Phương thức cập nhật này là đường công bố duy nhất; các bộ mô tả công cụ Plugin không được chấp nhận trong tham số connect. Mỗi bộ mô tả phải sử dụng name của công cụ an toàn cho nhà cung cấp và chỉ định một command trong danh sách lệnh hiện tại được phép của Node. Gateway tin cậy siêu dữ liệu bộ mô tả từ Node đã ghép cặp, lọc các bộ mô tả nằm ngoài bề mặt lệnh đã phê duyệt, loại bỏ chúng khi Node ngắt kết nối và từ chối các nỗ lực của người vận hành nhằm sửa đổi danh mục của Node khác. Đặt gateway.nodes.pluginTools.enabled: false để bỏ qua các bộ mô tả do Node công bố. Các máy chủ Node đã kết nối công bố danh mục thay thế Skills hoàn chỉnh bằng node.skills.update. Phương thức dành cho vai trò Node này là đường công bố Skills duy nhất của Node; Skills không được chấp nhận trong tham số connect. Mỗi bộ mô tả chứa tên an toàn, mô tả và nội dung SKILL.md có giới hạn. Gateway phân tích nội dung đó bằng trình tải Skills thông thường, đưa nội dung vào các bản chụp Skills của agent trong khi Node được kết nối và loại bỏ khi ngắt kết nối. Đặt gateway.nodes.skills.enabled: false để bỏ qua Skills do Node công bố.

​
Trạng thái hiện diện

  • system-presence trả về các mục được định khóa theo danh tính thiết bị, bao gồm deviceId, roles và scopes, để giao diện người dùng có thể hiển thị một hàng cho mỗi thiết bị ngay cả khi thiết bị kết nối với cả vai trò người vận hành và Node.
  • node.list bao gồm lastSeenAtMs và lastSeenReason tùy chọn. Các Node đã kết nối báo cáo thời gian kết nối hiện tại với lý do connect; các Node đã ghép cặp cũng có thể báo cáo trạng thái hiện diện nền lâu dài thông qua một sự kiện Node đáng tin cậy.
Các Node macOS gốc cũng có thể gửi sự kiện node.presence.activity đã xác thực với thời gian đầu vào không hoạt động có giới hạn. Gateway tự suy ra dấu thời gian hoạt động theo đồng hồ của mình, cung cấp máy Mac được kết nối gần đây nhất thông qua node.list và node.describe, đồng thời phát các bản cập nhật node.presence tới những máy khách có phạm vi đọc. Xem Trạng thái hiện diện của máy tính đang hoạt động để biết hành vi lựa chọn, quyền riêng tư, ngữ cảnh mô hình và định tuyến thông báo.

​
Sự kiện Node còn hoạt động trong nền

Các Node gọi node.event với event: "node.presence.alive" để ghi nhận rằng một Node đã ghép cặp vẫn hoạt động trong một lần đánh thức nền mà không đánh dấu Node đó là đang kết nối:
trigger là một enum đóng: background, silent_push, bg_app_refresh, significant_location, manual, connect. Các giá trị không xác định được chuẩn hóa thành background (src/shared/node-presence.ts). Sự kiện chỉ được lưu lâu dài cho các phiên thiết bị Node đã xác thực; các phiên không có thiết bị hoặc chưa ghép cặp trả về handled: false. Các Gateway xử lý thành công trả về kết quả có cấu trúc:
Các Gateway cũ hơn có thể chỉ trả về { "ok": true } cho node.event; hãy coi đó là một RPC đã được xác nhận, không phải việc lưu trạng thái hiện diện lâu dài.

​
Xác định phạm vi sự kiện phát rộng

Các sự kiện phát rộng do máy chủ đẩy được kiểm soát theo phạm vi để các phiên chỉ có phạm vi ghép cặp hoặc chỉ dành cho Node không thụ động nhận nội dung phiên (src/gateway/server-broadcast.ts):
  • Các khung trò chuyện, agent và kết quả công cụ (các sự kiện agent được truyền phát, sự kiện kết quả công cụ) yêu cầu ít nhất operator.read. Các phiên không có phạm vi này sẽ bỏ qua hoàn toàn các khung đó.
  • Các sự kiện phát rộng plugin.* do Plugin xác định mặc định bị giới hạn ở operator.write hoặc operator.admin; các mục tường minh như plugin.approval.requested / plugin.approval.resolved sử dụng operator.approvals thay thế.
  • Các sự kiện trạng thái/vận chuyển (heartbeat, presence, tick, vòng đời kết nối/ngắt kết nối) vẫn không bị hạn chế để mọi phiên đã xác thực đều có thể quan sát tình trạng vận chuyển.
  • Các họ sự kiện phát rộng không xác định mặc định bị giới hạn theo phạm vi (đóng khi lỗi), trừ khi một trình xử lý đã đăng ký nới lỏng chúng một cách tường minh.
Mỗi kết nối máy khách duy trì số thứ tự riêng theo từng máy khách, do đó các sự kiện phát rộng vẫn được sắp xếp tăng dần trên socket đó ngay cả khi các máy khách khác nhau nhìn thấy những tập con khác nhau của luồng sự kiện sau khi lọc theo phạm vi.

​
Các họ phương thức RPC

hello-ok.features.methods là danh sách khám phá thận trọng được xây dựng từ src/gateway/server-methods-list.ts cùng với các phương thức được xuất bởi Plugin/kênh đã tải — đây không phải bản kết xuất được tạo tự động của mọi phương thức, và một số phương thức (ví dụ: push.test, web.login.start, web.login.wait, sessions.usage) được chủ ý loại khỏi khả năng khám phá dù chúng là các phương thức thực sự có thể gọi. Hãy coi đây là khả năng khám phá tính năng, không phải danh sách đầy đủ của src/gateway/server-methods/*.ts.
  • health trả về bản chụp tình trạng Gateway từ bộ nhớ đệm hoặc vừa được thăm dò.
  • diagnostics.stability trả về bộ ghi độ ổn định chẩn đoán gần đây có giới hạn: tên sự kiện, số lượng, kích thước byte, số liệu bộ nhớ, trạng thái hàng đợi/phiên, tên kênh/Plugin và mã định danh phiên. Không bao gồm văn bản trò chuyện, phần thân Webhook, đầu ra công cụ, phần thân yêu cầu/phản hồi thô, token, cookie hoặc bí mật. Yêu cầu operator.read.
  • status trả về bản tóm tắt Gateway kiểu /status; các trường nhạy cảm chỉ dành cho máy khách vận hành có phạm vi quản trị.
  • gateway.identity.get trả về danh tính thiết bị Gateway được các luồng chuyển tiếp và ghép cặp sử dụng.
  • system-presence trả về bản chụp trạng thái hiện diện hiện tại của các thiết bị người vận hành/Node đã kết nối.
  • system-event nối thêm một sự kiện hệ thống và có thể cập nhật/phát rộng ngữ cảnh trạng thái hiện diện.
  • last-heartbeat trả về sự kiện Heartbeat mới nhất đã được lưu lâu dài.
  • set-heartbeats bật/tắt việc xử lý Heartbeat trên Gateway.
  • gateway.suspend.prepare chỉ tạo một hợp đồng tạm ngừng hợp tác ngắn hạn khi công việc Gateway đang được theo dõi ở trạng thái rảnh. gateway.suspend.status kiểm tra hợp đồng đó và gateway.suspend.resume giải phóng hợp đồng sau khi hoạt động trở lại hoặc thao tác máy chủ bị hủy.
  • models.list trả về danh mục mô hình được runtime cho phép. Xem “các chế độ xem models.list” bên dưới.
  • usage.status trả về bản tóm tắt các khoảng thời gian sử dụng/hạn mức còn lại của nhà cung cấp.
  • usage.cost trả về bản tóm tắt tổng hợp mức sử dụng chi phí trong một khoảng ngày. Truyền agentId cho một agent hoặc agentScope: "all" để tổng hợp các agent đã cấu hình.
  • doctor.memory.status trả về trạng thái sẵn sàng của bộ nhớ vector / embedding đã lưu trong bộ nhớ đệm cho không gian làm việc của agent mặc định đang hoạt động. Chỉ truyền { "probe": true } hoặc { "deep": true } để ping trực tiếp một nhà cung cấp embedding cụ thể. Truyền { "agentId": "agent-id" } để giới hạn thống kê kho Dreaming ở một không gian làm việc của agent; nếu bỏ qua, các không gian làm việc Dreaming đã cấu hình sẽ được tổng hợp.
  • doctor.memory.dreamDiary, doctor.memory.backfillDreamDiary, doctor.memory.resetDreamDiary, doctor.memory.resetGroundedShortTerm, doctor.memory.repairDreamingArtifacts và doctor.memory.dedupeDreamDiary chấp nhận { "agentId": "agent-id" } tùy chọn; nếu bỏ qua, chúng hoạt động trên không gian làm việc của agent mặc định đã cấu hình.
  • doctor.memory.remHarness trả về bản xem trước bộ kiểm thử REM chỉ đọc, có giới hạn dành cho các máy khách mặt phẳng điều khiển từ xa, bao gồm đường dẫn không gian làm việc, đoạn trích bộ nhớ, Markdown có căn cứ đã kết xuất và các ứng viên thăng hạng sâu. Yêu cầu operator.read.
  • sessions.usage trả về bản tóm tắt mức sử dụng theo từng phiên. Truyền agentId cho một agent hoặc agentScope: "all" để liệt kê các agent đã cấu hình cùng nhau. Cả hai phương thức mức sử dụng đều chấp nhận mode: "specific" với timeZone IANA để xác định ranh giới và nhóm ngày theo lịch có tính đến DST. utcOffset vẫn được hỗ trợ cho các máy khách cũ hơn và làm phương án dự phòng khi runtime Gateway không nhận dạng múi giờ được yêu cầu.
  • sessions.usage.timeseries trả về mức sử dụng chuỗi thời gian cho một phiên.
  • sessions.usage.logs trả về các mục nhật ký mức sử dụng cho một phiên.
  • channels.status trả về bản tóm tắt trạng thái của các kênh/Plugin tích hợp sẵn + đi kèm.
  • channels.logout đăng xuất khỏi một kênh/tài khoản cụ thể nếu kênh hỗ trợ.
  • web.login.start bắt đầu luồng đăng nhập bằng QR/web cho nhà cung cấp kênh web hiện tại có hỗ trợ QR.
  • web.login.wait chờ luồng đó hoàn tất và khởi động kênh khi thành công.
  • push.test gửi thông báo đẩy APNs thử nghiệm tới một Node iOS đã đăng ký.
  • voicewake.get trả về các cụm từ kích hoạt đánh thức đã lưu.
  • voicewake.set cập nhật các cụm từ kích hoạt đánh thức và phát rộng thay đổi.
  • plugins.list (operator.read) trả về danh mục Plugin đã cài đặt cùng các lựa chọn chính thức được tuyển chọn cục bộ, thông tin chẩn đoán và trạng thái liệu chế độ cài đặt hiện tại có cho phép sửa đổi hay không.
  • plugins.search (operator.read) tìm kiếm các họ Plugin mã và Plugin gói có thể cài đặt trên ClawHub. Truyền query không rỗng và limit tùy chọn từ 1 đến 100.
  • plugins.install (operator.admin) cài đặt một mục danh mục chính thức bằng { source: "official", pluginId } hoặc một gói ClawHub bằng { source: "clawhub", packageName, version?, acknowledgeClawHubRisk? }. Các bản cài đặt ClawHub duy trì các bước kiểm tra về độ tin cậy, tính toàn vẹn và chính sách cài đặt của Gateway. Các bản cài đặt thành công yêu cầu khởi động lại Gateway.
  • plugins.setEnabled (operator.admin) thay đổi chính sách bật của một Plugin đã cài đặt bằng { pluginId, enabled }. Phản hồi bao gồm mục danh mục đã cập nhật, siêu dữ liệu khởi động lại và mọi cảnh báo lựa chọn vị trí.
  • plugins.uninstall (operator.admin) xóa một Plugin được cài đặt bên ngoài bằng { pluginId }: các tham chiếu cấu hình, bản ghi cài đặt và tệp được quản lý. Không thể gỡ cài đặt Plugin đi kèm, chỉ có thể tắt. Phản hồi liệt kê các thao tác xóa và luôn yêu cầu khởi động lại Gateway.
  • send là RPC gửi đi trực tiếp cho các lượt gửi nhắm đến kênh/tài khoản/luồng bên ngoài trình chạy trò chuyện.
  • logs.tail trả về phần đuôi nhật ký tệp Gateway đã cấu hình, với các điều khiển con trỏ/giới hạn và số byte tối đa.
  • terminal.open khởi chạy một PTY máy chủ cho agentId được chỉ định rõ hoặc tác tử mặc định, rồi trả về tác tử đã phân giải, thư mục làm việc, shell và trạng thái cô lập.
  • terminal.input, terminal.resize và terminal.close chỉ thao tác trên các phiên thuộc sở hữu của kết nối gọi.
  • terminal.upload chấp nhận một tệp base64 có kích thước tối đa 16 MiB, đưa tệp vào một thư mục tạm thời riêng tư tồn tại 24 giờ trên Gateway của phiên hoặc máy chủ Node đã ghép cặp, rồi trả về đường dẫn tuyệt đối. Bên gọi vẫn phải dán hoặc sử dụng đường dẫn đó theo cách khác; RPC không bao giờ ghi dữ liệu đầu vào vào thiết bị đầu cuối hoặc thực thi lệnh.
  • Các sự kiện terminal.data và terminal.exit chỉ được truyền trực tuyến đến kết nối sở hữu phiên.
  • Các phiên bị mất kết nối sẽ được tách ra thay vì bị kết thúc: chúng vẫn có thể được gắn lại trong gateway.terminal.detachedSessionTimeoutSeconds (mặc định 300; 0 khôi phục hành vi kết thúc khi ngắt kết nối), trong khi đầu ra gần đây tích lũy trong bộ đệm phía máy chủ có giới hạn.
  • terminal.list trả về các phiên có thể gắn; terminal.attach liên kết lại một phiên đang hoạt động hoặc đã tách với kết nối gọi và trả về bộ đệm phát lại (tiếp quản kiểu tmux — chủ sở hữu đang hoạt động trước đó nhận được terminal.exit với lý do detached); terminal.text đọc bộ đệm dưới dạng văn bản thuần túy mà không gắn vào.
  • Mọi phương thức thiết bị đầu cuối đều yêu cầu operator.admin; gateway.terminal.enabled phải được đặt rõ ràng thành true. Các tác tử được sandbox hoàn toàn sẽ bị từ chối, và thay đổi chính sách tác tử sẽ đóng các PTY hiện có và đang được khởi tạo, bao gồm cả các PTY đã tách.
  • talk.catalog trả về danh mục nhà cung cấp Talk chỉ đọc cho giọng nói, phiên âm trực tuyến và thoại thời gian thực: mã định danh nhà cung cấp chuẩn, bí danh registry, nhãn, trạng thái cấu hình, kết quả ready tùy chọn ở cấp nhóm, mã định danh mô hình/giọng nói được công khai, chế độ chuẩn, phương thức truyền tải, chiến lược bộ não và các cờ âm thanh/khả năng thời gian thực, mà không trả về bí mật của nhà cung cấp hoặc thay đổi cấu hình toàn cục. Các Gateway hiện tại đặt ready sau khi áp dụng lựa chọn nhà cung cấp lúc chạy; trên các Gateway cũ hơn, hãy xem việc thiếu trường này là chưa được xác minh.
  • talk.config trả về payload cấu hình Talk có hiệu lực; includeSecrets yêu cầu operator.talk.secrets (hoặc operator.admin).
  • talk.session.create tạo một phiên Talk do Gateway sở hữu cho realtime/gateway-relay, transcription/gateway-relay hoặc stt-tts/managed-room. Đối với stt-tts/managed-room, bên gọi operator.write truyền sessionKey cũng phải truyền spawnedBy để giới hạn phạm vi hiển thị khóa phiên; việc tạo sessionKey không giới hạn phạm vi và brain: "direct-tools" yêu cầu operator.admin.
  • talk.session.join xác thực token phiên phòng được quản lý, phát session.ready hoặc session.replaced khi cần, rồi trả về siêu dữ liệu phòng/phiên cùng các sự kiện Talk gần đây, nhưng không bao giờ trả về token dạng văn bản thuần túy hoặc hàm băm của token.
  • talk.session.appendAudio nối thêm âm thanh đầu vào PCM dạng base64 vào các phiên chuyển tiếp thời gian thực và phiên âm do Gateway sở hữu.
  • talk.session.startTurn, talk.session.endTurn và talk.session.cancelTurn điều khiển vòng đời lượt của phòng được quản lý, đồng thời từ chối lượt cũ trước khi xóa trạng thái.
  • talk.session.cancelOutput dừng đầu ra âm thanh của trợ lý, chủ yếu để cho phép ngắt lời được kiểm soát bằng VAD trong các phiên chuyển tiếp Gateway.
  • talk.session.submitToolResult hoàn tất một lệnh gọi công cụ của nhà cung cấp do phiên chuyển tiếp thời gian thực thuộc sở hữu của Gateway phát ra. Yêu cầu chờ mọi tín hiệu hoàn tất bất đồng bộ do cầu nối nhà cung cấp cung cấp; các lần gửi thất bại giữ lượt chạy được liên kết ở trạng thái hoạt động và không phát sự kiện kết quả công cụ thành công. Truyền options: { willContinue: true } cho đầu ra công cụ tạm thời hoặc options: { suppressResponse: true } khi cầu nối nhà cung cấp công bố khả năng hỗ trợ chặn và kết quả không nên khởi tạo phản hồi khác.
  • talk.session.steer gửi điều khiển bằng giọng nói cho lượt chạy đang hoạt động vào một phiên Talk dựa trên tác tử do Gateway sở hữu: { sessionId, text, mode? }, trong đó mode là status, steer, cancel hoặc followup; nếu bỏ qua chế độ, chế độ sẽ được phân loại từ văn bản nói.
  • talk.session.close đóng một phiên chuyển tiếp, phiên âm hoặc phòng được quản lý do Gateway sở hữu và phát các sự kiện Talk kết thúc.
  • talk.mode đặt/phát sóng trạng thái chế độ Talk hiện tại cho các máy khách WebChat/Control UI.
  • talk.client.create tạo hoặc tiếp tục một phiên nhà cung cấp thời gian thực do máy khách sở hữu bằng webrtc hoặc provider-websocket, trong khi Gateway sở hữu thông tin xác thực, chỉ dẫn, chính sách công cụ và voiceSessionId được trả về. Máy khách truyền sessionKey và tái sử dụng voiceSessionId khi thay thế phương thức truyền tải của nhà cung cấp trong một cuộc gọi.
  • talk.client.transcript nối thêm một mục { role, text } đã hoàn tất vào phiên tác tử thông thường. entryId bắt buộc có tính lũy đẳng trong voiceSessionId; việc thử lại không tạo bản sao thông điệp bản chép lời.
  • talk.client.close đóng phiên thoại logic sau khi hoàn tất các lượt ghi bản chép lời đang chờ. Thao tác đóng có tính lũy đẳng và có thể gửi bản tóm tắt cuộc gọi chỉ chứa thay đổi đến kênh không phải WebChat gần nhất của phiên.
  • talk.client.toolCall cho phép các phương thức truyền tải thời gian thực do máy khách sở hữu chuyển tiếp lệnh gọi công cụ của nhà cung cấp đến chính sách Gateway. Công cụ được hỗ trợ đầu tiên là openclaw_agent_consult; máy khách nhận mã định danh lượt chạy và chờ các sự kiện vòng đời trò chuyện thông thường trước khi gửi kết quả công cụ dành riêng cho nhà cung cấp. Các hành động có tác động lớn gắn với giọng nói trả về VOICE_CONFIRMATION_REQUIRED:<id> cho đến khi một phát ngôn hoàn chỉnh sau đó của người dùng xác nhận rõ ràng chính xác hành động đó và lần tham vấn tiếp theo cung cấp confirmationId.
  • talk.client.steer gửi điều khiển bằng giọng nói cho lượt chạy đang hoạt động đối với các phương thức truyền tải thời gian thực do máy khách sở hữu. Gateway phân giải lượt chạy nhúng đang hoạt động từ sessionKey và trả về kết quả chấp nhận/từ chối có cấu trúc thay vì âm thầm bỏ qua chỉ dẫn.
  • talk.event là kênh sự kiện Talk duy nhất cho các bộ điều hợp thời gian thực, phiên âm, STT/TTS, phòng được quản lý, điện thoại và cuộc họp.
  • talk.speak tổng hợp giọng nói thông qua nhà cung cấp giọng nói Talk đang hoạt động.
  • tts.status trả về trạng thái bật TTS, nhà cung cấp đang hoạt động, các nhà cung cấp dự phòng và trạng thái cấu hình nhà cung cấp.
  • tts.providers trả về danh mục nhà cung cấp TTS hiển thị được.
  • tts.enable và tts.disable bật/tắt trạng thái tùy chọn TTS.
  • tts.setProvider cập nhật nhà cung cấp TTS ưu tiên.
  • tts.convert thực hiện một lần chuyển đổi văn bản thành giọng nói.
  • tts.speak (operator.write) kết xuất text không rỗng bằng chuỗi nhà cung cấp TTS chung đã cấu hình và trả về trực tiếp toàn bộ một đoạn âm thanh dưới dạng audioBase64, cùng với provider và siêu dữ liệu outputFormat, mimeType và fileExtension tùy chọn. Khác với tts.convert, phương thức này không trả về đường dẫn cục bộ của Gateway; khác với talk.speak, phương thức này không yêu cầu nhà cung cấp Talk. Văn bản vượt quá messages.tts.maxTextLength trả về INVALID_REQUEST; lỗi tổng hợp trả về UNAVAILABLE.
  • secrets.reload phân giải lại các SecretRef đang hoạt động và phát hành nguyên tử trạng thái lúc chạy có nhận biết chủ sở hữu. Các lỗi đủ điều kiện của chủ sở hữu có thể được phát hành dưới dạng suy giảm lạnh hoặc cũ với warningCount; các lỗi nghiêm ngặt hoặc chưa được ánh xạ sẽ từ chối tải lại và giữ nguyên ảnh chụp nhanh đang hoạt động.
  • secrets.resolve phân giải các phép gán bí mật cho đích lệnh đối với một tập hợp lệnh/đích cụ thể.
  • config.get trả về ảnh chụp nhanh cấu hình hiện tại trên đĩa, hash của tệp gốc thô, configRevisionHash đã phân giải và appliedConfigHash tùy chọn cho bản sửa đổi đã phân giải được môi trường chạy Gateway đang hoạt động chấp nhận.
  • config.set ghi một payload cấu hình đã được xác thực.
  • config.patch hợp nhất một bản cập nhật cấu hình một phần. Việc thay thế mảng có tính phá hủy yêu cầu đường dẫn bị ảnh hưởng trong replacePaths; các mảng lồng nhau dưới các phần tử mảng sử dụng đường dẫn [], chẳng hạn như agents.list[].skills.
  • config.apply xác thực và thay thế toàn bộ payload cấu hình.
  • config.schema trả về payload lược đồ cấu hình trực tiếp được Control UI và công cụ CLI sử dụng: lược đồ, uiHints, phiên bản, siêu dữ liệu tạo sinh, cùng siêu dữ liệu lược đồ Plugin và kênh khi có thể tải. Payload bao gồm siêu dữ liệu title / description từ cùng nhãn/văn bản trợ giúp như UI, bao gồm các nhánh kết hợp đối tượng lồng nhau, ký tự đại diện, phần tử mảng và anyOf / oneOf / allOf khi có tài liệu trường tương ứng.
  • config.schema.lookup trả về payload tra cứu giới hạn theo đường dẫn cho một đường dẫn cấu hình: đường dẫn đã chuẩn hóa, một Node lược đồ nông, gợi ý khớp cùng hintPath, reloadKind tùy chọn và các bản tóm tắt phần tử con trực tiếp để UI/CLI xem chi tiết. reloadKind là một trong restart, hot hoặc none (src/config/schema.ts) và phản ánh trình lập kế hoạch tải lại cấu hình Gateway cho đường dẫn được yêu cầu. Các Node lược đồ tra cứu giữ nguyên tài liệu hướng đến người dùng và các trường xác thực phổ biến (title, description, type, enum, const, format, pattern, giới hạn số/chuỗi/mảng/đối tượng, additionalProperties, deprecated, readOnly, writeOnly). Các bản tóm tắt phần tử con công khai key, path đã chuẩn hóa, type, required, hasChildren, reloadKind tùy chọn, cùng hint / hintPath đã khớp.
  • update.run chạy luồng cập nhật Gateway và chỉ lên lịch khởi động lại nếu cập nhật thành công; bên gọi có phiên có thể bao gồm continuationMessage để quá trình khởi động tiếp tục một lượt tác tử kế tiếp thông qua hàng đợi tiếp tục sau khi khởi động lại. Các bản cập nhật bằng trình quản lý gói và bản cập nhật checkout git được giám sát từ mặt phẳng điều khiển sử dụng cơ chế chuyển giao dịch vụ được quản lý đã tách thay vì thay thế cây gói hoặc thay đổi đầu ra checkout/bản dựng bên trong Gateway đang hoạt động. Một lượt chuyển giao đã bắt đầu trả về ok: true cùng result.reason: "managed-service-handoff-started" và handoff.status: "started". Một update.run đồng thời thứ hai do cùng tiến trình Gateway xử lý trả về ok: false cùng result.reason: "managed-service-handoff-already-running" và handoff.status: "already-running"; phần tiếp tục của nó không được chấp nhận, vì vậy bên gọi có thể thử lại sau khi bản cập nhật đang hoạt động hoàn tất. Các trình cập nhật CLI độc lập và tiến trình Gateway thay thế nằm ngoài cơ chế bảo vệ cục bộ theo tiến trình này. Các lượt chuyển giao không khả dụng hoặc thất bại trả về ok: false cùng managed-service-handoff-unavailable hoặc managed-service-handoff-failed, cộng thêm handoff.command khi cần cập nhật thủ công bằng shell. Không khả dụng có nghĩa là OpenClaw thiếu ranh giới trình giám sát an toàn hoặc danh tính dịch vụ bền vững, chẳng hạn như OPENCLAW_SYSTEMD_UNIT cho systemd. Trong một lượt chuyển giao đã bắt đầu, dấu hiệu khởi động lại có thể tạm thời báo stats.reason: "restart-health-pending"; phần tiếp tục bị trì hoãn cho đến khi CLI xác minh Gateway đã khởi động lại và ghi dấu hiệu ok cuối cùng.
  • update.status làm mới và trả về dấu hiệu khởi động lại do cập nhật mới nhất, bao gồm phiên bản đang chạy sau khi khởi động lại nếu có.
  • wizard.start, wizard.next, wizard.status và wizard.cancel cung cấp trình hướng dẫn thiết lập ban đầu qua WS RPC.
  • agents.list trả về các mục agent đã cấu hình, bao gồm siêu dữ liệu mô hình và runtime có hiệu lực.
  • agents.create, agents.update và agents.delete quản lý các bản ghi agent và liên kết workspace.
  • agents.files.list, agents.files.get và agents.files.set quản lý các tệp workspace khởi tạo được cung cấp cho một agent.
  • audit.activity.list trả về sổ cái hoạt động chỉ chứa siêu dữ liệu và có phiên bản; audit.list vẫn là RPC chạy/công cụ an toàn về khả năng tương thích.
  • agents.workspace.list và agents.workspace.get (operator.read) cung cấp khả năng duyệt phân trang, chỉ đọc đối với thư mục workspace của agent cho các máy khách thuộc miền người vận hành đáng tin cậy được mô tả trong Phạm vi người vận hành. Yêu cầu chỉ chấp nhận đường dẫn tương đối với workspace; thao tác đọc luôn bị giới hạn trong thư mục gốc workspace đã được phân giải thành đường dẫn thực (từ chối thoát qua liên kết tượng trưng và liên kết cứng), bị giới hạn kích thước và chỉ hỗ trợ văn bản UTF-8 cùng các loại hình ảnh phổ biến (base64). Phản hồi không tiết lộ đường dẫn workspace trên máy chủ. Không có thao tác ghi nào trong namespace này.
  • tasks.list, tasks.get và tasks.cancel cung cấp sổ cái tác vụ của Gateway cho SDK và máy khách người vận hành. Xem Các RPC của sổ cái tác vụ bên dưới.
  • artifacts.list, artifacts.get và artifacts.download cung cấp bản tóm tắt và nội dung tải xuống của các hiện vật bắt nguồn từ bản chép lời cho một phạm vi sessionKey, runId hoặc taskId được chỉ định rõ ràng. Các truy vấn lượt chạy và tác vụ phân giải phiên sở hữu ở phía máy chủ và chỉ trả về nội dung phương tiện trong bản chép lời có nguồn gốc khớp; các nguồn URL không an toàn hoặc cục bộ trả về nội dung tải xuống không được hỗ trợ thay vì được máy chủ tìm nạp.
  • environments.list và environments.status duy trì khả năng khám phá môi trường cục bộ của Gateway và Node. Các worker đám mây đã cấu hình và bản ghi bền vững do những hồ sơ trước đó để lại bổ sung siêu dữ liệu worker với providerId, leaseId tùy chọn, state, ageMs, idleMs tùy chọn và attachedSessionIds. Các trạng thái vòng đời của worker là requested, provisioning, bootstrapping, ready, attached, idle, draining, destroying, destroyed, failed và orphaned.
  • environments.create ({ profileId, idempotencyKey }) cấp phát một worker từ hồ sơ nhà cung cấp Plugin đã cấu hình; các lần thử lại với cùng khóa sẽ tái sử dụng thao tác bền vững. environments.destroy ({ environmentId }) yêu cầu tháo dỡ môi trường worker bền vững theo cách lũy đẳng. Cả hai đều yêu cầu operator.admin, là thao tác ghi trên mặt phẳng điều khiển và trả về cùng cấu trúc tóm tắt môi trường được dùng trong phản hồi trạng thái.
  • agent.identity.get trả về danh tính trợ lý có hiệu lực cho một agent hoặc phiên.
  • agent.wait chờ một lượt chạy hoàn tất và trả về ảnh chụp trạng thái kết thúc khi có.
  • sessions.list trả về chỉ mục phiên hiện tại, bao gồm siêu dữ liệu agentRuntime theo từng hàng khi đã cấu hình backend runtime cho agent. Khi tính năng bố trí worker đám mây được bật hoặc tồn tại trạng thái khôi phục bền vững, các hàng phiên cũng bao gồm trạng thái placement đóng (local, requested, provisioning, syncing, starting, active, draining, reconciling, reclaimed hoặc failed) cùng các trường dành riêng cho trạng thái về môi trường, epoch của chủ sở hữu, workspace, gói, con trỏ ACK hoặc khôi phục.
  • sessions.subscribe và sessions.unsubscribe bật hoặc tắt đăng ký sự kiện thay đổi phiên cho máy khách WS hiện tại.
  • sessions.messages.subscribe và sessions.messages.unsubscribe bật hoặc tắt đăng ký sự kiện bản chép lời/tin nhắn cho một phiên. Truyền includeApprovals: true để cũng nhận các sự kiện vòng đời session.approval đã được làm sạch cho những phê duyệt có đối tượng được lưu trữ bao gồm chính xác phiên đó và có ràng buộc người review cho phép máy khách đăng ký. Khi đó, phản hồi đăng ký sẽ bao gồm approvalReplay đang chờ có giới hạn; đây là dữ liệu có thẩm quyền khi truncated là false. Việc chọn tham gia áp dụng cho từng lệnh gọi đăng ký và không được duy trì: đăng ký lại cùng một phiên mà không có includeApprovals: true sẽ xóa đăng ký phê duyệt hiện có. Ngoài quyền đọc phiên thông thường, việc chọn tham gia này yêu cầu operator.admin hoặc operator.approvals trên thiết bị đã ghép đôi.
  • sessions.preview trả về bản xem trước bản chép lời có giới hạn cho các khóa phiên cụ thể.
  • sessions.describe trả về một hàng phiên Gateway cho một khóa phiên chính xác.
  • sessions.resolve phân giải hoặc chuẩn hóa một đích phiên.
  • sessions.create tạo một mục phiên mới. Các giá trị model và thinkingLevel tùy chọn lưu trữ nguyên tử các ghi đè ban đầu về mô hình và suy luận. worktree: true cấp phát một worktree được quản lý; worktreeBaseRef/worktreeName tùy chọn chọn ref cơ sở và tên nhánh, còn execNode (operator.admin) ràng buộc việc thực thi phiên với một máy chủ Node. Worktree đã tạo được trả lại trong kết quả và lưu trữ trên hàng phiên (worktree: { id, branch, repoRoot }). Khi mục được tạo nhưng chat.send ban đầu lồng bên trong bị từ chối, kết quả thành công sẽ bao gồm runStarted: false và runError; máy khách có thể giữ lại lời nhắc và thử lại với khóa phiên được trả về. Bên gọi truyền parentSessionKey cùng emitCommandHooks: true cũng nên khai báo cách xử lý vòng đời của một phiên con riêng biệt: succeedsParent: true kết thúc phiên cha với session_end, trong khi false giữ phiên cha hoạt động và chỉ phát session_start của phiên con. Việc bỏ qua succeedsParent duy trì hành vi chuyển tiếp phiên cha kiểu cũ cho các máy khách hiện có. Cách xử lý này yêu cầu cả liên kết cha và các hook lệnh; một bản fork không thể đánh dấu phiên cha là thành công. Hành vi đặt lại tại chỗ của phiên chính không thay đổi vì không có phiên con riêng biệt nào được tạo.
  • sessions.dispatch (operator.admin) chuyển một phiên OpenClaw cục bộ hiện có với worktree được quản lý thuộc sở hữu của phiên sang một hồ sơ worker đám mây đã cấu hình. Truyền { key, profileId, agentId? }. Phương thức này không tồn tại khi chưa cấu hình hồ sơ worker, đóng khả năng tiếp nhận lượt cục bộ trước khi chờ công việc đang hoạt động hoàn tất và chỉ trả về sau khi việc bố trí đạt quyền sở hữu worker active. Việc điều phối chỉ theo một chiều; kéo ngược từ worker về cục bộ không thuộc RPC này.
  • sessions.groups.list, sessions.groups.put, sessions.groups.rename và sessions.groups.delete quản lý danh mục nhóm phiên tùy chỉnh do Gateway sở hữu (tên + thứ tự hiển thị). Tư cách thành viên vẫn nằm trong trường category của từng phiên; thao tác đổi tên và xóa cập nhật các phiên thành viên ở phía máy chủ.
  • sessions.send gửi một tin nhắn vào phiên hiện có.
  • sessions.steer là biến thể ngắt và điều hướng dành cho phiên đang hoạt động.
  • sessions.abort hủy công việc đang hoạt động của một phiên. Truyền key cùng runId tùy chọn, hoặc chỉ runId cho các lượt chạy đang hoạt động mà Gateway có thể phân giải thành một phiên.
  • sessions.patch cập nhật siêu dữ liệu/ghi đè của phiên và báo cáo mô hình chuẩn hóa đã phân giải cùng agentRuntime có hiệu lực.
  • sessions.reset, sessions.delete và sessions.compact thực hiện bảo trì phiên.
  • sessions.get trả về toàn bộ hàng phiên đã lưu trữ.
  • Việc thực thi trò chuyện vẫn sử dụng chat.history, chat.send, chat.abort và chat.inject. chat.history được chuẩn hóa hiển thị cho các máy khách UI: các thẻ chỉ thị nội tuyến bị loại bỏ khỏi văn bản hiển thị, các payload XML của lệnh gọi công cụ dạng văn bản thuần túy (<tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> và các khối lệnh gọi công cụ bị cắt ngắn) cùng các token điều khiển mô hình ASCII/toàn chiều rộng bị rò rỉ sẽ bị loại bỏ, các hàng trợ lý chỉ chứa token im lặng (chính xác là NO_REPLY / no_reply) bị bỏ qua và các hàng quá lớn có thể được thay bằng phần giữ chỗ.
  • chat.message.get là trình đọc toàn bộ tin nhắn có giới hạn, được bổ sung cho một mục bản chép lời hiển thị duy nhất. Truyền sessionKey, agentId tùy chọn khi việc chọn phiên được giới hạn theo agent và một messageId của bản chép lời trước đó được cung cấp qua chat.history; Gateway trả về cùng phép chiếu đã chuẩn hóa hiển thị mà không áp dụng giới hạn cắt ngắn của lịch sử nhẹ khi mục đã lưu trữ vẫn còn khả dụng và không quá lớn.
  • chat.toolTitles trả về tiêu đề mục đích ngắn cho các lệnh gọi công cụ được kết xuất trong Control UI (theo lô, tối đa 24 mục với dữ liệu đầu vào có giới hạn). Tính năng này được chọn tham gia qua gateway.controlUi.toolTitles (mặc định tắt); Gateway đã tắt tính năng sẽ trả lời { titles: {}, disabled: true } mà không gọi mô hình để máy khách ngừng yêu cầu. Khi được bật, tiêu đề sử dụng định tuyến mô hình tiện ích tiêu chuẩn: utilityModel được cấu hình rõ ràng (một quyết định của người vận hành mà, giống như mọi tác vụ tiện ích, có thể gửi nội dung tác vụ có giới hạn đến nhà cung cấp đã chọn), nếu không thì dùng mô hình nhỏ mặc định do nhà cung cấp của phiên khai báo để không ngầm xuất hiện đích truyền dữ liệu mới; utilityModel trống sẽ tắt hoàn toàn tính năng. Tiêu đề không bao giờ chuyển về dùng mô hình chính. Kết quả được lưu đệm trong cơ sở dữ liệu trạng thái theo agent với khóa là tên công cụ + dữ liệu đầu vào, vì vậy các lượt xem lặp lại không bao giờ tính phí lại cho cùng lệnh gọi.
  • chat.send chấp nhận fastMode: "auto" cho một lượt để sử dụng chế độ nhanh đối với các lệnh gọi mô hình bắt đầu trước ngưỡng tự động, sau đó bắt đầu các lệnh gọi thử lại, dự phòng, kết quả công cụ hoặc tiếp tục về sau mà không dùng chế độ nhanh. Ngưỡng mặc định là 60 giây (DEFAULT_FAST_MODE_AUTO_ON_SECONDS) và có thể được cấu hình theo từng mô hình bằng agents.defaults.models["<provider>/<model>"].params.fastAutoOnSeconds. Bên gọi chat.send có thể truyền fastAutoOnSeconds cho một lượt để ghi đè ngưỡng cho yêu cầu đó. Truyền queueMode (steer, followup, collect hoặc interrupt) để chỉ ghi đè chế độ hàng đợi đã lưu trữ cho yêu cầu này; các thao tác điều hướng rõ ràng trong Control UI sử dụng queueMode: "steer".
  • device.pair.list trả về các thiết bị ghép đôi đang chờ và đã được phê duyệt.
  • device.pair.setupCode tạo mã thiết lập di động và theo mặc định là URL dữ liệu QR PNG. Phương thức này yêu cầu operator.admin và được chủ ý loại khỏi thông tin khám phá được quảng bá. Kết quả bao gồm setupCode, qrDataUrl tùy chọn, gatewayUrl, nhãn không bí mật auth và urlSource.
  • device.pair.approve, device.pair.reject và device.pair.remove quản lý các bản ghi ghép đôi thiết bị.
  • device.pair.rename gán một nhãn người vận hành ({ deviceId, label }) được ưu tiên hơn tên hiển thị do máy khách báo cáo và vẫn được giữ lại sau khi sửa chữa hoặc phê duyệt lại thiết bị.
  • device.token.rotate xoay vòng token của thiết bị đã ghép đôi trong giới hạn vai trò đã phê duyệt và phạm vi của bên gọi.
  • device.token.revoke thu hồi token của thiết bị đã ghép đôi trong giới hạn vai trò đã phê duyệt và phạm vi của bên gọi.
Mã thiết lập nhúng một thông tin xác thực khởi tạo có thời hạn ngắn. Máy khách không được ghi nhật ký hoặc lưu trữ thông tin này sau khi luồng ghép đôi kết thúc.
  • node.pair.list, node.pair.approve, node.pair.reject, và node.pair.remove bao quát việc phê duyệt khả năng của node. node.pair.request và node.pair.verify đã bị loại bỏ trong phiên bản 2026.7 cùng với kho lưu trữ ghép nối node độc lập; các yêu cầu đang chờ xử lý được Gateway tạo trong khi node kết nối.
  • node.list và node.describe trả về trạng thái node đã biết/đang kết nối.
  • node.rename cập nhật nhãn của một node đã ghép nối.
  • node.invoke chuyển tiếp một lệnh đến node đang kết nối.
  • node.invoke.result trả về kết quả cho một yêu cầu gọi.
  • mcp.tools.call.v1 là lệnh máy chủ node không giao diện để gọi một công cụ MCP cục bộ trên node đã được cấu hình. Lệnh này được truyền qua node.invoke, yêu cầu node khai báo lệnh và vẫn chịu sự phê duyệt ghép nối cùng gateway.nodes.denyCommands.
  • node.event chuyển các sự kiện bắt nguồn từ node trở lại gateway.
  • node.pluginTools.update là đường dẫn công bố duy nhất để thay thế các bộ mô tả công cụ plugin/MCP hiển thị với agent của node đang kết nối; tham số connect không chứa chúng.
  • node.pending.pull và node.pending.ack là các API hàng đợi của node đang kết nối.
  • node.pending.enqueue và node.pending.drain quản lý công việc đang chờ xử lý bền vững cho các node ngoại tuyến/đã ngắt kết nối.
  • approval.history trả về theo thứ tự mới nhất trước các phê duyệt kết thúc được lưu giữ trong 30 ngày cho yêu cầu thực thi, plugin và agent hệ thống (phạm vi operator.approvals). Phương thức này hỗ trợ phân trang bằng con trỏ cùng bộ lọc loại tùy chọn; các phê duyệt đang chờ xử lý không phải là hàng lịch sử.
  • approval.get và approval.resolve là các phương thức phê duyệt bền vững không phụ thuộc vào loại (phạm vi operator.approvals). approval.get trả về một phép chiếu đã làm sạch của trạng thái đang chờ xử lý hoặc kết thúc được lưu giữ với urlPath ổn định; approval.resolve chấp nhận ID phê duyệt chuẩn, một kind tường minh và một quyết định, áp dụng cơ chế câu trả lời đầu tiên được chấp nhận và luôn trả về kết quả chuẩn đã ghi nhận.
  • exec.approval.request, exec.approval.get, exec.approval.list, và exec.approval.resolve bao quát các yêu cầu phê duyệt thực thi một lần cùng việc tra cứu/phát lại phê duyệt đang chờ xử lý. Chúng là các bộ điều hợp tại ranh giới giao thức trên cùng một sổ đăng ký phê duyệt bền vững.
  • exec.approval.waitDecision chờ một phê duyệt thực thi đang chờ xử lý và trả về quyết định cuối cùng (hoặc null khi hết thời gian chờ).
  • exec.approvals.get và exec.approvals.set quản lý các bản chụp nhanh chính sách phê duyệt thực thi của gateway.
  • exec.approvals.node.get và exec.approvals.node.set quản lý chính sách phê duyệt thực thi cục bộ trên node thông qua các lệnh chuyển tiếp của node.
  • plugin.approval.request, plugin.approval.list, plugin.approval.waitDecision, và plugin.approval.resolve bao quát các luồng phê duyệt do plugin định nghĩa.
  • ui.command cho phép bên gọi operator.write gửi các lệnh bố cục và điều hướng có kiểu đến các máy khách giao diện điều khiển đang kết nối có quảng bá khả năng ui-commands.
  • Các lệnh bao quát việc chia/đóng/lấy tiêu điểm ngăn, khả năng hiển thị thanh bên, khả năng hiển thị và vị trí neo của bảng terminal/trình duyệt, cũng như điều hướng phiên.
  • Giao thức v1 chủ ý phân phối đến mọi giao diện điều khiển có khả năng và đang kết nối. Nếu không có giao diện nào kết nối, yêu cầu sẽ thất bại với UNAVAILABLE thay vì giả vờ rằng bố cục đã thay đổi.
  • Tự động hóa: wake lên lịch chèn văn bản đánh thức ngay lập tức hoặc vào Heartbeat tiếp theo; cron.get, cron.list, cron.status, cron.add, cron.update, cron.remove, cron.run, cron.runs quản lý công việc đã lên lịch.
  • cron.run vẫn là RPC kiểu đưa vào hàng đợi dành cho các lần chạy thủ công. Máy khách cần ngữ nghĩa hoàn tất nên đọc runId được trả về và thăm dò cron.runs.
  • cron.runs chấp nhận bộ lọc runId không rỗng tùy chọn để máy khách có thể theo dõi một lần chạy thủ công trong hàng đợi mà không xảy ra tranh chấp với các mục lịch sử khác của cùng công việc.
  • Skills và công cụ: commands.list, skills.*, tools.catalog, tools.effective, tools.invoke. Xem Các phương thức trợ giúp cho người vận hành bên dưới.

​
Các nhóm sự kiện phổ biến

  • chat: các bản cập nhật trò chuyện trên giao diện như chat.inject và các sự kiện trò chuyện khác chỉ có trong bản ghi. Trong giao thức v4, tải trọng phần thay đổi chứa deltaText; message vẫn là bản chụp nhanh tích lũy của trợ lý. Các phép thay thế không theo tiền tố đặt replace=true và sử dụng deltaText làm văn bản thay thế.
  • session.message, session.operation, session.tool: các bản cập nhật bản ghi, thao tác phiên đang diễn ra và luồng sự kiện cho một phiên đã đăng ký.
  • session.approval: trạng thái phê duyệt đang chờ xử lý và kết thúc đã được làm sạch cho một bên đăng ký chính xác theo phiên đã chủ động chọn tham gia. Các phê duyệt con sử dụng đối tượng tổ tiên đã được lưu bền vững; các sự kiện không bao giờ sửa đổi bản ghi hoặc đánh thức agent.
  • sessions.changed: chỉ mục hoặc siêu dữ liệu phiên đã thay đổi.
  • presence: cập nhật bản chụp nhanh trạng thái hiện diện của hệ thống.
  • tick: sự kiện duy trì kết nối/trạng thái hoạt động định kỳ.
  • health: cập nhật bản chụp nhanh tình trạng của gateway.
  • heartbeat: cập nhật luồng sự kiện Heartbeat.
  • cron: sự kiện thay đổi lần chạy/công việc Cron.
  • shutdown: thông báo tắt gateway.
  • node.pair.requested / node.pair.resolved: vòng đời ghép nối node.
  • node.invoke.request: phát rộng yêu cầu gọi node.
  • device.pair.requested / device.pair.resolved: vòng đời thiết bị đã ghép nối.
  • voicewake.changed: cấu hình kích hoạt bằng từ đánh thức đã thay đổi.
  • config.changed: một lần ghi cấu hình đã được lưu bền vững (tải trọng chứa đường dẫn cấu hình, hàm băm của bản chụp nhanh mới và dấu thời gian — không bao giờ chứa nội dung cấu hình). Thuộc phạm vi đọc của người vận hành; máy khách làm mới qua config.get.
  • exec.approval.requested / exec.approval.resolved: vòng đời phê duyệt thực thi.
  • plugin.approval.requested / plugin.approval.resolved: vòng đời phê duyệt plugin.

​
Các phương thức trợ giúp cho Node

Node có thể gọi skills.bins để lấy danh sách hiện tại gồm các tệp thực thi của skill nhằm kiểm tra tự động cho phép.

​
RPC sổ cái kiểm toán

audit.activity.list cung cấp cho máy khách của người vận hành một chế độ xem ổn định theo thứ tự mới nhất trước về siêu dữ liệu vòng đời của lần chạy agent, hành động công cụ và tin nhắn đã chọn tham gia. Phương thức này yêu cầu operator.read. Truy vấn loại trừ các bản ghi cũ hơn 30 ngày và sổ cái SQLite dùng chung được giới hạn ở 100.000 bản ghi. Các hàng hết hạn bị xóa trong quá trình khởi động Gateway, bảo trì hằng giờ và các lần ghi sau đó. Xem Lịch sử kiểm toán để biết mô hình dữ liệu và ngữ nghĩa quyền riêng tư.
  • Tham số: agentId, sessionKey hoặc runId chính xác tùy chọn; kind tùy chọn ("agent_run", "tool_action" hoặc "message"); status tùy chọn ("started", "succeeded", "failed", "cancelled", "timed_out", "blocked" hoặc "unknown"); direction của tin nhắn tùy chọn ("inbound" hoặc "outbound") và channel chính xác; các giới hạn mili giây Unix bao hàm after / before tùy chọn; limit tùy chọn từ 1 đến 500; và chuỗi cursor tùy chọn từ trang trước.
  • Kết quả: { "events": AuditActivityEventV1[], "nextCursor"?: string }.
Hợp kiểu kết quả V1 có tên chứa các schema riêng biệt cho lần chạy agent, hành động công cụ, tin nhắn đến và tin nhắn đi. Bộ phân biệt eventType lần lượt là agent_run, tool_action, inbound_message hoặc outbound_message; kind và direction của tin nhắn vẫn khả dụng để lọc và hiển thị. Mỗi sự kiện có schemaVersion: 1 dạng số nguyên. Tham chiếu danh tính tin nhắn sử dụng chính xác định dạng hmac-sha256:v1:<32 hex key id>:<64 hex digest>; ID tác nhân là người gửi qua kênh sử dụng cùng định dạng. Tất cả các biến thể đều yêu cầu eventType, schemaVersion, eventId, sequence, sourceSequence, occurredAt, kind, action, status, actor và redaction. Các trường của biến thể là: Các enum đóng của tin nhắn là:
  • conversationKind: direct, group, channel hoặc unknown.
  • outcome đến: completed, skipped hoặc failed; reasonCode tùy chọn: duplicate, reply_operation_active, reply_operation_aborted, fast_abort, plugin_bound_handled, plugin_bound_unavailable, plugin_bound_declined, plugin_bound_error, before_dispatch_handled, acp_dispatch_completed, acp_dispatch_failed, acp_dispatch_empty hoặc acp_dispatch_aborted.
  • outcome đi: sent, suppressed, failed hoặc unknown; reasonCode tùy chọn: cancelled_by_message_sending_hook, cancelled_by_reply_payload_sending_hook, empty_after_message_sending_hook, empty_after_reply_payload_sending_hook, hoặc no_visible_payload. Một bộ điều hợp không trả về danh tính nền tảng là unknown, vì không thể bác bỏ tác dụng phụ bên ngoài.
  • deliveryKind: text, media hoặc other; failureStage: platform_send, queue hoặc unknown.
Các trường kết thúc có tương quan với nhau, không phải tùy chọn độc lập: Mỗi sự kiện hoạt động bao gồm một mã định danh sự kiện ổn định, số thứ tự sổ cái đơn điệu tăng, số thứ tự sự kiện nguồn, dấu thời gian, tác nhân, hành động, trạng thái, giá trị số nguyên schemaVersion: 1 và redaction: "metadata_only". Bản ghi lần chạy và công cụ yêu cầu thông tin nguồn gốc của agent và lần chạy, đồng thời có thể bao gồm thông tin nguồn gốc phiên. Bản ghi tin nhắn có thể bao gồm mã định danh agent và lần chạy, nhưng chủ ý không bao giờ bao gồm sessionKey hoặc sessionId; do đó, bộ lọc truy vấn sessionKey chỉ áp dụng cho các hàng lần chạy và công cụ. Sự kiện công cụ có thể bao gồm mã định danh lệnh gọi công cụ và tên công cụ. Bản ghi tin nhắn sử dụng message.inbound.processed hoặc message.outbound.finished và bổ sung hướng, kênh, loại cuộc hội thoại, kết quả đã chuẩn hóa, cùng loại phân phối, giai đoạn lỗi, thời lượng, số lượng kết quả, mã lý do và các bí danh tài khoản/cuộc hội thoại/tin nhắn/đích được tạo khóa cục bộ theo bản cài đặt (tất cả đều là tùy chọn). Các bí danh này hỗ trợ việc tương quan nhưng không phải là ẩn danh hóa: cơ sở dữ liệu trạng thái chứa khóa của chúng, trong khi các bản xuất RPC và CLI thì không. Sổ cái không lưu prompt, nội dung tin nhắn, đối số công cụ, kết quả công cụ, đầu ra lệnh hoặc văn bản lỗi thô. Các giá trị sessionKey của lần chạy/công cụ vẫn là siêu dữ liệu tương quan thô và có thể chứa mã định danh tài khoản nền tảng hoặc đối tác; bản ghi tin nhắn không chứa khóa phiên. Đối với các hàng đến, durationMs đo quá trình điều phối lõi cho đến trạng thái kết thúc và resultCount đếm các payload công cụ, chặn và phản hồi trong hàng đợi đã hoàn tất. Đối với các hàng đi, durationMs bao quát quyền sở hữu phân phối cho đến khi xác nhận, chuyển vào hàng thư lỗi hoặc đối soát (bao gồm thời gian chờ trong hàng đợi), và resultCount đếm các lần gửi vật lý đã xác định trên nền tảng. deliveryKind, khi có, mô tả payload hiệu lực sau các hook và quá trình kết xuất; các hàng bị ngăn gửi hoặc có trạng thái mơ hồ do sự cố sẽ không có giá trị này. Phạm vi tin nhắn hiện tại bao gồm các tin nhắn đến được chấp nhận và đi tới quá trình điều phối lõi, kể cả kết quả trùng lặp/trạng thái kết thúc của lõi. Phạm vi tin nhắn đi ghi một hàng kết thúc cho mỗi payload phản hồi logic ban đầu đi tới cơ chế phân phối bền vững dùng chung; việc chia đoạn và phân nhánh của adapter được tổng hợp trong resultCount. Các lần gửi có thể thử lại trong hàng đợi hoặc có trạng thái mơ hồ chỉ được ghi sau khi xác nhận, chuyển vào hàng thư lỗi hoặc đối soát. Các đường dẫn cục bộ của Plugin và gửi trực tiếp bỏ qua những ranh giới dùng chung này hiện chưa được bao phủ. Hàng đợi worker có giới hạn hoạt động theo nỗ lực tối đa và có thể làm mất bản ghi khi xảy ra lỗi hoặc quá tải, vì vậy bề mặt này không phải là kho lưu trữ tuân thủ không mất dữ liệu. Tính năng ghi được bật theo mặc định và do audit.enabled kiểm soát. Việc ghi tin nhắn được kiểm soát riêng bởi audit.messages và mặc định là "off". Khi tính năng ghi bị tắt, audit.activity.list tiếp tục cung cấp các bản ghi đã được ghi trước đó cho đến khi chúng hết hạn. Các schema yêu cầu, kết quả và AuditEvent của audit.list đã phát hành vẫn không thay đổi và chỉ trả về bản ghi lần chạy agent và thao tác công cụ. Các ứng dụng khách vận hành mới nên gọi audit.activity.list khi Gateway quảng bá phương thức này. Các Gateway cũ hơn có thể báo unknown method: audit.activity.list hoặc, vì việc cấp quyền diễn ra trước khi tra cứu phương thức trong các phiên bản đã phát hành, báo missing scope: operator.admin cho một yêu cầu có phạm vi đọc. Chỉ coi trường hợp sau là phương thức không tồn tại khi phương thức đó không được quảng bá. Sau đó, ứng dụng khách chỉ có thể thử lại audit.list khi các bộ lọc của nó không yêu cầu hỗ trợ loại tin nhắn, hướng hoặc kênh. Sử dụng openclaw audit cho truy vấn văn bản và bản xuất JSON có giới hạn.

​
RPC sổ cái tác vụ

Ứng dụng khách vận hành kiểm tra và hủy các bản ghi tác vụ nền của Gateway thông qua các RPC sổ cái tác vụ (packages/gateway-protocol/src/schema/tasks.ts). Các RPC này trả về bản tóm tắt tác vụ đã được làm sạch, không phải trạng thái runtime thô.
  • tasks.list yêu cầu operator.read.
    • Tham số: status tùy chọn ("queued", "running", "completed", "failed", "cancelled" hoặc "timed_out") hoặc một mảng các trạng thái đó, agentId tùy chọn, sessionKey tùy chọn, limit tùy chọn từ 1 đến 500, và chuỗi cursor tùy chọn.
    • Kết quả: { "tasks": TaskSummary[], "nextCursor"?: string }.
  • tasks.get yêu cầu operator.read.
    • Tham số: { "taskId": string }.
    • Kết quả: { "task": TaskSummary }.
    • Mã định danh tác vụ không tồn tại trả về dạng lỗi không tìm thấy của Gateway.
  • tasks.cancel yêu cầu operator.write.
    • Tham số: { "taskId": string, "reason"?: string }.
    • Kết quả: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
    • found cho biết sổ cái có tác vụ khớp hay không. cancelled cho biết runtime đã chấp nhận hoặc ghi nhận yêu cầu hủy hay chưa.
TaskSummary bao gồm id, status và siêu dữ liệu tùy chọn: kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, dấu thời gian, tiến độ, bản tóm tắt trạng thái kết thúc và văn bản lỗi đã được làm sạch. agentId xác định agent đang thực thi tác vụ; sessionKey và ownerKey bảo toàn ngữ cảnh của bên yêu cầu và điều khiển.

​
Phương thức trợ giúp dành cho bên vận hành

  • commands.list (operator.read) truy xuất danh mục lệnh runtime cho một agent.
    • agentId là tùy chọn; bỏ qua để đọc không gian làm việc mặc định của agent.
    • scope kiểm soát bề mặt mà name chính nhắm đến: text trả về token lệnh văn bản chính không có / ở đầu; native và đường dẫn both mặc định trả về tên gốc có nhận biết nhà cung cấp khi có.
    • textAliases chứa các bí danh dấu gạch chéo chính xác như /model và /m.
    • nativeName chứa tên lệnh gốc có nhận biết nhà cung cấp khi tên đó tồn tại.
    • provider là tùy chọn và chỉ ảnh hưởng đến cách đặt tên gốc cùng tính khả dụng của lệnh Plugin gốc.
    • includeArgs=false loại bỏ siêu dữ liệu đối số đã tuần tự hóa khỏi phản hồi.
  • tools.catalog (operator.read) truy xuất danh mục công cụ runtime cho một agent. Phản hồi bao gồm các công cụ được nhóm và siêu dữ liệu nguồn gốc:
    • source: core hoặc plugin
    • pluginId: Plugin sở hữu khi source="plugin"
    • optional: liệu công cụ Plugin có phải là tùy chọn hay không
  • tools.effective (operator.read) truy xuất danh mục công cụ có hiệu lực tại runtime cho một phiên.
    • sessionKey là bắt buộc.
    • Gateway suy ra ngữ cảnh runtime đáng tin cậy từ phiên ở phía máy chủ thay vì chấp nhận ngữ cảnh xác thực hoặc phân phối do bên gọi cung cấp.
    • Phản hồi là một phép chiếu do máy chủ suy ra, có phạm vi theo phiên, của danh mục đang hoạt động, bao gồm các công cụ lõi, Plugin, kênh và máy chủ MCP đã được phát hiện.
    • tools.effective chỉ đọc đối với MCP: nó có thể chiếu danh mục MCP của phiên đang hoạt động qua chính sách công cụ cuối cùng, nhưng không tạo runtime MCP, kết nối phương thức truyền tải hoặc phát hành tools/list. Nếu không tồn tại danh mục đang hoạt động phù hợp, phản hồi có thể bao gồm thông báo như mcp-not-yet-connected, mcp-not-yet-listed hoặc mcp-stale-catalog.
    • Các mục công cụ có hiệu lực sử dụng source="core", source="plugin", source="channel" hoặc source="mcp".
  • tools.invoke (operator.write) gọi một công cụ khả dụng thông qua cùng đường dẫn chính sách Gateway như /tools/invoke.
    • name là bắt buộc. args, sessionKey, agentId, confirm và idempotencyKey là tùy chọn.
    • Nếu cả sessionKey và agentId đều hiện diện, agent của phiên đã phân giải phải khớp với agentId.
    • Các trình bao bọc lõi chỉ dành cho chủ sở hữu như cron, gateway và nodes yêu cầu danh tính chủ sở hữu/quản trị viên (operator.admin) mặc dù bản thân tools.invoke là operator.write.
    • Phản hồi là một phong bì hướng đến SDK với các trường ok, toolName, output tùy chọn và error có kiểu. Các trường hợp từ chối do phê duyệt hoặc chính sách trả về ok:false trong payload thay vì bỏ qua pipeline chính sách công cụ của Gateway.
  • skills.status (operator.read) truy xuất danh mục skill hiển thị cho một agent.
    • agentId là tùy chọn; bỏ qua để đọc không gian làm việc mặc định của agent.
    • Phản hồi bao gồm tính đủ điều kiện, các yêu cầu còn thiếu, kiểm tra cấu hình và các tùy chọn cài đặt đã được làm sạch mà không làm lộ giá trị bí mật thô.
  • skills.search và skills.detail (operator.read) trả về siêu dữ liệu khám phá ClawHub.
  • skills.upload.begin, skills.upload.chunk và skills.upload.commit (operator.admin) chuẩn bị một kho lưu trữ skill riêng tư trước khi cài đặt. Đây là đường dẫn tải lên quản trị riêng biệt dành cho các máy khách đáng tin cậy, không phải luồng cài đặt skill ClawHub thông thường, và bị tắt theo mặc định trừ khi skills.install.allowUploadedArchives được bật.
    • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) tạo một lượt tải lên được liên kết với slug và giá trị buộc đó.
    • skills.upload.chunk({ uploadId, offset, dataBase64 }) nối thêm các byte tại độ lệch đã giải mã chính xác.
    • skills.upload.commit({ uploadId, sha256? }) xác minh kích thước cuối cùng và SHA-256. Việc commit chỉ hoàn tất lượt tải lên; nó không cài đặt skill.
    • Các kho lưu trữ skill đã tải lên là kho lưu trữ zip chứa một thư mục gốc SKILL.md. Tên thư mục nội bộ của kho lưu trữ không bao giờ chọn đích cài đặt.
  • skills.install (operator.admin) có ba chế độ:
    • Chế độ ClawHub: { source: "clawhub", slug, version?, force? } cài đặt một thư mục skill vào thư mục skills/ của không gian làm việc mặc định của agent.
    • Chế độ tải lên: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } cài đặt một lượt tải lên đã commit vào thư mục skills/<slug> của không gian làm việc mặc định của agent. Slug và giá trị buộc phải khớp với yêu cầu skills.upload.begin ban đầu. Yêu cầu sẽ bị từ chối trừ khi skills.install.allowUploadedArchives được bật; cài đặt này không ảnh hưởng đến các lượt cài đặt ClawHub.
    • Chế độ trình cài đặt Gateway: { name, installId, timeoutMs? } chạy một hành động metadata.openclaw.install đã khai báo trên máy chủ Gateway. Các máy khách cũ hơn có thể vẫn gửi dangerouslyForceUnsafeInstall; trường này đã lỗi thời, chỉ được chấp nhận để tương thích giao thức và bị bỏ qua. Sử dụng security.installPolicy cho các quyết định cài đặt thuộc quyền sở hữu của người vận hành.
  • skills.update (operator.admin) có hai chế độ:
    • Chế độ ClawHub cập nhật một slug được theo dõi hoặc tất cả lượt cài đặt ClawHub được theo dõi trong không gian làm việc mặc định của agent.
    • Chế độ cấu hình vá các giá trị skills.entries.<skillKey> như enabled, apiKey và env.

​
Các chế độ xem models.list

models.list chấp nhận một tham số view tùy chọn (src/agents/model-catalog-visibility.ts):
  • Bỏ qua hoặc "default": nếu agents.defaults.modelPolicy.allow được cấu hình, phản hồi là danh mục được phép, bao gồm các mô hình được khám phá động cho các mục provider/*. Nếu không, phản hồi là toàn bộ danh mục của Gateway.
  • "configured": hành vi có kích thước phù hợp với bộ chọn. Nếu agents.defaults.modelPolicy.allow được cấu hình, nó vẫn được ưu tiên, bao gồm khám phá theo phạm vi nhà cung cấp cho các mục provider/*. Khi không có danh sách cho phép, phản hồi sử dụng các mục models.providers.<provider>.models rõ ràng, và chỉ quay về toàn bộ danh mục khi không tồn tại hàng mô hình nào được cấu hình.
  • "provider-config": danh mục models.providers.*.models do nguồn biên soạn, độc lập với danh sách cho phép của bộ chọn. Các hàng bao gồm khả năng công khai của mô hình và tính khả dụng có nhận biết tuyến, nhưng loại bỏ các endpoint của nhà cung cấp, tài liệu xác thực và cấu hình yêu cầu runtime.
  • "all": toàn bộ danh mục Gateway, bỏ qua agents.defaults.modelPolicy.allow. Dùng cho giao diện chẩn đoán/khám phá, không dùng cho bộ chọn mô hình thông thường.

​
Phê duyệt thực thi

  • Khi một yêu cầu thực thi cần được phê duyệt, Gateway phát rộng exec.approval.requested.
  • Các máy khách vận hành phân giải bằng cách gọi exec.approval.resolve (yêu cầu operator.approvals).
  • Đối với host=node, exec.approval.request phải bao gồm systemRunPlan (siêu dữ liệu phiên/argv/cwd/rawCommand chuẩn). Các yêu cầu thiếu systemRunPlan sẽ bị từ chối.
  • Sau khi được phê duyệt, các lệnh gọi node.invoke system.run được chuyển tiếp sẽ tái sử dụng systemRunPlan chuẩn đó làm ngữ cảnh lệnh/cwd/phiên có thẩm quyền.
  • Nếu bên gọi thay đổi command, rawCommand, cwd, agentId hoặc sessionKey trong khoảng thời gian từ lúc chuẩn bị đến lần chuyển tiếp system.run cuối cùng đã được phê duyệt, Gateway sẽ từ chối lượt chạy thay vì tin tưởng payload đã bị thay đổi.

​
Phương án dự phòng phân phối của agent

  • Các yêu cầu agent có thể bao gồm deliver=true để yêu cầu phân phối ra ngoài.
  • bestEffortDeliver=false (mặc định) giữ hành vi nghiêm ngặt: các đích phân phối không thể phân giải hoặc chỉ dùng nội bộ sẽ trả về INVALID_REQUEST.
  • bestEffortDeliver=true cho phép quay về thực thi chỉ trong phiên khi không thể phân giải tuyến có thể phân phối ra bên ngoài (ví dụ: các phiên nội bộ/webchat hoặc cấu hình nhiều kênh không rõ ràng).
  • Kết quả agent cuối cùng có thể bao gồm result.deliveryStatus khi đã yêu cầu phân phối, sử dụng cùng các trạng thái sent, suppressed, partial_failed và failed được ghi lại cho openclaw agent --json --deliver.

​
Quản lý phiên bản

  • PROTOCOL_VERSION, MIN_CLIENT_PROTOCOL_VERSION, MIN_NODE_PROTOCOL_VERSION và MIN_PROBE_PROTOCOL_VERSION nằm trong packages/gateway-protocol/src/version.ts.
  • Máy khách gửi minProtocol + maxProtocol. Máy khách vận hành và giao diện người dùng phải bao gồm giao thức hiện tại trong phạm vi đó; máy khách và máy chủ hiện tại chạy giao thức v4.
  • Các máy khách đã xác thực có cả role: "node" và client.mode: "node" có thể sử dụng giao thức Node N-1 (hiện là v3). Các phép thăm dò khởi động lại nhẹ sử dụng cùng cửa sổ N-1. Xác thực thiết bị, ghép nối, phạm vi, chính sách lệnh và phê duyệt thực thi không thay đổi bởi cửa sổ tương thích này. Các khả năng và lệnh của Node thuộc sở hữu Plugin sẽ bị giữ lại cho đến khi Node nâng cấp lên giao thức hiện tại vì các bề mặt được lưu trữ của chúng không thuộc hợp đồng N-1.
  • Các schema và mô hình được tạo từ định nghĩa TypeBox:
    • pnpm protocol:gen
    • pnpm protocol:gen:swift
    • pnpm protocol:check

​
Hằng số máy khách

Phần triển khai máy khách tham chiếu nằm trong packages/gateway-client/src/ (OpenClaw bao bọc nó thông qua facade src/gateway/client.ts mỏng). Các giá trị mặc định này ổn định trên toàn giao thức v4 và là đường cơ sở được mong đợi cho các máy khách bên thứ ba. Máy chủ công bố các giá trị policy.tickIntervalMs, policy.maxPayload và policy.maxBufferedBytes có hiệu lực trong hello-ok; máy khách nên tuân theo các giá trị đó thay vì các giá trị mặc định trước khi bắt tay. Máy khách tham chiếu cho phép các yêu cầu hữu hạn tự quản lý thời hạn đã cấu hình khi mọi yêu cầu đang chờ đều có thời hạn. Một yêu cầu expectFinal không có timeoutMs hữu hạn, bất kỳ yêu cầu nào có timeoutMs: null, hoặc hỗn hợp các yêu cầu hữu hạn và không giới hạn sẽ duy trì bộ giám sát nhịp hoạt động. Nếu các sự kiện đến và phản hồi vẫn im lặng quá ngưỡng hết thời gian chờ nhịp, máy khách sẽ đóng socket bằng mã 4000, từ chối mọi yêu cầu đang chờ và kết nối lại. Máy khách không phát lại các yêu cầu bị từ chối sau khi kết nối lại.

​
Xác thực

  • Xác thực Gateway bằng bí mật dùng chung sử dụng connect.params.auth.token hoặc connect.params.auth.password, tùy theo gateway.auth.mode đã cấu hình ("none" | "token" | "password" | "trusted-proxy").
  • Các chế độ mang danh tính như Tailscale Serve (gateway.auth.allowTailscale: true) hoặc gateway.auth.mode: "trusted-proxy" không phải loopback đáp ứng bước kiểm tra xác thực kết nối từ tiêu đề yêu cầu thay vì connect.params.auth.*.
  • gateway.auth.mode: "none" truy cập riêng bỏ qua hoàn toàn xác thực kết nối bằng bí mật dùng chung; không để chế độ đó lộ diện trên truy cập công khai/không đáng tin cậy.
  • Sau khi ghép cặp, Gateway cấp một token thiết bị giới hạn theo vai trò + phạm vi của kết nối, được trả về trong hello-ok.auth.deviceToken. Máy khách nên lưu token này sau mọi lần kết nối thành công.
  • Khi kết nối lại bằng token thiết bị đã lưu đó, cũng nên sử dụng lại tập phạm vi đã được phê duyệt và lưu cho token đó. Điều này duy trì quyền truy cập đọc/thăm dò/trạng thái đã được cấp và tránh âm thầm thu hẹp các lần kết nối lại về một phạm vi ngầm định chỉ dành cho quản trị viên.
  • Tập hợp thông tin xác thực kết nối phía máy khách (selectConnectAuth trong packages/gateway-client/src/client.ts):
    • auth.password độc lập và luôn được chuyển tiếp khi được đặt.
    • auth.token được điền theo thứ tự ưu tiên: trước tiên là token dùng chung được chỉ định rõ, sau đó là deviceToken được chỉ định rõ, rồi đến token đã lưu cho từng thiết bị (được lập khóa theo deviceId + role).
    • auth.bootstrapToken chỉ được gửi khi không có phương án nào ở trên phân giải được auth.token. Token dùng chung hoặc bất kỳ token thiết bị nào được phân giải sẽ ngăn gửi giá trị này.
    • Việc tự động nâng cấp token thiết bị đã lưu trong lần thử lại một lần AUTH_TOKEN_MISMATCH chỉ được cho phép với các điểm cuối đáng tin cậy: loopback, hoặc wss:// có tlsFingerprint được ghim. wss:// công khai không có ghim không đủ điều kiện.
  • Quy trình khởi tạo bằng mã thiết lập tích hợp sẵn trả về hello-ok.auth.deviceToken của Node chính cùng một token người vận hành có giới hạn trong hello-ok.auth.deviceTokens để bàn giao đáng tin cậy cho thiết bị di động. Token người vận hành bao gồm operator.talk.secrets để đọc cấu hình Talk gốc, nhưng loại trừ các phạm vi thay đổi ghép cặp và operator.admin.
  • Trong khi quy trình khởi tạo bằng mã thiết lập không thuộc đường cơ sở chờ phê duyệt, chi tiết PAIRING_REQUIRED bao gồm recommendedNextStep: "wait_then_retry", retryable: true và pauseReconnect: false. Tiếp tục kết nối lại bằng cùng token khởi tạo cho đến khi yêu cầu được phê duyệt hoặc token mất hiệu lực.
  • Chỉ lưu hello-ok.auth.deviceTokens khi kết nối đã dùng xác thực khởi tạo trên phương thức truyền tải đáng tin cậy như wss:// hoặc ghép cặp loopback/cục bộ.
  • Nếu máy khách cung cấp rõ deviceToken hoặc scopes, tập phạm vi do bên gọi yêu cầu đó vẫn có thẩm quyền quyết định; phạm vi được lưu đệm chỉ được tái sử dụng khi máy khách đang tái sử dụng token đã lưu cho từng thiết bị.
  • Token thiết bị có thể được xoay vòng/thu hồi qua device.token.rotate và device.token.revoke (yêu cầu operator.pairing). Việc xoay vòng hoặc thu hồi token của Node hay vai trò khác không phải người vận hành cũng yêu cầu operator.admin.
  • device.token.rotate trả về siêu dữ liệu xoay vòng. Phương thức này chỉ trả lại token mang quyền thay thế cho các lệnh gọi từ cùng thiết bị đã được xác thực bằng token thiết bị đó, để máy khách chỉ dùng token có thể lưu token thay thế trước khi kết nối lại. Các thao tác xoay vòng bằng token dùng chung/quản trị viên không trả lại token mang quyền.
  • Việc cấp, xoay vòng và thu hồi token luôn bị giới hạn trong tập vai trò đã được phê duyệt được ghi trong mục ghép cặp của thiết bị đó; thao tác thay đổi token không thể mở rộng hoặc nhắm đến vai trò thiết bị mà phê duyệt ghép cặp chưa từng cấp.
  • Đối với các phiên token của thiết bị đã ghép cặp, việc quản lý thiết bị tự giới hạn phạm vi trừ khi bên gọi cũng có operator.admin: bên gọi không phải quản trị viên chỉ có thể quản lý token người vận hành cho mục thiết bị của chính mình. Việc quản lý token của Node và các vai trò khác không phải người vận hành chỉ dành cho quản trị viên, ngay cả đối với thiết bị của chính bên gọi.
  • device.token.rotate và device.token.revoke cũng kiểm tra tập phạm vi của token người vận hành đích so với phạm vi phiên hiện tại của bên gọi. Bên gọi không phải quản trị viên không thể xoay vòng hoặc thu hồi token người vận hành có phạm vi rộng hơn phạm vi họ đang có.
  • Lỗi xác thực bao gồm error.details.code cùng các gợi ý khôi phục:
    • error.details.canRetryWithDeviceToken (boolean)
    • error.details.recommendedNextStep: một trong các giá trị retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration (packages/gateway-protocol/src/connect-error-details.ts).
  • Hành vi máy khách đối với AUTH_TOKEN_MISMATCH:
    • Máy khách đáng tin cậy có thể thử lại một lần có giới hạn bằng token được lưu đệm cho từng thiết bị.
    • Nếu lần thử lại đó thất bại, hãy dừng các vòng lặp kết nối lại tự động và hiển thị hướng dẫn hành động cho người vận hành.
  • AUTH_SCOPE_MISMATCH có nghĩa là token thiết bị đã được nhận diện nhưng không bao phủ vai trò/phạm vi được yêu cầu. Không trình bày đây là token không hợp lệ; hãy nhắc người vận hành ghép cặp lại hoặc phê duyệt hợp đồng phạm vi hẹp hơn/rộng hơn.

​
Danh tính thiết bị và ghép cặp

  • Các Node nên bao gồm danh tính thiết bị ổn định (device.id) được suy ra từ dấu vân tay của cặp khóa.
  • Gateway cấp token cho từng thiết bị + vai trò.
  • Các ID thiết bị mới cần được phê duyệt ghép cặp trừ khi tính năng tự động phê duyệt cục bộ được bật.
  • Tự động phê duyệt ghép cặp tập trung vào các kết nối loopback cục bộ trực tiếp.
  • OpenClaw cũng có một đường dẫn tự kết nối hẹp, cục bộ với backend/container dành cho các luồng trợ giúp đáng tin cậy dùng bí mật chung.
  • Các kết nối tailnet hoặc LAN trên cùng máy vẫn được coi là từ xa khi ghép cặp và cần được phê duyệt.
  • Máy khách WS thường bao gồm danh tính device trong connect (người vận hành + Node). Các ngoại lệ duy nhất dành cho người vận hành không có thiết bị là các đường dẫn tin cậy được chỉ định rõ:
    • gateway.controlUi.allowInsecureAuth=true để tương thích HTTP không an toàn chỉ trên localhost.
    • xác thực Control UI cho người vận hành qua gateway.auth.mode: "trusted-proxy" thành công.
    • gateway.controlUi.dangerouslyDisableDeviceAuth=true (biện pháp khẩn cấp, hạ cấp bảo mật nghiêm trọng).
    • Các RPC backend gateway-client qua loopback trực tiếp trên đường dẫn trợ giúp nội bộ dành riêng.
  • Việc bỏ qua danh tính thiết bị gây hệ quả đối với phạm vi. Khi một kết nối người vận hành không có thiết bị được cho phép qua đường dẫn tin cậy được chỉ định rõ, OpenClaw vẫn xóa các phạm vi tự khai báo thành tập rỗng trừ khi đường dẫn đó có một ngoại lệ duy trì phạm vi được đặt tên. Khi đó, các phương thức bị giới hạn theo phạm vi sẽ thất bại với missing scope.
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true là một đường dẫn duy trì phạm vi khẩn cấp của Control UI. Đường dẫn này không cấp phạm vi cho các máy khách WebSocket backend tùy chỉnh hoặc có dạng CLI tùy ý.
  • Đường dẫn trợ giúp backend gateway-client qua loopback trực tiếp dành riêng chỉ duy trì phạm vi cho các RPC mặt phẳng điều khiển cục bộ nội bộ; các ID backend tùy chỉnh không nhận được ngoại lệ này.
  • Mọi kết nối phải ký nonce connect.challenge do máy chủ cung cấp.

​
Chẩn đoán di chuyển xác thực thiết bị

Đối với các máy khách cũ vẫn sử dụng hành vi ký trước thử thách, connect trả về mã chi tiết DEVICE_AUTH_* trong error.details.code cùng một error.details.reason ổn định. Các lỗi di chuyển thường gặp: Mục tiêu di chuyển:
  • Luôn chờ connect.challenge.
  • Ký payload v2 chứa nonce của máy chủ.
  • Gửi cùng nonce đó trong connect.params.device.nonce.
  • Payload chữ ký ưu tiên là v3 (buildDeviceAuthPayloadV3 trong packages/gateway-client/src/device-auth.ts), liên kết platform và deviceFamily ngoài các trường thiết bị/máy khách/vai trò/phạm vi/token/nonce.
  • Các chữ ký v2 cũ vẫn được chấp nhận để đảm bảo khả năng tương thích, nhưng việc ghim siêu dữ liệu thiết bị đã ghép đôi vẫn kiểm soát chính sách lệnh khi kết nối lại.

​
TLS và ghim

  • TLS được hỗ trợ cho các kết nối WS (cấu hình gateway.tls).
  • Máy khách có thể tùy chọn ghim dấu vân tay chứng chỉ của Gateway thông qua gateway.remote.tlsFingerprint hoặc CLI --tls-fingerprint.

​
Phạm vi

Giao thức này cung cấp toàn bộ API của Gateway: trạng thái, kênh, mô hình, trò chuyện, tác nhân, phiên, node, phê duyệt và nhiều chức năng khác. Bề mặt chính xác được xác định bởi các schema TypeBox được tái xuất từ packages/gateway-protocol/src/schema.ts.

​
Liên quan