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-protocolphát hành các schema, trình xác thực, kiểu TypeScript, trình trợ giúp gọn 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-clientphát hành 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.
Truyền tải và đóng khung
- WebSocket, frame văn bản, payload JSON.
- Frame đầu tiên phải là 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 có thể đọc được
bởi con người và có thể thay đổi, ngoại trừ khi 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à toàn bộ tập hợp 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 chiếu đố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 phát hành token thiết bị (cấu trúc
ở trên). pluginSurfaceUrls là tùy chọn và ánh xạ tên bề mặt Plugin (ví dụ:
canvas) tới các URL được lưu trữ theo 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
đã ngừng dùng 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ị này với
config.get.configRevisionHash để xác định xem cấu hình đã lưu mới hơn 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 khi ghi cấu hình sử dụng.
Khi Gateway vẫn đang hoàn tất khởi động các tiến trình phụ trợ, 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 giới hạn kết nối thay vì coi đây là
lỗi bắt tay cuối cùng.
Khi token thiết bị được phát hành, hello-ok.auth sẽ 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
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ỉ lưu
hello-ok.auth.deviceTokens khi xác thực khởi tạo chạy qua 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 đáng tin cậy trong cùng tiến trình (client.id: "gateway-client",
client.mode: "backend") có thể bỏ qua device trên 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 được 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 subagent) 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ộ. Máy khách từ xa,
có nguồn gốc trình duyệt, Node và máy khách sử dụng token thiết bị/danh tính thiết bị rõ ràng vẫn
phải trải qua các bước 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
Các worker đám mây sử dụng một cổng vào loopback chuyên dụng thô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 người 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 lưu dưới dạng băm, 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; đồng thời
kiểm tra riêng phiên bản và tập tính năng hiện tại. Khi thành công, hệ thống trả về
worker-hello-ok tối thiểu; quá trình 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 nhỏ hơn 64 KiB, ngoại trừ frame worker.inference.start
đã thương lượng có thể lên tới 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 cơ chế rào chắn epoch chủ sở hữu, liên kết phiên
do Gateway sở hữu, thao tác so sánh-và-hoán đổi trên 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 người 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ể kết xuất 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 tạo. 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 sẽ không khả dụng ngay cả khi chính sách công cụ cho phép 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 chuyển đổi chi tiết (ví dụ:screen.record,camera.capture).
Vai trò và phạm vi
Để xem đầy đủ mô hình phạm vi người 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 người 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 đóng và chuyên dụng.
src/gateway/operator-scopes.ts), toàn bộ tập hợp đóng:
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 cấu trúc nguồn và có thể là đố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 người 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 thông qua
chat.send áp dụng các bước kiểm tra cấp lệnh nghiêm ngặt hơn: 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 người vận hành thấp hơn.
node.pair.approve có thêm bước kiểm tra phạm vi tại thời điểm phê duyệt bên trên
phạm vi phương thức cơ sở (operator.pairing), dựa trên commands
(src/infra/node-pairing-authz.ts) đã khai báo của yêu cầu đang chờ xử lý:
Khả năng/lệnh/quyền (node)
Các node khai báo yêu cầu về khả năng khi 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 cho phép gọi.permissions: các nút bật/tắt chi tiết (ví dụ:screen.record,camera.capture).
node.pluginTools.update. Các máy chủ node không giao diện sẽ khởi động lại để áp dụng
các thay đổi khai báo trong danh mục MCP. Phương thức cập nhật này là đường dẫn
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 đôi,
lọc các bộ mô tả nằm ngoài bề mặt lệnh đã phê duyệt, xóa chúng khi node ngắt kết nối
và từ chối các thao tá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ố toàn bộ danh mục thay thế Skills của chúng bằng
node.skills.update. Phương thức dành cho vai trò node này là đường dẫn 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, phầ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 nhanh Skills của tác nhân khi node
được kết nối và xóa nội dung 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 đôi cũng có thể báo cáo trạng thái hiện diện lâu dài trong nền 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 qua
node.list và node.describe, đồng thời phát các bản cập nhật
node.presence đến các 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 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 đôi từng hoạt động trong lần đánh thức nền mà không đánh dấu node đó là đã 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 bền vững 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 đôi trả về
handled: false.
Các Gateway xử lý thành công trả về một 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 trạng thái hiện diện được lưu bền vững.
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 đôi 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, tác nhân 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 đó. - Theo mặc định, các lần phát rộng
plugin.*do Plugin định nghĩa được giới hạn ởoperator.writehoặcoperator.admin; các mục rõ ràng 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. - Theo mặc định, các họ sự kiện phát rộng không xá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 rõ ràng.
Các họ phương thức RPC
hello-ok.features.methods là một danh sách khám phá thận trọng được tạo từ
src/gateway/server-methods-list.ts cùng các mục xuất phương thức
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 cố ý loại khỏi hoạt độ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à cơ chế 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 nhanh tình trạng Gateway đã lưu đệm hoặc vừa thăm dò.diagnostics.stabilitytrả về bộ ghi chẩn đoán độ ổn định 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, mã định danh phiên. Không có văn bản trò chuyện, nội dung Webhook, đầu ra công cụ, nội dung thô của yêu cầu/phản hồi, 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 người 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 đôi sử dụng.system-presencetrả về bản chụp nhanh 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 được lưu bền vững gần đây nhất.set-heartbeatsbật hoặc tắt quá trình xử lý Heartbeat trên Gateway.gateway.suspend.preparechỉ tạo một hợp đồng tạm ngưng phối hợp ngắn hạn khi công việc Gateway được theo dõi đang nhàn rỗi.gateway.suspend.statuskiểm tra hợp đồng đó vàgateway.suspend.resumegiải phóng hợp đồng sau khi khôi phục hoặc sau một 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 thời gian chạy cho phép. Xem các chế độ xem “models.list” bên dưới.usage.statustrả về các cửa sổ sử dụng/tóm tắt hạn ngạch còn lại của nhà cung cấp.usage.costtrả về các bản tóm tắt tổng hợp chi phí sử dụng cho một khoảng ngày. TruyềnagentIdcho một tác nhân hoặcagentScope: "all"để tổng hợp các tác nhân đã cấu hình.doctor.memory.statustrả về trạng thái sẵn sàng của bộ nhớ vector / embedding được lưu đệm cho không gian làm việc của tác nhân mặc định đang hoạt động. Chỉ truyền{ "probe": true }hoặc{ "deep": true }để ping rõ ràng nhà cung cấp embedding trực tiếp. Truyền{ "agentId": "agent-id" }để giới hạn số liệu thống kê kho Dreaming vào một không gian làm việc của tác nhân; 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 tác nhân 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 nâng cấp sâu. Yêu cầuoperator.read.sessions.usagetrả về các bản tóm tắt mức sử dụng theo từng phiên. TruyềnagentIdcho một tác nhân hoặcagentScope: "all"để liệt kê các tác nhân đã 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ó nhận biết 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 thời gian chạy Gateway không nhận dạng được múi giờ 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ề các bản tóm tắt trạng thái kênh/Plugin tích hợp sẵn và đi kèm.channels.logoutđăng xuất 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 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 một thông báo đẩy APNs thử nghiệm đến node iOS đã đăng ký.voicewake.gettrả về các cụm từ kích hoạt bằng giọng nói đã lưu.voicewake.setcập nhật các cụm từ kích hoạt bằng giọng nói 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à việc 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 kích hoạ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à các tệp được quản lý. Không thể gỡ cài đặt các Plugin đi kèm mà chỉ có thể vô hiệu hóa. 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 đã cấu hình của Gateway, 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 động một PTY máy chủ choagentIdđược chỉ định rõ hoặc tác nhân mặc định, rồi trả về tác nhân đã phân giải, thư mục làm việc, shell và trạng thái giới hạn.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 nối, 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 của 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 đế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 mấ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 theo 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 nhân được sandbox hoàn toàn sẽ bị từ chối, và việc thay đổi chính sách tác nhân sẽ đóng các PTY hiện có cũng như đang 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 dành cho giọng nói, phiên âm trực tuyến và thoại thời gian thực: các mã định danh nhà cung cấp chuẩn, bí danh sổ đăng ký, nhãn, trạng thái đã cấu hình, kết quảreadytùy chọn ở cấp nhóm, các mã định danh mô hình/giọng nói được cung cấp, chế độ chuẩn, phương thức truyền tải, chiến lược bộ não và 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 sửa đổ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; nếu thuộc tính này không có trên Gateway cũ, hãy coi trạng thái là chưa được xác minh.talk.configtrả về tải trọng 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, các 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 mã thông báo 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ề mã thông báo dạng văn bản thuần túy hoặc giá trị băm của mã đó.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 và phiên âm thời gian thực 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 để ngắt lời có kiểm soát bằng VAD trong các phiên chuyển tiếp của 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 sẽ 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 vẫn giữ lượt chạy 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 thông báo hỗ trợ chế độ chặn và kết quả không được bắt đầu một phản hồi khác.talk.session.steergửi điều khiển giọng nói của lượt chạy đang hoạt động vào một phiên Talk dựa trên tác nhân do Gateway sở hữu:{ sessionId, text, mode? }, trong đómodelàstatus,steer,cancelhoặcfollowup; nếu bỏ qua chế độ, hệ thống sẽ phân loại dựa trên văn bản được 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 rộ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 nhân 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 trùng lặp của thông điệp bản chép lời.talk.client.closeđóng phiên thoại logic sau các thao tác ghi bản chép lời đang chờ xử lý. Thao tác đóng có tính lũy đẳng và có thể gửi bản tóm lược 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ụ đầu tiên được hỗ trợ 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 giọng nói của lượt chạy đang hoạt động cho 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 việc điều hướng.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ị.tts.enablevàtts.disablechuyển đổi 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ề toàn bộ một đoạn âm thanh trực tiếp dưới dạngaudioBase64, cùng với siêu dữ liệuprovidervà các siêu dữ liệu tùy chọnoutputFormat,mimeTypevàfileExtension. Không giốngtts.convert, phương thức này không trả về đường dẫn cục bộ của Gateway; không giốngtalk.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. Lỗi của chủ sở hữu đủ điều kiện có thể được phát hành dưới dạng suy giảm nguội hoặc cũ vớiwarningCount; lỗi nghiêm ngặt hoặc chưa á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 tải trọng 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 từng 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 bên dưới mục nhập mảng sử dụng các đường dẫn[], chẳng hạn nhưagents.list[].skills.config.applyxác thực và thay thế toàn bộ tải trọng cấu hình.config.schematrả về tải trọng lược đồ cấu hình trực tiếp được công cụ Control UI và CLI sử dụng: lược đồ,uiHints, phiên bản, siêu dữ liệu tạo và siêu dữ liệu lược đồ plugin + kênh khi có thể tải. Tải trọng bao gồm siêu dữ liệutitle/descriptiontừ cùng nhãn/văn bản trợ giúp như giao diện người dùng, bao gồm các nhánh kết hợp đối tượng lồng nhau, ký tự đại diện, mục mảng vàanyOf/oneOf/allOfkhi có tài liệu trường phù hợp.config.schema.lookuptrả về tải trọng 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 +hintPath,reloadKindtùy chọn và bản tóm tắt các phần tử con trực tiếp để giao diện người dùng/CLI truy sâu.reloadKindlà một trongrestart,hothoặcnone(src/config/schema.ts) và phản ánh bộ 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ữ lại 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). Bản tóm tắt phần tử con cung cấpkey,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; các bên gọi có phiên có thể bao gồmcontinuationMessageđể khi khởi động, một lượt tác nhân tiếp theo được tiếp tục thông qua hàng đợi tiếp diễn sau 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ế bàn giao dịch vụ được quản lý tách rời, thay vì thay thế cây gói hoặc sửa đổi đầu ra checkout/bản dựng bên trong Gateway đang hoạt động. Một lượt bà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"; yêu cầu tiếp diễn 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 bà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 shell thủ công. 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đối với systemd. Trong một lượt bàn giao đã bắt đầu, tín hiệu khởi động lại có thể báo cáostats.reason: "restart-health-pending"trong thời gian ngắn; yêu cầu tiếp diễn bị trì hoãn cho đến khi CLI xác minh Gateway đã khởi động lại và ghi tín hiệuokcuối cùng.update.statuslàm mới và trả về tín 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.
Trình trợ giúp tác tử và không gian làm việc
Trình trợ giúp tác tử và không gian làm việc
agents.listtrả về các mục tác tử hiển thị với Gateway, bao gồm siêu dữ liệu mô hình/môi trường thực thi có hiệu lực vàkindngữ nghĩa tùy chọn (agenthoặcsystem). Máy khách quảng bá khả năng bắt tayagent-kindđể nhận danh sách đầy đủ có kiểu; máy khách không có khả năng này tiếp tục nhận danh sách kiểu cũ, an toàn cho bộ chọn và không có các hàng hệ thống. Máy khách nhận biết loại sẽ loại trừ các hàngsystemkhỏi bộ chọn thông thường nhưng vẫn giữ chúng trong chế độ xem chẩn đoán. Các Gateway v4 cũ hơn có thể trả về các hàng không cókind.agents.create,agents.updatevàagents.deletequản lý bản ghi tác tử và việc kết nối không gian làm việc.agents.files.list,agents.files.getvàagents.files.setquản lý các tệp không gian làm việc khởi tạo được cung cấp cho một tác tử.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 chỉ đọc, có phân trang đối với thư mục không gian làm việc của tác tử cho các máy khách trong miền toán tử tin cậy được mô tả tại Phạm vi toán tử. Yêu cầu chỉ chấp nhận các đường dẫn tương đối với không gian làm việc; thao tác đọc được giới hạn trong thư mục gốc không gian làm việc đã được phân giải đườ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 để lộ đường dẫn không gian làm việc trên máy chủ. Không có thao tác ghi nào trong không gian tên 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 toán tử. Xem RPC 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à lượt tải xuống hiện vật được suy ra từ bản chép lời cho 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 đa 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ề lượt tải xuống không được hỗ trợ thay vì được tìm nạp ở phía máy chủ.environments.listvàenvironments.statusduy trì khả năng khám phá môi trường cục bộ của Gateway và môi trường Node. Các worker đám mây đã cấu hình và bản ghi bền vững do các 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 hủy bỏ môi trường worker bền vững theo cách lũy đẳng. Cả hai đều yêu cầuoperator.admin, là các 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 tác tử hoặc phiên.agent.waitchờ một lượt chạy hoàn tất và trả về ảnh chụp nhanh 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ệuagentRuntimecho từng hàng khi đã cấu hình phần phụ trợ môi trường thực thi tác tử. Khi bật tính năng bố trí worker đám mây 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 chủ sở hữu, không gian làm việc, gói, con trỏ ACK hoặc khôi phục.sessions.subscribevàsessions.unsubscribebật hoặc tắt đăng ký nhận 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ý nhận sự kiện bản chép lời/tin nhắn cho một phiên. TruyềnincludeApprovals: trueđể đồng thời nhận các sự kiện vòng đờisession.approvalđã được làm sạch dành cho các phê duyệt có đối tượng được lưu trữ bao gồm chính xác phiên đó và có liên kết người đánh giá cho phép máy khách đăng ký. Khi đó, phản hồi đăng ký bao gồm mộtapprovalReplayđang chờ có giới hạn; giá trị này là nguồn chính thức khitruncatedlà false. Việc chọn tham gia áp dụng theo từng lệnh gọi đăng ký, không được duy trì: đăng ký lại cùng 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 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 giữ nguyên tử các giá trị 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 tham chiếu cơ sở và tên nhánh, cònexecNode(operator.admin) liên kết việc thực thi của phiên với một máy chủ Node. Worktree đã tạo được trả lại trong kết quả và lưu giữ 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 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 bằngsession_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 phiên cha và hook lệnh; một fork không thể đánh dấu thành công cho phiên cha. 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ó có 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 việc 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ỉ diễn ra một chiều; RPC này không bao gồm thao tác kéo ngược từ worker về cục bộ.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 sẽ 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 cho một 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ỉrunIdđối với 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/giá trị ghi đè của phiên và báo cáo mô hình chuẩn đã 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 máy khách UI: các thẻ chỉ thị nội tuyến bị loại khỏi văn bản hiển thị, các tải trọng XML lời gọi công cụ dạng văn bản thuần (<tool_call>...</tool_call>,<function_call>...</function_call>,<tool_calls>...</tool_calls>,<function_calls>...</function_calls>và các khối lời 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ỉ đều 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 nằm trong phạm vi tác tử và mộtmessageIdcủa bản chép lời đã được cung cấp trước đó 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ẹ, miễn là mục đã lưu trữ vẫn còn và không quá lớn.chat.toolTitlestrả về các tiêu đề ngắn mô tả mục đích cho lời gọi công cụ được hiển thị trong Control UI (theo lô, tối đa 24 mục với đầ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 cơ chế đị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 toán tử mà, giống 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 phiên khai báo để không ngầm xuất hiện đích gửi dữ liệu mới;utilityModeltrống sẽ tắt hoàn toàn tính năng này. Tiêu đề không bao giờ chuyển sang dùng mô hình chính làm phương án dự phòng. Kết quả được lưu đệm trong cơ sở dữ liệu trạng thái theo tác tử với khóa là tên công cụ + đầu vào, vì vậy các lượt xem lặp lại không bao giờ bị tính phí lại cho cùng lời gọi.chat.sendchấp nhậnfastMode: "auto"cho một lượt để sử dụng chế độ nhanh đối với các lời gọi mô hình bắt đầu trước ngưỡng cắt tự động, sau đó bắt đầu các lời 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 cắt 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 cắt 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à một 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 toán tử ({ 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 duy trì sau khi sửa chữa hoặc phê duyệt lại thiết bị.device.token.rotateluân chuyển token của thiết bị đã ghép đôi trong giới hạn vai trò được 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ò được 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.removephụ trách phê duyệt năng lực 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 ghép nối Node độc lập; các yêu cầu đang chờ xử lý được Gateway tạo 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ấ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.eventtruyề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 mô tả công cụ Plugin/MCP hiển thị với tác nhân của Node đang kết nối; các 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 bền vững đang chờ xử lý 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ề các phê duyệt cuối cùng theo thứ tự mới nhất trước, được lưu giữ trong 30 ngày cho các yêu cầu thực thi, Plugin và tác nhân 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 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 trạng thái cuối được lưu giữ vớiurlPathổn định;approval.resolvechấp nhận mã phê duyệt chuẩn, mộtkindrõ ràng và một quyết định, áp dụng cơ chế câu trả lời đầu tiên thắng, đồng thời luôn trả về kết quả chuẩn đã ghi nhận.exec.approval.request,exec.approval.get,exec.approval.list, vàexec.approval.resolvephụ trách 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 biên 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.resolvephụ trách các luồng phê duyệt do Plugin định nghĩa.
Các lệnh Control UI
Các lệnh Control UI
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 Control UI đang kết nối có quảng bá năng lựcui-commands.- Các lệnh phụ trách 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 thiết bị đầu cuối/trình duyệt, cũng như điều hướng phiên.
- Giao thức v1 chủ ý phát đến mọi Control UI đang kết nối và có năng lực. Nếu không có Control UI 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à một RPC kiểu đưa vào hàng đợi 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ọcrunIdtùy chọn, không rỗng để 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 người dùng nhưchat.injectvà các sự kiện trò chuyện khác chỉ dành cho bản ghi hội thoại. Trong giao thức v4, tải trọng delta chứadeltaText;messagevẫn là bản chụp nhanh tích lũy của trợ lý. Các 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 hội thoại, 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à cuối cùng đã được làm sạch cho bên đăng ký phiên chính xác đã 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; sự kiện không bao giờ sửa đổi bản ghi hội thoại hoặc đánh thức tác nhân.sessions.changed: chỉ mục hoặc siêu dữ liệu phiên đã thay đổi.presence: các bản 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: bản cập nhật bản chụp nhanh tình trạng Gateway.heartbeat: bản 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 thao tác 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 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). Có phạm vi đọc dành cho 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 Node
Node có thể gọiskills.bins để truy xuất danh sách tệp thực thi Skills hiện tại
cho các bước kiểm tra tự động cho phép.
RPC sổ cái kiểm tra
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 tác nhân, hành động công cụ và tin nhắn chủ động chọn tham gia. Phương thức này yêu cầu
operator.read. Các truy vấn loại trừ bản ghi cũ hơn 30 ngày và sổ cái
SQLite dùng chung bị 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 tra để biết mô hình dữ liệu và ngữ nghĩa quyền riêng tư.
- Tham số:
agentId,sessionKey, hoặ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 Unixafter/beforebao hàm tù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 có thể dùng để lọc và hiển thị. Mọi sự kiện đều có
schemaVersion: 1 dạng số nguyên. Các 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>; mã tác nhân là người gửi của kênh
sử dụng cùng định dạng.
Tất 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 biến thể là:
Các enum tin nhắn đóng là:
conversationKind:direct,group,channel, hoặcunknown.outcomeđến:completed,skipped, hoặ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_empty, hoặcacp_dispatch_aborted.outcomeđi:sent,suppressed,failed, hoặ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,media, hoặcother;failureStage:platform_send,queue, hoặ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 tăng đơn điệu,
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ượt chạy và công cụ
yêu cầu nguồn gốc agent và lượt chạy, đồng thời có thể bao gồm nguồn gốc phiên. Bản ghi
tin nhắn có thể bao gồm mã định danh agent và lượt chạy, nhưng có 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ượt 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út danh tài khoản/cuộc hội thoại/tin nhắn/đích
được định khóa cục bộ theo bản cài đặt (nếu có). Các bút danh này hỗ trợ
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ượt chạy/công cụ vẫn là siêu dữ liệu tương quan thô và có thể nhúng
mã định danh tài khoản nền tảng hoặc đối tác; bản ghi tin nhắn bỏ qua 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 tải trọng công cụ, chặn và phản hồi đã hoàn tất trong hàng đợi. Đố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,
đưa vào hàng thư chết 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ả tải trọng 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ẽ bỏ qua 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 đến
quá trình điều phối lõi, bao gồm các kết quả trùng lặp/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 tải trọng phản hồi logic ban đầu đi đến cơ chế phân phối bền vững
dùng chung; việc chia nhỏ và phân nhánh qua bộ điều hợp được tổng hợp trong resultCount. Các lần gửi
có thể thử lại hoặc mơ hồ trong hàng đợi chỉ được ghi sau khi xác nhận, đưa vào hàng
thư chết 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 các
ranh giới dùng chung đó hiện chưa được bao phủ. Hàng đợi worker có giới hạn hoạt động theo khả năng tốt nhất
và có thể làm mất bản ghi khi xảy ra lỗi hoặc bão hòa, 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à được kiểm soát bởi
audit.enabled. 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 vẫn 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 lược đồ 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ượt chạy agent và hành động công cụ. Các máy 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, do
việc ủy 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 đó, máy 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 các 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ụ
Máy 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 thời gian chạy 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 gồm 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ề cấu trúc 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 thời gian chạy có chấp nhận hoặc ghi nhận yêu cầu hủy hay không.
- 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, các dấu thời gian, tiến độ,
bản tóm tắt 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 giữ lại ngữ cảnh của bên yêu cầu và ngữ cảnh điều khiển.
Các phương thức trợ giúp dành cho người vận hành
commands.list(operator.read) truy xuất danh mục lệnh thời gian chạy 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 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 nhận biết nhà cung cấp khi có tên đó.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ụ thời gian chạy 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: chủ sở hữu Plugin khisource="plugin"optional: 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 trong thời gian chạy cho một phiên.sessionKeylà bắt buộc.- Gateway suy ra ngữ cảnh thời gian chạy đá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à phép chiếu do máy chủ suy ra, giới hạn trong phiên, của danh mục đang hoạt động, bao gồm 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 môi trường chạy MCP, kết nối phương thức truyền tải hoặc phát hànhtools/list. Nếu không có 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ì dành cho SDK với
ok,toolName,outputtùy chọn và các trườngerrorcó kiểu. Việc từ chối do phê duyệt hoặc chính sách trả vềok:falsetrong tải trọng 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 Skills 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 đ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ộ 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 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ị ép 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. Thao tá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 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/trong 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>trong không gian làm việc mặc định của agent. Slug và giá trị ép buộc phải khớp với yêu cầuskills.upload.beginban đầu. Yêu cầu 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 vẫn có thể 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 do người vận hành sở hữu.
- 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 tham số view tùy chọn
(src/agents/model-catalog-visibility.ts):
- Bị 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 phát hiện động cho các mụcprovider/*. Nếu không, phản hồi là toàn bộ danh mục 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 có hàng mô hình nào được cấu hình."provider-config": danh mụcmodels.providers.*.modelsdo nguồn tạo, độ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 nhận biết tuyến, nhưng loại bỏ điểm cuối nhà cung cấp, tài liệu xác thực và cấu hình yêu cầu thời gian chạy."all": toàn bộ danh mục Gateway, bỏ quaagents.defaults.modelPolicy.allow. Dùng cho giao diện người dùng 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. - Máy khách của người 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(argv/cwd/rawCommand/siêu dữ liệu phiên chuẩn tắc). 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 tắc đó 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ặcsessionKeygiữa bước chuẩn bị và lần chuyển tiếpsystem.runcuối cùng đã được phê duyệt, Gateway sẽ từ chối chạy thay vì tin tưởng tải trọng đã 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) duy trì 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ộ trả vềINVALID_REQUEST.bestEffortDeliver=truecho phép quay về chế độ thực thi chỉ trong phiên khi không thể phân giải tuyến phân phối bên ngoài (ví dụ: các phiên nội bộ/webchat hoặc cấu hình đa 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 của người 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. - 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 hạng 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 Node do Plugin sở hữu 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. - Lược đồ và mô hình được tạo từ các đị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 giao thức v4 và là đường cơ sở dự kiến cho
máy khách bên thứ ba.
Máy chủ thông báo
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 tổ hợp các yêu cầu hữu hạn và
không giới hạn đều duy trì watchdog nhịp hoạt động. Nếu các sự kiện đến và
phản hồi tiếp tục im lặng quá ngưỡng hết thời gian nhịp, máy khách sẽ đóng
socket với 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ừ các tiêu đề yêu cầu thay vìconnect.params.auth.*. gateway.auth.mode: "none"qua điểm vào riêng tư hoàn toàn bỏ qua xác thực kết nối bằng bí mật dùng chung; không để chế độ đó lộ ra trên điểm vào công khai/không đáng tin cậy.- Sau khi ghép đôi, Gateway cấp một token thiết bị có phạm vi giới hạn theo vai trò
kết nối + các phạm vi, được trả về trong
hello-ok.auth.deviceToken. Máy khách nên lưu giữ token đó 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 tái sử dụng tập phạm vi đã phê duyệt được 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 thành một phạm vi ngầm định hẹp hơn 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 tường minh, sau đó làdeviceTokentường minh, rồi đến token được lưu theo từng thiết bị (được định danh bằngdeviceId+role).auth.bootstrapTokenchỉ được gửi khi không có mục 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 đã phân giải đều ngăn việc gửi mục 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 phép đối 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 đáp ứng điều kiện.
- Quá trình khởi tạo bằng mã thiết lập tích hợp trả về Node chính
hello-ok.auth.deviceTokencùng một token người vận hành có giới hạn tronghello-ok.auth.deviceTokensđể chuyển giao an toàn 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 không bao gồm các phạm vi thay đổi ghép đôi vàoperator.admin. - Trong khi quá 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 trở nên không hợp lệ. - Chỉ lưu giữ
hello-ok.auth.deviceTokenskhi kết nối sử 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 đôi loopback/cục bộ. - Nếu máy khách cung cấp
deviceTokentường minh hoặcscopestường minh, tập phạm vi do bên gọi yêu cầu đó vẫn có hiệu lực quyết định; các phạm vi được lưu đệm chỉ được tái sử dụng khi máy khách tái sử dụng token được lưu theo từng thiết bị. - Có thể xoay vòng/thu hồi token thiết bị thông 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 hoặc 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. Nó chỉ trả lại token mang 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 giữ token thay thế trước khi kết nối lại. Các thao tác xoay vòng bằng bí mật dùng chung/quản trị viên không trả lại token mang.- Việc cấp, xoay vòng và thu hồi token luôn bị giới hạn trong tập vai trò đã phê duyệt được ghi lại trong mục ghép đôi của thiết bị đó; thao tác thay đổi token không thể mở rộng hoặc nhắm đến một vai trò thiết bị mà phê duyệt ghép đôi chưa từng cấp.
- Đối với các phiên token của thiết bị đã ghép đôi, việc quản lý thiết bị chỉ giới hạn ở chính thiết bị đó, 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 họ. 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ả 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 token người vận hành đích so với các 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 token mà họ đang nắm giữ.- 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 trongretry_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 của máy khách đối với
AUTH_TOKEN_MISMATCH:- Máy khách đáng tin cậy có thể thực hiện một lần thử lại có giới hạn bằng token được lưu đệm theo 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 dạng nhưng không bao phủ vai trò/các phạm vi được yêu cầu. Không trình bày trường hợp này như một token không hợp lệ; hãy nhắc người vận hành ghép đôi 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 nối
- Các Node phải chứa 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 theo từng thiết bị + vai trò.
- Các ID thiết bị mới phải được phê duyệt ghép nối, trừ khi tính năng tự động phê duyệt cục bộ được bật.
- Tự động phê duyệt ghép nối 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ộ trong backend/container dành cho các luồng trình trợ giúp dùng bí mật dùng chung đáng tin cậy.
- Các kết nối tailnet hoặc LAN trên cùng máy chủ vẫn được xem là từ xa khi ghép nối và cần được phê duyệt.
- Các máy khách WS thường gửi kèm danh tính
devicetrongconnect(operator + node). Các ngoại lệ operator không có thiết bị duy nhất là những đường dẫn tin cậy rõ ràng:gateway.controlUi.allowInsecureAuth=trueđể tương thích với HTTP không an toàn chỉ trên localhost.- xác thực operator thành công trên Control UI bằng
gateway.auth.mode: "trusted-proxy". gateway.controlUi.dangerouslyDisableDeviceAuth=true(biện pháp khẩn cấp, làm suy giảm nghiêm trọng mức độ bảo mật).- Các RPC backend
gateway-clientqua loopback trực tiếp trên đường dẫn trình trợ giúp nội bộ dành riêng.
- Việc bỏ qua danh tính thiết bị gây ra hệ quả về phạm vi. Khi một kết nối
operator không có thiết bị được cho phép qua một đường dẫn tin cậy rõ ràng, OpenClaw
vẫn xóa các phạm vi do kết nối tự khai báo thành một tập hợ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ó cấu trúc giống CLI bất kỳ.- Đường dẫn trình 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. - Tất cả kết nối phải ký nonce
connect.challengedo máy chủ cung cấp.
Chẩn đoán quá trình 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 cơ chế thử thách,connect
trả về các mã chi tiết DEVICE_AUTH_* trong error.details.code với 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 có 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. - 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ỉ Gateway qua
gateway.remote.tlsFingerprinthoặc CLI--tls-fingerprint.
Phạm vi
Giao thức này cung cấp toàn bộ API 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 nội dung khác. Bề mặt chính xác được xác định bởi các lược đồ TypeBox được tái xuất từpackages/gateway-protocol/src/schema.ts.