---
read_when:
    - اجرای میزبان Node بدون رابط کاربری
    - جفت‌سازی یک گره غیر macOS برای system.run
summary: مرجع CLI برای `openclaw node` (میزبان Node بدون رابط کاربری)
title: Node
x-i18n:
    generated_at: "2026-05-06T17:54:16Z"
    model: gpt-5.5
    provider: openai
    source_hash: af4735ac4961dc36fd3f11299eb3ec4e156835e7257b21a79bb1d4b467445faa
    source_path: cli/node.md
    workflow: 16
---

# `openclaw node`

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

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

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

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

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

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

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

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

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

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

```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`)
- `--tls`: استفاده از TLS برای اتصال Gateway
- `--tls-fingerprint <sha256>`: اثرانگشت گواهی TLS مورد انتظار (sha256)
- `--node-id <id>`: نادیده گرفتن شناسه نود (توکن جفت‌سازی را پاک می‌کند)
- `--display-name <name>`: نادیده گرفتن نام نمایشی نود

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

`openclaw node run` و `openclaw node install` احراز هویت Gateway را از config/env حل می‌کنند (هیچ پرچم `--token`/`--password` روی دستورهای نود وجود ندارد):

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

برای نودی که به یک Gateway غیر local loopback با `ws://` در یک شبکه خصوصی مورد اعتماد وصل می‌شود،
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` را تنظیم کنید. بدون آن، راه‌اندازی نود
بسته شکست می‌خورد و از شما می‌خواهد از `wss://`، یک تونل SSH، یا Tailscale استفاده کنید.
این یک اعلام رضایت در محیط پردازش است، نه یک کلید پیکربندی `openclaw.json`.
`openclaw node install` وقتی در محیط دستور نصب حاضر باشد، آن را در سرویس نود تحت نظارت
پایدار می‌کند.

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

یک میزبان نود بدون رابط کاربری را به‌عنوان سرویس کاربر نصب کنید.

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

گزینه‌ها:

- `--host <host>`: میزبان WebSocket Gateway (پیش‌فرض: `127.0.0.1`)
- `--port <port>`: پورت WebSocket Gateway (پیش‌فرض: `18789`)
- `--tls`: استفاده از TLS برای اتصال Gateway
- `--tls-fingerprint <sha256>`: اثرانگشت گواهی TLS مورد انتظار (sha256)
- `--node-id <id>`: نادیده گرفتن شناسه نود (توکن جفت‌سازی را پاک می‌کند)
- `--display-name <name>`: نادیده گرفتن نام نمایشی نود
- `--runtime <runtime>`: runtime سرویس (`node` یا `bun`)
- `--force`: نصب دوباره/بازنویسی اگر از قبل نصب شده باشد

مدیریت سرویس:

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

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

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

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

## جفت‌سازی

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

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

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

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

این به‌طور پیش‌فرض غیرفعال است. فقط برای جفت‌سازی تازه `role: node` بدون
scopeهای درخواستی اعمال می‌شود. کلاینت‌های اپراتور/مرورگر، Control UI، WebChat، و ارتقاهای role،
scope، metadata، یا public-key همچنان به تأیید دستی نیاز دارند.

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

میزبان نود شناسه نود، توکن، نام نمایشی، و اطلاعات اتصال Gateway خود را در
`~/.openclaw/node.json` ذخیره می‌کند.

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

`system.run` با تأییدیه‌های اجرای محلی کنترل می‌شود:

- `~/.openclaw/exec-approvals.json`
- [تأییدیه‌های اجرا](/fa/tools/exec-approvals)
- `openclaw approvals --node <id|name|ip>` (ویرایش از Gateway)

برای اجرای نود async تأییدشده، OpenClaw پیش از درخواست تأیید، یک `systemRunPlan`
canonical آماده می‌کند. ارسال بعدی `system.run` تأییدشده همان plan ذخیره‌شده را دوباره استفاده می‌کند،
پس ویرایش‌های فیلدهای command/cwd/session پس از ایجاد درخواست تأیید
به‌جای تغییر دادن چیزی که نود اجرا می‌کند، رد می‌شوند.

## مرتبط

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