Nodeها

یک گره دستگاهی همراه (macOS/iOS/watchOS/Android/بدون رابط گرافیکی) است که با role: "node" به Gateway متصل می‌شود و از طریق node.invoke سطحی از فرمان‌ها (برای مثال canvas.*، camera.*، device.*، notifications.*، system.*) را ارائه می‌کند. بیشتر گره‌ها از WebSocket مربوط به Gateway روی درگاه اپراتور استفاده می‌کنند. گره مستقیم و اختیاری Apple Watch از نظرسنجی HTTPS امضاشده روی همان درگاه استفاده می‌کند، زیرا watchOS شبکه‌سازی عمومی سطح‌پایین را برای برنامه‌های عادی مسدود می‌کند. جزئیات پروتکل: پروتکل Gateway.

انتقال قدیمی: پروتکل Bridge (TCP JSONL؛ فقط برای پیشینه گره‌های فعلی).

macOS همچنین می‌تواند در حالت گره اجرا شود: برنامه نوار منو به سرور WS مربوط به Gateway به‌عنوان یک گره متصل می‌شود (بنابراین openclaw nodes … روی این Mac کار می‌کند). برنامه فرمان‌های بومی Canvas، دوربین، صفحه‌نمایش، اعلان و کنترل رایانه را به همان سطح فرمان میزبان گره که openclaw node run استفاده می‌کند، می‌افزاید. روی آن Mac یک گره CLI دوم راه‌اندازی نکنید؛ برنامه محیط اجرای میزبان گره CLI متناظر را به‌عنوان یک کارگر داخلی اجرا می‌کند و تنها اتصال Gateway و هویت گره باقی می‌ماند.

گره‌ها تجهیزات جانبی هستند، نه Gateway: سرویس Gateway را اجرا نمی‌کنند و پیام‌های کانال (Telegram، WhatsApp و غیره) به Gateway می‌رسند، نه به گره‌ها.

راهنمای عیب‌یابی: /nodes/troubleshooting

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

گره‌ها از جفت‌سازی دستگاه استفاده می‌کنند. گره هنگام اتصال یک هویت دستگاه امضاشده ارائه می‌دهد؛ Gateway برای role: node یک درخواست جفت‌سازی دستگاه ایجاد می‌کند. آن را از طریق CLI دستگاه‌ها (یا رابط کاربری) تأیید کنید. راه‌اندازی مستقیم Apple Watch از یک کد راه‌اندازی کوتاه‌عمر و مختص گره که مدیر صادر کرده است برای تأیید سطح فرمان ثابت و کم‌خطر آن استفاده می‌کند؛ گسترش قابلیت‌ها در آینده همچنان به تأیید عادی نیاز دارد.

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>

درخواست‌های جفت‌سازی در انتظار، 5 دقیقه پس از آخرین تلاش مجدد دستگاه منقضی می‌شوند — دستگاهی که پیوسته دوباره متصل می‌شود، همان یک درخواست در انتظار (و requestId) را زنده نگه می‌دارد، به‌جای آنکه هر چند دقیقه یک درخواست جدید صادر کند؛ برای چرخه کامل درخواست/تأیید، به جفت‌سازی گره مراجعه کنید. اگر گره با جزئیات احراز هویت تغییریافته (نقش/دامنه‌ها/کلید عمومی) دوباره تلاش کند، درخواست در انتظار قبلی جایگزین و یک requestId جدید ایجاد می‌شود — کلاینت‌ها برای درخواست جایگزین‌شده یک رویداد device.pair.resolved دریافت می‌کنند و باید پیش از تأیید، openclaw devices list را دوباره اجرا کنید.

• nodes status زمانی گره را جفت‌شده علامت‌گذاری می‌کند که نقش جفت‌سازی دستگاه آن شامل node باشد.
• یک Mac بومی متصل که مجوز Accessibility دارد، می‌تواند فعالیت تجمیع‌شده ورودی فیزیکی را گزارش کند. Gateway تازه‌ترین Mac واجد شرایط را به‌عنوان active علامت‌گذاری می‌کند، یک راهنمای پایدار شناسه گره به عامل می‌دهد و هشدارهای اتصال گره را پیش از بازگشت جایگزینِ با تأخیر به آن هدایت می‌کند. برای راه‌اندازی، حریم خصوصی، زمان‌بندی و عیب‌یابی به حضور رایانه فعال مراجعه کنید.
• رکورد جفت‌سازی دستگاه، قرارداد پایدار نقش تأییدشده است. چرخش توکن درون همان قرارداد باقی می‌ماند؛ نمی‌تواند گره جفت‌شده را به نقشی ارتقا دهد که تأیید جفت‌سازی هرگز اعطا نکرده است.
• node.pair.* (CLI: openclaw nodes pending/approve/reject/remove/rename) یک مخزن جداگانه جفت‌سازی گره تحت مالکیت Gateway است که سطح فرمان/قابلیت تأییدشده گره را در اتصال‌های مجدد ردیابی می‌کند. این مخزن احراز هویت انتقال را کنترل نمی‌کند — جفت‌سازی دستگاه این کار را انجام می‌دهد.
• openclaw nodes remove --node <id|name|ip> جفت‌سازی یک گره را حذف می‌کند. برای گره مبتنی بر دستگاه، نقش node دستگاه را در مخزن دستگاه‌های جفت‌شده لغو و نشست‌های دارای نقش گره آن دستگاه را قطع می‌کند: دستگاه چندنقشی سطر خود را حفظ می‌کند و فقط نقش node را از دست می‌دهد، درحالی‌که سطر دستگاه مختص گره حذف می‌شود. همچنین هر ورودی منطبق را از مخزن جداگانه جفت‌سازی گره پاک می‌کند. operator.pairing ممکن است سطرهای گره غیر‌اپراتور را روی دستگاه‌های دیگر حذف کند؛ فراخواننده دارای توکن دستگاه که نقش گره خودش را روی دستگاهی چندنقشی لغو می‌کند، علاوه‌براین به operator.admin نیاز دارد.
• دامنه تأیید از فرمان‌های اعلام‌شده درخواست در انتظار پیروی می‌کند:
  • درخواست بدون فرمان: operator.pairing
  • فرمان‌های غیر اجرایی گره: operator.pairing + operator.write
  • system.run / system.run.prepare / system.which: operator.pairing + operator.admin

ناهمخوانی نسخه و ترتیب ارتقا

WebSocket مربوط به Gateway کلاینت‌های گره احراز هویت‌شده را در یک بازه پروتکلی N-1 می‌پذیرد. بنابراین Gateway فعلی v4 گره‌های v3 را زمانی می‌پذیرد که اتصال هر دو role: "node" و client.mode: "node" را اعلام کند. نشست‌های اپراتور و رابط کاربری همچنان باید از پروتکل فعلی استفاده کنند.

برای ارتقای مرحله‌ای ناوگان، ابتدا Gateway و سپس هر گره را ارتقا دهید. گره N-1 هنگام ارتقا همچنان قابل مشاهده و مدیریت باقی می‌ماند؛ Gateway همراه با توصیه ارتقا، legacy node protocol accepted را ثبت می‌کند. جفت‌سازی، احراز هویت دستگاه، فهرست‌های مجاز فرمان و تأییدهای اجرا همچنان اعمال می‌شوند. قابلیت‌ها و فرمان‌های تحت مالکیت Plugin تا زمانی که گره به پروتکل فعلی ارتقا نیابد، پنهان می‌مانند. گره‌های قدیمی‌تر از N-1 پیش از اتصال مجدد به ارتقای خارج از باند نیاز دارند.

