CLI backends
기준일: 2026-07-26
공식 기준: CLI backends
CLI backends 문서는 OpenClaw 공식 문서(gateway/cli-backends)를 한국어로 정리한 가이드입니다. CLI backends: local AI CLI fallback with optional MCP tool bridge 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.
핵심 요약
CLI backends: local AI CLI fallback with optional MCP tool bridge
한국어 가이드 범위: gateway/cli-backends 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.
문서 구성
공식 문서의 주요 섹션은 다음과 같습니다.
- 빠른 시작
- Using it as a fallback
- 구성
- 동작 방식
- Timeouts and long-running work
- Return to the 48-hour default:
- Or choose an explicit 12-hour limit:
- Claude CLI specifics
- Claude browser tools and 1Password sign-in
- 세션
- Fallback prelude from claude-cli sessions
- Images
- Inputs and outputs
- Plugin-owned defaults
- Text transform overlays
- Native compaction ownership
- Bundle MCP overlays
- Reseed history cap
- 제한 사항
- 트러블슈팅
- 관련 문서
상세 내용
본문
OpenClaw can run a local AI CLI as a text-only fallback when API providers are down, rate-limited, or misbehaving. It is intentionally conservative:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- OpenClaw tools are not injected directly, but a backend with
bundleMcp: truecan receive gateway tools through a loopback MCP bridge. - JSONL streaming for CLIs that support it.
- Sessions are supported, so follow-up turns stay coherent.
- Images pass through if the CLI accepts image paths.
빠른 시작
The bundled Anthropic plugin registers a default claude-cli backend, so it works with no config beyond having Claude Code installed and logged in:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
openclaw agent --agent main --message "hi" --model claude-cli/claude-sonnet-4-6
Using it as a fallback
Add the CLI backend to your fallback list so it only runs when primary models fail:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-opus-4",
fallbacks: ["claude-cli/claude-sonnet-4-6"],
},
models: {
"anthropic/claude-opus-4": { alias: "Opus" },
"claude-cli/claude-sonnet-4-6": {},
},
},
},
}
구성
Users choose a registered backend through the model and runtime policy. Keep the model ref canonical and select the CLI runtime per model:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
{
agents: {
defaults: {
model: "anthropic/claude-opus-5",
models: {
"anthropic/claude-opus-5": {
agentRuntime: { id: "claude-cli" },
},
},
},
},
}
동작 방식
- Selects a backend by provider prefix (
claude-cli/...). 2. Builds a system prompt using the same OpenClaw prompt and workspace context. 3. Executes the CLI with a session id (if supported) so history stays consistent. The bundledclaude-clibackend keeps a Claude stdio process alive per OpenClaw session and sends follow-up turns over stream-json stdin. 4. Parses output (JSON or plain text) and returns the final text. 5. Persists session ids per backend so follow-ups reuse the same CLI session.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Timeouts and long-running work
CLI backends have two independent limits:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
agents.defaults.timeoutSecondslimits the whole agent turn. Normal Gateway turns inherit the 48-hour default;0makes the turn budget unlimited. A stored override such as600replaces that default.- The CLI no-output watchdog stops a subprocess that remains silent. Each backend plugin owns separate fresh/resume profiles, and the watchdog remains active even when the overall turn budget is unlimited.
Return to the 48-hour default:
openclaw config unset agents.defaults.timeoutSeconds
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Or choose an explicit 12-hour limit:
openclaw config set agents.defaults.timeoutSeconds 43200 ```
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Claude CLI specifics
The bundled claude-cli backend prefers Claude Code's native skill resolver. When the current skills snapshot has at least one selected skill with a materialized path, OpenClaw passes a temporary Claude Code plugin via --plugin-dir and omits the duplicate OpenClaw skills catalog from the appended system prompt. Without a materialized plugin skill, OpenClaw keeps the prompt catalog as a fallback. Skill env/API key overrides still apply to the child process environment for the run.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Claude browser tools and 1Password sign-in
Claude Code can drive a Chrome browser through the Claude in Chrome extension, including 1Password for Claude credential autofill. The bundled backend does not enable it; register a CLI backend plugin that appends --chrome to the launch args of a claude-stream-json-dialect backend. OpenClaw preserves a configured --chrome on normal runs and always forces --no-chrome on runs with a restricted tool policy, such as side questions. The Chrome window, the extension, and any 1Password approval prompts live on the gateway host, so someone must be at that machine to approve credential use.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default
세션
Serialization: serialize: true keeps same-lane runs ordered (most CLIs serialize on one provider lane). OpenClaw also drops stored CLI session reuse when the selected auth identity changes, including a changed auth profile id, static API key, static token, or OAuth account identity when the CLI exposes one; OAuth access/refresh token rotation alone does not cut the session. If a CLI has no stable OAuth account id, OpenClaw lets that CLI enforce its own resume permissions.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- If the CLI supports sessions, set
sessionArgswith a{sessionId}placeholder (for example["--session-id", "{sessionId}"]). - If the CLI uses a resume subcommand with different flags, set
resumeArgs(replacesargswhen resuming) and optionallyresumeOutputfor non-JSON resumes. sessionMode:always: always send a session id (new UUID if none stored).existing: only send a session id if one was stored before.none: never send a session id.claude-clidefaults toliveSession: "claude-stdio",output: "jsonl", andinput: "stdin", so follow-up turns reuse the live Claude process while it is active, including for custom configs that omit transport fields. If the gateway restarts or the idle process exits, OpenClaw resumes from the stored Claude session id. Stored session ids are verified against a readable project transcript before resume; a missing transcript clears the binding (logged asreason=transcript-missing) instead of silently starting a fresh session under--resume.- Claude live sessions keep bounded JSONL output guards: 8 MiB and 20,000 raw JSONL lines per turn.
- Stored CLI sessions are provider-owned continuity. Automatic reset is disabled by default;
/resetand explicit daily or idlesession.resetpolicies still cut them. - Fresh CLI sessions normally reseed only from OpenClaw's compaction summary plus the post-compaction tail. To recover short sessions invalidated before compaction, a backend can opt in with
reseedFromRawTranscriptWhenUncompacted: true. Raw transcript reseed stays bounded and limited to safe invalidations, such as a missing CLI transcript, an orphaned tool-use tail, message-policy/system-prompt/cwd/MCP changes, or a session-expired retry; auth profile or credential-epoch changes never reseed raw transcript history.
Fallback prelude from claude-cli sessions
When a claude-cli attempt fails over to a non-CLI candidate in agents.defaults.model.fallbacks, OpenClaw seeds the next attempt with a context prelude harvested from Claude Code's local JSONL transcript (under ~/.claude/projects/, keyed per workspace). Without this seed the fallback provider starts cold, since OpenClaw's own session transcript is empty for claude-cli runs.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- The prelude prefers the latest
/compactsummary orcompact_boundarymarker, then appends the most recent post-boundary turns up to a char budget. Pre-boundary turns are dropped because the summary already represents them. - Tool blocks are coalesced to compact
(tool call: name)and(tool result: …)hints to keep the prompt budget honest; an oversized summary is truncated and labeled(truncated). - Same-provider
claude-clitoclaude-clifallbacks rely on Claude's own--resumeand skip the prelude. - The seed reuses the existing Claude session-file path validation, so arbitrary paths cannot be read.
Images
Plugin authors declare image-path support with imageArg:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
imageArg: "--image",
imageMode: "repeat"
Inputs and outputs
주요 항목:
output: "text"(default) treats stdout as the final response.output: "json"tries to parse JSON and extract text plus a session id.output: "jsonl"parses a JSONL stream and extracts the final agent message plus session identifiers when present.- For Gemini CLI JSON output, OpenClaw reads reply text from
responseand usage fromstatswhenusageis missing or empty. The bundled Gemini CLI adapter usesstream-json. input: "arg"(default) passes the prompt as the last CLI arg.input: "stdin"sends the prompt via stdin.- If the prompt is very long and
maxPromptArgCharsis set, stdin is used instead.
Plugin-owned defaults
CLI backend defaults are part of the plugin surface:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- Plugins register them with
api.registerCliBackend(...). - The backend
idbecomes the provider prefix in model refs. - Command, argv, environment, parser, session, and watchdog behavior stays in plugin code.
- Backend-specific normalization stays plugin-owned through the optional
normalizeConfighook. - The default
stream-jsonparser reads assistantmessageevents, tool events, finalresultusage, and fatal Gemini error events. - Usage falls back to
statswhenusageis absent or empty;stats.cachednormalizes into OpenClawcacheRead, and ifstats.inputis missing, input tokens derive fromstats.input_tokens - stats.cached.
| Key | Value |
|---|---|
command |
claude |
args |
-p --output-format stream-json --include-partial-messages --verbose --setting-sources user --allowedTools mcp__openclaw__* --disallowedTools ScheduleWakeup,CronCreate,Bash(run_in_background:true),Monitor |
output |
jsonl |
input |
stdin |
modelArg |
--model |
sessionArgs |
["--session-id", "{sessionId}"] |
sessionMode |
always |
imageArg |
@ |
imagePathScope |
workspace |
systemPromptFileArg |
--append-system-prompt-file |
systemPromptMode |
append |
| Key | Value |
|---|---|
command |
gemini |
args |
--skip-trust --approval-mode auto_edit --output-format stream-json --prompt {prompt} |
resumeArgs |
same, with --resume {sessionId} |
output / resumeOutput |
jsonl |
jsonlDialect |
gemini-stream-json |
imageArg |
@ |
imagePathScope |
workspace |
modelArg |
--model |
sessionMode |
existing |
sessionIdFields |
["session_id", "sessionId"] |
Text transform overlays
Plugins that need small prompt/message compatibility shims can declare bidirectional text transforms without replacing a provider or CLI backend:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
api.registerTextTransforms({
input: [{ from: /red basket/g, to: "blue basket" }],
output: [{ from: /blue basket/g, to: "red basket" }],
});
Native compaction ownership
Some CLI backends run an agent that compacts its own transcript, so OpenClaw must not run its safeguard summarizer against them — doing so fights the backend's own compaction and can hard-fail the turn.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });
Bundle MCP overlays
CLI backends do not receive OpenClaw tool calls directly, but a backend can opt into a generated MCP config overlay with bundleMcp: true. Current bundled behavior:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
claude-cli: generated strict MCP config file.google-gemini-cli: generated Gemini system settings file.- spawns a loopback HTTP MCP server that exposes gateway tools to the CLI process, authenticated with a per-run context grant (
OPENCLAW_MCP_TOKEN) active only for the current execution attempt; - binds tool access to the Gateway-selected session, account, and channel context instead of trusting child-process headers;
- loads enabled bundle-MCP servers for the current workspace and merges them with any existing backend MCP config/settings shape;
- rewrites the launch config using the backend-owned integration mode from the owning plugin.
Reseed history cap
When a fresh CLI session is seeded from a prior OpenClaw transcript (for example after a session_expired retry), the rendered `` block is capped to keep reseed prompts from exploding. The default is 12,288 characters (about 3,000 tokens).
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
제한 사항
주요 항목:
- OpenClaw does not inject tool calls into the CLI backend protocol. Backends only see gateway tools when they opt into
bundleMcp: true. - Streaming is backend-specific: some backends stream JSONL, others buffer until exit.
- Structured outputs depend on the CLI's own JSON format.
트러블슈팅
| Symptom | Fix |
|---|---|
| CLI not found | Put the CLI on the gateway service's PATH, or update the owning plugin's registered command. |
| Wrong model name | Update the plugin's modelAliases mapping. |
| No session continuity | Check the plugin's sessionArgs and sessionMode. |
| Images ignored | Check the plugin's imageArg and the CLI's file-path support. |
관련 문서
주요 항목:
- Gateway runbook
- Local models
실습 체크리스트
- 공식 문서와 로컬 버전을 대조합니다:
https://docs.openclaw.ai/gateway/cli-backends - 관련 CLI는
openclaw --help및 하위 명령--help로 옵션을 확인합니다. - 설정 변경 시
openclaw config/openclaw doctor로 유효성을 검사합니다. - Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.
자주 쓰는 명령·설정 예시
openclaw agent --agent main --message "hi" --model claude-cli/claude-sonnet-4-6
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-opus-4",
fallbacks: ["claude-cli/claude-sonnet-4-6"],
},
models: {
"anthropic/claude-opus-4": { alias: "Opus" },
"claude-cli/claude-sonnet-4-6": {},
},
},
},
}
{
agents: {
defaults: {
model: "anthropic/claude-opus-5",
models: {
"anthropic/claude-opus-5": {
agentRuntime: { id: "claude-cli" },
},
},
},
},
}
# Return to the 48-hour default:
openclaw config unset agents.defaults.timeoutSeconds
# Or choose an explicit 12-hour limit:
openclaw config set agents.defaults.timeoutSeconds 43200
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default
imageArg: "--image",
imageMode: "repeat"
관련 링크
이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.