클로드 코드 새 모델 차단 — 허용 목록 앞자리 일치와 차단 목록 설정

회사 설정에 「오퍼스 5만 쓰게」 적어 둔 줄 알았는데, 오퍼스 5.5가 나온 날 팀원들 선택지에 그게 떠 있었다면 설정이 틀린 게 아닙니다. 원래 그렇게 동작하는 규칙이었습니다.

클로드 코드의 모델 허용 목록은 기본적으로 앞자리 일치로 동작합니다. 공식 문서의 예를 옮기면, 페이블 5를 가리키는 항목은 페이블 5와 페이블 5.1을 모두 허용하고, 오퍼스 5 항목은 오퍼스 5.5가 나오면 클로드 코드가 지원하는 즉시 그것까지 허용합니다. 새 모델이 나오면 비용과 동작을 먼저 확인하고 싶은 조직에게는 곤란한 구멍이었는데, 2.1.283판에서 이걸 막는 관리 설정 두 개가 생겼습니다. 예전에 권한 규칙으로 비싼 모델을 요청하는 곁가지 작업을 막는 법을 다뤘는데, 이번 것은 모델 선택 자체를 조직 단위로 잠그는 쪽입니다.

짧게 정리하면

• 차단 목록은 적어 둔 모델을 허용 목록이 허락하더라도 막고, 허용 목록 없이도 혼자 동작합니다.
• 정확 일치 설정을 켜면 허용 목록의 모델 항목이 적힌 판만 허용해서, 새 판은 목록에 추가할 때까지 막혀 있습니다.
• 두 설정 모두 관리 설정에서만 읽히고 2.1.283판 이상에서만 동작하므로, 최소 판 설정을 함께 걸어야 옛 판이 빠져나가지 못합니다.

클로드 코드 변경 기록 2.1.283, 모델 설정 문서의 모델 선택 제한 절, 설정 항목 참조의 세 항목을 대조했습니다. 설정 예시의 모델 아이디는 본문 표기 원칙에 따라 우리말로 풀어 적었습니다.

앞자리 일치가 새 판을 여는 방식

허용 목록 항목은 세 가지로 쓸 수 있습니다. 소넷처럼 모델 계열 이름, 소넷 4.5처럼 판 앞부분, 날짜까지 붙은 전체 모델 아이디입니다. 문제는 가운데입니다. 판 앞부분 항목은 그 뒤에 한 토막을 더 붙인 아이디까지 모두 허용합니다. 오퍼스 5 뒤에 5가 붙으면 오퍼스 5.5가 되니 허용 범위에 들어갑니다.

허용 목록이 관리 설정에 있으면 사용자·프로젝트·로컬 설정은 그 목록을 늘릴 수 없습니다. 설정이 덮어쓰기가 아니라 합쳐지는 규칙에서 이 목록은 예외로 관리 쪽 목록만 적용됩니다. 그러니 사용자가 우회하는 문제는 없는데, 관리자 스스로 적은 항목이 생각보다 넓게 열려 있었던 셈입니다.

설정 항목 참조 기준, 새 판을 붙잡는 두 설정

항목	차단 목록	정확 일치 설정
하는 일	적은 모델을 막음, 허용 목록이 허락해도 막음	허용 목록의 모델 항목이 적힌 판만 허용
허용 목록 없이	혼자서도 동작	허용 목록의 일치 방식을 바꾸는 설정
계열 이름을 적으면	그 계열 전체를 막음	계열 이름 항목은 여전히 계열 전체 허용
새 판이 나오면	어느 항목도 막지 않은 판은 허용된 채로 남음	목록에 추가할 때까지 막힘
무시되는 항목	최고 모델 별칭, 계획용 조합 별칭, 기본값	같음

두 설정은 성격이 반대입니다. 차단 목록은 「이것만 빼고」이고, 정확 일치는 「적은 것만」입니다. 새 판이 나올 때마다 확인 후 풀어 주는 운영이라면 정확 일치가 맞고, 특정 판 하나만 막고 나머지는 흐름대로 두려면 차단 목록이 맞습니다. 정확 일치에서 적힌 판에는 그 판의 날짜 붙은 아이디도 포함됩니다.

차단 목록의 표기 함정

차단 목록에 모델 아이디를 적으면 그 판을 모든 표기에서 막습니다. 날짜가 붙은 아이디도, 클라우드 사업자별 아이디도 함께 막힙니다. 여기까지는 편한데, 판 번호에서 뒷자리를 빼고 적으면 결과가 달라집니다. 오퍼스 5라고만 적으면 그 뒤의 오퍼스 5.5 같은 하위 판까지 함께 막힙니다. 오퍼스 5 하나만 막고 싶다면 문서 안내대로 5 뒤에 0을 붙인 아이디로 적어야 합니다.

허용 목록의 앞자리 일치와 방향이 같다는 점을 기억하면 헷갈리지 않습니다. 뒷자리를 비워 둔 항목은 허용 목록에서는 뒤따르는 판까지 열고, 차단 목록에서는 뒤따르는 판까지 닫습니다.

옛 판 클로드 코드는 두 설정을 모른 채 지나갑니다. 문서는 2.1.283판보다 오래된 판이 두 설정을 무시한다고 적고, 그런 판이 시작하지 못하게 최소 판 설정을 함께 걸라고 안내합니다. 또 두 설정은 관리 설정에서만 읽히고, 사용자·프로젝트·로컬 설정이나 명령줄 설정 옵션에 적으면 경고와 함께 무시됩니다. 개인 설정 파일에 적어 놓고 막혔다고 믿으면 아무것도 막히지 않은 상태입니다.

막힌 모델을 고르면 벌어지는 일

