---
read_when:
    - اجرای میزبان Node بدون رابط گرافیکی
    - جفت‌سازی یک Node غیر macOS برای system.run
summary: مرجع CLI برای `openclaw node` (میزبان Node بدون رابط گرافیکی)
title: Node
x-i18n:
    generated_at: "2026-07-27T13:55:24Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 341539d05545ddcbf6175c34af7dca49332ba55906283b9933b9c9b1732c0e4d
    source_path: cli/node.md
    workflow: 16
---

# `openclaw node`

یک **میزبان Node بدون رابط گرافیکی** اجرا کنید که به WebSocket مربوط به Gateway متصل می‌شود و
`system.run` / `system.which` را روی این دستگاه ارائه می‌کند.

در macOS، برنامه نوار منو از قبل این زمان‌اجرای میزبان Node را در اتصال Node خود
تعبیه کرده و قابلیت‌های بومی Mac را اضافه می‌کند. از `openclaw node run` روی Mac
فقط زمانی استفاده کنید که عمداً یک Node بدون رابط گرافیکی و بدون برنامه می‌خواهید. اجرای
هم‌زمان هر دو، دو هویت Node برای یک دستگاه ایجاد می‌کند.

## چرا از میزبان Node استفاده کنیم؟

هنگامی از میزبان Node استفاده کنید که می‌خواهید عامل‌ها **فرمان‌ها را روی دستگاه‌های دیگر**
در شبکه‌تان اجرا کنند، بدون آنکه برنامه همراه کامل macOS را روی آن‌ها نصب کنید.

موارد استفاده رایج:

- اجرای فرمان‌ها روی دستگاه‌های راه‌دور Linux/Windows (سرورهای ساخت، دستگاه‌های آزمایشگاه، NAS).
- حفظ exec به‌صورت **ایزوله‌شده** روی Gateway، اما واگذاری اجراهای تأییدشده به میزبان‌های دیگر.
- فراهم‌کردن یک مقصد اجرای سبک و بدون رابط گرافیکی برای خودکارسازی یا Nodeهای CI.

اجرا همچنان با **تأییدهای exec** و فهرست‌های مجاز مختص هر عامل روی
میزبان Node محافظت می‌شود؛ بنابراین می‌توانید دسترسی به فرمان‌ها را محدود و صریح نگه دارید.

`openclaw node run` می‌تواند پس از اتصال، ابزارهای مبتنی بر Plugin یا MCP را منتشر کند.
Gateway به‌طور پیش‌فرض به توصیف‌گرهای Node جفت‌شده اعتماد می‌کند، اما الزام می‌کند
که فرمان هر توصیف‌گر در سطح فرمان‌های تأییدشده Node باقی بماند. عامل هر توصیف‌گر
پذیرفته‌شده را به‌شکل یک ابزار Plugin عادی می‌بیند، اما اجرا همچنان از طریق
`node.invoke` انجام می‌شود؛ بنابراین قطع اتصال Node، ابزار را از اجراهای جدید
عامل حذف می‌کند. اپراتورهای Gateway می‌توانند انتشار را با
`gateway.nodes.pluginTools.enabled: false` غیرفعال کنند.