انتقال مستقیم HTTPS در watchOS به نسخه فعلی پروتکل نیاز دارد؛ پیش از فعال‌کردن حالت مستقیم، برنامه ساعت را همراه با Gateway به‌روزرسانی کنید.

میزبان گره راه‌دور (system.run)

زمانی از میزبان گره استفاده کنید که Gateway روی یک دستگاه اجرا می‌شود و می‌خواهید فرمان‌ها روی دستگاه دیگری اجرا شوند. مدل همچنان با Gateway ارتباط دارد؛ وقتی host=node انتخاب شده باشد، Gateway فراخوانی‌های exec را به میزبان گره هدایت می‌کند.

نکته تأیید:

• اجرای گره مبتنی بر تأیید، زمینه دقیق درخواست را مقید می‌کند. مسیر اجرا پیش از تأیید یک systemRunPlan متعارف آماده می‌کند؛ پس از اعطای تأیید، Gateway همان برنامه ذخیره‌شده را ارسال می‌کند، نه فیلدهای فرمان/cwd/نشست که فراخواننده بعداً ویرایش کرده باشد، و پیش از اجرا دایرکتوری کاری را دوباره اعتبارسنجی می‌کند.
• برای اجرای مستقیم فایل‌های پوسته/محیط اجرا، OpenClaw همچنین در حد امکان یک عملوند مشخص فایل محلی را مقید می‌کند و اگر آن فایل پیش از اجرا تغییر کند، اجرا را رد می‌کند.
• اگر OpenClaw نتواند برای یک فرمان مفسر/محیط اجرا دقیقاً یک فایل محلی مشخص را شناسایی کند، اجرای مبتنی بر تأیید رد می‌شود، به‌جای آنکه پوشش کامل محیط اجرا وانمود شود. برای معناشناسی گسترده‌تر مفسر از سندباکس، میزبان‌های جداگانه یا فهرست مجاز صریح و مورد اعتماد/گردش‌کار کامل استفاده کنید.

راه‌اندازی میزبان گره (پیش‌زمینه)

روی دستگاه گره:

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

node run همچنین --context-path (مسیر زمینه WS مربوط به Gateway)، --tls، --tls-fingerprint <sha256> و --node-id (بازنویسی شناسه نمونه کلاینت قدیمی؛ این کار جفت‌سازی را بازنشانی نمی‌کند) را می‌پذیرد.

Gateway راه‌دور از طریق تونل SSH (اتصال loopback)

اگر Gateway به loopback متصل باشد (gateway.bind=loopback، پیش‌فرض در حالت محلی)، میزبان‌های گره راه‌دور نمی‌توانند مستقیماً متصل شوند. یک تونل SSH ایجاد کنید و میزبان گره را به انتهای محلی تونل هدایت کنید.

مثال (میزبان گره -> میزبان Gateway):

# ترمینال A (در حال اجرا نگه دارید): هدایت 18790 محلی -> Gateway در 127.0.0.1:18789ssh -N -L 18790:127.0.0.1:18789 user@gateway-host # ترمینال B: توکن Gateway را صادر کنید و از طریق تونل متصل شویدexport OPENCLAW_GATEWAY_TOKEN="<gateway-token>"openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

نکات:

• openclaw node run از احراز هویت با توکن یا گذرواژه پشتیبانی می‌کند.
• متغیرهای محیطی ترجیح داده می‌شوند: OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD.
• گزینه جایگزین پیکربندی gateway.auth.token / gateway.auth.password است.
• در حالت محلی، میزبان گره عمداً gateway.remote.token / gateway.remote.password را نادیده می‌گیرد.
• در حالت راه‌دور، gateway.remote.token / gateway.remote.password طبق قواعد تقدم راه‌دور واجد شرایط هستند.
• اگر SecretRefهای فعال محلی gateway.auth.* پیکربندی شده اما حل‌نشده باشند، احراز هویت میزبان گره به‌صورت بسته شکست می‌خورد.
• حل احراز هویت میزبان گره فقط متغیرهای محیطی OPENCLAW_GATEWAY_* را می‌پذیرد.

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

openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"openclaw node startopenclaw node restart

node install همچنین --context-path، --tls، --tls-fingerprint، --node-id (فقط شناسه نمونه کلاینت قدیمی)، --runtime <node> (پیش‌فرض: گره) و --force برای نصب مجدد را می‌پذیرد. node status، node stop و node uninstall نیز در دسترس هستند.

جفت‌سازی و نام‌گذاری

روی میزبان Gateway:

openclaw devices listopenclaw devices approve <requestId>openclaw nodes status

اگر گره با جزئیات احراز هویت تغییریافته دوباره تلاش کرد، openclaw devices list را دوباره اجرا و requestId فعلی را تأیید کنید.

گزینه‌های نام‌گذاری:

• --display-name روی openclaw node run / openclaw node install (در سطر SQLite مشترک node_host_config در کنار شناسه نمونه کلاینت و فراداده اتصال Gateway پایدار می‌ماند).
• openclaw nodes rename --node <id|name|ip> --name "Build Node" (بازنویسی Gateway).

سرورهای MCP میزبانی‌شده روی گره

سرورهای MCP را روی دستگاه گره در openclaw.json پیکربندی کنید، نه روی Gateway:

{  nodeHost: {    mcp: {      servers: {        localDocs: {          command: "npx",          args: ["-y", "@modelcontextprotocol/server-filesystem", "/srv/docs"],          toolFilter: {            include: ["read_*", "search"],          },        },        internalApi: {          url: "https://mcp.internal.example/mcp",          transport: "streamable-http",          headers: {            Authorization: "Bearer ${INTERNAL_MCP_TOKEN}",          },        },      },    },  },}

میزبان گره بدون رابط گرافیکی این سرورها را راه‌اندازی می‌کند، ابزارهایشان را فهرست می‌کند و پس از اتصال توصیفگرها را منتشر می‌کند. فراخوانی ابزارها از طریق mcp.tools.call.v1 به همان گره بازمی‌گردند؛ Gateway به پیکربندی MCP متناظر یا یک Plugin جاوااسکریپت نیاز ندارد. سرورهای OAuth MCP در این مسیر v1 میزبانی‌شده روی گره پشتیبانی نمی‌شوند.

میزبان‌های گره فعلی، خانواده فرمان داخلی mcp.tools.call.v1 را هنگام جفت‌سازی اولیه خود اعلام می‌کنند، حتی اگر هیچ سرور MCP پیکربندی نشده باشد. گره‌ای که با نسخه قدیمی‌تر OpenClaw جفت شده است ممکن است پس از به‌روزرسانی میزبان گره، ارتقای یک‌باره سطح فرمان را درخواست کند. افزودن، حذف یا فیلترکردن سرورها پس از آن به جفت‌سازی مجدد نیاز ندارد، زیرا خانواده فرمان تأییدشده بدون تغییر است. برای اعمال تغییرات پیکربندی MCP گره، openclaw node run یا openclaw node restart را راه‌اندازی مجدد کنید؛ میزبان گره این پیکربندی را پایش نمی‌کند.

