نظرة عامة على المنصات

تطبيق macOS

تطبيق macOS هو الرفيق الموجود في شريط القائمة لـ OpenClaw. وهو يمتلك الأذونات، ويدير/يرتبط بالبوابة محليًا (launchd أو يدويًا)، ويعرض إمكانيات نظام macOS للوكيل كعقدة.

ما يفعله

  • يعرض إشعارات أصلية والحالة في شريط القائمة.
  • يمتلك مطالبات TCC (الإشعارات، إمكانية الوصول، تسجيل الشاشة، الميكروفون، التعرف على الكلام، الأتمتة/AppleScript).
  • يشغل أو يتصل بالبوابة (محليًا أو عن بُعد).
  • يكشف عن أدوات خاصة بـ macOS فقط (Canvas، الكاميرا، تسجيل الشاشة، system.run).
  • يبدأ خدمة مضيف العقدة المحلية في الوضع البعيد (launchd)، ويتوقف عنها في الوضع المحلي.
  • يستضيف اختياريًا PeekabooBridge لأتمتة واجهة المستخدم.
  • يثبت واجهة سطر الأوامر العالمية (openclaw) عبر npm/pnpm عند الطلب (لا يُوصى بـ bun لوقت تشغيل البوابة).

الوضع المحلي مقابل البعيد

  • المحلي (الافتراضي): يربط التطبيق ببوابة محلية قيد التشغيل إذا كانت موجودة؛ وإلا فإنه يمكّن خدمة launchd عبر openclaw gateway install.
  • البعيد: يتصل التطبيق ببوابة عبر SSH/Tailscale ولا يبدأ عملية محلية أبدًا. يبدأ التطبيق خدمة مضيف العقدة المحلية حتى تتمكن البوابة البعيدة من الوصول إلى هذا الـ Mac. لا ينشئ التطبيق البوابة كعملية تابعة.

التحكم في Launchd

يدير التطبيق وكيل LaunchAgent لكل مستخدم مُوسوم بـ ai.openclaw.gateway (أو ai.openclaw.<profile> عند استخدام --profile/OPENCLAW_PROFILE؛ لا يزال com.openclaw.* القديم يُفصل).

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

استبدل الوسم بـ ai.openclaw.<profile> عند تشغيل ملف تعريف مسمى. إذا لم يكن LaunchAgent مثبتًا، فعّله من التطبيق أو شغل openclaw gateway install.

إمكانيات العقدة (mac)

يعرض تطبيق macOS نفسه كعقدة. الأوامر الشائعة:

  • Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
  • الكاميرا: camera.snap, camera.clip
  • الشاشة: screen.record
  • النظام: system.run, system.notify

تقرر العقدة خريطة permissions حتى يتمكن الوكلاء من تحديد ما هو مسموح به. خدمة العقدة + اتصال بين العمليات للتطبيق:

  • عندما تكون خدمة مضيف العقدة بدون واجهة قيد التشغيل (الوضع البعيد)، تتصل بـ Gateway WS كعقدة.
  • يتم تنفيذ system.run في تطبيق macOS (سياق واجهة المستخدم/TCC) عبر مقبس يونيكس محلي؛ تبقى المطالبات والإخراج داخل التطبيق.

مخطط (SCI):

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

موافقات التنفيذ (system.run)

يتم التحكم في system.run من خلال موافقات التنفيذ في تطبيق macOS (الإعدادات → موافقات التنفيذ). يتم تخزين الأمان + السؤال + القائمة المسموح بها محليًا على الـ Mac في:

~/.openclaw/exec-approvals.json

مثال:

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}

