الواجهات الخلفية لـ CLI

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• لا تُحقن أدوات OpenClaw مباشرةً، لكن الخلفيات التي تستخدم bundleMcp: true يمكنها تلقي أدوات Gateway عبر جسر MCP بنمط local loopback.
• تدفق JSONL لواجهات CLI التي تدعمه.
• الجلسات مدعومة (لذلك تظل أدوار المتابعة مترابطة).
• يمكن تمرير الصور عبرها إذا كانت واجهة CLI تقبل مسارات الصور.

​

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

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

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

​

استخدامها كخطة احتياطية

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

• إذا كنت تستخدم agents.defaults.models (قائمة سماح)، فيجب أن تضمّن نماذج خلفية CLI لديك هناك أيضًا.
• إذا فشل الموفّر الأساسي (مصادقة، حدود معدّل، مُهل)، فسيجرّب OpenClaw خلفية CLI بعد ذلك.

​

نظرة عامة على الإعداد

agents.defaults.cliBackends

<provider>/<model>

​

مثال إعداد

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "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",
          // For CLIs with a dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style CLIs can point at a prompt file instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // Opt in only if this backend may reseed safe invalidated sessions
          // from bounded raw OpenClaw transcript history before compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

​

كيف يعمل

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

claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

​

الجلسات

• إذا كانت واجهة CLI تدعم الجلسات، فعيّن sessionArg (مثل --session-id) أو sessionArgs (العنصر النائب {sessionId}) عندما يلزم إدراج المعرّف في أعلام متعددة.
• إذا كانت واجهة CLI تستخدم أمرًا فرعيًا للاستئناف مع أعلام مختلفة، فعيّن resumeArgs (يستبدل args عند الاستئناف) واختياريًا resumeOutput (للاستئنافات غير JSON).
• sessionMode:
  • always: أرسل دائمًا معرّف جلسة (UUID جديد إذا لم يكن هناك معرّف مخزن).
  • existing: أرسل معرّف جلسة فقط إذا كان واحد قد خُزن من قبل.
  • none: لا ترسل معرّف جلسة أبدًا.
• يضبط claude-cli افتراضيًا liveSession: "claude-stdio"، وoutput: "jsonl"، وinput: "stdin" حتى تعيد أدوار المتابعة استخدام عملية Claude الحية أثناء نشاطها. أصبح stdio الدافئ هو الافتراضي الآن، بما في ذلك للإعدادات المخصصة التي تحذف حقول النقل. إذا أُعيد تشغيل Gateway أو خرجت العملية الخاملة، يستأنف OpenClaw من معرّف جلسة Claude المخزن. تُتحقق معرّفات الجلسات المخزنة مقابل نص مشروع قائم قابل للقراءة قبل الاستئناف، لذلك تُمسح الارتباطات الوهمية باستخدام reason=transcript-missing بدلًا من بدء جلسة Claude CLI جديدة بصمت تحت --resume.
• تحتفظ جلسات Claude الحية بحراس محدودين لمخرجات JSONL. تسمح الإعدادات الافتراضية بما يصل إلى 8 MiB و20,000 سطر JSONL خام لكل دور. يمكن لأدوار Claude كثيفة الأدوات رفعها لكل خلفية باستخدام agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars وmaxTurnLines؛ يقيّد OpenClaw هذه الإعدادات إلى 64 MiB و100,000 سطر.
• جلسات CLI المخزنة هي استمرارية يملكها الموفّر. لا يقطعها إعادة تعيين الجلسة اليومية الضمنية؛ أما /reset وسياسات session.reset الصريحة فما زالت تقطعها.
• عادةً ما تعيد جلسات CLI الجديدة البذر فقط من ملخص Compaction في OpenClaw إضافة إلى ذيل ما بعد Compaction. لاستعادة الجلسات القصيرة التي تُبطل قبل Compaction، يمكن لخلفية الاشتراك باستخدام reseedFromRawTranscriptWhenUncompacted: true. لا يزال OpenClaw يبقي إعادة بذر النص الخام محدودة ويقصرها على الإبطالات الآمنة مثل فقدان نصوص CLI، أو تغييرات موجه النظام/MCP، أو إعادة المحاولة بسبب session-expired؛ ولا تعيد تغييرات ملف تعريف المصادقة أو credential-epoch بذر سجل النص الخام أبدًا.

