Advisor 도구로 어려운 결정 에스컬레이션

공식 기준: https://code.claude.com/docs/en/advisor

기준일: 2026-07-26 · CLI 기준 2.1.220

개요

Advisor 도구는 메인 모델이 작업 중 핵심 시점(접근법 확정 전, 반복 오류, 완료 선언 전 등)에 더 강한 두 번째 모델을 서버 측으로 호출해 전체 대화(모든 tool call·결과 포함)를 검토하고 지침을 받도록 합니다.

실험적이며 Anthropic API 전용입니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud Agent Platform, Microsoft Foundry에서는 사용할 수 없습니다. 동작·가격·가용성은 변경될 수 있습니다.

Advisor는 Anthropic 인프라의 server tool로 실행됩니다. 구독·API 과금 계정 모두 사용 가능하며, 어떤 모델이 advisor인지는 사용자가 고르고 호출 시점은 Claude가 결정합니다.

핵심 개념

Advisor model: 메인 모델 이상 능력의 상담 모델
Server tool: 서버에서 전체 transcript를 읽어 지침 반환
활성화 경로: /advisor, advisorModel 설정, --advisor 플래그
비용: advisor 모델 요율로 추가 토큰 소비; 매 턴이 아니라 결정 지점 호출

상세

언제 쓰는가

긴 다단계 작업에서 대부분 턴은 일상적이지만 계획 품질이 결과를 좌우할 때 적합합니다. 대규모 리팩터, 반복 오류 디버깅, 완료 전 독립 점검 등이 예입니다.

짧은 작업이나 매 턴 최강 모델이 필요한 작업에는 가치가 적습니다. 그 경우 메인 모델을 바꾸거나 opusplan·subagents를 검토하세요.

활성화 방법

다음 중 하나로 advisor 모델을 설정하면, 메인 모델이 지원하는 세션에서 advisor가 켜지고 시작 후 Advisor Tool (experimental) is on and may use more tokens · /advisor 알림이 표시됩니다.

`/advisor` 명령

/advisor opus

인수 없이 실행하면 피커가 열립니다. 선택은 user settings의 advisorModel에 저장되어 세션 간 유지됩니다.

조직 availableModels allowlist가 저장된 advisor를 제외하면 허용 모델을 고를 때까지 호출되지 않습니다. 현재 메인 모델이 advisor를 지원하지 않아도 선택은 저장되며, 호환 메인으로 /model 전환 시 활성화됩니다.

settings의 `advisorModel`

{
  "advisorModel": "opus"
}

`--advisor` 플래그

claude --advisor opus

해당 세션에서 설정 파일보다 우선합니다. claude --help에는 목록되지 않습니다. 메인 모델이 미지원이거나 allowlist 제외 시 오류로 종료합니다.

참고 (min-version 2.1.210): Claude Code는 Fable 5를 advisor로 제공하지 않습니다. Fable 5 접근이 있는 조직에서도 피커에 Fable 5 (temporarily unavailable)로 dimmed 표시되며 /advisor fable·--advisor fable은 거부됩니다. Fable 5를 메인 모델로 쓰는 것은 영향 없습니다. 원격 롤아웃이 복귀 시점을 제어합니다.

Advisor 모델 선택

Advisor는 메인 모델 이상 능력이어야 합니다.

Main model	Accepted advisors	Notes
Haiku 4.5	Fable, Opus, Sonnet	Haiku는 advisor로 쓸 수 없음
Sonnet 4.6	Fable, Opus, Sonnet
Sonnet 5	Fable, Opus, Sonnet 5	Sonnet 4.6 advisor 거부
Opus 4.6	Fable, Opus, Sonnet 5	Sonnet 5와 Opus 4.6은 동등 랭크로 허용
Opus 4.7 이상	Fable, Opus 4.7 이상	이전 Opus/Sonnet 5 advisor 거부
Fable 5 (v2.1.170+)	Fable	Opus/Sonnet advisor 거부; 현재 Fable advisor 미제공으로 Fable 메인 세션은 advisor 없이 실행

별칭 opus/sonnet(및 롤아웃 후 fable) 또는 full model ID(claude-opus-5 등)를 사용합니다. Subagents는 구성된 advisor를 상속하고 자신의 모델 기준 pairing check를 적용합니다.

pairing이 맞지 않으면 메인 요청에 advisor가 붙지 않습니다. 알 수 없는 모델이면 역시 미부착입니다.

흔한 pairing

Pairing	용도
Sonnet main + Opus advisor	일상 작업 Sonnet, 계획·모호 실패·완료 점검은 Opus
Sonnet main + Fable advisor	결정 지점에만 Fable 5 (v2.1.170+, Fable access, 현재 advisor 옵션 복귀 후)
Haiku main + Opus advisor	최저 비용 메인 + 강한 계획
Opus main + Opus advisor	고위험 작업의 독립 2차 검토
Fable main + Fable advisor	최상위 pairing (Fable advisor 복귀 후)
Sonnet main + Sonnet advisor	저비용 2차 의견

