​

Anthropic (Claude)

​

옵션 A: Anthropic API 키

​

CLI 설정

openclaw onboard
# choose: Anthropic API key

# or non-interactive
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"

​

Claude CLI 구성 스니펫

{
  env: { ANTHROPIC_API_KEY: "sk-ant-..." },
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

​

thinking 기본값 (Claude 4.6)

• Anthropic Claude 4.6 모델은 명시적인 thinking 수준이 설정되지 않은 경우 OpenClaw에서 기본적으로 adaptive thinking을 사용합니다.
• 메시지별로 (/think:<level>) 또는 모델 params에서 재정의할 수 있습니다: agents.defaults.models["anthropic/<model>"].params.thinking.
• 관련 Anthropic 문서:
  • Adaptive thinking
  • Extended thinking

​

Fast mode (Anthropic API)

• /fast on은 service_tier: "auto"에 매핑됩니다
• /fast off는 service_tier: "standard_only"에 매핑됩니다
• 구성 기본값:

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-6": {
          params: { fastMode: true },
        },
      },
    },
  },
}

• OpenClaw는 직접적인 api.anthropic.com 요청에 대해서만 Anthropic 서비스 티어를 주입합니다. anthropic/*를 프록시 또는 게이트웨이를 통해 라우팅하는 경우 /fast는 service_tier를 변경하지 않습니다.
• 명시적인 Anthropic serviceTier 또는 service_tier 모델 params가 설정되어 있으면 둘 다 설정된 경우 /fast 기본값보다 우선합니다.
• Anthropic는 응답의 usage.service_tier 아래에 실제 티어를 보고합니다. Priority Tier 용량이 없는 계정에서는 service_tier: "auto"가 여전히 standard로 해석될 수 있습니다.

​

프롬프트 캐싱 (Anthropic API)

​

구성

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
  },
}

​

기본값

​

에이전트별 cacheRetention 재정의

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" }, // 대부분의 에이전트에 대한 기준선
        },
      },
    },
    list: [
      { id: "research", default: true },
      { id: "alerts", params: { cacheRetention: "none" } }, // 이 에이전트에만 적용되는 재정의
    ],
  },
}

1. agents.defaults.models["provider/model"].params
2. agents.list[].params (id가 일치할 때 키별로 재정의)

​

Bedrock Claude 참고 사항

• Bedrock의 Anthropic Claude 모델(amazon-bedrock/*anthropic.claude*)은 구성된 경우 cacheRetention 전달을 허용합니다.
• Anthropic가 아닌 Bedrock 모델은 런타임에서 강제로 cacheRetention: "none"이 적용됩니다.
• Anthropic API 키 스마트 기본값은 명시적인 값이 설정되지 않은 경우 Claude-on-Bedrock 모델 참조에도 cacheRetention: "short"를 기본 적용합니다.

​

1M 컨텍스트 윈도우 (Anthropic beta)

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { context1m: true },
        },
      },
    },
  },
}

​

옵션 B: 메시지 provider로 Claude CLI 사용

• claude-cli/claude-sonnet-4-6
• claude-cli/claude-opus-4-6

1. OpenClaw는 게이트웨이 호스트에서 claude -p --output-format stream-json --include-partial-messages ... 를 실행하고 stdin을 통해 프롬프트를 전송합니다.
2. 첫 번째 턴에서는 --session-id <uuid>를 전송합니다.
3. 후속 턴에서는 저장된 Claude 세션을 --resume <sessionId>로 재사용합니다.
4. 채팅 메시지는 여전히 일반 OpenClaw 메시지 파이프라인을 거치지만, 실제 모델 응답은 Claude CLI가 생성합니다.

​

요구 사항

• 게이트웨이 호스트에 Claude CLI가 설치되어 있고 PATH에서 사용할 수 있거나, 절대 명령 경로로 구성되어 있어야 합니다.
• Claude CLI가 동일한 호스트에서 이미 인증되어 있어야 합니다:

claude auth status

• 구성에서 claude-cli/... 또는 claude-cli backend config를 명시적으로 참조하면 OpenClaw는 게이트웨이 시작 시 번들된 Anthropic plugin을 자동으로 로드합니다.

​

구성 스니펫

{
  agents: {
    defaults: {
      model: {
        primary: "claude-cli/claude-sonnet-4-6",
      },
      models: {
        "claude-cli/claude-sonnet-4-6": {},
      },
      sandbox: { mode: "off" },
    },
  },
}

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

​

제공되는 기능

• 로컬 CLI에서 Claude 구독 인증 재사용(런타임에 읽고, 저장되지는 않음)
• 일반적인 OpenClaw 메시지/세션 라우팅
• 턴 간 Claude CLI 세션 연속성(인증 변경 시 무효화됨)
• loopback MCP bridge를 통해 Claude CLI에 노출되는 게이트웨이 도구
• 라이브 partial-message 진행 상황이 포함된 JSONL 스트리밍

​

Anthropic 인증에서 Claude CLI로 마이그레이션

• OpenClaw를 실행하는 동일한 게이트웨이 호스트에 Claude CLI 설치
• 해당 위치에서 Claude CLI에 이미 로그인됨: claude auth login

openclaw models auth login --provider anthropic --method cli --set-default

openclaw onboard --auth-choice anthropic-cli

• Claude CLI가 게이트웨이 호스트에서 이미 로그인되어 있는지 확인
• 기본 모델을 claude-cli/...로 전환
• anthropic/claude-opus-4-6 같은 Anthropic 기본 모델 폴백을 claude-cli/claude-opus-4-6로 다시 작성
• agents.defaults.models에 일치하는 claude-cli/... 항목 추가

openclaw models status

• 기존 Anthropic 인증 프로필 삭제
• 기본 default model/allowlist 경로 외부의 오래된 anthropic/... config 참조를 모두 제거

​

중요한 제한 사항

• 이것은 Anthropic API provider가 아닙니다. 로컬 CLI 런타임입니다.
• OpenClaw는 tool call을 직접 주입하지 않습니다. Claude CLI는 loopback MCP bridge를 통해 게이트웨이 도구를 받습니다(bundleMcp: true, 기본값).
• Claude CLI는 JSONL(stream-json 및 --include-partial-messages)을 통해 응답을 스트리밍합니다. 프롬프트는 argv가 아니라 stdin을 통해 전송됩니다.
• 인증은 라이브 Claude CLI 자격 증명에서 런타임에 읽어 오며 OpenClaw 프로필에 저장되지 않습니다. 비대화형 컨텍스트에서는 키체인 프롬프트가 억제됩니다.
• 세션 재사용은 cliSessionBinding 메타데이터를 통해 추적됩니다. Claude CLI 로그인 상태가 변경되면(재로그인, 토큰 교체) 저장된 세션이 무효화되고 새로운 세션이 시작됩니다.
• 공유된 다중 사용자 과금 설정이 아니라 개인 게이트웨이 호스트에 가장 적합합니다.

​

참고

• Anthropic의 공개 Claude Code 문서는 여전히 claude -p 같은 직접 CLI 사용을 문서화하고 있습니다. 저희는 로컬에서 사용자가 관리하는 폴백은 허용될 가능성이 높다고 판단하지만, Anthropic가 OpenClaw 사용자에게 보낸 별도 안내에 따르면 OpenClaw Claude 로그인 경로는 서드파티 harness 사용으로 간주되며 Extra Usage (구독과 별도로 청구되는 사용량 기반 과금)가 필요합니다. 프로덕션에서는 대신 Anthropic API 키를 권장합니다.
• Anthropic setup-token은 이제 OpenClaw에서 다시 레거시/수동 경로로 사용할 수 있습니다. Anthropic의 OpenClaw 관련 과금 안내는 여전히 적용되므로, 이 경로에는 Anthropic가 Extra Usage를 요구한다는 전제로 사용하세요.
• 인증 세부 정보 및 재사용 규칙은 /concepts/oauth에 있습니다.

​

문제 해결

• 레거시 Anthropic 토큰 인증은 만료되거나 취소될 수 있습니다.
• 새로 설정하는 경우, Anthropic API 키 또는 게이트웨이 호스트의 로컬 Claude CLI 경로로 마이그레이션하세요.

• 인증은 에이전트별입니다. 새 에이전트는 메인 에이전트의 키를 상속하지 않습니다.
• 해당 에이전트에 대해 onboarding을 다시 실행하거나, 게이트웨이 호스트에서 API 키를 구성한 다음 openclaw models status로 확인하세요.

• openclaw models status를 실행해 어떤 인증 프로필이 활성 상태인지 확인하세요.
• onboarding을 다시 실행하거나, 해당 프로필 경로에 API 키 또는 Claude CLI를 구성하세요.

• auth.unusableProfiles는 openclaw models status --json에서 확인하세요.
• Anthropic rate-limit cooldown은 모델 범위일 수 있으므로, 현재 모델이 cooldown 중이어도 같은 Anthropic 모델 계열의 다른 모델은 여전히 사용 가능할 수 있습니다.
• 다른 Anthropic 프로필을 추가하거나 cooldown이 끝날 때까지 기다리세요.