العُقد

​

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

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

• nodes status يضع علامة على العقدة بأنها مقترنة عندما يتضمن دور اقتران جهازها node.
• يمكن لجهاز Mac أصلي متصل ولديه إذن إمكانية الوصول الإبلاغ عن نشاط الإدخال المادي المجمّع. يضع 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

​

تفاوت الإصدارات وترتيب الترقية

​

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

• ترتبط عمليات تشغيل العقد المدعومة بالموافقة بسياق الطلب الدقيق. يُعِد مسار التنفيذ systemRunPlan أساسيًا قبل الموافقة؛ وبعد منحها، يمرر Gateway تلك الخطة المخزنة، لا أي حقول للأمر/دليل العمل/الجلسة يعدّلها المستدعي لاحقًا، ويعيد التحقق من دليل العمل قبل التشغيل.
• بالنسبة إلى عمليات التنفيذ المباشر لملفات الصدفة/بيئة التشغيل، يربط OpenClaw أيضًا، بأفضل جهد ممكن، مُعامل ملف محلي واحدًا محددًا، ويرفض التشغيل إذا تغيّر ذلك الملف قبل التنفيذ.
• إذا تعذر على OpenClaw تحديد ملف محلي محدد واحد بالضبط لأمر مفسر/بيئة تشغيل، يُرفض التنفيذ المدعوم بالموافقة بدلًا من التظاهر بتوفير تغطية كاملة لبيئة التشغيل. استخدم العزل، أو مضيفين منفصلين، أو قائمة سماح موثوقة صريحة/سير عمل كامل لدلالات المفسر الأوسع.

​

بدء مضيف عقدة (في الواجهة الأمامية)

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

​

Gateway بعيد عبر نفق SSH (ربط الاسترجاع)

# الطرفية 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.
• في الوضع المحلي، يتجاهل مضيف العقدة عمدًا gateway.remote.token / gateway.remote.password.
• في الوضع البعيد، يكون gateway.remote.token / gateway.remote.password مؤهلين وفق قواعد أسبقية الوضع البعيد.
• إذا كانت SecretRefs المحلية النشطة gateway.auth.* مضبوطة ولكنها غير محلولة، تفشل مصادقة مضيف العقدة بحالة مغلقة.
• لا يحترم حل مصادقة مضيف العقدة سوى متغيرات البيئة OPENCLAW_GATEWAY_*.

​

بدء مضيف عقدة (كخدمة)

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

​

الاقتران + التسمية

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

• --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 المستضافة على العقدة

{
  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}",
          },
        },
      },
    },
  },
}

​

Skills المستضافة على العقدة

​

حالة الهوية بلا واجهة رسومية

• ~/.openclaw/state/openclaw.sqlite (node_host_config): معرّف مثيل العميل، واسم العرض، وبيانات تعريف اتصال Gateway.
• ~/.openclaw/identity/device.json: زوج مفاتيح الجهاز الموقّع ومعرّف الجهاز المشفّر المشتق.
• ~/.openclaw/identity/device-auth.json: رموز مصادقة الأجهزة المقترنة، المفهرسة حسب معرّف الجهاز المشفّر والدور.

​

إضافة الأوامر إلى قائمة السماح

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

​

توجيه التنفيذ إلى العقدة

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 لمضيف العقدة
• أداة التنفيذ
• موافقات التنفيذ

​

استدلال النموذج المحلي

​

جلسات Codex والنصوص المنسوخة

​

جلسات Claude والنصوص المنسوخة

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

​

جلسات OpenCode وPi

​

رفع الملفات إلى الطرفية

​

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

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

​

سياسة الأوامر

1. يجب أن يعلن Node عن الأمر في بيانات تعريف اتصاله الموثَّق (connect.commands).
2. يجب أن تتضمن قائمة السماح في Gateway، المستمدة من المنصة والموافقة، الأمر المعلن.

​

الإعدادات (openclaw.json)

{
  gateway: {
    nodes: {
      // وافق تلقائيًا على إقران Node لأول مرة من الشبكات الموثوقة (قائمة CIDR).
      // يكون معطلًا عند عدم تعيينه. ينطبق فقط على طلبات role:node لأول مرة
      // التي لا تطلب نطاقات؛ ولا يوافق تلقائيًا على الترقيات.
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
        // الموافقة التلقائية المتحقق منها عبر SSH (الافتراضي: مفعّلة). توافق على إقران
        // Node لأول مرة عند تطابق مفتاح الجهاز تمامًا كما يُقرأ مجددًا عبر SSH.
        sshVerify: true,
      },
      // ثق بأدوات Plugin المرئية للوكيل التي تنشرها العُقد المقترنة (الافتراضي: 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",
    },
  },
}

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

​