언제 Claude가 advisor를 부르는가

호출 시점은 모델 주도입니다. 접근법 확정 전, 반복 오류, 완료 선언 전에 상담하는 경향이 있습니다. 프롬프트로 consult the advisor before you continue처럼 요청할 수 있습니다. 호출 횟수 cap/강제 설정은 없습니다.

세션에서 보이는 것

호출 중 transcript에 advisor 모델명의 Advising 줄이 표시되고, 완료 후 검토 확인이 나옵니다. Ctrl+O로 전체 지침을 펼칩니다.

Claude는 대체로 지침을 따르지만, 파일 내용·실행 결과가 모순되면 무조건 따르지 않고 충돌을 표면화합니다. Advisor는 항상 전체 대화를 받습니다.

비용

각 호출은 advisor 모델 요율로 토큰을 추가 소비합니다. API 과금은 advisor 입·출력 요율, 구독은 플랜 한도에 포함됩니다. 매 턴 호출이 아니므로 빠른 메인 + 강한 advisor가 전 구간 강 모델보다 보통 저렴합니다. /usage 세션 합계에 포함됩니다.

프롬프트 캐시 영향

세션 중 advisor on/off는 메인 모델 prompt cache를 무효화하지 않습니다. advisor 반환 지침은 이후 턴 transcript 캐시에 포함됩니다. Advisor 자체의 conversation 읽기는 호출마다 full transcript를 다시 처리하며 호출 간 재사용하지 않습니다.

요구사항

Anthropic API only (LLM gateway의 ANTHROPIC_BASE_URL 경유 시 gateway가 요청을 Anthropic API로 온전히 전달해야 함)
지원 메인 모델: Opus 4.6+, Sonnet 4.6+, Haiku 4.5; Fable 5는 v2.1.170+ (현재 Fable advisor 미제공으로 Fable 메인 세션은 advisor 없이 동작)

끄기

/advisor off

또는 피커에서 No advisor. 완전 비활성:

CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1

이 경우 /advisor 불가, advisorModel 무시, --advisor는 받아들여지나 효과 없음(기존 스크립트 호환).

접근	강한 모델이 도는 시점	시작 방식
Advisor tool	작업 중 결정 지점	Claude가 필요 시 호출
`opusplan`	plan mode (allowlist 허용 시), 이후 Sonnet 실행	plan mode 진입
Subagents + `model`	위임된 서브태스크 전체	Claude 위임 또는 명시 호출
`/model`	이후 모든 턴	사용자가 전환

체크리스트

Anthropic API 경로인지 확인했다 (Bedrock/Vertex/Foundry 아님)
메인 모델이 advisor를 지원한다
pairing이 메인 ≤ advisor 능력 규칙을 만족한다
/advisor, advisorModel, 또는 --advisor로 활성화했다
비용 증가를 /usage로 추적할 계획을 세웠다
필요 시 /advisor off 또는 env로 비활성화 방법을 안다

다음 단계

Advisor 도구로 어려운 결정 에스컬레이션

공식 기준: https://code.claude.com/docs/en/advisor

기준일: 2026-07-26 · CLI 기준 2.1.220

개요

핵심 개념

Advisor model: 메인 모델 이상 능력의 상담 모델
Server tool: 서버에서 전체 transcript를 읽어 지침 반환
활성화 경로: /advisor, advisorModel 설정, --advisor 플래그
비용: advisor 모델 요율로 추가 토큰 소비; 매 턴이 아니라 결정 지점 호출

상세

언제 쓰는가

짧은 작업이나 매 턴 최강 모델이 필요한 작업에는 가치가 적습니다. 그 경우 메인 모델을 바꾸거나 opusplan·subagents를 검토하세요.

활성화 방법

`/advisor` 명령

/advisor opus

인수 없이 실행하면 피커가 열립니다. 선택은 user settings의 advisorModel에 저장되어 세션 간 유지됩니다.

settings의 `advisorModel`

{
  "advisorModel": "opus"
}

`--advisor` 플래그

claude --advisor opus

해당 세션에서 설정 파일보다 우선합니다. claude --help에는 목록되지 않습니다. 메인 모델이 미지원이거나 allowlist 제외 시 오류로 종료합니다.

참고 (min-version 2.1.210): Claude Code는 Fable 5를 advisor로 제공하지 않습니다. Fable 5 접근이 있는 조직에서도 피커에 Fable 5 (temporarily unavailable)로 dimmed 표시되며 /advisor fable·--advisor fable은 거부됩니다. Fable 5를 메인 모델로 쓰는 것은 영향 없습니다. 원격 롤아웃이 복귀 시점을 제어합니다.

