اپلیکیشن iOS

دسترس‌پذیری: بیلدهای اپ iPhone، هنگامی که برای یک انتشار فعال باشند، از طریق کانال‌های Apple توزیع می‌شوند. بیلدهای توسعه محلی نیز می‌توانند از کد منبع اجرا شوند.

چه کاری انجام می‌دهد

• از طریق WebSocket به یک Gateway متصل می‌شود (LAN یا tailnet).
• قابلیت‌های Node را ارائه می‌کند: Canvas، عکس فوری از صفحه، ثبت تصویر دوربین، موقعیت مکانی، حالت مکالمه، فعال‌سازی صوتی و خلاصه‌های اختیاری Health.
• فرمان‌های node.invoke را دریافت و رویدادهای وضعیت Node را گزارش می‌کند.
• فضای کاری عامل انتخاب‌شده را به‌صورت فقط‌خواندنی از بخش عامل‌ها (فایل‌ها) مرور می‌کند: پیمایش در پوشه‌ها، پیش‌نمایش متنی با برجسته‌سازی نحو، پیش‌نمایش تصاویر و خروجی‌گرفتن از طریق برگه اشتراک‌گذاری. هیچ عملیات نوشتنی انجام نمی‌شود؛ اندازه پیش‌نمایش‌ها توسط Gateway محدود می‌شود.
• برای هر Gateway جفت‌شده، یک حافظه نهان آفلاین کوچک و فقط‌خواندنی از نشست‌ها و رونوشت‌های اخیر گفتگو نگه می‌دارد: هنگام اجرای سرد، آخرین رونوشت شناخته‌شده فوراً نمایش داده می‌شود و پس از پاسخ Gateway تازه‌سازی می‌شود، گفتگوهای اخیر در حالت قطع اتصال قابل مرور می‌مانند و بازنشانی/فراموش‌کردن، حافظه نهان محلی محافظت‌شده را پاک می‌کند.
• پیام‌های متنی ارسال‌شده در حالت قطع اتصال را در یک صندوق خروجی پایدار برای هر Gateway در صف قرار می‌دهد (حداکثر 50 پیام): حباب‌های در صف در رونوشت نمایش داده می‌شوند، هنگام اتصال مجدد به‌ترتیب و با تلاش‌های مجدد هم‌توان ارسال می‌شوند، تا زمانی که تاریخچه مرجع ارسال را تأیید کند پایدار می‌مانند، پیش از نمایش اقدام تلاش مجدد/حذف با وقفه افزایشی دوباره تلاش می‌شوند و پس از 48 ساعت آفلاین‌بودن به‌جای ارسال منقضی می‌شوند؛ بازنشانی/فراموش‌کردن، صف را همراه با حافظه نهان پاک می‌کند.
• گفتگو، بخش واحد متن و صدا است. اقدامات گفتگو می‌توانند بدون خروج از گفتگو، صفحه کامل نشست‌ها را باز کنند و استدلال دستیار و فعالیت ابزارها را نمایش دهند یا پنهان کنند. برای دیکته پیش‌نویس روی میکروفون بزنید، برای ضبط پیام صوتی منوی آن را باز کنید یا برای صدای بلادرنگ از کنترل درون‌خطی مکالمه استفاده کنید؛ کنترل مکالمه هنگام شنیدن یا صحبت‌کردن بر اساس سطح زنده میکروفون یا پخش متحرک می‌شود.
• تنظیمات -> OpenClaw هنگامی که اتصال اپراتور دارای operator.admin باشد و Gateway از openclaw.chat پشتیبانی کند، یک دستیار اختصاصی تنظیمات Gateway را باز می‌کند. گفتگوی راه‌اندازی آن از گفتگوی عادی جدا می‌ماند، پاسخ‌های محرمانه را به‌صورت محلی پنهان می‌کند و تنها پس از زدن بازکردن گفتگو به گفتگو منتقل می‌شود.
• پیام‌های دستیار را بنا به درخواست می‌خواند: روی پیامی در گفتگو لمس طولانی کنید و گوش‌دادن را انتخاب کنید. اپ، کلیپ‌های tts.speak پشتیبانی‌شده Gateway را با ارائه‌دهنده پیکربندی‌شده TTS پخش می‌کند و هنگامی که صدای Gateway در دسترس یا قابل پخش نباشد، به گفتار روی دستگاه برمی‌گردد. پخش با تعویض نشست یا رفتن اپ به پس‌زمینه متوقف می‌شود.

