پروتکل Gateway

Gateway پروتکل WS، صفحه کنترل واحد + انتقال Node برای OpenClaw است. همه کلاینت‌ها (CLI، رابط کاربری وب، برنامه macOS، Nodeهای iOS/Android، Nodeهای headless) از طریق WebSocket وصل می‌شوند و در زمان دست‌دهی، نقش + حوزه خود را اعلام می‌کنند.

انتقال

• WebSocket، فریم‌های متنی با payloadهای JSON.
• نخستین فریم باید یک درخواست connect باشد.
• فریم‌های پیش از اتصال به 64 KiB محدود هستند. پس از دست‌دهی موفق، کلاینت‌ها باید از محدودیت‌های hello-ok.policy.maxPayload و hello-ok.policy.maxBufferedBytes پیروی کنند. وقتی تشخیص‌ها فعال باشند، فریم‌های ورودی بیش‌ازحد بزرگ و بافرهای خروجی کند، پیش از آنکه gateway فریم تحت‌تأثیر را ببندد یا حذف کند، رویدادهای payload.large منتشر می‌کنند. این رویدادها اندازه‌ها، محدودیت‌ها، سطح‌ها و کدهای دلیل امن را نگه می‌دارند. آن‌ها بدنه پیام، محتوای پیوست، بدنه خام فریم، توکن‌ها، کوکی‌ها یا مقادیر محرمانه را نگه نمی‌دارند.

دست‌دهی (connect)

Gateway → کلاینت (چالش پیش از اتصال):

{  "type": "event",  "event": "connect.challenge",  "payload": { "nonce": "…", "ts": 1737264000000 }}

کلاینت → Gateway:

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "maxProtocol": 4,    "client": {      "id": "cli",      "version": "1.2.3",      "platform": "macos",      "mode": "operator"    },    "role": "operator",    "scopes": ["operator.read", "operator.write"],    "caps": [],    "commands": [],    "permissions": {},    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-cli/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

Gateway → کلاینت:

{  "type": "res",  "id": "…",  "ok": true,  "payload": {    "type": "hello-ok",    "protocol": 4,    "server": { "version": "…", "connId": "…" },    "features": { "methods": ["…"], "events": ["…"] },    "snapshot": { "…": "…" },    "auth": {      "role": "operator",      "scopes": ["operator.read", "operator.write"]    },    "policy": {      "maxPayload": 26214400,      "maxBufferedBytes": 52428800,      "tickIntervalMs": 15000    }  }}

در حالی که Gateway هنوز در حال تکمیل sidecarهای راه‌اندازی است، درخواست connect می‌تواند یک خطای قابل‌تلاش‌مجدد UNAVAILABLE برگرداند که در آن details.reason برابر "startup-sidecars" و شامل retryAfterMs است. کلاینت‌ها باید این پاسخ را در چارچوب بودجه کلی اتصال خود دوباره تلاش کنند، به‌جای اینکه آن را به‌عنوان شکست نهایی دست‌دهی نمایش دهند.

server، features، snapshot و policy همگی طبق schema (packages/gateway-protocol/src/schema/frames.ts) الزامی هستند. auth نیز الزامی است و نقش/حوزه‌های مذاکره‌شده را گزارش می‌کند. pluginSurfaceUrls اختیاری است و نام سطح‌های Plugin، مانند canvas، را به URLهای میزبانی‌شده و حوزه‌بندی‌شده نگاشت می‌کند.

URLهای سطح Plugin حوزه‌بندی‌شده ممکن است منقضی شوند. Nodeها می‌توانند node.pluginSurface.refresh را با { "surface": "canvas" } فراخوانی کنند تا یک ورودی تازه در pluginSurfaceUrls دریافت کنند. بازآرایی آزمایشی Plugin بوم از مسیر سازگاری منسوخ canvasHostUrl، canvasCapability یا node.canvas.capability.refresh پشتیبانی نمی‌کند؛ کلاینت‌ها و gatewayهای native فعلی باید از سطح‌های Plugin استفاده کنند.

وقتی هیچ توکن دستگاهی صادر نمی‌شود، hello-ok.auth مجوزهای مذاکره‌شده را بدون فیلدهای توکن گزارش می‌کند:

{  "auth": {    "role": "operator",    "scopes": ["operator.read", "operator.write"]  }}

کلاینت‌های بک‌اند مورداعتماد در همان فرایند (client.id: "gateway-client", client.mode: "backend") می‌توانند در اتصالات loopback مستقیم، وقتی با توکن/گذرواژه مشترک gateway احراز هویت می‌کنند، device را حذف کنند. این مسیر برای RPCهای صفحه کنترل داخلی رزرو شده است و مانع می‌شود baselineهای قدیمی جفت‌سازی CLI/دستگاه، کار بک‌اند محلی مانند به‌روزرسانی‌های نشست subagent را مسدود کنند. کلاینت‌های دوردست، کلاینت‌های با مبدأ مرورگر، کلاینت‌های Node، و کلاینت‌های صریح device-token/device-identity همچنان از بررسی‌های عادی جفت‌سازی و ارتقای حوزه استفاده می‌کنند.

وقتی یک توکن دستگاه صادر می‌شود، hello-ok همچنین شامل موارد زیر است:

