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

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

​

قبل تفعيله

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

​

التفعيل

openclaw plugins enable admin-http-rpc
openclaw gateway restart

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

openclaw plugins disable admin-http-rpc
openclaw gateway restart

​

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

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

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

​

المصادقة

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

​

نموذج الأمان

• يتيح تفعيل 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/rpc
Authorization: Bearer <gateway-token>
Content-Type: application/json

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

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

​

الاستجابة

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

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

​

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

• الاكتشاف: 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

​

مقارنة WebSocket

​

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

​

ذات صلة

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