الزامات

• Gateway در دستگاه دیگری در حال اجرا باشد (macOS، Linux یا Windows از طریق WSL2).
• مسیر شبکه:
  • همان LAN از طریق Bonjour، یا
  • Tailnet از طریق DNS-SD تک‌پخشی (دامنه نمونه: openclaw.internal.)، یا
  • میزبان/درگاه دستی (مسیر جایگزین).

شروع سریع (جفت‌سازی + اتصال)

در نخستین اجرا، اپ یک توضیح کوتاه درباره جفت‌سازی و یک صفحه مجوزها (اعلان‌ها، دوربین، میکروفون، عکس‌ها، مخاطبان، تقویم، یادآورها، موقعیت مکانی) نمایش می‌دهد. اعطای همه مجوزها اختیاری است و می‌توان آن‌ها را بعداً در تنظیمات -> مجوزها یا در اپ Settings سیستم iOS تغییر داد.

1. یک Gateway احراز هویت‌شده را با مسیری راه‌اندازی کنید که تلفن بتواند به آن دسترسی پیدا کند. Tailscale Serve مسیر پیشنهادی برای دسترسی از راه دور است:

openclaw gateway --port 18789 --tailscale serve

برای یک راه‌اندازی قابل اعتماد در همان LAN، به‌جای آن از یک gateway.bind: "lan" احراز هویت‌شده استفاده کنید. اتصال پیش‌فرض loopback از تلفن قابل دسترسی نیست. اگر Gateway هنوز پیکربندی نشده است، ابتدا openclaw onboard را اجرا کنید تا ایجاد کد راه‌اندازی، مسیر احراز هویت با توکن یا گذرواژه داشته باشد.

2. رابط کنترل را باز کنید، Nodeها را انتخاب کنید و در صفحه دستگاه‌ها روی جفت‌سازی دستگاه همراه کلیک کنید. دسترسی کامل توصیه می‌شود و به‌طور پیش‌فرض انتخاب شده است؛ تنها زمانی دسترسی محدود را انتخاب کنید که می‌خواهید کنترل‌های مدیریتی Gateway حذف شوند، سپس روی ایجاد کد راه‌اندازی کلیک کنید.

3. در اپ iOS، تنظیمات -> Gateway را باز کنید، کد QR را اسکن کنید (یا کد راه‌اندازی را جای‌گذاری کنید) و متصل شوید.

   اگر کد راه‌اندازی هم مسیر LAN و هم مسیر Tailscale Serve داشته باشد، اپ آن‌ها را به‌ترتیب بررسی می‌کند و نخستین نقطه پایانی قابل دسترسی را ذخیره می‌کند.

   Gatewayهای جفت‌شده در فهرست Gatewayها باقی می‌مانند. علامت تیک، Gateway متمرکز را مشخص می‌کند؛ از کنترل صاعقه در ردیف دیگری استفاده کنید تا نشست اپراتور آن نیز هم‌زمان متصل بماند. تغییر تمرکز، سایر Gatewayهای فعال را قطع نمی‌کند. فقط Gateway متمرکز، نشست Node دارای قابلیت‌های iPhone را دریافت می‌کند؛ بنابراین دوربین، صفحه، موقعیت مکانی و دیگر فرمان‌های دستگاه همیشه یک مالک بدون ابهام دارند. ممکن است iOS پس از رفتن اپ به پس‌زمینه، این اتصال‌های پیش‌زمینه را معلق کند.

4. اپ رسمی به‌طور خودکار متصل می‌شود. اگر در انتظار تأیید درخواستی را نشان داد، پیش از تأیید، نقش و دامنه‌های دسترسی آن را بررسی کنید.

   تنظیمات → Gateway نشان می‌دهد اتصال اپراتور ذخیره‌شده دارای دسترسی کامل یا محدود است. راه‌اندازی متن ساده LAN با ws:// برای امنیت توکن حامل، به‌طور خودکار محدود می‌شود. اگر محدود است، wss:// یا Tailscale Serve را پیکربندی کنید، یک کد دسترسی کامل جدید را از رابط کنترل یا openclaw qr اسکن کنید، سپس برای فعال‌کردن تنظیمات و ارتقاها دوباره متصل شوید.

