어드바이저(advisor) 도구로 어려운 결정을 위임하기

과제를 진행하다 보면 '이 방향이 맞을까', '이 에러는 왜 반복될까', '이제 끝내도 될까' 같은 판단이 필요한 순간이 오죠. 어드바이저 도구는 바로 그런 결정의 순간에, 주 모델보다 더 강한 두 번째 모델을 Claude가 상담하도록 만들어 주는 기능이에요. 어드바이저는 전체 대화(모든 도구 호출과 결과 포함)를 받아서 안내를 돌려주고, Claude는 이를 반영해 계속 진행합니다.

어드바이저는 Anthropic 인프라에서 서버 도구로 실행되며, 구독 계정과 API 과금 계정 모두에서 쓸 수 있어요. 어떤 모델을 어드바이저로 쓸지는 직접 고르고, 언제 호출할지는 Claude가 정합니다. 이 페이지에서는 어드바이저를 켜는 법, 허용되는 모델 조합, 상담 중에 화면에 표시되는 것, 그리고 과금 방식을 다룹니다.

출처: 공식문서

본문

어드바이저는 언제 쓸까

대부분의 턴은 평범하지만 결과를 좌우하는 건 계획의 질인, 길고 다단계인 과제에 어울려요. 대규모 리팩터링, 같은 에러가 반복되는 디버깅 세션, 그리고 Claude가 '끝났다'고 선언하기 전에 독립적으로 검증받고 싶은 작업이 대표적이죠.

계획할 것이 거의 없는 짧은 작업이나, 매 턴마다 가장 강한 모델이 필요한 작업에서는 추가 가치가 적어요. 그럴 땐 주 모델을 전환하거나, "opusplan 및 서브에이전트와의 비교"에서 두 번째 의견을 얻는 다른 방법을 살펴보세요.

어드바이저 켜기

어드바이저 모델은 세 가지 방법으로 설정할 수 있어요.

/advisor 명령: 세션 중간에 설정·변경하고 기본값으로 저장
advisorModel 설정: 설정 파일에 영구 기본값 구성
--advisor 플래그: 시작할 때 단일 세션용으로 설정

각 방법 모두 지원하는 주 모델을 쓰는 세션에서 어드바이저를 켜요. 세션이 시작하면 Claude Code는 Advisor Tool (experimental) is on and may use more tokens · /advisor 알림을 보여줍니다. 어드바이저를 끄려면 Turn the advisor off를 보세요. 일부 플랜에서는 Fable을 어드바이저로 쓸 때 Fable 사용량을 사용 크레딧으로 과금하는 일회성 동의가 필요해요.

`/advisor` 명령 사용하기

인자 없이 /advisor를 실행하면 사용 가능한 어드바이저 모델 목록이 열리고, 모델을 직접 넘겨도 됩니다.

/advisor opus

명령은 Advisor set to 뒤에 어드바이저 모델 이름을 붙여 확인해 줘요. 선택은 사용자 설정의 advisorModel에 저장되어 세션을 넘어 유지됩니다(세션에만 적용된다고 advisorModel 항목이 명시한 경우 제외).

명령은 터미널 선택기가 없는 곳에서도 동작해요: -p를 쓰는 비대화형 모드, Agent SDK, 데스크톱 앱, Remote Control에서 말이죠. 여기엔 Claude Code v2.1.260 이상이 필요해요. 해당 화면에서는:

인자 없는 /advisor는 현재 어드바이저 모델과 허용되는 별칭을 출력
/advisor opus처럼 모델을 넘기면 설정
/advisor off는 끔

Claude Code는 조직의 availableModels 허용 목록에서 제외된 저장 어드바이저를 호출하지 않아요. 어드바이저를 쓰려면 /advisor로 허용된 모델을 고르세요. 현재 주 모델이 지원하지 않는 어드바이저여도 Claude Code는 저장은 해 둡니다. 그 어드바이저는 이후에 /model로 호환되는 주 모델로 전환하면 활성화돼요.

