​

CLI backends (وقت تشغيل الرجوع الاحتياطي)

• لا يتم حقن أدوات OpenClaw مباشرة، لكن يمكن للـ backends التي تحتوي على bundleMcp: true (وهو الإعداد الافتراضي لـ Claude CLI) أن تتلقى أدوات gateway عبر جسر MCP loopback.
• بث JSONL (يستخدم Claude CLI القيمة --output-format stream-json مع --include-partial-messages؛ وتُرسل المطالبات عبر stdin).
• الجلسات مدعومة (بحيث تبقى الأدوار اللاحقة مترابطة).
• يمكن تمرير الصور إذا كان CLI يقبل مسارات الصور.

​

بدء سريع مناسب للمبتدئين

openclaw agent --message "hi" --model claude-cli/claude-sonnet-4-6

openclaw agent --message "hi" --model codex-cli/gpt-5.4

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
      },
    },
  },
}

​

استخدامها كرجوع احتياطي

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["claude-cli/claude-sonnet-4-6", "claude-cli/claude-opus-4-6"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "claude-cli/claude-sonnet-4-6": {},
        "claude-cli/claude-opus-4-6": {},
      },
    },
  },
}

• إذا كنت تستخدم agents.defaults.models (قائمة السماح)، فيجب أن تتضمن claude-cli/....
• إذا فشل المزوّد الأساسي (المصادقة، حدود المعدل، المهلات)، فسيحاول OpenClaw CLI backend بعده.
• لا يزال Claude CLI backend المضمّن يقبل الأسماء المستعارة الأقصر مثل claude-cli/opus أو claude-cli/opus-4.6 أو claude-cli/sonnet، لكن تستخدم الوثائق وأمثلة التكوين المراجع الأساسية claude-cli/claude-*.

​

نظرة عامة على التكوين

agents.defaults.cliBackends

<provider>/<model>

​

