Claude Code 2.1.166 fallbackModel, deny rule, cross-session messaging 실무 점검
모델 과부하 대응, 모든 도구 차단, 세션 간 권한 전달 차단을 어디까지 믿어도 되는지 정리했습니다.
Claude Code 2.1.166에서 바로 확인할 세 가지
Claude Code 2.1.166은 primary model 장애 때 최대 세 개의 fallbackModel을 순서대로 시도하고, deny rule glob과 cross-session messaging 권한 처리를 강화한 릴리스입니다. 개발 세션이나 GitHub Actions에서 Claude Code를 쓰고 있다면 모델 대체, 도구 차단, 세션 간 권한 요청을 한 번에 점검해야 합니다.
2026년 6월 6일 Anthropic 공식 Claude Code changelog에는 2.1.166과 뒤이은 167, 168 패치가 같은 날 올라왔습니다. 설정을 손댈 만한 내용은 2.1.166에 몰려 있고, 뒤의 두 패치는 공식 표기상 bug fixes and reliability improvements입니다.
Claude Code 2.1.166 fallbackModel deny rule cross-session messaging 변경은 새 명령 암기보다 장애와 권한을 나눠 보는 쪽에 가깝습니다. 모델이 바쁠 때 넘길 후보, 도구 호출을 막을 범위, 다른 세션에서 건너온 메시지가 권한 요청으로 이어지는지를 각각 떼어 점검해야 합니다.
개인 사용자는 `claude --version`과 `claude doctor`로 시작하면 됩니다. 팀은 local settings에서 작은 실험을 끝낸 뒤 project settings나 managed settings로 올릴지 정하는 흐름이 낫습니다.
2026년 6월 6일 릴리스 흐름
기능 변화는 2.1.166에 집중되어 있고, 같은 날 이어진 167/168 항목은 안정성 패치로 확인됩니다. 설치 버전이 168번 패치까지 올라가 있어도 이 글에서 다루는 새 설정의 근거는 2.1.166 항목입니다.
공식 changelog와 GitHub CHANGELOG.md를 나란히 확인하면, 2.1.166에는 운영자가 따로 메모할 변경이 많습니다. 최대 세 개 fallbackModel 순차 시도, interactive session에도 적용되는 `--fallback-model`, deny rule의 tool-name 위치 glob, SendMessage로 전달된 메시지의 권한 전달 차단이 같은 항목에 들어 있습니다.
뒤이은 167/168 항목은 별도 설정을 소개하지 않고 reliability improvements로 정리되어 있습니다. 현재 설치 버전 번호가 168까지 올라가 있다면 2.1.166보다 뒤 릴리스라는 점만 확인할 수 있습니다. 다만 그 두 패치에 fallbackModel 기능이 새로 붙었다고 말할 근거는 없습니다.
이 날짜에 볼 부분은 새 모델 홍보가 아니라 장애와 권한 요청 처리입니다. Claude Code를 오래 켜 두거나 여러 세션을 나눠 쓰는 사람에게 이 구분이 더 중요합니다.
fallbackModel은 모델 장애 대응 장치입니다
fallbackModel은 primary model이 overloaded 또는 unavailable일 때 순차 대체 후보를 두는 설정입니다. 인증 오류, rate limit, request-size, transport errors를 자동으로 해결하는 우회 장치가 아닙니다.
작업 중 primary model이 overloaded 또는 unavailable 상태가 되면 Claude Code 2.1.166은 최대 세 개의 fallbackModel 후보를 순서대로 시도할 수 있습니다. 이번 changelog는 `--fallback-model`이 interactive session에도 적용된다고 적어, 터미널에서 계속 대화하며 코딩하는 사용자의 적용 범위가 넓어졌습니다.
실패 원인은 따로 봐야 합니다. 공식 changelog는 unexpected non-retryable error에서 fallback model로 해당 turn을 한 번 재시도한다고 설명합니다. auth, rate-limit, request-size, transport errors는 즉시 표면화됩니다. API 키가 틀렸거나 quota가 막힌 상황은 fallbackModel로 가려지지 않습니다.
운영 관점에서 fallbackModel은 비용 절감 장치보다 가용성 장치입니다. 긴 리팩터링 세션에서 primary model이 잠깐 unavailable인 경우에는 도움이 될 수 있습니다. 팀의 사용량 제한이나 인증 정책이 원인이라면 fallback 후보를 늘려도 근본 문제는 남습니다.
공식 CLI reference의 `--fallback-model` 설명이 아직 print mode와 background session 중심으로 남아 있다는 점도 확인해 둘 만합니다. 최신 근거는 2026년 6월 6일 changelog입니다. 구체 설정 예시는 로컬 CLI 경고와 공식 문서가 확인하는 범위 안에서만 다루는 것이 안전합니다.
deny rule glob에서 '*'를 쓰기 전
2.1.166부터 deny rule의 tool-name 위치에 glob pattern을 쓸 수 있고, '*'는 모든 도구를 deny하는 규칙으로 동작합니다. review-only나 plan-only 세션에는 맞지만, 일반 구현 세션에 넣으면 Claude Code의 파일 편집과 테스트 실행까지 막을 수 있습니다.
deny rule glob은 권한 정책을 넓게 잠그는 기능입니다. 특정 도구 하나를 막는 방식에서 더 나아가 tool-name 위치에 glob pattern을 두고 차단 범위를 잡습니다. 공식 changelog는 `*`를 모든 도구 deny 규칙으로 쓸 수 있다고 설명합니다.
한국 사용자 입장에서는 개인 설정보다 팀 설정에서 조심할 부분이 큽니다. 보안 검토 세션에서는 Bash, 파일 쓰기, 네트워크성 작업을 막고 읽기 중심으로만 돌리고 싶을 수 있습니다. 일반 구현 세션에 넓은 deny rule을 project settings로 공유하면 필요한 편집이나 테스트 실행도 멈춥니다.
권한 문서도 같이 봐야 합니다. Claude Code permissions 문서는 Bash permission rule에서 wildcard가 명령 어느 위치에도 올 수 있고, 복합 명령은 하위 명령마다 독립적으로 매칭해야 한다고 설명합니다. 2.1.166의 deny rule glob은 changelog에서 확인하고, 실제 rule 해석은 permissions 문서로 다시 확인하는 흐름이 좋습니다.
실제 적용 전에는 아래 순서가 실수를 줄입니다.
- `*` deny rule을 쓰는 세션이 review-only인지 구현 세션인지 구분합니다.
- `.claude/settings.local.json` 같은 로컬 범위에서 테스트합니다.
- shared project settings나 managed settings에 넣기 전 복구 경로와 예외 정책을 정합니다.
SendMessage로 넘어온 권한 요청
cross-session messaging 변경은 다른 Claude 세션에서 SendMessage로 전달된 메시지가 사용자 권한까지 함께 전달하지 않도록 한 조치입니다. receiver는 relayed permission request를 거부하고, auto mode는 이 흐름을 차단합니다.
여러 Claude 세션을 동시에 쓰면 한 세션의 메시지가 다른 세션으로 넘어갈 수 있습니다. 여기서 조심할 지점은 메시지 내용보다 권한입니다. 받는 세션이 relayed message를 사용자 권한이 실린 요청처럼 처리하면, 사용자가 의도하지 않은 승인 흐름이 생길 수 있습니다.
공식 changelog는 2.1.166에서 다른 Claude session에서 SendMessage로 relayed된 메시지가 user authority를 함께 전달하지 않도록 hardened cross-session messaging을 적용했다고 설명합니다. receiver가 relayed permission request를 거부하고 auto mode가 이를 차단한다는 내용도 같은 항목에 있습니다.
이 패치는 Claude Code 전체 보안 모델이 바뀌었다는 뜻이 아닙니다. 자동화 세션, 병렬 작업 세션, 백그라운드 세션을 같이 돌릴 때 권한 요청의 출처를 더 엄격히 보는 변경으로 이해하는 편이 정확합니다.
버전 확인부터 local settings까지
실무 도입은 공유 설정을 바로 바꾸기보다 `claude --version`, `claude doctor`, 테스트 저장소의 제한 세션, local settings 검증 순서로 진행하는 편이 안전합니다. 그 뒤 project settings, managed settings, GitHub Actions `claude_args` 적용 여부를 판단하면 됩니다.
처음에는 `claude --version`을 봅니다. 설치 버전이 2.1.166 이상인지 알아야 fallbackModel, deny rule glob, cross-session messaging 변경을 실제 환경에서 논할 수 있습니다. 설치 상태와 구성 문제는 `claude doctor`로 확인하는 편이 빠릅니다.
설치 경로도 문서화되어 있습니다. macOS, Linux, WSL에서는 `curl -fsSL https://claude.ai/install.sh | bash`를 쓸 수 있고, npm global package는 `@anthropic-ai/claude-code`입니다. 공식 quickstart와 setup 문서 기준으로 npm 패키지는 Node.js 18 이상이 필요하며, npm 수동 업그레이드는 `npm install -g @anthropic-ai/claude-code@latest`가 권장됩니다.
설정 범위는 더 신중해야 합니다. Claude Code settings는 user `~/.claude/settings.json`, project `.claude/settings.json`, local `.claude/settings.local.json`, managed settings로 나뉩니다. managed settings가 가장 높은 우선순위를 갖습니다. fallbackModel이나 강한 deny rule은 처음부터 project나 managed 범위에 넣지 말고 local에서 작은 테스트를 먼저 해보는 편이 좋습니다.
| 확인 항목 | 먼저 할 일 | 확인 이유 |
|---|---|---|
| 버전 | `claude --version` | 2.1.166 이상인지 확인 |
| 설치 상태 | `claude doctor` | 설치, 구성, auto-update 상태 점검 |
| fallbackModel | 테스트 저장소에서 제한 세션 실행 | 실제 overload를 억지로 만들지 않고 설정 인식부터 확인 |
| deny rule glob | `.claude/settings.local.json`에서 좁은 규칙 검증 | 모든 도구 차단이 작업을 막는지 확인 |
| CI 자동화 | GitHub Actions `claude_args`와 Secrets 점검 | unattended 실행에서 비용, 권한, turn 제한 관리 |
한국 팀이 먼저 문서화할 부분
국내 개인 개발자와 소규모 팀은 Claude Code 같은 AI 코딩 도구를 빨리 들여오지만, fallbackModel과 deny rule 같은 운영 설정은 나중에 정리하는 경우가 많습니다. 이번 릴리스는 어느 설정을 개인, 프로젝트, managed 범위에 둘지 다시 묻게 합니다.
Claude Code 2.1.166 fallbackModel deny rule cross-session messaging 업데이트는 국내 독자에게 개인 생산성보다 팀 규칙 문제로 남을 가능성이 큽니다. 모델 fallback은 세션 중단을 줄이는 데 도움이 될 수 있지만, fallback 후보 모델의 비용, 품질, 허용 정책은 팀마다 다릅니다.
deny rule glob은 더 직접적입니다. `*`로 모든 도구를 막을 수 있다는 사실은 plan-only, review-only, 보안 검토용 세션을 만들 때 유용합니다. 이 규칙을 공유 저장소에 잘못 넣으면 팀원이 Claude Code로 테스트 실행이나 파일 편집을 하지 못할 수 있습니다.
cross-session messaging 보안 강화는 자동화가 많아질수록 신경 써야 합니다. 백그라운드 세션, 병렬 작업, GitHub Actions처럼 사람이 매번 화면을 보고 있지 않은 흐름에서는 권한 요청이 어디서 왔는지 기록해야 합니다. 팀 문서에는 settings scope와 permission rule을 함께 남기는 것이 좋습니다.
지금 점검할 사람과 건너뛸 사람
Claude Code를 개인 터미널, 팀 저장소, GitHub Actions에서 실제로 쓰고 있다면 이번 릴리스를 확인할 가치가 있습니다. Claude Code를 쓰지 않거나 rate limit 해결책만 찾는 독자라면 우선순위가 낮습니다.
Opus나 Sonnet 기반 세션을 오래 돌리는 개인 개발자, 팀 저장소에 `.claude/settings.json`을 두는 팀, CI에서 Claude Code를 실행하는 조직은 fallbackModel과 권한 정책을 같이 봐야 합니다. 릴리스 노트를 읽고 끝낼 변경이 아니라 설정을 건드리기 전에 확인할 항목입니다.
Claude Code를 아직 쓰지 않는다면 설치 자체보다 사용 시나리오를 정하는 일이 먼저입니다. rate limit이나 인증 오류를 해결하려는 목적이라면 이 릴리스가 답이 되기 어렵습니다. 공식 changelog가 해당 오류를 fallback retry 대상에서 제외했기 때문입니다.
실제로 적용할 때는 2.1.166 이상인지 확인하고, 테스트 저장소에서 harmless prompt로 동작을 봅니다. 그다음 local settings에서 좁은 deny rule을 실험합니다. 팀에 공유할 설정은 이 과정을 거친 뒤 project나 managed 범위로 옮기는 편이 안전합니다.
자주 묻는 질문
Q. Claude Code 2.1.166에서 fallbackModel은 언제 동작하나?
A. 공식 changelog 기준으로 primary model이 overloaded 또는 unavailable 상태일 때 최대 세 개의 fallbackModel을 순서대로 시도합니다. 2.1.166부터 `--fallback-model`은 interactive session에도 적용됩니다.
Q. fallbackModel이 rate limit이나 인증 오류도 해결하나?
A. 아닙니다. 공식 changelog는 auth, rate-limit, request-size, transport errors가 fallback retry 대상이 아니라 즉시 표면화된다고 제한합니다. fallbackModel은 가용성 보완 장치이지 quota나 인증 문제를 우회하는 기능이 아닙니다.
Q. Claude Code deny rule에서 '*'를 쓰면 무엇이 막히나?
A. 2.1.166부터 deny rule의 tool-name 위치에 glob pattern을 쓸 수 있고, `*`는 모든 도구를 deny하는 규칙으로 동작합니다. review-only나 plan-only 세션에는 맞지만 일반 구현 세션에서는 파일 편집, 테스트 실행 같은 작업 흐름을 막습니다.
Q. cross-session messaging 보안 변경은 어떤 위험을 줄이나?
A. 다른 Claude 세션에서 SendMessage로 전달된 메시지가 사용자 권한까지 함께 전달되는 상황을 막습니다. 공식 changelog는 receiver가 relayed permission request를 거부하고 auto mode가 이를 차단한다고 설명합니다.
Q. 업데이트 후 가장 먼저 확인할 명령은 무엇인가?
A. 먼저 `claude --version`으로 2.1.166 이상인지 확인하고, 이어서 `claude doctor`로 설치와 구성 상태를 봅니다. 권한 규칙은 공유 설정에 넣기 전에 `.claude/settings.local.json` 같은 로컬 범위에서 좁게 테스트하는 편이 안전합니다.
Q. 167/168 패치도 새 기능 릴리스인가?
A. 공식 changelog에는 167/168 패치가 bug fixes and reliability improvements로 정리되어 있습니다. 이 글에서 다룬 fallbackModel, deny rule glob, cross-session messaging 보안 강화는 2.1.166 항목의 기능 변화입니다.
함께 읽으면 좋은 글
참조 링크
- Claude Code changelog — 2.1.166, 2.1.167, 2.1.168의 날짜와 변경 항목을 확인한 공식 원문 업데이트
- anthropics/claude-code CHANGELOG.md — 공식 changelog 페이지가 생성 원본으로 지목하는 변경 이력 감사 자료
- Claude Code settings — user, project, local, managed settings 범위와 우선순위 확인
- Configure permissions — permission rule, wildcard, deny rule 운영 해석에 필요한 공식 문서
- Environment variables — FALLBACK_FOR_ALL_PRIMARY_MODELS와 thinking 관련 환경 변수 확인
- Quickstart — 설치 명령과 npm 패키지, Node.js 요구 사항 확인
- Advanced setup — npm 수동 업그레이드와 설치 방식별 업데이트 관리 확인
- Claude Code GitHub Actions — CI 자동화에서 claude_args와 Secrets를 함께 점검하기 위한 참고 문서