Fable 에이전트를 Haiku로 몰래 라우팅하는 env var

모든 서브에이전트의 YAML에 model: fable을 고정해 뒀는데도 전체 에이전트가 계속 Haiku처럼 답한다면, 원인은 거의 항상 엄격한 해석 순서에서 그 고정보다 위에 있는 오래된 환경 변수 하나입니다. 더 문제는 조용히 실패한다는 점입니다.

우선순위 사다리: CLAUDE_CODE_SUBAGENT_MODEL이 Fable 고정을 덮어쓰는 이유

Claude Code에서 서브에이전트의 모델은 엄격한 단방향 우선순위 체인으로 결정됩니다. 순서는 (1) CLAUDE_CODE_SUBAGENT_MODEL 환경 변수, (2) 호출별 파라미터, (3) YAML frontmatter의 model 필드, (4) 세션 모델입니다 . 환경 변수는 예외 없이 항상 이깁니다. 즉 셸이나 CI 환경에 예전 테스트에서 남은 export CLAUDE_CODE_SUBAGENT_MODEL=haiku가 있으면, frontmatter에 선언한 model: fable과 관계없이 모든 서브에이전트가 조용히 Haiku 4.5로 내려갑니다 .

예를 들어 에이전트 파일에는 model: fable이 선언되어 있지만, 환경에는 이전 테스트 실행에서 남은 CLAUDE_CODE_SUBAGENT_MODEL=haiku가 아직 들어 있다고 해 봅시다. 해석은 1순위에서 멈춥니다. 에이전트는 Haiku 4.5에서 실행되고, 아무 경고도 뜨지 않습니다.

두 번째 조용한 함정은 사용 가능 여부입니다. 고정한 모델을 실제로 제공할 수 없는 경우, 예를 들어 Fable 5가 현재 플랜에서 막혀 있거나, ZDR 충돌로 차단되었거나, Claude Code가 /model 선택기에 Fable이 처음 등장한 v2.1.170보다 오래된 버전이면, Claude Code는 오류나 로그 없이 세션 모델로 fallback합니다 . 따라서 Fable 고정이 흔적 없이 사라지는 길은 두 가지입니다. 그 위에 있는 환경 변수, 또는 사용할 수 없는 모델입니다. 바깥에서 보면 둘 다 똑같습니다. 요청한 것보다 작은 모델처럼 행동하는 에이전트만 보입니다.

Fable 에이전트 플릿을 실행하기 전에 확인할 것

어디든 model: fable을 고정하기 전에 네 가지를 확인하세요. 앞의 조용한 fallback은 전제 조건이 빠졌을 때만 발목을 잡습니다. Fable 5는 유료 Anthropic 플랜(Pro, Max, Team, Enterprise)이 필요하며 Free에서는 사용할 수 없습니다 . API에서는 모델 ID가 claude-fable-5이며, 직접 호출하거나 Amazon Bedrock, Google Cloud, Microsoft Foundry를 통해 사용할 수 있습니다 .

구축 전에 다음을 확인하세요.

• 클라이언트 빌드: Fable 5가 /model 선택기에 나타나려면 Claude Code v2.1.170 이상이 필요합니다. 그보다 이전 빌드에서는 조건을 충족하는 플랜이어도 표시되지 않습니다 .
• 데이터 보존: Fable 5는 30일 데이터 보존이 필요하며, 이는 Zero Data Retention(ZDR)과 양립할 수 없습니다. 조직에서 ZDR을 강제한다면 Fable은 사용할 수 없습니다. 고정하기 전에 확인하세요 .
• 동시 실행: 병렬 에이전트 세션마다 유효한 Claude Code 접근 권한이 필요합니다. 공유 좌석을 나눠 쓰는 multiplexing은 없습니다. 에이전트 10개를 동시에 돌리면 플랜에서 동시 사용 슬롯 10개를 사용합니다 .

