أدوات مدمجة

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

موافقات التنفيذ هي التطبيق المصاحب / سياج الحماية لمضيف العقدة للسماح لوكيل معزول بتشغيل أوامر على مضيف حقيقي (gateway أو node). فكر فيها كقفل أمان مشترك: يُسمح بالأوامر فقط عندما تتفق السياسة + قائمة السماح + (اختياريًا) موافقة المستخدم جميعًا. موافقات التنفيذ هي إضافة إلى سياسة الأداة والبوابة المرتفعة (ما لم يتم تعيين المرتفعة على full، مما يتجاوز الموافقات). السياسة الفعالة هي الأكثر صرامة بين tools.exec.* وقيم الموافقات الافتراضية؛ إذا تم حذف حقل من الموافقات، يتم استخدام قيمة tools.exec. إذا كانت واجهة مستخدم التطبيق المصاحب غير متاحة، يتم حل أي طلب يتطلب مطالبة بواسطة الخيار الاحتياطي للسؤال (الافتراضي: رفض).

حيث يتم تطبيقها

يتم فرض موافقات التنفيذ محليًا على مضيف التنفيذ:

  • مضيف البوابة → عملية openclaw على جهاز البوابة
  • مضيف العقدة → مُشغّل العقدة (تطبيق macOS المصاحب أو مضيف العقدة بدون واجهة)

تقسيم macOS:

  • خدمة مضيف العقدة تُمرر system.run إلى تطبيق macOS عبر IPC محلي.
  • تطبيق macOS يفرض الموافقات + ينفذ الأمر في سياق واجهة المستخدم.

الإعدادات والتخزين

تعيش الموافقات في ملف JSON محلي على مضيف التنفيذ: ~/.openclaw/exec-approvals.json مثال على المخطط:

