برنامه Android

نمای کلی پشتیبانی

• نقش: برنامه نود همراه (Android میزبان Gateway نیست).
• Gateway لازم است: بله (آن را روی macOS، Linux، یا Windows از طریق WSL2 اجرا کنید).
• نصب: Google Play برای برنامه، شروع به کار برای Gateway، سپس جفت‌سازی.
• Gateway: راهنمای عملیاتی + پیکربندی.
  • پروتکل‌ها: پروتکل Gateway (نودها + صفحه کنترل).

کنترل سیستم

کنترل سیستم (launchd/systemd) روی میزبان Gateway قرار دارد. Gateway را ببینید.

راهنمای عملیاتی اتصال

برنامه نود Android ⇄ (mDNS/NSD + WebSocket) ⇄ Gateway

Android مستقیما به WebSocketِ Gateway متصل می‌شود و از جفت‌سازی دستگاه (role: node) استفاده می‌کند.

برای Tailscale یا میزبان‌های عمومی، Android به یک نقطه پایانی امن نیاز دارد:

• ترجیحی: Tailscale Serve / Funnel با https://<magicdns> / wss://<magicdns>
• همچنین پشتیبانی می‌شود: هر URL دیگر wss:// برای Gateway با یک نقطه پایانی TLS واقعی
• ws:// بدون رمزنگاری همچنان روی نشانی‌های LAN خصوصی / میزبان‌های .local، به‌علاوه localhost، 127.0.0.1، و پل شبیه‌ساز Android (10.0.2.2) پشتیبانی می‌شود

پیش‌نیازها

• می‌توانید Gateway را روی ماشین «اصلی» اجرا کنید.
• دستگاه/شبیه‌ساز Android می‌تواند به WebSocketِ Gateway دسترسی داشته باشد:
  • همان LAN با mDNS/NSD، یا
  • همان tailnet در Tailscale با استفاده از Wide-Area Bonjour / unicast DNS-SD (پایین را ببینید)، یا
  • میزبان/درگاه Gateway به‌صورت دستی (راه fallback)
• جفت‌سازی موبایل روی tailnet/عمومی از نقطه‌های پایانی خام tailnet IP با ws:// استفاده نمی‌کند. به‌جای آن از Tailscale Serve یا یک URL دیگر wss:// استفاده کنید.
• می‌توانید CLI (openclaw) را روی ماشین Gateway (یا از طریق SSH) اجرا کنید.

1) Gateway را شروع کنید

openclaw gateway --port 18789 --verbose

در لاگ‌ها تأیید کنید چیزی شبیه این می‌بینید:

• listening on ws://0.0.0.0:18789

برای دسترسی Android از راه دور از طریق Tailscale، به‌جای bind خام tailnet، Serve/Funnel را ترجیح دهید:

openclaw gateway --tailscale serve

این کار یک نقطه پایانی امن wss:// / https:// به Android می‌دهد. تنظیم ساده gateway.bind: "tailnet" برای جفت‌سازی اولیه Android از راه دور کافی نیست، مگر اینکه TLS را جداگانه هم terminate کنید.

2) کشف را تأیید کنید (اختیاری)

از ماشین Gateway:

dns-sd -B _openclaw-gw._tcp local.

یادداشت‌های بیشتر برای اشکال‌زدایی: Bonjour.

اگر یک دامنه کشف گسترده را هم پیکربندی کرده‌اید، با این مقایسه کنید:

openclaw gateway discover --json

این دستور local. به‌علاوه دامنه گسترده پیکربندی‌شده را در یک عبور نشان می‌دهد و به‌جای hintهای فقط TXT، از نقطه پایانی سرویس resolve‌شده استفاده می‌کند.

کشف tailnet (وین ⇄ لندن) از طریق unicast DNS-SD

کشف NSD/mDNS در Android از شبکه‌ها عبور نمی‌کند. اگر نود Android و Gateway شما روی شبکه‌های متفاوت هستند اما از طریق Tailscale متصل‌اند، به‌جای آن از Wide-Area Bonjour / unicast DNS-SD استفاده کنید.

کشف به‌تنهایی برای جفت‌سازی Android روی tailnet/عمومی کافی نیست. مسیر کشف‌شده همچنان به یک نقطه پایانی امن (wss:// یا Tailscale Serve) نیاز دارد:

1. یک zone برای DNS-SD (مثلا openclaw.internal.) روی میزبان Gateway راه‌اندازی کنید و رکوردهای _openclaw-gw._tcp را منتشر کنید.
2. split DNS در Tailscale را برای دامنه انتخابی خود، با اشاره به آن سرور DNS، پیکربندی کنید.

جزئیات و نمونه پیکربندی CoreDNS: Bonjour.

3) از Android متصل شوید

