Claude Code Advisor: Sonnet + Opus 설정과 호출 확인

Claude Code advisor를 사용하면 일상적인 코딩은 Sonnet이 맡고 어려운 판단은 Opus가 검토하도록 구성할 수 있습니다. claude --model sonnet --advisor opus로 시작한 뒤, 검토에 의존하기 전에 Advising 항목과 실제 호출 결과를 확인합니다. 호출 시점은 모델이 정하며 추가 토큰이 들고, 게이트웨이가 도구를 거부하면 자문 호출이 사라질 수 있습니다.

2026-11-06 기준으로 advisor 기능은 실험적 기능입니다. 아래 예제는 CLI가 설치되어 있고 인증이 정상 작동하며, Anthropic에 일반 요청을 직접 보낼 수 있는 환경을 전제로 합니다. 구독 계정과 API 사용량에 따라 요금을 내는 계정 모두 이 연결 방식을 사용할 수 있습니다. 게이트웨이의 지원 여부는 별도로 확인해야 합니다.

advisor와 다른 모델 전환 방식 비교

리팩터링, 반복되는 버그 수정, 간혹 어려운 판단이 필요한 구현 작업에는 advisor를 선택합니다. Sonnet이 작업을 맡고, 두 번째 모델은 도구 호출과 결과를 포함한 대화 기록을 검토합니다.

이는 Anthropic이 advisor 전략에서 설명한 역할 분담입니다. 모든 작업에서 Opus 수준의 결과를 얻거나 일정한 비용을 절감한다고 보장하지는 않습니다.

필요한 작업	선택할 방식	달라지는 동작
실행 도중 간헐적으로 조언 받기	Advisor	Claude가 다른 모델에 자문할 시점을 정합니다
Opus로 계획한 뒤 Sonnet으로 구현하기	opusplan	모델 접근 권한이 있으면 계획 모드에서 Opus를 사용하고, 실행에는 Sonnet을 사용합니다
별도의 조사나 검토 작업 맡기기	model을 지정한 서브에이전트	선택한 모델이 위임받은 작업을 수행합니다
이후 주 세션 요청에서 더 강한 추론 사용하기	/model	주 모델을 변경합니다

계획이 거의 필요 없는 짧은 작업은 advisor 없이 시작합니다. 거의 모든 단계에 Opus가 필요하다면 주 세션을 Opus 5.5로 전환합니다.

시작 명령만으로 검색, grep, 문서 조사를 맡는 Haiku 서브에이전트 세 개가 만들어지지는 않습니다. 이런 구성이 필요하면 서브에이전트 모델 설정 방법에 따라 별도로 설정합니다. 문서에 나오는 CLI 옵션은 JSON과 함께 사용하는 --agents입니다. 온라인에서 공유되는 --subagents haiku 명령으로 대체하지 않습니다.

세 가지 방법으로 advisor 켜기

처음 시험할 때는 시작 플래그를 사용합니다. 저장된 자문 모델 선택을 바꾸지 않고 한 세션에서만 시도할 수 있습니다. 먼저 Bash에서 클라이언트 버전을 확인합니다.

claude --version

Sonnet 5.5와 Opus 5.5를 사용하는 이 예제에는 2.1.284 이상이 필요합니다. 이 최소 버전은 모델 요구 사항에 따른 값이며, advisor 기능이 처음 출시된 버전이라는 뜻은 아닙니다. 문서에 안내된 CLI 업데이트 명령은 claude update입니다.

한 세션에서만 사용: —advisor

프로젝트 디렉터리에서 Bash로 다음 명령을 실행합니다.

claude --model sonnet --advisor opus

2026-11-06 기준으로 Anthropic에 직접 연결하는 현재 구성에서 이 별칭들은 Sonnet 5.5와 Opus 5.5를 가리킵니다. 별칭이 가리키는 모델은 바뀔 수 있으며 설정에서 재정의할 수도 있습니다. 버전을 명확히 지정하려면 전체 모델 ID를 사용합니다.

claude --model claude-sonnet-5-5 --advisor claude-opus-5-5

이 세션에서는 플래그가 advisorModel 설정보다 우선합니다. advisor 문서에도 --advisor가 claude --help에 표시되지 않는다고 명시되어 있습니다.

실행 중인 세션에서 변경: /advisor