• يحافظ serialize: true على ترتيب التشغيلات في المسار نفسه.
• معظم واجهات CLI تُسلسل على مسار موفّر واحد.
• يسقط OpenClaw إعادة استخدام جلسة CLI المخزنة عندما تتغير هوية المصادقة المحددة، بما في ذلك تغيّر معرّف ملف تعريف المصادقة، أو مفتاح API ثابت، أو رمز ثابت، أو هوية حساب OAuth عندما تعرضها واجهة CLI. لا تقطع دورة رموز وصول OAuth وتحديثها جلسة CLI المخزنة. إذا لم تعرض واجهة CLI معرّف حساب OAuth مستقرًا، يترك OpenClaw لتلك الواجهة فرض أذونات الاستئناف.

​

تمهيد احتياطي من جلسات claude-cli

• يفضل التمهيد أحدث ملخص /compact أو علامة compact_boundary، ثم يضيف أحدث أدوار ما بعد الحد حتى ميزانية أحرف محددة. تُسقط أدوار ما قبل الحد لأن الملخص يمثلها بالفعل.
• تُدمج كتل الأدوات في تلميحات مختصرة مثل (tool call: name) و (tool result: …) للحفاظ على ميزانية الموجه منضبطة. يُوسم الملخص بـ (truncated) إذا تجاوز الحد.
• تعتمد انتقالات الاحتياط من claude-cli إلى claude-cli للموفّر نفسه على --resume الخاص بـ Claude وتتخطى التمهيد.
• يعيد البذر استخدام التحقق الحالي من مسار ملف جلسة Claude، لذلك لا يمكن قراءة مسارات عشوائية.

​

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

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

​

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

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

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

​

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

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

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

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

​

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

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

api.registerTextTransforms({
  input: [
    { from: /red basket/g, to: "blue basket" },
    { from: /paper ticket/g, to: "digital ticket" },
    { from: /left shelf/g, to: "right shelf" },
  ],
  output: [
    { from: /blue basket/g, to: "red basket" },
    { from: /digital ticket/g, to: "paper ticket" },
    { from: /right shelf/g, to: "left shelf" },
  ],
});

​

تراكبات MCP المجمّعة

• claude-cli: ملف إعداد MCP صارم مولّد
• codex-cli: تجاوزات إعداد مضمنة لـ mcp_servers؛ يتم تمييز خادم OpenClaw loopback المولّد بوضع موافقة أدوات خاص بكل خادم في Codex حتى لا تتوقف استدعاءات MCP بسبب مطالبات الموافقة المحلية
• google-gemini-cli: ملف إعدادات نظام Gemini مولّد

• ينشئ خادم MCP عبر HTTP بنمط loopback يعرّض أدوات Gateway لعملية CLI
• يصادق الجسر باستخدام رمز لكل جلسة (OPENCLAW_MCP_TOKEN)
• يقيّد الوصول إلى الأدوات بسياق الجلسة والحساب والقناة الحالية
• يحمّل خوادم bundle-MCP الممكّنة لمساحة العمل الحالية
• يدمجها مع أي شكل موجود لإعدادات/ضبط MCP للواجهة الخلفية
• يعيد كتابة إعداد التشغيل باستخدام وضع التكامل المملوك للواجهة الخلفية من الامتداد المالك

​

القيود

• لا توجد استدعاءات مباشرة لأدوات OpenClaw. لا يحقن OpenClaw استدعاءات أدوات في بروتوكول واجهة CLI الخلفية. لا ترى الواجهات الخلفية أدوات Gateway إلا عندما تختار bundleMcp: true.
• البث خاص بكل واجهة خلفية. تبث بعض الواجهات الخلفية JSONL؛ وتنتظر أخرى حتى الخروج.
• المخرجات المنظمة تعتمد على تنسيق JSON الخاص بـ CLI.
• جلسات Codex CLI تستأنف عبر إخراج نصي (بدون JSONL)، وهو أقل تنظيمًا من تشغيل --json الأولي. لا تزال جلسات OpenClaw تعمل بشكل طبيعي.

​

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

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

​

ذات صلة

• دليل تشغيل Gateway
• النماذج المحلية