CLI backend (fallback runtime)

OpenClaw는 API provider가 다운되거나, rate 제한되거나, 일시적으로 오작동할 때 로컬 AI CLI를 텍스트 전용 fallback으로 실행할 수 있습니다. 이것은 의도적으로 보수적입니다:

  • Tool이 비활성화됨 (tool 호출 없음).
  • 텍스트 입력 → 텍스트 출력 (신뢰할 수 있음).
  • Session 지원 (후속 turn이 일관성을 유지함).
  • 이미지 전달 가능 (CLI가 이미지 경로를 허용하는 경우).

이것은 기본 경로가 아니라 안전망으로 설계되었습니다. 외부 API에 의존하지 않고 "항상 작동하는" 텍스트 응답을 원할 때 사용하세요.

초보자 친화적인 빠른 시작

어떤 config 없이도 Claude Code CLI를 사용할 수 있습니다 (OpenClaw는 내장 기본값을 제공함):

openclaw agent --message "hi" --model claude-cli/opus-4.5

Codex CLI도 즉시 작동합니다:

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

gateway가 launchd/systemd에서 실행되고 PATH가 최소인 경우 명령 경로만 추가하세요:

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

그게 다입니다. CLI 자체를 넘어서는 key나 추가 auth config가 필요하지 않습니다.

Fallback으로 사용

CLI backend를 fallback 목록에 추가하여 기본 model이 실패할 때만 실행되도록 하세요:

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

참고:

  • agents.defaults.models (allowlist)를 사용하는 경우 claude-cli/...를 포함해야 합니다.
  • 기본 provider가 실패하면 (auth, rate limit, timeout), OpenClaw는 다음으로 CLI backend를 시도합니다.

구성 개요

모든 CLI backend는 다음 아래에 있습니다:

agents.defaults.cliBackends

각 항목은 provider id로 키가 지정됩니다 (예: claude-cli, my-cli). Provider id는 model ref의 왼쪽이 됩니다:

<provider>/<model>

예제 구성

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude"
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          input: "arg",
          modelArg: "--model",
          modelAliases: {
            "claude-opus-4-5": "opus",
            "claude-sonnet-4-5": "sonnet"
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true
        }
      }
    }
  }
}

작동 방식

  1. Provider prefix에 따라 backend 선택 (claude-cli/...).
  2. 동일한 OpenClaw prompt + workspace context를 사용하여 system prompt 구성.
  3. Session id로 CLI 실행 (지원되는 경우) 히스토리가 일관성을 유지하도록.
  4. 출력 파싱 (JSON 또는 일반 텍스트) 및 최종 텍스트 반환.
  5. Backend별 session id 유지, 후속 조치가 동일한 CLI 세션을 재사용하도록.

Session

  • CLI가 session을 지원하는 경우 sessionArg (예: --session-id) 또는 sessionArgs (placeholder {sessionId})를 ID가 여러 flag에 삽입되어야 할 때 설정하세요.
  • CLI가 다른 flag와 함께 resume subcommand를 사용하는 경우 resumeArgs (재개 시 args 교체) 및 선택적으로 resumeOutput (비JSON 재개용)을 설정하세요.
  • sessionMode:
    • always: 항상 session id 전송 (저장된 것이 없으면 새 UUID).
    • existing: 이전에 저장된 session id가 있는 경우에만 전송.
    • none: session id를 전송하지 않음.

이미지 (pass-through)

CLI가 이미지 경로를 허용하는 경우 imageArg를 설정하세요:

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

OpenClaw는 base64 이미지를 임시 파일에 작성합니다. imageArg가 설정되면 해당 경로가 CLI arg로 전달됩니다. imageArg가 없으면 OpenClaw는 파일 경로를 prompt에 추가합니다 (경로 주입), 이는 일반 경로에서 로컬 파일을 자동 로드하는 CLI (Claude Code CLI 동작)에 충분합니다.

입력 / 출력

  • output: "json" (기본값)은 JSON을 파싱하고 텍스트 + session id를 추출하려고 시도합니다.
  • output: "jsonl"은 JSONL 스트림 (Codex CLI --json)을 파싱하고 마지막 agent 메시지와 thread_id가 있는 경우 추출합니다.
  • output: "text"는 stdout을 최종 응답으로 처리합니다.

입력 모드:

  • input: "arg" (기본값)은 prompt를 마지막 CLI arg로 전달합니다.
  • input: "stdin"은 prompt를 stdin을 통해 보냅니다.
  • Prompt가 매우 길고 maxPromptArgChars가 설정된 경우 stdin이 사용됩니다.

기본값 (내장)

OpenClaw는 claude-cli에 대한 기본값을 제공합니다:

  • command: "claude"
  • args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]
  • resumeArgs: ["-p", "--output-format", "json", "--dangerously-skip-permissions", "--resume", "{sessionId}"]
  • modelArg: "--model"
  • systemPromptArg: "--append-system-prompt"
  • sessionArg: "--session-id"
  • systemPromptWhen: "first"
  • sessionMode: "always"

OpenClaw는 codex-cli에 대한 기본값도 제공합니다:

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

필요한 경우에만 재정의하세요 (일반적: 절대 command 경로).

제한 사항

  • OpenClaw tool 없음 (CLI backend는 tool 호출을 받지 않음). 일부 CLI는 여전히 자체 agent tooling을 실행할 수 있습니다.
  • 스트리밍 없음 (CLI 출력이 수집된 다음 반환됨).
  • 구조화된 출력은 CLI의 JSON 형식에 따라 다릅니다.
  • Codex CLI 세션은 텍스트 출력을 통해 재개됩니다 (JSONL 없음), 초기 --json 실행보다 덜 구조화되어 있습니다. OpenClaw 세션은 여전히 정상적으로 작동합니다.

문제 해결

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