اپراتورهای Gateway می‌توانند همه ابزارهای قابل مشاهده برای عامل را که گره‌های جفت‌شده منتشر می‌کنند، از جمله ابزارهای MCP میزبانی‌شده روی گره، با gateway.nodes.pluginTools.enabled: false نادیده بگیرند. ردکردن دقیق فرمان‌ها مانند gateway.nodes.denyCommands: ["mcp.tools.call.v1"] نیز اجرا را مسدود می‌کند.

Skills میزبانی‌شده روی گره

Skills را در دایرکتوری فعال Skills مربوط به OpenClaw روی دستگاه گره نصب کنید؛ به‌طور پیش‌فرض ~/.openclaw/skills. ‏OPENCLAW_HOME، OPENCLAW_STATE_DIR و OPENCLAW_CONFIG_PATH این پروفایل فعال را جابه‌جا می‌کنند. OPENCLAW_STATE_DIR برای Skills تقدم دارد؛ در غیر این صورت، skills/ کنار مسیری است که openclaw config file چاپ می‌کند. میزبان گره بدون رابط گرافیکی پس از اتصال، فایل‌های معتبر SKILL.md را منتشر می‌کند و Gateway فقط تا زمانی که آن گره متصل باقی بماند، آن‌ها را به نماهای لحظه‌ای Skills عامل می‌افزاید. نام هر دایرکتوری Skills باید با فیلد frontmatter ‏name مطابقت داشته باشد تا مکان‌یاب انتزاعی گره بدون افزودن فیلد پروتکل دیگری به یک ورودی نگاشت شود.

جفت‌سازی اولیه نقش Node، انتشار Skills را تأیید می‌کند. افزودن، حذف یا تغییر Skills به جفت‌سازی دوباره یا تغییر پیکربندی Gateway نیاز ندارد. پس از تغییر فایل‌های Skills در Node، openclaw node run یا openclaw node restart را راه‌اندازی مجدد کنید؛ میزبان Node دایرکتوری Skills را پایش نمی‌کند.

ورودی‌های Skills میزبانی‌شده روی Node، Node خود را مشخص می‌کنند و محل اجرای خود را به‌همراه دارند. فایل‌های Skills، مسیرهای نسبی ارجاع‌شده و فایل‌های اجرایی روی همان Node باقی می‌مانند. عامل، محل اعلام‌شدهٔ node://.../SKILL.md را با ابزار عادی read می‌خواند. file_fetch مسیرهای مطلق Node را که اپراتور تأیید کرده است می‌پذیرد، نه مکان‌یاب‌های Skills در Node؛ محیط‌های اجرایی فاقد ابزار عادی خواندن می‌توانند در عوض cat SKILL.md را از طریق exec host=node node=<node-id> با دایرکتوری اعلام‌شدهٔ node://.../skills/<name> به‌عنوان workdir اجرا کنند. فایل‌ها و فایل‌های اجرایی ارجاع‌شده از همان مقصد exec و دایرکتوری کاری استفاده می‌کنند. میزبان Node آن مکان‌یاب را نسبت به دایرکتوری وضعیت فعال OpenClaw خود حل می‌کند؛ بنابراین مسیرهای نسبی روی Node حل می‌شوند، نه روی دستگاه Gateway. Node منتشرکننده باید system.run تأییدشده داشته باشد، و خط‌مشی exec عامل باید host=node را مجاز کند؛ در غیر این صورت، Skill از اسنپ‌شات آن عامل خارج می‌ماند.

برای توقف انتشار، nodeHost.skills.enabled: false را روی Node تنظیم کنید. اپراتورهای Gateway می‌توانند با gateway.nodes.skills.enabled: false، Skills همهٔ Nodeهای جفت‌شده را نادیده بگیرند.

وضعیت هویت بدون رابط گرافیکی

Node بدون رابط گرافیکی سه رکورد وضعیت جداگانه نگه می‌دارد:

• ~/.openclaw/state/openclaw.sqlite (node_host_config): شناسهٔ نمونهٔ کلاینت، نام نمایشی و فرادادهٔ اتصال Gateway.
• ~/.openclaw/identity/device.json: جفت‌کلید امضاشدهٔ دستگاه و شناسهٔ رمزنگاری‌شدهٔ دستگاه که از آن مشتق شده است.
• ~/.openclaw/identity/device-auth.json: توکن‌های احراز هویت دستگاه جفت‌شده که بر اساس شناسهٔ رمزنگاری‌شدهٔ دستگاه و نقش کلیدگذاری شده‌اند.

برای یک Node امضاشده، Gateway از شناسهٔ رمزنگاری‌شدهٔ دستگاه برای جفت‌سازی و مسیریابی Node استفاده می‌کند. شناسهٔ نمونهٔ کلاینت فقط فرادادهٔ اتصال است. بنابراین تغییر --node-id یا مهاجرت یک node.json بازنشسته، جفت‌سازی را بازنشانی نمی‌کند. برای روند پشتیبانی‌شدهٔ لغو و جفت‌سازی مجدد و یادداشت‌های ارتقا، به وضعیت هویت و جفت‌سازی مراجعه کنید.

قراردادن فرمان‌ها در فهرست مجاز

تأییدهای exec برای هر میزبان Node جداگانه هستند. ورودی‌های فهرست مجاز را از Gateway اضافه کنید:

openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"

تأییدها در ~/.openclaw/exec-approvals.json روی میزبان Node نگه‌داری می‌شوند.

هدایت exec به Node

پیش‌فرض‌ها را پیکربندی کنید (پیکربندی Gateway):

openclaw config set tools.exec.host nodeopenclaw config set tools.exec.security allowlistopenclaw config set tools.exec.node "<id-or-name>"

یا برای هر نشست:

/exec host=node security=allowlist node=<id-or-name>

پس از تنظیم، هر فراخوانی exec با host=node روی میزبان Node اجرا می‌شود (با رعایت فهرست مجاز/تأییدهای Node).

host=auto به‌طور ضمنی و خودکار Node را انتخاب نمی‌کند، اما درخواست صریح host=node برای هر فراخوانی از auto مجاز است. اگر می‌خواهید exec روی Node پیش‌فرض نشست باشد، tools.exec.host=node یا /exec host=node ... را صریحاً تنظیم کنید.

موارد مرتبط:

• CLI میزبان Node
• ابزار Exec
• تأییدهای Exec

استنتاج مدل محلی

یک Node دسکتاپ یا سرور می‌تواند مدل‌های دارای قابلیت گفت‌وگو را از سرور Ollama در حال اجرا روی همان Node ارائه کند. عامل‌ها از ابزار node_inference در Plugin مربوط به Ollama برای کشف مدل‌های نصب‌شده و اجرای یک پرامپت محدود از راه دور استفاده می‌کنند؛ Gateway به دسترسی مستقیم شبکه‌ای به Ollama نیاز ندارد. برای راه‌اندازی، فیلترکردن مدل و فرمان‌های راستی‌آزمایی مستقیم، به استنتاج محلی Ollama روی Node مراجعه کنید.

نشست‌ها و رونوشت‌های Codex

