--- read_when: - OpenClaw에서 Anthropic 모델을 사용하려는 경우 summary: OpenClaw에서 API 키 또는 Claude CLI를 통해 Anthropic Claude 사용 title: Anthropic x-i18n: generated_at: "2026-07-04T15:11:51Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 0e6fd143b85bb448f65d5d1b35ce465cce7c6f41987b39b9665910cf71761032 source_path: providers/anthropic.md workflow: 16 --- Anthropic은 **Claude** 모델 제품군을 만듭니다. OpenClaw는 두 가지 인증 경로를 지원합니다. - **API 키** — 사용량 기반 청구가 적용되는 Anthropic API 직접 액세스(`anthropic/*` 모델) - **Claude CLI** — 같은 호스트의 기존 Claude Code 로그인을 재사용 OpenClaw의 Claude CLI 백엔드는 설치된 Claude Code CLI를 비대화형 print 모드로 실행합니다. Anthropic의 현재 Claude Code 문서는 `claude -p`를 Agent SDK/프로그래밍 방식 사용으로 설명합니다. Anthropic의 2026년 6월 15일 지원 업데이트는 발표되었던 Agent SDK 청구 변경을 일시 중단했습니다. 현재 Anthropic은 Claude Agent SDK, `claude -p`, 서드파티 앱 사용량이 여전히 구독의 사용량 한도에서 차감된다고 말합니다. 이전에 발표된 월별 Agent SDK 크레딧은 Anthropic이 해당 계획을 수정하는 동안 사용할 수 없습니다. 대화형 Claude Code도 여전히 로그인된 Claude 플랜 한도에서 차감됩니다. API 키 인증은 계속해서 종량제 API 청구가 직접 적용됩니다. 장기간 실행되는 gateway 호스트, 공유 자동화, 예측 가능한 프로덕션 지출에는 Anthropic API 키를 사용하세요. 구독 청구 동작에 의존하기 전에 Anthropic의 현재 지원 문서를 확인하세요. - [Claude Code CLI 참조](https://code.claude.com/docs/en/cli-usage) - [Claude 플랜으로 Claude Agent SDK 사용](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) - [Pro 또는 Max 플랜으로 Claude Code 사용](https://support.claude.com/en/articles/11145838-use-claude-code-with-your-pro-or-max-plan) - [Team 또는 Enterprise 플랜으로 Claude Code 사용](https://support.claude.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan) - [Claude Code 비용 관리](https://code.claude.com/docs/en/costs) ## 시작하기 **권장 대상:** 표준 API 액세스 및 사용량 기반 청구. [Anthropic Console](https://console.anthropic.com/)에서 API 키를 만듭니다. ```bash openclaw onboard # choose: Anthropic API key ``` 또는 키를 직접 전달합니다. ```bash openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY" ``` ```bash openclaw models list --provider anthropic ``` ### 구성 예시 ```json5 { env: { ANTHROPIC_API_KEY: "example-anthropic-key-not-real" }, agents: { defaults: { model: { primary: "anthropic/claude-opus-4-8" } } }, } ``` **권장 대상:** 별도 API 키 없이 기존 Claude CLI 로그인을 재사용하는 경우. 다음으로 확인합니다. ```bash claude --version ``` ```bash openclaw onboard # choose: Claude CLI ``` OpenClaw는 기존 Claude CLI 자격 증명을 감지해 재사용합니다. ```bash openclaw models list --provider anthropic ``` Claude CLI 백엔드의 설정 및 런타임 세부 정보는 [CLI 백엔드](/ko/gateway/cli-backends)에 있습니다. Claude CLI 재사용은 OpenClaw 프로세스가 Claude CLI 로그인과 같은 호스트에서 실행될 것을 전제로 합니다. Docker 설치는 컨테이너 홈을 유지하고 그 안에서 Claude Code에 로그인할 수 있습니다. 자세한 내용은 [Docker의 Claude CLI 백엔드](/ko/install/docker#claude-cli-backend-in-docker)를 참고하세요. [Podman](/ko/install/podman) 같은 다른 컨테이너 설치는 호스트의 `~/.claude`를 설정이나 런타임에 마운트하지 않습니다. 그런 환경에서는 Anthropic API 키를 사용하거나, [OpenAI Codex](/ko/providers/openai)처럼 OpenClaw가 관리하는 OAuth를 제공하는 provider를 선택하세요. ### 구성 예시 표준 Anthropic 모델 참조와 CLI 런타임 오버라이드를 함께 사용하는 것을 권장합니다. ```json5 { agents: { defaults: { model: { primary: "anthropic/claude-opus-4-8" }, models: { "anthropic/claude-opus-4-8": { agentRuntime: { id: "claude-cli" }, }, }, }, }, } ``` 레거시 `claude-cli/claude-opus-4-7` 모델 참조는 호환성을 위해 여전히 작동하지만, 새 구성은 provider/model 선택을 `anthropic/*`로 유지하고 실행 백엔드는 provider/model 런타임 정책에 두어야 합니다. ### 청구 및 `claude -p` OpenClaw는 Claude CLI 실행에 Claude Code의 비대화형 `claude -p` 경로를 사용합니다. Anthropic은 현재 이 경로를 Agent SDK/프로그래밍 방식 사용으로 취급합니다. - Anthropic의 2026년 6월 15일 지원 업데이트는 이전에 발표된 별도 Agent SDK 크레딧 플랜을 일시 중단했습니다. - 현재 구독 플랜의 Claude Agent SDK, `claude -p`, 서드파티 앱 사용량은 여전히 로그인된 구독의 사용량 한도에서 차감됩니다. - 이전에 발표된 월별 Agent SDK 크레딧은 Anthropic이 해당 계획을 수정하는 동안 사용할 수 없습니다. - Console/API 키 로그인은 종량제 API 청구를 사용하며 구독 Agent SDK 크레딧을 받지 않습니다. 일시 중단 공지는 Anthropic의 [Agent SDK 플랜 문서](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan)를 참고하고, 구독 동작은 Claude Code 플랜 문서의 [Pro/Max](https://support.claude.com/en/articles/11145838-use-claude-code-with-your-pro-or-max-plan) 및 [Team/Enterprise](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan)를 참고하세요. Anthropic은 OpenClaw 릴리스 없이도 Claude Code 청구 및 속도 제한 동작을 변경할 수 있습니다. 청구 예측 가능성이 중요하다면 `claude auth status`, `/status`, 그리고 연결된 Anthropic 문서를 확인하세요. 공유 프로덕션 자동화에는 Claude CLI 대신 Anthropic API 키를 사용하세요. OpenClaw는 [OpenAI Codex](/ko/providers/openai), [Qwen Cloud](/ko/providers/qwen), [MiniMax](/ko/providers/minimax), [Z.AI / GLM](/ko/providers/zai)의 구독형 옵션도 지원합니다. ## 사고 기본값(Claude Fable 5, 4.8, 4.6) `anthropic/claude-fable-5`는 항상 adaptive thinking을 사용하며 기본값은 `high` effort입니다. Anthropic은 이 모델에서 thinking 비활성화를 허용하지 않으므로 `/think off`와 `/think minimal`은 `low` effort를 사용합니다. OpenClaw는 Fable 5 요청에서 사용자 지정 temperature 값도 생략합니다. Claude Opus 4.8은 OpenClaw에서 기본적으로 thinking이 꺼진 상태를 유지합니다. `/think high|xhigh|max`로 adaptive thinking을 명시적으로 활성화하면 OpenClaw는 Anthropic의 Opus 4.8 effort 값을 전송합니다. Claude 4.6 모델은 기본값이 `adaptive`입니다. 메시지별로 `/think:` 또는 모델 매개변수에서 오버라이드합니다. ```json5 { agents: { defaults: { models: { "anthropic/claude-opus-4-8": { params: { thinking: "high" }, }, }, }, }, } ``` 관련 Anthropic 문서: - [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking) - [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) ## 안전 거부 폴백(Claude Fable 5) Claude Fable 5를 사용한다는 것은 Claude Opus 4.8도 사용한다는 뜻입니다. Fable 5는 요청을 거절할 수 있는 안전 분류기와 함께 제공되며, Anthropic이 승인한 복구 방식은 해당 턴을 `claude-opus-4-8`이 처리하도록 하는 것입니다. OpenClaw는 직접 API 키 요청에 대해 이를 자동으로 사용하므로, 일부 Fable 턴은 Claude Opus 4.8로 답변되고 청구됩니다. 정책이나 예산상 Opus가 처리하는 턴을 허용할 수 없다면 `anthropic/claude-fable-5`를 선택하지 마세요. ### 이 기능이 있는 이유 Fable 5 분류기는 제한된 도메인의 요청에 대해 `stop_reason: "refusal"`을 반환하며, 무해한 주변 작업(보안 도구, 생명과학, 또는 모델에 원시 추론을 재현해 달라고 요청하는 경우)에도 오탐이 발생합니다. 폴백이 없으면 다른 Claude 모델이 기꺼이 처리할 수 있는 경우에도 턴이 오류로 종료됩니다. Anthropic 자체 거부 메시지는 API 통합자에게 폴백 모델을 구성하라고 안내합니다. ### 작동 방식 1. `anthropic/claude-fable-5`로 보내는 모든 직접 API 키 요청에 대해 OpenClaw는 Anthropic의 서버 측 폴백 옵트인을 전송합니다. 즉, `server-side-fallback-2026-06-01` 베타 헤더와 `fallbacks: [{"model": "claude-opus-4-8"}]`를 함께 보냅니다. Claude Opus 4.8은 Anthropic이 Fable 5에 허용하는 유일한 폴백 대상입니다. 2. 안전 분류기 거절만 폴백을 트리거합니다. 속도 제한, 과부하, 서버 오류는 이전과 정확히 동일하게 동작하며 OpenClaw의 일반 [모델 장애 조치](/ko/concepts/model-failover)를 거칩니다. 3. 구조는 같은 호출 안에서 일어납니다. 출력 전에 거절되면 지연 시간 외에는 보이지 않으며 전체 답변은 Opus 4.8에서 나옵니다. 스트림 중간 거절의 경우 부분 텍스트는 폴백 모델이 이어서 계속할 접두사로 유지되고, 거절된 모델의 reasoning과 도구 호출은 Anthropic의 재생 규칙에 따라 폐기됩니다(다시 되돌려 보내거나 실행해서는 안 됩니다). 4. Claude Opus 4.8도 거절하면, 이 기능 이전과 정확히 동일하게 해당 턴은 거부를 오류로 표시합니다. 폴백은 Anthropic API 수준에서 발생하므로 `claude-opus-4-8`이 구성된 모델 목록이나 폴백 체인에 있을 필요는 없습니다. Fable을 사용할 수 있는 API 키는 항상 Opus를 처리할 수 있습니다. ### 관측 가능성 및 청구 - 폴백으로 처리된 턴은 assistant 메시지에 `fromModel`과 `toModel`을 명명하는 `provider_fallback` 진단을 기록하고, 메시지의 `responseModel`은 `claude-opus-4-8`을 보고합니다. - Anthropic은 시도별로 청구합니다. 출력 전 거절은 무료이며, 구조는 Claude Opus 4.8 요율(현재 Fable 5 요율의 절반)로 청구됩니다. OpenClaw의 턴별 비용 추정도 이에 맞춰 폴백 처리 턴을 Opus 요율로 산정합니다. - 스트림 중간 거절은 이미 스트리밍된 Fable 부분도 Anthropic 측에서 추가로 청구합니다. 해당 부분은 API의 시도별 사용량에 보고되지만 OpenClaw의 턴별 추정에는 포함되지 않습니다. ### 범위 `api.anthropic.com`에 대해 API 키 인증을 사용하는 `anthropic/claude-fable-5`에 적용됩니다. OAuth(Claude CLI 구독 재사용), 프록시 기본 URL, Bedrock, Vertex, Foundry 요청은 변경되지 않으며 해당 환경에서는 여전히 거부가 오류로 표시됩니다. 라이브 검증됨: Fable 5에 원시 chain of thought를 재현해 달라는 무해한 프롬프트는 폴백 없이 전송하면 `category: "reasoning_extraction"`으로 거절되고, 같은 프롬프트를 OpenClaw를 통해 보내면 `provider_fallback` 진단이 첨부된 정상적인 Opus 처리 답변을 반환합니다. 기저 동작은 Anthropic의 [거부 및 폴백 가이드](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback)를 참고하세요. ## 프롬프트 캐싱 OpenClaw는 API 키 인증에 대해 Anthropic의 프롬프트 캐싱 기능을 지원합니다. | 값 | 캐시 기간 | 설명 | | ------------------- | -------------- | -------------------------------------- | | `"short"` (기본값) | 5분 | API 키 인증에 자동 적용 | | `"long"` | 1시간 | 확장 캐시 | | `"none"` | 캐싱 없음 | 프롬프트 캐싱 비활성화 | ```json5 { agents: { defaults: { models: { "anthropic/claude-opus-4-6": { params: { cacheRetention: "long" }, }, }, }, }, } ``` 모델 수준 매개변수를 기준값으로 사용한 다음, `agents.list[].params`로 특정 에이전트를 오버라이드합니다: ```json5 { 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`, 키별로 재정의) 이를 통해 한 agent는 장기 캐시를 유지하고, 같은 모델을 사용하는 다른 agent는 버스트성/낮은 재사용 트래픽에 대해 캐싱을 비활성화할 수 있습니다. - Bedrock의 Anthropic Claude 모델(`amazon-bedrock/*anthropic.claude*`)은 구성된 경우 `cacheRetention` 패스스루를 허용합니다. - Anthropic이 아닌 Bedrock 모델은 런타임에 `cacheRetention: "none"`으로 강제됩니다. - 명시적 값이 설정되지 않은 경우 API 키 스마트 기본값도 Claude-on-Bedrock 참조에 `cacheRetention: "short"`를 시드합니다. ## 고급 구성 OpenClaw의 공유 `/fast` 토글은 Anthropic 직접 트래픽(`api.anthropic.com`으로의 API 키 및 OAuth)을 지원합니다. | 명령 | 매핑 대상 | |---------|---------| | `/fast on` | `service_tier: "auto"` | | `/fast off` | `service_tier: "standard_only"` | ```json5 { agents: { defaults: { models: { "anthropic/claude-sonnet-4-6": { params: { fastMode: true }, }, }, }, }, } ``` - 직접 `api.anthropic.com` 요청에만 주입됩니다. 프록시 경로는 `service_tier`를 변경하지 않습니다. - 명시적 `serviceTier` 또는 `service_tier` params는 둘 다 설정된 경우 `/fast`를 재정의합니다. - Priority Tier 용량이 없는 계정에서는 `service_tier: "auto"`가 `standard`로 해석될 수 있습니다. 번들 Anthropic Plugin은 이미지 및 PDF 이해를 등록합니다. OpenClaw는 구성된 Anthropic 인증에서 미디어 기능을 자동으로 확인하므로 추가 구성이 필요 없습니다. | 속성 | 값 | | --------------- | --------------------- | | 기본 모델 | `claude-opus-4-8` | | 지원 입력 | 이미지, PDF 문서 | 이미지 또는 PDF가 대화에 첨부되면 OpenClaw는 이를 Anthropic 미디어 이해 제공자를 통해 자동으로 라우팅합니다. Anthropic의 1M 컨텍스트 창은 Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6과 같은 GA 지원 Claude 4.x 모델에서 사용할 수 있습니다. OpenClaw는 해당 모델의 크기를 자동으로 1M으로 설정합니다. ```json5 { agents: { defaults: { models: { "anthropic/claude-opus-4-6": {}, }, }, }, } ``` 이전 구성은 `params.context1m: true`를 유지할 수 있지만, OpenClaw는 더 이상 폐기된 `context-1m-2025-08-07` 베타 헤더를 전송하지 않습니다. 해당 값이 있는 이전 `anthropicBeta` 구성 항목은 요청 헤더 해석 중 무시되며, 지원되지 않는 이전 Claude 모델은 일반 컨텍스트 창을 유지합니다. `params.context1m: true`는 적격 GA 지원 Opus 및 Sonnet 모델의 Claude CLI 백엔드(`claude-cli/*`)에도 적용되어, 해당 CLI 세션의 런타임 컨텍스트 창이 직접 API 동작과 일치하도록 유지합니다. Anthropic 자격 증명에 긴 컨텍스트 액세스가 필요합니다. OAuth/구독 토큰 인증은 필요한 Anthropic 베타 헤더를 유지하지만, OpenClaw는 이전 구성에 남아 있는 경우 폐기된 1M 베타 헤더를 제거합니다. `anthropic/claude-opus-4-8` 및 해당 `claude-cli` 변형은 기본적으로 1M 컨텍스트 창을 가지므로 `params.context1m: true`가 필요 없습니다. ## 문제 해결 Anthropic 토큰 인증은 만료될 수 있으며 취소될 수 있습니다. 새 설정에서는 대신 Anthropic API 키를 사용하세요. Anthropic 인증은 **agent별**입니다. 새 agent는 기본 agent의 키를 상속하지 않습니다. 해당 agent에 대해 온보딩을 다시 실행하거나 Gateway 호스트에 API 키를 구성한 다음 `openclaw models status`로 확인하세요. `openclaw models status`를 실행하여 어떤 인증 프로필이 활성 상태인지 확인하세요. 온보딩을 다시 실행하거나 해당 프로필 경로에 대한 API 키를 구성하세요. `openclaw models status --json`에서 `auth.unusableProfiles`를 확인하세요. Anthropic 속도 제한 쿨다운은 모델 범위일 수 있으므로, 형제 Anthropic 모델은 여전히 사용할 수 있을 수 있습니다. 다른 Anthropic 프로필을 추가하거나 쿨다운이 끝날 때까지 기다리세요. 추가 도움말: [문제 해결](/ko/help/troubleshooting) 및 [FAQ](/ko/help/faq). ## 관련 항목 제공자, 모델 참조 및 장애 조치 동작 선택. Claude CLI 백엔드 설정 및 런타임 세부 정보. 제공자 전반에서 프롬프트 캐싱이 작동하는 방식. 인증 세부 정보 및 자격 증명 재사용 규칙.