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인 백엔드는 loopback MCP 브리지를 통해 gateway 도구를 받을 수 있습니다.
• 이를 지원하는 CLI를 위한 JSONL streaming.
• Sessions are supported됩니다(따라서 후속 턴이 일관성을 유지합니다).
• CLI가 이미지 경로를 허용하는 경우 Images can be passed through됩니다.

​

초보자 친화적 빠른 시작

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

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

​

fallback으로 사용하기

{
  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(allowlist)를 사용하는 경우, CLI 백엔드 모델도 거기에 포함해야 합니다.
• 기본 provider가 실패하면(auth, rate limits, timeouts), 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. provider prefix(codex-cli/...)를 기준으로 백엔드를 선택합니다.
2. 동일한 OpenClaw prompt + workspace context를 사용해 system prompt를 빌드합니다.
3. 지원되는 경우 session id로 CLI를 실행하여 기록이 일관되게 유지되도록 합니다. 번들 claude-cli 백엔드는 OpenClaw session마다 Claude stdio 프로세스를 살려 두고 후속 턴을 stream-json stdin으로 보냅니다.
4. 출력을 파싱(JSON 또는 일반 텍스트)하고 최종 텍스트를 반환합니다.
5. 백엔드별로 session ids를 영속화하여 후속 턴이 같은 CLI session을 재사용하도록 합니다.

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

​

Sessions

• CLI가 sessions를 지원하면 ID를 여러 flags에 삽입해야 할 때 sessionArg(예: --session-id) 또는 sessionArgs(placeholder {sessionId})를 설정하세요.
• CLI가 다른 flags를 가진 resume subcommand를 사용하는 경우, resumeArgs(resuming 시 args 대체)와 선택적으로 resumeOutput (non-JSON resumes용)을 설정하세요.
• sessionMode:
  • always: 항상 session id를 보냅니다(저장된 것이 없으면 새 UUID).
  • existing: 이전에 저장된 session id가 있을 때만 보냅니다.
  • none: session id를 절대 보내지 않습니다.
• claude-cli는 기본적으로 liveSession: "claude-stdio", output: "jsonl", input: "stdin"을 사용하므로 후속 턴은 활성 상태인 동안 live Claude process를 재사용합니다. Warm stdio는 이제 transport fields를 생략한 custom configs를 포함해 기본값입니다. Gateway가 재시작되거나 idle process가 종료되면, OpenClaw는 저장된 Claude session id에서 resume합니다. 저장된 session ids는 resume 전에 기존 readable project transcript와 대조해 검증되므로, phantom bindings는 --resume 아래에서 조용히 새 Claude CLI session을 시작하는 대신 reason=transcript-missing으로 지워집니다.
• Claude live sessions는 제한된 JSONL output guards를 유지합니다. 기본값은 턴당 최대 8 MiB 및 20,000 raw JSONL lines를 허용합니다. Tool-heavy Claude turns는 백엔드별로 agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars 및 maxTurnLines로 이를 늘릴 수 있습니다. OpenClaw는 해당 설정을 64 MiB 및 100,000 lines로 제한합니다.
• 저장된 CLI sessions는 provider-owned continuity입니다. 암시적 daily session reset은 이를 끊지 않습니다. /reset 및 명시적 session.reset policies는 여전히 끊습니다.
• Fresh CLI sessions는 일반적으로 OpenClaw의 compaction summary와 post-compaction tail에서만 reseed합니다. Compaction 전에 invalidated된 짧은 sessions를 복구하려면, 백엔드가 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는 같은 lane의 실행 순서를 유지합니다.
• 대부분의 CLI는 하나의 provider lane에서 serialize합니다.
• OpenClaw는 선택된 auth identity가 변경되면 저장된 CLI session reuse를 중단합니다. 여기에는 CLI가 노출하는 경우 변경된 auth profile id, static API key, static token, OAuth account identity가 포함됩니다. OAuth access 및 refresh token rotation은 저장된 CLI session을 끊지 않습니다. CLI가 stable OAuth account id를 노출하지 않으면, OpenClaw는 해당 CLI가 resume permissions를 강제하도록 둡니다.

​

claude-cli sessions의 fallback prelude

• prelude는 최신 /compact summary 또는 compact_boundary marker를 우선 사용한 다음, char budget까지 가장 최근 post-boundary turns를 추가합니다. summary가 이미 이를 대표하므로 pre-boundary turns는 삭제됩니다.
• Tool blocks는 prompt budget을 정직하게 유지하기 위해 compact (tool call: name) 및 (tool result: …) hints로 병합됩니다. summary가 넘치면 (truncated)로 표시됩니다.
• 같은 provider의 claude-cli에서 claude-cli로 fallback하는 경우 Claude 자체 --resume에 의존하고 prelude를 건너뜁니다.
• seed는 기존 Claude session-file path validation을 재사용하므로, 임의 경로를 읽을 수 없습니다.

​

Images (pass-through)

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

​

Inputs / outputs

• output: "json"(기본값)은 JSON을 파싱하고 text + session id를 추출하려고 시도합니다.
• Gemini CLI JSON output의 경우, OpenClaw는 usage가 없거나 비어 있으면 response에서 reply text를, stats에서 usage를 읽습니다.
• output: "jsonl"은 JSONL streams(예: Codex CLI --json)를 파싱하고, 존재하는 경우 최종 agent message와 session identifiers를 추출합니다.
• output: "text"는 stdout을 최종 응답으로 취급합니다.

• input: "arg"(기본값)는 prompt를 마지막 CLI arg로 전달합니다.
• input: "stdin"은 prompt를 stdin으로 보냅니다.
• prompt가 매우 길고 maxPromptArgChars가 설정되어 있으면 stdin이 사용됩니다.

​

Defaults (plugin-owned)

• 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 필드에서 읽습니다.
• usage가 없거나 비어 있으면 사용량은 stats로 대체됩니다.
• stats.cached는 OpenClaw cacheRead로 정규화됩니다.
• stats.input이 없으면 OpenClaw는 입력 토큰을 stats.input_tokens - stats.cached에서 파생합니다.

​

Plugin 소유 기본값

• Plugin은 api.registerCliBackend(...)로 이를 등록합니다.
• 백엔드 id는 모델 참조에서 제공자 접두사가 됩니다.
• agents.defaults.cliBackends.<id>의 사용자 설정은 여전히 Plugin 기본값을 재정의합니다.
• 백엔드별 설정 정리는 선택적 normalizeConfig 훅을 통해 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" },
  ],
});