{  "auth": {    "deviceToken": "…",    "role": "operator",    "scopes": ["operator.read", "operator.write"]  }}

bootstrap داخلی QR/setup-code یک مسیر تحویل موبایل تازه است. یک اتصال موفق baseline setup-code یک توکن Node اصلی به‌همراه یک توکن operator محدود برمی‌گرداند:

{  "auth": {    "deviceToken": "…",    "role": "node",    "scopes": [],    "deviceTokens": [      {        "deviceToken": "…",        "role": "operator",        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]      }    ]  }}

تحویل operator عمداً محدود شده است تا onboarding با QR بتواند حلقه operator موبایل را شروع کند و راه‌اندازی native را بدون اعطای حوزه‌های تغییر جفت‌سازی یا operator.admin کامل کند. این شامل operator.talk.secrets است تا کلاینت native بتواند پیکربندی Talk موردنیاز خود را پس از bootstrap بخواند. دسترسی گسترده‌تر به جفت‌سازی و admin به یک جریان جداگانه جفت‌سازی یا توکن operator تأییدشده نیاز دارد. کلاینت‌ها باید hello-ok.auth.deviceTokens را فقط وقتی پایدار کنند که اتصال از احراز هویت bootstrap روی انتقال مورداعتماد مانند wss:// یا جفت‌سازی loopback/local استفاده کرده باشد.

نمونه Node

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "maxProtocol": 4,    "client": {      "id": "ios-node",      "version": "1.2.3",      "platform": "ios",      "mode": "node"    },    "role": "node",    "scopes": [],    "caps": ["camera", "canvas", "screen", "location", "voice"],    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],    "permissions": { "camera.capture": true, "screen.record": false },    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-ios/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

فریم‌بندی

• درخواست: {type:"req", id, method, params}
• پاسخ: {type:"res", id, ok, payload|error}
• رویداد: {type:"event", event, payload, seq?, stateVersion?}

متدهای دارای اثر جانبی به کلیدهای idempotency نیاز دارند (schema را ببینید).

نقش‌ها + حوزه‌ها

برای مدل کامل حوزه‌های operator، بررسی‌های زمان تأیید، و معناشناسی secret مشترک، حوزه‌های operator را ببینید.

نقش‌ها

• operator = سرویس‌گیرنده سطح کنترل (CLI/UI/اتوماسیون).
• node = میزبان قابلیت (camera/screen/canvas/system.run).

دامنه‌ها (operator)

دامنه‌های رایج:

• operator.read
• operator.write
• operator.admin
• operator.approvals
• operator.pairing
• operator.talk.secrets

talk.config با includeSecrets: true به operator.talk.secrets (یا operator.admin) نیاز دارد. وقتی رازها گنجانده می‌شوند، سرویس‌گیرنده‌ها باید اعتبارنامه ارائه‌دهنده فعال Talk را از talk.resolved.config.apiKey بخوانند؛ talk.providers.<id>.apiKey در شکل منبع باقی می‌ماند و ممکن است یک شیء SecretRef یا یک رشته پوشیده‌شده باشد.

روش‌های RPC متعلق به Gateway که توسط Plugin ثبت شده‌اند ممکن است دامنه operator خودشان را درخواست کنند، اما پیشوندهای مدیریت هسته رزرو شده (config.*، exec.approvals.*، wizard.*، update.*) همیشه به operator.admin نگاشت می‌شوند.

دامنه روش فقط نخستین دروازه است. برخی دستورهای اسلش که از طریق chat.send قابل دسترسی هستند، افزون بر آن بررسی‌های سخت‌گیرانه‌تری در سطح دستور اعمال می‌کنند. برای نمونه، نوشتن‌های پایدار /config set و /config unset به operator.admin نیاز دارند.

node.pair.approve افزون بر دامنه پایه روش، یک بررسی دامنه اضافی در زمان تأیید نیز دارد:

• درخواست‌های بدون دستور: operator.pairing
• درخواست‌های دارای دستورهای node غیر اجرایی: operator.pairing + operator.write
• درخواست‌هایی که شامل system.run، system.run.prepare، یا system.which هستند: operator.pairing + operator.admin

قابلیت‌ها/دستورها/مجوزها (node)

گره‌ها هنگام اتصال ادعاهای قابلیت را اعلام می‌کنند:

• caps: دسته‌های سطح‌بالای قابلیت مانند camera، canvas، screen، location، voice، و talk.
• commands: فهرست مجاز دستورها برای فراخوانی.
• permissions: کنترل‌های جزئی (مانند screen.record، camera.capture).

Gateway این موارد را به‌عنوان ادعا در نظر می‌گیرد و فهرست‌های مجاز سمت سرور را اعمال می‌کند.

حضور

• system-presence ورودی‌هایی را برمی‌گرداند که با هویت دستگاه کلیدگذاری شده‌اند.
• ورودی‌های حضور شامل deviceId، roles، و scopes هستند تا UIها بتوانند برای هر دستگاه یک ردیف واحد نشان دهند، حتی وقتی دستگاه هم به‌عنوان operator و هم به‌عنوان node متصل می‌شود.
• node.list شامل فیلدهای اختیاری lastSeenAtMs و lastSeenReason است. گره‌های متصل، زمان اتصال فعلی خود را به‌عنوان lastSeenAtMs با دلیل connect گزارش می‌کنند؛ گره‌های جفت‌شده همچنین می‌توانند زمانی که یک رویداد قابل اعتماد گره، فراداده جفت‌سازی آن‌ها را به‌روزرسانی می‌کند، حضور پس‌زمینه پایدار را گزارش کنند.