ملاحظات:

  • إدخالات allowlist هي أنماط عامة لمسارات الملفات الثنائية المحلولة.
  • نص أمر shell الخام الذي يحتوي على بناء تحكم أو توسيع في shell (&&, ||, ;, |, ```, $, <, >, (, )) يعتبر خطأ في القائمة المسموح بها ويتطلب موافقة صريحة (أو إدراج الملف الثنائي لـ shell في القائمة المسموح بها).
  • اختيار "السماح دائمًا" في المطالبة يضيف هذا الأمر إلى القائمة المسموح بها.
  • يتم تصفية تجاوزات بيئة system.run (يحذف PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4) ثم دمجها مع بيئة التطبيق.
  • بالنسبة لبرامج غلاف shell (bash|sh|zsh ... -c/-lc)، يتم تقليل تجاوزات البيئة ذات النطاق المحدد للطلب إلى قائمة مسموح بها صريحة صغيرة (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
  • لقرارات السماح دائمًا في وضع القائمة المسموح بها، تستمر برامج غلاف الإرسال المعروفة (env, nice, nohup, stdbuf, timeout) في مسارات الملفات القابلة للتنفيذ الداخلية بدلاً من مسارات الغلاف. إذا كان فك الغلاف غير آمن، فلن يتم حفظ أي إدخال في القائمة المسموح بها تلقائيًا.

الروابط العميقة

يسجل التطبيق مخطط عنوان URL openclaw:// للإجراءات المحلية.

openclaw://agent

يُطلق طلب agent للبوابة.

open 'openclaw://agent?message=Hello%20from%20deep%20link'

معلمات الاستعلام:

  • message (مطلوب)
  • sessionKey (اختياري)
  • thinking (اختياري)
  • deliver / to / channel (اختياري)
  • timeoutSeconds (اختياري)
  • key (مفتاح الوضع غير المراقب الاختياري)

السلامة:

  • بدون key، يطلب التطبيق تأكيدًا.
  • بدون key، يفرض التطبيق حدًا قصيرًا للرسالة لمطالبة التأكيد ويتجاهل deliver / to / channel.
  • باستخدام key صالح، يكون التشغيل غير مراقب (مخصص للأتمتات الشخصية).

سير العمل للمبتدئين (النموذجي)

  1. قم بتثبيت وتشغيل OpenClaw.app.
  2. أكمل قائمة التحقق من الأذونات (مطالبات TCC).
  3. تأكد من تفعيل الوضع المحلي وأن البوابة قيد التشغيل.
  4. قم بتثبيت واجهة سطر الأوامر إذا كنت تريد الوصول إلى الطرفية.

وضع دليل الحالة (macOS)

تجنب وضع دليل حالة OpenClaw الخاص بك في iCloud أو المجلدات الأخرى المتزامنة مع السحابة. يمكن للمسارات المدعومة بالمزامنة إضافة زمن انتقال وتسبب أحيانًا سباقات قفل ملف/مزامنة للجلسات والمعلومات الاعتمادية. يُفضل مسار حالة محلي غير متزامن مثل:

OPENCLAW_STATE_DIR=~/.openclaw

إذا اكتشف openclaw doctor الحالة تحت:

  • ~/Library/Mobile Documents/com~apple~CloudDocs/...
  • ~/Library/CloudStorage/...

فسوف يحذر ويوصي بالعودة إلى مسار محلي.

سير عمل البناء والتطوير (الأصلي)

  • cd apps/macos && swift build
  • swift run OpenClaw (أو Xcode)
  • حزمة التطبيق: scripts/package-mac-app.sh

تصحيح اتصال البوابة (واجهة سطر الأوامر لـ macOS)

استخدم واجهة سطر الأوامر للتصحيح لممارسة نفس منطق مصافحة WebSocket للبوابة والاكتشاف الذي يستخدمه تطبيق macOS، دون تشغيل التطبيق.

cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json

خيارات الاتصال:

  • --url <ws://host:port>: تجاوز التكوين
  • --mode <local|remote>: حل من التكوين (الافتراضي: التكوين أو محلي)
  • --probe: فرض فحص صحة جديد
  • --timeout <ms>: مهلة الطلب (الافتراضي: 15000)
  • --json: إخراج منظم للمقارنة

خيارات الاكتشاف:

  • --include-local: تضمين البوابات التي سيتم تصفيتها على أنها "محلية"
  • --timeout <ms>: نافذة الاكتشاف الإجمالية (الافتراضي: 2000)
  • --json: إخراج منظم للمقارنة

نصيحة: قارن بـ openclaw gateway discover --json لترى ما إذا كان خط أنابيب الاكتشاف الخاص بتطبيق macOS (NWBrowser + DNS‑SD fallback لشبكة الذيل) يختلف عن الاكتشاف القائم على dns-sd لواجهة سطر الأوامر Node.

هندسة الاتصال البعيد (أنفاق SSH)

عندما يعمل تطبيق macOS في الوضع البعيد، فإنه يفتح نفق SSH حتى تتمكن مكونات واجهة المستخدم المحلية من التحدث إلى بوابة بعيدة كما لو كانت على localhost.

النفق التحكمي (منفذ Gateway WebSocket)

  • الغرض: فحوصات الصحة، الحالة، الدردشة عبر الويب، التكوين، ومكالمات مستوى التحكم الأخرى.
  • المنفذ المحلي: منفذ البوابة (الافتراضي 18789)، ثابت دائمًا.
  • المنفذ البعيد: نفس منفذ البوابة على المضيف البعيد.
  • السلوك: لا يوجد منفذ محلي عشوائي؛ يعيد التطبيق استخدام نفق صحي موجود أو يعيد تشغيله إذا لزم الأمر.
  • شكل SSH: ssh -N -L <local>:127.0.0.1:<remote> مع BatchMode + ExitOnForwardFailure + خيارات keepalive.
  • الإبلاغ عن IP: يستخدم نفق SSH loopback، لذا سترى البوابة IP العقدة كـ 127.0.0.1. استخدم النقل المباشر (ws/wss) إذا كنت تريد ظهور IP العميل الحقيقي (انظر الوصول البعيد لـ macOS).

لخطوات الإعداد، انظر الوصول البعيد لـ macOS. للتفاصيل البروتوكولية، انظر بروتوكول البوابة.

الوثائق ذات الصلة

المنصاتتطبيق Linux