​

번들 MCP 오버레이

• claude-cli: 생성된 엄격한 MCP 설정 파일
• codex-cli: mcp_servers에 대한 인라인 설정 재정의; 생성된 OpenClaw loopback 서버는 Codex의 서버별 도구 승인 모드로 표시되어 MCP 호출이 로컬 승인 프롬프트에서 중단되지 않도록 합니다
• google-gemini-cli: 생성된 Gemini 시스템 설정 파일

• Gateway 도구를 CLI 프로세스에 노출하는 loopback HTTP MCP 서버 생성
• 세션별 토큰(OPENCLAW_MCP_TOKEN)으로 브리지 인증
• 도구 접근 범위를 현재 세션, 계정, 채널 컨텍스트로 제한
• 현재 작업공간에 대해 활성화된 bundle-MCP 서버 로드
• 기존 백엔드 MCP 설정/설정 형태와 병합
• 소유 extension의 백엔드 소유 통합 모드를 사용하여 실행 설정 재작성

​

제한 사항

• 직접 OpenClaw 도구 호출 없음. OpenClaw는 도구 호출을 CLI 백엔드 프로토콜에 주입하지 않습니다. 백엔드는 bundleMcp: true를 선택한 경우에만 Gateway 도구를 볼 수 있습니다.
• 스트리밍은 백엔드별로 다릅니다. 일부 백엔드는 JSONL을 스트리밍하고, 다른 백엔드는 종료될 때까지 버퍼링합니다.
• 구조화된 출력은 CLI의 JSON 형식에 따라 달라집니다.
• Codex CLI 세션은 텍스트 출력(JSONL 아님)을 통해 재개되며, 이는 초기 --json 실행보다 구조화가 덜 되어 있습니다. OpenClaw 세션은 여전히 정상적으로 작동합니다.

​

문제 해결

• CLI를 찾을 수 없음: command를 전체 경로로 설정하세요.
• 잘못된 모델 이름: modelAliases를 사용하여 provider/model → CLI 모델로 매핑하세요.
• 세션 연속성 없음: sessionArg가 설정되어 있고 sessionMode가 none이 아닌지 확인하세요(Codex CLI는 현재 JSON 출력으로 재개할 수 없습니다).
• 이미지가 무시됨: imageArg를 설정하세요(그리고 CLI가 파일 경로를 지원하는지 확인하세요).

​

관련 항목

• Gateway 런북
• 로컬 모델