---
read_when:
    - راه‌اندازی یا اشکال‌زدایی کنترل از راه دور مک
summary: روند برنامه macOS برای کنترل یک Gateway راه‌دور OpenClaw از طریق SSH
title: کنترل از راه دور
x-i18n:
    generated_at: "2026-05-06T09:30:57Z"
    model: gpt-5.5
    provider: openai
    source_hash: bd7eb110f4c3e6a52b4b9baeccce4ef9d02c01104c188940c28f245bc161894a
    source_path: platforms/mac/remote.md
    workflow: 16
---

این جریان به برنامه macOS اجازه می‌دهد مثل یک کنترل از راه دور کامل برای یک OpenClaw Gateway که روی میزبان دیگری (دسکتاپ/سرور) اجرا می‌شود عمل کند. این همان قابلیت **راه دور از طریق SSH** (اجرای راه دور) برنامه است. همه قابلیت‌ها - بررسی‌های سلامت، هدایت Voice Wake، و گفت‌وگوی وب - همان پیکربندی SSH راه دور را از _تنظیمات → عمومی_ بازاستفاده می‌کنند.

## حالت‌ها

- **محلی (این Mac)**: همه‌چیز روی لپ‌تاپ اجرا می‌شود. SSH دخیل نیست.
- **راه دور از طریق SSH (پیش‌فرض)**: فرمان‌های OpenClaw روی میزبان راه دور اجرا می‌شوند. برنامه Mac با `-o BatchMode` به‌همراه هویت/کلید انتخابی شما و یک بازارسال پورت محلی، اتصال SSH باز می‌کند.
- **اتصال مستقیم راه دور (ws/wss)**: تونل SSH وجود ندارد. برنامه Mac مستقیماً به URL مربوط به Gateway وصل می‌شود (برای مثال، از طریق Tailscale Serve یا یک پراکسی معکوس HTTPS عمومی).

## انتقال‌های راه دور

حالت راه دور از دو انتقال پشتیبانی می‌کند:

- **تونل SSH** (پیش‌فرض): از `ssh -N -L ...` برای بازارسال پورت Gateway به localhost استفاده می‌کند. Gateway نشانی IP مربوط به Node را `127.0.0.1` خواهد دید، چون تونل loopback است.
- **مستقیم (ws/wss)**: مستقیماً به URL مربوط به Gateway وصل می‌شود. Gateway نشانی IP واقعی کلاینت را می‌بیند.

در حالت تونل SSH، نام‌های میزبان کشف‌شده LAN/tailnet به‌صورت
`gateway.remote.sshTarget` ذخیره می‌شوند. برنامه `gateway.remote.url` را روی نقطه پایانی تونل محلی نگه می‌دارد، برای مثال `ws://127.0.0.1:18789`، تا CLI، گفت‌وگوی وب، و سرویس میزبان محلی Node همگی از همان انتقال loopback امن استفاده کنند.

خودکارسازی مرورگر در حالت راه دور متعلق به میزبان Node مربوط به CLI است، نه Node بومی برنامه macOS. برنامه، سرویس نصب‌شده میزبان Node را هرجا ممکن باشد راه‌اندازی می‌کند؛ اگر از همان Mac به کنترل مرورگر نیاز دارید، آن را با `openclaw node install ...` و `openclaw node start` نصب/راه‌اندازی کنید (یا `openclaw node run ...` را در پیش‌زمینه اجرا کنید)، سپس همان Node دارای قابلیت مرورگر را هدف بگیرید.

## پیش‌نیازها روی میزبان راه دور

1. Node + pnpm را نصب کنید و OpenClaw CLI را بسازید/نصب کنید (`pnpm install && pnpm build && pnpm link --global`).
2. مطمئن شوید `openclaw` برای شِل‌های غیرتعاملی روی PATH قرار دارد (در صورت نیاز به `/usr/local/bin` یا `/opt/homebrew/bin` symlink کنید).
3. SSH را با احراز هویت کلیدی باز کنید. برای دسترسی پایدار بیرون از LAN، IPهای **Tailscale** را توصیه می‌کنیم.

## راه‌اندازی برنامه macOS

1. _تنظیمات → عمومی_ را باز کنید.
2. زیر **OpenClaw اجرا می‌شود**، **راه دور از طریق SSH** را انتخاب کنید و این موارد را تنظیم کنید:
   - **انتقال**: **تونل SSH** یا **مستقیم (ws/wss)**.
   - **هدف SSH**: `user@host` (اختیاری `:port`).
     - اگر Gateway روی همان LAN است و Bonjour را اعلام می‌کند، آن را از فهرست کشف‌شده انتخاب کنید تا این فیلد خودکار پر شود.
   - **URL مربوط به Gateway** (فقط مستقیم): `wss://gateway.example.ts.net` (یا `ws://...` برای محلی/LAN).
   - **فایل هویت** (پیشرفته): مسیر کلید شما.
   - **ریشه پروژه** (پیشرفته): مسیر checkout راه دور که برای فرمان‌ها استفاده می‌شود.
   - **مسیر CLI** (پیشرفته): مسیر اختیاری به یک entrypoint/باینری قابل‌اجرای `openclaw` (هنگام اعلام‌شدن به‌صورت خودکار پر می‌شود).