رویداد زنده بودن پس‌زمینه گره

گره‌ها می‌توانند node.event را با event: "node.presence.alive" فراخوانی کنند تا ثبت شود که یک گره جفت‌شده در طول یک بیدارسازی پس‌زمینه زنده بوده، بدون اینکه به‌عنوان متصل علامت‌گذاری شود.

{  "event": "node.presence.alive",  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"}

trigger یک enum بسته است: background، silent_push، bg_app_refresh، significant_location، manual، یا connect. رشته‌های ناشناخته trigger پیش از پایداری توسط Gateway به background عادی‌سازی می‌شوند. این رویداد فقط برای نشست‌های دستگاه node احراز هویت‌شده پایدار است؛ نشست‌های بدون دستگاه یا جفت‌نشده handled: false را برمی‌گردانند.

Gatewayهای موفق یک نتیجه ساختاریافته برمی‌گردانند:

{  "ok": true,  "event": "node.presence.alive",  "handled": true,  "reason": "persisted"}

Gatewayهای قدیمی‌تر ممکن است هنوز برای node.event مقدار { "ok": true } را برگردانند؛ سرویس‌گیرنده‌ها باید آن را به‌عنوان یک RPC تأییدشده در نظر بگیرند، نه به‌عنوان پایداری حضور بادوام.

دامنه‌بندی رویدادهای پخش

رویدادهای پخش WebSocket که از سرور ارسال می‌شوند با دامنه محدود می‌شوند تا نشست‌های محدود به جفت‌سازی یا فقط گره، محتوای نشست را به‌صورت منفعل دریافت نکنند.

• فریم‌های چت، عامل، و نتیجه ابزار (از جمله رویدادهای agent جریانی و نتایج فراخوانی ابزار) دست‌کم به operator.read نیاز دارند. نشست‌های بدون operator.read این فریم‌ها را به‌طور کامل رد می‌کنند.
• پخش‌های plugin.* تعریف‌شده توسط Plugin بسته به اینکه Plugin چگونه آن‌ها را ثبت کرده است، به operator.write یا operator.admin محدود می‌شوند.
• رویدادهای وضعیت و انتقال (heartbeat، presence، tick، چرخه عمر اتصال/قطع اتصال، و مانند آن) بدون محدودیت باقی می‌مانند تا سلامت انتقال برای هر نشست احراز هویت‌شده قابل مشاهده بماند.
• خانواده‌های ناشناخته رویدادهای پخش به‌صورت پیش‌فرض با دامنه محدود می‌شوند (بسته در صورت خطا)، مگر اینکه یک handler ثبت‌شده صراحتاً آن‌ها را آزادتر کند.

هر اتصال سرویس‌گیرنده شماره توالی مخصوص همان سرویس‌گیرنده را نگه می‌دارد تا پخش‌ها روی همان سوکت ترتیب یکنواخت را حفظ کنند، حتی وقتی سرویس‌گیرنده‌های مختلف زیرمجموعه‌های متفاوتی از جریان رویداد را پس از فیلتر دامنه می‌بینند.

خانواده‌های رایج روش‌های RPC

سطح عمومی WS گسترده‌تر از نمونه‌های handshake/auth بالا است. این یک خروجی تولیدشده نیست — hello-ok.features.methods یک فهرست محافظه‌کارانه برای کشف قابلیت است که از src/gateway/server-methods-list.ts به‌علاوه exportهای روش بارگذاری‌شده Plugin/channel ساخته شده است. آن را به‌عنوان کشف قابلیت در نظر بگیرید، نه یک شمارش کامل از src/gateway/server-methods/*.ts.

خانواده‌های رویداد رایج

• chat: به‌روزرسانی‌های چت UI مانند chat.inject و سایر رویدادهای چت فقط مربوط به رونوشت. در نسخهٔ ۴ پروتکل، payloadهای دلتا deltaText را حمل می‌کنند؛ message عکس‌برداشت تجمعی دستیار باقی می‌ماند. جایگزینی‌های غیرپیشوندی replace=true را تنظیم می‌کنند و از deltaText به‌عنوان متن جایگزین استفاده می‌کنند.
• session.message، session.operation و session.tool: به‌روزرسانی‌های رونوشت، عملیات نشست در جریان، و جریان رویداد برای یک نشست مشترک‌شده.
• sessions.changed: نمایهٔ نشست یا فراداده تغییر کرده است.
• presence: به‌روزرسانی‌های عکس‌برداشت حضور سیستم.
• tick: رویداد دوره‌ای keepalive / زنده‌بودن.
• health: به‌روزرسانی عکس‌برداشت سلامت gateway.
• heartbeat: به‌روزرسانی جریان رویداد Heartbeat.
• cron: رویداد تغییر اجرای/کار cron.
• shutdown: اعلان خاموش‌شدن gateway.
• node.pair.requested / node.pair.resolved: چرخهٔ عمر جفت‌سازی Node.
• node.invoke.request: پخش درخواست فراخوانی Node.
• device.pair.requested / device.pair.resolved: چرخهٔ عمر دستگاه جفت‌شده.
• voicewake.changed: پیکربندی trigger واژهٔ بیدارباش تغییر کرده است.
• exec.approval.requested / exec.approval.resolved: چرخهٔ عمر تأیید اجرا.
• plugin.approval.requested / plugin.approval.resolved: چرخهٔ عمر تأیید Plugin.

متدهای کمک‌کنندهٔ Node

• Nodeها می‌توانند skills.bins را فراخوانی کنند تا فهرست فعلی فایل‌های اجرایی skill را برای بررسی‌های اجازهٔ خودکار واکشی کنند.

RPCهای دفتر وظایف

کلاینت‌های اپراتور می‌توانند رکوردهای وظیفهٔ پس‌زمینهٔ Gateway را از طریق RPCهای دفتر وظایف بررسی و لغو کنند. این متدها خلاصه‌های پالایش‌شدهٔ وظیفه را برمی‌گردانند، نه وضعیت خام زمان اجرا.

• tasks.list به operator.read نیاز دارد.
  • پارامترها: status اختیاری ("queued"، "running"، "completed"، "failed"، "cancelled" یا "timed_out") یا آرایه‌ای از آن وضعیت‌ها، agentId اختیاری، sessionKey اختیاری، limit اختیاری از 1 تا 500، و رشتهٔ اختیاری cursor.
  • نتیجه: { "tasks": TaskSummary[], "nextCursor"?: string }.
• tasks.get به operator.read نیاز دارد.
  • پارامترها: { "taskId": string }.
  • نتیجه: { "task": TaskSummary }.
  • شناسه‌های وظیفهٔ ناموجود، شکل خطای not-found متعلق به Gateway را برمی‌گردانند.
• tasks.cancel به operator.write نیاز دارد.
  • پارامترها: { "taskId": string, "reason"?: string }.
  • نتیجه: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }.
  • found گزارش می‌دهد که آیا دفتر، وظیفهٔ مطابقی داشته است یا نه. cancelled گزارش می‌دهد که آیا زمان اجرا لغو را پذیرفته یا ثبت کرده است.

TaskSummary شامل id، status و فرادادهٔ اختیاری مانند kind، runtime، title، agentId، sessionKey، childSessionKey، ownerKey، runId، taskId، flowId، parentTaskId، sourceId، timestampها، پیشرفت، خلاصهٔ پایانی و متن خطای پالایش‌شده است. agentId عاملی را شناسایی می‌کند که وظیفه را اجرا می‌کند؛ sessionKey و ownerKey زمینهٔ درخواست‌کننده و کنترل را حفظ می‌کنند.

متدهای کمک‌کنندهٔ اپراتور

• اپراتورها می‌توانند commands.list (operator.read) را برای دریافت فهرست دستورهای زمان اجرای یک عامل فراخوانی کنند.
  • agentId اختیاری است؛ برای خواندن فضای کاری عامل پیش‌فرض آن را حذف کنید.
  • scope کنترل می‌کند که name اصلی کدام سطح را هدف بگیرد:
    • text توکن دستور متنی اصلی را بدون / ابتدایی برمی‌گرداند
    • native و مسیر پیش‌فرض both، در صورت وجود، نام‌های بومی آگاه از ارائه‌دهنده را برمی‌گردانند
  • textAliases نام‌های مستعار دقیق اسلش‌دار مانند /model و /m را حمل می‌کند.
  • nativeName نام دستور بومی آگاه از ارائه‌دهنده را، وقتی وجود داشته باشد، حمل می‌کند.
  • provider اختیاری است و فقط بر نام‌گذاری بومی و در دسترس بودن دستورهای Plugin بومی اثر می‌گذارد.
  • includeArgs=false فراداده آرگومان سریال‌شده را از پاسخ حذف می‌کند.
• اپراتورها می‌توانند tools.catalog (operator.read) را برای دریافت کاتالوگ ابزار زمان اجرا برای یک عامل فراخوانی کنند. پاسخ شامل ابزارهای گروه‌بندی‌شده و فراداده منشأ است:
  • source: core یا plugin
  • pluginId: مالک Plugin وقتی source="plugin" باشد
  • optional: اینکه ابزار Plugin اختیاری است یا نه
• اپراتورها می‌توانند tools.effective (operator.read) را برای دریافت فهرست ابزار مؤثر در زمان اجرا برای یک نشست فراخوانی کنند.
  • sessionKey الزامی است.
  • Gateway به‌جای پذیرش زمینه احراز هویت یا تحویلِ ارائه‌شده توسط فراخوان، زمینه زمان اجرای قابل اعتماد را سمت سرور از نشست استخراج می‌کند.
  • پاسخ، یک تصویر مشتق‌شده سمت سرور و محدود به نشست از فهرست فعال است، شامل ابزارهای هسته، Plugin، کانال، و ابزارهای سرور MCP که از قبل کشف شده‌اند.
  • tools.effective برای MCP فقط خواندنی است: ممکن است کاتالوگ MCP یک نشست گرم را از طریق سیاست نهایی ابزار تصویر کند، اما زمان‌های اجرای MCP را ایجاد نمی‌کند، ترابری‌ها را وصل نمی‌کند، یا tools/list صادر نمی‌کند. اگر هیچ کاتالوگ گرم مطابقی وجود نداشته باشد، پاسخ ممکن است اعلانی مانند mcp-not-yet-connected، mcp-not-yet-listed، یا mcp-stale-catalog را شامل شود.
  • ورودی‌های ابزار مؤثر از source="core"، source="plugin"، source="channel"، یا source="mcp" استفاده می‌کنند.
• اپراتورها می‌توانند tools.invoke (operator.write) را برای فراخوانی یک ابزار در دسترس از همان مسیر سیاست Gateway مانند /tools/invoke فراخوانی کنند.
  • name الزامی است. args، sessionKey، agentId، confirm، و idempotencyKey اختیاری هستند.
  • اگر هم sessionKey و هم agentId وجود داشته باشند، عامل نشست حل‌شده باید با agentId مطابقت داشته باشد.
  • پوشش‌دهنده‌های هسته فقط-مالک مانند cron، gateway، و nodes به هویت مالک/مدیر (operator.admin) نیاز دارند، هرچند خود متد tools.invoke برابر operator.write است.
  • پاسخ یک پوشش رو به SDK با فیلدهای ok، toolName، output اختیاری، و error نوع‌دار است. ردهای تأیید یا سیاست، به‌جای دور زدن خط لوله سیاست ابزار Gateway، در payload مقدار ok:false برمی‌گردانند.
• اپراتورها می‌توانند skills.status (operator.read) را برای دریافت فهرست skill قابل مشاهده برای یک عامل فراخوانی کنند.
  • agentId اختیاری است؛ برای خواندن فضای کاری عامل پیش‌فرض آن را حذف کنید.
  • پاسخ شامل واجد شرایط بودن، نیازمندی‌های موجود نبودن، بررسی‌های پیکربندی، و گزینه‌های نصب پاک‌سازی‌شده است، بدون افشای مقادیر خام secret.
• اپراتورها می‌توانند skills.search و skills.detail (operator.read) را برای فراداده کشف ClawHub فراخوانی کنند.
• اپراتورها می‌توانند skills.upload.begin، skills.upload.chunk، و skills.upload.commit (operator.admin) را برای آماده‌سازی یک آرشیو skill خصوصی پیش از نصب آن فراخوانی کنند. این یک مسیر بارگذاری مدیرانه جداگانه برای کلاینت‌های قابل اعتماد است، نه جریان عادی نصب skill از ClawHub، و به‌طور پیش‌فرض غیرفعال است مگر اینکه skills.install.allowUploadedArchives فعال باشد.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) یک بارگذاری وابسته به آن slug و مقدار force ایجاد می‌کند.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) بایت‌ها را در offset دقیقِ رمزگشایی‌شده اضافه می‌کند.
  • skills.upload.commit({ uploadId, sha256? }) اندازه نهایی و SHA-256 را راستی‌آزمایی می‌کند. Commit فقط بارگذاری را نهایی می‌کند؛ skill را نصب نمی‌کند.
  • آرشیوهای skill بارگذاری‌شده آرشیوهای zip هستند که یک ریشه SKILL.md دارند. نام دایرکتوری داخلی آرشیو هرگز هدف نصب را انتخاب نمی‌کند.
• اپراتورها می‌توانند skills.install (operator.admin) را در سه حالت فراخوانی کنند:
  • حالت ClawHub: { source: "clawhub", slug, version?, force? } یک پوشه skill را در دایرکتوری skills/ فضای کاری عامل پیش‌فرض نصب می‌کند.
  • حالت بارگذاری: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } یک بارگذاری commit‌شده را در دایرکتوری skills/<slug> فضای کاری عامل پیش‌فرض نصب می‌کند. مقدار slug و force باید با درخواست اصلی skills.upload.begin مطابقت داشته باشند. این حالت رد می‌شود مگر اینکه skills.install.allowUploadedArchives فعال باشد. این تنظیم بر نصب‌های ClawHub اثر نمی‌گذارد.
  • حالت نصب‌کننده Gateway: { name, installId, timeoutMs? } یک کنش اعلام‌شده metadata.openclaw.install را روی میزبان Gateway اجرا می‌کند. کلاینت‌های قدیمی‌تر ممکن است هنوز dangerouslyForceUnsafeInstall را ارسال کنند؛ این فیلد منسوخ شده، فقط برای سازگاری پروتکل پذیرفته می‌شود، و نادیده گرفته می‌شود. برای تصمیم‌های نصب تحت مالکیت اپراتور از security.installPolicy استفاده کنید.
• اپراتورها می‌توانند skills.update (operator.admin) را در دو حالت فراخوانی کنند:
  • حالت ClawHub یک slug رهگیری‌شده یا همه نصب‌های رهگیری‌شده ClawHub را در فضای کاری عامل پیش‌فرض به‌روزرسانی می‌کند.
  • حالت پیکربندی مقادیر skills.entries.<skillKey> مانند enabled، apiKey، و env را patch می‌کند.

نماهای models.list

models.list یک پارامتر اختیاری view می‌پذیرد:

• حذف‌شده یا "default": رفتار فعلی زمان اجرا. اگر agents.defaults.models پیکربندی شده باشد، پاسخ کاتالوگ مجاز است، شامل مدل‌های کشف‌شده به‌صورت پویا برای ورودی‌های provider/*. در غیر این صورت پاسخ، کاتالوگ کامل Gateway است.
• "configured": رفتار در اندازه انتخاب‌گر. اگر agents.defaults.models پیکربندی شده باشد، همچنان اولویت دارد، شامل کشف محدود به ارائه‌دهنده برای ورودی‌های provider/*. بدون یک allowlist، پاسخ از ورودی‌های صریح models.providers.*.models استفاده می‌کند و فقط وقتی هیچ ردیف مدل پیکربندی‌شده‌ای وجود نداشته باشد به کاتالوگ کامل برمی‌گردد.
• "all": کاتالوگ کامل Gateway، با دور زدن agents.defaults.models. از این برای تشخیص و رابط‌های کاربری کشف استفاده کنید، نه انتخاب‌گرهای عادی مدل.

تأییدهای اجرا

• وقتی یک درخواست exec به تأیید نیاز داشته باشد، Gateway رویداد exec.approval.requested را پخش می‌کند.
• کلاینت‌های اپراتور با فراخوانی exec.approval.resolve حل می‌کنند (به scope operator.approvals نیاز دارد).
• برای host=node، exec.approval.request باید systemRunPlan را شامل شود (argv/cwd/rawCommand/فراداده نشستِ canonical). درخواست‌هایی که systemRunPlan ندارند رد می‌شوند.
• پس از تأیید، فراخوانی‌های فورواردشده node.invoke system.run همان systemRunPlan canonical را به‌عنوان زمینه معتبر دستور/cwd/نشست دوباره استفاده می‌کنند.
• اگر فراخوان بین آماده‌سازی و فوروارد نهاییِ تأییدشده system.run مقدار command، rawCommand، cwd، agentId، یا sessionKey را تغییر دهد، Gateway به‌جای اعتماد به payload تغییریافته، اجرا را رد می‌کند.

fallback تحویل عامل

• درخواست‌های agent می‌توانند deliver=true را برای درخواست تحویل خروجی شامل کنند.
• bestEffortDeliver=false رفتار سخت‌گیرانه را نگه می‌دارد: هدف‌های تحویل حل‌نشده یا فقط-داخلی INVALID_REQUEST برمی‌گردانند.
• bestEffortDeliver=true اجازه می‌دهد وقتی هیچ مسیر قابل تحویل خارجی قابل حل نباشد، به اجرای فقط-نشست fallback شود (برای مثال نشست‌های داخلی/webchat یا پیکربندی‌های چندکاناله مبهم).
• نتیجه‌های نهایی agent ممکن است وقتی تحویل درخواست شده باشد result.deliveryStatus را شامل شوند، با استفاده از همان وضعیت‌های sent، suppressed، partial_failed، و failed که برای openclaw agent --json --deliver مستند شده‌اند.

نسخه‌بندی

• PROTOCOL_VERSION در packages/gateway-protocol/src/version.ts قرار دارد.
• کلاینت‌ها minProtocol + maxProtocol را ارسال می‌کنند؛ سرور بازه‌هایی را که پروتکل فعلی‌اش را شامل نشوند رد می‌کند. کلاینت‌ها و سرورهای فعلی به پروتکل v4 نیاز دارند.
• Schemaها + مدل‌ها از تعریف‌های TypeBox تولید می‌شوند:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

ثابت‌های کلاینت

کلاینت مرجع در src/gateway/client.ts از این پیش‌فرض‌ها استفاده می‌کند. مقادیر در سراسر پروتکل v4 پایدار هستند و baseline مورد انتظار برای کلاینت‌های شخص ثالث‌اند.

سرور مقادیر مؤثر policy.tickIntervalMs، policy.maxPayload، و policy.maxBufferedBytes را در hello-ok اعلام می‌کند؛ کلاینت‌ها باید به‌جای پیش‌فرض‌های پیش از handshake، همان مقادیر را رعایت کنند.

احراز هویت

• احراز هویت Gateway با راز مشترک، بسته به حالت احراز هویت پیکربندی‌شده، از connect.params.auth.token یا connect.params.auth.password استفاده می‌کند.
• حالت‌های دارای هویت، مانند Tailscale Serve (gateway.auth.allowTailscale: true) یا gateway.auth.mode: "trusted-proxy" غیر loopback، بررسی احراز هویت اتصال را از سرآیندهای درخواست، به‌جای connect.params.auth.*، برآورده می‌کنند.
• حالت ورودی خصوصی gateway.auth.mode: "none" احراز هویت اتصال با راز مشترک را کاملا رد می‌کند؛ این حالت را روی ورودی عمومی/نامطمئن در معرض دسترس قرار ندهید.
• پس از جفت‌سازی، Gateway یک توکن دستگاه صادر می‌کند که به نقش اتصال
  • دامنه‌ها محدود است. این توکن در hello-ok.auth.deviceToken برگردانده می‌شود و باید برای اتصال‌های آینده توسط کلاینت پایدار شود.
• کلاینت‌ها باید hello-ok.auth.deviceToken اصلی را پس از هر اتصال موفق پایدار کنند.
• اتصال مجدد با آن توکن دستگاه ذخیره‌شده باید مجموعه دامنه تاییدشده ذخیره‌شده برای آن توکن را نیز دوباره استفاده کند. این کار دسترسی خواندن/کاوش/وضعیت را که قبلا اعطا شده حفظ می‌کند و از فروکاستن بی‌صدای اتصال‌های مجدد به یک دامنه ضمنی باریک‌تر و فقط مدیریتی جلوگیری می‌کند.
• سرهم‌بندی احراز هویت اتصال در سمت کلاینت (selectConnectAuth در src/gateway/client.ts):
  • auth.password مستقل است و هر زمان تنظیم شده باشد همیشه ارسال می‌شود.
  • auth.token به‌ترتیب اولویت پر می‌شود: ابتدا توکن مشترک صریح، سپس یک deviceToken صریح، سپس یک توکن ذخیره‌شده به‌ازای هر دستگاه (کلیدشده با deviceId + role).
  • auth.bootstrapToken فقط زمانی فرستاده می‌شود که هیچ‌کدام از موارد بالا یک auth.token را به‌دست نیاورده باشند. توکن مشترک یا هر توکن دستگاه به‌دست‌آمده‌ای آن را سرکوب می‌کند.
  • ارتقای خودکار یک توکن دستگاه ذخیره‌شده در تلاش مجدد یک‌باره AUTH_TOKEN_MISMATCH فقط به نقطه‌های پایانی مورد اعتماد محدود است — loopback، یا wss:// با tlsFingerprint سنجاق‌شده. wss:// عمومی بدون سنجاق‌کردن واجد شرایط نیست.
• راه‌اندازی bootstrap داخلی با کد راه‌اندازی، hello-ok.auth.deviceToken نود اصلی به‌همراه یک توکن عملگر محدود را در hello-ok.auth.deviceTokens برای تحویل موبایل مورد اعتماد برمی‌گرداند. توکن عملگر شامل operator.talk.secrets برای خواندن پیکربندی بومی Talk است، اما دامنه‌های تغییر جفت‌سازی و operator.admin را مستثنی می‌کند.
• هنگامی که bootstrap کد راه‌اندازی غیرخط‌مبنا منتظر تایید است، جزئیات PAIRING_REQUIRED شامل recommendedNextStep: "wait_then_retry"، retryable: true، و pauseReconnect: false است. کلاینت‌ها باید تا زمانی که درخواست تایید شود یا توکن نامعتبر شود، با همان توکن bootstrap به اتصال مجدد ادامه دهند.
• hello-ok.auth.deviceTokens را فقط زمانی پایدار کنید که اتصال از احراز هویت bootstrap روی یک انتقال مورد اعتماد مانند wss:// یا جفت‌سازی loopback/محلی استفاده کرده باشد.
• اگر کلاینت یک deviceToken صریح یا scopes صریح ارائه کند، آن مجموعه دامنه درخواست‌شده توسط فراخواننده مرجع باقی می‌ماند؛ دامنه‌های کش‌شده فقط زمانی دوباره استفاده می‌شوند که کلاینت از توکن ذخیره‌شده به‌ازای هر دستگاه دوباره استفاده کند.
• توکن‌های دستگاه را می‌توان از طریق device.token.rotate و device.token.revoke چرخاند/لغو کرد (به دامنه operator.pairing نیاز دارد). چرخاندن یا لغو یک نود یا نقش غیرعملگر دیگر همچنین به operator.admin نیاز دارد.
• device.token.rotate فراداده چرخش را برمی‌گرداند. این متد توکن bearer جایگزین را فقط برای فراخوانی‌های همان دستگاه که از قبل با همان توکن دستگاه احراز هویت شده‌اند بازتاب می‌دهد، تا کلاینت‌های فقط‌توکن بتوانند جایگزین خود را پیش از اتصال مجدد پایدار کنند. چرخش‌های مشترک/مدیریتی توکن bearer را بازتاب نمی‌دهند.
• صدور، چرخش، و لغو توکن محدود به مجموعه نقش تاییدشده‌ای می‌ماند که در ورودی جفت‌سازی آن دستگاه ثبت شده است؛ تغییر توکن نمی‌تواند دامنه را گسترش دهد یا نقش دستگاهی را هدف بگیرد که تایید جفت‌سازی هرگز اعطا نکرده است.
• برای نشست‌های توکن دستگاه جفت‌شده، مدیریت دستگاه خوددامنه است مگر این‌که فراخواننده operator.admin نیز داشته باشد: فراخواننده‌های غیرمدیر فقط می‌توانند توکن عملگر ورودی دستگاه خودشان را مدیریت کنند. مدیریت توکن نود و دیگر توکن‌های غیرعملگر فقط مدیریتی است، حتی برای دستگاه خود فراخواننده.
• device.token.rotate و device.token.revoke همچنین مجموعه دامنه توکن عملگر هدف را در برابر دامنه‌های نشست فعلی فراخواننده بررسی می‌کنند. فراخواننده‌های غیرمدیر نمی‌توانند توکن عملگری گسترده‌تر از آنچه خودشان دارند را بچرخانند یا لغو کنند.
• شکست‌های احراز هویت شامل error.details.code به‌همراه راهنمایی‌های بازیابی هستند:
  • error.details.canRetryWithDeviceToken (بولی)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• رفتار کلاینت برای AUTH_TOKEN_MISMATCH:
  • کلاینت‌های مورد اعتماد می‌توانند یک تلاش مجدد محدود با توکن کش‌شده به‌ازای هر دستگاه انجام دهند.
  • اگر آن تلاش مجدد شکست بخورد، کلاینت‌ها باید حلقه‌های اتصال مجدد خودکار را متوقف کنند و راهنمای اقدام عملگر را نمایش دهند.
• AUTH_SCOPE_MISMATCH یعنی توکن دستگاه شناسایی شد اما نقش/دامنه‌های درخواست‌شده را پوشش نمی‌دهد. کلاینت‌ها نباید این را به‌عنوان توکن بد نمایش دهند؛ از عملگر بخواهید دوباره جفت‌سازی کند یا قرارداد دامنه باریک‌تر/گسترده‌تر را تایید کند.

هویت دستگاه + جفت‌سازی

• نودها باید یک هویت دستگاه پایدار (device.id) داشته باشند که از اثرانگشت keypair مشتق شده است.
• Gatewayها برای هر دستگاه + نقش توکن صادر می‌کنند.
• تاییدهای جفت‌سازی برای شناسه‌های دستگاه جدید لازم هستند، مگر این‌که تایید خودکار محلی فعال باشد.
• تایید خودکار جفت‌سازی حول اتصال‌های مستقیم local loopback متمرکز است.
• OpenClaw همچنین یک مسیر self-connect محدود محلی در backend/container برای جریان‌های کمکی راز مشترک مورد اعتماد دارد.
• اتصال‌های tailnet همان میزبان یا LAN همچنان برای جفت‌سازی remote تلقی می‌شوند و به تایید نیاز دارند.
• کلاینت‌های WS معمولا هویت device را هنگام connect شامل می‌کنند (عملگر + نود). تنها استثناهای عملگر بدون دستگاه، مسیرهای اعتماد صریح هستند:
  • gateway.controlUi.allowInsecureAuth=true برای سازگاری HTTP ناامن فقط localhost.
  • احراز هویت موفق Control UI عملگر با gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass، کاهش شدید امنیت).
  • RPCهای backend مستقیم-loopback gateway-client روی مسیر کمکی داخلی رزروشده.
• حذف هویت دستگاه پیامدهای دامنه دارد. وقتی اتصال عملگر بدون دستگاه از طریق یک مسیر اعتماد صریح مجاز می‌شود، OpenClaw همچنان دامنه‌های خوداظهارشده را به یک مجموعه خالی پاک می‌کند مگر این‌که آن مسیر یک استثنای نام‌گذاری‌شده برای حفظ دامنه داشته باشد. سپس متدهای محدودشده با دامنه با missing scope شکست می‌خورند.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true یک مسیر حفظ دامنه break-glass برای Control UI است. این گزینه دامنه‌ها را به کلاینت‌های WebSocket سفارشی دلخواه backend یا CLI-شکل اعطا نمی‌کند.
• مسیر کمکی backend رزروشده مستقیم-loopback gateway-client دامنه‌ها را فقط برای RPCهای داخلی control-plane محلی حفظ می‌کند؛ شناسه‌های backend سفارشی این استثنا را دریافت نمی‌کنند.
• همه اتصال‌ها باید nonce ارائه‌شده توسط سرور در connect.challenge را امضا کنند.

عیب‌یابی مهاجرت احراز هویت دستگاه

برای کلاینت‌های قدیمی که هنوز از رفتار امضای پیش از challenge استفاده می‌کنند، connect اکنون کدهای جزئیات DEVICE_AUTH_* را زیر error.details.code با یک error.details.reason پایدار برمی‌گرداند.

شکست‌های رایج مهاجرت:

هدف مهاجرت:

• همیشه منتظر connect.challenge بمانید.
• payload نسخه 2 را که شامل nonce سرور است امضا کنید.
• همان nonce را در connect.params.device.nonce بفرستید.
• payload امضای ترجیحی v3 است، که علاوه بر فیلدهای دستگاه/کلاینت/نقش/دامنه‌ها/توکن/nonce، platform و deviceFamily را نیز bind می‌کند.
• امضاهای قدیمی v2 برای سازگاری همچنان پذیرفته می‌شوند، اما pinning فراداده دستگاه جفت‌شده همچنان سیاست فرمان را در اتصال مجدد کنترل می‌کند.

TLS + سنجاق‌کردن

• TLS برای اتصال‌های WS پشتیبانی می‌شود.
• کلاینت‌ها می‌توانند به‌صورت اختیاری اثرانگشت گواهی gateway را سنجاق کنند (پیکربندی gateway.tls به‌همراه gateway.remote.tlsFingerprint یا CLI --tls-fingerprint را ببینید).

دامنه

این پروتکل API کامل gateway را در معرض دسترس قرار می‌دهد (وضعیت، کانال‌ها، مدل‌ها، چت، عامل، نشست‌ها، نودها، تاییدها، و غیره). سطح دقیق توسط طرحواره‌های TypeBox در packages/gateway-protocol/src/schema.ts تعریف شده است.

مرتبط

• پروتکل Bridge
• runbook Gateway