macOS companion app
کنترل از راه دور
این جریان به برنامه macOS امکان میدهد بهعنوان یک کنترل از راه دور کامل برای Gateway متعلق به OpenClaw که روی میزبان دیگری (رایانه رومیزی/سرور) اجرا میشود، عمل کند. برنامه مستقیماً به نشانیهای Gateway مورداعتماد در LAN/Tailnet متصل میشود، یا هنگامی که Gateway راه دور فقط روی 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 استفاده میکند. Gateway نشانی IP گره را بهصورت127.0.0.1میبیند، زیرا تونل loopback است. - مستقیم (ws/wss): مستقیماً به نشانی Gateway متصل میشود. Gateway نشانی IP واقعی کلاینت را میبیند.
برنامه قابلیت چندگانهسازی اتصال SSH و اجرای پسزمینه پس از احراز هویت را برای فرایندهای SSH خود غیرفعال میکند تا بتواند همان فرایند دقیق را پایش و راهاندازی مجدد کند، حتی اگر نام مستعار انتخابشده ControlMaster یا ForkAfterAuthentication را فعال کند.
تأیید کلید میزبان SSH بهطور پیشفرض سختگیرانه است، زیرا اعتبارنامههای Gateway از این تونل عبور میکنند. برای استفاده از رفتار اعتماد خودِ یک نام مستعار SSH مدیریتشده، --ssh-host-key-policy openssh را از طریق openclaw-mac configure-remote تنظیم کنید، یا 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 و سرویس محلی میزبان گره همگی از همان انتقال loopback استفاده کنند. هنگامی که کشف، هم نشانیهای IP خام Tailnet و هم نامهای میزبان پایدار را برمیگرداند، برنامه نامهای Tailscale MagicDNS یا LAN را ترجیح میدهد تا اتصالها در برابر تغییر نشانی مقاومتر باشند. اگر پورت تونل محلی با پورت Gateway راه دور متفاوت است، gateway.remote.remotePort را روی پورت میزبان راه دور تنظیم کنید.
خودکارسازی مرورگر در حالت راه دور در اختیار میزبان گره CLI است، نه گره بومی برنامه macOS. برنامه در صورت امکان سرویس نصبشده میزبان گره را راهاندازی میکند؛ برای فعالکردن کنترل مرورگر از آن Mac، آن را با openclaw node install ... و openclaw node start نصب/راهاندازی کنید (یا openclaw node run ... را در پیشزمینه اجرا کنید)، سپس آن گره دارای قابلیت مرورگر را هدف قرار دهید.
پیشنیازها روی میزبان راه دور
- 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-mac connect، wizard و configure-remote پیکربندی فعال را به این ترتیب تعیین میکنند: ابتدا OPENCLAW_CONFIG_PATH، سپس $OPENCLAW_STATE_DIR/openclaw.json و بعد ~/.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 (پیشرفته): مسیر checkout راه دور که برای فرمانها استفاده میشود.
- CLI path (پیشرفته): مسیر اختیاری یک نقطه ورود/فایل اجرایی
openclawکه قابل اجرا باشد (هنگام اعلام، بهطور خودکار پر میشود).
- روی Test remote بزنید. موفقیت یعنی
openclaw status --jsonراه دور بهدرستی اجرا شده است. خطاها معمولاً به مشکلات PATH/CLI مربوطاند؛ کد خروج 127 یعنی CLI در میزبان راه دور پیدا نشده است. - بررسیهای سلامت و Web Chat اکنون بهطور خودکار از طریق انتقال انتخابشده اجرا میشوند.
Web Chat
- تونل SSH: از طریق پورت کنترلی WebSocket منتقلشده به Gateway متصل میشود (پیشفرض 18789).
- مستقیم (ws/wss): مستقیماً به نشانی پیکربندیشده Gateway متصل میشود.
- هیچ سرور HTTP جداگانهای برای Web Chat وجود ندارد.
مجوزها
- میزبان راه دور به همان تأییدیههای TCC حالت محلی نیاز دارد (Automation، Accessibility، Screen Recording، Microphone، Speech Recognition، Notifications). برای اعطای آنها، ورود اولیه را یکبار روی آن دستگاه اجرا کنید.
- گرهها وضعیت مجوزهای خود را از طریق
node.list/node.describeاعلام میکنند تا عاملها بدانند چه امکاناتی در دسترس است.
نکات امنیتی
- در میزبان راه دور، اتصال به loopback را ترجیح دهید و از طریق SSH، Tailscale Serve یا نشانی مستقیم مورداعتماد Tailnet/LAN متصل شوید.
- تونلزنی SSH بهطور پیشفرض به کلید میزبانی نیاز دارد که از قبل مورداعتماد باشد. ابتدا به کلید میزبان اعتماد کنید (آن را به فایل پیکربندیشده میزبانهای شناختهشده بیفزایید)، یا برای نام مستعار مدیریتشدهای که خطمشی اعتماد OpenSSH آن را میپذیرید، صراحتاً
gateway.remote.sshHostKeyPolicy: "openssh"را تنظیم کنید. - اگر Gateway را به یک رابط غیر-loopback متصل میکنید، احراز هویت معتبر Gateway را الزامی کنید: توکن، گذرواژه یا یک پراکسی معکوس آگاه از هویت با
gateway.auth.mode: "trusted-proxy". - اتصالهای مستقیم
wss://یک خطمشی گواهی را هم برای ترافیک اپراتور/کنترل و هم برای گره همراه Mac اعمال میکنند. برای پین صریح،gateway.remote.tlsFingerprintرا تنظیم کنید. بدون آن، برنامه تنها پس از موفقیت اعتماد عادی macOS، پین نخستین استفاده را ثبت میکند. - امنیت و 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 واقعی کارخواه را ببیند، Transport را به Direct (ws/wss) تغییر دهید. |
| داشبورد کار میکند، اما قابلیتهای Mac آفلاین هستند | اتصال اپراتور/کنترل سالم است، اما اتصال Node همراه برقرار نیست یا سطح فرمان آن وجود ندارد. بخش دستگاه را در نوار منو باز کنید و بررسی کنید که آیا Mac در وضعیت paired · disconnected است. اتصالهای مستقیم اپراتور و Node در wss:// از همان خطمشی گواهی پیکربندیشده یا ذخیرهشده استفاده میکنند. برای نقاط پایانی مطمئن Tailscale Serve در wss://*.ts.net، پینهای قدیمی ذخیرهشده گواهی نهایی پس از چرخش گواهی جایگزین میشوند و تلاش مجدد بهطور خودکار انجام میشود. پینهای پیکربندیشده هرگز بهطور خودکار نمیچرخند؛ پس از بررسی گواهی جدید، gateway.remote.tlsFingerprint را بهروزرسانی کنید یا به Remote over SSH تغییر دهید. |
| بیدارباش صوتی | عبارتهای فعالساز در حالت راهدور بهطور خودکار هدایت میشوند؛ به هدایتکننده جداگانهای نیاز نیست. |
صداهای اعلان
برای هر اعلان، صداها را از اسکریپتها با openclaw nodes notify انتخاب کنید، برای مثال:
openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glassدر برنامه هیچ کلید سراسری برای صدای پیشفرض وجود ندارد؛ فراخوانندهها برای هر درخواست یک صدا (یا بدون صدا) انتخاب میکنند.
