Claude Code availableModels: 팀 모델 선택을 allowlist로 통제하는 법 | DAKER 커뮤니티
Claude Code availableModels: 팀 모델 선택을 allowlist로 통제하는 법
Claude Code availableModels란, 사용자가 선택할 수 있는 모델 이름을 설정으로 제한하는 allowlist입니다. 2026년 6월 25일 기준 공식 문서는 model만으로는 Default 선택을 막을 수 없고, enforceAvailableModels와 alias pinning을 함께 봐야 한다고 설명합니다.
_클로드 코드 availableModels와 enforceAvailableModels로 모델 선택 범위를 제한하는 팀 운영 카드._
Claude Code 모델 allowlist는 왜 필요한가요?
한 줄 요약: 팀원이 어떤 모델을 쓸 수 있는지 비용, 정책, 검증 기준에 맞춰 고정하려면 availableModels를 설정해야 합니다.
Claude Code는 CLI, IDE, Desktop, web, mobile, Agent SDK 등 여러 표면에서 실행됩니다. 개인 실험이라면 /model로 바꾸면 끝이지만, 팀 운영에서는 비용 상한, 보안 정책, 평가 완료 모델, third-party provider 지원 범위가 달라집니다. 그래서 "기본 모델을 무엇으로 시작할까"와 "어떤 모델로 바꿀 수 있게 할까"를 분리해야 합니다.
DAKER의 사용량과 팀 비용 읽기는 비용 관측을 다뤘고, sandbox.credentials 보안 설정는 실행 경계를 좁히는 법을 다뤘습니다. 이번 글은 모델 선택 경계를 운영 정책으로 고정하는 방법입니다.
model, availableModels, enforceAvailableModels는 어떻게 다른가요?
model은 세션이 시작할 때 고르는 초기값입니다. 하지만 사용자가 /model에서 Default를 고르면 계정 티어의 런타임 기본값으로 돌아갈 수 있습니다. 이 우회를 막으려면 availableModels와 enforceAvailableModels를 함께 봐야 합니다.
설정 | 역할 | 흔한 실수 |
|---|---|---|
| 세션 시작 모델 지정 | 이것만으로 팀 정책이 강제된다고 착각 |
| 선택 가능한 named model 제한 | Default가 여전히 열려 있을 수 있음 |
| Default도 allowlist 안에서 해석 | 빈 allowlist에는 기대처럼 동작하지 않음 |
|
| alias만 허용하고 실제 버전을 고정하지 않음 |
조직 모델 제한 | Console에서 특정 모델 사용을 제한 | provider와 인증 방식에 따라 전달 범위가 다름 |
공식 문서 기준 availableModels만 두면 Default 옵션은 남을 수 있습니다. 팀이 특정 모델 계열이나 버전을 강제하려면 Default 해석까지 확인해야 합니다.
단계별 사용법: 팀 모델 정책은 어떻게 잡나요?
먼저 팀 작업을 분류합니다. 예: 일반 구현, 대규모 리팩터링, 보안 리뷰, 문서 작성.
각 작업에 허용할 모델 계열과 비용 상한을 정합니다.
user/project/local 설정이 아니라 강제 정책이 필요한지 판단합니다.
강제가 필요하면 managed settings 또는 서버 관리 설정으로
availableModels를 배포합니다.Default 우회를 막아야 하면
enforceAvailableModels: true를 함께 둡니다.특정 버전 고정이 필요하면
ANTHROPIC_DEFAULT_SONNET_MODEL같은 alias 환경변수도 설정합니다.CLI, IDE, Desktop, web, mobile, Agent SDK 중 어느 표면에 정책이 전달되는지 확인합니다.
/model,--model, subagent model override, advisor model까지 실제로 거절/대체되는지 테스트합니다.
_model, availableModels, enforceAvailableModels, alias pinning을 나눠 점검하는 모델 거버넌스 흐름._
짧은 예시: 모델 정책 리뷰 문구는 어떻게 쓰나요?
이 저장소의 Claude Code 모델 설정을 운영 관점에서 리뷰해줘.
확인할 것:
- model이 초기값인지, 강제 정책인지 구분되어 있는지
- availableModels가 팀 정책과 맞는지
- Default 선택이 allowlist 밖 모델로 우회되지 않는지
- sonnet/opus/haiku/fable alias가 특정 버전을 가리키는지
- subagent, skill, advisor model override가 정책을 우회하지 않는지
- CLI, IDE, web/mobile, Agent SDK에 정책이 어디까지 전달되는지
결과는 위험도와 바로 바꿀 설정 순서로 정리해줘.이 문구는 모델 이름을 최신으로 맞히는 것보다 정책 구멍을 찾는 데 초점을 둡니다. 새 모델이 나올수록 "좋은 모델"보다 "검증된 모델"을 먼저 물어야 하는 팀도 많습니다.
팀 적용 체크리스트는 무엇인가요?
model을 강제 정책으로 오해하지 않았는가availableModels와enforceAvailableModels를 함께 검토했는가Default 선택이 계정 티어 기본값으로 빠지지 않는지 테스트했는가
alias가 허용될 때 실제 버전 pinning이 필요한지 정했는가
subagent, skill, command, advisor 모델 override까지 확인했는가
cloud/web/mobile 세션에는 어떤 managed settings가 전달되는지 확인했는가
제한된 모델을 선택했을 때 실패인지 대체인지 사용자 안내를 정했는가
공식 출처는 어디에서 확인했나요?
2026년 6월 25일 기준 Claude Code Model configuration documentation, settings documentation, organization model restriction notes를 확인했습니다. 공개 본문에는 DAKER 운영 정책에 맞춰 DAKER 내부 링크만 연결했습니다.
FAQ
model 설정만 하면 팀원이 다른 모델을 못 쓰나요?
아닙니다. model은 초기 선택에 가깝습니다. 사용자가 Default나 다른 모델을 고를 수 있는지까지 통제하려면 availableModels와 enforceAvailableModels를 함께 봐야 합니다.
availableModels에 빈 배열을 넣으면 모든 모델이 막히나요?
공식 문서는 빈 배열이 Default-model enforcement를 기대처럼 걸지 않는다고 설명합니다. 실제 정책에는 비어 있지 않은 allowlist와 enforceAvailableModels 조합을 검토해야 합니다.
subagent 모델 override도 제한되나요?
공식 문서 기준 subagent frontmatter, Agent tool의 model parameter, /agents picker, CLAUDE_CODE_SUBAGENT_MODEL 같은 표면도 allowlist 영향을 받습니다. 다만 거절이 아니라 inherited/default 모델로 fallback될 수 있어 결과 메시지를 확인해야 합니다.
비용 통제에는 모델 제한만으로 충분한가요?
아닙니다. 모델 제한은 한 축입니다. /usage, prompt caching, subagent 병렬도, 긴 context, Remote Control이나 automation 실행 빈도까지 같이 봐야 비용이 안정됩니다.
다음 팀 설정 리뷰에서는 먼저 "Default가 어디로 해석되는가"를 확인하고, 그다음 allowlist와 alias pinning을 맞춰 보세요.