دکمه رابط کنترل به یک نشست از قبل جفت‌شده با operator.admin نیاز دارد. به‌عنوان مسیر جایگزین ترمینال، یک Gateway کشف‌شده را در اپ iOS انتخاب کنید (یا میزبان دستی را فعال و میزبان/درگاه را وارد کنید)، سپس درخواست را در میزبان Gateway تأیید کنید:

openclaw devices listopenclaw devices approve <requestId>

اگر اپ با جزئیات احراز هویت تغییریافته (نقش/دامنه‌ها/کلید عمومی) دوباره برای جفت‌سازی تلاش کند، درخواست در انتظار قبلی جایگزین می‌شود و یک requestId جدید ایجاد می‌شود. پیش از تأیید، دوباره openclaw devices list را اجرا کنید.

اختیاری: اگر Node سیستم iOS همیشه از یک زیرشبکه کاملاً کنترل‌شده متصل می‌شود، می‌توانید تأیید خودکار Node در نخستین اتصال را با CIDRهای صریح یا IPهای دقیق فعال کنید:

{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

این قابلیت به‌طور پیش‌فرض غیرفعال است. فقط برای جفت‌سازی تازه role: node بدون دامنه دسترسی درخواستی اعمال می‌شود. جفت‌سازی اپراتور/مرورگر و هرگونه تغییر نقش، دامنه دسترسی، فراداده یا کلید عمومی همچنان به تأیید دستی نیاز دارد.

5. اتصال را بررسی کنید:

openclaw nodes statusopenclaw gateway call node.list --params "{}"

خلاصه‌های Health

Node سیستم iOS می‌تواند یک تجمیع اختیاری و فقط‌خواندنی HealthKit را برای روز تقویمی جاری برگرداند. رضایت دستگاه iOS و مجوز صریح فرمان Gateway، دو مانع مستقل هستند. برای راه‌اندازی، فراخوانی، فیلدهای داده ارسالی، رفتار حریم خصوصی و عیب‌یابی، به خلاصه‌های HealthKit مراجعه کنید.

به‌طور پیش‌فرض، اپ همراه Apple Watch همچنان از رله موجود iPhone استفاده می‌کند و به جفت‌سازی جداگانه Gateway نیاز ندارد. Watch را در اپ Watch متعلق به Apple با iPhone جفت کنید، OpenClaw را از Watch app -> My Watch -> Available Apps نصب کنید، سپس OpenClaw را یک‌بار در هر دو دستگاه باز کنید.

بازبینی تأیید فرمان‌ها

یک اتصال اپراتور با operator.admin یا یک اتصال جفت‌شده operator.approvals که صراحتاً توسط Gateway هدف قرار گرفته است، می‌تواند درخواست‌های در انتظار اجرا را در iPhone بازبینی کند. کارت تأیید، پیش‌نمایش پاک‌سازی‌شده فرمان، هشدار، زمینه میزبان، زمان انقضا و تنها تصمیم‌های ارائه‌شده توسط آن درخواست را نمایش می‌دهد. Apple Watch جفت‌شده همان درخواست ایمن برای بازبین را از طریق رله موجود iPhone دریافت می‌کند و زیرمجموعه فشرده تصمیم‌های یک‌بار اجازه‌دادن/ردکردن را ارائه می‌دهد. حالت مستقیم Gateway در Watch، درخواست‌های تأیید را منتقل نمی‌کند.

وضعیت تأیید با رابط کنترل و بخش‌های گفتگوی پشتیبانی‌شده مشترک است. نخستین پاسخ ثبت‌شده برنده است. iPhone و Watch رکورد مرجع نهایی Gateway را پس از حل درخواست توسط بخش دیگری، پس از دریافت اعلان حل‌شدن از راه دور و هر زمان که ممکن است تأیید دریافت نتیجه از دست رفته باشد، دریافت می‌کنند. اقدامات تا زمانی که این بازخوانی تأیید نکند درخواست همچنان در انتظار است، غیرفعال می‌مانند.

مالکیت تأیید به Gateway انتخاب‌شده متصل است. تعویض Gatewayها نمی‌تواند درخواست قدیمی را روی اتصال جایگزین اعمال کند. Gatewayهایی که پیش از روش‌های یکپارچه تأیید ایجاد شده‌اند، به روش‌های عرضه‌شده مخصوص اجرا بازمی‌گردند؛ حفظ وضعیت نهایی و نتایج غنی‌تر بین‌بخشی به یک Gateway به‌روزشده نیاز دارد.

پاسخ به پرسش‌های عامل

گفتگو، پرسش‌های در انتظار Gateway را برای اتصال‌های اپراتور دارای operator.questions (یا operator.admin) به‌شکل کارت‌های بومی نمایش می‌دهد. کارت‌ها از گزینه‌های تک‌انتخابی و چندانتخابی، توضیحات گزینه‌ها، پاسخ‌های متنی آزاد سایر و شمارش معکوس انقضا پشتیبانی می‌کنند. اتصال مجدد، پرسش‌های در انتظار را از Gateway دوباره بارگیری می‌کند. کارت هنگامی قفل می‌شود که این دستگاه به آن پاسخ دهد، بخش دیگری زودتر به آن پاسخ دهد یا پرسش منقضی یا لغو شود.

Node مستقیم و اختیاری Apple Watch

حالت مستقیم به ساعت، هویت امضاشده Node و اتصال Gateway اختصاصی خودش را می‌دهد. تا زمانی که OpenClaw فعال است، فرمان‌های پشتیبانی‌شده Node از طریق Wi-Fi یا شبکه همراه ساعت همچنان کار می‌کنند، حتی اگر iPhone جفت‌شده در دسترس نباشد.

الزامات:

• iPhone با دامنه دسترسی operator.admin به Gateway متصل باشد.
• کد راه‌اندازی، یک نقطه پایانی Gateway با wss:// و گواهی مورد اعتماد watchOS را اعلام کند؛ ساعت مبدأ متناظر https:// را بررسی می‌کند. HTTP متن ساده و اعتماد مبتنی بر گواهی خودامضا یا فقط اثرانگشت پشتیبانی نمی‌شوند. برای پیکربندی نقطه پایانی به جفت‌سازی تحت مالکیت Gateway مراجعه کنید. مسیرهای loopback، مختص iPhone و فقط tailnet به‌طور مستقل از ساعت قابل دسترسی نیستند.
• استفاده از شبکه همراه به Apple Watch دارای قابلیت شبکه همراه و سرویس فعال نیاز دارد.
• OpenClaw در ساعت فعال باشد. Apple به اپ‌های معمولی watchOS اجازه نمی‌دهد اتصال‌های عمومی WebSocket/TCP را حفظ کنند؛ بنابراین Node مستقیم از نظرسنجی‌های کوتاه HTTPS استفاده می‌کند و هنگام بازگشت اپ به پیش‌زمینه دوباره متصل می‌شود. به راهنمای شبکه سطح پایین watchOS متعلق به Apple مراجعه کنید.

راه‌اندازی:

1. در iPhone، تنظیمات -> Apple Watch را باز کنید.
2. روی فعال‌کردن اتصال مستقیم Gateway بزنید.
3. پیش از انقضای کد راه‌اندازی کوتاه‌عمر، OpenClaw را در ساعت باز کنید.
4. ردیف جداگانه Apple Watch را با openclaw nodes status بررسی کنید.

کد راه‌اندازی دارای یک اعتبارنامه راه‌اندازی اولیه کوتاه‌عمر و مختص Node است؛ تا زمان انقضای آن، مانند گذرواژه با آن رفتار کنید. این کد هرگز گذرواژه یا توکن ذخیره‌شده Gateway در iPhone را در بر نمی‌گیرد. پس از جفت‌سازی، ساعت توکن دستگاه خودش را ذخیره و اعتبارنامه راه‌اندازی اولیه را حذف می‌کند. حالت مستقیم فقط فرمان‌های زیر را پوشش می‌دهد. گفتگو، مکالمه، تأییدها و جریان اعلان موجود watch.* همچنان قابلیت‌های رله iPhone هستند و به iPhone جفت‌شده نیاز دارند.

فرمان‌های Node مستقیم watchOS:

watchOS، WebKit را در اختیار اپ‌های شخص ثالث قرار نمی‌دهد؛ بنابراین Node مستقیم ساعت، فرمان‌های Canvas را اعلام نمی‌کند.

ارسال مبتنی بر رله برای بیلدهای رسمی

بیلدهای رسمی و توزیع‌شده iOS به‌جای انتشار توکن خام APNs برای Gateway، از یک رله ارسال خارجی استفاده می‌کنند. بیلدهای رسمی App Store از مسیر انتشار عمومی از رله میزبانی‌شده در https://ios-push-relay.openclaw.ai استفاده می‌کنند؛ این URL پایه برای توزیع App Store به‌صورت ثابت در کد قرار دارد و هیچ بازنویسی‌ای را نمی‌خواند.

استقرارهای سفارشی رله به یک مسیر بیلد/استقرار عمداً جداگانه iOS نیاز دارند که URL رله آن با URL رله Gateway یکسان باشد. مسیر انتشار App Store هرگز URL سفارشی رله را نمی‌پذیرد. اگر از بیلد سفارشی رله استفاده می‌کنید، URL متناظر رله Gateway را تنظیم کنید:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",        },      },    },  },}

نحوهٔ کار جریان:

• برنامهٔ iOS با استفاده از App Attest و یک JWS تراکنش برنامهٔ StoreKit در رله ثبت‌نام می‌کند.
• رله یک شناسهٔ مات رله به‌همراه مجوز ارسال محدود به ثبت‌نام برمی‌گرداند.
• برنامهٔ iOS هویت Gateway جفت‌شده (gateway.identity.get) را دریافت و آن را در ثبت‌نام رله وارد می‌کند تا ثبت‌نام مبتنی بر رله به همان Gateway مشخص واگذار شود.
• برنامه آن ثبت‌نام مبتنی بر رله را با push.apns.register به Gateway جفت‌شده ارسال می‌کند.
• Gateway از شناسهٔ ذخیره‌شدهٔ رله برای push.test، بیدارسازی‌های پس‌زمینه و تلنگرهای بیدارسازی استفاده می‌کند.
• اگر برنامه بعداً به Gateway دیگری یا بیلدی با URL پایهٔ متفاوت رله متصل شود، به‌جای استفادهٔ مجدد از اتصال قدیمی، ثبت‌نام رله را تازه‌سازی می‌کند.

مواردی که Gateway برای این مسیر به آن‌ها نیاز ندارد: هیچ توکن رلهٔ سراسری برای استقرار و هیچ کلید مستقیم APNs برای ارسال‌های رسمی App Store مبتنی بر رله.

جریان مورد انتظار اپراتور:

1. برنامهٔ رسمی iOS را نصب کنید.
2. اختیاری: فقط هنگام استفاده از یک بیلد سفارشی رله که عمداً جداست، gateway.push.apns.relay.baseUrl را روی Gateway تنظیم کنید.
3. برنامه را با Gateway جفت کنید و اجازه دهید اتصال آن کامل شود.
4. پس از آنکه برنامه توکن APNs داشته باشد، نشست اپراتور متصل شود و ثبت‌نام رله موفق باشد، برنامه push.apns.register را منتشر می‌کند.
5. پس از آن، push.test، بیدارسازی‌های اتصال مجدد و تلنگرهای بیدارسازی می‌توانند از ثبت‌نام ذخیره‌شدهٔ مبتنی بر رله استفاده کنند.

چراغ‌های زنده‌بودن پس‌زمینه

هنگامی که iOS برنامه را برای پوش بی‌صدا، تازه‌سازی پس‌زمینه یا رویداد تغییر چشمگیر مکان بیدار می‌کند، برنامه یک اتصال مجدد کوتاه Node را امتحان می‌کند و سپس node.event را با event: "node.presence.alive" فراخوانی می‌کند. Gateway فقط پس از مشخص‌شدن هویت احراز‌شدهٔ دستگاه Node، این مورد را به‌صورت lastSeenAtMs/lastSeenReason در فرادادهٔ Node/دستگاه جفت‌شده ثبت می‌کند.

برنامه تنها زمانی یک بیدارسازی پس‌زمینه را با موفقیت ثبت‌شده در نظر می‌گیرد که پاسخ Gateway شامل handled: true باشد. Gatewayهای قدیمی‌تر ممکن است node.event را با { "ok": true } تأیید کنند؛ این پاسخ سازگار است، اما به‌عنوان به‌روزرسانی پایدار آخرین زمان مشاهده‌شدن محسوب نمی‌شود.

نکتهٔ سازگاری:

• OPENCLAW_APNS_RELAY_BASE_URL همچنان به‌عنوان یک بازنویسی موقت متغیر محیطی برای Gateway کار می‌کند (gateway.push.apns.relay.baseUrl مسیر مبتنی بر پیکربندی است).
• حالت پوش بیلد انتشار App Store، میزبان رلهٔ میزبانی‌شده را به‌صورت ثابت در خود دارد و هرگز بازنویسی URL رله را نمی‌خواند — متغیر محیطی زمان بیلد OPENCLAW_PUSH_RELAY_BASE_URL فقط بر حالت‌های بیلد محلی/سندباکس iOS اثر می‌گذارد.

جریان احراز هویت و اعتماد

رله برای اعمال دو محدودیتی وجود دارد که APNs مستقیم روی Gateway نمی‌تواند برای بیلدهای رسمی iOS فراهم کند:

• فقط بیلدهای واقعی OpenClaw برای iOS که از طریق Apple توزیع شده‌اند می‌توانند از رلهٔ میزبانی‌شده استفاده کنند.
• یک Gateway فقط می‌تواند برای دستگاه‌های iOS که با همان Gateway مشخص جفت شده‌اند، پوش‌های مبتنی بر رله ارسال کند.

گام‌به‌گام:

1. iOS app -> gateway: برنامه از طریق جریان عادی احراز هویت Gateway با Gateway جفت می‌شود و یک نشست احراز‌شدهٔ Node به‌همراه یک نشست احراز‌شدهٔ اپراتور دریافت می‌کند. نشست اپراتور gateway.identity.get را فراخوانی می‌کند.
2. iOS app -> relay: برنامه نقاط پایانی ثبت‌نام رله را از طریق HTTPS و با مدرک App Attest به‌همراه یک JWS تراکنش برنامهٔ StoreKit فراخوانی می‌کند. رله شناسهٔ بسته، مدرک App Attest و مدرک توزیع Apple را اعتبارسنجی می‌کند و مسیر توزیع رسمی/تولیدی را الزامی می‌داند — این همان چیزی است که مانع استفادهٔ بیلدهای محلی Xcode/توسعه از رلهٔ میزبانی‌شده می‌شود، زیرا یک بیلد محلی نمی‌تواند مدرک توزیع رسمی Apple را ارائه کند.
3. gateway identity delegation: برنامه پیش از ثبت‌نام رله، هویت Gateway جفت‌شده را از gateway.identity.get دریافت و آن را در محمولهٔ ثبت‌نام رله وارد می‌کند. رله یک شناسهٔ رله و مجوز ارسال محدود به ثبت‌نام را برمی‌گرداند که به آن هویت Gateway واگذار شده است.
4. gateway -> relay: Gateway شناسهٔ رله و مجوز ارسال دریافتی از push.apns.register را ذخیره می‌کند. هنگام push.test، بیدارسازی‌های اتصال مجدد و تلنگرهای بیدارسازی، Gateway درخواست ارسال را با هویت دستگاه خودش امضا می‌کند؛ رله هم مجوز ارسال ذخیره‌شده و هم امضای Gateway را در برابر هویت Gateway واگذارشده هنگام ثبت‌نام تأیید می‌کند. Gateway دیگری نمی‌تواند از آن ثبت‌نام ذخیره‌شده دوباره استفاده کند، حتی اگر به‌نحوی شناسه را به دست آورد.
5. relay -> APNs: رله مالک اطلاعات اعتبارسنجی تولیدی APNs و توکن خام APNs برای بیلد رسمی است. Gateway هرگز توکن خام APNs را برای بیلدهای رسمی مبتنی بر رله ذخیره نمی‌کند؛ رله پوش نهایی را از طرف Gateway جفت‌شده به APNs ارسال می‌کند.

دلیل ایجاد این طراحی: دور نگه‌داشتن اطلاعات اعتبارسنجی تولیدی APNs از Gatewayهای کاربران، جلوگیری از ذخیرهٔ توکن‌های خام APNs بیلد رسمی روی Gateway، محدودکردن استفاده از رلهٔ میزبانی‌شده به بیلدهای رسمی OpenClaw برای iOS و جلوگیری از ارسال پوش‌های بیدارسازی توسط یک Gateway به دستگاه‌های iOS متعلق به Gateway دیگر.

بیلدهای محلی/دستی همچنان از APNs مستقیم استفاده می‌کنند. اگر این بیلدها را بدون رله آزمایش می‌کنید، Gateway همچنان به اطلاعات اعتبارسنجی مستقیم APNs نیاز دارد:

export OPENCLAW_APNS_TEAM_ID="TEAMID"export OPENCLAW_APNS_KEY_ID="KEYID"export OPENCLAW_APNS_PRIVATE_KEY_P8="$(cat /path/to/AuthKey_KEYID.p8)"

این‌ها متغیرهای محیطی زمان اجرای میزبان Gateway هستند، نه تنظیمات Fastlane. apps/ios/fastlane/.env فقط اطلاعات احراز هویت App Store Connect مانند APP_STORE_CONNECT_KEY_ID و APP_STORE_CONNECT_ISSUER_ID را ذخیره می‌کند؛ تحویل مستقیم APNs را برای بیلدهای محلی iOS پیکربندی نمی‌کند.

محل ذخیره‌سازی پیشنهادی روی میزبان Gateway، هماهنگ با سایر اطلاعات اعتبارسنجی ارائه‌دهندگان در ~/.openclaw/credentials/:

mkdir -p ~/.openclaw/credentials/apnschmod 700 ~/.openclaw/credentials/apnsmv /path/to/AuthKey_KEYID.p8 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8chmod 600 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8export OPENCLAW_APNS_PRIVATE_KEY_PATH="$HOME/.openclaw/credentials/apns/AuthKey_KEYID.p8"

فایل .p8 را commit نکنید یا آن را در مسیر checkout مخزن قرار ندهید.

مسیرهای کشف

Bonjour (LAN)

برنامهٔ iOS، _openclaw-gw._tcp را در local. و در صورت پیکربندی، در همان دامنهٔ کشف گستردهٔ DNS-SD جست‌وجو می‌کند. Gatewayهای موجود در همان LAN به‌طور خودکار از local. ظاهر می‌شوند؛ کشف میان‌شبکه‌ای می‌تواند بدون تغییر نوع چراغ از دامنهٔ گستردهٔ پیکربندی‌شده استفاده کند.

Tailnet (میان‌شبکه‌ای)

اگر mDNS مسدود است، از یک ناحیهٔ یک‌پخشی DNS-SD استفاده کنید (دامنه‌ای انتخاب کنید؛ نمونه: openclaw.internal.) و DNS تفکیکی Tailscale را به کار ببرید. برای نمونهٔ CoreDNS به Bonjour مراجعه کنید.

میزبان/درگاه دستی

در Settings، گزینهٔ Manual Host را فعال کنید و میزبان + درگاه Gateway را وارد کنید (پیش‌فرض 18789).

چند Gateway

برنامه فهرستی از همهٔ Gatewayهایی که با آن‌ها جفت شده است نگه می‌دارد تا بتوانید بدون جفت‌سازی دوباره میان آن‌ها جابه‌جا شوید:

• در Settings -> Gateway، فهرست Paired Gateways نمایش داده می‌شود و Gateway فعال علامت‌گذاری شده است. برای جابه‌جایی روی یک مورد بزنید؛ برنامه نشست‌های فعلی را قطع می‌کند و دوباره به Gateway انتخاب‌شده متصل می‌شود. وقتی بیش از یک Gateway جفت شده باشد، یک منوی جابه‌جایی سریع کنار ردیف اتصال ظاهر می‌شود.
• اطلاعات اعتبارسنجی، تصمیم‌های اعتماد TLS، ترجیحات مختص هر Gateway و تاریخچهٔ کش‌شدهٔ گفت‌وگو برای هر Gateway جداگانه ذخیره می‌شوند. جابه‌جایی هرگز وضعیت Gatewayها را با یکدیگر ترکیب نمی‌کند و ثبت‌نام پوش از Gateway فعال پیروی می‌کند.
• یک Gateway جفت‌شده را بکشید (یا از منوی زمینهٔ آن استفاده کنید) و گزینهٔ Forget را بزنید؛ با این کار اطلاعات اعتبارسنجی، توکن‌های دستگاه، پین TLS و گفت‌وگوهای کش‌شدهٔ آن حذف می‌شوند.
• برای جابه‌جایی به Gatewayهای کشف‌شده، آن‌ها باید در شبکه قابل مشاهده باشند؛ Gatewayهای دستی با میزبان و درگاه ذخیره‌شده دوباره متصل می‌شوند.

Canvas + A2UI

Node مربوط به iOS یک Canvas مبتنی بر WKWebView را رندر می‌کند. برای کنترل آن از node.invoke استفاده کنید:

openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-host>:18789/__openclaw__/canvas/"}'

نکات:

• میزبان Canvas در Gateway، /__openclaw__/canvas/ و /__openclaw__/a2ui/ را از سرور HTTP مربوط به Gateway ارائه می‌کند (همان درگاه gateway.port، پیش‌فرض 18789).
• Node مربوط به iOS داربست داخلی را به‌عنوان نمای متصل پیش‌فرض نگه می‌دارد. canvas.a2ui.push و canvas.a2ui.reset از صفحهٔ A2UI همراه برنامه و تحت مالکیت آن استفاده می‌کنند.
• صفحه‌های A2UI مربوط به Gateway راه‌دور در iOS فقط قابل رندر هستند؛ کنش‌های بومی دکمه‌های A2UI فقط از صفحه‌های همراه برنامه و تحت مالکیت آن پذیرفته می‌شوند.
• با canvas.navigate و {"url":""} به داربست داخلی بازگردید.

ارتباط با Computer Use

برنامهٔ iOS یک سطح Node موبایل است، نه بک‌اند Codex Computer Use. ‏Codex Computer Use و cua-driver mcp یک دسکتاپ محلی macOS را از طریق ابزارهای MCP کنترل می‌کنند؛ برنامهٔ iOS قابلیت‌های iPhone را از طریق فرمان‌های Node در OpenClaw مانند canvas.*، camera.*، screen.*، location.* و talk.* ارائه می‌کند.

عامل‌ها همچنان می‌توانند با فراخوانی فرمان‌های Node، برنامهٔ iOS را از طریق OpenClaw کنترل کنند، اما این فراخوانی‌ها از پروتکل Node مربوط به Gateway عبور می‌کنند و از محدودیت‌های پیش‌زمینه/پس‌زمینهٔ iOS پیروی می‌کنند. برای کنترل دسکتاپ محلی از Codex Computer Use و برای قابلیت‌های Node در iOS از این صفحه استفاده کنید.

ارزیابی / تصویر لحظه‌ای Canvas

openclaw nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__openclaw; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'

openclaw nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}'