Claude Code 안에서 다음을 입력합니다.

/advisor opus

Advisor set to 다음에 모델 이름이 표시됩니다. 인자 없이 /advisor만 실행하면 모델 선택 목록이 열립니다.

로컬 터미널 세션에서는 보통 이 선택이 기본값으로 저장됩니다. 원격 세션에서 선택을 유지하는 규칙은 설정 참조 문서에 별도로 나와 있습니다.

이후 세션의 기본값 지정: advisorModel

사용자 설정 파일 ~/.claude/settings.json에 다음 속성을 추가합니다.

{
  "advisorModel": "opus"
}

파일에 있는 다른 설정은 그대로 유지합니다. 이 속성은 자문 모델만 선택하며, Sonnet을 주 모델로 지정하지는 않습니다.

기능을 켠 뒤 다음 알림을 확인합니다.

Advisor Tool (experimental) is on and may use more tokens · /advisor

이 알림은 기능이 활성화되었음을 보여 줍니다. 실제 자문 호출이 있었다는 증거는 아닙니다.

지원되는 모델 조합

Claude Code가 정한 순위를 기준으로 주 모델과 같거나 더 높은 자문 모델을 선택합니다. 아래 조합은 2026-11-06에 확인한 현재 모델 조합 표에서 일부를 골랐습니다.

주 모델	자문 모델	적합한 용도
Sonnet 5.5	Opus 5.5	일상적인 구현 작업에 더 강한 모델의 검토 추가
Haiku 5.5	Opus 5.5	가벼운 주 모델과 더 깊이 있는 자문 결합
Sonnet 5.5	Sonnet 5.5	같은 모델로 한 번 더 검토
Opus 5.5	Opus 5.5	별도의 Opus가 추가 검토
Opus 4.7 또는 Opus 4.8	Sonnet 5.5	문서에서 허용하는 서로 다른 계열의 조합

Haiku 5.5를 주 모델이나 자문 모델로 쓰려면 2.1.293 이상이 필요합니다. Sonnet 5.5가 Opus 4.7 또는 Opus 4.8의 자문 모델이 되려면 2.1.287 이상이 필요합니다. Haiku 4.5는 자문을 요청할 수 있지만 자문 모델이 될 수는 없습니다.

이는 허용되는 조합이며, 해당 저장소에서의 품질 순위를 보장하는 목록이 아닙니다. 조직의 허용 모델 목록인 availableModels가 선택을 차단할 수도 있습니다. 자문 역할을 맡을 수 없거나 허용되지 않은 모델을 --advisor로 지정하면 대화형 실행이 시작 단계에서 오류로 중단될 수 있습니다. 자문 모델의 순위가 주 모델보다 낮거나 모델 ID를 인식하지 못하면 주 세션은 advisor 없이 계속될 수 있습니다.

서브에이전트는 advisor 설정을 상속하고 자신의 모델을 기준으로 조합을 확인합니다. 전체 사용량을 평가할 때는 서브에이전트가 요청할 수 있는 자문도 포함합니다.

자문 모델의 실제 호출 확인

먼저 도구 호출 기록을 증거로 확인한 뒤 사용량을 살펴봅니다. 시작 알림이나 Claude가 Opus에 자문했다고 설명하는 것만으로는 충분하지 않습니다.

잘 아는 저장소에서 다음 읽기 전용 프롬프트를 시도합니다. 파일을 바꾸지 않고 인증 흐름을 살펴본 뒤, 작은 리팩터링과 회귀 위험, 필요한 테스트를 제안하도록 요청합니다.

Inspect this repository's authentication flow without changing files.
Propose one small refactor and identify its main regression risk.
Consult the advisor before presenting the plan.
Include the tests that would check the proposed change.

이 프롬프트는 확인을 위한 예시이며 호출을 보장하지 않습니다. 호출 시점은 Claude가 정합니다. 계획 수립, 반복되는 오류, 완료 전 확인은 자문이 자주 일어나는 상황이며, 정해진 세 가지 실행 조건은 아닙니다.

Claude Code advisor에는 호출을 강제하거나 횟수 상한을 정하는 설정이 없습니다. 프롬프트나 CLAUDE.md에서 더 자주 자문하도록 요청할 수는 있지만, 검토를 반드시 거치도록 강제하지는 못합니다.