과금은 로그인 방식에 따라 달라집니다. 구독 및 Enterprise 좌석은 플랜 사용량 창에서 차감되고, API 키 로그인은 토큰당 종량제로 계산됩니다 . 이 중 하나라도 놓치면 고정한 Fable 모델은 아무것도 가리키지 않게 됩니다. 바로 위에서 설명한 증발 현상입니다.

YAML에서 서브에이전트 모델을 선언하는 방법

서브에이전트의 모델은 정의 파일의 YAML frontmatter 안 model: 필드에 설정합니다. Claude Code는 이 위치에서 여섯 가지 값을 받습니다. sonnet, opus, haiku, fable, claude-fable-5 같은 전체 모델 ID, 또는 세션 모델을 재사용하는 기본값인 inherit입니다 . 각 에이전트는 자체 파일을 가지므로, 전역으로 고정하기보다 역할별로 모델을 고정하세요.

어떤 고정값이든 믿기 전에 환경을 점검하세요. 플릿을 실행하는 셸에서 echo $CLAUDE_CODE_SUBAGENT_MODEL을 실행하고, CI에서는 명시적인 job step으로 출력하세요. 오래된 값이 나온다면 unset하거나 비워 두세요. 이 환경 변수는 해석 순서의 최상단에 있으며, 작성해 둔 모든 model: fable 줄을 조용히 덮어씁니다 .

오케스트레이터와 병렬 에이전트를 함께 쓰는 구성이라면 frontmatter는 단순합니다.

# orchestrator.md
---
name: orchestrator
model: fable
---

# developer.md
---
name: developer
model: sonnet
---

# chore.md
---
name: chore-runner
model: haiku
---

충돌하는 환경 변수가 없으면 commander는 계획 수립과 최종 점검에 Fable 5를 사용하고, 각 병렬 developer는 Sonnet 5에서 실행되며, chore 에이전트는 Haiku 4.5에서 실행됩니다 . Anthropic의 model-config 문서 표현대로, 해석은 "the env var, then the per-invocation parameter, then frontmatter, then the session model" 순서의 엄격한 우선순위를 따릅니다. 따라서 YAML은 그보다 높은 항목이 가로채지 않을 때만 효력을 가집니다 (source: Claude Code model config, 2026-06).

마지막으로, 2026년 5월 v2.1.139에 추가된 Claude Code의 agent view에서 실제 모델을 확인하세요 . 파일에 적힌 문자열만 보지 말고, 각 에이전트의 첫 번째 tool call에 표시되는 모델을 읽으세요. 실제로 비용을 지불하게 되는 모델은 YAML이 선언한 값이 아니라 런타임이 보여 주는 값입니다.

발목 잡는 함정: Fable 모델 라우팅이 어긋날 때

네 가지 실패 모드는 조용한 모델 교체를 잘못된 청구와 거짓 "성공" 신호로 바꿉니다. 각각은 순진한 플릿이 신뢰하는 검사 — 깨끗한 YAML 파일, HTTP 200, 반환된 응답 — 를 통과하지만, 실제로 적용된 모델, 비용, 완료 상태는 생각과 다릅니다. 공통점은 하나입니다. 실제로 무엇이 실행됐는지는 설정이 아니라 런타임이 결정합니다.

