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

# `openclaw node`

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

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

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

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

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

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

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

برای ابزارهای اعلانی MCP، ساختار معمول سرور MCP را در دستگاه Node زیر
`nodeHost.mcp.servers` در `openclaw.json` اضافه کنید، سپس میزبان 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 وب‌سوکت افزوده می‌شود.
- `--tls`: استفاده از TLS برای اتصال Gateway
- `--no-tls`: اجبار اتصال متن ساده به Gateway، حتی هنگامی که پیکربندی محلی Gateway، TLS را فعال کرده است
- `--tls-fingerprint <sha256>`: اثر انگشت مورد انتظار گواهی TLS ‏(sha256)
- `--node-id <id>`: بازنویسی شناسهٔ قدیمی نمونهٔ کلاینت ذخیره‌شده در `node.json` (جفت‌سازی را بازنشانی نمی‌کند)
- `--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://` متصل می‌شود، local loopback،
آدرس‌های IP خصوصی، `.local` و میزبان‌های Tailnet با الگوی `*.ts.net` پذیرفته
می‌شوند. برای سایر نام‌های 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 وب‌سوکت افزوده می‌شود.
- `--tls`: استفاده از TLS برای اتصال Gateway
- `--tls-fingerprint <sha256>`: اثر انگشت مورد انتظار گواهی TLS ‏(sha256)
- `--node-id <id>`: بازنویسی شناسهٔ قدیمی نمونهٔ کلاینت ذخیره‌شده در `node.json` (جفت‌سازی را بازنشانی نمی‌کند)
- `--display-name <name>`: بازنویسی نام نمایشی Node
- `--runtime <runtime>`: محیط اجرای سرویس (`node` یا `bun`)
- `--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
```

این فرمان شناسهٔ دستگاه و کلید عمومی را از `identity/device.json` چاپ می‌کند و
هرگز فایل‌های هویت را ایجاد یا تغییر نمی‌دهد.

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

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

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

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

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

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

| فایل                        | هدف                                                                                                                                       |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `node.json`                 | شناسهٔ نمونهٔ کلاینت زیر کلید قدیمی `nodeId`، نام نمایشی و فرادادهٔ اتصال Gateway. کلاینت این مقدار را به‌صورت `instanceId` ارسال می‌کند. |
| `identity/device.json`      | جفت‌کلید امضاشدهٔ Ed25519 و شناسهٔ دستگاه مشتق‌شده. برای اتصال‌های امضاشده، این شناسهٔ دستگاه همان شناسهٔ Node مسیریابی‌شده و هویت جفت‌سازی است. |
| `identity/device-auth.json` | توکن‌های دستگاه جفت‌شده، کلیدگذاری‌شده بر اساس شناسهٔ رمزنگاری‌شدهٔ دستگاه و نقش. |

`--node-id` فقط شناسهٔ نمونهٔ کلاینت را در `node.json` تغییر می‌دهد. شناسهٔ
رمزنگاری‌شدهٔ دستگاه را تغییر نمی‌دهد و احراز هویت جفت‌سازی را پاک نمی‌کند.
به همین ترتیب، حذف فقط `node.json` نیز جفت‌سازی را بازنشانی نمی‌کند. برای لغو
و جفت‌سازی مجدد یک 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 ممکن بود یک فیلد قدیمی `token` را در `node.json`
باقی بگذارند. OpenClaw فعلی از آن فیلد استفاده نمی‌کند و دفعهٔ بعد که میزبان
Node فایل را ذخیره کند، آن را حذف می‌کند. هر دو فایل زیر `identity/` را خصوصی
نگه دارید؛ آن‌ها حاوی جفت‌کلید دستگاه و توکن‌های احراز هویت هستند.

## تأییدهای اجرا

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

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

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

## مرتبط

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