برنامه Android

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

• نقش: برنامه گره همراه (Android میزبان Gateway نیست).
• Gateway لازم است: بله (آن را روی macOS، Linux، یا Windows از طریق WSL2 اجرا کنید).
• نصب: شروع به کار + جفت‌سازی.
• 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 گیت‌وی دسترسی داشته باشد:
  • همان LAN با mDNS/NSD، یا
  • همان tailnet در Tailscale با Wide-Area Bonjour / unicast DNS-SD (پایین را ببینید)، یا
  • میزبان/درگاه دستی گیت‌وی (گزینه جایگزین)
• جفت‌سازی موبایل روی tailnet/عمومی از نقاط پایانی IP خام tailnet با ws:// استفاده نمی‌کند. به‌جای آن از Tailscale Serve یا یک URL دیگر wss:// استفاده کنید.
• می‌توانید CLI (openclaw) را روی دستگاه گیت‌وی (یا از طریق SSH) اجرا کنید.

# 1) Gateway را راه‌اندازی کنید

openclaw gateway --port 18789 --verbose

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

• listening on ws://0.0.0.0:18789

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

openclaw gateway --tailscale serve

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

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

از دستگاه گیت‌وی:

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

نکته‌های بیشتر برای عیب‌یابی: Bonjour.

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

openclaw gateway discover --json

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

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

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

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

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

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

# 3) از Android وصل شوید

در برنامه Android:

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

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

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

# سیگنال‌های زنده بودن حضور

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

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

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

روی دستگاه گیت‌وی:

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

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

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

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

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

# 5) تأیید کنید گره وصل است

• از طریق وضعیت گره‌ها:

  openclaw nodes status
  

• از طریق Gateway:

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

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

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

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

# 7) Canvas + دوربین

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

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

1. فایل ~/.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 یا IP tailnet استفاده کنید، مثلاً http://<gateway-magicdns>:18789/__openclaw__/canvas/.

این سرور یک کلاینت live-reload را به HTML تزریق می‌کند و با تغییر فایل‌ها reload می‌شود. میزبان A2UI در http://<gateway-host>:18789/__openclaw__/a2ui/ قرار دارد.

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

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

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

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

برای پارامترها و کمک‌کننده‌های CLI، گره دوربین را ببینید.

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

• زبانه Voice: Android دو حالت capture صریح دارد. Mic یک نشست دستی در زبانه Voice است که هر مکث را به‌عنوان یک نوبت چت ارسال می‌کند و وقتی برنامه از foreground خارج شود یا کاربر زبانه Voice را ترک کند، متوقف می‌شود. Talk حالت Talk Mode پیوسته است و تا زمانی که خاموش شود یا گره قطع شود به گوش دادن ادامه می‌دهد.
• Talk Mode پیش از شروع capture، سرویس foreground موجود را از dataSync به dataSync|microphone ارتقا می‌دهد، سپس وقتی Talk Mode متوقف می‌شود آن را پایین می‌آورد. Android 14+ به اعلان FOREGROUND_SERVICE_MICROPHONE، مجوز زمان اجرای RECORD_AUDIO، و نوع سرویس میکروفون در زمان اجرا نیاز دارد.
• پاسخ‌های گفتاری از talk.speak از طریق ارائه‌دهنده Talk پیکربندی‌شده در گیت‌وی استفاده می‌کنند. TTS محلی سیستم فقط زمانی استفاده می‌شود که talk.speak در دسترس نباشد.
• بیدارباش صوتی در UX/زمان اجرای Android غیرفعال می‌ماند.
• خانواده‌های فرمان اضافی Android (دسترس‌پذیری به دستگاه + مجوزها بستگی دارد):
  • device.status، device.info، device.permissions، device.health
  • notifications.list، notifications.actions (پایین‌تر بازارسال اعلان‌ها را ببینید)
  • photos.latest
  • contacts.search، contacts.add
  • calendar.events، calendar.add
  • callLog.search
  • sms.search
  • motion.activity، motion.pedometer

# نقاط ورود دستیار

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

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

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

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

کلید	نوع	توضیح
notifications.allowPackages	string[]	فقط اعلان‌های این نام‌های بسته بازارسال شوند. اگر تنظیم شود، همه بسته‌های دیگر نادیده گرفته می‌شوند.
notifications.denyPackages	string[]	هرگز اعلان‌های این نام‌های بسته بازارسال نشوند. پس از allowPackages اعمال می‌شود.
notifications.quietHours.start	string (HH:mm)	شروع بازه ساعت‌های سکوت (زمان محلی دستگاه). اعلان‌ها در طول این بازه سرکوب می‌شوند.
notifications.quietHours.end	string (HH:mm)	پایان بازه ساعت‌های سکوت.
notifications.rateLimit	number	بیشینه اعلان‌های بازارسال‌شده برای هر بسته در هر دقیقه. اعلان‌های اضافی حذف می‌شوند.

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

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

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

# مرتبط

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