التطبيق المصاحب لنظام macOS

توقيع تطبيقات macOS

يتم بناء هذا التطبيق عادةً من scripts/package-mac-app.sh، والذي يقوم الآن بما يلي:

  • تعيين معرف حزمة تصحيح أخطاء ثابت: ai.openclaw.mac.debug
  • كتابة ملف Info.plist باستخدام معرف الحزمة ذلك (يمكن التجاوز عبر BUNDLE_ID=...)
  • استدعاء scripts/codesign-mac-app.sh لتوقيع الملف الثنائي الرئيسي وحزمة التطبيق بحيث يعامل نظام macOS كل إعادة بناء كحزمة موقعة نفسها ويحافظ على أذونات TCC (الإشعارات، إمكانية الوصول، تسجيل الشاشة، الميكروفون، الكلام). للحصول على أذونات مستقرة، استخدم هوية توقيع حقيقية؛ التوقيع المخصص (ad-hoc) اختياري وهش (انظر أذونات macOS).
  • استخدام CODESIGN_TIMESTAMP=auto افتراضيًا؛ فهو يمكّن الطوابع الزمنية الموثوقة لتوقيعات معرف المطور (Developer ID). اضبط CODESIGN_TIMESTAMP=off لتخطي وضع الطابع الزمني (بناءات تصحيح أخطاء دون اتصال).
  • حقن بيانات وصفية للبناء في Info.plist: OpenClawBuildTimestamp (بتوقيت UTC) و OpenClawGitCommit (تجزئة Git مختصرة) حتى تتمكن نافذة "حول" من عرض معلومات البناء، و Git، وقناة التصحيح/الإصدار.
  • يتطلب التعبئة Node 22+: ينفذ السكريبت بناءات TS وبناء واجهة التحكم (Control UI).
  • قراءة SIGN_IDENTITY من البيئة. أضف export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)" (أو شهادة معرف المطور للتطبيق الخاصة بك) إلى ملف shell rc الخاص بك لتوقيع التطبيق دائمًا بشهادتك. يتطلب التوقيع المخصص (ad-hoc) موافقة صريحة عبر ALLOW_ADHOC_SIGNING=1 أو SIGN_IDENTITY="-" (غير موصى به لاختبار الأذونات).
  • إجراء تدقيق لمعرف الفريق (Team ID) بعد التوقيع والفشل إذا كان أي ملف Mach-O داخل حزمة التطبيق موقّعًا بواسطة معرف فريق مختلف. اضبط SKIP_TEAM_ID_CHECK=1 للتجاوز.

الاستخدام

# من جذر المستودع
scripts/package-mac-app.sh               # يختار الهوية تلقائيًا؛ يحدث خطأ إذا لم يتم العثور على أي هوية
SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh   # شهادة حقيقية
ALLOW_ADHOC_SIGNING=1 scripts/package-mac-app.sh    # توقيع مخصص (لن تثبت الأذونات)
SIGN_IDENTITY="-" scripts/package-mac-app.sh        # توقيع مخصص صريح (نفس المحاذير)
DISABLE_LIBRARY_VALIDATION=1 scripts/package-mac-app.sh   # حل مؤقت لتطابق معرف فريق Sparkle (للتطوير فقط)

ملاحظة حول التوقيع المخصص (Ad-hoc)

عند التوقيع باستخدام SIGN_IDENTITY="-" (مخصص)، يقوم السكريبت تلقائيًا بتعطيل وقت التشغيل المعزز (--options runtime). هذا ضروري لمنع حدوث تعطل عندما يحاول التطبيق تحميل أطر العمل المضمنة (مثل Sparkle) التي لا تشترك في نفس معرف الفريق (Team ID). كما أن التوقيعات المخصصة (ad-hoc) تفسد استمرارية أذونات TCC؛ انظر أذونات macOS لخطوات الاستعادة.

بيانات وصفية للبناء لعرض "حول"

يقوم package-mac-app.sh بوضع علامة على الحزمة بـ:

  • OpenClawBuildTimestamp: توقيت ISO8601 UTC في وقت التعبئة
  • OpenClawGitCommit: تجزئة Git مختصرة (أو unknown إذا كانت غير متوفرة)

تقوم علامة التبويب "حول" بقراءة هذه المفاتيح لعرض الإصدار، وتاريخ البناء، وتفعيلة Git، وما إذا كان بناء تصحيح أخطاء (عبر #if DEBUG). قم بتشغيل أداة التعبئة لتحديث هذه القيم بعد إجراء تغييرات على الكود.

السبب

ترتبط أذونات TCC بمعرف الحزمة و التوقيع الرقمي. كانت بناءات التصحيح غير الموقعة ذات UUID المتغيرة تتسبب في نسيان نظام macOS للمنح بعد كل إعادة بناء. توقيع الملفات الثنائية (مخصص افتراضيًا) والحفاظ على معرف/مسار ثابت للحزمة (dist/OpenClaw.app) يحافظ على المنح بين عمليات البناء، بما يتوافق مع نهج VibeTunnel.

التحكم عن بعدإصدار macOS