بروتوكول Gateway

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

النقل وتأطير الرسائل

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

أشكال الإطارات:

• الطلب: {type:"req", id, method, params}
• الاستجابة: {type:"res", id, ok, payload|error}
• الحدث: {type:"event", event, payload, seq?, stateVersion?}

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

المصافحة

يرسل 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.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/رمز الإعداد مسار تسليم للأجهزة المحمولة. يعيد الاتصال الأساسي الناجح باستخدام رمز الإعداد رمزًا مميزًا أساسيًا للعقدة، إضافة إلى رمز مميز واحد محدود للمشغّل:

{  "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:// أو اقتران الاسترجاع الحلقي/المحلي).

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

دور العامل والبروتوكول المغلق

يستخدم العاملون السحابيون نقطة دخول مخصصة للاسترجاع الحلقي عبر نفق SSH الذي يملكه Gateway والمثبّت بمفتاح المضيف. وهي لا تقبل إلا هوية العامل ولا توجّه مطلقًا المصادقة العامة، أو أحداث العُقد، أو استدعاءات 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، لذا لا تتوفر الأدوات المقيّدة بالإمكانات حتى عندما تسمح بها سياسة الأدوات صراحةً.

مثال على اتصال عقدة

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

تعلن العُقد عن ادعاءات الإمكانات عند الاتصال:

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

يتعامل Gateway مع هذه على أنها ادعاءات ويفرض قوائم السماح من جانب الخادم.

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

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

الأدوار:

• operator: عميل مستوى التحكم (CLI/واجهة المستخدم/الأتمتة).
• node: مضيف الإمكانات (الكاميرا/الشاشة/لوحة الرسم/system.run).
• 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):

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

تعلن العُقد عن ادعاءات الإمكانات عند الاتصال:

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

يتعامل Gateway مع هذه على أنها ادعاءات ويفرض قوائم السماح من جانب الخادم. يمكن للعُقد المتصلة نشر واصفات اختيارية لأدوات Plugin أو MCP مرئية للوكيل باستخدام node.pluginTools.update بعد نجاح الاتصال أو إعادة الاتصال. تُعاد تشغيل مضيفات العُقد عديمة الواجهة لتطبيق تغييرات مخزون MCP التعريفية. طريقة التحديث هذه هي مسار النشر الوحيد؛ ولا تُقبل واصفات أدوات Plugin ضمن معاملات connect. يجب أن يستخدم كل واصف أداة name آمنة لمزوّد الخدمة وأن يسمّي command ضمن قائمة السماح الحالية للأوامر في العقدة. يثق Gateway في بيانات الواصف الوصفية الواردة من العقدة المقترنة، ويرشّح الواصفات الواقعة خارج نطاق الأوامر المعتمد، ويزيلها عند قطع اتصال العقدة، ويرفض محاولات المشغّل لتعديل كتالوج عقدة أخرى. عيّن gateway.nodes.pluginTools.enabled: false لتجاهل الواصفات التي تنشرها العقدة.

تنشر مضيفات العُقد المتصلة كتالوج الاستبدال الكامل للمهارات لديها باستخدام node.skills.update. طريقة دور العقدة هذه هي مسار نشر مهارات العقدة الوحيد؛ ولا تُقبل المهارات ضمن معاملات connect. يحتوي كل واصف على اسم آمن ووصف ومحتوى SKILL.md محدود. يحلّل Gateway ذلك المحتوى باستخدام محمّل المهارات المعتاد، ويدرجه في لقطات مهارات الوكيل ما دامت العقدة متصلة، ويزيله عند قطع الاتصال. عيّن gateway.nodes.skills.enabled: false لتجاهل المهارات التي تنشرها العقدة.

الحضور

• system-presence يعيد إدخالات مفهرسة حسب هوية الجهاز، بما في ذلك deviceId وroles وscopes، لكي تتمكن واجهات المستخدم من عرض صف واحد لكل جهاز حتى عندما يتصل بصفته مشغّلًا وعقدة في آن واحد.
• node.list يتضمن lastSeenAtMs وlastSeenReason اختياريين. تُبلغ العُقد المتصلة عن وقت الاتصال الحالي بالسبب connect؛ ويمكن للعُقد المقترنة أيضًا الإبلاغ عن حضور دائم في الخلفية عبر حدث عقدة موثوق.

يمكن لعُقد macOS الأصلية أيضًا إرسال أحداث node.presence.activity موثّقة مع مدة خمول إدخال محدودة. يشتق Gateway الطوابع الزمنية للنشاط وفق ساعته الخاصة، ويعرض أحدث جهاز Mac متصل عبر node.list و node.describe، ويبث تحديثات node.presence إلى العملاء ذوي نطاق القراءة. راجع حضور الحاسوب النشط لمعرفة سلوك الاختيار والخصوصية وسياق النموذج وتوجيه الإشعارات.

