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-protocolcung 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áyprotocol.schema.jsonđã được tạo.@openclaw/gateway-clientcung 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.
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 theohello-ok.policy.maxPayloadvà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ệnpayload.largetrước khi gateway đóng kết nối hoặc loại bỏ frame. Các sự kiện này chứasurface, 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.
- 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?}
{ 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 }.requiredScopeslà tập hợp đầy đủ các phạm vi đã biết cho thao tác được yêu cầu. Thông báomissing scope: <scope>cũ được giữ lại cho các máy khách cũ hơn.
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:connect:
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 đó:
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ộtconnect 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 trongconnect.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ữ.
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
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).
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.
src/gateway/operator-scopes.ts), tập hợp đóng đầy đủ:
operator.readoperator.writeoperator.adminoperator.approvalsoperator.pairingoperator.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,voicevà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).
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-presencetrả về các mục được định khóa theo danh tính thiết bị, bao gồmdeviceId,rolesvà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.listbao gồmlastSeenAtMsvàlastSeenReasontù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ý doconnect; 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.
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ọinode.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:
{ "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ấtoperator.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.writehoặcoperator.admin; các mục tường minh nhưplugin.approval.requested/plugin.approval.resolvedsử dụngoperator.approvalsthay 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.
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.
Hệ thống và danh tính
Hệ thống và danh tính
healthtrả về bản chụp tình trạng Gateway từ bộ nhớ đệm hoặc vừa được thăm dò.diagnostics.stabilitytrả 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ầuoperator.read.statustrả 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.gettrả 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-presencetrả 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-eventnố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-heartbeattrả về sự kiện Heartbeat mới nhất đã được lưu lâu dài.set-heartbeatsbật/tắt việc xử lý Heartbeat trên Gateway.gateway.suspend.preparechỉ 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.statuskiểm tra hợp đồng đó vàgateway.suspend.resumegiả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.
Mô hình và mức sử dụng
Mô hình và mức sử dụng
models.listtrả về danh mục mô hình được runtime cho phép. Xem “các chế độ xemmodels.list” bên dưới.usage.statustrả 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.costtrả 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ềnagentIdcho một agent hoặcagentScope: "all"để tổng hợp các agent đã cấu hình.doctor.memory.statustrả 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.repairDreamingArtifactsvàdoctor.memory.dedupeDreamDiarychấ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.remHarnesstrả 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ầuoperator.read.sessions.usagetrả về bản tóm tắt mức sử dụng theo từng phiên. TruyềnagentIdcho một agent hoặcagentScope: "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ậnmode: "specific"vớitimeZoneIANA để xác định ranh giới và nhóm ngày theo lịch có tính đến DST.utcOffsetvẫ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.timeseriestrả về mức sử dụng chuỗi thời gian cho một phiên.sessions.usage.logstrả về các mục nhật ký mức sử dụng cho một phiên.
Kênh và trình trợ giúp đăng nhập
Kênh và trình trợ giúp đăng nhập
channels.statustrả 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.startbắ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.waitchờ luồng đó hoàn tất và khởi động kênh khi thành công.push.testgửi thông báo đẩy APNs thử nghiệm tới một Node iOS đã đăng ký.voicewake.gettrả về các cụm từ kích hoạt đánh thức đã lưu.voicewake.setcập nhật các cụm từ kích hoạt đánh thức và phát rộng thay đổi.
Quản lý Plugin
Quản lý Plugin
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ềnquerykhông rỗng vàlimittù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.
Nhắn tin và nhật ký
Nhắn tin và nhật ký
sendlà 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.tailtrả 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.
Thiết bị đầu cuối của người vận hành
Thiết bị đầu cuối của người vận hành
terminal.openkhởi chạy một PTY máy chủ choagentIdđượ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.resizevàterminal.closechỉ thao tác trên các phiên thuộc sở hữu của kết nối gọi.terminal.uploadchấ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.datavàterminal.exitchỉ đượ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;0khô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.listtrả về các phiên có thể gắn;terminal.attachliê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 đượcterminal.exitvới lý dodetached);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.enabledphả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 và TTS
Talk và TTS
talk.catalogtrả 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ảreadytù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 đặtreadysau 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.configtrả về payload cấu hình Talk có hiệu lực;includeSecretsyêu cầuoperator.talk.secrets(hoặcoperator.admin).talk.session.createtạo một phiên Talk do Gateway sở hữu chorealtime/gateway-relay,transcription/gateway-relayhoặcstt-tts/managed-room. Đối vớistt-tts/managed-room, bên gọioperator.writetruyềnsessionKeycũng phải truyềnspawnedByđể giới hạn phạm vi hiển thị khóa phiên; việc tạosessionKeykhông giới hạn phạm vi vàbrain: "direct-tools"yêu cầuoperator.admin.talk.session.joinxác thực token phiên phòng được quản lý, phátsession.readyhoặcsession.replacedkhi 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.appendAudionố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.endTurnvà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.cancelOutputdừ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.submitToolResulthoà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ềnoptions: { willContinue: true }cho đầu ra công cụ tạm thời hoặcoptions: { 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.steergử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 đómodelàstatus,steer,cancelhoặcfollowup; 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.createtạ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ằngwebrtchoặcprovider-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ềnsessionKeyvà tái sử dụngvoiceSessionIdkhi 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.transcriptnối thêm một mục{ role, text }đã hoàn tất vào phiên tác tử thông thường.entryIdbắt buộc có tính lũy đẳng trongvoiceSessionId; 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.toolCallcho 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ấpconfirmationId.talk.client.steergử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ừsessionKeyvà 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.eventlà 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.speaktổng hợp giọng nói thông qua nhà cung cấp giọng nói Talk đang hoạt động.tts.statustrả 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.providerstrả về danh mục nhà cung cấp TTS hiển thị được.tts.enablevàtts.disablebật/tắt trạng thái tùy chọn TTS.tts.setProvidercập nhật nhà cung cấp TTS ưu tiên.tts.convertthự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ấttextkhô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ạngaudioBase64, cùng vớiprovidervà siêu dữ liệuoutputFormat,mimeTypevàfileExtensiontùy chọn. Khác vớitts.convert, phương thức này không trả về đường dẫn cục bộ của Gateway; khác vớitalk.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.maxTextLengthtrả vềINVALID_REQUEST; lỗi tổng hợp trả vềUNAVAILABLE.
Bí mật, cấu hình, cập nhật và trình hướng dẫn
Bí mật, cấu hình, cập nhật và trình hướng dẫn
secrets.reloadphâ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ớiwarningCount; 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.resolvephâ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.gettrả về ảnh chụp nhanh cấu hình hiện tại trên đĩa,hashcủa tệp gốc thô,configRevisionHashđã phân giải vàappliedConfigHashtù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.setghi một payload cấu hình đã được xác thực.config.patchhợ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 trongreplacePaths; 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.applyxác thực và thay thế toàn bộ payload cấu hình.config.schematrả 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ệutitle/descriptiontừ 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/allOfkhi có tài liệu trường tương ứng.config.schema.lookuptrả 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ùnghintPath,reloadKindtù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.reloadKindlà một trongrestart,hothoặcnone(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 khaikey,pathđã chuẩn hóa,type,required,hasChildren,reloadKindtùy chọn, cùnghint/hintPathđã khớp.update.runchạ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ồmcontinuationMessageđể 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: truecùngresult.reason: "managed-service-handoff-started"vàhandoff.status: "started". Mộtupdate.runđồng thời thứ hai do cùng tiến trình Gateway xử lý trả vềok: falsecùngresult.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: falsecùngmanaged-service-handoff-unavailablehoặcmanaged-service-handoff-failed, cộng thêmhandoff.commandkhi 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_UNITcho 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áostats.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ệuokcuối cùng.update.statuslà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.statusvàwizard.cancelcung cấp trình hướng dẫn thiết lập ban đầu qua WS RPC.
Các trình trợ giúp cho agent và workspace
Các trình trợ giúp cho agent và workspace
agents.listtrả 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.updatevàagents.deletequản lý các bản ghi agent và liên kết workspace.agents.files.list,agents.files.getvàagents.files.setquản lý các tệp workspace khởi tạo được cung cấp cho một agent.audit.activity.listtrả về sổ cái hoạt động chỉ chứa siêu dữ liệu và có phiên bản;audit.listvẫn là RPC chạy/công cụ an toàn về khả năng tương thích.agents.workspace.listvà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.getvàtasks.cancelcung 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.getvàartifacts.downloadcung 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 visessionKey,runIdhoặctaskIdđượ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.listvàenvironments.statusduy 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ệuworkervớiproviderId,leaseIdtùy chọn,state,ageMs,idleMstù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,failedvà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ầuoperator.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.gettrả về danh tính trợ lý có hiệu lực cho một agent hoặc phiên.agent.waitchờ 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ó.
Điều khiển phiên
Điều khiển phiên
sessions.listtrả về chỉ mục phiên hiện tại, bao gồm siêu dữ liệuagentRuntimetheo 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áiplacementđóng (local,requested,provisioning,syncing,starting,active,draining,reconciling,reclaimedhoặcfailed) 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.subscribevàsessions.unsubscribebậ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.subscribevàsessions.messages.unsubscribebậ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ềnincludeApprovals: trueđể cũng nhận các sự kiện vòng đờisession.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ồmapprovalReplayđang chờ có giới hạn; đây là dữ liệu có thẩm quyền khitruncatedlà 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: truesẽ 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ầuoperator.adminhoặcoperator.approvalstrên thiết bị đã ghép đôi.sessions.previewtrả 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.describetrả về một hàng phiên Gateway cho một khóa phiên chính xác.sessions.resolvephân giải hoặc chuẩn hóa một đích phiên.sessions.createtạo một mục phiên mới. Các giá trịmodelvàthinkingLeveltùy chọn lưu trữ nguyên tử các ghi đè ban đầu về mô hình và suy luận.worktree: truecấp phát một worktree được quản lý;worktreeBaseRef/worktreeNametùy chọn chọn ref cơ sở và tên nhánh, cònexecNode(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ưngchat.sendban đầu lồng bên trong bị từ chối, kết quả thành công sẽ bao gồmrunStarted: falsevà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ềnparentSessionKeycùngemitCommandHooks: truecũ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: truekết thúc phiên cha vớisession_end, trong khifalsegiữ phiên cha hoạt động và chỉ phátsession_startcủa phiên con. Việc bỏ quasucceedsParentduy 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 workeractive. 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.renamevàsessions.groups.deletequả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ườngcategorycủ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.sendgửi một tin nhắn vào phiên hiện có.sessions.steerlà biến thể ngắt và điều hướng dành cho phiên đang hoạt động.sessions.aborthủy công việc đang hoạt động của một phiên. TruyềnkeycùngrunIdtùy chọn, hoặc chỉrunIdcho 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.patchcậ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ùngagentRuntimecó hiệu lực.sessions.reset,sessions.deletevàsessions.compactthực hiện bảo trì phiên.sessions.gettrả 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.abortvà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.getlà 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ềnsessionKey,agentIdtùy chọn khi việc chọn phiên được giới hạn theo agent và mộtmessageIdcủa bản chép lời trước đó được cung cấp quachat.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.toolTitlestrả 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 quagateway.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;utilityModeltrố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.sendchấp nhậnfastMode: "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ằngagents.defaults.models["<provider>/<model>"].params.fastAutoOnSeconds. Bên gọichat.sendcó thể truyềnfastAutoOnSecondscho một lượt để ghi đè ngưỡng cho yêu cầu đó. TruyềnqueueMode(steer,followup,collecthoặcinterrupt) để 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ụngqueueMode: "steer".
Ghép đôi thiết bị và token thiết bị
Ghép đôi thiết bị và token thiết bị
device.pair.listtrả về các thiết bị ghép đôi đang chờ và đã được phê duyệt.device.pair.setupCodetạ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ầuoperator.adminvà được chủ ý loại khỏi thông tin khám phá được quảng bá. Kết quả bao gồmsetupCode,qrDataUrltùy chọn,gatewayUrl, nhãn không bí mậtauthvàurlSource.device.pair.approve,device.pair.rejectvàdevice.pair.removequản lý các bản ghi ghép đôi thiết bị.device.pair.renamegá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.rotatexoay 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.revokethu 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.
Ghép nối Node, gọi và công việc đang chờ xử lý
Ghép nối Node, gọi và công việc đang chờ xử lý
node.pair.list,node.pair.approve,node.pair.reject, vànode.pair.removebao quát việc phê duyệt khả năng của node.node.pair.requestvà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.listvànode.describetrả về trạng thái node đã biết/đang kết nối.node.renamecập nhật nhãn của một node đã ghép nối.node.invokechuyển tiếp một lệnh đến node đang kết nối.node.invoke.resulttrả về kết quả cho một yêu cầu gọi.mcp.tools.call.v1là 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 quanode.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ùnggateway.nodes.denyCommands.node.eventchuyển các sự kiện bắt nguồn từ node trở lại gateway.node.pluginTools.updatelà đườ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ốconnectkhông chứa chúng.node.pending.pullvànode.pending.acklà các API hàng đợi của node đang kết nối.node.pending.enqueuevànode.pending.drainquả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.
Các nhóm phê duyệt
Các nhóm phê duyệt
approval.historytrả 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 vioperator.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.getvàapproval.resolvelà các phương thức phê duyệt bền vững không phụ thuộc vào loại (phạm vioperator.approvals).approval.gettrả 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ớiurlPathổn định;approval.resolvechấp nhận ID phê duyệt chuẩn, mộtkindtườ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.resolvebao 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.waitDecisionchờ một phê duyệt thực thi đang chờ xử lý và trả về quyết định cuối cùng (hoặcnullkhi hết thời gian chờ).exec.approvals.getvàexec.approvals.setquả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.getvàexec.approvals.node.setquả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.resolvebao quát các luồng phê duyệt do plugin định nghĩa.
Các lệnh của giao diện điều khiển
Các lệnh của giao diện điều khiển
ui.commandcho phép bên gọioperator.writegử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ăngui-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
UNAVAILABLEthay vì giả vờ rằng bố cục đã thay đổi.
Tự động hóa, Skills và công cụ
Tự động hóa, Skills và công cụ
- Tự động hóa:
wakelê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.runsquản lý công việc đã lên lịch. cron.runvẫ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 đọcrunIdđược trả về và thăm dòcron.runs.cron.runschấp nhận bộ lọcrunIdkhô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.injectvà 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ứadeltaText;messagevẫ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ố đặtreplace=truevà sử dụngdeltaTextlà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 quaconfig.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ọiskills.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,sessionKeyhoặcrunIdchính xác tùy chọn;kindtùy chọn ("agent_run","tool_action"hoặc"message");statustùy chọn ("started","succeeded","failed","cancelled","timed_out","blocked"hoặc"unknown");directioncủa tin nhắn tùy chọn ("inbound"hoặc"outbound") vàchannelchính xác; các giới hạn mili giây Unix bao hàmafter/beforetùy chọn;limittùy chọn từ1đến500; và chuỗicursortùy chọn từ trang trước. - Kết quả:
{ "events": AuditActivityEventV1[], "nextCursor"?: string }.
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,channelhoặcunknown.outcomeđến:completed,skippedhoặcfailed;reasonCodetù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_emptyhoặcacp_dispatch_aborted.outcomeđi:sent,suppressed,failedhoặcunknown;reasonCodetù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ặcno_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,mediahoặcother;failureStage:platform_send,queuehoặcunknown.
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.listyêu cầuoperator.read.- Tham số:
statustùy chọn ("queued","running","completed","failed","cancelled"hoặc"timed_out") hoặc một mảng các trạng thái đó,agentIdtùy chọn,sessionKeytùy chọn,limittùy chọn từ1đến500, và chuỗicursortùy chọn. - Kết quả:
{ "tasks": TaskSummary[], "nextCursor"?: string }.
- Tham số:
tasks.getyêu cầuoperator.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.
- Tham số:
tasks.cancelyêu cầuoperator.write.- Tham số:
{ "taskId": string, "reason"?: string }. - Kết quả:
{ "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }. foundcho biết sổ cái có tác vụ khớp hay không.cancelledcho biết runtime đã chấp nhận hoặc ghi nhận yêu cầu hủy hay chưa.
- Tham số:
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.agentIdlà tùy chọn; bỏ qua để đọc không gian làm việc mặc định của agent.scopekiểm soát bề mặt mànamechính nhắm đến:texttrả về token lệnh văn bản chính không có/ở đầu;nativevà đường dẫnbothmặc định trả về tên gốc có nhận biết nhà cung cấp khi có.textAliaseschứa các bí danh dấu gạch chéo chính xác như/modelvà/m.nativeNamechứa tên lệnh gốc có nhận biết nhà cung cấp khi tên đó tồn tại.providerlà 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=falseloạ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:corehoặcpluginpluginId: Plugin sở hữu khisource="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.sessionKeylà 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.effectivechỉ đọ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ànhtools/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-listedhoặcmcp-stale-catalog.- Các mục công cụ có hiệu lực sử dụng
source="core",source="plugin",source="channel"hoặcsource="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.namelà bắt buộc.args,sessionKey,agentId,confirmvàidempotencyKeylà tùy chọn.- Nếu cả
sessionKeyvàagentIdđều hiện diện, agent của phiên đã phân giải phải khớp vớiagentId. - Các trình bao bọc lõi chỉ dành cho chủ sở hữu như
cron,gatewayvànodesyêu cầu danh tính chủ sở hữu/quản trị viên (operator.admin) mặc dù bản thântools.invokelàoperator.write. - Phản hồi là một phong bì hướng đến SDK với các trường
ok,toolName,outputtùy chọn vàerrorcó kiểu. Các trường hợp từ chối do phê duyệt hoặc chính sách trả vềok:falsetrong 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.agentIdlà 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.searchvàskills.detail(operator.read) trả về siêu dữ liệu khám phá ClawHub.skills.upload.begin,skills.upload.chunkvà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ừ khiskills.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ụcskills/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ụcskills/<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ầuskills.upload.beginban đầu. Yêu cầu sẽ bị từ chối trừ khiskills.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 độngmetadata.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ửidangerouslyForceUnsafeInstall; 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ụngsecurity.installPolicycho các quyết định cài đặt thuộc quyền sở hữu của người vận hành.
- Chế độ ClawHub:
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,apiKeyvà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ếuagents.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ụcprovider/*. 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ếuagents.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ụcprovider/*. Khi không có danh sách cho phép, phản hồi sử dụng các mụcmodels.providers.<provider>.modelsrõ 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ụcmodels.providers.*.modelsdo 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ỏ quaagents.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ầuoperator.approvals). - Đối với
host=node,exec.approval.requestphải bao gồmsystemRunPlan(siêu dữ liệu phiên/argv/cwd/rawCommandchuẩn). Các yêu cầu thiếusystemRunPlansẽ 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ụngsystemRunPlanchuẩ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,agentIdhoặcsessionKeytrong khoảng thời gian từ lúc chuẩn bị đến lần chuyển tiếpsystem.runcuố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
agentcó thể bao gồmdeliver=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=truecho 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ả
agentcuối cùng có thể bao gồmresult.deliveryStatuskhi đã yêu cầu phân phối, sử dụng cùng các trạng tháisent,suppressed,partial_failedvàfailedđược ghi lại choopenclaw agent --json --deliver.
Quản lý phiên bản
PROTOCOL_VERSION,MIN_CLIENT_PROTOCOL_VERSION,MIN_NODE_PROTOCOL_VERSIONvàMIN_PROBE_PROTOCOL_VERSIONnằm trongpackages/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:genpnpm protocol:gen:swiftpnpm protocol:check
Hằng số máy khách
Phần triển khai máy khách tham chiếu nằm trongpackages/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.tokenhoặcconnect.params.auth.password, tùy theogateway.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ặcgateway.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 (
selectConnectAuthtrongpackages/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 theodeviceId+role).auth.bootstrapTokenchỉ được gửi khi không có phương án nào ở trên phân giải đượcauth.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_MISMATCHchỉ được cho phép với các điểm cuối đáng tin cậy: loopback, hoặcwss://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.deviceTokencủa Node chính cùng một token người vận hành có giới hạn tronghello-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ồmoperator.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_REQUIREDbao gồmrecommendedNextStep: "wait_then_retry",retryable: truevà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.deviceTokenskhi 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õ
deviceTokenhoặcscopes, 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.rotatevàdevice.token.revoke(yêu cầuoperator.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ầuoperator.admin. device.token.rotatetrả 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.rotatevàdevice.token.revokecũ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.codecù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_MISMATCHcó 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
devicetrongconnect(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-clientqua 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=truelà 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-clientqua 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.challengedo 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(buildDeviceAuthPayloadV3trongpackages/gateway-client/src/device-auth.ts), liên kếtplatformvàdeviceFamilyngoài các trường thiết bị/máy khách/vai trò/phạm vi/token/nonce. - Các chữ ký
v2cũ 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.tlsFingerprinthoặ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.