일부 플랜에서는 Fable을 어드바이저로 쓸 때 Fable 사용량을 사용 크레딧으로 과금하는 일회성 동의가 필요합니다. 동의 전에 /advisor fable이 하는 일은 Fable advisor and usage credits에서 보세요.

설정에서 `advisorModel` 지정하기

세션을 열지 않고 기본값으로 구성하려면 설정 파일에 넣으세요.

{
  "advisorModel": "opus"
}

`--advisor` 플래그 사용하기

저장된 설정을 바꾸지 않고 단일 세션만 지정하려면 플래그로 시작하세요.

claude --advisor opus

이 세션 동안 Claude Code는 advisorModel 설정 대신 플래그를 사용해요. --advisor는 claude --help에는 나열되지 않습니다. 다음 조건에서는 시작 시 에러로 종료돼요.

세션의 주 모델이 어드바이저를 지원하지 않거나
요청한 모델(예: Haiku)이 어드바이저가 될 수 없거나
조직의 availableModels 허용 목록이 요청한 모델을 제외하거나
Fable을 요청했는데 계정에 아직 사용 크레딧 동의가 필요하거나

이런 조건 중 하나가 적용되는데 --advisor로 백그라운드 세션을 시작하면, Claude Code는 종료하는 대신 어드바이저 없이 세션을 시작해요.

어드바이저 모델 고르기

어드바이저는 주 모델만큼은 강력해야 해요. 각 주 모델이 받아들이는 어드바이저는 다음과 같습니다.

주 모델	허용되는 어드바이저	비고
Haiku 4.5	Fable, Opus, Sonnet	Haiku는 어드바이저를 호출할 수 있지만 어드바이저가 될 수는 없음
Sonnet 4.6	Fable, Opus, Sonnet
Sonnet 5	Fable, Opus, Sonnet 5	Sonnet 4.6 어드바이저는 거부됨
Opus 4.6	Fable, Opus, Sonnet 5	Sonnet 5와 Opus 4.6은 동등하게 강력하게 평가되므로 Opus 4.6 주 모델은 Sonnet 5 어드바이저를 받아들임
Opus 4.7 이상	Fable, 그리고 Opus 4.7 이상	Opus 4.7 이상 모델은 동등하게 강력하게 평가되어 서로 어드바이저를 받아들임. Opus 4.7 주 모델이 Opus 4.6 또는 Sonnet 5 어드바이저를 쓰면 거부됨
Fable 5.1 또는 Fable 5	Fable 5.1 또는 Fable 5	Opus나 Sonnet 어드바이저는 거부됨

Fable 5.1은 Claude Code v2.1.257 이상이 필요해요. 두 Fable 모델 모두 Fable 접근 권한이 필요합니다.

어드바이저는 fable, opus, sonnet으로 설정하세요. 이 별칭은 각 모델 계열의 Claude Code 내장 기본 버전으로 해석되며, 새 Claude Code 릴리스와 함께 앞으로 나아갑니다. claude-opus-5 같은 전체 모델 ID를 넘길 수도 있어요.

서브에이전트는 설정된 어드바이저를 상속하고, 자신의 모델에 대해 동일한 조합 검사를 적용합니다.

Claude Code는 요청을 보내기 전에 조합을 검증해요.

어드바이저가 주 모델보다 약하면, 어드바이저는 주 모델 요청에 붙지 않습니다. /advisor 명령 출력과 알림이 이를 보여줘요. 자신의 모델이 조합을 만족하는 서브에이전트는 여전히 어드바이저를 쓸 수 있어요.
주 모델 또는 어드바이저가 Claude Code가 모르는 모델이면, 어드바이저는 붙지 않습니다.

Fable 어드바이저와 사용 크레딧

일부 플랜에서는 Fable 사용량이 사용 크레딧으로 과금되고, 어드바이저로서의 Fable도 같은 방식으로 과금돼요. 계정에 Fable 사용량을 사용 크레딧으로 과금하는 데 필요한 일회성 동의가 있으면, Claude Code는 /model로 Fable 모델을 선택할 때 동의를 요청하고, 동의를 수락하기 전까지는 Fable을 어드바이저로 적용하지 않습니다.

