پروتکل Gateway

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

بسته‌های npm

این بسته‌ها همراه با چرخه‌های انتشار OpenClaw عرضه می‌شوند. در طول عرضهٔ اولیه، ممکن است npm تا زمان انتشار نخستین نسخهٔ حاوی بسته، E404 را برگرداند.

• @openclaw/gateway-protocol طرح‌واره‌ها، اعتبارسنج‌ها، نوع‌های TypeScript، ابزارهای کمکی سبک برای فریم و خطا و ثابت‌های نسخه را منتشر می‌کند. فایل tarball آن شامل قرارداد ماشین‌خوانِ تولیدشدهٔ protocol.schema.json است.
• @openclaw/gateway-client کلاینت مرجع Node و یک ورودی امن برای مرورگر را در @openclaw/gateway-client/browser منتشر می‌کند.

برای راهنمایی دربارهٔ چرخهٔ عمر برنامه، به ساخت کلاینت Gateway مراجعه کنید. برای برنامه‌هایی که بر Gateway به‌عنوان یک فرایند فرزند نظارت می‌کنند، به جاسازی OpenClaw مراجعه کنید.

انتقال و فریم‌بندی

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

شکل فریم‌ها:

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

خطاهای پاسخ از { code, message, details?, retryable?, retryAfterMs? } استفاده می‌کنند. کلاینت‌ها باید بر اساس code و details.code شاخه‌بندی کنند؛ message برای انسان خوانا باقی می‌ماند و می‌تواند تغییر کند، مگر آنجا که یادداشت سازگاری خلاف آن را بیان کند. شکست‌های مجوزدهی در سطح متد از code: "FORBIDDEN" در سطح بالا همراه با جزئیات ساختاریافتهٔ دامنه‌های مفقود استفاده می‌کنند:

• دامنهٔ مفقود: { code: "MISSING_SCOPE", missingScope, requiredScopes }. requiredScopes مجموعهٔ کامل دامنه‌های شناخته‌شده برای عملیات درخواستی است. پیام قدیمی missing scope: <scope> برای کلاینت‌های قدیمی‌تر حفظ شده است.

کلاینت‌ها باید ابتدا details را بخوانند و از پیام قدیمی فقط به‌عنوان راهکار بازگشتی سازگاری استفاده کنند. readMissingScopeError و readMissingScopeErrorDetails از @openclaw/gateway-protocol/gateway-error-details صادر می‌شوند؛ کلاینت Gateway امن برای مرورگر آن‌ها را دوباره از @openclaw/gateway-client/browser صادر می‌کند.

طرح‌واره‌ها با نام‌های GatewayErrorDetailsSchema و MissingScopeErrorDetailsSchema از @openclaw/gateway-protocol/schema صادر می‌شوند. شکست‌های دامنهٔ HTTP، شیء MISSING_SCOPE را زیر error.details بازتاب می‌دهند و از وضعیت HTTP برابر با 403 استفاده می‌کنند.

متدهای دارای اثر جانبی به کلیدهای هم‌توانی نیاز دارند (طرح‌واره را ببینید).

دست‌دهی

Gateway یک چالش پیش از اتصال ارسال می‌کند:

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

کلاینت با connect پاسخ می‌دهد:

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 4,    "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 با hello-ok پاسخ می‌دهد:

