CLI 백엔드 (폴백 런타임)

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

  • 도구가 비활성화됩니다 (도구 호출 없음).
  • 텍스트 입력 → 텍스트 출력 (안정적).
  • 세션이 지원됩니다 (후속 턴의 일관성 유지).
  • 이미지 전달 가능 CLI가 이미지 경로를 수용하는 경우.

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

초보자 친화적 빠른 시작

Claude Code CLI는 설정 없이 사용할 수 있습니다 (OpenClaw에 내장 기본값이 포함됨):

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

Codex CLI도 바로 사용할 수 있습니다:

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

게이트웨이가 launchd/systemd에서 실행되고 PATH가 최소한인 경우, 명령어 경로만 추가하세요:

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

이것으로 끝입니다. CLI 자체 외에 키나 추가 인증 설정이 필요 없습니다.

폴백으로 사용하기

CLI 백엔드를 폴백 목록에 추가하면 기본 모델이 실패할 때만 실행됩니다:

{
  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(허용 목록)를 사용하는 경우, claude-cli/...를 포함해야 합니다.
  • 기본 제공자가 실패하면(인증, 속도 제한, 타임아웃), OpenClaw가 다음으로 CLI 백엔드를 시도합니다.

설정 개요

모든 CLI 백엔드는 다음 위치에 있습니다:

agents.defaults.cliBackends

각 항목은 제공자 ID(예: claude-cli, my-cli)로 키가 지정됩니다. 제공자 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-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. 제공자 접두사(claude-cli/...)를 기반으로 백엔드를 선택합니다.
  2. 동일한 OpenClaw 프롬프트 + 워크스페이스 컨텍스트를 사용하여 시스템 프롬프트를 빌드합니다.
  3. 세션 ID(지원되는 경우)와 함께 CLI를 실행하여 히스토리 일관성을 유지합니다.
  4. 출력을 파싱(JSON 또는 일반 텍스트)하고 최종 텍스트를 반환합니다.
  5. 백엔드별로 세션 ID를 유지하여, 후속 대화가 동일한 CLI 세션을 재사용합니다.

세션

  • CLI가 세션을 지원하는 경우, sessionArg(예: --session-id)를 설정하거나 ID를 여러 플래그에 삽입해야 하는 경우 sessionArgs(플레이스홀더 {sessionId})를 설정합니다.
  • CLI가 다른 플래그를 가진 재개 서브커맨드를 사용하는 경우, resumeArgs(재개 시 args를 대체)와 선택적으로 resumeOutput (비JSON 재개용)을 설정합니다.
  • sessionMode:
    • always: 항상 세션 ID를 전송합니다 (저장된 것이 없으면 새 UUID).
    • existing: 이전에 저장된 세션 ID가 있는 경우에만 전송합니다.
    • none: 세션 ID를 전송하지 않습니다.

이미지 (패스스루)

CLI가 이미지 경로를 수용하는 경우, imageArg를 설정합니다:

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

OpenClaw는 base64 이미지를 임시 파일에 기록합니다. imageArg가 설정되면 해당 경로가 CLI 인수로 전달됩니다. imageArg가 없으면 OpenClaw가 프롬프트에 파일 경로를 추가합니다(경로 주입). 이것은 일반 경로에서 로컬 파일을 자동으로 불러오는 CLI에 충분합니다(Claude Code CLI 동작).

입출력

  • output: "json" (기본값)은 JSON을 파싱하고 텍스트 + 세션 ID를 추출합니다.
  • output: "jsonl"은 JSONL 스트림(Codex CLI --json)을 파싱하고 마지막 에이전트 메시지와 thread_id가 있으면 추출합니다.
  • output: "text"는 stdout을 최종 응답으로 취급합니다.

입력 모드:

  • input: "arg" (기본값)은 프롬프트를 마지막 CLI 인수로 전달합니다.
  • input: "stdin"은 stdin을 통해 프롬프트를 전송합니다.
  • 프롬프트가 매우 길고 maxPromptArgChars가 설정된 경우, stdin이 사용됩니다.

기본값 (내장)

OpenClaw에는 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"

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 도구 없음 (CLI 백엔드는 도구 호출을 수신하지 않음). 일부 CLI는 자체 에이전트 도구를 실행할 수 있습니다.
  • 스트리밍 없음 (CLI 출력을 수집한 후 반환).
  • 구조화된 출력은 CLI의 JSON 형식에 의존합니다.
  • Codex CLI 세션은 텍스트 출력(JSONL 아님)을 통해 재개되므로, 초기 --json 실행보다 구조화 수준이 낮습니다. OpenClaw 세션은 여전히 정상적으로 동작합니다.

문제 해결

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