حدث بقاء العقدة حية في الخلفية

تستدعي العُقد node.event باستخدام event: "node.presence.alive" لتسجيل أن عقدة مقترنة كانت حية أثناء تنبيه في الخلفية، من دون وضع علامة عليها بأنها متصلة:

{  "event": "node.presence.alive",  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"هاتف iPhone الخاص بـ Peter\",\"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). لا يُحفظ الحدث إلا لجلسات أجهزة العُقد الموثّقة؛ أما الجلسات التي لا تتضمن جهازًا أو غير المقترنة فتعيد handled: false.

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

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

قد تعيد بوابات Gateway الأقدم { "ok": true } فقط من أجل node.event؛ تعامل مع ذلك بصفته إقرارًا باستدعاء RPC، وليس حفظًا دائمًا للحضور.

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

تخضع أحداث البث التي يدفعها الخادم لنطاقات الصلاحية، بحيث لا تتلقى الجلسات المقيّدة بنطاق الاقتران أو المخصصة للعُقد فقط محتوى الجلسة بشكل سلبي (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: تغيّر تكوين مشغّل كلمة الإيقاظ.
• exec.approval.requested / exec.approval.resolved: دورة حياة موافقة التنفيذ.
• plugin.approval.requested / plugin.approval.resolved: دورة حياة موافقة Plugin.

طرائق مساعدة Node

يمكن لعُقد Node استدعاء skills.bins لجلب القائمة الحالية لملفات Skills التنفيذية من أجل عمليات التحقق من السماح التلقائي.

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 دون تغيير، ولا تعيد إلا سجلات تشغيل الوكيل وإجراءات الأدوات. ينبغي لعملاء المشغّل الجدد استدعاء audit.activity.list عندما يعلن Gateway دعمه. قد تُبلغ بوابات Gateway الأقدم إما عن unknown method: audit.activity.list أو، لأن التخويل كان يسبق البحث عن الطريقة في الإصدارات المشحونة، عن missing scope: operator.admin لطلب ذي نطاق قراءة. لا تتعامل مع الحالة الأخيرة على أنها غياب للطريقة إلا عندما لا تكون الطريقة مُعلنة. ويمكن للعميل حينها إعادة محاولة audit.list فقط عندما لا تتطلب مرشحاته دعم نوع الرسالة، أو الاتجاه، أو القناة.

استخدم openclaw audit للاستعلامات النصية وصادرات JSON المحدودة.

استدعاءات RPC لسجل المهام

يفحص عملاء المشغّل سجلات مهام Gateway في الخلفية ويلغونها عبر استدعاءات RPC لسجل المهام (packages/gateway-protocol/src/schema/tasks.ts). تعيد هذه ملخصات منقّحة للمهام، لا حالة وقت التشغيل الخام.

• 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 خاصًا قبل تثبيته. هذا مسار تحميل منفصل للمسؤول ومخصص للعملاء الموثوقين، وليس مسار تثبيت Skill المعتاد في 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 اختياريًا (src/agents/model-catalog-visibility.ts):

• محذوف أو "default": إذا جرى تكوين agents.defaults.models، فتكون الاستجابة هي الكتالوج المسموح به، بما في ذلك النماذج المكتشفة ديناميكيًا لإدخالات provider/*. وإلا فتكون الاستجابة هي كتالوج Gateway الكامل.
• "configured": سلوك بحجم أداة الاختيار. إذا جرى تكوين agents.defaults.models، فإنه يظل ذا الأولوية، بما في ذلك الاكتشاف المحدد النطاق بحسب المزوّد لإدخالات provider/*. من دون قائمة سماح، تستخدم الاستجابة إدخالات models.providers.<provider>.models الصريحة، ولا تعود إلى الكتالوج الكامل إلا عند عدم وجود صفوف نماذج مكوّنة.
• "provider-config": مخزون 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 القياسي نفسه بوصفه سياق الأمر/مجلد العمل الحالي/الجلسة المعتمد.
• إذا عدّل مستدعٍ 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 و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 نفسها. لا تتغير مصادقة الجهاز والإقران والنطاقات وسياسة الأوامر وموافقات التنفيذ بفعل نافذة التوافق هذه. تُحجب إمكانات 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 بالسر المشترك connect.params.auth.token أو connect.params.auth.password، حسب gateway.auth.mode المُهيأ ("none" | "token" | "password" | "trusted-proxy").
• تستوفي الأوضاع الحاملة للهوية، مثل Tailscale Serve ‏(gateway.auth.allowTailscale: true) أو gateway.auth.mode: "trusted-proxy" غير ذي الاسترجاع المحلي، فحص مصادقة الاتصال من ترويسات الطلب بدلاً من 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 على نقاط النهاية الموثوقة فقط: الاسترجاع المحلي، أو 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:// أو الاقتران عبر الاسترجاع المحلي/المحلي.
• إذا قدّم العميل 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 (packages/gateway-protocol/src/connect-error-details.ts).
• سلوك العميل عند AUTH_TOKEN_MISMATCH:
  • يجوز للعملاء الموثوقين محاولة إعادة واحدة محدودة باستخدام رمز مخزّن مؤقتًا خاص بكل جهاز.
  • إذا فشلت إعادة المحاولة، فأوقف حلقات إعادة الاتصال التلقائية وأظهر إرشادات الإجراء المطلوب من المشغّل.
• تعني AUTH_SCOPE_MISMATCH أن رمز الجهاز قد تم التعرف عليه، لكنه لا يغطي الدور أو النطاقات المطلوبة. لا تعرض هذا باعتباره رمزًا غير صالح؛ اطلب من المشغّل إعادة الاقتران أو الموافقة على عقد النطاقات الأضيق أو الأوسع.

هوية الجهاز والاقتران

• ينبغي للعقد تضمين هوية جهاز ثابتة (device.id) مشتقة من بصمة زوج مفاتيح.
• تصدر بوابات Gateway رموزًا لكل جهاز ودور.
• تلزم موافقات الاقتران لمعرّفات الأجهزة الجديدة ما لم تكن الموافقة التلقائية المحلية مفعّلة.
• تتركز الموافقة التلقائية على الاقتران حول الاتصالات المحلية المباشرة عبر الاسترجاع المحلي.
• يتضمن OpenClaw أيضًا مسار اتصال ذاتي ضيقًا محليًا بالنسبة إلى الواجهة الخلفية/الحاوية لتدفقات المساعد الموثوقة التي تستخدم السر المشترك.
• تظل الاتصالات من المضيف نفسه عبر الشبكة الخاصة أو LAN تُعامل على أنها بعيدة لأغراض الاقتران وتتطلب الموافقة.
• تتضمن عملاء WS عادةً هوية device أثناء connect (المشغّل + العقدة). والاستثناءات الوحيدة للمشغّل من دون جهاز هي مسارات الثقة الصريحة:
  • gateway.controlUi.allowInsecureAuth=true للتوافق مع HTTP غير الآمن والمقتصر على المضيف المحلي.
  • مصادقة ناجحة لواجهة Control UI الخاصة بالمشغّل عبر gateway.auth.mode: "trusted-proxy".
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (ملاذ أخير، خفض شديد للأمان).
  • استدعاءات RPC المباشرة عبر الاسترجاع المحلي لواجهة gateway-client الخلفية على مسار المساعد الداخلي المحجوز.
• يترتب على حذف هوية الجهاز عواقب تخص النطاقات. عندما يُسمح باتصال مشغّل من دون جهاز عبر مسار ثقة صريح، يظل OpenClaw يمسح النطاقات المعلنة ذاتيًا إلى مجموعة فارغة ما لم يكن لذلك المسار استثناء مسمى للاحتفاظ بالنطاقات. عندئذ تفشل الأساليب المقيّدة بالنطاقات مع missing scope.
• يُعد gateway.controlUi.dangerouslyDisableDeviceAuth=true مسارًا لواجهة Control UI للاحتفاظ بالنطاقات في حالات الملاذ الأخير. ولا يمنح نطاقات إلى عملاء WebSocket مخصصين عشوائيين على هيئة واجهة خلفية أو CLI.
• يحتفظ مسار مساعد الواجهة الخلفية المحجوز والمباشر عبر الاسترجاع المحلي gateway-client بالنطاقات فقط لاستدعاءات 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)، التي تربط platform وdeviceFamily إضافة إلى حقول الجهاز والعميل والدور والنطاقات والرمز وnonce.
• تظل توقيعات v2 القديمة مقبولة للتوافق، لكن تثبيت البيانات الوصفية للجهاز المقترن يظل يتحكم في سياسة الأوامر عند إعادة الاتصال.

TLS والتثبيت

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

النطاق

يتيح هذا البروتوكول واجهة Gateway API الكاملة: الحالة، والقنوات، والنماذج، والمحادثة، والوكيل، والجلسات، والعقد، والموافقات، وغير ذلك. ويُحدد السطح الدقيق بواسطة مخططات TypeBox المُعاد تصديرها من packages/gateway-protocol/src/schema.ts.

ذو صلة

• بروتوكول الجسر
• دليل تشغيل Gateway