{  "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    }  }}

server، features، snapshot، policy و auth همگی برای HelloOkSchema (packages/gateway-protocol/src/schema/frames.ts) الزامی هستند. auth نقش/دامنه‌های مذاکره‌شده را حتی زمانی که هیچ توکن دستگاهی صادر نشده باشد گزارش می‌کند (شکل بالا). pluginSurfaceUrls اختیاری است و نام‌های سطوح Plugin (برای مثال canvas) را به URLهای میزبانی‌شده و دارای دامنه نگاشت می‌کند؛ ممکن است منقضی شود، بنابراین Nodeها node.pluginSurface.refresh را با { "surface": "canvas" } فراخوانی می‌کنند تا یک ورودی تازه دریافت کنند. مسیر منسوخ‌شدهٔ canvasHostUrl / canvasCapability / node.canvas.capability.refresh پشتیبانی نمی‌شود؛ از سطوح Plugin استفاده کنید. appliedConfigHash اختیاریِ اسنپ‌شات، بازبینی پیکربندی مبدأِ حل‌شده‌ای است که زمان اجرای فعال Gateway پذیرفته است. کلاینت‌ها می‌توانند آن را با config.get.configRevisionHash مقایسه کنند تا مشخص شود آیا یک پیکربندی ذخیره‌شدهٔ جدیدتر همچنان به راه‌اندازی مجدد نیاز دارد یا نه. config.get.hash همچنان بازبینی خام فایل ریشه است که نگهبان‌های تعارض نوشتن پیکربندی از آن استفاده می‌کنند.

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

وقتی توکن دستگاه صادر شود، hello-ok.auth آن را اضافه می‌کند:

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

راه‌اندازی اولیهٔ داخلی با کد QR/راه‌اندازی، یک مسیر تحویل به موبایل است. اتصال موفق با کد راه‌اندازی پایه، یک توکن اصلی Node به‌علاوهٔ یک توکن اپراتور محدود برمی‌گرداند:

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

این تحویل اپراتور عمداً محدود است: برای آغاز چرخهٔ اپراتور موبایل و راه‌اندازی بومی، از جمله operator.talk.secrets برای خواندن پیکربندی Talk، کافی است، اما هیچ دامنه‌ای برای تغییر جفت‌سازی و هیچ operator.admin ندارد. دسترسی گسترده‌تر به جفت‌سازی/مدیریت به یک جریان جداگانهٔ جفت‌سازی یا توکنِ تأییدشده نیاز دارد. hello-ok.auth.deviceTokens را فقط زمانی پایدار ذخیره کنید که احراز هویت راه‌اندازی اولیه از طریق یک انتقال مورداعتماد (wss:// یا جفت‌سازی loopback/محلی) اجرا شده باشد.

کلاینت‌های مورداعتمادِ بک‌اند در همان فرایند (client.id: "gateway-client"، client.mode: "backend") می‌توانند در اتصال‌های مستقیم loopback هنگام احراز هویت با توکن/گذرواژهٔ مشترک Gateway، device را حذف کنند. این مسیر مختص RPCهای داخلی صفحهٔ کنترل است (برای مثال به‌روزرسانی نشست‌های عامل فرعی) و مانع از آن می‌شود که خطوط پایهٔ قدیمی جفت‌سازی CLI/دستگاه، کار محلی بک‌اند را مسدود کنند. کلاینت‌های راه‌دور، دارای مبدأ مرورگر، Node و کلاینت‌های صریحِ توکن دستگاه/هویت دستگاه همچنان از بررسی‌های عادی جفت‌سازی و ارتقای دامنه عبور می‌کنند.

نقش Worker و پروتکل بسته

Workerهای ابری از یک ورودی اختصاصی loopback از طریق تونل SSH تحت مالکیت Gateway و سنجاق‌شده به کلید میزبان استفاده می‌کنند. این ورودی فقط هویت Worker را می‌پذیرد و هرگز احراز هویت عمومی، رویدادهای Node، RPCهای اپراتور یا متدهای Plugin را هدایت نمی‌کند. یک connect سخت‌گیرانه، اعتبارنامهٔ کوتاه‌عمر و هش‌شده در حالت ذخیره را که به محیط، هش بسته، دورهٔ مالک، نسخهٔ مجموعهٔ RPC، زمان انقضا و یک نشست تهی‌پذیر مقید است اعتبارسنجی می‌کند؛ همچنین نسخه و مجموعهٔ قابلیت‌های فعلی را جداگانه بررسی می‌کند. موفقیت، حداقل worker-hello-ok را برمی‌گرداند؛ مذاکرهٔ قابلیت‌ها مستقل از نسخهٔ عمومی پروتکل است. فریم‌ها زیر 64 KiB باقی می‌مانند، به‌جز فریم مذاکره‌شدهٔ worker.inference.start که می‌تواند تا 25 MiB باشد. فهرست مجاز بسته شامل worker.heartbeat، worker.transcript.commit، worker.live-event، worker.inference.start و worker.inference.cancel است.

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

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

کلاینت‌های اپراتور می‌توانند قابلیت‌های اختیاری را در connect.params.caps اعلام کنند:

• tool-events: رویدادهای ساختاریافتهٔ چرخهٔ عمر ابزار را می‌پذیرد.
• inline-widgets: می‌تواند نتایج ابزارِ ویجت درون‌خطی میزبانی‌شده را رندر کند.

قابلیت‌های کلاینت، کلاینت متصل را توصیف می‌کنند، نه مجوزدهی را. ابزارهای عامل می‌توانند قابلیت‌های الزامی را اعلام کنند؛ Gateway آن ابزارها را حذف می‌کند، مگر اینکه همهٔ الزامات در caps کلاینت مبدأ وجود داشته باشند. اجراهای برخاسته از کانال هیچ قابلیت کلاینت Gateway ندارند، بنابراین ابزارهای محدودشده بر اساس قابلیت، حتی وقتی سیاست ابزار صراحتاً آن‌ها را مجاز می‌کند، در دسترس نیستند.

نمونهٔ اتصال Node

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 4,    "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": "…"    }  }}

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

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

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

نقش‌ها و دامنه‌ها

برای مدل کامل دامنهٔ اپراتور، بررسی‌های زمان تأیید و معناشناسی راز مشترک، به دامنه‌های اپراتور مراجعه کنید.

نقش‌ها:

• operator: کلاینت صفحهٔ کنترل (CLI/UI/اتوماسیون).
• node: میزبان قابلیت (camera/screen/canvas/system.run).
• worker: میزبان اجرای ابری روی پروتکل اختصاصی و بستهٔ Worker.

دامنه‌های اپراتور (src/gateway/operator-scopes.ts)، مجموعهٔ کامل بسته:

• 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.admin (src/shared/gateway-method-policy.ts) نگاشت می‌شوند: config.*، exec.approvals.*، wizard.*، update.*.

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

node.pair.approve افزون بر دامنهٔ پایهٔ متد (operator.pairing)، یک بررسی دامنهٔ اضافی در زمان تأیید دارد که بر اساس commands اعلام‌شدهٔ درخواست در انتظار (src/infra/node-pairing-authz.ts) انجام می‌شود:

قابلیت‌ها/فرمان‌ها/مجوزها (Node)

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

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

