​

Nodes

• Nodes هي أجهزة طرفية وليست بوابات. فهي لا تشغّل خدمة gateway.
• تصل رسائل Telegram/WhatsApp/إلخ إلى gateway، وليس إلى nodes.
• دليل استكشاف الأخطاء وإصلاحها: /nodes/troubleshooting

​

الاقتران + الحالة

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

• يعلّم nodes status العقدة على أنها مقترنة عندما تتضمن أدوار اقتران الجهاز لديها قيمة node.
• سجل اقتران الجهاز هو العقد الدائم للأدوار المعتمدة. ويبقى تدوير الرموز داخل ذلك العقد؛ ولا يمكنه ترقية عقدة مقترنة إلى دور مختلف لم تمنحه الموافقة أصلًا.
• يُعد node.pair.* ‏(CLI: ‏openclaw nodes pending/approve/reject/rename) مخزن اقتران عقد منفصلًا مملوكًا للـ gateway؛ وهو لا يتحكم في مصافحة WS ‏connect.
• يتبع نطاق الموافقة الأوامر المعلنة في الطلب المعلق:
  • طلب بلا أوامر: ‏operator.pairing
  • أوامر node غير التنفيذية: ‏operator.pairing + operator.write
  • system.run / system.run.prepare / system.which: ‏operator.pairing + operator.admin

​

مضيف node بعيد (system.run)

​

ما الذي يعمل وأين

• مضيف Gateway: يستقبل الرسائل، ويشغّل النموذج، ويوجّه استدعاءات الأدوات.
• مضيف Node: ينفذ system.run/system.which على جهاز العقدة.
• الموافقات: تُفرض على مضيف node عبر ~/.openclaw/exec-approvals.json.

• تربط عمليات تشغيل العقدة المدعومة بالموافقة سياق الطلب الدقيق.
• بالنسبة إلى عمليات التنفيذ المباشر لملفات shell/runtime، يربط OpenClaw أيضًا على أساس أفضل جهد مُعامل ملف محلي فعلي واحد، ويرفض التشغيل إذا تغيّر ذلك الملف قبل التنفيذ.
• إذا لم يتمكن OpenClaw من تحديد ملف محلي فعلي واحد بالضبط لأمر interpreter/runtime، فسيتم رفض التنفيذ المدعوم بالموافقة بدلًا من الادعاء بتغطية كاملة لوقت التشغيل. استخدم sandboxing، أو مضيفات منفصلة، أو قائمة سماح موثوقة صريحة/تدفقًا كاملاً من أجل دلالات interpreter الأوسع.

​

ابدأ مضيف node ‏(مقدمة)

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

​

Gateway بعيدة عبر نفق SSH ‏(ربط loopback)

# الطرفية A (اتركها قيد التشغيل): مرّر المنفذ المحلي 18790 -> gateway 127.0.0.1:18789
ssh -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.
• في الوضع المحلي، يتجاهل مضيف node عمدًا القيم gateway.remote.token / gateway.remote.password.
• في الوضع البعيد، تكون gateway.remote.token / gateway.remote.password مؤهلة وفق قواعد الأولوية البعيدة.
• إذا كانت gateway.auth.* المحلية الفعالة مكوّنة كـ SecretRefs ولكنها غير محلولة، فإن مصادقة مضيف node تفشل بشكل مغلق.
• لا يحترم حل مصادقة مضيف node إلا متغيرات البيئة OPENCLAW_GATEWAY_*.

​

ابدأ مضيف node ‏(كخدمة)

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

​

اقترن + سمِّ

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

• --display-name على openclaw node run / openclaw node install ‏(تُحفَظ في ~/.openclaw/node.json على العقدة).
• openclaw nodes rename --node <id|name|ip> --name "Build 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"

​

وجّه exec إلى node

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

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

• CLI مضيف node
• أداة Exec
• موافقات Exec

​

استدعاء الأوامر

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

​

لقطات الشاشة (لقطات canvas)

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

​

عناصر تحكم Canvas

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com
openclaw 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 عناوين URL أو مسارات ملفات محلية (--target)، بالإضافة إلى --x/--y/--width/--height اختياريًا لتحديد الموضع.
• يقبل canvas eval JavaScript مضمنة (--js) أو وسيطة موضعية.

​

A2UI ‏(Canvas)

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

• يتم دعم A2UI v0.8 JSONL فقط (يتم رفض v0.9/createSurface).

​

الصور + الفيديوهات (كاميرا العقدة)

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # الافتراضي: كلا الاتجاهين (سطران MEDIA)
openclaw nodes camera snap --node <idOrNameOrIp> --facing front

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

• يجب أن تكون العقدة في المقدمة من أجل canvas.* وcamera.* ‏(تعيد الاستدعاءات في الخلفية NODE_BACKGROUND_UNAVAILABLE).
• يتم تقييد مدة المقطع (حاليًا <= 60s) لتجنب الحمولات الكبيرة جدًا بتنسيق base64.
• سيطلب Android أذونات CAMERA/RECORD_AUDIO متى أمكن؛ وتفشل الأذونات المرفوضة برسالة *_PERMISSION_REQUIRED.

​

تسجيلات الشاشة (nodes)

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

• يعتمد توفر screen.record على منصة العقدة.
• يتم تقييد تسجيلات الشاشة إلى <= 60s.
• يعطّل --no-audio التقاط الميكروفون على المنصات المدعومة.
• استخدم --screen <index> لاختيار شاشة عندما تتوفر شاشات متعددة.

​

الموقع (nodes)

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