برای ابزارهای MCP اعلانی، ساختار عادی سرور MCP را زیر
`nodeHost.mcp.servers` در `openclaw.json` روی دستگاه Node اضافه کنید، سپس
میزبان Node را راه‌اندازی مجدد کنید. Node خانواده فرمان `mcp.tools.call.v1`
را که مشروط به تأیید است اعلام می‌کند و ابزارهای فهرست‌شده را پس از اتصال منتشر
می‌کند؛ تغییر فهرست سرورها در آینده به جفت‌سازی مجدد نیاز ندارد. به
[سرورهای MCP میزبانی‌شده روی Node](/fa/nodes#node-hosted-mcp-servers) مراجعه کنید.

## پراکسی مرورگر (بدون پیکربندی)

اگر `browser.enabled` روی Node غیرفعال نشده باشد، میزبان‌های Node به‌طور خودکار
یک پراکسی مرورگر را اعلام می‌کنند. این قابلیت به عامل اجازه می‌دهد بدون پیکربندی
اضافی، از خودکارسازی مرورگر روی آن Node استفاده کند.

پراکسی به‌طور پیش‌فرض سطح عادی پروفایل مرورگر Node را ارائه می‌کند. اگر
`nodeHost.browserProxy.allowProfiles` را تنظیم کنید، پراکسی محدودکننده می‌شود:
هدف‌گیری پروفایل‌هایی که در فهرست مجاز نیستند رد می‌شود و مسیرهای ایجاد/حذف
پروفایل دائمی از طریق پراکسی مسدود می‌شوند.

در صورت نیاز، آن را روی Node غیرفعال کنید:

```json5
{
  nodeHost: {
    browserProxy: {
      enabled: false,
    },
  },
}
```

## اجرا (پیش‌زمینه)

```bash
openclaw node run --host <gateway-host> --port 18789
```

گزینه‌ها:

- `--host <host>`: میزبان WebSocket مربوط به Gateway (پیش‌فرض: `127.0.0.1`)
- `--port <port>`: درگاه WebSocket مربوط به Gateway (پیش‌فرض: `18789`)
- `--context-path <path>`: مسیر زمینه WebSocket مربوط به Gateway (برای مثال `/openclaw-gw`). به URL مربوط به WebSocket افزوده می‌شود.
- `--tls`: استفاده از TLS برای اتصال Gateway
- `--no-tls`: اجبار اتصال متن ساده به Gateway، حتی زمانی که پیکربندی Gateway محلی TLS را فعال کرده است
- `--tls-fingerprint <sha256>`: اثر انگشت مورد انتظار گواهی TLS (sha256)
- `--node-id <id>`: بازنویسی شناسه نمونه کلاینت ذخیره‌شده در وضعیت SQLite مشترک (جفت‌سازی را بازنشانی نمی‌کند)
- `--display-name <name>`: بازنویسی نام نمایشی Node

## احراز هویت Gateway برای میزبان Node

`openclaw node run` و `openclaw node install` احراز هویت Gateway را از پیکربندی/محیط تعیین می‌کنند (در فرمان‌های Node پرچم‌های `--token`/`--password` وجود ندارند):

- `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` ابتدا بررسی می‌شوند.
- سپس پیکربندی محلی به‌عنوان گزینه جایگزین: `gateway.auth.token` / `gateway.auth.password`.
- در حالت محلی، میزبان Node عمداً `gateway.remote.token` / `gateway.remote.password` را به ارث نمی‌برد.
- اگر `gateway.auth.token` / `gateway.auth.password` صراحتاً از طریق SecretRef پیکربندی شده و حل‌نشده باشد، تعیین احراز هویت Node به‌صورت بسته شکست می‌خورد (بدون آنکه گزینه جایگزین راه‌دور مشکل را پنهان کند).
- در `gateway.mode=remote`، فیلدهای کلاینت راه‌دور (`gateway.remote.token` / `gateway.remote.password`) نیز طبق قواعد اولویت راه‌دور قابل استفاده هستند.
- تعیین احراز هویت میزبان Node فقط متغیرهای محیطی `OPENCLAW_GATEWAY_*` را می‌پذیرد.

برای Nodeای که به یک Gateway متن ساده `ws://` متصل می‌شود، loopback، آدرس‌های
IP خصوصی صریح، `.local` و میزبان‌های `*.ts.net` در Tailnet پذیرفته
می‌شوند. برای سایر نام‌های DNS خصوصی مورد اعتماد، `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` را تنظیم کنید؛
بدون آن، راه‌اندازی Node به‌صورت بسته شکست می‌خورد و از شما می‌خواهد از
`wss://`، تونل SSH یا Tailscale استفاده کنید. این یک انتخاب صریح در
محیط فرایند است، نه کلید پیکربندی `openclaw.json`.
اگر `openclaw node install` در محیط فرمان نصب وجود داشته باشد، آن را در سرویس
تحت نظارت Node ماندگار می‌کند.

## سرویس (پس‌زمینه)

یک میزبان Node بدون رابط گرافیکی را به‌عنوان سرویس کاربر نصب کنید (launchd در macOS، ‏systemd در
Linux و Windows Task Scheduler در Windows).

```bash
openclaw node install --host <gateway-host> --port 18789
```

گزینه‌ها:

- `--host <host>`: میزبان WebSocket مربوط به Gateway (پیش‌فرض: `127.0.0.1`)
- `--port <port>`: درگاه WebSocket مربوط به Gateway (پیش‌فرض: `18789`)
- `--context-path <path>`: مسیر زمینه WebSocket مربوط به Gateway (برای مثال `/openclaw-gw`). به URL مربوط به WebSocket افزوده می‌شود.
- `--tls`: استفاده از TLS برای اتصال Gateway
- `--tls-fingerprint <sha256>`: اثر انگشت مورد انتظار گواهی TLS (sha256)
- `--node-id <id>`: بازنویسی شناسه نمونه کلاینت ذخیره‌شده در وضعیت SQLite مشترک (جفت‌سازی را بازنشانی نمی‌کند)
- `--display-name <name>`: بازنویسی نام نمایشی Node
- `--runtime <runtime>`: زمان‌اجرای سرویس (`node`)
- `--force`: نصب مجدد/بازنویسی در صورت نصب‌بودن قبلی

سرویس را مدیریت کنید:

```bash
openclaw node status
openclaw node start
openclaw node stop
openclaw node restart
openclaw node uninstall
```

برای میزبان Node پیش‌زمینه‌ای (بدون سرویس) از `openclaw node run` استفاده کنید.

فرمان‌های سرویس برای خروجی قابل‌خواندن توسط ماشین، `--json` را می‌پذیرند.

میزبان Node راه‌اندازی مجدد Gateway و بسته‌شدن‌های شبکه را درون فرایند دوباره
امتحان می‌کند. اگر Gateway یک توقف نهایی احراز هویت به‌دلیل توکن/گذرواژه/bootstrap
گزارش کند، میزبان Node جزئیات بسته‌شدن را ثبت می‌کند و با کد غیرصفر خارج می‌شود تا
launchd/systemd/Task Scheduler بتواند آن را با پیکربندی و اعتبارنامه‌های تازه
راه‌اندازی مجدد کند. توقف‌های نیازمند جفت‌سازی در جریان پیش‌زمینه باقی می‌مانند
تا درخواست معلق بتواند تأیید شود.

## جفت‌سازی

نخستین اتصال یک درخواست معلق جفت‌سازی دستگاه (`role: node`) روی Gateway ایجاد می‌کند.

وقتی میزبان Gateway بتواند به‌صورت غیرتعاملی با SSH به میزبان Node متصل شود (همان کاربر،
کلید میزبان مورد اعتماد)، درخواست معلق به‌طور خودکار تأیید می‌شود: Gateway
فرمان `openclaw node identity --json` را از طریق SSH روی میزبان Node اجرا می‌کند و در صورت
تطابق دقیق کلید دستگاه، آن را تأیید می‌کند. این قابلیت به‌طور پیش‌فرض فعال است؛
برای الزامات و روش غیرفعال‌کردن آن (`gateway.nodes.pairing.sshVerify: false`) به
[تأیید خودکار دستگاه با اعتبارسنجی SSH](/fa/gateway/pairing#ssh-verified-device-auto-approval-default)
مراجعه کنید.

در غیر این صورت، به‌صورت دستی تأیید کنید:

```bash
openclaw devices list
openclaw devices approve <requestId>
```

هویت محلی Node را که Gateway با آن اعتبارسنجی می‌کند بررسی کنید:

```bash
openclaw node identity --json
```

این فرمان شناسه دستگاه و کلید عمومی را از ردیف `primary` در
`state/openclaw.sqlite` نمایش می‌دهد و هرگز پایگاه داده یا هویت جدیدی ایجاد نمی‌کند.

در شبکه‌های Node به‌شدت کنترل‌شده، اپراتور Gateway می‌تواند صراحتاً تأیید خودکار
جفت‌سازی بار نخست Node از CIDRهای مورد اعتماد را فعال کند:

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

این قابلیت به‌طور پیش‌فرض غیرفعال است (`autoApproveCidrs` تنظیم نشده است). فقط برای
جفت‌سازی جدید `role: node` بدون حوزه‌های درخواستی و از IP کلاینتی که
Gateway به آن اعتماد دارد اعمال می‌شود. کلاینت‌های اپراتور/مرورگر، Control UI، ‏WebChat و ارتقاهای
نقش، حوزه، فراداده یا کلید عمومی همچنان به تأیید دستی نیاز دارند.

اگر Node جفت‌سازی را با جزئیات احراز هویت تغییرکرده (نقش/حوزه‌ها/کلید عمومی) دوباره
امتحان کند، درخواست معلق قبلی جایگزین می‌شود و یک `requestId` جدید ایجاد می‌شود.
پیش از تأیید، `openclaw devices list` را دوباره اجرا کنید.

### وضعیت هویت و جفت‌سازی

Node بدون رابط گرافیکی، شناسه نمونه کلاینت خود را از هویت امضاشده دستگاه
که Gateway برای جفت‌سازی و مسیریابی استفاده می‌کند جدا نگه می‌دارد. این وضعیت در
پوشه وضعیت OpenClaw قرار دارد (به‌طور پیش‌فرض `~/.openclaw`، یا در صورت تنظیم
`$OPENCLAW_STATE_DIR`):

| وضعیت                                                    | هدف                                                                                                                          |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `state/openclaw.sqlite` (`node_host_config`)             | شناسه نمونه کلاینت، نام نمایشی و فراداده اتصال Gateway. کلاینت این شناسه را به‌صورت `instanceId` ارسال می‌کند.                     |
| `state/openclaw.sqlite` (`device_identities`, `primary`) | جفت‌کلید امضاشده Ed25519 و شناسه دستگاه مشتق‌شده. برای اتصال‌های امضاشده، این شناسه دستگاه همان شناسه Node مسیریابی‌شده و هویت جفت‌سازی است. |
| `state/openclaw.sqlite` (`device_auth_tokens`)           | توکن‌های دستگاه جفت‌شده، کلیدگذاری‌شده بر اساس شناسه رمزنگاری‌شده دستگاه و نقش.                                                                 |

`--node-id` فقط شناسه نمونه کلاینت را در وضعیت SQLite مشترک تغییر می‌دهد.
این کار شناسه رمزنگاری‌شده دستگاه را تغییر نمی‌دهد و احراز هویت جفت‌سازی را پاک نمی‌کند.
مهاجرت یک `node.json` بازنشسته با `openclaw doctor --fix` نیز جفت‌سازی را
بازنشانی نمی‌کند. برای لغو و جفت‌سازی مجدد یک Node:

1. روی Gateway، فرمان `openclaw nodes remove --node <id|name|ip>` را اجرا کنید.
2. روی Node، سرویس نصب‌شده را با `openclaw node restart` راه‌اندازی مجدد کنید، یا
   فرمان پیش‌زمینه `openclaw node run` را متوقف کرده و دوباره اجرا کنید. این کار
   جریان جفت‌سازی دستگاه را آغاز می‌کند. اگر `openclaw devices list` درخواستی نشان
   نمی‌دهد و Node خطای `AUTH_DEVICE_TOKEN_MISMATCH` را گزارش می‌کند، آن را یک بار دیگر
   راه‌اندازی مجدد یا دوباره اجرا کنید. تلاش ردشده توکن محلیِ اکنون لغوشده را پاک
   می‌کند؛ تلاش بعدی می‌تواند درخواست جفت‌سازی بدهد.
3. روی Gateway، فرمان `openclaw devices list` و سپس
   `openclaw devices approve <deviceRequestId>` را اجرا کنید.
4. Node را دوباره راه‌اندازی یا اجرا کنید. کلاینتی که برای جفت‌سازی متوقف شده است،
   پس از تأیید به‌طور خودکار ادامه نمی‌دهد؛ این اتصال مجدد، درخواست جداگانه
   سطح فرمان را ایجاد می‌کند.
5. روی Gateway، فرمان `openclaw nodes pending` و سپس
   `openclaw nodes approve <nodeRequestId>` را اجرا کنید.

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

نسخه‌های قدیمی‌تر OpenClaw وضعیت میزبان Node را در `node.json`، هویت امضاشده
را در `identity/device.json` و احراز هویت جفت‌شده را در
`identity/device-auth.json` ذخیره می‌کردند. میزبان Node را متوقف کنید و
`openclaw doctor --fix` را یک بار اجرا کنید؛ Doctor هر منبع بازنشسته را تصاحب و
اعتبارسنجی می‌کند، ردیف استاندارد SQLite را وارد و تأیید می‌کند، سپس فایل قدیمی را
حذف می‌کند. تا زمانی که یکی از فایل‌های بازنشسته یا یک تصاحب ناتمام Doctor باقی
مانده باشد، فرمان‌های عادی Node با این دستورالعمل تعمیر به‌صورت بسته شکست می‌خورند.
`state/openclaw.sqlite` را خصوصی نگه دارید؛ این مورد حاوی جفت‌کلید دستگاه و توکن‌های
احراز هویت است.

## تأییدهای Exec

`system.run` مشروط به تأییدهای محلی exec است:

- `$OPENCLAW_STATE_DIR/exec-approvals.json`، یا
  در صورت تنظیم‌نبودن متغیر، `~/.openclaw/exec-approvals.json`
- [تأییدهای Exec](/fa/tools/exec-approvals)
- `openclaw approvals --node <id|name|ip>` (ویرایش از Gateway)

برای اجرای ناهمگام تأییدشده روی Node، ‏OpenClaw پیش از درخواست تأیید یک
`systemRunPlan` استاندارد آماده می‌کند. ارسال بعدی `system.run` که
تأیید شده است از همان طرح ذخیره‌شده دوباره استفاده می‌کند؛ بنابراین ویرایش فیلدهای
فرمان/cwd/session پس از ایجاد درخواست تأیید، به‌جای تغییر آنچه Node اجرا می‌کند
رد می‌شود.

## مرتبط

- [مرجع CLI](/fa/cli)
- [Nodeها](/fa/node