자문 모델 이름과 함께 표시되는 Advising 항목을 찾습니다. 결과는 다음과 같이 해석합니다.

결과	확인할 수 있는 사실	다음 조치
Reviewed	자문 모델이 대화 기록을 검토했습니다	읽을 수 있는 조언이 반환되었다면 Ctrl+O를 누르고 결과 계획을 살펴봅니다
Declined	호출은 이루어졌지만 자문 모델이 조언 제공을 거절했습니다	이유가 있다면 읽고 요청을 다시 검토합니다
Unavailable	호출이 실패했습니다	Advisor unavailable (<error_code>)를 확인하고 해당 실패를 진단합니다
Advising 항목 없음	확인된 자문 호출이 없습니다	호출을 명시적으로 요청한 뒤에도 기록이 없으면 활성화 상태와 요청 경로를 확인합니다

확인용 요청을 보낸 뒤 /usage를 실행합니다. 자문 모델 사용량은 세션 합계에 포함되지만, 합계가 늘었다는 사실만으로 검토 성공을 알 수는 없습니다. 호출 기록에 나온 결과와 함께 확인합니다.

자문 호출 비용과 캐시

다른 모델이 대화를 한 번 더 읽는 비용을 예산에 포함합니다. 자문 모델의 토큰은 주 모델 사용량에 추가됩니다.

API로 결제하면 자문 모델의 입력·출력 토큰에 해당 모델의 요금이 적용됩니다. 구독으로 Sonnet/Opus 구성을 사용하면 자문 활동도 요금제 사용 한도에 포함됩니다. 별도의 무제한 검토 이용량이 제공되는 것은 아닙니다.

2026-11-06 기준 Anthropic의 Opus 5.5 표준 요금은 입력 토큰 백만 개당 $4, 출력 토큰 백만 개당 $20입니다.

다음은 자문 모델만 계산한 가정에 따른 추정치입니다. Anthropic API 직접 과금, 표준 글로벌 요금, 캐시되지 않은 입력 토큰 50,000개와 청구 대상 출력 토큰 2,000개를 가정합니다. 청구되는 출력에는 추론에 사용한 토큰도 포함됩니다.

Advisor token cost
= (50,000 × $4 + 2,000 × $20) / 1,000,000
= $0.24

이 금액은 호출당 고정 요금이 아닙니다. 주 모델의 작업 비용은 제외했으며, 구독 사용 한도를 얼마나 소비하는지도 계산하지 않았습니다. 대화 기록이나 자문 모델의 출력이 길어지면 추정 비용도 늘어납니다.

Claude Code의 advisor 문서에 따르면 자문 호출마다 전체 대화 기록을 다시 읽으며, 자문 모델의 캐시를 재사용하지 않습니다. /advisor를 켜거나 꺼도 주 모델의 프롬프트 캐시는 유지됩니다. 이후 요청에서는 반환된 조언도 이 캐시에 포함될 수 있습니다.

이 설명은 Claude Code에 한정됩니다. 직접 사용하는 Messages API에는 이제 자문 모델용 caching 옵션이 별도로 문서화되어 있습니다. 이 옵션은 여기서 설명하는 CLI 설정 절차에 포함되지 않습니다.

조합을 도입하기 전에 같은 작업을 완료하는 데 든 전체 비용을 비교합니다. 동일한 완료 기준으로 검사하고 재시도와 실패한 시도도 계산에 넣습니다. 대화 맥락이 큰 세션에서는 모든 증가분을 advisor 때문이라고 판단하기 전에 MCP가 추가하는 컨텍스트를 측정합니다.

/usage에 표시되는 달러 금액은 추정치입니다. 실제 청구 내역은 제공업체의 과금 기록에서 확인합니다.

게이트웨이 400 오류와 알림 없는 폴백 해결

발생한 문제에 맞는 해결책을 선택합니다. 기능이 활성화되지 않은 경우, 모델 조합이 거부된 경우, 서버 도구를 지원하지 않는 경우는 복구 방법이 다릅니다.

시작 알림이나 자문 호출이 없는 경우

모델을 바꾸기 전에 환경 변수와 설정의 env 항목을 확인합니다. CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1은 기능을 완전히 비활성화합니다.