동의 전에는 /advisor fable을 입력하거나 /advisor 선택기에서 Fable을 골라도 Claude Code는 Fable을 어드바이저로 저장하지 않아요. 대신 /model fable을 가리킵니다. claude --advisor fable로 실행하면 Claude Code는 시작 시 /model fable을 가리키는 메시지와 함께 종료됩니다. 백그라운드 세션에서는 종료하는 대신 어드바이저 없이 세션을 시작해요. 이미 advisorModel로 Fable이 저장되어 있으면, Claude Code는 어드바이저 없이 요청을 보냅니다. 주 모델이 어드바이저를 지원하는 대화형 세션에서는 /model fable을 가리키는 알림도 보여줘요.

동의하려면 /model fable을 실행하고 Fable로 계속하기를 선택하세요. Claude Code는 동의를 기록하고 Fable을 선택 모델로 저장합니다. 그런 다음 어드바이저로 Fable을 선택하면 됩니다.

일반적인 모델 조합

허용되는 어떤 조합이든 동작해요. 다음 조합들은 비용과 성능을 서로 다른 방식으로 균형 잡습니다.

조합	언제 쓰나
Sonnet 주 + Opus 어드바이저	Sonnet이 일상 작업을 처리하고 계획, 모호한 실패, 완료 검사를 Opus로 에스컬레이션
Sonnet 주 + Fable 어드바이저	내내 Fable을 돌리지 않고 결정 지점에서만 Fable 안내. Fable 접근 권한 필요
Haiku 주 + Opus 어드바이저	가장 저렴한 주 모델에 강력한 계획. Haiku 단독보다는 비싸지만 주 모델을 Sonnet·Opus로 바꾸는 것보다는 저렴
Opus 주 + Opus 어드바이저	두 번째 Opus가 첫 번째를 검토. 독립적 검토가 비용보다 중요한 고위험 작업에 유용
Fable 주 + Fable 어드바이저	Fable을 쓸 수 있을 때 가장 강력한 조합. Claude Code는 Fable 주 모델에 Opus·Sonnet 어드바이저를 적용하지 않음
Sonnet 주 + Sonnet 어드바이저	일상적인 실수를 잡는 저비용 두 번째 의견

Claude가 어드바이저를 상담하는 시점

Claude가 언제 어드바이저를 호출할지 스스로 정해요. 접근 방식을 결정하기 전, 에러가 반복될 때, 작업 완료를 선언하기 전에 상담하는 경향이 있지만, 시점은 규칙이 아니라 모델 주도입니다.

프롬프트에서 다른 도구를 요청하듯 상담을 요청할 수 있어요. 예를 들어 consult the advisor before you continue처럼요. 어드바이저 호출을 제한하거나 강제하는 설정은 없으니, 더 자주·덜 자주 상담하길 원하면 지시에 말하면 됩니다.

세션 중 화면에 보이는 것

Claude가 어드바이저를 호출하면, 호출이 진행되는 동안 트랜스크립트에 어드바이저 모델 이름이 붙은 Advising 줄이 표시돼요. 결과가 돌아오면 그 줄이 어드바이저가 안내를 줬는지 보고합니다.

Reviewed: 어드바이저가 대화를 검토했음을 확인. 읽을 수 있는 안내를 돌려줬다면 Ctrl+O로 읽기
Declined: 줄이 Advisor declined to advise on this request로 표시. 어드바이저가 이유를 줬다면 Ctrl+O로 읽기

Claude는 일반적으로 어드바이저의 안내를 따르지만, 자신의 증거가 특정 주장과 모순되면 적응해요. 권장 단계를 시도했는데 실패하거나, 파일 내용이 조언과 모순되면 Claude는 무조건 따르는 대신 충돌을 표면화합니다.

어드바이저는 항상 전체 대화를 받고, 시점은 Claude가 통제해요. 더 많은 통제나 다른 구성을 원하면 어드바이저가 서브에이전트·opusplan과 어떻게 다른지를 보세요.

비용

Claude가 어드바이저를 호출하면 어드바이저 모델이 대화를 읽으므로, 각 호출은 주 모델의 사용량에 더해 어드바이저 모델 요율로 토큰을 소비해요. 어드바이저 토큰의 과금 방식은 지불 방식에 따라 달라집니다.