Gateway این موارد را به‌عنوان ادعا در نظر می‌گیرد و فهرست‌های مجاز را در سمت سرور اعمال می‌کند. Nodeهای متصل می‌توانند پس از اتصال یا اتصال مجدد موفق، توصیفگرهای اختیاری ابزار Plugin یا MCP را که برای عامل قابل‌مشاهده‌اند با node.pluginTools.update منتشر کنند. میزبان‌های Node بدون رابط برای اعمال تغییرات اعلانی موجودی MCP دوباره راه‌اندازی می‌شوند. این روش به‌روزرسانی تنها مسیر انتشار است؛ توصیفگرهای ابزار Plugin در پارامترهای connect پذیرفته نمی‌شوند. هر توصیفگر باید از یک name ابزار امن برای ارائه‌دهنده استفاده کند و یک command را در فهرست مجاز فرمان‌های کنونی Node نام ببرد. Gateway به فرادادهٔ توصیفگر از Node جفت‌شده اعتماد می‌کند، توصیفگرهای خارج از سطح فرمان تأییدشده را فیلتر می‌کند، هنگام قطع اتصال Node آن‌ها را حذف می‌کند و تلاش‌های اپراتور برای تغییر کاتالوگ Node دیگری را رد می‌کند. برای نادیده‌گرفتن توصیفگرهای منتشرشده توسط Node، gateway.nodes.pluginTools.enabled: false را تنظیم کنید.

میزبان‌های Node متصل، کاتالوگ جایگزین کامل مهارت‌های خود را با node.skills.update منتشر می‌کنند. این روش مخصوص نقش Node تنها مسیر انتشار مهارت‌های Node است؛ مهارت‌ها در پارامترهای connect پذیرفته نمی‌شوند. هر توصیفگر شامل نامی امن، توضیح و محتوای محدودشدهٔ SKILL.md است. Gateway آن محتوا را با بارگذار معمول مهارت‌ها تجزیه می‌کند، تا زمانی که Node متصل است آن را در نماهای لحظه‌ای مهارت عامل می‌گنجاند و هنگام قطع اتصال حذف می‌کند. برای نادیده‌گرفتن مهارت‌های منتشرشده توسط Node، gateway.nodes.allowSkills: false را تنظیم کنید.

حضور

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

Nodeهای بومی macOS همچنین می‌توانند رویدادهای احرازهویت‌شدهٔ node.presence.activity را با زمان بیکاری ورودی محدودشده ارسال کنند. Gateway مُهرهای زمانی فعالیت را بر اساس ساعت خودش استخراج می‌کند، تازه‌ترین Mac متصل را از طریق node.list و node.describe ارائه می‌دهد و به‌روزرسانی‌های node.presence را برای کلاینت‌های دارای دامنهٔ خواندن پخش می‌کند. وقتی کاربر اشتراک‌گذاری فعالیت را غیرفعال می‌کند، برنامه { "action": "clear" } را ارسال می‌کند؛ Gateway مُهرهای زمانی را فقط برای همان اتصال احرازهویت‌شدهٔ دقیق Node پاک می‌کند. Gatewayهایی که پیش از این اقدام تأییدشونده هستند، آن را مدیریت‌نشده برمی‌گردانند؛ بنابراین Node مبتنی بر Mac یک بار دوباره متصل می‌شود و اجازه می‌دهد پاک‌سازی هنگام قطع اتصال، وضعیت اتصال قدیمی را حذف کند. برای رفتار انتخاب، حریم خصوصی، زمینهٔ مدل و مسیریابی اعلان‌ها، به حضور رایانهٔ فعال مراجعه کنید.

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

Nodeها برای ثبت اینکه یک Node جفت‌شده هنگام بیدارشدن در پس‌زمینه زنده بوده است، بدون علامت‌گذاری آن به‌عنوان متصل، 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 یک شمارش بسته است: background، silent_push، bg_app_refresh، significant_location، manual، connect. مقادیر ناشناخته به background (src/shared/node-presence.ts) نرمال‌سازی می‌شوند. رویداد فقط برای نشست‌های احرازهویت‌شدهٔ دستگاه Node پایدار می‌شود؛ نشست‌های بدون دستگاه یا جفت‌نشده handled: false را برمی‌گردانند.

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

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

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

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

رویدادهای پخشی ارسال‌شده از سرور با دامنه محدود می‌شوند تا نشست‌های محدود به جفت‌سازی یا فقط Node، محتوای نشست را به‌طور منفعل دریافت نکنند (src/gateway/server-broadcast.ts):

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

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

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

