macOS companion app
کنترل از راه دور
این جریان به برنامه macOS امکان میدهد بهعنوان کنترل از راه دور کامل برای یک Gateway متعلق به OpenClaw که روی میزبان دیگری (رایانه رومیزی/سرور) اجرا میشود عمل کند. برنامه مستقیماً به نشانیهای Gateway مورداعتماد در شبکه LAN یا Tailnet متصل میشود، یا هنگامی که Gateway راه دور فقط روی local loopback در دسترس است، یک تونل SSH را مدیریت میکند. بررسیهای سلامت، هدایت Voice Wake و Web Chat همگی از همان پیکربندی راه دور در Settings -> General استفاده میکنند.
حالتها
- محلی (این Mac): همهچیز روی لپتاپ اجرا میشود؛ SSH دخالتی ندارد.
- راه دور از طریق SSH (پیشفرض): فرمانهای OpenClaw روی میزبان راه دور اجرا میشوند. برنامه با
-o BatchMode، هویت/کلید انتخابی شما و یک انتقال پورت محلی، اتصال SSH باز میکند. - راه دور مستقیم (ws/wss): بدون تونل SSH؛ برنامه مستقیماً به نشانی Gateway متصل میشود (LAN، Tailscale، Tailscale Serve یا یک پراکسی معکوس عمومی HTTPS).
روشهای انتقال راه دور
- تونل SSH (پیشفرض): از
ssh -N -L ...برای انتقال پورت Gateway به localhost استفاده میکند. از آنجا که تونل روی loopback است، Gateway نشانی IP مربوط به Node را127.0.0.1میبیند. - مستقیم (ws/wss): مستقیماً به نشانی Gateway متصل میشود. Gateway نشانی IP واقعی کارخواه را میبیند.
برنامه برای فرایندهای SSH خود، چندگانهسازی اتصال SSH و انتقال به پسزمینه پس از احراز هویت را غیرفعال میکند تا بتواند همان فرایند مشخص را پایش و راهاندازی مجدد کند، حتی اگر نام مستعار انتخابشده ControlMaster یا ForkAfterAuthentication را فعال کرده باشد.
تأیید کلید میزبان SSH بهطور پیشفرض سختگیرانه است، زیرا اعتبارنامههای Gateway از این تونل عبور میکنند. برای استفاده از رفتار اعتماد خودِ یک نام مستعار SSH مدیریتشده، از طریق openclaw-mac configure-remote گزینه --ssh-host-key-policy openssh را تنظیم کنید، یا gateway.remote.sshHostKeyPolicy را مستقیماً روی "openssh" قرار دهید. پیش از فعالکردن این گزینه، نام مستعار و هر پیکربندی منطبق با Host * یا پیکربندی سیستمی را بررسی کنید. تغییر مقصد SSH (در برنامه یا از طریق configure-remote) سیاست را دوباره به strict بازنشانی میکند، مگر اینکه صریحاً برای مقصد جدید دوباره آن را فعال کنید.
در حالت تونل SSH، نامهای میزبان کشفشده در LAN یا Tailnet بهصورت gateway.remote.sshTarget ذخیره میشوند. برنامه gateway.remote.url را روی نقطه پایانی تونل محلی نگه میدارد (برای نمونه ws://127.0.0.1:18789) تا CLI، Web Chat و سرویس محلی میزبان Node همگی از روش انتقال loopback یکسانی استفاده کنند. هنگامی که فرایند کشف هم نشانیهای IP خام Tailnet و هم نامهای میزبان پایدار را برمیگرداند، برنامه Tailscale MagicDNS یا نامهای LAN را ترجیح میدهد تا اتصالها در برابر تغییر نشانی پایدارتر بمانند. اگر پورت تونل محلی با پورت Gateway راه دور متفاوت است، gateway.remote.remotePort را روی پورت میزبان راه دور تنظیم کنید.
خودکارسازی مرورگر در حالت راه دور در اختیار میزبان Node متعلق به CLI است، نه Node بومی برنامه macOS. برنامه در صورت امکان سرویس نصبشده میزبان Node را راهاندازی میکند؛ برای فعالکردن کنترل مرورگر از آن Mac، آن را با openclaw node install ... و openclaw node start نصب/راهاندازی کنید (یا openclaw node run ... را در پیشزمینه اجرا کنید)، سپس آن Node دارای قابلیت مرورگر را بهعنوان مقصد انتخاب کنید.
پیشنیازها روی میزبان راه دور
- Node و pnpm را نصب کنید و CLI متعلق به OpenClaw را بسازید/نصب کنید (
pnpm install && pnpm build && pnpm link --global). - مطمئن شوید
openclawبرای پوستههای غیرتعاملی در PATH قرار دارد (در صورت نیاز، پیوندی نمادین در/usr/local/binیا/opt/homebrew/binایجاد کنید). - برای انتقال SSH: احراز هویت SSH مبتنی بر کلید را راهاندازی کنید. برای دسترسی پایدار خارج از LAN، نشانیهای IP متعلق به Tailscale توصیه میشوند.
راهاندازی برنامه macOS
برای پیشپیکربندی برنامه بدون طیکردن جریان خوشامدگویی، از طریق SSH:
openclaw-mac configure-remote \ --ssh-target user@gateway-host \ --local-port 18789 \ --remote-port 18789 \ --token "$OPENCLAW_GATEWAY_TOKEN"یا برای Gateway که از قبل روی یک LAN یا Tailnet مورداعتماد در دسترس است، SSH را کاملاً کنار بگذارید:
openclaw-mac configure-remote \ --direct-url ws://192.168.0.202:18789 \ --token "$OPENCLAW_GATEWAY_TOKEN"هر دو روش در ~/.openclaw/openclaw.json مینویسند، فرایند راهاندازی اولیه را تکمیلشده علامتگذاری میکنند و اجازه میدهند برنامه در اجرای بعدی روش انتقال انتخابشده را مدیریت کند. مقدار پیشفرض --local-port/--remote-port برابر 18789 است. سایر گزینهها: --password، --identity <path>، --ssh-host-key-policy <strict|openssh>، --project-root <path>، --cli-path <path>، --json. برای مرجع کامل، openclaw-mac configure-remote --help را اجرا کنید.
برای پیکربندی از رابط کاربری:
- _Settings -> General_ را باز کنید.
- در بخش OpenClaw runs، گزینه Remote را انتخاب و موارد زیر را تنظیم کنید:
- Transport: SSH tunnel یا Direct (ws/wss).
- SSH target:
user@host(با:portاختیاری). اگر Gateway در همان LAN قرار دارد و خود را از طریق Bonjour معرفی میکند، آن را از فهرست کشفشده انتخاب کنید تا این فیلد بهطور خودکار پر شود. - Gateway URL (فقط حالت Direct):
wss://gateway.example.ts.net(یاws://...برای اتصال محلی/LAN). - Identity file (پیشرفته): مسیر کلید شما.
- Project root (پیشرفته): مسیر نسخه کاری راه دور که برای فرمانها استفاده میشود.
- CLI path (پیشرفته): مسیر اختیاری به نقطه ورود/فایل اجرایی قابل اجرای
openclaw(در صورت معرفیشدن، بهطور خودکار پر میشود).
- Test remote را بزنید. موفقیت به این معناست که
openclaw status --jsonراه دور بهدرستی اجرا شده است. شکستها معمولاً ناشی از مشکلات PATH/CLI هستند؛ کد خروج 127 یعنی CLI روی میزبان راه دور پیدا نشده است. - از این پس، بررسیهای سلامت و Web Chat بهطور خودکار از طریق روش انتقال انتخابشده اجرا میشوند.
Web Chat
- تونل SSH: از طریق پورت کنترلی WebSocket انتقالیافته (پیشفرض 18789) به Gateway متصل میشود.
- مستقیم (ws/wss): مستقیماً به نشانی پیکربندیشده Gateway متصل میشود.
- هیچ سرور HTTP جداگانهای برای Web Chat وجود ندارد.
مجوزها
- میزبان راه دور به همان تأییدیههای TCC حالت محلی نیاز دارد (خودکارسازی، دسترسپذیری، ضبط صفحه، میکروفون، تشخیص گفتار، اعلانها). فرایند راهاندازی اولیه را یکبار روی آن دستگاه اجرا کنید تا این مجوزها اعطا شوند.
- Nodeها وضعیت مجوزهای خود را از طریق
node.list/node.describeاعلام میکنند تا عاملها بدانند چه قابلیتهایی در دسترس است.
نکات امنیتی
- روی میزبان راه دور، اتصال به loopback را ترجیح دهید و از طریق SSH، Tailscale Serve یا یک نشانی مستقیم مورداعتماد Tailnet/LAN متصل شوید.
- تونلزنی SSH بهطور پیشفرض به کلید میزبانی نیاز دارد که از قبل مورداعتماد باشد. ابتدا به کلید میزبان اعتماد کنید (آن را به فایل پیکربندیشده میزبانهای شناختهشده اضافه کنید)، یا برای نام مستعار مدیریتشدهای که سیاست اعتماد OpenSSH آن را میپذیرید، صریحاً
gateway.remote.sshHostKeyPolicy: "openssh"را تنظیم کنید. - اگر Gateway را به رابطی غیر از loopback متصل میکنید، احراز هویت معتبر Gateway را الزامی کنید: توکن، گذرواژه یا یک پراکسی معکوس آگاه از هویت با
gateway.auth.mode: "trusted-proxy". - امنیت و Tailscale را ببینید.
جریان ورود WhatsApp (راه دور)
-
openclaw channels login --channel whatsapp --verboseرا روی میزبان راه دور اجرا کنید. کد QR را با WhatsApp روی تلفن خود اسکن کنید. - اگر اعتبار احراز هویت منقضی شد، ورود را دوباره روی همان میزبان اجرا کنید. بررسی سلامت، مشکلات پیوند را نمایش میدهد.
عیبیابی
| نشانه | علت / راهحل |
|---|---|
exit 127 / یافت نشد |
برای پوستههای غیرورودی، openclaw در PATH قرار ندارد. آن را به /etc/paths یا فایل rc پوستهٔ خود اضافه کنید، یا در /usr/local/bin//opt/homebrew/bin یک پیوند نمادین به آن بسازید. |
| کاوش سلامت ناموفق بود | دسترسیپذیری SSH و PATH را بررسی کنید و مطمئن شوید Baileys (WhatsApp) وارد حساب شده است (openclaw status --json). |
| گفتوگوی وب گیر کرده است | تأیید کنید که Gateway روی میزبان راهدور در حال اجرا است و درگاه هدایتشده با درگاه WS مربوط به Gateway مطابقت دارد؛ رابط کاربری به یک اتصال سالم WS نیاز دارد. |
نشانی IP مربوط به Node، مقدار 127.0.0.1 را نشان میدهد |
این وضعیت در تونل SSH مورد انتظار است. اگر میخواهید Gateway نشانی IP واقعی کارخواه را ببیند، روش انتقال را به مستقیم (ws/wss) تغییر دهید. |
| داشبورد کار میکند، اما قابلیتهای Mac آفلاین هستند | اتصال اپراتور/کنترل سالم است، اما اتصال Node همراه برقرار نیست یا سطح فرمان آن وجود ندارد. بخش دستگاه را در نوار منو باز کنید و بررسی کنید که آیا وضعیت Mac برابر با paired · disconnected است. برای نقاط پایانی Tailscale Serve با الگوی wss://*.ts.net، برنامه پس از چرخش گواهی، پینهای قدیمی و منسوخ برگ TLS را تشخیص میدهد؛ وقتی macOS به گواهی جدید اعتماد کند، پین منسوخ را یکبار پاک میکند و بهطور خودکار دوباره تلاش میکند. اگر گواهی مورد اعتماد سیستم نیست یا میزبان نام Tailscale Serve ندارد، gateway.remote.tlsFingerprint را روی اثر انگشت مورد انتظار گواهی تنظیم کنید، گواهی را بررسی کنید یا به راهدور از طریق SSH تغییر دهید. |
| بیدارباش صوتی | عبارتهای فعالساز در حالت راهدور بهطور خودکار هدایت میشوند؛ به هدایتکنندهٔ جداگانهای نیاز نیست. |
صداهای اعلان
برای هر اعلان، صدا را از اسکریپتها با openclaw nodes notify انتخاب کنید؛ برای مثال:
openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glassدر برنامه کلید سراسری برای صدای پیشفرض وجود ندارد؛ فراخوانندهها برای هر درخواست یک صدا انتخاب میکنند (یا هیچ صدایی انتخاب نمیکنند).
