OpenClaw에 Anthropic Claude API 연동하기: 5분 설정 가이드

새로운 AI 모델을 설정할 때마다 복잡한 인증 과정과 설정값 때문에 머리 아픈 적 많으셨죠? 특히 Anthropic의 Claude처럼 강력한 모델을 내 프로젝트에 딱 맞게 연결하는 일은 생각보다 까다로울 수 있어요.

OpenClaw를 사용하면 Anthropic API key부터 Claude 구독 계정까지, 여러분의 환경에 가장 적합한 방식으로 Claude 모델을 쉽고 빠르게 연동할 수 있답니다. 지금부터 그 방법을 하나씩 친절하게 설명해 드릴게요.

Anthropic (Claude)

Anthropic은 Claude 모델 패밀리를 개발하고 API를 통해 접근 권한을 제공해요. OpenClaw에서는 API key나 setup-token을 사용해서 인증할 수 있어요.

옵션 A: Anthropic API key

추천 대상: 표준 API 접근 및 사용량 기반 과금이 필요한 경우. Anthropic Console에서 API key를 생성하세요.

CLI setup

openclaw onboard
# choose: Anthropic API key

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

Claude CLI config snippet

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

Thinking 기본 설정 (Claude 4.6)

Anthropic Claude 4.6 모델은 별도의 thinking level을 설정하지 않으면 OpenClaw에서 기본적으로 adaptive thinking을 사용해요.
메시지별로( /think:<level>) 또는 모델 파라미터(agents.defaults.models["anthropic/<model>"].params.thinking)에서 이 설정을 덮어쓸 수 있어요.
관련 Anthropic 문서:
- Adaptive thinking
- Extended thinking

Fast mode (Anthropic API)

OpenClaw의 공유 /fast 토글은 api.anthropic.com으로 전송되는 API-key 및 OAuth 인증 요청을 포함하여 직접적인 퍼블릭 Anthropic 트래픽을 지원해요.