بیدارسازی صوتی + حالت مکالمه

• بیدارسازی صوتی و حالت مکالمه در Settings در دسترس هستند.
• مکالمهٔ بلادرنگ OpenAI هنگامی که talk.realtime.transport برابر با webrtc باشد از WebRTC تحت مالکیت کلاینت استفاده می‌کند؛ پیکربندی صریح gateway-relay همچنان تحت مالکیت Gateway است. به حالت مکالمه مراجعه کنید.
• Nodeهای iOS دارای قابلیت مکالمه، قابلیت talk را اعلام می‌کنند و می‌توانند talk.ptt.start، talk.ptt.stop، talk.ptt.cancel و talk.ptt.once را اظهار کنند؛ Gateway به‌طور پیش‌فرض این فرمان‌های فشردن برای صحبت را برای Nodeهای مورد اعتماد دارای قابلیت مکالمه مجاز می‌داند.
• ممکن است iOS صدای پس‌زمینه را معلق کند؛ وقتی برنامه فعال نیست، قابلیت‌های صوتی را در حد بهترین تلاش در نظر بگیرید.

خطاهای رایج

• NODE_BACKGROUND_UNAVAILABLE: برنامهٔ iOS را به پیش‌زمینه بیاورید (فرمان‌های Canvas/دوربین/صفحه به آن نیاز دارند).
• A2UI_HOST_UNAVAILABLE: صفحهٔ همراه A2UI در WebView برنامه قابل دسترسی نبود؛ برنامه را در برگهٔ Screen در پیش‌زمینه نگه دارید و دوباره تلاش کنید.
• درخواست جفت‌سازی هرگز ظاهر نمی‌شود: openclaw devices list را اجرا و به‌صورت دستی تأیید کنید.
• Watch هیچ وضعیتی از iPhone نشان نمی‌دهد: تأیید کنید که iPhone مقادیر watchPaired: true و watchAppInstalled: true را در watch.status گزارش می‌کند. اگر جفت‌سازی نادرست است، Watch را در برنامهٔ Watch اپل جفت کنید. اگر نصب نادرست است، برنامهٔ همراه را از My Watch -> Available Apps نصب کنید. پس از هرکدام از این تغییرات، OpenClaw را یک‌بار روی Watch باز کنید؛ دسترسی فوری همچنان نیازمند اجرای هر دو برنامه است، درحالی‌که به‌روزرسانی‌های صف‌شده می‌توانند بعداً در پس‌زمینه دریافت شوند.
• اتصال مجدد پس از نصب دوباره ناموفق است: توکن جفت‌سازی Keychain پاک شده است؛ Node را دوباره جفت کنید.

مستندات مرتبط

• جفت‌سازی
• کشف
• Bonjour