CLI बैकएंड

• OpenClaw tools सीधे inject नहीं किए जाते, लेकिन bundleMcp: true वाले backends loopback MCP bridge के जरिए gateway tools प्राप्त कर सकते हैं।
• इसे support करने वाले CLIs के लिए JSONL streaming।
• Sessions समर्थित हैं (ताकि follow-up turns सुसंगत रहें)।
• Images को pass through किया जा सकता है अगर CLI image paths स्वीकार करता है।

​

शुरुआती लोगों के लिए आसान quick start

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

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

​

इसे fallback के रूप में उपयोग करना

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

• अगर आप agents.defaults.models (allowlist) उपयोग करते हैं, तो आपको अपने CLI backend models भी वहाँ शामिल करने होंगे।
• अगर primary provider fail होता है (auth, rate limits, timeouts), तो OpenClaw अगला CLI backend आजमाएगा।

​

Configuration overview

agents.defaults.cliBackends

<provider>/<model>

​

Example configuration

{
  agents: {
    defaults: {
      cliBackends: {
        "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. provider prefix (claude-cli/...) के आधार पर backend चुनता है।
2. उसी OpenClaw prompt + workspace context का उपयोग करके system prompt बनाता है।
3. session id (अगर supported हो) के साथ CLI execute करता है ताकि history consistent रहे। bundled claude-cli backend हर OpenClaw session के लिए Claude stdio process alive रखता है और follow-up turns को stream-json stdin पर भेजता है।
4. output parse करता है (JSON या plain text) और final text लौटाता है।
5. प्रति backend session ids persist करता है, ताकि follow-ups उसी CLI session को reuse करें।

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

​

Sessions

• अगर CLI sessions support करता है, तो sessionArg (जैसे --session-id) या sessionArgs (placeholder {sessionId}) set करें जब ID को multiple flags में insert करना हो।
• अगर CLI अलग flags के साथ resume subcommand उपयोग करता है, तो resumeArgs (resuming के समय args को replace करता है) और वैकल्पिक रूप से resumeOutput (non-JSON resumes के लिए) set करें।
• sessionMode:
  • always: हमेशा session id भेजें (अगर कोई stored न हो तो नया UUID)।
  • existing: session id केवल तभी भेजें जब पहले से कोई stored हो।
  • none: कभी session id न भेजें।
• claude-cli defaults liveSession: "claude-stdio", output: "jsonl", और input: "stdin" पर हैं, ताकि follow-up turns active रहते समय live Claude process को reuse करें। Warm stdio अब default है, उन custom configs के लिए भी जो transport fields omit करते हैं। अगर Gateway restart होता है या idle process exit होता है, OpenClaw stored Claude session id से resume करता है। Stored session ids resume से पहले existing readable project transcript के विरुद्ध verified होते हैं, इसलिए phantom bindings --resume के तहत चुपचाप fresh Claude CLI session शुरू करने के बजाय reason=transcript-missing के साथ cleared होते हैं।
• Claude live sessions bounded JSONL output guards रखते हैं। Defaults हर turn में 8 MiB और 20,000 raw JSONL lines तक allow करते हैं। Tool-heavy Claude turns इन्हें प्रति backend agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars और maxTurnLines के साथ बढ़ा सकते हैं; OpenClaw उन settings को 64 MiB और 100,000 lines तक clamp करता है।
• Stored CLI sessions provider-owned continuity हैं। implicit daily session reset उन्हें cut नहीं करता; /reset और explicit session.reset policies अभी भी ऐसा करते हैं।
• Fresh CLI sessions सामान्यतः केवल OpenClaw के Compaction summary और post-compaction tail से reseed होते हैं। Compaction से पहले invalidated short sessions को recover करने के लिए, backend reseedFromRawTranscriptWhenUncompacted: true के साथ opt in कर सकता है। OpenClaw फिर भी raw transcript reseed bounded रखता है और उसे missing CLI transcripts, system-prompt/MCP changes, या session-expired retry जैसी safe invalidations तक सीमित करता है; auth profile या credential-epoch changes कभी raw transcript history reseed नहीं करते।

• serialize: true same-lane runs को ordered रखता है।
• अधिकांश CLIs एक provider lane पर serialize करते हैं।
• selected auth identity बदलने पर OpenClaw stored CLI session reuse drop कर देता है, जिसमें changed auth profile id, static API key, static token, या CLI द्वारा expose की गई OAuth account identity शामिल है। OAuth access और refresh token rotation stored CLI session को cut नहीं करता। अगर CLI stable OAuth account id expose नहीं करता है, तो OpenClaw उस CLI को resume permissions enforce करने देता है।

​

claude-cli sessions से fallback prelude

• prelude latest /compact summary या compact_boundary marker को prefer करता है, फिर char budget तक सबसे हाल के post-boundary turns append करता है। Pre-boundary turns drop किए जाते हैं क्योंकि summary पहले से उन्हें represent करता है।
• Tool blocks को compact (tool call: name) और (tool result: …) hints में coalesce किया जाता है ताकि prompt budget ईमानदार रहे। Overflow होने पर summary को (truncated) label किया जाता है।
• Same-provider claude-cli से claude-cli fallbacks Claude के अपने --resume पर rely करते हैं और prelude skip करते हैं।
• seed existing Claude session-file path validation reuse करता है, इसलिए arbitrary paths read नहीं किए जा सकते।

​

Images (pass-through)

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

​

Inputs / outputs

• output: "json" (default) JSON parse करने और text + session id extract करने की कोशिश करता है।
• Gemini CLI JSON output के लिए, OpenClaw reply text को response से और usage को stats से पढ़ता है जब usage missing या empty हो। bundled Gemini CLI default stream-json उपयोग करता है, लेकिन पुराने --output-format json overrides अभी भी JSON parser उपयोग करते हैं।
• output: "jsonl" JSONL streams parse करता है और final agent message plus session identifiers extract करता है जब present हों।
• output: "text" stdout को final response मानता है।

• input: "arg" (डिफ़ॉल्ट) प्रॉम्प्ट को अंतिम CLI arg के रूप में पास करता है।
• input: "stdin" प्रॉम्प्ट को stdin के ज़रिए भेजता है।
• यदि प्रॉम्प्ट बहुत लंबा है और maxPromptArgChars सेट है, तो stdin उपयोग किया जाता है।

​

डिफ़ॉल्ट (Plugin-स्वामित्व वाले)

• command: "claude"
• args: ["-p","--output-format","stream-json","--include-partial-messages","--verbose", ...]
• output: "jsonl"
• input: "stdin"
• modelArg: "--model"
• sessionMode: "always"

• command: "gemini"
• args: ["--skip-trust", "--approval-mode", "auto_edit", "--output-format", "stream-json", "--prompt", "{prompt}"]
• resumeArgs: ["--skip-trust", "--approval-mode", "auto_edit", "--resume", "{sessionId}", "--output-format", "stream-json", "--prompt", "{prompt}"]
• output: "jsonl"
• resumeOutput: "jsonl"
• jsonlDialect: "gemini-stream-json"
• imageArg: "@"
• imagePathScope: "workspace"
• modelArg: "--model"
• sessionMode: "existing"
• sessionIdFields: ["session_id", "sessionId"]

• डिफ़ॉल्ट stream-json पार्सर सहायक message इवेंट, टूल इवेंट, अंतिम result उपयोग, और घातक Gemini त्रुटि इवेंट पढ़ता है।
• यदि आप Gemini args को --output-format json पर ओवरराइड करते हैं, तो OpenClaw उस बैकएंड को वापस output: "json" में सामान्यीकृत करता है और JSON response फ़ील्ड से उत्तर टेक्स्ट पढ़ता है।
• जब usage अनुपस्थित या खाली हो, तो उपयोग stats पर वापस जाता है।
• stats.cached को OpenClaw cacheRead में सामान्यीकृत किया जाता है।
• यदि stats.input गायब है, तो OpenClaw इनपुट टोकन stats.input_tokens - stats.cached से निकालता है।

​

Plugin-स्वामित्व वाले डिफ़ॉल्ट

• Plugins उन्हें api.registerCliBackend(...) के साथ पंजीकृत करते हैं।
• बैकएंड id मॉडल refs में provider prefix बन जाता है।
• agents.defaults.cliBackends.<id> में उपयोगकर्ता कॉन्फ़िगरेशन अब भी Plugin डिफ़ॉल्ट को ओवरराइड करता है।
• बैकएंड-विशिष्ट कॉन्फ़िगरेशन सफ़ाई वैकल्पिक normalizeConfig hook के माध्यम से Plugin-स्वामित्व में रहती है।

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" },
  ],
});

​

नेटिव Compaction स्वामित्व

api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });

​

बंडल MCP ओवरले

• claude-cli: generate की गई strict MCP config file
• google-gemini-cli: generate की गई Gemini system settings file

• एक loopback HTTP MCP server spawn करता है जो gateway tools को CLI process के सामने expose करता है
• per-session token (OPENCLAW_MCP_TOKEN) के साथ bridge को authenticate करता है
• tool access को वर्तमान session, account, और channel context तक scope करता है
• वर्तमान workspace के लिए enabled bundle-MCP servers load करता है
• उन्हें किसी भी मौजूदा बैकएंड MCP config/settings shape के साथ merge करता है
• owning extension से बैकएंड-स्वामित्व वाले integration mode का उपयोग करके launch config को फिर से लिखता है

​

Reseed history cap

• cap केवल reseed prompt के prior-history block को नियंत्रित करता है। Live-session output limits को reliability.outputLimits के अंतर्गत अलग से tune किया जाता है (Sessions देखें)।

​

सीमाएँ

• कोई direct OpenClaw tool calls नहीं। OpenClaw CLI बैकएंड protocol में tool calls inject नहीं करता। बैकएंड केवल gateway tools देखते हैं जब वे bundleMcp: true में opt in करते हैं।
• Streaming बैकएंड-विशिष्ट है। कुछ बैकएंड JSONL stream करते हैं; अन्य exit तक buffer करते हैं।
• Structured outputs CLI के JSON format पर निर्भर करते हैं।

​

समस्या निवारण

• CLI नहीं मिला: command को पूर्ण path पर सेट करें।
• गलत model name: provider/model → CLI model को map करने के लिए modelAliases का उपयोग करें।
• कोई session continuity नहीं: सुनिश्चित करें कि sessionArg सेट है और sessionMode none नहीं है।
• Images ignored: imageArg सेट करें (और सत्यापित करें कि CLI file paths को support करता है)।

​

संबंधित

• Gateway runbook
• Local models