Plugin رسمی codex می‌تواند نشست‌های بایگانی‌نشدهٔ Codex را روی یک میزبان Node بدون رابط گرافیکی یا Node بومی macOS ارائه کند. ثبت کاتالوگ دیگر به supervision.enabled وابسته نیست؛ آن گزینه ابزارهای نظارتی در دسترس عامل را کنترل می‌کند. برای غیرفعال‌کردن کاتالوگ اپراتور و فرمان‌های کاتالوگ Node جفت‌شده، بدون غیرفعال‌کردن ارائه‌دهنده یا چارچوب اجرا، sessionCatalog.enabled: false را در پیکربندی Plugin مربوط به Codex تنظیم کنید. Plugin همچنان باید روی هر دو رایانه فعال باشد و تنظیم Node به‌منزلهٔ رضایت محلی باقی می‌ماند: فعال‌کردن فقط Gateway نمی‌تواند وضعیت Codex رایانه‌ای دیگر را بخواند.

Node فرمان‌های فقط‌خواندنی و نسخه‌بندی‌شدهٔ codex.appServer.threads.list.v1 و codex.appServer.thread.turns.list.v1 را اعلام می‌کند. یک میزبان Node بومی که Codex CLI را در دسترس دارد، codex.terminal.resume.v1 را نیز اعلام می‌کند. وقتی این فرمان‌ها برای نخستین بار ظاهر می‌شوند، ارتقای جفت‌سازی Node را تأیید کنید. Gateway آن‌ها را از طریق خط‌مشی عادی Node در Plugin فراخوانی می‌کند و خرابی‌ها را بر اساس میزبان ایزوله می‌کند.

ردیف‌های Node جفت‌شده به‌صورت یک گروه Codex در نوار کناری عادی نشست‌ها ظاهر می‌شوند. به‌طور پیش‌فرض، انتخاب یک ردیف، پنل عادی گفت‌وگو را باز می‌کند و رونوشت ماندگار آن را از طریق فراخوانی‌های محدود و صفحه‌بندی‌شده با مکان‌نمای thread/turns/list با نگاشت کامل موارد می‌خواند. برای اجرای codex resume <thread-id> در ترمینال اپراتور روی رایانهٔ مالک نشست، از منوی ردیف، سرصفحهٔ نمایشگر یا ترجیح بازکردن نشست‌های Codex/Claude در استفاده کنید. مسیر ترمینال Node جفت‌شده یک رلهٔ PTY فهرست‌مجاز است که Plugin مربوط به Codex مالک آن است، نه اجرای دلخواه فرمان روی Node.

این رله قراردادهای کامل ادامهٔ چارچوب اجرای OpenClaw و مالکیت بایگانی را ارائه نمی‌کند. بنابراین ادامه و بایگانی برای ردیف‌های راه دور در دسترس نیستند. روی رایانهٔ Gateway، ردیف‌های ذخیره‌شده و غیرفعال می‌توانند یک شاخهٔ گفت‌وگوی مجزا و قفل‌شده به مدل را آغاز کنند. هرکدام فقط پس از تأیید اپراتور مبنی بر اینکه هیچ کلاینت Codex دیگری از آن استفاده نمی‌کند، قابل بایگانی است؛ فعالیت زندهٔ یک ردیف ذخیره‌شده همچنان نامشخص می‌ماند. ردیف‌های فعال نمی‌توانند شاخه بسازند یا بایگانی شوند.

برای راه‌اندازی، صفحه‌بندی، ادامهٔ محلی و مرز امنیتی فراداده، به نظارت بر نشست‌های Codex مراجعه کنید.

نشست‌ها و رونوشت‌های Claude

Plugin همراه anthropic به‌طور پیش‌فرض نشست‌های بایگانی‌نشدهٔ Claude CLI و Claude Desktop را روی Gateway و Nodeهای جفت‌شده کشف می‌کند. برای غیرفعال‌کردن کاتالوگ اپراتور و فرمان‌های کاتالوگ Node جفت‌شده، بدون غیرفعال‌کردن مدل‌های Anthropic یا بک‌اند Claude CLI، plugins.entries.anthropic.config.sessionCatalog.enabled: false را تنظیم کنید. یک Node راه دور برنامهٔ macOS، هنگامی که Plugin مربوط به Anthropic فعال باشد و ~/.claude/projects/ وجود داشته باشد، anthropic.claude.sessions.list.v1 و anthropic.claude.sessions.read.v1 را اعلام می‌کند. وقتی این فرمان‌ها برای نخستین بار ظاهر می‌شوند، ارتقای جفت‌سازی Node را تأیید کنید.

یک میزبان Node بومی که Claude CLI را در دسترس دارد، anthropic.claude.terminal.resume.v1 را نیز اعلام می‌کند. ردیف‌های واجد شرایط CLI و Desktop می‌توانند claude --resume <session-id> را در ترمینال اپراتور روی میزبان مالک خود باز کنند. این کار تصاحب نشست بومی است؛ برخلاف پذیرش توسط OpenClaw، ابتدا از نشست Claude شاخه‌ای ایجاد نمی‌کند.

کاتالوگ، رکوردهای معتبر نمایهٔ پروژهٔ Claude CLI را با یک پیشوند فرادادهٔ محدود از فایل‌های JSONL کنونی sdk-cli ترکیب می‌کند. فرادادهٔ محلی Claude Desktop عنوان‌ها و وضعیت بایگانی Desktop را فراهم می‌کند. وقتی هر دو منبع به شناسهٔ یکسان نشست Claude Code اشاره کنند، فرادادهٔ Desktop اولویت دارد؛ رونوشت‌های مختص CLI همچنان قابل مشاهده‌اند، زیرا CLI پرچم بایگانی ندارد. خواندن رونوشت‌ها از مکان‌نماهای مبهمِ افست بایتی و خواندن محدود و روبه‌عقب فایل استفاده می‌کند؛ بنابراین انتخاب یک نشست بزرگ یا بارگیری صفحه‌ای قدیمی‌تر، کل تاریخچهٔ JSONL را در یک پاسخ Gateway نمی‌خواند.

فرمان‌های فهرست و خواندن فقط‌خواندنی هستند. آن‌ها فرادادهٔ کاتالوگ و محتوای رونوشت را فقط از طریق روش‌های عمومی sessions.catalog.list و sessions.catalog.read در اختیار یک اتصال احرازهویت‌شدهٔ اپراتور دارای operator.write قرار می‌دهند. یک ردیف Claude CLI محلی Gateway را می‌توان از نگارشگر عادی گفت‌وگو پذیرفت: OpenClaw تاریخچهٔ قابل‌مشاهده و محدود را وارد می‌کند، در نوبت نخست با --fork-session از سر می‌گیرد و رونوشت مبدأ را دست‌نخورده باقی می‌گذارد.

یک میزبان Node بدون رابط گرافیکی می‌تواند جریان ادامهٔ مشابه را به‌صورت اختیاری فعال کند:

{  nodeHost: {    agentRuns: {      claude: { enabled: true },    },  },}

Node فقط زمانی agent.cli.claude.run.v1 را اعلام می‌کند که این تنظیم محلی Node فعال باشد و فایل اجرایی claude روی آن Node قابل حل باشد. Gateway نمی‌تواند آن را از راه دور فعال کند. فرمان همچنین از خط‌مشی تأیید exec موجود Node عبور می‌کند. وقتی هر سه فرمان Claude اعلام شده باشند و خط‌مشی فرمان Node در Gateway آن‌ها را مجاز کند، یک ردیف Claude CLI روی آن Node قابل ادامه می‌شود: OpenClaw تاریخچهٔ محدود را وارد می‌کند، نشست پذیرفته‌شده را به Node و دایرکتوری کاری گزارش‌شده در کاتالوگ آن متصل می‌کند و هر نوبت یک‌مرحله‌ای claude -p را در آنجا اجرا می‌کند. نوبت نخست همچنان از --fork-session استفاده می‌کند و رونوشت مبدأ را حفظ می‌کند.

