CLI बैकएंड

OpenClaw API प्रदाताओं के डाउन होने, रेट-लिमिटेड होने या अस्थायी रूप से गलत व्यवहार करने पर स्थानीय AI CLIs को केवल-टेक्स्ट fallback के रूप में चला सकता है। यह जानबूझकर रूढ़िवादी है:

• OpenClaw टूल सीधे inject नहीं किए जाते, लेकिन bundleMcp: true वाले बैकएंड loopback MCP ब्रिज के जरिए gateway टूल प्राप्त कर सकते हैं।
• इसका समर्थन करने वाली CLIs के लिए JSONL स्ट्रीमिंग।
• सत्र समर्थित हैं (इसलिए फॉलो-अप टर्न सुसंगत रहते हैं)।
• इमेज pass through की जा सकती हैं अगर CLI इमेज पाथ स्वीकार करती है।

इसे प्राथमिक पथ के बजाय एक सुरक्षा जाल के रूप में डिज़ाइन किया गया है। इसका उपयोग तब करें जब आप बाहरी APIs पर निर्भर हुए बिना "हमेशा काम करता है" टेक्स्ट प्रतिक्रियाएँ चाहते हों।

अगर आप ACP सत्र नियंत्रणों, बैकग्राउंड टास्क, थ्रेड/बातचीत बाइंडिंग और स्थायी बाहरी कोडिंग सत्रों के साथ पूरा harness runtime चाहते हैं, तो इसके बजाय ACP एजेंट का उपयोग करें। CLI बैकएंड ACP नहीं हैं।

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

आप Claude Code CLI का उपयोग बिना किसी config के कर सकते हैं (bundled Anthropic Plugin एक default बैकएंड register करता है):

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

जब कोई explicit agent list configure नहीं की जाती, तो main default agent id होता है। अगर आप कई agents का उपयोग करते हैं, तो इसे उस agent id से बदलें जिसे आप चलाना चाहते हैं।

अगर आपका gateway launchd/systemd के तहत चलता है और PATH minimal है, तो केवल command path जोड़ें:

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

बस इतना ही। CLI के अलावा कोई keys या अतिरिक्त auth config आवश्यक नहीं है।

अगर आप gateway host पर bundled CLI बैकएंड को primary message provider के रूप में उपयोग करते हैं, तो OpenClaw अब owning bundled Plugin को auto-load करता है जब आपका config उस बैकएंड को model ref में या agents.defaults.cliBackends के तहत explicit रूप से reference करता है।

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

अपनी fallback list में CLI बैकएंड जोड़ें ताकि यह केवल primary models के विफल होने पर चले:

{  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 बैकएंड models भी वहाँ शामिल करने होंगे।
• अगर primary provider विफल होता है (auth, rate limits, timeouts), तो OpenClaw अगला CLI बैकएंड आज़माएगा।

Configuration overview

सभी CLI बैकएंड यहाँ रहते हैं:

agents.defaults.cliBackends

हर entry एक provider id (जैसे claude-cli, my-cli) से keyed होती है। provider id आपके model ref का बायाँ हिस्सा बन जाता है:

<provider>/<model>

उदाहरण 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/...) के आधार पर बैकएंड चुनता है।
2. उसी OpenClaw prompt + workspace context का उपयोग करके system prompt बनाता है।
3. session id (अगर समर्थित हो) के साथ CLI execute करता है ताकि history consistent रहे। bundled claude-cli बैकएंड हर OpenClaw session के लिए एक Claude stdio process जीवित रखता है और follow-up turns को stream-json stdin पर भेजता है।
4. Output parse करता है (JSON या plain text) और final text return करता है।
5. प्रति बैकएंड session ids persist करता है, ताकि follow-ups वही CLI session फिर से उपयोग करें।

bundled Anthropic claude-cli बैकएंड OpenClaw skills के लिए Claude Code के native skill resolver को prefer करता है। जब current skills snapshot में materialized path वाला कम से कम एक selected skill शामिल होता है, तो OpenClaw --plugin-dir के साथ temporary Claude Code Plugin pass करता है और appended system prompt से duplicate OpenClaw skills catalog हटा देता है। अगर snapshot में कोई materialized Plugin skill नहीं है, तो OpenClaw prompt catalog को fallback के रूप में रखता है। Skill env/API key overrides अभी भी run के लिए child process environment पर OpenClaw द्वारा apply किए जाते हैं।

Claude CLI का अपना noninteractive permission mode भी है। OpenClaw उसे Claude-specific policy config जोड़ने के बजाय existing exec policy से map करता है। OpenClaw-managed Claude live sessions के लिए, effective OpenClaw exec policy authoritative है: YOLO (tools.exec.security: "full" और tools.exec.ask: "off") Claude को --permission-mode bypassPermissions के साथ launch करता है, जबकि restrictive effective exec policy Claude को --permission-mode default के साथ launch करता है। Per-agent agents.list[].tools.exec settings उस agent के लिए global tools.exec को override करती हैं। Raw Claude backend args में अभी भी --permission-mode शामिल हो सकता है, लेकिन live Claude launches उस flag को effective OpenClaw exec policy से match करने के लिए normalize करते हैं।