• CI 파이프라인 드리프트. 이전 작업 단계에서 내보낸 CLAUDE_CODE_SUBAGENT_MODEL=haiku가 해당 작업의 모든 이후 에이전트 호출에 그대로 남습니다. env는 우선순위 사다리의 맨 위에 있으므로 , 각 서브에이전트는 조용히 Haiku 4.5를 Haiku 비용으로 실행합니다. 그러면 비용 모니터링은 정상처럼 보입니다. 지출이 줄어들기 때문입니다. 그래서 Fable 오케스트레이터가 파이프라인 중간에 강등됐다는 사실을 경고하지 못합니다.
• 분류기에 의한 재라우팅. Anthropic의 사이버보안 또는 생물학 분류기에 걸린 요청은 API 계층에서 Opus 4.8로 자동 라우팅되며, Fable 가격으로 청구되지 않습니다 . 에이전트는 여전히 HTTP 200을 받기 때문에 상태 코드만으로는 실제 적용 모델을 확인할 수 없습니다. Fable 5라고 믿은 실행이 Opus에서 처리됐을 수 있습니다.
• 거절도 200으로 도착합니다. Fable은 4xx가 아니라 HTTP 200 응답 안에 stop_reason: "refusal"을 담아 반환할 수 있습니다 . 검증 루프의 종료 조건에 명시적인 stop_reason 검사를 연결하세요. HTTP 상태만 보는 루프는 거절을 완료된 작업으로 취급하고 아무것도 병합하지 않습니다.
• 지역. Fable 5에는 미국 한정 1.1배 추론 배수가 붙습니다 . 지역 라우팅이 섞인 병렬 에이전트는 YAML만으로는 디버그할 수 없는 지연 시간과 비용 차이를 만들어냅니다.

"In multi-agent setups the orchestrator, not the workers, is the failure point — fan out ten agents and the slices are usually fine, but the results fail to fit together" — Fable 5 플릿을 위한 모델 라우팅 가이드 (source: mcp.directory, 2026).

네 경우 모두 방어 방식은 같습니다. 설정이나 HTTP 계층이 아니라 응답에서 실제 적용 모델과 stop_reason을 확인하고, 플래그가 붙었거나 실패한 실행은 의도적으로 Opus 4.8 fallback으로 라우팅해야 합니다 .

권장 Fable 플릿 구성: 오케스트레이터, 병렬 에이전트, Haiku 잡무

긴 실행을 버티는 구성은 Fable 5를 모든 곳에 쓰는 방식이 아니라 역할별로 모델을 층화하는 방식입니다. Fable 5는 100만 토큰 컨텍스트 창으로 전체 저장소, 스펙, 작업 장부, 모든 병렬 에이전트의 출력을 한 번에 담을 수 있기 때문에 지휘 계층에 둡니다 . 이것이 중요한 이유는 멀티 에이전트 실행이 개별 작업이 아니라 오케스트레이터에서 무너지기 때문입니다. 작업자들의 조각은 멀쩡한데, 관리자가 컨텍스트를 다 쓰거나 계획을 잃어버립니다 .

• 지휘관 — Fable 5: 계획, 위임, 최종 점검을 맡습니다. Anthropic이 내부 평가에서 Opus 4.8 대비 장기 작업 성과가 세 배 높았다고 보고한 파일 기반 메모리가 중심을 잡습니다 .
• 병렬 개발자 — Sonnet 5: 팬아웃, 파이프라인, 검증 루프 위임 패턴 전반에서 리서치, 구현, 검증을 처리합니다 .
• 잡무 — Haiku 4.5: 위험이 낮은 포매팅, 요약, 알림을 가장 낮은 비용으로 처리해, 결정적인 하위 작업에 Fable 쿼터가 쓰이지 않게 합니다 .

이 구성을 묶는 배선 규칙은 하나입니다. 사이버보안 또는 생물학 분류기 재라우팅에 걸릴 수 있는 에이전트에는 의도적인 Opus 4.8 fallback을 추가하고, Fable이 실제 적용 모델이라고 절대 가정하지 마세요 . Fable은 HTTP 200 안에 stop_reason: "refusal"을 담아 반환할 수 있으므로, 검증 루프 종료 조건은 전송 계층에서 추론하지 말고 응답 본문을 기준으로 검사 가능해야 합니다 . 가장 큰 컨텍스트는 위에 두고, 가장 저렴한 모델은 아래에 두며, 모든 실제 적용 모델을 확인하세요. 그래야 플릿이 무너지지 않습니다.

