메인 콘텐츠로 건너뛰기

​
Anthropic (Claude)

Anthropic은 Claude 모델 제품군을 만들고 API를 통해 접근을 제공합니다. OpenClaw에서는 API 키나 setup-token으로 인증할 수 있습니다.

​
옵션 A: Anthropic API 키

적합한 경우: 표준 API 접근과 사용량 기반 과금. Anthropic Console에서 API 키를 생성하세요.

​
CLI 설정

openclaw onboard
# choose: Anthropic API key

# or non-interactive
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 level을 설정하지 않으면 OpenClaw에서 기본적으로 adaptive thinking을 사용합니다.
  • 메시지별(/think:<level>) 또는 모델 params인 agents.defaults.models["anthropic/<model>"].params.thinking으로 재정의할 수 있습니다.
  • 관련 Anthropic 문서:

​
Prompt caching (Anthropic API)

OpenClaw는 Anthropic의 prompt caching 기능을 지원합니다. 이 기능은 API 전용이며, 구독 인증에서는 cache 설정을 반영하지 않습니다.

​
설정

모델 설정에서 cacheRetention 파라미터를 사용하세요.
ValueCache DurationDescription
noneNo caching프롬프트 캐싱 비활성화
short5 minutesAPI Key 인증의 기본값
long1 hour확장 캐시(beta flag 필요)
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": {
          params: { cacheRetention: "long" },
        },
      },
    },
  },
}

​
기본값

Anthropic API Key 인증을 사용할 때 OpenClaw는 모든 Anthropic 모델에 cacheRetention: "short"(5분 캐시)를 자동 적용합니다. 설정 파일에서 cacheRetention을 명시하면 이를 덮어쓸 수 있습니다.

​
에이전트별 cacheRetention 재정의

모델 수준 params를 기본값으로 두고, 특정 agent는 agents.list[].params로 재정의하세요. 
{
  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
    ],
  },
}
캐시 관련 params의 config 병합 순서:
  1. agents.defaults.models["provider/model"].params
  2. agents.list[].params (id가 일치하면 키별로 덮어씀)
이렇게 하면 같은 모델을 쓰더라도 어떤 agent는 장시간 캐시를 유지하고, 다른 agent는 쓰기 비용이 아까운 burst/저재사용 트래픽을 피하기 위해 캐싱을 끌 수 있습니다.

​
Bedrock Claude notes

  • Bedrock의 Anthropic Claude 모델(amazon-bedrock/*anthropic.claude*)은 설정되어 있으면 cacheRetention pass-through를 허용합니다.
  • Anthropic이 아닌 Bedrock 모델은 런타임에 cacheRetention: "none"으로 강제됩니다.
  • Anthropic API-key smart default는 명시적 값이 없을 때 Claude-on-Bedrock 모델 ref에도 cacheRetention: "short"를 채워 넣습니다.

​
Legacy parameter

이전의 cacheControlTtl 파라미터도 하위 호환성을 위해 여전히 지원됩니다.
  • "5m"는 short로 매핑
  • "1h"는 long으로 매핑
새 cacheRetention 파라미터로 옮기는 것을 권장합니다. OpenClaw는 Anthropic API 요청에 extended-cache-ttl-2025-04-11 beta flag를 포함합니다. 프로바이더 header를 직접 재정의한다면 이를 유지하세요(/gateway/configuration 참고).

​
1M context window (Anthropic beta)

Anthropic의 1M context window는 beta gate 뒤에 있습니다. 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-* beta 요청을 거부합니다. OpenClaw는 OAuth 인증에서는 context1m beta header를 자동으로 건너뛰고, 필요한 OAuth beta만 유지합니다.

​
옵션 B: Claude setup-token

적합한 경우: Claude 구독을 사용할 때.

​
Where to get a 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-token)

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

​
설정 예시 (setup-token)

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

​
참고 사항

​
Troubleshooting

401 errors / token suddenly invalid
  • 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의 키를 자동 상속하지 않습니다.
  • 해당 agent에 대해 온보딩을 다시 실행하거나, gateway 호스트에 setup-token/API 키를 붙여넣은 뒤 openclaw models status로 확인하세요.