OpenClaw CLI 백엔드 설정: API 장애 시 자동 전환하기

개발을 하다 보면 API 제공업체의 서버가 다운되거나, 갑자기 Rate Limit에 걸려 작업 흐름이 끊기는 난감한 상황을 겪곤 하죠. 도구가 제 역할을 못 하면 생산성이 뚝 떨어지기 마련인데요.

이럴 때 OpenClaw의 CLI backends를 활용하면 로컬 AI CLI를 텍스트 전용 fallback으로 실행해서 흐름을 유지할 수 있어요. API가 응답하지 않을 때를 대비한 든든한 안전장치인 셈이죠.

CLI backends (fallback runtime)

OpenClaw는 API 제공업체의 서비스가 중단되거나, Rate Limit이 발생하거나, 일시적으로 오류를 일으킬 때 로컬 AI CLI를 텍스트 전용 fallback으로 실행할 수 있어요. 이 기능은 안정성을 위해 의도적으로 보수적으로 설계되었습니다.

• Tools 비활성화 (tool call을 사용하지 않음).
• Text in → text out (신뢰성 높음).
• Sessions 지원 (후속 질문에서도 문맥이 유지됨).
• Images 전달 가능 (CLI가 이미지 경로를 지원하는 경우).

이 기능은 주력 경로라기보다는 **안전망(safety net)**으로 설계되었어요. 외부 API에 의존하지 않고 “항상 작동하는” 텍스트 응답이 필요할 때 사용해 보세요.

초보자를 위한 빠른 시작

Claude Code CLI를 별도의 설정 없이 바로 사용할 수 있어요 (내장된 Anthropic 플러그인이 기본 backend를 등록해 둡니다).

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

Codex CLI도 내장된 OpenAI 플러그인을 통해 바로 작동해요.

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

만약 Gateway가 launchd/systemd 환경에서 실행되어 PATH가 최소화되어 있다면, 다음과 같이 명령어 경로만 추가해 주세요.

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

이게 전부예요. CLI 자체 설정 외에 별도의 키나 인증 설정은 필요 없어요.

Gateway 호스트에서 내장 CLI backend를 주요 메시지 제공자로 사용하는 경우, 설정에서 모델 참조나 agents.defaults.cliBackends를 통해 해당 backend를 명시하면 OpenClaw가 관련 플러그인을 자동으로 로드합니다.

폴백(Fallback)으로 사용하기

기본 모델이 실패할 때만 실행되도록 fallback 리스트에 CLI backend를 추가해 보세요.

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

참고 사항:

• agents.defaults.models (allowlist)를 사용하는 경우, 반드시 claude-cli/...를 포함해야 해요.
• 기본 제공업체가 인증 실패, Rate Limit, 타임아웃 등으로 응답하지 않으면 OpenClaw가 다음 순서로 CLI backend를 시도합니다.

설정 개요

모든 CLI backend 설정은 다음 위치에서 관리해요.

agents.defaults.cliBackends

각 항목은 provider id (예: claude-cli, my-cli)를 키로 가집니다. 이 provider id는 모델 참조 시 왼쪽 부분이 됩니다.

<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-6": "opus",
            "claude-sonnet-4-6": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

작동 원리

1. provider 접두사(claude-cli/...)를 바탕으로 backend를 선택합니다.
2. 동일한 OpenClaw 프롬프트와 workspace 컨텍스트를 사용하여 system prompt를 생성합니다.
3. 대화 기록이 일관되게 유지되도록 session id(지원되는 경우)와 함께 CLI를 실행합니다.
4. 출력을 파싱 (JSON 또는 일반 텍스트)하여 최종 텍스트를 반환합니다.
5. backend별로 session id를 유지하므로, 후속 질문 시 동일한 CLI 세션을 재사용합니다.

세션

• CLI가 세션을 지원한다면 sessionArg (예: --session-id)를 설정하세요. ID를 여러 플래그에 넣어야 한다면 sessionArgs (플레이스홀더 {sessionId} 사용)를 설정하면 됩니다.
• CLI가 다른 플래그와 함께 resume 서브커맨드를 사용한다면, resumeArgs (재개 시 args를 대체)를 설정하고 필요한 경우 resumeOutput (JSON이 아닌 형태로 재개될 때)을 설정하세요.
• sessionMode:
  • always: 항상 session id를 전송합니다 (저장된 게 없으면 새 UUID 생성).
  • existing: 저장된 session id가 있을 때만 전송합니다.
  • none: session id를 절대 보내지 않습니다.

이미지 (패스스루)

사용 중인 CLI가 이미지 경로를 지원한다면 imageArg를 설정하세요.

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

OpenClaw는 base64 이미지를 임시 파일로 기록합니다. imageArg가 설정되어 있으면 해당 경로들이 CLI 인자로 전달됩니다. 만약 imageArg가 없으면 OpenClaw는 프롬프트에 파일 경로를 추가(path injection)하는데, 이는 로컬 파일 경로를 자동으로 로드하는 CLI(Claude Code CLI 등)에서 유용합니다.

입력 및 출력

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

입력 모드:

• input: "arg" (기본값): 프롬프트를 마지막 CLI 인자로 전달합니다.
• input: "stdin": stdin을 통해 프롬프트를 보냅니다.
• 프롬프트가 매우 길고 maxPromptArgChars가 설정되어 있다면 stdin이 사용됩니다.

기본값 (플러그인 제공)

내장된 Anthropic 플러그인은 claude-cli를 위해 다음 기본값을 등록합니다.

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

내장된 OpenAI 플러그인도 codex-cli를 위한 기본값을 등록합니다.

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

내장된 Google 플러그인도 google-gemini-cli를 위한 기본값을 등록합니다.

• command: "gemini"
• args: ["--prompt", "--output-format", "json"]
• resumeArgs: ["--resume", "{sessionId}", "--prompt", "--output-format", "json"]
• modelArg: "--model"
• sessionMode: "existing"
• sessionIdFields: ["session_id", "sessionId"]

필요한 경우에만 덮어쓰세요 (보통 command에 절대 경로를 지정할 때 사용합니다).

플러그인 소유 기본값

CLI backend 기본값은 이제 플러그인 시스템의 일부입니다.

• 플러그인은 api.registerCliBackend(...)를 통해 기본값을 등록합니다.
• backend id는 모델 참조 시 provider 접두사가 됩니다.
• agents.defaults.cliBackends.<id>에 작성한 사용자 설정은 플러그인 기본값보다 우선합니다.
• backend별 설정 정리(cleanup)는 선택 사항인 normalizeConfig 훅을 통해 플러그인이 직접 관리합니다.

제한 사항

• OpenClaw tools 미지원: CLI backend는 tool call을 받지 않습니다. 다만 일부 CLI는 자체적인 에이전트 툴링을 실행할 수도 있습니다.
• 스트리밍 미지원: CLI 출력을 모두 수집한 뒤에 반환합니다.
• Structured outputs: CLI의 JSON 형식에 의존합니다.
• Codex CLI 세션: 텍스트 출력(JSONL 아님)을 통해 재개되는데, 이는 초기 --json 실행보다 구조화가 덜 되어 있습니다. 그래도 OpenClaw 세션은 정상적으로 작동합니다.

문제 해결

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

AI Setup Assistant

다음 단계

• Custom Plugins
• Gateway Configuration