مثال على التكوين

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          input: "arg",
          modelArg: "--model",
          modelAliases: {
            "claude-opus-4-6": "opus",
            "claude-sonnet-4-6": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

​

كيف يعمل

1. يحدد backend بناءً على بادئة المزوّد (claude-cli/...).
2. يبني مطالبة نظام باستخدام مطالبة OpenClaw نفسها + سياق مساحة العمل.
3. ينفّذ CLI باستخدام معرّف جلسة (إذا كان مدعومًا) حتى يبقى السجل متسقًا.
4. يحلل الإخراج (JSON أو نص عادي) ويعيد النص النهائي.
5. يحفظ معرّفات الجلسات لكل backend، بحيث تعيد الأدوار اللاحقة استخدام جلسة CLI نفسها.

​

الجلسات

• إذا كانت CLI تدعم الجلسات، فاضبط sessionArg (مثل --session-id) أو sessionArgs (العنصر النائب {sessionId}) عندما يلزم إدراج المعرّف في عدة علامات.
• إذا كانت CLI تستخدم أمرًا فرعيًا للاستئناف مع علامات مختلفة، فاضبط resumeArgs (ويحل محل args عند الاستئناف) واختياريًا resumeOutput (لعمليات الاستئناف غير المعتمدة على JSON).
• sessionMode:
  • always: أرسل دائمًا معرّف جلسة (UUID جديد إذا لم يكن هناك معرّف مخزّن).
  • existing: أرسل معرّف جلسة فقط إذا كان مخزنًا من قبل.
  • none: لا ترسل معرّف جلسة أبدًا.

• يحافظ serialize: true على ترتيب التشغيلات في المسار نفسه.
• تسلسل معظم CLIs يكون على مسار مزوّد واحد.
• claude-cli أضيق من ذلك: تُسلسل التشغيلات المستأنفة لكل معرّف جلسة Claude، وتُسلسل التشغيلات الجديدة لكل مسار مساحة عمل. ويمكن لمساحات العمل المستقلة أن تعمل بالتوازي.
• يتخلى OpenClaw عن إعادة استخدام جلسة CLI المخزنة عندما تتغير حالة مصادقة backend، بما في ذلك إعادة تسجيل الدخول، أو تدوير الرموز، أو تغيير بيانات اعتماد ملف تعريف المصادقة.

​

الصور (تمرير مباشر)

imageArg: "--image",
imageMode: "repeat"

​

الإدخالات / المخرجات

• output: "json" (الافتراضي) يحاول تحليل JSON واستخراج النص + معرّف الجلسة.
• بالنسبة إلى مخرجات JSON الخاصة بـ Gemini CLI، يقرأ OpenClaw نص الرد من response والاستخدام من stats عندما تكون usage مفقودة أو فارغة.
• يحلل output: "jsonl" تدفقات JSONL (مثل Claude CLI stream-json وCodex CLI --json) ويستخرج رسالة الوكيل النهائية بالإضافة إلى معرّفات الجلسة عند وجودها.
• output: "text" يعامل stdout على أنه الاستجابة النهائية.

• input: "arg" (الافتراضي) يمرر المطالبة باعتبارها آخر وسيطة CLI.
• input: "stdin" يرسل المطالبة عبر stdin.
• إذا كانت المطالبة طويلة جدًا وكان maxPromptArgChars مضبوطًا، فسيُستخدم stdin.

​

الإعدادات الافتراضية (مملوكة لـ plugin)

• command: "claude"
• args: ["-p", "--output-format", "stream-json", "--include-partial-messages", "--verbose", "--permission-mode", "bypassPermissions"]
• resumeArgs: ["-p", "--output-format", "stream-json", "--include-partial-messages", "--verbose", "--permission-mode", "bypassPermissions", "--resume", "{sessionId}"]
• output: "jsonl"
• input: "stdin"
• modelArg: "--model"
• systemPromptArg: "--append-system-prompt"
• sessionArg: "--session-id"
• systemPromptWhen: "first"
• sessionMode: "always"

• command: "codex"
• args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
• resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
• output: "jsonl"
• resumeOutput: "text"
• modelArg: "--model"
• imageArg: "--image"
• sessionMode: "existing"

• command: "gemini"
• args: ["--prompt", "--output-format", "json"]
• resumeArgs: ["--resume", "{sessionId}", "--prompt", "--output-format", "json"]
• modelArg: "--model"
• sessionMode: "existing"
• sessionIdFields: ["session_id", "sessionId"]

• يُقرأ نص الرد من الحقل response في JSON.
• يعود الاستخدام إلى stats عندما تكون usage غائبة أو فارغة.
• تُطبّع stats.cached إلى OpenClaw cacheRead.
• إذا كانت stats.input مفقودة، يشتق OpenClaw رموز الإدخال من stats.input_tokens - stats.cached.

​

الإعدادات الافتراضية المملوكة لـ plugin

• تسجلها plugins باستخدام api.registerCliBackend(...).
• يصبح id الخاص بـ backend هو بادئة المزوّد في مراجع النموذج.
• يظل تكوين المستخدم في agents.defaults.cliBackends.<id> متقدمًا على الإعداد الافتراضي للـ plugin.
• يظل تنظيف التكوين الخاص بـ backend مملوكًا للـ plugin عبر الخطاف الاختياري normalizeConfig.

​

تراكبات Bundle MCP

• claude-cli: ‏bundleMcp: true (الافتراضي)
• codex-cli: لا يوجد تراكب bundle MCP
• google-gemini-cli: لا يوجد تراكب bundle MCP

• يشغّل خادم MCP محليًا عبر HTTP loopback يكشف أدوات gateway لعملية CLI
• يصادق الجسر باستخدام رمز لكل جلسة (OPENCLAW_MCP_TOKEN)
• يقيّد الوصول إلى الأدوات بسياق الجلسة والحساب والقناة الحالية
• يحمّل خوادم bundle-MCP الممكّنة لمساحة العمل الحالية
• يدمجها مع أي --mcp-config موجودة مسبقًا في backend
• يعيد كتابة وسائط CLI لتمرير --strict-mcp-config --mcp-config <generated-file>

​

القيود

• لا توجد استدعاءات مباشرة لأدوات OpenClaw. لا يحقن OpenClaw استدعاءات الأدوات ضمن بروتوكول CLI backend. ومع ذلك، فإن backends التي تحتوي على bundleMcp: true (وهو الإعداد الافتراضي لـ Claude CLI) تتلقى أدوات gateway عبر جسر MCP loopback، لذلك يستطيع Claude CLI استدعاء أدوات OpenClaw عبر دعم MCP الأصلي لديه.
• يعتمد البث على backend. يستخدم Claude CLI بث JSONL (stream-json مع --include-partial-messages)؛ وقد تظل CLI backends الأخرى مخزنة مؤقتًا حتى الخروج.
• المخرجات المهيكلة تعتمد على تنسيق JSON الخاص بـ CLI.
• جلسات Codex CLI تُستأنف عبر مخرجات نصية (وليس JSONL)، وهو ما يجعلها أقل هيكلةً من التشغيل الأولي باستخدام --json. ومع ذلك، تظل جلسات OpenClaw تعمل بشكل طبيعي.

​

استكشاف الأخطاء وإصلاحها

• تعذر العثور على CLI: اضبط command على مسار كامل.
• اسم نموذج خاطئ: استخدم modelAliases لربط provider/model → نموذج CLI.
• لا يوجد استمرارية للجلسة: تأكد من ضبط sessionArg وأن sessionMode ليست none (لا يستطيع Codex CLI حاليًا الاستئناف مع مخرجات JSON).
• يتم تجاهل الصور: اضبط imageArg (وتأكد من أن CLI تدعم مسارات الملفات).