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

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

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

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

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

• اجرای فرمان‌ها روی دستگاه‌های راه‌دور Linux/Windows (سرورهای ساخت، دستگاه‌های آزمایشگاه، NAS).
• حفظ اجرای exec در sandbox روی 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 مراجعه کنید.

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

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

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

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

{  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)
• --context-path <path>: مسیر زمینه WebSocket مربوط به Gateway (برای مثال /openclaw-gw). به نشانی 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).

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). به نشانی WebSocket افزوده می‌شود.
• --tls: استفاده از TLS برای اتصال Gateway
• --tls-fingerprint <sha256>: اثر انگشت مورد انتظار گواهی TLS (sha256)
• --node-id <id>: بازنویسی شناسه نمونه کلاینت ذخیره‌شده در وضعیت SQLite مشترک (جفت‌سازی را بازنشانی نمی‌کند)
• --display-name <name>: بازنویسی نام نمایشی Node
• --runtime <runtime>: زمان‌اجرای سرویس (node)
• --force: نصب مجدد/بازنویسی در صورت نصب قبلی

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

openclaw node statusopenclaw node startopenclaw node stopopenclaw node restartopenclaw node uninstall

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

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

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

جفت‌سازی

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

وقتی میزبان Gateway بتواند بدون تعامل به میزبان Node از طریق SSH متصل شود (همان کاربر، کلید میزبان مورد اعتماد)، درخواست در انتظار به‌طور خودکار تأیید می‌شود: Gateway فرمان openclaw node identity --json را از طریق SSH روی میزبان Node اجرا می‌کند و در صورت تطابق دقیق کلید دستگاه، آن را تأیید می‌کند. این قابلیت به‌طور پیش‌فرض فعال است؛ برای الزامات و روش غیرفعال‌سازی آن (gateway.nodes.pairing.sshVerify: false) به تأیید خودکار دستگاه با اعتبارسنجی SSH مراجعه کنید.

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

openclaw devices listopenclaw devices approve <requestId>

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

openclaw node identity --json

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

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

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

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

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

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

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

--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 ذخیره می‌کردند و ممکن بود یک فیلد منسوخ token را در آن باقی بگذارند. میزبان Node را متوقف کنید و openclaw doctor --fix را یک بار اجرا کنید؛ Doctor فیلدهای پشتیبانی‌شده هویت و اتصال را به SQLite وارد می‌کند، فیلد توکن استفاده‌نشده را دور می‌اندازد، سطر را تأیید می‌کند و فایل بازنشسته را حذف می‌کند. تا زمانی که فایل یا ادعای ناتمام Doctor باقی است، فرمان‌های عادی Node به‌صورت بسته شکست می‌خورند و این دستورالعمل تعمیر را نمایش می‌دهند. هر دو فایل زیر identity/ را خصوصی نگه دارید؛ آن‌ها شامل جفت‌کلید دستگاه و توکن‌های احراز هویت هستند.

تأییدهای exec

system.run توسط تأییدهای محلی exec کنترل می‌شود:

• $OPENCLAW_STATE_DIR/exec-approvals.json، یا ~/.openclaw/exec-approvals.json هنگامی که متغیر تنظیم نشده است
• تأییدهای exec
• openclaw approvals --node <id|name|ip> (ویرایش از Gateway)

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

مرتبط

• مرجع CLI
• Nodeها