hello-ok.features.methods یک فهرست اکتشافی محافظه‌کارانه است که از src/gateway/server-methods-list.ts به‌همراه خروجی‌های روش Plugin/کانال بارگذاری‌شده ساخته می‌شود؛ این فهرست، خروجی تولیدشدهٔ همهٔ روش‌ها نیست و برخی روش‌ها (برای مثال push.test، web.login.start، web.login.wait، sessions.usage) عمداً از اکتشاف کنار گذاشته شده‌اند، هرچند روش‌هایی واقعی و قابل‌فراخوانی هستند. این را اکتشاف قابلیت در نظر بگیرید، نه فهرست کامل src/gateway/server-methods/*.ts.

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

• chat: به‌روزرسانی‌های گفت‌وگوی رابط کاربری مانند chat.inject و سایر رویدادهای گفت‌وگویی که فقط در رونوشت هستند. در پروتکل v4، محموله‌های تفاضلی deltaText را حمل می‌کنند؛ message همچنان تصویر تجمعی دستیار است. جایگزینی‌هایی که پیشوند نیستند replace=true را تنظیم می‌کنند و از deltaText به‌عنوان متن جایگزین استفاده می‌کنند.
• session.message، session.operation، session.tool: به‌روزرسانی‌های رونوشت، عملیات در حال اجرای نشست و جریان رویداد برای یک نشست مشترک‌شده.
• session.approval: حقیقت پاک‌سازی‌شده تأییدهای در انتظار و نهایی برای مشترک یک نشست دقیق که صریحاً انتخاب کرده است. تأییدهای فرزند از مخاطبان نیای ذخیره‌شده استفاده می‌کنند؛ رویدادها هرگز رونوشت‌ها را تغییر نمی‌دهند یا عامل‌ها را بیدار نمی‌کنند.
• sessions.changed: نمایه یا فراداده نشست تغییر کرده است.
• presence: به‌روزرسانی تصویر لحظه‌ای حضور سیستم.
• tick: رویداد دوره‌ای زنده‌نگه‌داشتن/فعال‌بودن.
• 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: پیکربندی محرک واژه بیدارباش تغییر کرده است.
• config.changed: یک نوشتن پیکربندی ذخیره شد (محموله مسیر پیکربندی، هش تصویر لحظه‌ای جدید و یک مُهر زمانی را حمل می‌کند — هرگز محتوای پیکربندی را حمل نمی‌کند). محدود به خواندن اپراتور؛ کلاینت‌ها از طریق config.get تازه‌سازی می‌کنند.
• exec.approval.requested / exec.approval.resolved: چرخه عمر تأیید اجرا.
• plugin.approval.requested / plugin.approval.resolved: چرخه عمر تأیید Plugin.

متدهای کمکی Node

Nodeها می‌توانند برای دریافت فهرست کنونی فایل‌های اجرایی Skill جهت بررسی‌های مجازسازی خودکار، skills.bins را فراخوانی کنند.

RPC دفترکل ممیزی

audit.activity.list نمایی پایدار و مرتب‌شده از جدیدترین به قدیمی‌ترین از فراداده چرخه عمر اجرای عامل، اقدام ابزار و پیام‌های انتخابی را در اختیار کلاینت‌های اپراتور قرار می‌دهد. این متد به operator.read نیاز دارد. پرس‌وجوها رکوردهای قدیمی‌تر از 30 روز را حذف می‌کنند و دفترکل مشترک SQLite به 100,000 رکورد محدود است. ردیف‌های منقضی‌شده هنگام راه‌اندازی Gateway، نگه‌داری ساعتی و نوشتن‌های بعدی حذف می‌شوند. برای مدل داده و معناشناسی حریم خصوصی، تاریخچه ممیزی را ببینید.

• پارامترها: agentId، sessionKey یا runId دقیق و اختیاری؛ kind اختیاری ("agent_run"، "tool_action" یا "message")؛ status اختیاری ("started"، "succeeded"، "failed"، "cancelled"، "timed_out"، "blocked" یا "unknown")؛ direction پیام اختیاری ("inbound" یا "outbound") و channel دقیق؛ کران‌های شامل و اختیاری after / before برحسب میلی‌ثانیه Unix؛ limit اختیاری از 1 تا 500؛ و رشته اختیاری cursor از صفحه پیشین.
• نتیجه: { "events": AuditActivityEventV1[], "nextCursor"?: string }.

اتحاد نام‌گذاری‌شده نتیجه V1 برای اجرای عامل، اقدام ابزار، پیام ورودی و پیام خروجی شِماهای جداگانه دارد. متمایزکننده eventType به‌ترتیب agent_run، tool_action، inbound_message یا outbound_message است؛ kind و direction پیام برای فیلترکردن و نمایش همچنان در دسترس‌اند. هر رویداد دارای schemaVersion: 1 صحیح است. ارجاع‌های هویت پیام از قالب دقیق hmac-sha256:v1:<32 hex key id>:<64 hex digest> استفاده می‌کنند؛ شناسه کنشگر فرستنده کانال نیز از همان قالب استفاده می‌کند.

همه گونه‌ها به eventType، schemaVersion، eventId، sequence، sourceSequence، occurredAt، kind، action، status، actor و redaction نیاز دارند. فیلدهای هر گونه عبارت‌اند از:

شمارش‌های بسته پیام عبارت‌اند از:

• conversationKind: direct، group، channel یا unknown.
• outcome ورودی: completed، skipped یا failed؛ reasonCode اختیاری: 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 یا acp_dispatch_aborted.
• outcome خروجی: sent، suppressed، failed یا unknown؛ reasonCode اختیاری: cancelled_by_message_sending_hook، cancelled_by_reply_payload_sending_hook، empty_after_message_sending_hook، empty_after_reply_payload_sending_hook یا no_visible_payload. آداپتوری که هیچ هویت پلتفرمی برنمی‌گرداند unknown است، زیرا اثر جانبی خارجی را نمی‌توان رد کرد.
• deliveryKind: text، media یا other؛ failureStage: platform_send، queue یا unknown.

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

هر رویداد فعالیت شامل شناسه پایدار رویداد، توالی یکنوای دفترکل، توالی رویداد مبدأ، مُهر زمانی، کنشگر، اقدام، وضعیت، مقدار صحیح schemaVersion: 1 و redaction: "metadata_only" است. رکوردهای اجرا و ابزار به منشأ عامل و اجرا نیاز دارند و ممکن است منشأ نشست را نیز شامل شوند. رکوردهای پیام ممکن است شناسه‌های عامل و اجرا را شامل شوند، اما عمداً هرگز شامل sessionKey یا sessionId نیستند؛ بنابراین فیلتر پرس‌وجوی sessionKey فقط بر ردیف‌های اجرا و ابزار اعمال می‌شود. رویدادهای ابزار ممکن است شناسه فراخوانی ابزار و نام ابزار را شامل شوند.

رکوردهای پیام از message.inbound.processed یا message.outbound.finished استفاده می‌کنند و جهت، کانال، نوع مکالمه، نتیجه نرمال‌شده، و نوع تحویل، مرحله شکست، مدت‌زمان، تعداد نتایج، کد دلیل و نام‌های مستعار کلیددارِ محلیِ نصب برای حساب/مکالمه/پیام/مقصد را به‌صورت اختیاری اضافه می‌کنند. این نام‌های مستعار به هم‌بستگی کمک می‌کنند، اما ناشناس‌سازی نیستند: پایگاه داده وضعیت کلید آن‌ها را در خود دارد، درحالی‌که خروجی‌های RPC و CLI آن را ندارند. دفتر کل، پرامپت‌ها، بدنه پیام‌ها، آرگومان‌های ابزار، نتایج ابزار، خروجی فرمان یا متن خام خطا را ذخیره نمی‌کند. مقادیر sessionKey مربوط به اجرا/ابزار، به‌عنوان فراداده خام هم‌بستگی باقی می‌مانند و می‌توانند شناسه‌های حساب پلتفرم یا همتا را در خود جای دهند؛ رکوردهای پیام کلیدهای نشست را حذف می‌کنند.

برای ردیف‌های ورودی، durationMs ارسال اصلی را تا وضعیت نهایی آن اندازه‌گیری می‌کند و resultCount تعداد محموله‌های نهایی‌شده ابزار، بلوک و پاسخِ صف‌شده را می‌شمارد. برای ردیف‌های خروجی، durationMs بازه مالکیت تحویل تا تأیید، نامه مرده یا تطبیق (شامل زمان انتظار در صف) را پوشش می‌دهد و resultCount تعداد ارسال‌های فیزیکی شناسایی‌شده پلتفرم را می‌شمارد. deliveryKind، در صورت وجود، محموله مؤثر پس از هوک‌ها و رندر را توصیف می‌کند؛ ردیف‌های سرکوب‌شده یا دارای ابهام ناشی از خرابی، آن را حذف می‌کنند.

پوشش کنونی پیام شامل پیام‌های ورودی پذیرفته‌شده‌ای است که به ارسال اصلی می‌رسند، از جمله نتایج تکراری/نهایی هسته. پوشش خروجی برای هر محموله منطقی پاسخ اصلی که به تحویل پایدار مشترک می‌رسد، یک ردیف نهایی می‌نویسد؛ قطعه‌بندی و پخش‌شدن در آداپتور در resultCount تجمیع می‌شوند. ارسال‌های صف‌شده قابل‌تلاش‌مجدد یا مبهم، تنها پس از تأیید، نامه مرده یا تطبیق ثبت می‌شوند. مسیرهای محلی Plugin و ارسال مستقیم که این مرزهای مشترک را دور می‌زنند، هنوز پوشش داده نشده‌اند. صف محدود کارگر به‌صورت بهترین‌تلاش عمل می‌کند و ممکن است هنگام شکست یا اشباع، رکوردها را حذف کند؛ بنابراین این سطح یک بایگانی انطباقِ بدون اتلاف نیست.

ثبت به‌طور پیش‌فرض فعال است و از طریق audit.enabled کنترل می‌شود. ثبت پیام به‌طور جداگانه با audit.messages کنترل می‌شود و مقدار پیش‌فرض آن "off" است. وقتی ثبت غیرفعال باشد، audit.activity.list همچنان رکوردهای پیش‌تر نوشته‌شده را تا زمان انقضایشان ارائه می‌کند.

شِماهای عرضه‌شده درخواست، نتیجه و AuditEvent مربوط به audit.list بدون تغییر باقی می‌مانند و فقط رکوردهای اجرای عامل و کنش ابزار را برمی‌گردانند. کلاینت‌های اپراتوری جدید باید وقتی Gateway آن را اعلام می‌کند، audit.activity.list را فراخوانی کنند. Gatewayهای قدیمی‌تر ممکن است unknown method: audit.activity.list یا، از آنجا که مجوزدهی در نسخه‌های عرضه‌شده پیش از جست‌وجوی متد انجام می‌شد، missing scope: operator.admin را برای یک درخواست با دامنه خواندن گزارش کنند. مورد دوم را تنها زمانی به‌معنای نبود متد تلقی کنید که متد اعلام نشده باشد. سپس کلاینت می‌تواند تنها زمانی audit.list را دوباره امتحان کند که فیلترهایش به پشتیبانی از نوع پیام، جهت یا کانال نیاز نداشته باشند.

برای پرس‌وجوهای متنی و خروجی‌های محدود JSON از openclaw audit استفاده کنید.

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

کلاینت‌های اپراتوری، رکوردهای وظایف پس‌زمینه Gateway را از طریق RPCهای دفتر کل وظایف (packages/gateway-protocol/src/schema/tasks.ts) بررسی و لغو می‌کنند. این 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 }.
  • شناسه‌های وظیفه ناموجود، قالب خطای یافت‌نشدن 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، مُهرهای زمانی، پیشرفت، خلاصه نهایی و متن پاک‌سازی‌شده خطا. 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، ok:false را در محموله برمی‌گردانند.
• skills.status (operator.read) فهرست قابل‌مشاهده مهارت‌ها را برای یک عامل دریافت می‌کند.
  • agentId اختیاری است؛ برای خواندن فضای کاری عامل پیش‌فرض آن را حذف کنید.
  • پاسخ شامل واجدشرایط‌بودن، نیازمندی‌های موجودنبوده، بررسی‌های پیکربندی و گزینه‌های پاک‌سازی‌شده نصب است، بدون اینکه مقادیر خام محرمانه را افشا کند.
• skills.search و skills.detail (operator.read) فراداده کشف ClawHub را برمی‌گردانند.
• skills.upload.begin، skills.upload.chunk و skills.upload.commit (operator.admin) پیش از نصب، یک بایگانی خصوصی مهارت را آماده می‌کنند. این یک مسیر بارگذاری مدیریتی جداگانه برای کلاینت‌های مورداعتماد است، نه جریان معمول نصب مهارت ClawHub، و به‌طور پیش‌فرض غیرفعال است، مگر اینکه skills.install.allowUploadedArchives فعال باشد.
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) یک بارگذاری وابسته به آن نامک و مقدار اجبار ایجاد می‌کند.
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) بایت‌ها را در آفست رمزگشایی‌شده دقیق اضافه می‌کند.
  • skills.upload.commit({ uploadId, sha256? }) اندازه نهایی و SHA-256 را تأیید می‌کند. ثبت فقط بارگذاری را نهایی می‌کند؛ مهارت را نصب نمی‌کند.
  • بایگانی‌های بارگذاری‌شده مهارت، بایگانی‌های zip حاوی ریشه SKILL.md هستند. نام دایرکتوری داخلی بایگانی هرگز مقصد نصب را انتخاب نمی‌کند.
• skills.install (operator.admin) سه حالت دارد:
  • حالت ClawHub: { source: "clawhub", slug, version?, force? } یک پوشه مهارت را در دایرکتوری skills/ فضای کاری عامل پیش‌فرض نصب می‌کند.
  • حالت بارگذاری: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } یک بارگذاری ثبت‌شده را در دایرکتوری skills/<slug> فضای کاری عامل پیش‌فرض نصب می‌کند. نامک و مقدار اجبار باید با درخواست اصلی skills.upload.begin مطابقت داشته باشند. مگر اینکه skills.install.allowUploadedArchives فعال باشد، رد می‌شود؛ این تنظیم بر نصب‌های ClawHub اثر نمی‌گذارد.
  • حالت نصب‌کننده Gateway: { name, installId, timeoutMs? } یک کنش اعلام‌شده metadata.openclaw.install را روی میزبان Gateway اجرا می‌کند. کلاینت‌های قدیمی‌تر ممکن است همچنان dangerouslyForceUnsafeInstall را ارسال کنند؛ این فیلد منسوخ شده، فقط برای سازگاری پروتکل پذیرفته می‌شود و نادیده گرفته می‌شود. برای تصمیم‌های نصب متعلق به اپراتور از security.installPolicy استفاده کنید.
• skills.update (operator.admin) دو حالت دارد:
  • حالت ClawHub یک نامک ردیابی‌شده یا همه نصب‌های ردیابی‌شده ClawHub را در فضای کاری عامل پیش‌فرض به‌روزرسانی می‌کند.
  • حالت پیکربندی مقادیر skills.entries.<skillKey> مانند enabled، apiKey و env را وصله می‌کند.

نماهای models.list

models.list یک پارامتر اختیاری view می‌پذیرد (src/agents/model-catalog-visibility.ts):

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

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

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

مسیر جایگزین تحویل عامل

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

نسخه‌بندی

• PROTOCOL_VERSION، MIN_CLIENT_PROTOCOL_VERSION، MIN_NODE_PROTOCOL_VERSION و MIN_PROBE_PROTOCOL_VERSION در packages/gateway-protocol/src/version.ts قرار دارند.
• کلاینت‌ها minProtocol + maxProtocol را ارسال می‌کنند. کلاینت‌های اپراتور و رابط کاربری باید پروتکل جاری را در آن بازه بگنجانند؛ کلاینت‌ها و سرورهای فعلی از پروتکل v4 استفاده می‌کنند.
• کلاینت‌های احراز هویت‌شده‌ای که هم role: "node" و هم client.mode: "node" را دارند، می‌توانند از پروتکل Node نسخهٔ N-1 (در حال حاضر v3) استفاده کنند. کاوشگرهای سبکِ راه‌اندازی مجدد از همان بازهٔ N-1 استفاده می‌کنند. احراز هویت دستگاه، جفت‌سازی، دامنه‌ها، سیاست فرمان و تأییدهای exec تحت تأثیر این بازهٔ سازگاری قرار نمی‌گیرند. قابلیت‌ها و فرمان‌های Node متعلق به Plugin تا زمانی که Node به پروتکل جاری ارتقا نیابد ارائه نمی‌شوند، زیرا سطوح میزبانی‌شدهٔ آن‌ها بخشی از قرارداد N-1 نیستند.
• شِماها و مدل‌ها از تعریف‌های TypeBox تولید می‌شوند:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

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

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

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

کلاینت مرجع به درخواست‌های محدود اجازه می‌دهد هنگامی که هر درخواست معلق مهلتی دارد، مهلت پیکربندی‌شدهٔ خود را مدیریت کنند. یک درخواست expectFinal بدون timeoutMs محدود، هر درخواستی با timeoutMs: null، یا ترکیبی از درخواست‌های محدود و نامحدود، پایشگر تیک را فعال نگه می‌دارد. اگر رویدادهای ورودی و پاسخ‌ها پس از آستانهٔ پایان مهلت تیک همچنان بی‌صدا بمانند، کلاینت سوکت را با کد 4000 می‌بندد، همهٔ درخواست‌های معلق را رد می‌کند و دوباره متصل می‌شود. پس از اتصال مجدد، درخواست‌های ردشده را دوباره اجرا نمی‌کند.

احراز هویت

• احراز هویت Gateway با راز مشترک، بسته به gateway.auth.mode پیکربندی‌شده ("none" | "token" | "password" | "trusted-proxy")، از 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 بازگردانده می‌شود. کلاینت‌ها باید پس از هر اتصال موفق آن را ذخیره کنند.
• اتصال مجدد با آن توکن دستگاه ذخیره‌شده باید مجموعه دامنه‌های تأییدشده ذخیره‌شده برای همان توکن را نیز دوباره استفاده کند. این کار دسترسی خواندن/کاوش/وضعیت را که قبلاً اعطا شده حفظ می‌کند و مانع از آن می‌شود که اتصال‌های مجدد بی‌سروصدا به دامنه ضمنی محدودتر و فقط مخصوص مدیر فروکاسته شوند.
• ساخت احراز هویت اتصال در سمت کلاینت (selectConnectAuth در packages/gateway-client/src/client.ts):
  • auth.password مستقل است و در صورت تنظیم، همیشه ارسال می‌شود.
  • auth.token به‌ترتیب اولویت مقداردهی می‌شود: ابتدا توکن مشترک صریح، سپس یک deviceToken صریح، و بعد یک توکن ذخیره‌شده برای هر دستگاه (با کلید deviceId + role).
  • auth.bootstrapToken فقط زمانی ارسال می‌شود که هیچ‌یک از موارد بالا auth.token را تعیین نکرده باشند. توکن مشترک یا هر توکن دستگاه تعیین‌شده‌ای آن را سرکوب می‌کند.
  • ارتقای خودکار توکن دستگاه ذخیره‌شده در تلاش مجدد یک‌باره AUTH_TOKEN_MISMATCH فقط به نقاط پایانی قابل‌اعتماد محدود است: loopback، یا wss:// با tlsFingerprint سنجاق‌شده. wss:// عمومی بدون سنجاق‌کردن واجد شرایط نیست.
• راه‌اندازی اولیه با کد راه‌اندازی داخلی، hello-ok.auth.deviceToken مربوط به Node اصلی را به‌همراه یک توکن اپراتور محدود در hello-ok.auth.deviceTokens برای تحویل امن به موبایل بازمی‌گرداند. توکن اپراتور شامل operator.talk.secrets برای خواندن پیکربندی بومی Talk است، اما دامنه‌های تغییر جفت‌سازی و operator.admin را شامل نمی‌شود.
• هنگامی‌که راه‌اندازی اولیه با کد راه‌اندازیِ غیربن‌خط در انتظار تأیید است، جزئیات PAIRING_REQUIRED شامل recommendedNextStep: "wait_then_retry"، retryable: true و pauseReconnect: false است. تا زمان تأیید درخواست یا نامعتبرشدن توکن، اتصال مجدد را با همان توکن راه‌اندازی اولیه ادامه دهید.
• hello-ok.auth.deviceTokens را فقط زمانی ذخیره کنید که اتصال از احراز هویت راه‌اندازی اولیه روی انتقالی قابل‌اعتماد مانند wss:// یا جفت‌سازی loopback/محلی استفاده کرده باشد.
• اگر کلاینت یک deviceToken صریح یا scopes صریح ارائه کند، مجموعه دامنه درخواستی فراخواننده همچنان مرجع نهایی است؛ دامنه‌های ذخیره‌شده فقط زمانی دوباره استفاده می‌شوند که کلاینت از توکن ذخیره‌شده همان دستگاه دوباره استفاده کند.
• توکن‌های دستگاه را می‌توان از طریق device.token.rotate و device.token.revoke چرخاند/لغو کرد (نیازمند operator.pairing). چرخاندن یا لغو توکن Node یا هر نقش غیر‌اپراتور دیگر نیز به operator.admin نیاز دارد.
• device.token.rotate فراداده چرخش را بازمی‌گرداند. توکن حامل جایگزین را فقط برای فراخوانی‌های همان دستگاه که از قبل با توکن همان دستگاه احراز هویت شده‌اند بازمی‌تاباند تا کلاینت‌های فقط‌توکنی بتوانند پیش از اتصال مجدد، توکن جایگزین خود را ذخیره کنند. چرخش‌های مشترک/مدیریتی توکن حامل را بازنمی‌تابانند.
• صدور، چرخش و لغو توکن به مجموعه نقش‌های تأییدشده ثبت‌شده در ورودی جفت‌سازی آن دستگاه محدود می‌ماند؛ تغییر توکن نمی‌تواند دامنه را گسترش دهد یا نقش دستگاهی را هدف قرار دهد که تأیید جفت‌سازی هرگز اعطا نکرده است.
• برای نشست‌های توکن دستگاه جفت‌شده، مدیریت دستگاه به خود دستگاه محدود است، مگر آنکه فراخواننده operator.admin را نیز داشته باشد: فراخوانندگان غیرمدیر فقط می‌توانند توکن اپراتورِ ورودی دستگاه خود را مدیریت کنند. مدیریت توکن Node و دیگر توکن‌های غیر‌اپراتور، حتی برای دستگاه خود فراخواننده، فقط در اختیار مدیر است.
• 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 (packages/gateway-protocol/src/connect-error-details.ts).
• رفتار کلاینت برای AUTH_TOKEN_MISMATCH:
  • کلاینت‌های قابل‌اعتماد می‌توانند یک تلاش مجدد محدود با توکن ذخیره‌شده همان دستگاه انجام دهند.
  • اگر آن تلاش مجدد ناموفق بود، حلقه‌های اتصال مجدد خودکار را متوقف کنید و راهنمای اقدام اپراتور را نمایش دهید.
• AUTH_SCOPE_MISMATCH یعنی توکن دستگاه شناسایی شده، اما نقش/دامنه‌های درخواستی را پوشش نمی‌دهد. این مورد را به‌عنوان توکن نامعتبر نمایش ندهید؛ از اپراتور بخواهید دوباره جفت‌سازی کند یا قرارداد دامنه محدودتر/گسترده‌تر را تأیید کند.

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

• Nodeها باید یک هویت پایدار دستگاه (device.id) مشتق‌شده از اثر انگشت جفت‌کلید را شامل شوند.
• Gatewayها برای هر دستگاه و نقش، توکن صادر می‌کنند.
• برای شناسه‌های دستگاه جدید، تأیید جفت‌سازی الزامی است، مگر آنکه تأیید خودکار محلی فعال باشد.
• تأیید خودکار جفت‌سازی بر اتصال‌های مستقیم loopback محلی متمرکز است.
• OpenClaw همچنین برای جریان‌های کمکی قابل‌اعتماد با راز مشترک، یک مسیر محدود خوداتصالی محلیِ بک‌اند/کانتینر دارد.
• اتصال‌های tailnet یا LAN روی همان میزبان همچنان برای جفت‌سازی راه‌دور محسوب می‌شوند و به تأیید نیاز دارند.
• کلاینت‌های WS معمولاً هنگام connect هویت device را ارائه می‌کنند (اپراتور + Node). تنها استثناهای اپراتور بدون دستگاه، مسیرهای اعتماد صریح هستند:
  • احراز هویت موفق Control UI اپراتور با gateway.auth.mode: "trusted-proxy".
  • RPCهای بک‌اند gateway-client با loopback مستقیم در مسیر کمکی داخلی رزروشده.
• حذف هویت دستگاه پیامدهایی برای دامنه‌ها دارد. وقتی اتصال اپراتور بدون دستگاه از طریق یک مسیر اعتماد صریح مجاز می‌شود، OpenClaw همچنان دامنه‌های خوداظهاری را به مجموعه‌ای خالی پاک می‌کند، مگر آنکه آن مسیر استثنای نام‌گذاری‌شده‌ای برای حفظ دامنه داشته باشد. سپس روش‌های مقید به دامنه با missing scope ناموفق می‌شوند.
• مسیر کمکی بک‌اند gateway-client با loopback مستقیم و رزروشده، دامنه‌ها را فقط برای RPCهای داخلی صفحه کنترل محلی حفظ می‌کند؛ شناسه‌های سفارشی بک‌اند از این استثنا برخوردار نیستند.
• همه اتصال‌ها باید nonce ارائه‌شده از سوی سرور یعنی connect.challenge را امضا کنند.

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

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

خطاهای رایج مهاجرت:

هدف مهاجرت:

• همیشه منتظر connect.challenge بمانید.
• بار داده v2 را که nonce سرور را شامل می‌شود امضا کنید.
• همان nonce را در connect.params.device.nonce ارسال کنید.
• بار داده امضای ترجیحی v3 است (buildDeviceAuthPayloadV3 در packages/gateway-client/src/device-auth.ts)، که علاوه بر فیلدهای دستگاه/کلاینت/نقش/دامنه‌ها/توکن/nonce، platform و deviceFamily را نیز مقید می‌کند.
• امضاهای قدیمی v2 برای سازگاری همچنان پذیرفته می‌شوند، اما سنجاق‌کردن فراداده دستگاه جفت‌شده همچنان خط‌مشی فرمان را هنگام اتصال مجدد کنترل می‌کند.

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

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

دامنه

این پروتکل API کامل Gateway را ارائه می‌کند: وضعیت، کانال‌ها، مدل‌ها، گفت‌وگو، عامل، نشست‌ها، Nodeها، تأییدها و موارد دیگر. سطح دقیق توسط طرح‌واره‌های TypeBox که از packages/gateway-protocol/src/schema.ts دوباره صادر شده‌اند تعریف می‌شود.

مرتبط

• ساخت کلاینت Gateway
• تعبیه OpenClaw
• پروتکل پل
• راهنمای عملیاتی Gateway