role: "node" ويعرض سطح أوامر (مثل canvas.* وcamera.* وdevice.* وnotifications.* وsystem.*) عبر node.invoke. تفاصيل البروتوكول: بروتوكول Gateway.
النقل القديم: بروتوكول Bridge (TCP JSONL؛
تاريخي فقط للعقد الحالية).
يمكن لـ macOS أيضًا العمل في وضع العقدة: يتصل تطبيق شريط القوائم بخادم WS الخاص بـ Gateway ويعرض أوامر اللوحة/الكاميرا المحلية الخاصة به كعقدة (بحيث يعمل
openclaw nodes … على هذا Mac). في وضع Gateway البعيد، تتولى استضافة عقدة CLI (openclaw node run أو خدمة العقدة المثبّتة) أتمتة المتصفح، وليس عقدة التطبيق الأصلية.
ملاحظات:
- العقد هي أجهزة طرفية، وليست بوابات. لا تشغّل خدمة Gateway.
- تصل رسائل Telegram/WhatsApp/إلخ إلى Gateway، وليس إلى العقد.
- دليل استكشاف الأخطاء وإصلاحها: /nodes/troubleshooting
الاقتران + الحالة
تستخدم عقد WS اقتران الأجهزة. تعرض العقد هوية جهاز أثناءconnect؛ وينشئ Gateway طلب اقتران جهاز لـ role: node. وافق عليه عبر CLI الأجهزة (أو واجهة المستخدم).
CLI سريع:
requestId جديد. أعد تشغيل
openclaw devices list قبل الموافقة.
ملاحظات:
- يضع
nodes statusعلامة مقترنة على العقدة عندما يتضمن دور اقتران جهازهاnode. - سجل اقتران الجهاز هو عقد الدور المعتمَد الدائم. يبقى تدوير الرمز داخل ذلك العقد؛ ولا يمكنه ترقية عقدة مقترنة إلى دور مختلف لم تمنحه موافقة الاقتران قط.
node.pair.*(CLI:openclaw nodes pending/approve/reject/remove/rename) هو مخزن منفصل لاقتران العقد تملكه Gateway؛ وهو لا يتحكم في مصافحةconnectالخاصة بـ WS.- يزيل
openclaw nodes remove --node <id|name|ip>اقتران عقدة. وبالنسبة إلى عقدة مدعومة بجهاز، فإنه يسحب دورnodeالخاص بالجهاز فيdevices/paired.jsonويفصل جلسات دور العقدة لذلك الجهاز — يحتفظ الجهاز متعدد الأدوار بصفه ويفقد دورnodeفقط، بينما يُحذف صف الجهاز ذي العقدة فقط. كما يمسح أي إدخال مطابق من مخزن اقتران العقد المنفصل المملوك لـ Gateway. قد يزيلoperator.pairingصفوف العقد غير المشغّلة؛ ويحتاج مستدعي رمز جهاز يسحب دور عقدته الخاصة على جهاز متعدد الأدوار أيضًا إلىoperator.admin. - يتبع نطاق الموافقة الأوامر المعلنة في الطلب المعلّق:
- طلب بلا أوامر:
operator.pairing - أوامر عقدة غير تنفيذية:
operator.pairing+operator.write system.run/system.run.prepare/system.which:operator.pairing+operator.admin
- طلب بلا أوامر:
مضيف عقدة بعيد (system.run)
استخدم مضيف عقدة عندما يعمل Gateway على جهاز وتريد تنفيذ الأوامر على جهاز آخر. لا يزال النموذج يتحدث إلى Gateway؛ ويعيد Gateway توجيه استدعاءاتexec إلى مضيف العقدة عند تحديد host=node.
ما الذي يعمل وأين
- مضيف Gateway: يستقبل الرسائل، ويشغّل النموذج، ويوجّه استدعاءات الأدوات.
- مضيف العقدة: ينفذ
system.run/system.whichعلى جهاز العقدة. - الموافقات: تُفرض على مضيف العقدة عبر
~/.openclaw/exec-approvals.json.
- تربط عمليات تشغيل العقد المدعومة بالموافقة سياق الطلب الدقيق.
- بالنسبة إلى عمليات تنفيذ ملفات shell/runtime المباشرة، يبذل OpenClaw أيضًا أفضل جهد لربط مُعامل ملف محلي ملموس واحد ويرفض التشغيل إذا تغيّر ذلك الملف قبل التنفيذ.
- إذا تعذر على OpenClaw تحديد ملف محلي ملموس واحد بالضبط لأمر مفسّر/runtime، فسيُرفض التنفيذ المدعوم بالموافقة بدلًا من ادعاء تغطية runtime كاملة. استخدم العزل، أو مضيفات منفصلة، أو قائمة سماح موثوقة صريحة/سير عمل كاملًا لدلالات المفسّر الأوسع.
بدء مضيف عقدة (في المقدمة)
على جهاز العقدة:Gateway بعيد عبر نفق SSH (ربط loopback)
إذا كان Gateway مربوطًا بـ loopback (gateway.bind=loopback، الافتراضي في الوضع المحلي)، فلا يمكن لمضيفات العقد البعيدة الاتصال مباشرة. أنشئ نفق SSH ووجّه مضيف العقدة إلى الطرف المحلي للنفق.
مثال (مضيف العقدة -> مضيف Gateway):
- يدعم
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مؤهلين وفق قواعد أولوية البعيد. - إذا كانت SecretRefs نشطة محلية لـ
gateway.auth.*مكوّنة لكنها غير محلولة، تفشل مصادقة مضيف العقدة بشكل مغلق. - لا يراعي حل مصادقة مضيف العقدة إلا متغيرات البيئة
OPENCLAW_GATEWAY_*.
بدء مضيف عقدة (خدمة)
الاقتران + التسمية
على مضيف Gateway:openclaw devices list
ووافق على requestId الحالي.
خيارات التسمية:
--display-nameعلىopenclaw node run/openclaw node install(يستمر في~/.openclaw/node.jsonعلى العقدة).openclaw nodes rename --node <id|name|ip> --name "Build Node"(تجاوز من Gateway).
اسمح بالأوامر
موافقات exec هي لكل مضيف عقدة. أضف إدخالات قائمة السماح من Gateway:~/.openclaw/exec-approvals.json.
وجّه exec إلى العقدة
اضبط الافتراضيات (إعداد Gateway):exec مع host=node على مضيف العقدة (خاضعًا لقائمة سماح/موافقات العقدة).
لن يختار host=auto العقدة ضمنيًا من تلقاء نفسه، لكن يُسمح بطلب host=node صريح لكل استدعاء من auto. إذا كنت تريد أن يكون exec على العقدة هو الافتراضي للجلسة، فاضبط tools.exec.host=node أو /exec host=node ... صراحة.
ذو صلة:
استدلال النموذج المحلي
يمكن لعقدة سطح مكتب أو خادم عرض نماذج قادرة على المحادثة من خادم Ollama يعمل على تلك العقدة. يستخدم الوكلاء أداةnode_inference الخاصة بـ Plugin Ollama لاكتشاف النماذج المثبّتة وتشغيل مطالبة محدودة عن بعد؛ ولا يحتاج Gateway إلى وصول شبكي مباشر إلى Ollama. راجع استدلال Ollama المحلي على العقدة
للإعداد، وتصفية النماذج، وأوامر التحقق المباشر.
استدعاء الأوامر
مستوى منخفض (RPC خام):سياسة الأوامر
يجب أن تجتاز أوامر العقد بوابتين قبل إمكان استدعائها:- يجب أن تعلن العقدة الأمر في قائمة WebSocket
connect.commands. - يجب أن تسمح سياسة منصة Gateway بالأمر المعلن.
canvas.* وcamera.list وlocation.get وscreen.snapshot.
العقد الموثوقة التي تعلن عن قدرة talk أو تعلن أوامر talk.*
تسمح أيضًا افتراضيًا بأوامر الضغط للتحدث المعلنة (talk.ptt.start وtalk.ptt.stop
وtalk.ptt.cancel وtalk.ptt.once)، بغض النظر عن تسمية المنصة.
لا تزال الأوامر الخطرة أو الثقيلة الخصوصية مثل camera.snap وcamera.clip و
screen.record تتطلب اشتراكًا صريحًا باستخدام
gateway.nodes.allowCommands. يتغلب gateway.nodes.denyCommands دائمًا على
الافتراضيات وإدخالات قائمة السماح الإضافية.
يمكن لأوامر العقد المملوكة لـ Plugin إضافة سياسة استدعاء عقدة في Gateway. تعمل تلك السياسة بعد فحص قائمة السماح وقبل التوجيه إلى العقدة، لذلك تشترك node.invoke الخام ومساعدات CLI وأدوات الوكيل المخصصة في حد إذن Plugin نفسه. لا تزال أوامر عقد Plugin الخطرة تتطلب اشتراكًا صريحًا عبر gateway.nodes.allowCommands.
بعد أن تغيّر عقدة قائمة أوامرها المعلنة، ارفض اقتران الجهاز القديم ووافق على الطلب الجديد كي يخزن Gateway لقطة الأوامر المحدثة.
الإعداد (openclaw.json)
توجد الإعدادات المتعلقة بالعقد ضمن gateway.nodes وtools.exec:
denyCommands أمرًا حتى عندما كان افتراضي منصة أو إدخال allowCommands سيسمح به بخلاف ذلك. راجع
مرجع إعداد Gateway
لتفاصيل حقول اقتران عقد Gateway وسياسة الأوامر.
تجاوز عقدة exec لكل وكيل:
لقطات الشاشة (لقطات Canvas)
إذا كانت العقدة تعرض Canvas (WebView)، فإنcanvas.snapshot يعيد { format, base64 }.
مساعد CLI (يكتب إلى ملف مؤقت ويطبع المسار المحفوظ):
عناصر تحكم Canvas
- يقبل
canvas presentعناوين URL أو مسارات ملفات محلية (--target)، إضافة إلى--x/--y/--width/--heightالاختيارية للتموضع. - يقبل
canvas evalJS مضمنًا (--js) أو وسيطة موضعية.
A2UI (Canvas)
- تستخدم العُقد المحمولة صفحة A2UI مملوكة للتطبيق ومضمّنة للعرض القادر على تنفيذ الإجراءات.
- يُدعم فقط A2UI v0.8 JSONL (يُرفض v0.9/createSurface).
- يعرض iOS و Android صفحات Gateway Canvas البعيدة، لكن إجراءات أزرار A2UI لا تُرسل إلا من صفحة A2UI المملوكة للتطبيق والمضمّنة. تكون صفحات A2UI المستضافة على Gateway عبر HTTP/HTTPS للعرض فقط على عملاء الأجهزة المحمولة هؤلاء.
الصور + مقاطع الفيديو (كاميرا العقدة)
الصور (jpg):
mp4):
- يجب أن تكون العقدة في المقدمة من أجل
canvas.*وcamera.*(تعيد الاستدعاءات في الخلفيةNODE_BACKGROUND_UNAVAILABLE). - تُقيّد مدة المقطع (حاليًا
<= 60s) لتجنب حمولات base64 كبيرة جدًا. - سيطلب Android أذونات
CAMERA/RECORD_AUDIOعندما يكون ذلك ممكنًا؛ تفشل الأذونات المرفوضة مع*_PERMISSION_REQUIRED.
تسجيلات الشاشة (العُقد)
تعرض العُقد المدعومةscreen.record (mp4). مثال:
- يعتمد توفر
screen.recordعلى منصة العقدة. - تُقيّد تسجيلات الشاشة إلى
<= 60s. - يعطّل
--no-audioالتقاط الميكروفون على المنصات المدعومة. - استخدم
--screen <index>لتحديد شاشة عندما تتوفر شاشات متعددة.
الموقع (العُقد)
تعرض العُقدlocation.get عندما يكون الموقع مفعّلًا في الإعدادات.
مساعد CLI:
- الموقع متوقف افتراضيًا.
- يتطلب “دائمًا” إذنًا من النظام؛ والجلب في الخلفية يُنفّذ بأفضل جهد.
- تتضمن الاستجابة خط العرض/خط الطول، والدقة (بالأمتار)، والطابع الزمني.
الرسائل النصية القصيرة (عُقد Android)
يمكن لعُقد Android عرضsms.send عندما يمنح المستخدم إذن SMS ويدعم الجهاز الاتصالات الهاتفية.
استدعاء منخفض المستوى:
- يجب قبول طلب الإذن على جهاز Android قبل الإعلان عن الإمكانية.
- لن تعلن الأجهزة التي تعمل عبر Wi-Fi فقط ولا تدعم الاتصالات الهاتفية عن
sms.send.
أوامر جهاز Android + البيانات الشخصية
يمكن لعُقد Android الإعلان عن عائلات أوامر إضافية عند تفعيل الإمكانات المقابلة. العائلات المتاحة:device.status,device.info,device.permissions,device.healthdevice.appsعندما تكون مشاركة التطبيقات المثبّتة مفعّلة في إعدادات Androidnotifications.list,notifications.actionsphotos.latestcontacts.search,contacts.addcalendar.events,calendar.addcallLog.searchsms.searchmotion.activity,motion.pedometer
device.appsخيار اشتراك ويعيد التطبيقات الظاهرة في المشغّل افتراضيًا.- أوامر الحركة مقيّدة بالإمكانات حسب المستشعرات المتاحة.
أوامر النظام (مضيف العقدة / عقدة Mac)
تعرض عقدة macOSsystem.run و system.notify و system.execApprovals.get/set.
يعرض مضيف العقدة بلا واجهة system.run و system.which و system.execApprovals.get/set.
أمثلة:
- يعيد
system.runstdout/stderr/رمز الخروج في الحمولة. - يمر تنفيذ الصدفة الآن عبر أداة
execمعhost=node؛ وتبقىnodesسطح RPC المباشر لأوامر العقدة الصريحة. - لا يعرّض
nodes invokeالأمرsystem.runأوsystem.run.prepare؛ يبقيان على مسار exec فقط. - يجهّز مسار exec خطة
systemRunPlanمعيارية قبل الموافقة. بمجرد منح الموافقة، يمرر Gateway تلك الخطة المخزنة، وليس أي حقول command/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. - بالنسبة لأغلفة الصدفة (
bash|sh|zsh ... -c/-lc)، تُختزل قيم--envالمحددة بنطاق الطلب إلى قائمة سماح صريحة (TERM,LANG,LC_*,COLORTERM,NO_COLOR,FORCE_COLOR). - بالنسبة لقرارات السماح الدائم في وضع قائمة السماح، تحتفظ أغلفة الإرسال المعروفة (
env,flock,nice,nohup,stdbuf,timeout) بمسارات الملفات التنفيذية الداخلية بدلًا من مسارات الأغلفة. إذا لم يكن فك الغلاف آمنًا، فلا يُحفظ أي إدخال في قائمة السماح تلقائيًا. - على مضيفي عُقد Windows في وضع قائمة السماح، تتطلب عمليات تشغيل غلاف الصدفة عبر
cmd.exe /cموافقة (لا يسمح إدخال قائمة السماح وحده بنموذج الغلاف تلقائيًا). - يدعم
system.notifyالخيارين--priority <passive|active|timeSensitive>و--delivery <system|overlay|auto>. - يتجاهل مضيفو العُقد تجاوزات
PATHويزيلون مفاتيح بدء التشغيل/الصدفة الخطرة (DYLD_*,LD_*,BASHOPTS,FPATH,KSH_ENV,NODE_OPTIONS,NODE_REDIRECT_WARNINGS,NODE_REPL_EXTERNAL_MODULE,NODE_REPL_HISTORY,NODE_V8_COVERAGE,PYTHON*,PERL*,RUBYOPT,SHELLOPTS,PS4,TCLLIBPATH). إذا كنت تحتاج إلى إدخالات PATH إضافية، فاضبط بيئة خدمة مضيف العقدة (أو ثبّت الأدوات في مواقع قياسية) بدلًا من تمريرPATHعبر--env. - في وضع عقدة macOS، يكون
system.runمحكومًا بموافقات exec في تطبيق macOS (الإعدادات → موافقات Exec). تعمل أوضاع الطلب/قائمة السماح/الكامل بالطريقة نفسها كما في مضيف العقدة بلا واجهة؛ وتعيد المطالبات المرفوضةSYSTEM_RUN_DENIED. - على مضيف العقدة بلا واجهة، يكون
system.runمحكومًا بموافقات exec (~/.openclaw/exec-approvals.json).
ربط عقدة Exec
عندما تتوفر عُقد متعددة، يمكنك ربط exec بعقدة محددة. يضبط هذا العقدة الافتراضية لـexec host=node (ويمكن تجاوزه لكل وكيل).
الإعداد الافتراضي العام:
خريطة الأذونات
قد تتضمن العُقد خريطةpermissions في node.list / node.describe، مفهرسة باسم الإذن (مثل screenRecording, accessibility) مع قيم منطقية (true = ممنوح).
مضيف العقدة بلا واجهة (عابر للمنصات)
يمكن لـ OpenClaw تشغيل مضيف عقدة بلا واجهة (دون واجهة مستخدم) يتصل بـ Gateway WebSocket ويعرضsystem.run / system.which. هذا مفيد على Linux/Windows
أو لتشغيل عقدة محدودة بجانب خادم.
ابدأ تشغيله:
- لا يزال الاقتران مطلوبًا (سيعرض Gateway مطالبة اقتران جهاز).
- يخزن مضيف العقدة معرّف العقدة، والرمز، واسم العرض، ومعلومات اتصال Gateway في
~/.openclaw/node.json. - تُفرض موافقات exec محليًا عبر
~/.openclaw/exec-approvals.json(انظر موافقات Exec). - على macOS، ينفذ مضيف العقدة بلا واجهة
system.runمحليًا افتراضيًا. عيّنOPENCLAW_NODE_EXEC_HOST=appلتوجيهsystem.runعبر مضيف exec في التطبيق المرافق؛ وأضفOPENCLAW_NODE_EXEC_FALLBACK=0لاشتراط مضيف التطبيق والفشل مغلقًا إذا لم يكن متاحًا. - أضف
--tls/--tls-fingerprintعندما يستخدم Gateway WS بروتوكول TLS.
وضع عقدة Mac
- يتصل تطبيق شريط قوائم macOS بخادم Gateway WS كعقدة (لذلك يعمل
openclaw nodes …مع جهاز Mac هذا). - في الوضع البعيد، يفتح التطبيق نفق SSH لمنفذ Gateway ويتصل بـ
localhost.