نوبت‌های اجراشده روی Node از پیش‌فرض‌های Claude همان Node استفاده می‌کنند. در v1، آن‌ها پیکربندی MCP حلقهٔ بازگشت Gateway یا Plugin مربوط به Skills در Gateway را دریافت نمی‌کنند، نمی‌توانند از رونوشت Gateway دوباره مقداردهی اولیه شوند و پیوست‌ها و تصاویر را رد می‌کنند. ردیف‌های Claude Desktop و Nodeهایی که فرمان اجرا را اعلام نمی‌کنند، فقط قابل مشاهده باقی می‌مانند. Node برنامهٔ macOS هنوز این فرمان را اعلام نمی‌کند؛ بنابراین ردیف‌های آن فقط قابل مشاهده باقی می‌مانند.

برای رفتار رابط کاربری کنترل و منابع ذخیره‌سازی، به Anthropic: نشست‌های Claude میان رایانه‌ها مراجعه کنید.

نشست‌های OpenCode و Pi

Pluginهای همراه OpenCode و ACPX نیز کاتالوگ‌های فقط‌خواندنی نشست‌های بومی را روی Gateway و Nodeهای جفت‌شده کشف می‌کنند. یک Node هنگامی که CLI مربوط به opencode نصب باشد، opencode.sessions.list.v1 / opencode.sessions.read.v1 را اعلام می‌کند و هنگامی که دایرکتوری نشست Pi وجود داشته باشد، acpx.pi.sessions.list.v1 / acpx.pi.sessions.read.v1 را اعلام می‌کند. وقتی فرمان‌های جدید برای نخستین بار ظاهر می‌شوند، ارتقای جفت‌سازی Node را تأیید کنید. وقتی CLI منطبق نیز در دسترس باشد، Node opencode.terminal.resume.v1 یا acpx.pi.terminal.resume.v1 را اضافه می‌کند؛ سپس منوی ردیف و سرصفحهٔ نمایشگر موجود می‌توانند نشست انتخاب‌شده را با opencode --session <id> یا pi --session <id> در ترمینال مالک آن دوباره باز کنند.

OpenCode از طریق سطح رسمی JSON/صدور CLI خود می‌خواند. Pi مخزن مستندشدهٔ نشست JSONL خود را می‌خواند، از جمله دایرکتوری‌های نشست پروژه و سراسری settings.json به‌همراه جایگزین‌های PI_CODING_AGENT_DIR و PI_CODING_AGENT_SESSION_DIR. هر دو کاتالوگ به‌طور پیش‌فرض فعال هستند؛ آن‌ها را در رابط وب زیر Config > Plugins خاموش کنید.

ازسرگیری ترمینال از دایرکتوری کاری ذخیره‌شدهٔ نشست و همان رلهٔ دوطرفهٔ PTY فهرست‌مجاز Codex و Claude استفاده می‌کند. این قابلیت اجرای دلخواه فرمان روی Node را ارائه نمی‌کند.

بارگذاری فایل در ترمینال

رابط کاربری کنترل می‌تواند فایل‌ها را به یک ترمینال باز Node جفت‌شده بکشد. میزبان Node بومی فرمان مختص مدیر terminal.upload را اعلام می‌کند؛ وقتی نخستین بار ظاهر شد، ارتقای جفت‌سازی را تأیید کنید. هر فایل به 16 MiB محدود است، در یک دایرکتوری موقت خصوصی روی همان Node قرار می‌گیرد و بدون اجراشدن، به‌شکل مسیری با نقل‌قول‌گذاری پوسته به ترمینال بازگردانده می‌شود.

درج مسیر از PowerShell، ‏cmd.exe و پوسته‌های POSIX شناخته‌شده (sh، Bash، Dash، Ash، Ksh، Zsh و Fish)، از جمله Git Bash در Windows، پشتیبانی می‌کند. سایر جایگزین‌های پوسته رد می‌شوند، زیرا قواعد نقل‌قول‌گذاری آن‌ها را نمی‌توان با اطمینان استنباط کرد؛ برای مسیرهای بومی WSL، میزبان Node را داخل WSL اجرا کنید. مسیرهای cmd.exe شامل % یا ! نیز رد می‌شوند، زیرا آن پوسته این نویسه‌ها را حتی داخل نقل‌قول دوتایی بسط می‌دهد.

فراخوانی فرمان‌ها

سطح پایین (RPC خام):

openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'

nodes invoke، ‏system.run و system.run.prepare را مسدود می‌کند؛ این فرمان‌ها فقط از طریق ابزار exec با host=node اجرا می‌شوند (بالا را ببینید). برای جریان‌های کاری رایج «دادن پیوست MEDIA به عامل» راهنماهای سطح بالاتری وجود دارد (بوم، دوربین، صفحه‌نمایش، موقعیت مکانی، در ادامه).

فرمان‌های جریانی و طولانی‌مدت Node از رویدادهای افزایشی node.invoke.progress استفاده می‌کنند. هر رویداد شامل شناسهٔ فراخوانی، یک شمارهٔ توالی با مبدأ صفر و یک قطعهٔ متنی محدودشده با UTF-8 است؛ Gateway قطعه‌ها را پیش از تحویل به فراخواننده مرتب می‌کند. node.invoke.result موجود همچنان تنها پاسخ پایانی است. فراخواننده‌های جریانی می‌توانند یک مهلت عدم فعالیت تنظیم کنند که با نخستین رویداد پیشرفت آغاز می‌شود و پس از پیشرفت‌های بعدی بازنشانی می‌شود، درحالی‌که مهلت سخت جداگانهٔ فراخوانی را هنگام تأیید و اجرا حفظ می‌کند. نتیجه، مهلت سخت، مهلت عدم فعالیت و قطع اتصال Node، همگی وضعیت جریان معلق را حذف می‌کنند. لغو از سوی فراخواننده، node.invoke.cancel را منتشر می‌کند؛ سپس میزبان Node درخت فرایند متناظر را خاتمه می‌دهد. فرمان‌های درخواست/پاسخ موجود بدون تغییرند.

خط‌مشی فرمان

فرمان‌های Node پیش از فراخوانی باید از دو دروازه عبور کنند:

1. Node باید فرمان را در فرادادهٔ اتصال احرازشدهٔ خود اعلام کند (connect.commands).
2. فهرست مجاز Gateway که از پلتفرم و تأیید مشتق شده است باید فرمان اعلام‌شده را در بر بگیرد.

فهرست‌های مجاز پیش‌فرض بر اساس پلتفرم (پیش از پیش‌فرض‌های Plugin و بازنویسی‌های allowCommands/denyCommands):

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

فرمان‌های canvas.* (canvas.present, canvas.hide, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*) یک پیش‌فرض Plugin در iOS، Android، macOS، Windows، Linux و پلتفرم‌های ناشناخته هستند. Nodeهای Linux آن‌ها را تنها هنگامی اعلام می‌کنند که سوکت محلی Canvas برنامهٔ دسکتاپ موجود باشد. همهٔ فرمان‌های Canvas در iOS به حضور در پیش‌زمینه محدود هستند.

