macOS companion app
إعداد بيئة التطوير على macOS
إعداد مطور macOS
ابنِ وشغّل تطبيق OpenClaw لنظام macOS من المصدر.
المتطلبات الأساسية
قبل بناء التطبيق، تأكد من تثبيت ما يلي لديك:
- Xcode 26.2+: مطلوب لتطوير Swift.
- Node.js 24 و pnpm: موصى بهما من أجل Gateway وCLI وسكربتات التحزيم. يظل Node 22 LTS، حاليًا
22.19+، مدعومًا للتوافق.
1. تثبيت الاعتماديات
ثبّت الاعتماديات على مستوى المشروع:
pnpm install2. بناء التطبيق وتحزيمه
لبناء تطبيق macOS وتحزيمه في dist/OpenClaw.app، شغّل:
./scripts/package-mac-app.shإذا لم تكن لديك شهادة Apple Developer ID، فسيستخدم السكربت تلقائيًا التوقيع المخصص (-).
لأوضاع التشغيل التطويرية، وأعلام التوقيع، واستكشاف مشكلات معرّف الفريق وإصلاحها، راجع ملف README لتطبيق macOS: https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md
ملاحظة: قد تؤدي التطبيقات الموقعة توقيعًا مخصصًا إلى ظهور مطالبات أمان. إذا تعطل التطبيق فورًا مع "إحباط المصيدة 6"، فراجع قسم استكشاف الأخطاء وإصلاحها.
3. تثبيت CLI وGateway
يتضمن التطبيق المحزّم مثبّت scripts/install-cli.sh المعتمد. على ملف
تعريف جديد، اختر هذا الـ Mac أثناء الإعداد الأولي؛ يثبّت التطبيق
CLI ومسار التشغيل المطابقين في مساحة المستخدم قبل بدء معالج Gateway.
للاسترداد اليدوي أثناء التطوير، ثبّت CLI المطابق بنفسك:
npm install -g openclaw@<version>يعمل أيضًا pnpm add -g openclaw@<version> وbun add -g openclaw@<version>.
بالنسبة إلى مسار تشغيل Gateway، يظل Node هو المسار الموصى به.
استكشاف الأخطاء وإصلاحها
فشل البناء: عدم تطابق سلسلة الأدوات أو SDK
يتوقع بناء تطبيق macOS أحدث SDK لنظام macOS وسلسلة أدوات Swift 6.2.
اعتماديات النظام (مطلوبة):
- أحدث إصدار macOS متاح في تحديث البرامج (مطلوب بواسطة SDKs الخاصة بـ Xcode 26.2)
- Xcode 26.2 (سلسلة أدوات Swift 6.2)
الفحوصات:
xcodebuild -versionxcrun swift --versionإذا لم تتطابق الإصدارات، فحدّث macOS/Xcode وأعد تشغيل البناء.
تعطل التطبيق عند منح الأذونات
إذا تعطل التطبيق عندما تحاول السماح بالوصول إلى التعرّف على الكلام أو الميكروفون، فقد يكون السبب ذاكرة TCC مؤقتة تالفة أو عدم تطابق في التوقيع.
الإصلاح:
-
أعد ضبط أذونات TCC:
bash tccutil reset All ai.openclaw.mac.debug -
إذا فشل ذلك، فغيّر
BUNDLE_IDمؤقتًا فيscripts/package-mac-app.shلفرض "بداية نظيفة" من macOS.
بقاء Gateway على "جارٍ البدء..." إلى أجل غير مسمى
إذا ظلت حالة Gateway على "جارٍ البدء..."، فتحقق مما إذا كانت عملية خاملة تحتفظ بالمنفذ:
openclaw gateway statusopenclaw gateway stop # If you're not using a LaunchAgent (dev mode / manual runs), find the listener:lsof -nP -iTCP:18789 -sTCP:LISTENإذا كان تشغيل يدوي يحتفظ بالمنفذ، فأوقف تلك العملية (Ctrl+C). كحل أخير، أنهِ PID الذي وجدته أعلاه.