Advisor 모델 선택

Advisor는 메인 모델 이상 능력이어야 합니다.

Main model	Accepted advisors	Notes
Haiku 4.5	Fable, Opus, Sonnet	Haiku는 advisor로 쓸 수 없음
Sonnet 4.6	Fable, Opus, Sonnet
Sonnet 5	Fable, Opus, Sonnet 5	Sonnet 4.6 advisor 거부
Opus 4.6	Fable, Opus, Sonnet 5	Sonnet 5와 Opus 4.6은 동등 랭크로 허용
Opus 4.7 이상	Fable, Opus 4.7 이상	이전 Opus/Sonnet 5 advisor 거부
Fable 5 (v2.1.170+)	Fable	Opus/Sonnet advisor 거부; 현재 Fable advisor 미제공으로 Fable 메인 세션은 advisor 없이 실행

pairing이 맞지 않으면 메인 요청에 advisor가 붙지 않습니다. 알 수 없는 모델이면 역시 미부착입니다.

흔한 pairing

Pairing	용도
Sonnet main + Opus advisor	일상 작업 Sonnet, 계획·모호 실패·완료 점검은 Opus
Sonnet main + Fable advisor	결정 지점에만 Fable 5 (v2.1.170+, Fable access, 현재 advisor 옵션 복귀 후)
Haiku main + Opus advisor	최저 비용 메인 + 강한 계획
Opus main + Opus advisor	고위험 작업의 독립 2차 검토
Fable main + Fable advisor	최상위 pairing (Fable advisor 복귀 후)
Sonnet main + Sonnet advisor	저비용 2차 의견

언제 Claude가 advisor를 부르는가

세션에서 보이는 것

호출 중 transcript에 advisor 모델명의 Advising 줄이 표시되고, 완료 후 검토 확인이 나옵니다. Ctrl+O로 전체 지침을 펼칩니다.

Claude는 대체로 지침을 따르지만, 파일 내용·실행 결과가 모순되면 무조건 따르지 않고 충돌을 표면화합니다. Advisor는 항상 전체 대화를 받습니다.

비용

프롬프트 캐시 영향

요구사항

Anthropic API only (LLM gateway의 ANTHROPIC_BASE_URL 경유 시 gateway가 요청을 Anthropic API로 온전히 전달해야 함)
지원 메인 모델: Opus 4.6+, Sonnet 4.6+, Haiku 4.5; Fable 5는 v2.1.170+ (현재 Fable advisor 미제공으로 Fable 메인 세션은 advisor 없이 동작)

끄기

/advisor off

또는 피커에서 No advisor. 완전 비활성:

CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1

이 경우 /advisor 불가, advisorModel 무시, --advisor는 받아들여지나 효과 없음(기존 스크립트 호환).

접근	강한 모델이 도는 시점	시작 방식
Advisor tool	작업 중 결정 지점	Claude가 필요 시 호출
`opusplan`	plan mode (allowlist 허용 시), 이후 Sonnet 실행	plan mode 진입
Subagents + `model`	위임된 서브태스크 전체	Claude 위임 또는 명시 호출
`/model`	이후 모든 턴	사용자가 전환

체크리스트

Anthropic API 경로인지 확인했다 (Bedrock/Vertex/Foundry 아님)
메인 모델이 advisor를 지원한다
pairing이 메인 ≤ advisor 능력 규칙을 만족한다
/advisor, advisorModel, 또는 --advisor로 활성화했다
비용 증가를 /usage로 추적할 계획을 세웠다
필요 시 /advisor off 또는 env로 비활성화 방법을 안다

Advisor 도구로 어려운 결정 에스컬레이션

개요

핵심 개념

상세

언제 쓰는가

활성화 방법

/advisor 명령

settings의 advisorModel

--advisor 플래그

Advisor 모델 선택

흔한 pairing

언제 Claude가 advisor를 부르는가

세션에서 보이는 것

비용

프롬프트 캐시 영향

요구사항

끄기

관련 기능 비교

체크리스트

다음 단계

관련 가이드

Advisor 도구로 어려운 결정 에스컬레이션

개요

핵심 개념

상세

언제 쓰는가

활성화 방법

/advisor 명령

settings의 advisorModel

--advisor 플래그

Advisor 모델 선택

흔한 pairing

언제 Claude가 advisor를 부르는가

세션에서 보이는 것

비용

프롬프트 캐시 영향

요구사항

끄기

관련 기능 비교

체크리스트

다음 단계

관련 가이드

`/advisor` 명령

settings의 `advisorModel`

`--advisor` 플래그

`/advisor` 명령

settings의 `advisorModel`

`--advisor` 플래그