در برنامه Android:

• برنامه اتصال Gateway خود را از طریق یک سرویس foreground زنده نگه می‌دارد (اعلان پایدار).
• برگه اتصال را باز کنید.
• از حالت کد راه‌اندازی یا دستی استفاده کنید.
• اگر کشف مسدود است، از میزبان/درگاه دستی در کنترل‌های پیشرفته استفاده کنید. برای میزبان‌های LAN خصوصی، ws:// همچنان کار می‌کند. برای میزبان‌های Tailscale/عمومی، TLS را روشن کنید و از یک نقطه پایانی wss:// / Tailscale Serve استفاده کنید.

پس از نخستین جفت‌سازی موفق، Android هنگام اجرا به‌صورت خودکار دوباره وصل می‌شود:

• نقطه پایانی دستی (اگر فعال باشد)، در غیر این صورت
• آخرین Gateway کشف‌شده (بهترین تلاش).

Beaconهای زنده بودن حضور

پس از اتصال نشست نود احراز هویت‌شده، و هنگامی که برنامه در حالی به پس‌زمینه می‌رود که سرویس foreground هنوز متصل است، Android node.event را با event: "node.presence.alive" فراخوانی می‌کند. Gateway این را تنها پس از شناخته شدن هویت دستگاه نود احراز هویت‌شده، به‌عنوان lastSeenAtMs/lastSeenReason در فراداده نود/دستگاه جفت‌شده ثبت می‌کند.

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

4) جفت‌سازی را تأیید کنید (CLI)

روی ماشین Gateway:

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>

جزئیات جفت‌سازی: جفت‌سازی.

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

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

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

5) تأیید کنید نود متصل است

• از طریق وضعیت نودها:

  openclaw nodes status

• از طریق Gateway:

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

6) چت + تاریخچه

برگه چت Android از انتخاب نشست پشتیبانی می‌کند (پیش‌فرض main، به‌علاوه نشست‌های موجود دیگر):

• تاریخچه: chat.history (برای نمایش نرمال‌سازی‌شده؛ تگ‌های directive درون‌خطی از متن قابل مشاهده حذف می‌شوند، payloadهای XML فراخوانی ابزار در متن ساده (از جمله <tool_call>...</tool_call>، <function_call>...</function_call>، <tool_calls>...</tool_calls>، <function_calls>...</function_calls>، و بلوک‌های کوتاه‌شده فراخوانی ابزار) و توکن‌های کنترلی مدل به ASCII/تمام‌عرض که نشت کرده‌اند حذف می‌شوند، ردیف‌های assistant با توکن کاملا خاموش مانند NO_REPLY / no_reply دقیق نادیده گرفته می‌شوند، و ردیف‌های بیش‌ازحد بزرگ می‌توانند با placeholder جایگزین شوند)
• ارسال: chat.send
• به‌روزرسانی‌های push (بهترین تلاش): chat.subscribe → event:"chat"

7) Canvas + دوربین

میزبان Canvas در Gateway (توصیه‌شده برای محتوای وب)

اگر می‌خواهید نود HTML/CSS/JS واقعی را نشان دهد که agent بتواند روی دیسک ویرایش کند، نود را به میزبان canvas در Gateway اشاره دهید.

1. روی میزبان Gateway فایل ~/.openclaw/workspace/canvas/index.html را ایجاد کنید.

2. نود را به آن هدایت کنید (LAN):

openclaw nodes invoke --node "&lt;Android Node&gt;" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18789/__openclaw__/canvas/"}'

Tailnet (اختیاری): اگر هر دو دستگاه روی Tailscale هستند، به‌جای .local از نام MagicDNS یا tailnet IP استفاده کنید، مثلا http://<gateway-magicdns>:18789/__openclaw__/canvas/.

این سرور یک کلاینت live-reload را به HTML تزریق می‌کند و هنگام تغییر فایل‌ها دوباره بارگذاری می‌کند. Gateway همچنین /__openclaw__/a2ui/ را سرو می‌کند، اما برنامه Android صفحه‌های A2UI راه دور را فقط برای render در نظر می‌گیرد. فرمان‌های A2UI دارای action، پیش از اعمال پیام‌ها، از صفحه A2UI متعلق به برنامه و همراه برنامه استفاده می‌کنند.

فرمان‌های Canvas (فقط foreground):