bundled Anthropic claude-cli बैकएंड OpenClaw /think levels को non-off levels के लिए Claude Code के native --effort flag से भी map करता है। minimal और low low पर map होते हैं, adaptive और medium medium पर map होते हैं, और high, xhigh, और max सीधे map होते हैं। अन्य CLI बैकएंड को /think के spawned CLI को प्रभावित कर सकने से पहले अपने owning Plugin से equivalent argv mapper declare करवाना होगा।

OpenClaw bundled claude-cli बैकएंड का उपयोग कर सके, उससे पहले Claude Code स्वयं उसी host पर पहले से logged in होना चाहिए:

claude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

Docker installs में Claude Code persisted container home के अंदर installed और logged in होना चाहिए, केवल host पर नहीं। देखें Docker में Claude CLI बैकएंड.

agents.defaults.cliBackends.claude-cli.command का उपयोग केवल तब करें जब claude binary पहले से PATH पर न हो।

Sessions

• अगर CLI sessions support करती है, तो sessionArg (जैसे --session-id) या sessionArgs (placeholder {sessionId}) set करें जब ID को कई flags में insert करना हो।
• अगर CLI अलग flags के साथ resume subcommand का उपयोग करती है, तो resumeArgs (resuming के समय args को replace करता है) और optional 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 का फिर से उपयोग करें। 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 के विरुद्ध verify किया जाता है, इसलिए phantom bindings --resume के तहत silently fresh Claude CLI session शुरू करने के बजाय reason=transcript-missing के साथ clear हो जाती हैं।
• Claude live sessions bounded JSONL output guards रखते हैं। Defaults प्रति turn 8 MiB और 20,000 raw JSONL lines तक allow करते हैं। Tool-heavy Claude turns इन्हें प्रति बैकएंड 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 होते हैं। उन short sessions को recover करने के लिए जो compaction से पहले invalidated हो जाते हैं, कोई बैकएंड reseedFromRawTranscriptWhenUncompacted: true से opt in कर सकता है। OpenClaw अभी भी raw transcript reseed को bounded रखता है और इसे safe invalidations जैसे missing CLI transcripts, system-prompt/MCP changes, या session-expired retry तक सीमित करता है; auth profile या credential-epoch changes कभी raw transcript history reseed नहीं करते।

Serialization notes:

• 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, या OAuth account identity शामिल है जब CLI कोई expose करती है। 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

जब कोई claude-cli attempt agents.defaults.model.fallbacks में किसी non-CLI candidate पर fail over करता है, तो OpenClaw Claude Code के local JSONL transcript at ~/.claude/projects/ से harvested context prelude के साथ अगले attempt को seed करता है। इस seed के बिना, fallback provider cold start करेगा क्योंकि OpenClaw का अपना session transcript claude-cli runs के लिए empty होता है।