talk.ptt.start، talk.ptt.stop، talk.ptt.cancel و talk.ptt.once به‌صورت پیش‌فرض برای هر Node که قابلیت talk را تبلیغ کند یا فرمان‌های talk.* را اعلام کند، مستقل از برچسب پلتفرم مجاز هستند.

فرمان‌های میزبان دسکتاپ (system.run، system.run.prepare، system.which، browser.proxy، mcp.tools.call.v1 و screen.snapshot در macOS/Windows) بخشی از جدول ایستای پیش‌فرض پلتفرم در بالا نیستند. پس از آنکه اپراتور یک درخواست جفت‌سازی را که آن‌ها را اعلام می‌کند تأیید کند، این فرمان‌ها در دسترس قرار می‌گیرند و سپس مجموعه‌فرمان‌های تأییدشدهٔ Node آن‌ها را هنگام اتصال مجدد حفظ می‌کند.

فرمان‌های خطرناک یا دارای حساسیت بالای حریم خصوصی، حتی اگر Node آن‌ها را اعلام کند، همچنان به فعال‌سازی صریح با gateway.nodes.allowCommands نیاز دارند: camera.snap، camera.clip، screen.record، computer.act، contacts.add، calendar.add، reminders.add، health.summary، sms.send، sms.search. gateway.nodes.denyCommands همیشه بر پیش‌فرض‌ها و ورودی‌های اضافی فهرست مجاز اولویت دارد. برای دروازهٔ رضایت iPhone به خلاصه‌های HealthKit و برای دروازه‌های اضافی macOS، خط‌مشی ابزار و مسلح‌سازی پیرامون ورودی دسکتاپ به استفاده از رایانه مراجعه کنید.

فرمان‌های Node متعلق به Plugin می‌توانند یک خط‌مشی فراخوانی Node در Gateway اضافه کنند. این خط‌مشی پس از بررسی فهرست مجاز و پیش از ارسال به Node اجرا می‌شود، بنابراین node.invoke خام، کمک‌کننده‌های CLI و ابزارهای اختصاصی عامل، همگی مرز مجوز یکسان Plugin را به اشتراک می‌گذارند. فرمان‌های خطرناک Node متعلق به Plugin همچنان به فعال‌سازی صریح gateway.nodes.allowCommands نیاز دارند.

پس از آنکه Node فهرست فرمان‌های اعلام‌شدهٔ خود را تغییر داد، جفت‌سازی قدیمی دستگاه را رد و درخواست جدید را تأیید کنید تا Gateway تصویر لحظه‌ای به‌روزشدهٔ فرمان‌ها را ذخیره کند.

پیکربندی (openclaw.json)

تنظیمات مرتبط با Node زیر gateway.nodes و tools.exec قرار دارند:

