# openclaw node

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

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

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

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

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

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

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

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

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

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

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

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

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 وقتی در محیط دستور نصب حاضر باشد، آن را در سرویس نود تحت نظارت پایدار می‌کند.

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

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

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: نصب دوباره/بازنویسی اگر از قبل نصب شده باشد

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

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 ایجاد می‌کند. آن را از این طریق تأیید کنید:

openclaw devices list
openclaw devices approve <requestId>

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

{
  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
• تأییدیه‌های اجرا
• openclaw approvals --node <id|name|ip> (ویرایش از Gateway)

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

# مرتبط

• مرجع CLI
• نودها