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

# OpenClaw راه دور (macOS ⇄ میزبان راه دور)

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

## حالت‌ها

- **محلی (همین Mac)**: همه‌چیز روی لپ‌تاپ اجرا می‌شود. SSH دخیل نیست.
- **راه دور از طریق SSH (پیش‌فرض)**: فرمان‌های OpenClaw روی میزبان راه دور اجرا می‌شوند. برنامهٔ Mac یک اتصال SSH با `-o BatchMode` به‌همراه هویت/کلید انتخابی شما و یک انتقال پورت محلی باز می‌کند.
- **راه دور مستقیم (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، Web Chat، و
سرویس میزبان 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` پیوند نمادین بسازید).
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** (پیشرفته): مسیر اختیاری به یک نقطهٔ ورود/باینری قابل اجرای `openclaw` (هنگام تبلیغ، خودکار پر می‌شود).
3. **آزمایش راه دور** را بزنید. موفقیت یعنی `openclaw status --json` راه دور درست اجرا می‌شود. خطاها معمولاً به مشکلات PATH/CLI مربوط‌اند؛ کد خروج 127 یعنی CLI روی میزبان راه دور پیدا نشده است.
4. بررسی‌های سلامت و Web Chat اکنون به‌صورت خودکار از طریق این تونل SSH اجرا می‌شوند.

## Web Chat

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

## مجوزها

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

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

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

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

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

## عیب‌یابی

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

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

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

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

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

## مرتبط

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