{  gateway: {    nodes: {      // جفت‌سازی بار اول Node از شبکه‌های مورد اعتماد (فهرست CIDR) را خودکار تأیید کن.      // در صورت تنظیم‌نبودن غیرفعال است. فقط برای درخواست‌های بار اول role:node      // بدون scope درخواستی اعمال می‌شود؛ ارتقاها را خودکار تأیید نمی‌کند.      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],        // تأیید خودکار اعتبارسنجی‌شده با SSH (پیش‌فرض: فعال). جفت‌سازی بار اول        // Node را با تطابق دقیق کلید دستگاه که از طریق SSH بازخوانی شده است تأیید می‌کند.        sshVerify: true,      },      // به ابزارهای Plugin قابل مشاهده برای عامل که Nodeهای جفت‌شده منتشر می‌کنند اعتماد کن (پیش‌فرض: true).      pluginTools: {        enabled: true,      },      // فرمان‌های خطرناک/دارای حساسیت بالای حریم خصوصی Node را فعال کن (camera.snap و غیره).      allowCommands: ["camera.snap", "screen.record"],      // نام دقیق فرمان‌ها را مسدود کن، حتی اگر پیش‌فرض‌ها یا allowCommands شامل آن‌ها باشند.      denyCommands: ["camera.clip"],    },  },  tools: {    exec: {      // میزبان پیش‌فرض exec: مقدار "node" همهٔ فراخوانی‌های exec را به یک Node جفت‌شده هدایت می‌کند.      host: "node",      // حالت امنیتی برای exec روی Node: فقط فرمان‌های تأییدشده/موجود در فهرست مجاز را اجازه بده.      security: "allowlist",      // exec را به یک Node مشخص (شناسه یا نام) مقید کن. برای اجازه‌دادن به هر Node حذفش کن.      node: "build-node",    },  },}

از نام دقیق فرمان‌های Node استفاده کنید. denyCommands یک فرمان را حذف می‌کند، حتی اگر یک پیش‌فرض پلتفرم یا ورودی allowCommands در حالت عادی آن را مجاز کند. Nodeهای جفت‌شده ممکن است به‌صورت پیش‌فرض توصیف‌گرهای ابزار Plugin قابل مشاهده برای عامل را منتشر کنند، اما فرمان هر توصیف‌گر همچنان باید در سطح فرمان‌های تأییدشدهٔ Node باشد. برای نادیده‌گرفتن همهٔ این توصیف‌گرها، gateway.nodes.pluginTools.enabled: false را تنظیم کنید. برای جزئیات فیلدهای جفت‌سازی Node در Gateway و خط‌مشی فرمان، به مرجع پیکربندی Gateway مراجعه کنید.

بازنویسی Node اجرای مخصوص هر عامل:

{  agents: {    list: [      {        id: "main",        tools: { exec: { node: "build-node" } },      },    ],  },}

نماگرفت‌ها (تصاویر لحظه‌ای Canvas)

اگر Node در حال نمایش Canvas (WebView) باشد، canvas.snapshot مقدار { format, base64 } را برمی‌گرداند.

کمک‌کنندهٔ CLI (در یک فایل موقت می‌نویسد و مسیر ذخیره‌شده را چاپ می‌کند):

openclaw nodes canvas snapshot --node <idOrNameOrIp> --format pngopenclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

کنترل‌های Canvas

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.comopenclaw nodes canvas hide --node <idOrNameOrIp>openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"

نکته‌ها:

• canvas present در Nodeهایی که از مسیرهای محلی پشتیبانی می‌کنند، URLها یا مسیرهای فایل محلی (--target) و نیز --x/--y/--width/--height اختیاری برای موقعیت‌دهی را می‌پذیرد. Canvas در Linux، URLهای HTTP(S) یا رندرکنندهٔ A2UI همراه خود را می‌پذیرد.
• canvas eval کد JS درون‌خطی (--js) یا یک آرگومان موقعیتی را می‌پذیرد.

A2UI (Canvas)

openclaw nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonlopenclaw nodes canvas a2ui reset --node <idOrNameOrIp>

نکته‌ها:

• Nodeهای موبایل و دسکتاپ Linux برای رندر دارای قابلیت کنش، از یک صفحهٔ A2UI همراه و متعلق به برنامه استفاده می‌کنند.
• فقط JSONL مربوط به A2UI v0.8 پشتیبانی می‌شود (v0.9/createSurface رد می‌شود).
• iOS و Android صفحه‌های راه‌دور Gateway Canvas را رندر می‌کنند، اما کنش‌های دکمهٔ A2UI فقط از صفحهٔ A2UI همراه و متعلق به برنامه ارسال می‌شوند. صفحه‌های HTTP/HTTPS مربوط به A2UI که Gateway میزبانی می‌کند، در این کلاینت‌های موبایل فقط قابل رندر هستند.
• macOS می‌تواند کنش‌ها را از صفحهٔ دقیق A2UI در Gateway که به دامنهٔ قابلیت محدود است و برنامه آن را انتخاب کرده، ارسال کند. دیگر صفحه‌های HTTP/HTTPS فقط قابل رندر باقی می‌مانند.
• Linux کنش‌ها را فقط از صفحهٔ A2UI همراه ارسال می‌کند. دیگر صفحه‌های HTTP/HTTPS فقط قابل رندر باقی می‌مانند و یک Node بدون رابط گرافیکی Linux که برنامهٔ دسکتاپ را ندارد، Canvas را تبلیغ نمی‌کند.

عکس‌ها + ویدئوها (دوربین Node)

عکس‌ها (jpg):

openclaw nodes camera list --node <idOrNameOrIp>openclaw nodes camera snap --node <idOrNameOrIp>            # پیش‌فرض: هر دو جهت دوربین (2 خط MEDIA)openclaw nodes camera snap --node <idOrNameOrIp> --facing frontopenclaw nodes camera snap --node <idOrNameOrIp> --device-id <id> --max-width 1200 --quality 0.9 --delay-ms 2000

کلیپ‌های ویدئویی (mp4):

openclaw nodes camera clip --node <idOrNameOrIp> --duration 10sopenclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

نکته‌ها:

• برای canvas.* و camera.*، Node باید در پیش‌زمینه باشد (فراخوانی‌های پس‌زمینه NODE_BACKGROUND_UNAVAILABLE را برمی‌گردانند).
• Nodeها مدت کلیپ را محدود می‌کنند تا بار base64 قابل مدیریت بماند (برای محدودیت‌های دقیق هر پلتفرم، ضبط دوربین را ببینید). ابزار عامل nodes همچنین مقدار درخواستی durationMs را پیش از ارسال فراخوانی به 300000 (5 دقیقه) محدود می‌کند؛ خود Node محدودیت سخت‌گیرانه‌تر را اعمال می‌کند.
• Android در صورت امکان برای مجوزهای CAMERA/RECORD_AUDIO درخواست نمایش می‌دهد؛ مجوزهای ردشده با *_PERMISSION_REQUIRED ناموفق می‌شوند.

ضبط‌های صفحه (Nodeها)

Nodeهای پشتیبانی‌شده screen.record (mp4) را ارائه می‌کنند. نمونه:

openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

نکته‌ها:

• دردسترس‌بودن screen.record به پلتفرم Node بستگی دارد.
• ابزار عامل nodes مقدار درخواستی durationMs را به 300000 (5 دقیقه) محدود می‌کند؛ ممکن است Node برای محدودکردن محتوای بازگشتی، محدودیت سخت‌گیرانه‌تری اعمال کند.
• --no-audio ضبط میکروفون را در پلتفرم‌های پشتیبانی‌شده غیرفعال می‌کند.
• هنگامی که چند صفحه‌نمایش دردسترس است، برای انتخاب یک صفحه‌نمایش از --screen <index> استفاده کنید (0 = اصلی).

موقعیت مکانی (Nodeها)

وقتی «موقعیت مکانی» در تنظیمات فعال باشد، Nodeها location.get را ارائه می‌کنند.

ابزار کمکی CLI:

openclaw nodes location get --node <idOrNameOrIp>openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

نکته‌ها:

• موقعیت مکانی به‌طور پیش‌فرض غیرفعال است.
• «همیشه» به مجوز سیستم نیاز دارد؛ واکشی در پس‌زمینه بر مبنای بهترین تلاش انجام می‌شود.
• پاسخ شامل عرض/طول جغرافیایی، دقت (متر) و مُهر زمانی است.
• شکل کامل پارامتر/پاسخ و کدهای خطا: فرمان موقعیت مکانی.

پیامک (Nodeهای Android)

وقتی کاربر مجوز SMS را اعطا کند و دستگاه از تلفن همراه پشتیبانی کند، Nodeهای Android می‌توانند sms.send و sms.search را ارائه کنند. هر دو فرمان به‌طور پیش‌فرض خطرناک‌اند: پیش از امکان فراخوانی آن‌ها، گرداننده Gateway باید آن‌ها را نیز به gateway.nodes.allowCommands اضافه کند (سیاست فرمان را ببینید).

برای جست‌وجوی فقط‌خواندنی پیامک، در openclaw.json صراحتاً آن را فعال کنید:

{  gateway: {    nodes: {      allowCommands: ["sms.search"],    },  },}

تنها زمانی sms.send را جداگانه اضافه کنید که Node باید امکان ارسال پیام را نیز داشته باشد. مجوز Android و مجوزدهی فرمان Gateway مستقل از یکدیگرند؛ اعطای مجوز تلفن، سیاست Gateway را ویرایش نمی‌کند.

فراخوانی سطح پایین:

openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'

نکته‌ها:

• ممکن است sms.search پیش از اعطای READ_SMS اعلام شود تا فراخوانی بتواند یک عیب‌یابی مجوز برگرداند؛ خواندن پیام‌ها همچنان به آن مجوز Android نیاز دارد.
• دستگاه‌های صرفاً Wi-Fi که قابلیت تلفن همراه ندارند، sms.send را اعلام نمی‌کنند.
• خطای requires explicit gateway.nodes.allowCommands opt-in به این معناست که تلفن فرمان را اعلام کرده، اما گرداننده Gateway آن را مجاز نکرده است.

فرمان‌های دستگاه و داده‌های شخصی

Nodeهای iOS و Android چندین فرمان داده‌ای فقط‌خواندنی را به‌طور پیش‌فرض اعلام می‌کنند (جدول سیاست فرمان را ببینید)؛ Android علاوه بر این، خانواده بزرگ‌تری را ارائه می‌کند که تنظیمات درون‌برنامه‌ای خودش آن را کنترل می‌کند.

خانواده‌های موجود:

• device.status، device.info — iOS، Android، Windows.
• device.permissions، device.health، device.apps — فقط Android؛ device.apps مستلزم فعال‌بودن اشتراک‌گذاری برنامه‌های نصب‌شده در تنظیمات Android است و به‌طور پیش‌فرض برنامه‌های قابل‌مشاهده در راه‌انداز را برمی‌گرداند.
• notifications.list، notifications.actions — فقط Android.
• photos.latest — iOS، Android.
• contacts.search — iOS، Android (به‌طور پیش‌فرض فقط‌خواندنی)؛ contacts.add خطرناک است و به gateway.nodes.allowCommands نیاز دارد.
• calendar.events — iOS، Android (به‌طور پیش‌فرض فقط‌خواندنی)؛ calendar.add خطرناک است و به gateway.nodes.allowCommands نیاز دارد.
• reminders.list — iOS، Android (به‌طور پیش‌فرض فقط‌خواندنی)؛ reminders.add خطرناک است و به gateway.nodes.allowCommands نیاز دارد.
• callLog.search — فقط Android.
• motion.activity، motion.pedometer — iOS، Android؛ براساس حسگرهای موجود با قابلیت محدود می‌شود.

نمونه فراخوانی‌ها:

openclaw nodes invoke --node <idOrNameOrIp> --command device.status --params '{}'openclaw nodes invoke --node <idOrNameOrIp> --command device.apps --params '{"limit":10}'openclaw nodes invoke --node <idOrNameOrIp> --command notifications.list --params '{}'openclaw nodes invoke --node <idOrNameOrIp> --command photos.latest --params '{"limit":1}'

فرمان‌های سیستم (میزبان Node / Node مک)

Node در macOS، system.run، system.which، system.notify و system.execApprovals.get/set را ارائه می‌کند. میزبان Node بدون رابط کاربری، system.run.prepare، system.run، system.which و system.execApprovals.get/set را ارائه می‌کند.

نمونه‌ها:

openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"bins":["git"]}'

نکته‌ها:

• system.run خروجی استاندارد/خطای استاندارد/کد خروج را در محتوای پاسخ برمی‌گرداند.
• اجرای پوسته اکنون از ابزار exec همراه با host=node عبور می‌کند؛ nodes همچنان سطح RPC مستقیم برای فرمان‌های صریح Node است.
• nodes invoke، system.run یا system.run.prepare را ارائه نمی‌کند؛ آن‌ها فقط در مسیر exec باقی می‌مانند.
• مسیر exec پیش از تأیید، یک systemRunPlan استاندارد آماده می‌کند. پس از اعطای تأیید، Gateway همان طرح ذخیره‌شده را ارسال می‌کند، نه فیلدهای فرمان/cwd/نشست که فراخواننده بعداً ویرایش کرده باشد.
• system.notify وضعیت مجوز اعلان در برنامه macOS را رعایت می‌کند؛ از --priority <passive|active|timeSensitive> و --delivery <system|overlay|auto> پشتیبانی می‌کند.
• فراداده ناشناخته platform / deviceFamily مربوط به Node از یک فهرست مجاز پیش‌فرض محافظه‌کارانه استفاده می‌کند که system.run و system.which را مستثنا می‌کند. اگر عمداً به این فرمان‌ها برای پلتفرمی ناشناخته نیاز دارید، آن‌ها را صراحتاً از طریق gateway.nodes.allowCommands اضافه کنید.
• system.run از --cwd، --env KEY=VAL، --command-timeout و --needs-screen-recording پشتیبانی می‌کند.
• برای پوشش‌دهنده‌های پوسته (bash|sh|zsh ... -c/-lc)، مقادیر --env محدود به درخواست، به یک فهرست مجاز صریح (TERM، LANG، LC_*، COLORTERM، NO_COLOR، FORCE_COLOR) کاهش می‌یابند.
• برای تصمیم‌های «همیشه مجاز» در حالت فهرست مجاز، پوشش‌دهنده‌های ارسال شناخته‌شده (env، flock، nice، nohup، stdbuf، timeout) به‌جای مسیرهای پوشش‌دهنده، مسیرهای فایل اجرایی داخلی را ماندگار می‌کنند. اگر بازکردن پوشش ایمن نباشد، هیچ ورودی فهرست مجازی به‌طور خودکار ماندگار نمی‌شود.
• در میزبان‌های Node ویندوز در حالت فهرست مجاز، اجراهای پوشش‌دهنده پوسته از طریق cmd.exe /c نیازمند تأییدند (صرف وجود ورودی فهرست مجاز، شکل پوشش‌دهنده را خودکار مجاز نمی‌کند).
• میزبان‌های Node بازنویسی‌های PATH را در --env نادیده می‌گیرند و پیش از اجرای فرمان، مجموعه بزرگ و نگه‌داری‌شده‌ای از متغیرهای آغازین مفسر/پوسته (برای نمونه NODE_OPTIONS، PYTHONPATH، BASH_ENV، DYLD_*، LD_*) را حذف می‌کنند. اگر به ورودی‌های اضافی PATH نیاز دارید، به‌جای ارسال PATH از طریق --env، محیط سرویس میزبان Node را پیکربندی کنید (یا ابزارها را در مکان‌های استاندارد نصب کنید).
• در حالت Node در macOS، system.run با تأییدهای exec در برنامه macOS کنترل می‌شود (Settings → Exec approvals). حالت‌های درخواست/فهرست مجاز/کامل مانند میزبان Node بدون رابط کاربری رفتار می‌کنند؛ درخواست‌های ردشده SYSTEM_RUN_DENIED را برمی‌گردانند.
• در میزبان Node بدون رابط کاربری، system.run با تأییدهای exec (~/.openclaw/exec-approvals.json) کنترل می‌شود؛ به‌طور خاص در macOS، متغیرهای محیطی مسیریابی میزبان exec را در بخش میزبان Node بدون رابط کاربری در ادامه ببینید.

اتصال Node برای exec

وقتی چند Node دردسترس است، می‌توانید exec را به یک Node مشخص متصل کنید. این کار Node پیش‌فرض برای exec host=node را تعیین می‌کند (و می‌توان آن را برای هر عامل بازنویسی کرد).

پیش‌فرض سراسری:

openclaw config set tools.exec.node "node-id-or-name"

بازنویسی برای هر عامل:

openclaw config get agents.listopenclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"

برای مجازکردن هر Node، مقدار را حذف کنید:

openclaw config unset tools.exec.nodeopenclaw config unset 'agents.list[0].tools.exec.node'

نگاشت مجوزها

Nodeها ممکن است در node.list / node.describe یک نگاشت permissions داشته باشند که کلید آن نام مجوز (برای نمونه screenRecording، accessibility، location) و مقدار آن بولی است (true = اعطاشده).

میزبان Node بدون رابط کاربری (چندسکویی)

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

آن را راه‌اندازی کنید:

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

نکته‌ها:

• همچنان جفت‌سازی لازم است (Gateway یک درخواست جفت‌سازی دستگاه نشان می‌دهد).
• فراداده نمونه کلاینت، هویت امضاشده دستگاه و احراز هویت جفت‌سازی از فایل‌های جداگانه استفاده می‌کنند؛ وضعیت هویت بدون رابط کاربری را ببینید.
• تأییدهای exec به‌صورت محلی از طریق ~/.openclaw/exec-approvals.json اعمال می‌شوند (تأییدهای exec را ببینید).
• در macOS، میزبان Node بدون رابط کاربری به‌طور پیش‌فرض system.run را به‌صورت محلی اجرا می‌کند. برای مسیریابی system.run از طریق میزبان exec برنامه همراه، OPENCLAW_NODE_EXEC_HOST=app را تنظیم کنید؛ برای الزامی‌کردن میزبان برنامه و توقف ایمن در صورت دردسترس‌نبودن آن، OPENCLAW_NODE_EXEC_FALLBACK=0 را اضافه کنید.
• وقتی WebSocket متعلق به Gateway از TLS استفاده می‌کند، --tls / --tls-fingerprint را اضافه کنید.

حالت Node مک

• برنامه نوار منوی macOS به‌عنوان یک Node به سرور WebSocket متعلق به Gateway متصل می‌شود (بنابراین openclaw nodes … روی این مک کار می‌کند).
• در حالت دوردست، برنامه یک تونل SSH برای درگاه Gateway باز می‌کند و به localhost متصل می‌شود.