• canvas.eval، canvas.snapshot، canvas.navigate (برای بازگشت به scaffold پیش‌فرض از {"url":""} یا {"url":"/"} استفاده کنید). canvas.snapshot مقدار { format, base64 } را برمی‌گرداند (پیش‌فرض format="jpeg").
• A2UI: canvas.a2ui.push، canvas.a2ui.reset (alias قدیمی canvas.a2ui.pushJSONL). این فرمان‌ها برای render دارای action از صفحه A2UI متعلق به برنامه و همراه برنامه استفاده می‌کنند.

فرمان‌های دوربین (فقط foreground؛ وابسته به مجوز):

• camera.snap (jpg)
• camera.clip (mp4)

برای پارامترها و helperهای CLI، نود دوربین را ببینید.

8) صدا + سطح فرمان گسترش‌یافته Android

• برگه صدا: Android دو حالت capture صریح دارد. میکروفون یک نشست دستی در برگه صدا است که هر مکث را به‌عنوان یک نوبت چت ارسال می‌کند و وقتی برنامه foreground را ترک کند یا کاربر از برگه صدا خارج شود متوقف می‌شود. گفتگو حالت Talk Mode پیوسته است و تا زمانی که خاموش شود یا نود قطع شود، به شنیدن ادامه می‌دهد.
• Talk Mode پیش از شروع capture، سرویس foreground موجود را از connectedDevice به connectedDevice|microphone ارتقا می‌دهد، سپس وقتی Talk Mode متوقف شد آن را تنزل می‌دهد. سرویس نود FOREGROUND_SERVICE_CONNECTED_DEVICE را همراه با CHANGE_NETWORK_STATE اعلام می‌کند؛ Android 14+ همچنین به اعلان FOREGROUND_SERVICE_MICROPHONE، اعطای runtime برای RECORD_AUDIO، و نوع سرویس microphone در زمان اجرا نیاز دارد.
• به‌صورت پیش‌فرض، Android Talk از تشخیص گفتار بومی، چت Gateway، و talk.speak از طریق provider پیکربندی‌شده Talk در Gateway استفاده می‌کند. TTS محلی سیستم فقط زمانی استفاده می‌شود که talk.speak در دسترس نباشد.
• Android Talk فقط زمانی از relay بلادرنگ Gateway استفاده می‌کند که talk.realtime.mode برابر realtime و talk.realtime.transport برابر gateway-relay باشد.
• wake صوتی در UX/runtime اندروید غیرفعال باقی می‌ماند.
• خانواده‌های فرمان اضافی Android (در دسترس بودن به دستگاه، مجوزها، و تنظیمات کاربر بستگی دارد):
  • device.status، device.info، device.permissions، device.health
  • device.apps فقط وقتی تنظیمات > قابلیت‌های تلفن > برنامه‌های نصب‌شده فعال باشد؛ به‌صورت پیش‌فرض برنامه‌های قابل مشاهده در launcher را فهرست می‌کند.
  • notifications.list، notifications.actions (در پایین بازارسال اعلان‌ها را ببینید)
  • photos.latest
  • contacts.search، contacts.add
  • calendar.events، calendar.add
  • callLog.search
  • sms.search
  • motion.activity، motion.pedometer

نقطه‌های ورود assistant

Android از اجرای OpenClaw از طریق trigger دستیار سیستم (Google Assistant) پشتیبانی می‌کند. وقتی پیکربندی شده باشد، نگه داشتن دکمه home یا گفتن «Hey Google, ask OpenClaw...» برنامه را باز می‌کند و prompt را وارد composer چت می‌کند.

این کار از فراداده App Actions در Android که در manifest برنامه اعلام شده استفاده می‌کند. هیچ پیکربندی اضافه‌ای در سمت Gateway لازم نیست -- intent دستیار کاملا توسط برنامه Android مدیریت و به‌عنوان یک پیام چت عادی بازارسال می‌شود.

بازارسال اعلان‌ها

Android می‌تواند اعلان‌های دستگاه را به‌عنوان event به Gateway بازارسال کند. چند کنترل به شما اجازه می‌دهند مشخص کنید کدام اعلان‌ها و در چه زمانی بازارسال شوند.

انتخاب‌گر اعلان همچنین برای eventهای اعلان بازارسال‌شده، رفتار امن‌تری به‌کار می‌گیرد و از بازارسال تصادفی اعلان‌های حساس سیستم جلوگیری می‌کند.

نمونه پیکربندی:

{  notifications: {    allowPackages: ["com.slack", "com.whatsapp"],    denyPackages: ["com.android.systemui"],    quietHours: {      start: "22:00",      end: "07:00",    },    rateLimit: 5,  },}

مرتبط

• برنامه iOS
• گره‌ها
• عیب‌یابی گره Android