{
  "version": 1,
  "socket": {
    "path": "~/.openclaw/exec-approvals.sock",
    "token": "base64url-token"
  },
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "askFallback": "deny",
      "autoAllowSkills": true,
      "allowlist": [
        {
          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
          "pattern": "~/Projects/**/bin/rg",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}

عناصر التحكم في السياسة

الأمان (exec.security)

  • deny: حظر جميع طلبات تنفيذ المضيف.
  • allowlist: السماح فقط بالأوامر الموجودة في قائمة السماح.
  • full: السماح بكل شيء (مكافئ للمرتفع).

السؤال (exec.ask)

  • off: عدم المطالبة أبدًا.
  • on-miss: المطالبة فقط عندما لا يتطابق مع قائمة السماح.
  • always: المطالبة عند كل أمر.

الخيار الاحتياطي للسؤال (askFallback)

إذا كانت المطالبة مطلوبة ولكن لا يمكن الوصول إلى واجهة مستخدم، يقرر الخيار الاحتياطي:

  • deny: حظر.
  • allowlist: السماح فقط إذا تطابق مع قائمة السماح.
  • full: السماح.

قائمة السماح (لكل وكيل)

قوائم السماح هي لكل وكيل. إذا وجد وكلاء متعددون، قم بالتبديل بين الوكيل الذي تقوم بتعديله في تطبيق macOS. الأنماط هي تطابقات نمطية غير حساسة لحالة الأحرف. يجب أن تحل الأنماط إلى مسارات ثنائية (يتم تجاهل الإدخالات التي تحتوي على الاسم الأساسي فقط). يتم ترحيل إدخالات agents.default القديمة إلى agents.main عند التحميل. أمثلة:

  • ~/Projects/**/bin/peekaboo
  • ~/.local/bin/*
  • /opt/homebrew/bin/rg

يتتبع كل إدخال في قائمة السماح:

  • id UUID ثابت يستخدم للهوية في واجهة المستخدم (اختياري)
  • آخر استخدام الطابع الزمني
  • آخر أمر مستخدم
  • آخر مسار تم حله

السماح التلقائي لواجهات سطر أوامر المهارات

عند تمكين السماح التلقائي لواجهات سطر أوامر المهارات، يتم التعامل مع الملفات القابلة للتنفيذ المشار إليها بواسطة المهارات المعروفة على أنها مسموح بها على العقد (عقدة macOS أو مضيف عقدة بدون واجهة). يستخدم هذا skills.bins عبر Gateway RPC لجلب قائمة bins الخاصة بالمهارة. قم بتعطيل هذا إذا كنت تريد قوائم سماح يدوية صارمة.

الملفات الثنائية الآمنة (stdin فقط)

يحدد tools.exec.safeBins قائمة صغيرة من الملفات الثنائية للإدخال القياسي فقط (على سبيل المثال jq) التي يمكنها التشغيل في وضع قائمة السماح بدون إدخالات صريحة في قائمة السماح. ترفض الملفات الثنائية الآمنة وسيطات الملفات الموضعية والرموز الشبيهة بالمسار، لذا يمكنها فقط العمل على الدفق الوارد. التحقق حتمي من شكل argv فقط (بدون فحوصات وجود نظام ملفات المضيف)، مما يمنع سلوك أوراكل وجود الملف من اختلافات السماح/الرفض. يتم رفض الخيارات الموجهة للملفات للملفات الثنائية الآمنة الافتراضية (على سبيل المثال sort -o, sort --output, sort --files0-from, sort --compress-program, wc --files0-from, jq -f/--from-file, grep -f/--file). تفرض الملفات الثنائية الآمنة أيضًا سياسة علم صريحة لكل ملف ثنائي للخيارات التي تكسر سلوك stdin فقط (على سبيل المثال sort -o/--output/--compress-program وأعلام grep العودية). تفرض الملفات الثنائية الآمنة أيضًا معاملة الرموز argv كـ نص حرفي في وقت التنفيذ (بدون توسيع النمط وبدون توسيع $VARS) للأجزاء الخاصة بـ stdin فقط، لذا لا يمكن استخدام أنماط مثل * أو $HOME/... لتهريب قراءات الملفات. يجب أيضًا أن تحل الملفات الثنائية الآمنة من أدلة الملفات الثنائية الموثوقة (الافتراضيات النظامية بالإضافة إلى PATH لعملية البوابة عند بدء التشغيل). هذا يحجب محاولات اختطاف PATH ذات النطاق المحدد للطلب. لا يُسمح بتسلسل shell وإعادة التوجيه تلقائيًا في وضع قائمة السماح. يُسمح بتسلسل shell (&&, ||, ;) عندما يلبي كل جزء من المستوى الأعلى قائمة السماح (بما في ذلك الملفات الثنائية الآمنة أو السماح التلقائي للمهارة). تظل عمليات إعادة التوجيه غير مدعومة في وضع قائمة السماح. يتم رفض الاستبدال بالأمر ($() / backticks) أثناء تحليل قائمة السماح، بما في ذلك داخل علامات الاقتباس المزدوجة؛ استخدم علامات الاقتباس المفردة إذا كنت بحاجة إلى نص حرفي $(). في موافقات تطبيق macOS المصاحب، يتم التعامل مع نص shell الخام الذي يحتوي على بناء تحكم أو توسيع في shell (&&, ||, ;, |, ```, $, <, >, (, )) على أنه عدم تطابق مع قائمة السماح ما لم يكن الملف الثنائي لـ shell نفسه مسموحًا به. الملفات الثنائية الآمنة الافتراضية: jq, cut, uniq, head, tail, tr, wc. grep و sort غير موجودين في القائمة الافتراضية. إذا قمت بالاشتراك، احتفظ بإدخالات صريحة في قائمة السماح لسير عملها غير stdin. بالنسبة لـ grep في وضع الملف الثنائي الآمن، قدم النمط باستخدام -e/--regexp؛ يتم رفض شكل النمط الموضعي حتى لا يمكن تهريب معاملات الملفات كمعاملات موضعية غامضة.

تحرير واجهة التحكم

استخدم واجهة التحكم → العقد → موافقات التنفيذ لتحرير الافتراضيات، والتجاوزات لكل وكيل، وقوائم السماح. اختر نطاقًا (الافتراضيات أو وكيل)، عدل السياسة، أضف/أزل أنماط قائمة السماح، ثم احفظ. تظهر واجهة المستخدم بيانات آخر استخدام لكل نمط حتى تتمكن من الحفاظ على القائمة مرتبة. يختار محدد الهدف البوابة (الموافقات المحلية) أو عقدة. يجب أن تعلن العقد عن system.execApprovals.get/set (تطبيق macOS أو مضيف عقدة بدون واجهة). إذا لم تعلن عقدة عن موافقات التنفيذ بعد، قم بتحرير ملفها المحلي ~/.openclaw/exec-approvals.json مباشرة. سطر الأوامر: openclaw approvals يدعم تحرير البوابة أو العقدة (انظر موافقات سطر الأوامر).

تدفق الموافقة

عندما تكون المطالبة مطلوبة، تبث البوابة exec.approval.requested إلى عملاء المشغل. تحلها واجهة التحكم وتطبيق macOS عبر exec.approval.resolve، ثم تقدم البوابة الطلب المعتمد إلى مضيف العقدة. عندما تكون الموافقات مطلوبة، تُرجع أداة التنفيذ على الفور بمعرف موافقة. استخدم ذلك المعرف لربط أحداث النظام اللاحقة (Exec finished / Exec denied). إذا لم تصل أي قرار قبل انتهاء المهلة، يتم التعامل مع الطلب على أنه انتهاء مهلة الموافقة ويتم عرضه كسبب للرفض. يتضمن حوار التأكيد:

  • الأمر + الوسيطات
  • cwd
  • معرف الوكيل
  • مسار الملف القابل للتنفيذ الذي تم حله
  • بيانات وصفية للمضيف + السياسة

الإجراءات:

  • السماح مرة واحدة → التشغيل الآن
  • السماح دائمًا → إضافة إلى قائمة السماح + التشغيل
  • الرفض → حظر

تحويل الموافقات إلى قنوات الدردشة

يمكنك تحويل مطالبات موافقة التنفيذ إلى أي قناة دردشة (بما في ذلك قنوات الإضافات) والموافقة عليها باستخدام /approve. يستخدم هذا خط أنابيب التسليم الصادر العادي. التكوين:

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session", // "session" | "targets" | "both"
      agentFilter: ["main"],
      sessionFilter: ["discord"], // substring or regex
      targets: [
        { channel: "slack", to: "U12345678" },
        { channel: "telegram", to: "123456789" },
      ],
    },
  },
}

الرد في الدردشة:

/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny

تدفق IPC لنظام macOS

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + approvals + system.run)

ملاحظات الأمان:

  • وضع مقبس Unix 0600، يتم تخزين الرمز المميز في exec-approvals.json.
  • فحص نظير UID نفسه.
  • تحدي/استجابة (nonce + HMAC token + hash الطلب) + TTL قصير.

أحداث النظام

يتم عرض دورة حياة التنفيذ كرسائل نظام:

  • Exec running (فقط إذا تجاوز الأمر عتبة إشعار التشغيل)
  • Exec finished
  • Exec denied

يتم نشر هذه في جلسة الوكيل بعد أن يبلغ العقدة عن الحدث. تصدر موافقات تنفيذ مضيف البوابة نفس أحداث دورة الحياة عند انتهاء الأمر (واختياريًا عند التشغيل لفترة أطول من العتبة). تعيد عمليات التنفيذ الخاضعة للموافقة استخدام معرف الموافقة كـ runId في هذه الرسائل لسهولة الارتباط.

الآثار المترتبة

  • full قوي؛ يُفضل استخدام قوائم السماح عندما يكون ذلك ممكنًا.
  • ask يبقيك في الحلقة مع السماح بالموافقات السريعة.
  • تمنع قوائم السماح لكل وكيل تسرب موافقات وكيل إلى الآخرين.
  • تنطبق الموافقات فقط على طلبات تنفيذ المضيف من المرسلين المصرح لهم. لا يمكن للمرسلين غير المصرح لهم إصدار /exec.
  • /exec security=full هي راحة على مستوى الجلسة للمشغلين المصرح لهم وتتجاوز الموافقات عن قصد. لمنع تنفيذ المضيف بقوة، اضبط أمان الموافقات على deny أو ارفض أداة exec عبر سياسة الأداة.

ذات صلة:

أداة التنفيذFirecrawl