بروتوكول Gateway

بروتوكول Gateway WS هو مستوى التحكم الوحيد + نقل العقد في OpenClaw. يتصل جميع العملاء (CLI، واجهة الويب، تطبيق macOS، عقد iOS/Android، العقد بلا واجهة) عبر WebSocket ويعلنون الدور + النطاق أثناء وقت المصافحة.

النقل

• WebSocket، إطارات نصية بحمولات JSON.
• يجب أن يكون الإطار الأول طلب connect.
• تُحدَّد إطارات ما قبل الاتصال بسعة 64 KiB. بعد مصافحة ناجحة، ينبغي للعملاء اتباع حدود hello-ok.policy.maxPayload و hello-ok.policy.maxBufferedBytes. عند تفعيل التشخيصات، تُصدر الإطارات الواردة الزائدة الحجم والمخازن المؤقتة الصادرة البطيئة أحداث payload.large قبل أن يغلق Gateway الإطار المتأثر أو يسقطه. تحتفظ هذه الأحداث بالأحجام، والحدود، والأسطح، ورموز الأسباب الآمنة. ولا تحتفظ بنص الرسالة، أو محتويات المرفقات، أو جسم الإطار الخام، أو الرموز، أو ملفات تعريف الارتباط، أو القيم السرية.

المصافحة (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 ينهي مكونات بدء التشغيل الجانبية، يمكن أن يعيد طلب connect خطأ UNAVAILABLE قابلا لإعادة المحاولة مع ضبط details.reason على "startup-sidecars" وretryAfterMs. ينبغي للعملاء إعادة محاولة هذه الاستجابة ضمن ميزانية الاتصال الإجمالية بدلا من عرضها كفشل مصافحة نهائي.

كل من server وfeatures وsnapshot وpolicy مطلوبة كلها في المخطط (packages/gateway-protocol/src/schema/frames.ts). كذلك auth مطلوبة وتعرض الدور/النطاقات المتفاوض عليها. pluginSurfaceUrls اختيارية وتربط أسماء أسطح Plugin ، مثل canvas، بعناوين URL مستضافة ومحددة النطاق.

قد تنتهي صلاحية عناوين URL لأسطح Plugin المحددة النطاق. يمكن للعقد استدعاء node.pluginSurface.refresh مع { "surface": "canvas" } لتلقي إدخال جديد في pluginSurfaceUrls. لا يدعم إعادة بناء Plugin Canvas التجريبي مسار التوافق المهمل canvasHostUrl أو canvasCapability أو node.canvas.capability.refresh؛ يجب على العملاء الأصليين وGateway الحاليين استخدام أسطح Plugin.

عندما لا يصدر رمز جهاز، يعرض hello-ok.auth الصلاحيات المتفاوض عليها من دون حقول الرمز:

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

يمكن لعملاء الخلفية الموثوقين داخل العملية نفسها (client.id: "gateway-client"، client.mode: "backend") حذف device على اتصالات loopback المباشرة عندما يصادقون باستخدام رمز/كلمة مرور Gateway المشتركة. هذا المسار مخصص لاستدعاءات RPC الداخلية لمستوى التحكم، ويمنع خطوط أساس إقران CLI/الأجهزة القديمة من حظر عمل الخلفية المحلي مثل تحديثات جلسات الوكلاء الفرعيين. العملاء البعيدون، وعملاء أصل المتصفح، وعملاء العقد، وعملاء رمز الجهاز/هوية الجهاز الصريحون ما زالوا يستخدمون فحوصات الإقران وترقية النطاق العادية.

عند إصدار رمز جهاز، يتضمن hello-ok أيضا:

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

تمهيد رمز QR/رمز الإعداد المدمج هو مسار تسليم محمول جديد. يعيد اتصال رمز إعداد خط أساس ناجح رمز عقدة أساسيا إضافة إلى رمز مشغل واحد محدود:

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

تسليم المشغل محدود عمدا حتى يتمكن إعداد QR من بدء حلقة المشغل المحمول وإكمال الإعداد الأصلي من دون منح نطاقات تغيير الإقران أو operator.admin. ويتضمن operator.talk.secrets حتى يتمكن العميل الأصلي من قراءة إعدادات Talk التي يحتاجها بعد التمهيد. يتطلب الوصول الأوسع للإقران والإدارة تدفق إقران مشغل أو رمز منفصلا ومعتمدا. ينبغي للعملاء حفظ hello-ok.auth.deviceTokens فقط عندما يستخدم الاتصال مصادقة التمهيد على نقل موثوق مثل wss:// أو loopback/الإقران المحلي.

مثال عقدة

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

تتطلب الأساليب ذات الآثار الجانبية مفاتيح عدم التكرار (انظر المخطط).

الأدوار + النطاقات

للاطلاع على نموذج نطاق المشغل الكامل، وفحوصات وقت الموافقة، ودلالات السر المشترك، راجع نطاقات المشغل.

الأدوار

• operator = عميل مستوى التحكم (CLI/واجهة المستخدم/الأتمتة).
• node = مضيف الإمكانية (camera/screen/canvas/system.run).

النطاقات (المشغل)

النطاقات الشائعة:

• 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 نطاق مشغل خاصا بها، لكن بادئات الإدارة الأساسية المحجوزة (config.* وexec.approvals.* وwizard.* وupdate.*) تُحل دائما إلى operator.admin.

نطاق الأسلوب هو البوابة الأولى فقط. بعض أوامر الشرطة المائلة التي يتم الوصول إليها عبر chat.send تطبق فحوصات أكثر صرامة على مستوى الأمر فوق ذلك. على سبيل المثال، تتطلب كتابات /config set و/config unset الدائمة operator.admin.

لدى node.pair.approve أيضا فحص نطاق إضافي وقت الموافقة فوق نطاق الأسلوب الأساسي:

• الطلبات بلا أوامر: operator.pairing
• الطلبات ذات أوامر عقد غير تنفيذية: operator.pairing + operator.write
• الطلبات التي تتضمن system.run أو system.run.prepare أو system.which: operator.pairing + operator.admin

الإمكانات/الأوامر/الصلاحيات (العقدة)

تعلن العقد مطالبات الإمكانية وقت الاتصال:

• caps: فئات إمكانات عالية المستوى مثل camera وcanvas وscreen وlocation وvoice وtalk.
• commands: قائمة سماح بالأوامر للاستدعاء.
• permissions: مفاتيح تبديل دقيقة (مثل screen.record وcamera.capture).

يتعامل Gateway مع هذه كـ مطالبات ويفرض قوائم السماح من جانب الخادم.

الحضور

• يعيد system-presence إدخالات مفهرسة حسب هوية الجهاز.
• تتضمن إدخالات الحضور deviceId وroles وscopes حتى تتمكن واجهات المستخدم من عرض صف واحد لكل جهاز حتى عندما يتصل بصفته مشغلا وعقدة في الوقت نفسه.
• يتضمن 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 تعداد مغلق: background أو silent_push أو bg_app_refresh أو significant_location أو manual أو connect. يطبع Gateway سلاسل المشغلات غير المعروفة إلى background قبل الحفظ. يكون الحدث دائما فقط لجلسات أجهزة العقد المصادق عليها؛ تعيد الجلسات بلا جهاز أو غير المقترنة handled: false.

تعيد Gateway الناجحة نتيجة منظمة:

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

قد تظل Gateway الأقدم تعيد { "ok": true } لـ node.event؛ ينبغي للعملاء التعامل مع ذلك كاستدعاء RPC مؤكد، وليس كاستمرار حضور دائم.

تحديد نطاق أحداث البث

تخضع أحداث بث WebSocket المدفوعة من الخادم للنطاقات، حتى لا تتلقى الجلسات المحددة بنطاق الإقران أو جلسات العقد فقط محتوى الجلسة بشكل سلبي.

• إطارات الدردشة والوكيل ونتائج الأدوات (بما في ذلك أحداث agent المتدفقة ونتائج استدعاءات الأدوات) تتطلب على الأقل operator.read. تتخطى الجلسات التي لا تملك operator.read هذه الإطارات بالكامل.
• بثوث plugin.* المعرفة بواسطة Plugin تخضع لـ operator.write أو operator.admin، بناء على كيفية تسجيل Plugin لها.
• أحداث الحالة والنقل (heartbeat وpresence وtick ودورة حياة الاتصال/قطع الاتصال، وما إلى ذلك) تبقى غير مقيدة حتى تبقى صحة النقل قابلة للملاحظة لكل جلسة مصادق عليها.
• عائلات أحداث البث غير المعروفة تخضع للنطاقات افتراضيا (تفشل مغلقة) ما لم يرخها معالج مسجل صراحة.

يحتفظ كل اتصال عميل برقم تسلسل خاص به لكل عميل حتى تحافظ البثوث على ترتيب تصاعدي على ذلك المقبس، حتى عندما يرى عملاء مختلفون مجموعات فرعية مختلفة مفلترة بالنطاق من تدفق الأحداث.

عائلات أساليب RPC الشائعة

سطح WS العام أوسع من أمثلة المصافحة/المصادقة أعلاه. هذه ليست نسخة مولدة — hello-ok.features.methods قائمة اكتشاف محافظة مبنية من src/gateway/server-methods-list.ts إضافة إلى صادرات أساليب Plugin/القناة المحملة. تعامل معها كاكتشاف ميزات، لا كتعداد كامل لـ src/gateway/server-methods/*.ts.

عائلات الأحداث الشائعة

• chat: تحديثات دردشة واجهة المستخدم مثل chat.inject وأحداث دردشة أخرى خاصة بالنص المنسوخ فقط. في بروتوكول v4، تحمل حمولات الفروقات deltaText؛ ويبقى message لقطة المساعد التراكمية. تضبط الاستبدالات غير البادئة replace=true وتستخدم deltaText كنص الاستبدال.
• session.message وsession.operation وsession.tool: تحديثات النص المنسوخ، وعملية الجلسة الجارية، وتدفق الأحداث لجلسة مشترك فيها.
• 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: تغيّر إعداد مشغل كلمة التنبيه.
• exec.approval.requested / exec.approval.resolved: دورة حياة موافقة التنفيذ.
• plugin.approval.requested / plugin.approval.resolved: دورة حياة موافقة Plugin.

طرق مساعدة Node

• يمكن للعُقد استدعاء skills.bins لجلب القائمة الحالية للملفات التنفيذية الخاصة بالـ Skills لفحوصات السماح التلقائي.

استدعاءات 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 }.
  • تعيد معرّفات المهام المفقودة بنية خطأ عدم العثور الخاصة بـ 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 نمطية. ترجع رفضات الموافقة أو السياسة ok:false في الحمولة بدلا من تجاوز مسار سياسة أدوات Gateway.
• يجوز للمشغّلين استدعاء skills.status (operator.read) لجلب مخزون Skills المرئي لوكيل.
  • agentId اختياري؛ احذفه لقراءة مساحة عمل الوكيل الافتراضية.
  • تتضمن الاستجابة الأهلية والمتطلبات المفقودة وفحوصات الإعدادات وخيارات تثبيت منقّاة من دون كشف قيم الأسرار الخام.
• يجوز للمشغّلين استدعاء skills.search وskills.detail (operator.read) للحصول على بيانات تعريف اكتشاف ClawHub.
• يجوز للمشغّلين استدعاء skills.upload.begin وskills.upload.chunk و skills.upload.commit (operator.admin) لتهيئة أرشيف Skill خاص قبل تثبيته. هذا مسار رفع إداري منفصل للعملاء الموثوقين، وليس تدفق تثبيت Skills العادي في 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. ينجز الالتزام الرفع فقط؛ ولا يثبّت Skill.
  • أرشيفات Skills المرفوعة هي أرشيفات zip تحتوي على جذر SKILL.md. لا يحدد اسم الدليل الداخلي في الأرشيف هدف التثبيت مطلقا.
• يجوز للمشغّلين استدعاء skills.install (operator.admin) في ثلاثة أوضاع:
  • وضع ClawHub: يثبّت { source: "clawhub", slug, version?, force? } مجلد Skill في دليل 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 اختياريا:

• محذوف أو "default": سلوك وقت التشغيل الحالي. إذا كان agents.defaults.models مكوّنا، تكون الاستجابة هي الكتالوج المسموح به، بما في ذلك النماذج المكتشفة ديناميكيا لإدخالات provider/*. وإلا تكون الاستجابة هي كتالوج Gateway الكامل.
• "configured": سلوك بحجم المنتقي. إذا كان agents.defaults.models مكوّنا، فإنه يظل هو السائد، بما في ذلك الاكتشاف المقيّد بالمزوّد لإدخالات provider/*. من دون قائمة سماح، تستخدم الاستجابة إدخالات models.providers.*.models الصريحة، مع الرجوع إلى الكتالوج الكامل فقط عندما لا توجد صفوف نماذج مكوّنة.
• "all": كتالوج Gateway الكامل، متجاوزا agents.defaults.models. استخدم هذا للتشخيصات وواجهات اكتشاف المستخدم، وليس منتقيات النماذج العادية.

موافقات التنفيذ

• عندما يحتاج طلب تنفيذ إلى موافقة، يبث 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/الجلسة.
• إذا غيّر مستدع command أو rawCommand أو cwd أو agentId أو sessionKey بين التحضير وإعادة التوجيه النهائية المعتمدة إلى system.run، فإن Gateway يرفض التشغيل بدلا من الوثوق بالحمولة المعدّلة.

رجوع تسليم الوكيل

• يمكن أن تتضمن طلبات agent القيمة deliver=true لطلب التسليم الصادر.
• يحافظ bestEffortDeliver=false على السلوك الصارم: تعيد أهداف التسليم غير المحلولة أو الداخلية فقط INVALID_REQUEST.
• يسمح bestEffortDeliver=true بالرجوع إلى التنفيذ داخل الجلسة فقط عندما لا يمكن حل مسار خارجي قابل للتسليم (مثل جلسات داخلية/دردشة ويب أو إعدادات متعددة القنوات ملتبسة).
• قد تتضمن نتائج agent النهائية result.deliveryStatus عندما يكون التسليم مطلوبا، باستخدام حالات sent وsuppressed وpartial_failed وfailed نفسها الموثقة في openclaw agent --json --deliver.

تحديد الإصدارات

• يوجد PROTOCOL_VERSION في packages/gateway-protocol/src/version.ts.
• يرسل العملاء minProtocol + maxProtocol؛ ويرفض الخادم النطاقات التي لا تتضمن بروتوكوله الحالي. يتطلب العملاء والخوادم الحاليون البروتوكول v4.
• يتم إنشاء المخططات + النماذج من تعريفات TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

ثوابت العميل

يستخدم العميل المرجعي في src/gateway/client.ts هذه القيم الافتراضية. القيم مستقرة عبر البروتوكول v4 وهي خط الأساس المتوقع للعملاء الخارجيين.

يعلن الخادم القيم الفعّالة policy.tickIntervalMs وpolicy.maxPayload وpolicy.maxBufferedBytes في hello-ok؛ وينبغي للعملاء احترام تلك القيم بدلا من القيم الافتراضية قبل المصافحة.

المصادقة

• يستخدم مصادقة Gateway بالسر المشترك connect.params.auth.token أو connect.params.auth.password، بحسب وضع المصادقة المكوّن.
• أوضاع حمل الهوية مثل Tailscale Serve (gateway.auth.allowTailscale: true) أو غير local loopback gateway.auth.mode: "trusted-proxy" تفي بفحص مصادقة الاتصال من رؤوس الطلب بدلا من 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:// العام من دون تثبيت.
• يعيد تمهيد رمز الإعداد المدمج رمز الجهاز للعقدة الأساسية hello-ok.auth.deviceToken بالإضافة إلى رمز مشغل محدود في 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). تدوير أو إبطال عقدة أو دور آخر غير مشغل يتطلب أيضا operator.admin.
• يعيد device.token.rotate بيانات وصفية للتدوير. يكرر رمز الحامل البديل فقط لاستدعاءات الجهاز نفسه التي تمت مصادقتها بالفعل باستخدام رمز ذلك الجهاز، حتى يتمكن العملاء المعتمدون على الرموز فقط من حفظ البديل قبل إعادة الاتصال. لا تكرر تدويرات المشترك/المسؤول رمز الحامل.
• يظل إصدار الرموز وتدويرها وإبطالها محدودا بمجموعة الأدوار الموافق عليها والمسجلة في إدخال اقتران ذلك الجهاز؛ لا يمكن لتعديل الرمز توسيع أو استهداف دور جهاز لم تمنحه موافقة الاقتران قط.
• بالنسبة إلى جلسات رموز الأجهزة المقترنة، تكون إدارة الجهاز ذاتية النطاق ما لم يكن لدى المستدعي أيضا 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) مشتقة من بصمة زوج مفاتيح.
• تصدر Gateways الرموز لكل جهاز + دور.
• موافقات الاقتران مطلوبة لمعرفات الأجهزة الجديدة ما لم تكن الموافقة التلقائية المحلية مفعلة.
• تتمحور الموافقة التلقائية على الاقتران حول اتصالات local loopback المباشرة.
• لدى OpenClaw أيضا مسار اتصال ذاتي ضيق داخل الخلفية/الحاوية لتدفقات المساعد الموثوقة ذات السر المشترك.
• لا تزال اتصالات tailnet أو LAN على المضيف نفسه تعامل على أنها بعيدة للاقتران و تتطلب موافقة.
• يتضمن عملاء WS عادة هوية device أثناء connect (مشغل + عقدة). استثناءات المشغلين من دون جهاز الوحيدة هي مسارات الثقة الصريحة:
  • gateway.controlUi.allowInsecureAuth=true لتوافق HTTP غير آمن على المضيف المحلي فقط.
  • مصادقة Control UI للمشغل عبر gateway.auth.mode: "trusted-proxy" الناجحة.
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (كسر طارئ، خفض أمان شديد).
  • RPCs خلفية gateway-client عبر direct-loopback على مسار المساعد الداخلي المحجوز.
• لحذف هوية الجهاز عواقب على النطاقات. عندما يسمح باتصال مشغل من دون جهاز عبر مسار ثقة صريح، يظل OpenClaw يمسح النطاقات المعلنة ذاتيا إلى مجموعة فارغة ما لم يكن لذلك المسار استثناء مسمى لحفظ النطاقات. عندها تفشل الطرق المحكومة بالنطاقات مع missing scope.
• gateway.controlUi.dangerouslyDisableDeviceAuth=true هو مسار حفظ نطاقات كسر طارئ لـ Control UI. لا يمنح نطاقات إلى عملاء WebSocket مخصصين عشوائيين بشكل خلفية أو CLI.
• يحافظ مسار مساعد الخلفية المحجوز gateway-client عبر direct-loopback على النطاقات فقط لـ RPCs مستوى التحكم المحلي الداخلية؛ لا تحصل معرفات الخلفية المخصصة على هذا الاستثناء.
• يجب أن توقع كل الاتصالات على قيمة nonce التي يوفرها الخادم connect.challenge.

تشخيصات ترحيل مصادقة الجهاز

بالنسبة إلى العملاء القدامى الذين ما زالوا يستخدمون سلوك التوقيع السابق للتحدي، يعيد connect الآن رموز تفاصيل DEVICE_AUTH_* ضمن error.details.code مع error.details.reason مستقر.

إخفاقات الترحيل الشائعة:

هدف الترحيل:

• انتظر دائما connect.challenge.
• وقع حمولة v2 التي تتضمن nonce الخادم.
• أرسل nonce نفسه في connect.params.device.nonce.
• حمولة التوقيع المفضلة هي v3، التي تربط platform وdeviceFamily بالإضافة إلى حقول الجهاز/العميل/الدور/النطاقات/الرمز/nonce.
• تظل توقيعات v2 القديمة مقبولة للتوافق، لكن تثبيت البيانات الوصفية للجهاز المقترن لا يزال يتحكم في سياسة الأوامر عند إعادة الاتصال.

TLS + التثبيت

• TLS مدعوم لاتصالات WS.
• يمكن للعملاء اختياريا تثبيت بصمة شهادة Gateway (راجع إعداد gateway.tls بالإضافة إلى gateway.remote.tlsFingerprint أو CLI --tls-fingerprint).

النطاق

يكشف هذا البروتوكول واجهة برمجة تطبيقات Gateway الكاملة (الحالة، القنوات، النماذج، الدردشة، الوكيل، الجلسات، العقد، الموافقات، إلخ). يحدد السطح الدقيق بواسطة مخططات TypeBox في packages/gateway-protocol/src/schema.ts.

ذو صلة

• بروتوكول Bridge
• دليل تشغيل Gateway