/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 service tier를 주입해요. 만약 anthropic/*를 프록시나 Gateway를 통해 라우팅한다면, /fast는 service_tier를 수정하지 않은 채로 둡니다.
명시적인 Anthropic serviceTier 또는 service_tier 모델 파라미터가 설정되어 있다면, 두 설정이 충돌할 때 /fast 기본값보다 우선시돼요.
Anthropic은 응답의 usage.service_tier 항목에 유효한 tier를 보고해요. Priority Tier 용량이 없는 계정에서는 service_tier: "auto"가 여전히 standard로 처리될 수 있어요.

Prompt caching (Anthropic API)

OpenClaw는 Anthropic의 prompt caching 기능을 지원해요. 이 기능은 API 전용이며, 구독(subscription) 인증은 캐시 설정을 따르지 않아요.

Configuration

모델 설정에서 cacheRetention 파라미터를 사용하세요:

Value	Cache Duration	Description
`none`	No caching	prompt caching 비활성화
`short`	5 minutes	API Key 인증 시 기본값
`long`	1 hour	확장 캐시 (beta flag 필요)

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

기본값

Anthropic API Key 인증을 사용할 때, OpenClaw는 모든 Anthropic 모델에 대해 자동으로 cacheRetention: "short" (5분 캐시)를 적용해요. 설정에서 cacheRetention을 명시적으로 지정하여 이 값을 덮어쓸 수 있어요.

Agent별 cacheRetention 덮어쓰기

모델 레벨 파라미터를 기본값으로 사용하고, agents.list[].params를 통해 특정 Agent의 설정을 변경할 수 있어요.

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" }, // baseline for most agents
        },
      },
    },
    list: [
      { id: "research", default: true },
      { id: "alerts", params: { cacheRetention: "none" } }, // override for this agent only
    ],
  },
}

캐시 관련 파라미터의 설정 병합 순서:

agents.defaults.models["provider/model"].params
agents.list[].params (일치하는 id가 있을 때 key 단위로 덮어씀)

이를 통해 한 Agent는 긴 캐시 수명을 유지하게 하고, 동일한 모델을 사용하는 다른 Agent는 트래픽이 불규칙하거나 재사용률이 낮을 때 쓰기 비용을 아끼기 위해 캐싱을 비활성화할 수 있어요.

Bedrock Claude 참고 사항

Bedrock의 Anthropic Claude 모델(amazon-bedrock/*anthropic.claude*)은 설정 시 cacheRetention 전달을 수용해요.
Anthropic이 아닌 Bedrock 모델은 런타임 시 강제로 cacheRetention: "none"이 적용돼요.
Anthropic API-key 스마트 기본값은 명시적인 값이 없을 때 Claude-on-Bedrock 모델 참조에 대해서도 cacheRetention: "short"를 심어줍니다.

레거시 파라미터

이전의 cacheControlTtl 파라미터도 하위 호환성을 위해 여전히 지원돼요:

"5m"은 short에 매핑돼요.
"1h"는 long에 매핑돼요.

새로운 cacheRetention 파라미터로 마이그레이션하는 것을 추천해요.

OpenClaw는 Anthropic API 요청 시 extended-cache-ttl-2025-04-11 beta flag를 포함해요. 만약 provider header를 직접 수정한다면 이 부분을 유지해 주세요 (/gateway/configuration 참고).

1M context window (Anthropic 베타)

Anthropic의 1M context window는 베타 기능이에요. OpenClaw에서는 지원되는 Opus/Sonnet 모델에 대해 params.context1m: true를 설정하여 모델별로 활성화할 수 있어요.

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

OpenClaw는 Anthropic 요청 시 이를 anthropic-beta: context-1m-2025-08-07로 매핑해요.

이 기능은 해당 모델에 대해 params.context1m이 명시적으로 true로 설정되었을 때만 활성화돼요.

요구 사항: Anthropic 계정(일반적으로 API key 결제 계정 또는 Extra Usage가 활성화된 구독 계정)에서 긴 컨텍스트 사용이 허용되어야 해요. 그렇지 않으면 Anthropic에서 다음과 같은 에러를 반환합니다: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

참고: Anthropic은 현재 구독 setup-token(sk-ant-oat-*)을 사용할 때 context-1m-* 베타 요청을 거부해요. 구독 인증과 함께 context1m: true를 설정하면, OpenClaw는 경고를 로그에 남기고 필요한 OAuth 베타는 유지하되 context1m 베타 헤더는 제외하여 표준 context window로 대체 작동(fallback)합니다.

옵션 B: 메시지 프로바이더로 Claude CLI 사용하기

추천 대상: 이미 Claude CLI가 설치되어 있고 Claude 구독으로 로그인된 단일 사용자 Gateway 호스트.

이 방식은 Anthropic API를 직접 호출하는 대신 로컬 claude 바이너리를 모델 추론에 사용해요. OpenClaw는 이를 다음과 같은 모델 참조를 가진 CLI backend provider로 취급해요:

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

작동 방식:

OpenClaw가 Gateway 호스트에서 claude -p --output-format json ...을 실행해요.
첫 번째 턴에서 --session-id <uuid>를 보냅니다.
후속 턴에서는 --resume <sessionId>를 통해 저장된 Claude 세션을 재사용해요.
채팅 메시지는 여전히 일반적인 OpenClaw 메시지 파이프라인을 거치지만, 실제 모델 응답은 Claude CLI에 의해 생성돼요.

요구 사항

Gateway 호스트에 Claude CLI가 설치되어 PATH에 등록되어 있거나, 절대 경로로 설정되어 있어야 해요.
해당 호스트에서 Claude CLI 인증이 이미 완료되어 있어야 해요:

claude auth status

설정에서 claude-cli/... 또는 claude-cli 백엔드 설정을 명시적으로 참조하면, OpenClaw가 Gateway 시작 시 번들로 포함된 Anthropic 플러그인을 자동으로 로드해요.

Config snippet

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

만약 claude 바이너리가 Gateway 호스트의 PATH에 없다면:

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

장점

로컬 CLI에서 사용 중인 Claude 구독 인증을 그대로 재사용할 수 있어요.
일반적인 OpenClaw 메시지/세션 라우팅을 사용할 수 있어요.
턴을 거듭해도 Claude CLI 세션 연속성이 유지돼요.

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

현재 setup-token이나 API key로 anthropic/...을 사용 중인데, 동일한 Gateway 호스트를 Claude CLI 방식으로 전환하고 싶다면:

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

또는 온보딩 과정에서:

openclaw onboard --auth-choice anthropic-cli

이 명령어가 수행하는 작업:

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

수행하지 않는 작업:

기존의 Anthropic 인증 프로필을 삭제하지 않아요.
메인 기본 모델/허용 목록 경로 이외의 오래된 anthropic/... 설정 참조를 제거하지 않아요.

덕분에 롤백이 간단해요. 필요한 경우 기본 모델을 다시 anthropic/...으로 변경하기만 하면 됩니다.

중요 제한 사항

이것은 Anthropic API 프로바이더가 아니에요. 로컬 CLI 런타임입니다.
CLI 백엔드 실행 시 OpenClaw 측의 Tool 기능은 비활성화돼요.
텍스트 입력, 텍스트 출력 방식입니다. OpenClaw 스트리밍 핸드오프는 지원되지 않아요.
다중 사용자 과금 환경이 아닌 개인용 Gateway 호스트에 가장 적합해요.

더 자세한 내용: /gateway/cli-backends

옵션 C: Claude setup-token

추천 대상: 본인의 Claude 구독을 사용하려는 경우.

setup-token을 얻는 방법

setup-token은 Anthropic Console이 아니라 Claude Code CLI에서 생성돼요. 어떤 머신에서든 다음 명령어를 실행할 수 있어요:

claude setup-token

생성된 토큰을 OpenClaw에 붙여넣거나(마법사: Anthropic token (paste setup-token)), Gateway 호스트에서 다음을 실행하세요:

openclaw models auth setup-token --provider anthropic

다른 머신에서 토큰을 생성했다면 직접 붙여넣으세요:

openclaw models auth paste-token --provider anthropic

CLI setup (setup-token)

# Paste a setup-token during setup
openclaw onboard --auth-choice setup-token

Config snippet (setup-token)

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

참고 사항

claude setup-token으로 setup-token을 생성해 붙여넣거나, Gateway 호스트에서 openclaw models auth setup-token을 실행하세요.
Claude 구독에서 “OAuth token refresh failed …” 에러가 보인다면 setup-token으로 다시 인증하세요. /gateway/troubleshooting을 참고해 주세요.
인증 상세 내용 및 재사용 규칙은 /concepts/oauth에 있습니다.

문제 해결

401 에러 / 토큰이 갑자기 유효하지 않음

Claude 구독 인증은 만료되거나 취소될 수 있어요. claude setup-token을 다시 실행하고 Gateway 호스트에 붙여넣으세요.
Claude CLI 로그인이 다른 머신에 있다면, Gateway 호스트에서 openclaw models auth paste-token --provider anthropic을 사용하세요.

No API key found for provider “anthropic”

인증은 Agent별로 이루어져요. 새로운 Agent는 메인 Agent의 key를 상속받지 않습니다.
해당 Agent에 대해 온보딩을 다시 실행하거나, Gateway 호스트에서 setup-token / API key를 붙여넣은 후 openclaw models status로 확인하세요.

No credentials found for profile anthropic:default

openclaw models status를 실행하여 어떤 인증 프로필이 활성화되어 있는지 확인하세요.
온보딩을 다시 실행하거나 해당 프로필에 대해 setup-token / API key를 붙여넣으세요.

No available auth profile (모두 cooldown/사용 불가 상태)

openclaw models status --json을 실행하여 auth.unusableProfiles를 확인하세요.
다른 Anthropic 프로필을 추가하거나 cooldown이 끝날 때까지 기다리세요.

더 많은 정보: /gateway/troubleshooting 및 /help/faq

다음 단계

궁금한 점이 더 있다면 AI Setup Assistant에게 언제든 물어보세요!

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.