Anthropic (Claude)

Anthropic은 Claude 모델 제품군을 개발하며, API를 통해 접근할 수 있습니다. OpenClaw에서는 API 키 또는 setup-token으로 인증할 수 있습니다.

옵션 A: Anthropic API 키

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

CLI 설정

openclaw onboard
# 선택: Anthropic API key

# 또는 비대화형
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"

설정 예시

{
  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>) 또는 모델 파라미터에서 재정의할 수 있습니다: agents.defaults.models["anthropic/<model>"].params.thinking.
관련 Anthropic 문서:
- Adaptive thinking
- Extended thinking

고속 모드 (Anthropic API)

OpenClaw의 공유 /fast 토글은 직접 Anthropic API 키 트래픽도 지원합니다.

/fast on은 service_tier: "auto"에 매핑
/fast off는 service_tier: "standard_only"에 매핑
설정 기본값:

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

주요 제한 사항:

API 키 전용입니다. Anthropic setup-token / OAuth 인증은 OpenClaw 고속 모드 티어 주입을 지원하지 않습니다.
OpenClaw는 직접 api.anthropic.com 요청에 대해서만 Anthropic 서비스 티어를 주입합니다. anthropic/*를 프록시나 게이트웨이를 통해 라우팅하는 경우, /fast는 service_tier를 변경하지 않습니다.
Anthropic은 응답의 usage.service_tier에 실제 적용된 티어를 보고합니다. Priority Tier 용량이 없는 계정에서는 service_tier: "auto"가 여전히 standard로 해석될 수 있습니다.

프롬프트 캐싱 (Anthropic API)

OpenClaw는 Anthropic의 프롬프트 캐싱 기능을 지원합니다. 이는 API 전용이며, 구독 인증에서는 캐시 설정이 적용되지 않습니다.

설정

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

값	캐시 기간	설명
`none`	캐싱 없음	프롬프트 캐싱 비활성화
`short`	5분	API 키 인증의 기본값
`long`	1시간	확장 캐시 (베타 플래그 필요)

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

기본값

Anthropic API 키 인증을 사용할 때, OpenClaw는 모든 Anthropic 모델에 자동으로 cacheRetention: "short" (5분 캐시)를 적용합니다. 설정에서 cacheRetention을 명시적으로 지정하면 이를 재정의할 수 있습니다.

에이전트별 cacheRetention 재정의

모델 수준의 파라미터를 기본값으로 사용하고, agents.list[].params를 통해 특정 에이전트를 재정의합니다.

{
  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" } }, // 이 에이전트에만 적용되는 재정의
    ],
  },
}

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

agents.defaults.models["provider/model"].params
agents.list[].params (id가 일치하는 항목, 키 단위로 재정의)

이를 통해 한 에이전트는 장기 캐시를 유지하면서 같은 모델을 사용하는 다른 에이전트는 캐싱을 비활성화하여 간헐적/재사용률 낮은 트래픽에 대한 쓰기 비용을 절감할 수 있습니다.

Bedrock Claude 참고 사항

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

레거시 파라미터

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

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

새로운 cacheRetention 파라미터로 마이그레이션하는 것을 권장합니다.

OpenClaw는 Anthropic API 요청에 extended-cache-ttl-2025-04-11 베타 플래그를 포함합니다. 프로바이더 헤더를 재정의하는 경우에도 이 플래그를 유지하세요(/gateway/configuration 참조).

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

Anthropic의 1M 컨텍스트 윈도우는 베타 게이트 기능입니다. 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 키 과금 또는 Extra Usage가 활성화된 구독 계정). 그렇지 않으면 Anthropic이 다음을 반환합니다: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

참고: Anthropic은 현재 OAuth/구독 토큰(sk-ant-oat-*)을 사용할 때 context-1m-* 베타 요청을 거부합니다. OpenClaw는 OAuth 인증 시 context1m 베타 헤더를 자동으로 건너뛰고 필요한 OAuth 베타만 유지합니다.

옵션 B: Claude setup-token

추천 대상: Claude 구독을 활용하는 경우.

setup-token 발급 방법

setup-token은 Anthropic Console이 아닌 Claude Code CLI에서 생성됩니다. 어떤 머신에서든 실행할 수 있습니다:

claude setup-token

토큰을 OpenClaw에 붙여넣거나(마법사: Anthropic token (paste setup-token)), 게이트웨이 호스트에서 실행합니다:

openclaw models auth setup-token --provider anthropic

다른 머신에서 토큰을 생성한 경우 붙여넣기를 사용합니다:

openclaw models auth paste-token --provider anthropic

CLI 설정 (setup-token)

# 온보딩 중 setup-token 붙여넣기
openclaw onboard --auth-choice setup-token

설정 예시 (setup-token)

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

참고 사항

claude setup-token으로 setup-token을 생성하여 붙여넣거나, 게이트웨이 호스트에서 openclaw models auth setup-token을 실행하세요.
Claude 구독에서 “OAuth token refresh failed …”가 표시되면 setup-token으로 재인증하세요. /gateway/troubleshooting#oauth-token-refresh-failed-anthropic-claude-subscription을 참조하세요.
인증 세부 정보 및 재사용 규칙은 /concepts/oauth에서 확인할 수 있습니다.

문제 해결

401 오류 / 토큰이 갑자기 무효화되는 경우

Claude 구독 인증은 만료되거나 해지될 수 있습니다. claude setup-token을 다시 실행하여 게이트웨이 호스트에 붙여넣으세요.
Claude CLI 로그인이 다른 머신에 있는 경우, 게이트웨이 호스트에서 openclaw models auth paste-token --provider anthropic을 사용하세요.

No API key found for provider “anthropic”

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

No credentials found for profile anthropic:default

openclaw models status를 실행하여 현재 활성 인증 프로필을 확인하세요.
온보딩을 다시 실행하거나, 해당 프로필에 setup-token / API 키를 붙여넣으세요.

No available auth profile (all in cooldown/unavailable)

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

자세한 내용: /gateway/troubleshooting 및 /help/faq.