​

CLI 백엔드 (폴백 런타임)

• 도구가 비활성화됩니다 (도구 호출 없음).
• 텍스트 입력 → 텍스트 출력 (안정적).
• 세션이 지원됩니다 (후속 대화가 일관성 있게 유지됨).
• CLI가 이미지 경로를 수용하면 이미지를 전달할 수 있습니다.

​

초보자를 위한 빠른 시작

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

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

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

​

폴백으로 사용하기

{
  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 백엔드를 시도합니다.

​

설정 개요

agents.defaults.cliBackends

<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. 후속 요청이 동일한 CLI 세션을 재사용할 수 있도록 백엔드별로 세션 id를 유지합니다.

​

세션

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

​

이미지 (전달)

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

​

입력 / 출력

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

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

​

기본값 (내장)

• 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"

• 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"

​

제한 사항

• 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가 파일 경로를 지원하는지 확인하세요).