Plugin RPC عبر HTTP للإدارة

يعرض Plugin المضمّن admin-http-rpc طرقًا مختارة من مستوى تحكم Gateway عبر HTTP لأتمتة المضيفات الموثوقة التي لا يمكنها استخدام عميل Gateway WebSocket RPC العادي.

يأتي هذا Plugin مضمنًا مع OpenClaw، لكنه معطّل افتراضيًا. عند تعطيله، لا يُسجَّل المسار. عند تفعيله، يضيف:

• POST /api/v1/admin/rpc
• نفس المستمع مثل Gateway: http://<gateway-host>:<port>/api/v1/admin/rpc

فعّله فقط لأدوات المضيف الخاصة، أو أتمتة شبكة tailnet، أو مدخل داخلي موثوق. لا تعرض هذا المسار مباشرةً للإنترنت العام.

قبل تفعيله

Admin HTTP RPC هو سطح كامل لمستوى تحكم المشغّل. يمكن لأي مستدعٍ يجتاز مصادقة Gateway عبر HTTP استدعاء الطرق المدرجة في قائمة السماح في هذه الصفحة.

استخدمه عندما تكون كل الشروط التالية صحيحة:

• المستدعي موثوق لتشغيل Gateway.
• المستدعي لا يمكنه استخدام عميل WebSocket RPC.
• المسار قابل للوصول فقط عبر loopback، أو شبكة tailnet، أو مدخل خاص موثّق.
• راجعت الطرق المسموح بها وهي تطابق الأتمتة التي تخطط لتشغيلها.

استخدم مسار WebSocket RPC لعملاء OpenClaw والأدوات التفاعلية التي يمكنها إبقاء اتصال Gateway WebSocket مفتوحًا.

التفعيل

فعّل Plugin المضمّن:

openclaw plugins enable admin-http-rpcopenclaw gateway restart

{  plugins: {    entries: {      "admin-http-rpc": { enabled: true },    },  },}

يُسجَّل المسار أثناء بدء تشغيل Plugin. أعد تشغيل Gateway بعد تغيير تكوين Plugin.

عطّله عندما لا تعود بحاجة إلى سطح HTTP:

openclaw plugins disable admin-http-rpcopenclaw gateway restart

التحقق من المسار

استخدم health كأصغر طلب آمن:

curl -sS http://<gateway-host>:<port>/api/v1/admin/rpc \  -H 'Authorization: Bearer <gateway-token>' \  -H 'Content-Type: application/json' \  -d '{"method":"health","params":{}}'

تحتوي الاستجابة الناجحة على ok: true:

{  "id": "generated-request-id",  "ok": true,  "payload": {    "status": "ok"  }}

عند تعطيل Plugin، يعيد المسار 404 لأنه غير مسجّل.

المصادقة

يستخدم مسار Plugin مصادقة Gateway عبر HTTP.

مسارات المصادقة الشائعة:

• مصادقة السر المشترك (gateway.auth.mode="token" أو "password"): Authorization: Bearer <token-or-password>
• مصادقة HTTP موثوقة حاملة للهوية (gateway.auth.mode="trusted-proxy"): مرّر المسار عبر الوكيل المكوّن والواعي بالهوية ودعه يحقن ترويسات الهوية المطلوبة
• مصادقة مفتوحة عبر مدخل خاص (gateway.auth.mode="none"): لا يلزم ترويسة مصادقة

نموذج الأمان

تعامل مع هذا Plugin كسطح كامل لمشغّل Gateway.

• يتيح تفعيل Plugin عمدًا الوصول إلى طرق admin RPC المدرجة في قائمة السماح عند /api/v1/admin/rpc.
• يعلن Plugin عقد البيان المحجوز contracts.gatewayMethodDispatch: ["authenticated-request"] حتى يتمكن مسار HTTP المصادق عليه من Gateway من إرسال طرق مستوى التحكم داخل العملية.
• تثبت مصادقة الحامل بالسر المشترك امتلاك سر مشغّل gateway.
• بالنسبة إلى مصادقة token وpassword، تُتجاهل ترويسات x-openclaw-scopes الأضيق وتُستعاد الإعدادات الافتراضية الكاملة العادية للمشغّل.
• تحترم أوضاع HTTP الموثوقة الحاملة للهوية x-openclaw-scopes عند وجودها.
• يعني gateway.auth.mode="none" أن هذا المسار غير موثّق إذا كان Plugin مفعّلًا. استخدم ذلك فقط خلف مدخل خاص تثق به بالكامل.
• تُرسَل الطلبات عبر معالجات طرق Gateway نفسها وفحوصات النطاق نفسها مثل WebSocket RPC بعد اجتياز مصادقة مسار Plugin.
• أبقِ هذا المسار على loopback، أو شبكة tailnet، أو مدخل خاص موثوق. لا تعرضه مباشرةً للإنترنت العام.
• عقود بيان Plugin ليست صندوقًا رمليًا. فهي تمنع الاستخدام العرضي لمساعدات SDK المحجوزة؛ ولا تزال Plugins الموثوقة تعمل داخل عملية Gateway.