차단 목록이 적었든 정확 일치 목록에서 빠졌든, 막힌 모델은 허용 목록이 적용되는 모든 자리에서 막힌 선택으로 취급됩니다. 어디서 골랐느냐에 따라 결과가 조금씩 다릅니다.

모델 설정 문서 기준, 막힌 모델을 지정한 자리별 결과

지정한 자리	결과
모델 선택 창	목록에서 숨겨짐, 이름을 직접 입력해도 거부
시작 옵션·환경 변수·모델 설정	시작할 때 버려지고 기본 옵션으로 결정
훅이나 백그라운드 요청	차단 목록이 막은 모델이면 세션의 모델로 대신 실행
기본 옵션	막힌 모델로 가려 하면 정해진 순서로 한 단계씩 내려감

셋째 줄은 조건을 정확히 읽어야 합니다. 에이전트 훅의 모델 칸처럼 훅이나 백그라운드 요청이 막힌 모델을 부를 때 세션 모델로 돌린다는 설명은, 문서에 차단 목록이 막은 모델의 경우로 적혀 있습니다. 이 요청이 실패하지 않고 조용히 다른 모델로 돈다는 점도 알아 두면 좋습니다. 비슷한 조용한 교체는 자동 모델 변경이 한 번 일어나면 돌아오지 않는 문제에서도 본 적이 있습니다.

넷째 줄의 기본 옵션은 두 설정을 따릅니다. 기본 옵션까지 허용 목록에 묶는 별도 설정을 켰든 안 켰든 마찬가지입니다. 그 설정을 비어 있지 않은 허용 목록과 함께 켰다면 막힌 기본 모델은 허용 목록 밖 모델과 똑같이 처리됩니다. 켜지 않았다면 기본 옵션이 막힌 모델로 가려 할 때 세 단계로 내려갑니다. 먼저 같은 계열에서 허용된 가장 새 판, 다음으로 더 저렴한 계열인 소넷과 하이쿠 순서로 각각 허용된 가장 새 모델, 마지막으로 허용 목록에서 허용된 모델을 가리키는 첫 항목입니다. 셋 다 없으면 기본 옵션으로 시작하는 세션은 고칠 설정 이름을 적은 오류와 함께 시작을 거부합니다. 정확 일치 설정은 관리 쪽 허용 목록에 모델이나 계열이 하나라도 적혀 있을 때만 기본 옵션에 영향을 줍니다.

설정을 어떤 경로로 내려보내느냐도 따져야 합니다. 관리 콘솔에서 내리는 서버 관리 설정은 앤트로픽이 운영하는 클라우드 세션까지 닿지만 외부 클라우드 사업자 경유 세션에는 닿지 않습니다. 반대로 기기에 까는 관리 설정 파일은 앤트로픽이 운영하는 클라우드 세션에는 닿지 않습니다. 모델 제한 절에 표로 정리된 내용이니, 어느 쪽으로 배포할지 정하기 전에 한 번 보는 게 좋습니다.

관리 출처를 여러 경로로 배포한다면 두 목록이 다르게 합쳐진다는 점도 알아 두세요. 관리 출처 병합을 켰을 때 모델 차단 목록은 모든 출처의 항목이 합쳐지지만, 모델 허용 목록은 그 목록을 정한 가장 높은 출처의 것을 통째로 씁니다. 관리 출처가 여럿일 때 키 종류별로 합쳐지는 방식을 정리했으니, 출처를 나눠 쓰는 조직이라면 함께 보세요.

자주 묻는 질문

개인 설정 파일에 차단 목록을 적어도 되나요

안 됩니다. 두 설정은 관리 설정에서만 읽히고, 사용자·프로젝트·로컬 설정이나 명령줄 설정 옵션에 적으면 경고와 함께 무시됩니다.

계열 이름을 적은 허용 목록에도 정확 일치가 먹히나요

아닙니다. 정확 일치는 모델 아이디 항목에만 적용되고, 계열 이름 항목은 여전히 그 계열 전체를 허용합니다. 새 판을 붙잡으려면 계열 이름 대신 판 아이디를 적어야 합니다.

오퍼스 5만 막으려 했는데 5.5까지 막혔습니다

뒷자리 없는 아이디는 하위 판까지 막습니다. 문서 안내대로 5 뒤에 0을 붙인 아이디로 바꾸면 오퍼스 5만 막힙니다.

기업 요금제 관리 콘솔의 모델 끄기와는 뭐가 다른가요

콘솔의 모델 제한은 계정 권한과 함께 전달되는 별도 장치이고 역할별로 나눌 수 있으며, 하이쿠는 끌 수 없습니다. 둘이 함께 걸리면 허용 목록이 허락하고 조직도 막지 않은 모델만 고를 수 있습니다.

새 모델이 나올 때마다 팀 전체가 같은 날 옮겨 가는 게 늘 좋은 건 아닙니다. 새 판은 토큰 쓰는 방식이 달라질 수 있고, 지침 파일도 한 번 손봐야 할 수 있습니다. 그래서 제가 관리자라면 정확 일치를 켜 두고, 새 판은 몇 명이 먼저 써 본 뒤 목록에 추가하는 쪽을 고르겠습니다. 차단 목록은 그보다 가볍게, 문제가 확인된 판 하나를 급히 막을 때 쓰기 좋은 도구로 보입니다. 어느 쪽이든 최소 판 설정을 빠뜨리면 반쪽짜리가 된다는 점만은 꼭 챙기시길 권합니다.

확인한 곳: 클로드 코드 변경 기록 2.1.283, 공식 모델 설정 문서(모델 선택 제한, 적용 범위, 기본 옵션 동작, 특정 모델·판 차단, 조직 모델 제한), 설정 항목 참조의 허용 목록·정확 일치·차단 목록 항목. 2026년 9월 28일 기준입니다.