자주 묻는 질문

CLAUDE_CODE_SUBAGENT_MODEL은 무엇이고 어디에서 설정하나요?

CLAUDE_CODE_SUBAGENT_MODEL은 모든 Claude Code 서브에이전트의 모델을 덮어쓰는 환경 변수이며, 해석 우선순위의 가장 위에 있습니다. 호출별 파라미터, YAML frontmatter의 model 필드, 세션 모델보다 먼저 적용됩니다 . 셸 프로필, .env 파일, CI 환경 변수처럼 환경이 로드되는 곳에 설정하면 됩니다. 이 값은 고정된 model: fable보다 우선하므로, 남아 있는 CLAUDE_CODE_SUBAGENT_MODEL=haiku 하나만으로도 에이전트가 조용히 Haiku로 라우팅됩니다. YAML 선언이 적용되게 하려면 이 변수를 해제하세요.

Fable 5는 Zero Data Retention 조직에서 사용할 수 있나요?

아니요. Fable 5는 30일 데이터 보관이 필요하며, 이는 Zero Data Retention(ZDR)과 함께 사용할 수 없습니다 . ZDR로 설정된 Enterprise 조직은 Fable 5를 사용할 수 없습니다. 사용하려면 해당 워크스페이스에서 ZDR을 비활성화하거나, 보관 정책에 맞는 모델로 해당 에이전트를 라우팅해야 합니다. 또한 Fable 5가 /model 선택기에 표시되려면 Claude Code v2.1.170 이상이 필요합니다 .

두 Claude Code 에이전트가 하나의 좌석이나 구독을 공유할 수 있나요?

아니요. 병렬로 실행되는 각 에이전트 세션에는 각각 유효한 Claude Code 액세스가 필요하며, 동시 실행 에이전트는 Anthropic 계정의 동시 사용 슬롯을 소비합니다 . 플릿 방식 오케스트레이션이 모델 액세스를 묶어 주거나 Anthropic 제한을 우회해 주지는 않습니다. 병렬 에이전트는 곧 병렬 비용을 뜻합니다 . 워커 열 개로 확장하기 전에 플랜의 동시성 제한을 확인하세요. 구독 좌석은 플랜 사용량 윈도우에서 차감되고, API 키 로그인은 토큰당 종량제로 청구된다는 점도 유의하세요 .

model: fable로 고정했는데 내 계정에서 Fable 5를 사용할 수 없으면 어떻게 되나요?

Claude Code는 조용히 세션 모델로 폴백합니다. 오류도 없고 로그 경고도 없습니다 . Fable 5는 어떤 계정에서도 기본값이 아니며 위의 보관 조건과 버전 조건을 충족해야 하므로, 사용할 수 없는 고정값은 아무 알림 없이 우선순위 사다리 아래로 내려갑니다. YAML 선언만 믿지 말고 에이전트 보기나 첫 번째 tool-call 응답 본문에서 실제 적용 모델을 확인하세요.

왜 Fable 에이전트 호출에 Fable 가격이 아니라 Opus 4.8 가격이 적용됐나요?

Anthropic의 사이버보안 또는 생물학 분류기에 걸린 요청은 API 계층에서 Opus 4.8로 자동 라우팅되며, 이렇게 재라우팅된 호출에는 Fable 가격(입력 토큰 100만 개당 \$10, 출력 토큰 100만 개당 \$50)이 적용되지 않습니다 . Fable은 고정 모델이 아니라 제품 표면이므로, 같은 엔드포인트라도 요청마다 다른 모델을 제공할 수 있습니다. 실제로 어떤 모델이 실행됐는지는 응답 본문의 model 필드로 확인하세요. 또한 Fable은 HTTP 200 안에서도 stop_reason: "refusal"을 반환할 수 있으므로, 전송 상태만으로 결과를 판단해서는 안 됩니다 .

이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.

구독하기