استخدم بوابات منفصلة عندما يعبر المستدعون حدود الثقة.

الطلب

POST /api/v1/admin/rpcAuthorization: Bearer <gateway-token>Content-Type: application/json

{  "id": "optional-request-id",  "method": "health",  "params": {}}

الحقول:

• id (سلسلة، اختياري): يُنسخ إلى الاستجابة. يُنشأ UUID عند حذفه.
• method (سلسلة، مطلوب): اسم طريقة Gateway المسموح بها.
• params (أي نوع، اختياري): معاملات خاصة بالطريقة.

الحجم الأقصى الافتراضي لجسم الطلب هو 1 MB.

الاستجابة

تستخدم استجابات النجاح شكل Gateway RPC:

{  "id": "optional-request-id",  "ok": true,  "payload": {}}

تستخدم أخطاء طرق Gateway:

{  "id": "optional-request-id",  "ok": false,  "error": {    "code": "INVALID_REQUEST",    "message": "bad params"  }}

تتبع حالة HTTP خطأ Gateway عندما يكون ذلك ممكنًا. على سبيل المثال، يعيد INVALID_REQUEST الحالة 400، ويعيد UNAVAILABLE الحالة 503.

الطرق المسموح بها

• الاكتشاف: commands.list يعيد أسماء طرق HTTP RPC المسموح بها بواسطة هذا Plugin.
• البوابة: health, status, logs.tail, usage.status, usage.cost, gateway.restart.request
• التكوين: config.get, config.schema, config.schema.lookup, config.set, config.patch, config.apply
• القنوات: channels.status, channels.start, channels.stop, channels.logout
• الويب: web.login.start, web.login.wait
• النماذج: models.list, models.authStatus
• الوكلاء: agents.list, agents.create, agents.update, agents.delete
• الموافقات: exec.approvals.get, exec.approvals.set, exec.approvals.node.get, exec.approvals.node.set
• Cron: cron.status, cron.list, cron.get, cron.runs, cron.add, cron.update, cron.remove, cron.run
• الأجهزة: device.pair.list, device.pair.approve, device.pair.reject, device.pair.remove
• العقد: node.list, node.describe, node.pair.list, node.pair.approve, node.pair.reject, node.pair.remove, node.rename
• المهام: tasks.list, tasks.get, tasks.cancel
• التشخيصات: doctor.memory.status, update.status

تُحظر طرق Gateway الأخرى إلى أن تُضاف عمدًا.

مقارنة WebSocket

يبقى مسار Gateway WebSocket RPC العادي واجهة API المفضلة لمستوى التحكم لعملاء OpenClaw. استخدم Admin HTTP RPC فقط لأدوات المضيف التي تحتاج إلى سطح HTTP بنمط طلب/استجابة.

لا يمكن لعملاء WebSocket ذوي الرمز المشترك من دون هوية جهاز موثوقة إعلان نطاقات المسؤول ذاتيًا أثناء الاتصال. يتبع Admin HTTP RPC عمدًا نموذج مشغّل HTTP الموثوق الحالي: عند تفعيل Plugin، تُعامل مصادقة الحامل بالسر المشترك كصلاحية وصول كاملة للمشغّل لهذا السطح الإداري.

استكشاف الأخطاء وإصلاحها

404 Not Found

: Plugin معطّل، أو لم يُعد تشغيل Gateway منذ تفعيله، أو أن الطلب يُرسل إلى عملية Gateway مختلفة.

401 Unauthorized

: لم يستوفِ الطلب مصادقة Gateway عبر HTTP. تحقق من رمز الحامل أو ترويسات هوية trusted-proxy.

400 INVALID_REQUEST

: جسم الطلب ليس JSON صالحًا، أو حقل method مفقود، أو الطريقة غير موجودة في قائمة السماح الخاصة بـ Plugin.

503 UNAVAILABLE

: معالج طريقة Gateway غير متاح. تحقق من سجلات Gateway وأعد المحاولة بعد انتهاء Gateway من بدء التشغيل.

ذات صلة

• نطاقات المشغّل
• أمان Gateway
• الوصول عن بُعد
• بيان Plugin
• المسارات الفرعية لـ SDK