• يكون Location معطلًا افتراضيًا.
• تتطلب قيمة “Always” إذنًا من النظام؛ ويكون الجلب في الخلفية على أساس أفضل جهد.
• تتضمن الاستجابة lat/lon والدقة (بالمتر) والطابع الزمني.

​

SMS ‏(عقد Android)

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

• يجب قبول مطالبة الإذن على جهاز Android قبل الإعلان عن هذه القدرة.
• لن تعلن الأجهزة التي تعمل عبر Wi‑Fi فقط ومن دون اتصال خلوي عن sms.send.

​

أوامر جهاز Android + البيانات الشخصية

• device.status وdevice.info وdevice.permissions وdevice.health
• notifications.list وnotifications.actions
• photos.latest
• contacts.search وcontacts.add
• calendar.events وcalendar.add
• callLog.search
• sms.search
• motion.activity وmotion.pedometer

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

• يتم تقييد أوامر الحركة بالقدرات المتاحة من المستشعرات.

​

أوامر النظام (مضيف node / عقدة mac)

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

• يعيد system.run قيمة stdout/stderr/exit code ضمن الحمولة.
• يمر تنفيذ shell الآن عبر أداة exec مع host=node؛ بينما تبقى nodes سطح RPC مباشرًا لأوامر العقدة الصريحة.
• لا تعرض nodes invoke الأمرين system.run أو system.run.prepare؛ فهذان يبقيان على مسار exec فقط.
• يقوم مسار exec بتحضير systemRunPlan معتمد قبل الموافقة. وبمجرد منح الموافقة، تقوم gateway بتمرير تلك الخطة المخزنة، وليس أي حقول أمر/cwd/session معدّلة لاحقًا من قبل المستدعي.
• يحترم system.notify حالة إذن الإشعارات في تطبيق macOS.
• تستخدم بيانات تعريف platform / deviceFamily غير المعروفة للعقدة قائمة سماح افتراضية محافظة تستبعد system.run وsystem.which. وإذا كنت تحتاج عمدًا إلى هذه الأوامر على منصة غير معروفة، فأضفها صراحةً عبر gateway.nodes.allowCommands.
• يدعم system.run الخيارات --cwd و--env KEY=VAL و--command-timeout و--needs-screen-recording.
• بالنسبة إلى مغلفات shell ‏(bash|sh|zsh ... -c/-lc)، يتم تقليص قيم --env الخاصة بنطاق الطلب إلى قائمة سماح صريحة (TERM وLANG وLC_* وCOLORTERM وNO_COLOR وFORCE_COLOR).
• بالنسبة إلى قرارات السماح الدائم في وضع allowlist، تقوم مغلفات الإرسال المعروفة (env وnice وnohup وstdbuf وtimeout) بحفظ مسارات الملفات التنفيذية الداخلية بدلًا من مسارات المغلف. وإذا لم يكن فك المغلف آمنًا، فلن يتم حفظ أي إدخال لقائمة السماح تلقائيًا.
• على مضيفات node التي تعمل بنظام Windows في وضع allowlist، تتطلب عمليات تشغيل مغلفات shell عبر cmd.exe /c موافقة (ولا يؤدي إدخال allowlist وحده إلى السماح التلقائي بصيغة المغلف).
• يدعم system.notify الخيارين --priority <passive|active|timeSensitive> و--delivery <system|overlay|auto>.
• تتجاهل مضيفات node تجاوزات PATH وتزيل مفاتيح بدء التشغيل/shell الخطرة (DYLD_* وLD_* وNODE_OPTIONS وPYTHON* وPERL* وRUBYOPT وSHELLOPTS وPS4). وإذا كنت تحتاج إلى إدخالات PATH إضافية، فقم بتكوين بيئة خدمة مضيف node ‏(أو بتثبيت الأدوات في مواقع قياسية) بدلًا من تمرير PATH عبر --env.
• في وضع node على macOS، يتم التحكم في system.run بواسطة موافقات exec في تطبيق macOS ‏(Settings → Exec approvals). وتتصرف الأوضاع ask/allowlist/full بالطريقة نفسها كما في مضيف node بدون واجهة؛ وتعيد المطالبات المرفوضة SYSTEM_RUN_DENIED.
• على مضيف node بدون واجهة، يتم التحكم في system.run بواسطة موافقات exec ‏(~/.openclaw/exec-approvals.json).

​

ربط exec بالعقدة

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

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

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

​

خريطة الأذونات

​

مضيف node بدون واجهة (متعدد المنصات)

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

• ما يزال الاقتران مطلوبًا (سيعرض Gateway مطالبة اقتران جهاز).
• يخزن مضيف node معرّف العقدة الخاص به، ورمزه، واسم العرض، ومعلومات اتصال gateway في ~/.openclaw/node.json.
• تُفرض موافقات exec محليًا عبر ~/.openclaw/exec-approvals.json (راجع موافقات Exec).
• على macOS، ينفذ مضيف node بدون واجهة الأمر system.run محليًا افتراضيًا. اضبط OPENCLAW_NODE_EXEC_HOST=app لتوجيه system.run عبر مضيف exec في التطبيق المرافق؛ وأضف OPENCLAW_NODE_EXEC_FALLBACK=0 لفرض استخدام مضيف التطبيق والفشل بشكل مغلق إذا لم يكن متاحًا.
• أضف --tls / --tls-fingerprint عندما تستخدم Gateway WS بروتوكول TLS.

​

وضع node على Mac

• يتصل تطبيق شريط القوائم في macOS بخادم Gateway WS كعقدة (لذلك تعمل openclaw nodes … على هذا الـ Mac).
• في الوضع البعيد، يفتح التطبيق نفق SSH لمنفذ Gateway ويتصل بـ localhost.