3. **آزمون راه دور** را بزنید. موفقیت نشان می‌دهد `openclaw status --json` راه دور درست اجرا می‌شود. شکست‌ها معمولاً به مشکلات PATH/CLI مربوط‌اند؛ کد خروج 127 یعنی CLI در میزبان راه دور پیدا نشده است.
4. بررسی‌های سلامت و گفت‌وگوی وب اکنون به‌صورت خودکار از طریق این تونل SSH اجرا می‌شوند.

## گفت‌وگوی وب

- **تونل SSH**: گفت‌وگوی وب از طریق پورت کنترل WebSocket بازارسال‌شده به Gateway وصل می‌شود (پیش‌فرض 18789).
- **مستقیم (ws/wss)**: گفت‌وگوی وب مستقیماً به URL پیکربندی‌شده Gateway وصل می‌شود.
- دیگر هیچ سرور HTTP جداگانه‌ای برای WebChat وجود ندارد.

## مجوزها

- میزبان راه دور به همان تأییدیه‌های TCC محلی نیاز دارد (Automation، Accessibility، Screen Recording، Microphone، Speech Recognition، Notifications). فرایند onboarding را روی همان ماشین اجرا کنید تا یک‌بار آن‌ها را اعطا کنید.
- Nodeها وضعیت مجوز خود را از طریق `node.list` / `node.describe` اعلام می‌کنند تا agentها بدانند چه چیزهایی در دسترس است.

## نکات امنیتی

- روی میزبان راه دور، اتصال‌های loopback را ترجیح دهید و از طریق SSH یا Tailscale وصل شوید.
- تونل‌زنی SSH از بررسی سخت‌گیرانه کلید میزبان استفاده می‌کند؛ ابتدا به کلید میزبان اعتماد کنید تا در `~/.ssh/known_hosts` وجود داشته باشد.
- اگر Gateway را به یک رابط غیر loopback bind می‌کنید، احراز هویت معتبر Gateway را الزامی کنید: توکن، گذرواژه، یا یک پراکسی معکوس آگاه از هویت با `gateway.auth.mode: "trusted-proxy"`.
- [امنیت](/fa/gateway/security) و [Tailscale](/fa/gateway/tailscale) را ببینید.

## جریان ورود WhatsApp (راه دور)

- `openclaw channels login --verbose` را **روی میزبان راه دور** اجرا کنید. QR را با WhatsApp روی گوشی خود اسکن کنید.
- اگر احراز هویت منقضی شد، ورود را روی همان میزبان دوباره اجرا کنید. بررسی سلامت مشکلات پیوند را نمایش می‌دهد.

## عیب‌یابی

- **کد خروج 127 / پیدا نشد**: `openclaw` برای شِل‌های غیر login روی PATH نیست. آن را به `/etc/paths`، فایل rc شِل خود اضافه کنید، یا به `/usr/local/bin`/`/opt/homebrew/bin` symlink کنید.
- **کاوش سلامت شکست خورد**: دسترسی SSH، PATH، و وارد بودن Baileys را بررسی کنید (`openclaw status --json`).
- **گفت‌وگوی وب گیر کرده است**: تأیید کنید Gateway روی میزبان راه دور در حال اجراست و پورت بازارسال‌شده با پورت WS مربوط به Gateway مطابقت دارد؛ UI به یک اتصال WS سالم نیاز دارد.
- **IP مربوط به Node برابر 127.0.0.1 نشان داده می‌شود**: با تونل SSH مورد انتظار است. اگر می‌خواهید Gateway نشانی IP واقعی کلاینت را ببیند، **انتقال** را به **مستقیم (ws/wss)** تغییر دهید.
- **داشبورد کار می‌کند اما قابلیت‌های Mac آفلاین هستند**: یعنی اتصال operator/control برنامه سالم است، اما اتصال Node همراه وصل نیست یا سطح فرمان آن وجود ندارد. بخش دستگاه در نوار منو را باز کنید و بررسی کنید آیا Mac به‌صورت `paired · disconnected` است. برای نقطه‌های پایانی Tailscale Serve با `wss://*.ts.net`، برنامه پس از چرخش گواهی، pinهای قدیمی TLS leaf را تشخیص می‌دهد، وقتی macOS به گواهی جدید اعتماد کند pin قدیمی را پاک می‌کند، و به‌صورت خودکار دوباره تلاش می‌کند. اگر گواهی مورد اعتماد سیستم نیست یا میزبان یک نام Tailscale Serve نیست، گواهی را بررسی کنید یا به **راه دور از طریق SSH** تغییر دهید.
- **Voice Wake**: عبارت‌های فعال‌سازی در حالت راه دور به‌صورت خودکار هدایت می‌شوند؛ forwarder جداگانه‌ای لازم نیست.

## صداهای اعلان

صداها را برای هر اعلان از اسکریپت‌ها با `openclaw` و `node.invoke` انتخاب کنید، برای مثال:

```bash
openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass
```

دیگر هیچ کلید سراسری «صدای پیش‌فرض» در برنامه وجود ندارد؛ فراخوان‌ها برای هر درخواست یک صدا (یا هیچ صدا) انتخاب می‌کنند.

## مرتبط

- [برنامه macOS](/fa/platforms/macos)
- [دسترسی راه دور](/fa/gateway/remote)