بنية IPC في macOS لدى OpenClaw

يربط مقبس Unix محلي خدمة مضيف Node بتطبيق macOS للحصول على موافقات التنفيذ وتشغيل system.run. تتوفر CLI لتصحيح الأخطاء باسم openclaw-mac ‏(apps/macos/Sources/OpenClawMacCLI) لإجراء عمليات التحقق من الاكتشاف والاتصال؛ ومع ذلك، تظل إجراءات الوكيل تتدفق عبر WebSocket الخاص بـ Gateway وnode.invoke. يشغّل مسار computer.act المدعوم بـ Node أتمتة Peekaboo المضمّنة داخل العملية؛ بينما تستخدم عملاء Peekaboo المستقلة PeekabooBridge.

الأهداف

• مثيل واحد لتطبيق واجهة المستخدم الرسومية يتولى جميع الأعمال التي تتعامل مع TCC (الإشعارات وتسجيل الشاشة والميكروفون والكلام وAppleScript).
• واجهة محدودة للأتمتة: Gateway وأوامر Node، وcomputer.act داخل العملية، بالإضافة إلى PeekabooBridge لعملاء أتمتة واجهة المستخدم المستقلين.
• أذونات متوقعة: استخدام معرّف حزمة موقّع واحد دائمًا، وتشغيله بواسطة launchd، لكي تظل منح أذونات TCC سارية.

آلية العمل

نقل Gateway وNode

• يشغّل التطبيق Gateway (في الوضع المحلي) ويتصل به بصفته Node.
• تُنفَّذ إجراءات الوكيل عبر node.invoke (مثل system.run وsystem.notify وcanvas.*).
• تتضمن أوامر Node: ‏canvas.* وcamera.snap وcamera.clip وscreen.snapshot وscreen.record وcomputer.act وsystem.run وsystem.notify.
• يبلّغ Node عن خريطة permissions لكي تتمكن الوكلاء من معرفة مدى توفر الوصول إلى الشاشة أو الكاميرا أو الميكروفون أو الكلام أو الأتمتة أو تسهيلات الاستخدام.

خدمة Node وIPC مع التطبيق

• تتصل خدمة مضيف Node بلا واجهة رسومية بـ WebSocket الخاص بـ Gateway.
• تُمرَّر طلبات system.run إلى تطبيق macOS عبر مقبس Unix محلي (ExecApprovalsSocket.swift).
• ينفّذ التطبيق الأمر في سياق واجهة المستخدم، ويعرض مطالبة عند الحاجة، ثم يعيد المخرجات.

المخطط (SCI):

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

PeekabooBridge (أتمتة واجهة المستخدم)

• لا تستخدم أداة computer المضمّنة للوكيل هذا المقبس. تنفّذ Node مقترنة بنظام macOS الإجراء computer.act داخل عملية التطبيق باستخدام خدمات Peekaboo المضمّنة.
• تستخدم أتمتة واجهة المستخدم مقبس UNIX منفصلًا (~/Library/Application Support/OpenClaw/<socket>) وبروتوكول JSON الخاص بـ PeekabooBridge.
• ترتيب تفضيل المضيف (من جانب العميل): Peekaboo.app ثم Claude.app ثم OpenClaw.app ثم التنفيذ المحلي.
• الأمان: تتطلب مضيفات الجسر TeamID مدرجًا في قائمة السماح (يدرج PeekabooBridgeHostCoordinator المضمّن فريقًا ثابتًا بالإضافة إلى فريق توقيع التطبيق نفسه في قائمة السماح)؛ وتوجد آلية تجاوز لمعرّف المستخدم نفسه خاصة بوضع DEBUG فقط، ويتحكم فيها PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (وفق اصطلاح Peekaboo).
• راجع: استخدام PeekabooBridge للاطلاع على التفاصيل.

تدفقات التشغيل

• إعادة التشغيل/إعادة البناء: ينهي scripts/restart-mac.sh المثيلات الموجودة، ويعيد البناء باستخدام Swift، ويعيد التحزيم، ثم يعيد التشغيل. يكتشف تلقائيًا هوية توقيع متاحة، ويرجع إلى --no-sign إذا لم يعثر على أي هوية؛ مرّر --sign لفرض التوقيع (يفشل إذا لم يتوفر مفتاح) أو --no-sign لفرض المسار غير الموقّع. يُلغى تعيين SIGN_IDENTITY في البيئة ضمن المسار الموقّع، لكي يختار الاكتشاف التلقائي للهوية في scripts/codesign-mac-app.sh الشهادة.
• مثيل واحد: يفحص التطبيق NSWorkspace.runningApplications بحثًا عن معرّف حزمة مكرر، ويخرج إذا عثر على أكثر من مثيل واحد (isDuplicateInstance() في MenuBar.swift).

ملاحظات التحصين

• يُفضّل اشتراط تطابق TeamID لجميع الواجهات ذات الامتيازات.
• PeekabooBridge: قد يسمح PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (في وضع DEBUG فقط) للجهات المستدعية التي تحمل معرّف المستخدم نفسه لأغراض التطوير المحلي.
• تظل جميع الاتصالات محلية فقط؛ ولا تُكشف أي مقابس شبكة.
• تنشأ مطالبات TCC من حزمة تطبيق واجهة المستخدم الرسومية فقط؛ حافظ على استقرار معرّف الحزمة الموقّع عبر عمليات إعادة البناء.
• تحصين مقبس موافقات التنفيذ: وضع الملف 0600، ورمز مميز مشترك، وفحص معرّف المستخدم للنظير (getpeereid)، وآلية تحدٍّ/استجابة باستخدام HMAC-SHA256، ومدة صلاحية قصيرة للطلبات.

ذو صلة

• تطبيق macOS
• تدفق IPC في macOS (موافقات التنفيذ)