API 과금: 어드바이저 토큰에 대해 어드바이저 모델의 입력·출력 요율을 지불
구독 플랜: 어드바이저 사용량은 플랜의 사용량 한도에 합산. 단, Fable 어드바이저는 Fable 사용량이 그렇게 되는 플랜에서 사용 크레딧으로 과금

계정에 사용 크레딧 동의가 필요하면, Claude Code가 동의 전까지 선택을 적용하지 않으므로 Fable 어드바이저는 그 전까지 과금되지 않습니다.

Claude는 매 턴이 아니라 결정 지점에서 어드바이저를 호출하므로, 빠른 주 모델과 더 강한 어드바이저를 조합하는 것이 보통 내내 강한 모델을 돌리는 것보다 저렴해요. 어드바이저 사용량은 /usage가 보여주는 세션 합계에 포함됩니다.

어드바이저 토큰이 API 응답에서 어떻게 보고되는지는 Claude API 문서의 Usage and billing을 보세요.

프롬프트 캐싱에 미치는 영향

세션 중간에 어드바이저를 켜거나 꺼도 주 모델의 프롬프트 캐시는 무효화되지 않아요. 모델 전환과 달리 /advisor 토글은 캐시된 프리픽스를 그대로 유지하고, 어드바이저가 돌려준 안내는 이후 턴에서 트랜스크립트의 일부로 캐시됩니다.

어드바이저 모델 자체의 대화 읽기는 캐시되지 않아요. 각 어드바이저 호출은 전체 트랜스크립트를 새로 처리하고, 호출 간 재사용은 없습니다.

요구 사항

어드바이저 도구는 다음을 모두 요구합니다.

Anthropic API 전용: 어드바이저는 서버 실행 도구입니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, Microsoft Foundry에서는 사용할 수 없어요. ANTHROPIC_BASE_URL로 구성된 LLM 게이트웨이를 통해 쓰면, 게이트웨이가 요청을 그대로 Anthropic API로 전달하는지에 따라 가용성이 달라집니다.
지원되는 주 모델: Fable, Opus 4.6 이상, Sonnet 4.6 이상, Haiku 4.5. 각각이 받아들이는 어드바이저는 어드바이저 모델 고르기 참조.
Feature-flag 조회: Claude Code는 Anthropic에서 가져온 feature flag를 통해 어드바이저를 켭니다. DISABLE_TELEMETRY처럼 flag 조회를 끄는 변수가 설정된 세션에서는 어드바이저가 꺼진 채 유지됩니다. Feature-flag 조회가 필요한 기능 참조.

어드바이저 끄기

어드바이저 사용을 중단하려면 /advisor off를 실행하거나 /advisor 선택기에서 No advisor를 고르세요.

/advisor off

어드바이저 도구를 완전히 비활성화하려면 CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1을 설정하세요. /advisor 명령은 사용 불가가 되고, 설정된 advisorModel은 무시됩니다. --advisor 플래그는 받아들여지지만 효과는 없어요. 환경 변수 참조.

접근법	강한 모델이 실행되는 시점	시작 방식
Advisor 도구	과제 중간의 결정 지점	Claude가 필요할 때 호출
`opusplan`	`availableModels`가 허용할 때 계획 모드 동안, 이후 실행은 Sonnet으로 전환	계획 모드 진입
`model`이 설정된 서브에이전트	위임된 하위 과제 전체	Claude가 위임하거나 사용자가 서브에이전트 호출
`/model`	다음 요청부터	사용자가 모델 전환

더 알아보기

Model configuration: 모델 전환, 노력 수준 설정, opusplan 사용
Manage costs effectively: 모델 전반의 토큰 사용량 추적
Advisor tool in the Claude API: 기본 서버 도구 이해 또는 Messages API에서 직접 사용
The advisor strategy: 빠른 주 모델과 더 강한 어드바이저를 조합하면 왜 효과적인지

어드바이저(advisor) 도구로 어려운 결정을 위임하기