لقطات الشاشة (لقطات 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 على Linux عناوين HTTP(S) URL أو عارض 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.jsonl
openclaw nodes canvas a2ui reset --node <idOrNameOrIp>

• تستخدم عُقد الأجهزة المحمولة وسطح مكتب Linux صفحة A2UI مضمّنة مملوكة للتطبيق للعرض القادر على تنفيذ الإجراءات.
• لا يُدعم سوى A2UI v0.8 JSONL ‏(يُرفض v0.9/createSurface).
• يعرض iOS وAndroid صفحات Gateway Canvas البعيدة، لكن لا تُرسل إجراءات أزرار A2UI إلا من صفحة A2UI المضمّنة المملوكة للتطبيق. تكون صفحات A2UI المستضافة على Gateway عبر HTTP/HTTPS مخصصة للعرض فقط على عملاء الأجهزة المحمولة هؤلاء.
• يمكن لـ macOS إرسال الإجراءات من صفحة Gateway A2UI الدقيقة المحددة بنطاق الإمكانية والتي يختارها التطبيق. تظل صفحات HTTP/HTTPS الأخرى مخصصة للعرض فقط.
• يرسل Linux الإجراءات فقط من صفحة A2UI المضمّنة. تظل صفحات HTTP/HTTPS الأخرى مخصصة للعرض فقط، ولا يعلن Node على Linux دون واجهة رسومية ومن دون تطبيق سطح المكتب عن Canvas.

​

الصور ومقاطع الفيديو (كاميرا Node)

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # الافتراضي: كلا الاتجاهين (سطران MEDIA)
openclaw nodes camera snap --node <idOrNameOrIp> --facing front
openclaw nodes camera snap --node <idOrNameOrIp> --device-id <id> --max-width 1200 --quality 0.9 --delay-ms 2000

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

• يجب أن يكون Node في الواجهة الأمامية لتنفيذ canvas.* وcamera.* (تعيد الاستدعاءات في الخلفية NODE_BACKGROUND_UNAVAILABLE).
• تحدّ العُقد من مدة المقطع لإبقاء حمولة base64 قابلة للإدارة (راجع التقاط الكاميرا لمعرفة الحدود الدقيقة لكل منصة). تحد أداة الوكيل nodes أيضًا قيمة durationMs المطلوبة عند 300000 (5 دقائق) قبل إعادة توجيه الاستدعاء؛ ويفرض Node نفسه الحد الأضيق.
• سيطلب Android أذونات CAMERA/RECORD_AUDIO عندما يكون ذلك ممكنًا؛ وتفشل الأذونات المرفوضة مع *_PERMISSION_REQUIRED.

​

تسجيلات الشاشة (العُقد)

openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
openclaw 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)

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

• الموقع معطّل افتراضيًا.
• يتطلب “Always” إذنًا من النظام؛ ويُنفَّذ الجلب في الخلفية حسب أفضل جهد ممكن.
• تتضمن الاستجابة خط العرض/خط الطول، والدقة (بالأمتار)، والطابع الزمني.
• للبنية الكاملة للمعلمات/الاستجابة ورموز الأخطاء: أمر الموقع.

​

الرسائل النصية القصيرة (عُقد Android)

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

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 لم يفوّضه.

​

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

• device.status، device.info — ‏iOS وAndroid وWindows.
• device.permissions، device.health، device.apps — ‏Android فقط؛ يتطلب device.apps تمكين مشاركة Installed Apps في Android Settings، ويُرجع افتراضيًا التطبيقات الظاهرة في مشغّل التطبيقات.
• 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 على Mac)

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؛ إذ يظلان متاحين في مسار التنفيذ فقط.
• يُعد مسار التنفيذ systemRunPlan معياريًا قبل الموافقة. وبمجرد منح الموافقة، يمرر Gateway تلك الخطة المخزنة، لا أي حقول للأمر أو دليل العمل أو الجلسة يعدّلها المستدعي لاحقًا.
• يراعي 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 بنظام Windows في وضع قائمة السماح، تتطلب عمليات تشغيل غلاف الصدفة عبر cmd.exe /c موافقةً (فإدخال قائمة السماح وحده لا يسمح تلقائيًا بصيغة الغلاف).
• يتجاهل مضيفو Node تجاوزات PATH في --env، ويزيلون مجموعة كبيرة ومُصانة من متغيرات بدء تشغيل المفسّر/الصدفة (مثل NODE_OPTIONS وPYTHONPATH وBASH_ENV وDYLD_* وLD_*) قبل تشغيل الأمر. إذا احتجت إلى إدخالات PATH إضافية، فاضبط بيئة خدمة مضيف Node (أو ثبّت الأدوات في المواقع القياسية) بدلًا من تمرير PATH عبر --env.
• في وضع Node على macOS، يخضع system.run لموافقات التنفيذ في تطبيق macOS (Settings → Exec approvals). تعمل أوضاع الطلب/قائمة السماح/الكامل بالطريقة نفسها التي يعمل بها مضيف Node بلا واجهة؛ وتُرجع المطالبات المرفوضة SYSTEM_RUN_DENIED.
• على مضيف Node بلا واجهة، يخضع system.run لموافقات التنفيذ (~/.openclaw/exec-approvals.json)؛ وعلى macOS تحديدًا، راجع متغيرات بيئة توجيه مضيف التنفيذ ضمن مضيف Node بلا واجهة أدناه.

​

ربط Node بالتنفيذ

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 مطالبة باقتران الجهاز).
• تستخدم البيانات الوصفية لمثيل العميل وهوية الجهاز الموقّعة ومصادقة الاقتران ملفات منفصلة؛ راجع حالة الهوية بلا واجهة.
• تُفرض موافقات التنفيذ محليًا عبر ~/.openclaw/exec-approvals.json (راجع موافقات التنفيذ).
• على macOS، ينفّذ مضيف Node بلا واجهة system.run محليًا افتراضيًا. عيّن OPENCLAW_NODE_EXEC_HOST=app لتوجيه system.run عبر مضيف التنفيذ في التطبيق المصاحب؛ وأضف OPENCLAW_NODE_EXEC_FALLBACK=0 لاشتراط مضيف التطبيق والفشل المغلق إذا لم يكن متاحًا.
• أضف --tls / --tls-fingerprint عندما يستخدم WebSocket الخاص بـ Gateway بروتوكول TLS.

​

وضع Node على Mac

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