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 문서:
- Adaptive thinking
- Extended thinking

Prompt caching (Anthropic API)

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

설정

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

Value	Cache Duration	Description
`none`	No 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을 명시하면 이를 덮어쓸 수 있습니다.

에이전트별 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 병합 순서:

agents.defaults.models["provider/model"].params
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" } } },
}

참고 사항

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

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로 확인하세요.

개요

모델 개념

설정

프로바이더

Anthropic

Anthropic (Claude)

옵션 A: Anthropic API 키

CLI 설정

설정 예시

기본 thinking 동작 (Claude 4.6)

Prompt caching (Anthropic API)

설정

기본값

에이전트별 cacheRetention 재정의

Bedrock Claude notes

Legacy parameter

1M context window (Anthropic beta)

옵션 B: Claude setup-token

Where to get a setup-token

CLI 설정 (setup-token)

설정 예시 (setup-token)

참고 사항

Troubleshooting

​Anthropic (Claude)

​옵션 A: Anthropic API 키

​CLI 설정

​설정 예시

​기본 thinking 동작 (Claude 4.6)

​Prompt caching (Anthropic API)

​설정

​기본값

​에이전트별 cacheRetention 재정의

​Bedrock Claude notes

​Legacy parameter

​1M context window (Anthropic beta)

​옵션 B: Claude setup-token

​Where to get a setup-token

​CLI 설정 (setup-token)

​설정 예시 (setup-token)

​참고 사항

​Troubleshooting

Anthropic (Claude)

옵션 A: Anthropic API 키

CLI 설정

설정 예시

기본 thinking 동작 (Claude 4.6)

Prompt caching (Anthropic API)

설정

기본값

에이전트별 cacheRetention 재정의

Bedrock Claude notes

Legacy parameter

1M context window (Anthropic beta)

옵션 B: Claude setup-token

Where to get a setup-token

CLI 설정 (setup-token)

설정 예시 (setup-token)

참고 사항

Troubleshooting