DISABLE_TELEMETRY와 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC도 확인합니다. 이 변수들은 기능 활성화 여부를 제어하는 기능 플래그 처리를 비활성화할 수 있으며, advisor는 이 처리에 의존합니다. 각 변수의 동작 설명을 읽고 첫 세션과 게이트웨이 인증 정보에 관한 조건도 확인합니다.

조직이 의도적으로 지정한 설정이라면 승인된 구성을 사용하거나 다른 검토 방식을 선택합니다. 선택적으로 추가한 로컬 설정이 원인이라면 해당 설정을 정의한 위치에서 삭제하고 다시 실행합니다. 확인용 프롬프트를 반복하고 호출 기록을 살펴봅니다. 환경 변수만 바꿨다는 사실이 성공을 증명하지는 않습니다.

세션은 작동하지만 모델 조합이 거부된 경우

두 모델의 실제 ID와 availableModels를 확인합니다. 저장된 자문 모델이 있어도 주 모델과 호환되지 않으면 비활성 상태로 남을 수 있습니다.

API가 요청에 포함된 조합을 거부하면 Claude Code는 advisor를 빼고 다시 요청합니다. 이때 대화는 오류 없이 계속될 수 있습니다. 허용되는 자문 모델을 선택한 뒤 /clear, /compact 또는 새 세션을 사용하고 다시 확인합니다.

대화를 지우기 전에 필요한 작업 맥락을 보관합니다. 이 복구 방법은 모델 조합 거부에 해당하며, 모든 게이트웨이 거부에 적용되지는 않습니다.

Input tag ‘advisor_20260301’ 오류가 표시되는 경우

Input tag 'advisor_20260301'을 언급하는 400 또는 422는 게이트웨이나 그 뒤의 API가 advisor 도구 유형을 거부했다는 뜻입니다.

2.1.280부터 Claude Code는 이 거부를 인식하고 advisor 항목과 해당 beta 값을 뺀 요청을 한 번 재전송합니다. 코드 작성 세션은 복구되더라도 advisor는 빠진 상태일 수 있습니다.

게이트웨이 호환성 안내에 따르면 같은 기본 URL로 보내는 요청에서는 Claude Code 프로세스를 종료할 때까지 advisor가 제외됩니다. 이 상태에서는 /advisor 명령도 사용할 수 없습니다. 요청 경로를 수정한 뒤 Claude Code를 완전히 종료하고 다시 실행합니다. 문서에 따르면 이 상태는 /clear만으로 초기화되지 않습니다.

클라이언트가 오래되었다면 먼저 업데이트합니다. 최신 클라이언트에서도 오류가 보이면 게이트웨이 운영자에게 도구 정의를 확인하도록 요청합니다.

• tools의 advisor_20260301 유형 항목이 이 도구를 지원하는 Anthropic API에 도달해야 합니다.
• 연결된 anthropic-beta 값인 advisor-tool-2026-03-01도 함께 전달되어야 합니다.
• 대상 API의 오류 응답 본문에는 Claude Code가 거부를 인식하는 데 쓰는 문구가 그대로 유지되어야 합니다.

도구와 해당 헤더를 제거했을 때 일반 요청이 작동한다면, advisor 없이 요청을 계속하는 폴백이 확인된 것입니다. 이 결과가 advisor 지원을 입증하지는 않습니다.

2026-11-06 기준 BetterToken의 모델 목록에는 claude-sonnet-5-5와 claude-opus-5-5가 있습니다. Claude Code 설정 안내에서는 ANTHROPIC_BASE_URL에 https://bettertoken.ai를 사용하며 /v1을 붙이지 않습니다. 모델이 제공된다는 사실만으로 advisor 지원이 확인되지는 않습니다. 사용할 경로의 지원 여부를 확인받고 실제 자문 호출을 검증합니다.

일반 Messages 요청도 실패한다면 최소 Claude API 요청 안내로 연결부터 따로 확인합니다. 그런 다음 advisor 확인용 요청을 반복합니다.

advisor 끄기

자문 호출을 중단하려면 세션에서 다음 명령을 사용합니다.

/advisor off

완전히 비활성화하려면 실행 전에 Bash에서 다음 변수를 설정합니다.

export CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1
claude

이 변수가 설정되면 /advisor를 사용할 수 없고 advisorModel도 무시됩니다. Claude Code는 --advisor를 받아들이지만 이 플래그는 아무 효과가 없습니다.