어드바이저(advisor)는 작업을 수행하는 모델이 막히거나 중요한 결정을 앞뒀을 때, 더 강한 모델에게 자문을 구하는 도구입니다. 평소에는 빠르고 저렴한 모델이 일하고, 판단이 어려운 순간에만 상위 모델이 개입하는 구조라서 "상위 모델 수준의 결과를 더 낮은 비용으로" 노리는 기능입니다. 이 글은 공식 문서를 바탕으로 Claude Code의 /advisor 사용법과 API 쪽 개념을 정리했습니다.
🟢 2026년 9월 현재 라인업: Claude Opus 5.5 / Claude Sonnet 5 / Claude Haiku 4.5 (상위 티어: Claude Fable 5.1). · 모델 안내 · Fable 구독 안내
Fable 5·5.1 구독 안내(2026년 9월 7일 갱신): 2026년 9월 1일 출시된 Claude Fable 5.1이 현행 Fable 모델이고, Fable 5는 레거시로 전환됐습니다. 구독 조건은 두 모델이 같습니다 — Max·Team Premium 플랜은 주간 사용 한도의 50% 범위에서 포함되고, Pro·Team Standard 플랜은 사용량 크레딧(입력 100만 토큰당
어드바이저 도구란
공식 문서 기준으로, 어드바이저 도구는 실행 모델(executor) — 실제로 파일을 읽고 코드를 고치는 모델 — 이 작업 도중 접근 방식을 확정하기 전, 같은 오류가 반복될 때, 완료를 선언하기 전 같은 핵심 순간에 더 강한 어드바이저 모델을 호출하게 해줍니다. 어드바이저는 지금까지의 전체 대화(모든 도구 호출과 결과 포함)를 받아 검토하고, 실행 모델이 이어서 적용할 지침을 돌려줍니다. 어드바이저는 Anthropic 서버에서 실행되는 서버 도구(server tool)입니다.
사용 조건
- 공식 문서 기준 실험(experimental) 기능이며, 동작·가격·제공 범위는 바뀔 수 있다고 명시되어 있습니다.
- Claude Code v2.1.98 이상이 필요합니다(
claude update로 업데이트). - Anthropic API 경유에서만 동작합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 쓸 수 없습니다.
켜고 끄는 법 — /advisor
Claude Code에서 /advisor 명령을 실행하면 어드바이저로 쓸 모델을 고르는 선택지가 나옵니다. 예를 들어 Sonnet이 실행을 맡고 Opus가 자문하는 조합이 대표적입니다. 끄려면 /advisor off를 실행하거나 선택 화면에서 "No advisor"를 고르면 됩니다. 조직 차원에서 아예 비활성화하려면 환경변수 CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1을 설정합니다 — 이 경우 /advisor 명령 자체가 사라지고 설정된 advisorModel도 무시됩니다.
지원 모델 조합
공식 문서 기준으로 실행(main) 모델은 Opus 4.6 이상, Sonnet 4.6 이상, 또는 Haiku 4.5가 지원되며, Fable 5는 Claude Code v2.1.170 이상에서 지원 대상에 포함됩니다. 후속 Fable 5.1은 Claude Code v2.1.255 이상에서 쓸 수 있으며, 어드바이저 조합 지원 여부는 공식 문서에서 확인하세요. Claude Code가 인식하지 못하는 모델을 실행 모델이나 어드바이저로 지정하면 어드바이저가 붙지 않습니다. 허용되는 조합이면 어떤 짝이든 쓸 수 있고, 조합에 따라 비용과 성능의 균형이 달라집니다.
언제 자문하나요 — 호출 시점은 모델이 판단
어드바이저 호출 시점은 규칙이 아니라 모델의 판단입니다. 공식 문서는 접근 방식을 확정하기 전, 오류가 반복될 때, 작업 완료를 선언하기 전에 자문하는 경향이 있다고 설명합니다. 더 자주(또는 덜) 자문하게 하고 싶으면 프롬프트에 그렇게 적으면 됩니다 — 예를 들어 "계속하기 전에 어드바이저에게 확인해"처럼 직접 요청할 수도 있습니다. 호출 횟수를 강제로 제한하거나 강제로 호출시키는 설정은 없습니다. 자문이 진행되는 동안에는 대화 기록에 어드바이저 모델 이름과 함께 "Advising" 표시가 나타납니다.
비용과 사용량
어드바이저는 매 턴이 아니라 결정 지점에서만 호출되므로, 공식 문서 기준 빠른 실행 모델 + 강한 어드바이저 조합이 강한 모델을 처음부터 끝까지 쓰는 것보다 대체로 저렴합니다. 어드바이저 사용량은 /usage에 표시되는 세션 합계에 포함됩니다. 참고로 /advisor를 켜고 끄는 것은 모델이나 effort를 바꾸는 것과 달리 실행 모델의 프롬프트 캐시를 깨지 않습니다.
API에서 쓰려면
같은 기능이 Claude API(Messages API)에도 베타로 제공됩니다. 요청에 베타 헤더 advisor-tool-2026-03-01을 포함하고 tools 배열에 어드바이저를 선언하는 방식이며, 자세한 스펙은 공식 API 문서에 있습니다. Claude Code 쪽 사용법 전체는 Claude Code 공식 advisor 문서를 참고하세요.
Claude Code의 다른 비용 관리 요령은 Claude Code 가격 가이드에서, 도구 사용(tool use)의 기본 개념은 Tool Use 가이드에서 이어서 볼 수 있습니다.
출처: Claude Code 공식 문서(code.claude.com/docs/en/advisor), Claude API 공식 문서(platform.claude.com). 실험/베타 기능으로 동작·가격·제공 범위는 변경될 수 있습니다.