• prelude latest /compact summary या compact_boundary marker को prefer करता है, फिर char budget तक सबसे recent post-boundary turns append करता है। Pre-boundary turns drop किए जाते हैं क्योंकि summary पहले से उन्हें represent करती है।
• Tool blocks को prompt budget honest रखने के लिए compact (tool call: name) और (tool result: …) hints में coalesce किया जाता है। Summary overflow होने पर (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 नहीं किए जा सकते।

इमेज (pass-through)

अगर आपकी CLI image paths स्वीकार करती है, तो imageArg set करें:

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

OpenClaw base64 images को temp files में write करेगा। अगर imageArg set है, तो वे paths CLI args के रूप में pass किए जाते हैं। अगर imageArg missing है, तो OpenClaw file paths को prompt (path injection) में append करता है, जो उन CLIs के लिए पर्याप्त है जो plain paths से local files auto- load करती हैं।

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 modes:

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

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

बंडल किए गए CLI बैकएंड डिफ़ॉल्ट्स अपने स्वामी Plugin के साथ रहते हैं। उदाहरण के लिए, Anthropic claude-cli का स्वामी है और Google google-gemini-cli का स्वामी है। OpenAI Codex एजेंट रन openai/* के माध्यम से Codex app-server harness का उपयोग करते हैं; OpenClaw अब बंडल किया हुआ codex-cli बैकएंड पंजीकृत नहीं करता।

बंडल किया गया Anthropic Plugin claude-cli के लिए एक डिफ़ॉल्ट पंजीकृत करता है:

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

बंडल किया गया Google Plugin भी google-gemini-cli के लिए एक डिफ़ॉल्ट पंजीकृत करता है:

• 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"]

पूर्वापेक्षा: स्थानीय Gemini CLI इंस्टॉल होना चाहिए और PATH पर gemini के रूप में उपलब्ध होना चाहिए (brew install gemini-cli या npm install -g @google/gemini-cli)।

Gemini CLI आउटपुट नोट्स:

• डिफ़ॉल्ट 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 से निकालता है।

केवल आवश्यकता होने पर ओवरराइड करें (आम: पूर्ण command पाथ)।

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

CLI बैकएंड डिफ़ॉल्ट्स अब Plugin सतह का हिस्सा हैं:

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

जिन Plugins को छोटे प्रॉम्प्ट/संदेश संगतता shims चाहिए, वे provider या CLI बैकएंड बदले बिना द्विदिश टेक्स्ट transforms घोषित कर सकते हैं:

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

input CLI को पास किए गए सिस्टम प्रॉम्प्ट और उपयोगकर्ता प्रॉम्प्ट को फिर से लिखता है। output OpenClaw द्वारा अपने नियंत्रण markers और channel delivery संभालने से पहले streamed assistant text और parsed final text को फिर से लिखता है। provider-backed model calls के लिए, output stream repair के बाद और tool execution से पहले structured tool-call arguments के अंदर string values को भी पुनर्स्थापित करता है। Raw provider JSON fragments अपरिवर्तित रहते हैं; consumers को structured partial, end, या result payload का उपयोग करना चाहिए।

Provider-specific JSONL events emit करने वाले CLIs के लिए, उस बैकएंड के config पर jsonlDialect सेट करें। समर्थित dialects Claude Code-compatible streams के लिए claude-stream-json और Gemini CLI stream-json events के लिए gemini-stream-json हैं।

Native compaction स्वामित्व

कुछ CLI बैकएंड ऐसा एजेंट चलाते हैं जो अपना स्वयं का transcript compact करता है, इसलिए OpenClaw को उनके विरुद्ध अपना safeguard summarizer नहीं चलाना चाहिए - ऐसा करने से बैकएंड की अपनी compaction से टकराव होता है और turn hard-fail हो सकता है।

claude-cli में कोई harness endpoint नहीं है - Claude Code internally compact करता है - इसलिए यह ownsNativeCompaction: true घोषित करता है, और OpenClaw compaction path से no-op लौटाता है। Codex जैसे native-harness sessions इसके बजाय अपने harness compaction endpoint पर route करते रहते हैं।

क्योंकि बैकएंड compaction का स्वामी है, केवल OpenClaw के safeguard को claude-cli session पर fire होने से रोकने के लिए contextTokens: 1_000_000 सेट करने वाला पुराना stopgap अब आवश्यक नहीं है - opt-out उसे बदल देता है।

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

ownsNativeCompaction केवल उस बैकएंड के लिए घोषित करें जो वास्तव में अपनी compaction का स्वामी हो: उसे अपने context window के पास पहुंचने पर अपने transcript को भरोसेमंद ढंग से bound करना चाहिए और resumable session persist करना चाहिए (जैसे --resume / --session-id); अन्यथा deferred session budget से ऊपर रह सकता है। Matching agentHarnessId sessions अभी भी harness endpoint पर route करते हैं।

Bundle MCP overlays

CLI बैकएंड OpenClaw tool calls सीधे प्राप्त नहीं करते, लेकिन कोई बैकएंड bundleMcp: true के साथ generated MCP config overlay में opt in कर सकता है।

वर्तमान बंडल व्यवहार:

• claude-cli: generated strict MCP config file
• google-gemini-cli: generated Gemini system settings file

जब bundle MCP सक्षम होता है, OpenClaw:

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

यदि कोई MCP server enabled नहीं है, तो OpenClaw तब भी strict config inject करता है जब कोई बैकएंड bundle MCP में opt in करता है ताकि background runs isolated रहें।

Session-scoped bundled MCP runtimes को session के भीतर reuse के लिए cache किया जाता है, फिर mcp.sessionIdleTtlMs milliseconds के idle time के बाद reap किया जाता है (डिफ़ॉल्ट 10 minutes; disable करने के लिए 0 सेट करें)। Auth probes, slug generation, और active-memory recall जैसे one-shot embedded runs run end पर cleanup request करते हैं ताकि stdio children और Streamable HTTP/SSE streams run से अधिक समय तक जीवित न रहें।

Reseed history cap

जब कोई fresh CLI session किसी पिछले OpenClaw transcript से seed किया जाता है (उदाहरण के लिए session_expired retry के बाद), तो rendered <conversation_history> block को cap किया जाता है ताकि reseed prompts बेकाबू न बढ़ें। डिफ़ॉल्ट 12288 characters है (लगभग 3000 tokens)।

Claude CLI बैकएंड resolved Claude context tier से निकली बड़ी cap स्वतः उपयोग करते हैं। Standard 200K-token Claude runs बड़ा transcript slice रखते हैं, और 1M-token Claude runs उससे भी बड़ा slice रखते हैं, जबकि अन्य CLI बैकएंड conservative default रखते हैं।

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

सीमाएं

• सीधे 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 को full path पर सेट करें।
• गलत model name: provider/model → CLI model map करने के लिए modelAliases का उपयोग करें।
• Session continuity नहीं है: सुनिश्चित करें कि sessionArg सेट है और sessionMode none नहीं है।
• Images ignore हो रही हैं: imageArg सेट करें (और verify करें कि CLI file paths support करता है)।

संबंधित

• Gateway runbook
• Local models