클로드 코드 조직 기본 모델 — 새 세션이 고른 모델과 다르게 시작하는 이유

어제 모델 선택 창에서 분명히 바꿔 뒀는데 오늘 켜 보니 다른 모델로 시작했다면, 설정이 날아간 게 아니라 더 높은 순위의 무언가가 이긴 경우가 대부분입니다.

클로드 코드의 모델 설정 문서에는 이 증상만 따로 다룬 절이 있습니다. 원인이 넷으로 정리돼 있고, 그중 하나가 기업 요금제 관리자가 정하는 조직 기본 모델입니다. 조직 기본 모델은 막는 장치가 아니라 출발점이라서, 무엇에 이기고 무엇에 지는지가 꽤 복잡합니다. 지난 글에서 새 모델을 붙잡아 두는 허용 목록 설정을 다뤘는데, 이번 글은 그 목록이 어떤 모델로 출발할지를 정하는 쪽과 어떻게 맞물리는지까지 이어서 봅니다.

짧게 정리하면

• 새 세션이 고른 모델과 다르게 시작하는 원인은 한 세션용 선택, 더 높은 순위의 설정, 저장 실패, 세션 재개 넷 중 하나입니다.
• 조직 기본 모델은 기본 옵션이 가리킬 모델을 정할 뿐이고, 시작 옵션·환경 변수·설정 파일의 모델 값이 있으면 그쪽이 이깁니다.
• 관리자가 사용자 선택을 덮어쓰는 옵션을 켜면 내가 저장한 선택은 그 세션에서만 유효하고 다음 실행에 조직 기본값으로 돌아갑니다.

클로드 코드 공식 모델 설정 문서의 새 세션 기본 모델, 다른 모델로 시작하는 경우, 조직 기본 모델, 기본값 설정 절을 대조했습니다. 설정 이름과 환경 변수 이름은 본문 표기 원칙에 따라 우리말로 풀어 적었습니다.

고른 모델이 다음 세션에 안 남는 네 가지 이유

모델 선택 창에서 고른 모델은 사용자 설정 파일에 저장됩니다. 그런데 이 저장이 일어나지 않거나, 저장은 됐는데 더 센 값에 밀리는 경우가 있습니다. 문서가 드는 원인을 표로 옮겼습니다.

모델 설정 문서 기준, 새 세션이 다른 모델로 시작하는 원인

원인	어떤 경우
한 세션용으로 골랐음	선택 창에서 이번 세션만 적용 키를 눌렀거나, 시작 옵션으로 모델을 지정했거나, 비대화형 실행에서 모델 명령을 썼음
더 높은 순위가 모델을 정함	프로젝트·관리 설정의 모델 값, 셸의 모델 환경 변수, 사용자 선택을 덮어쓰게 설정된 조직 기본 모델
저장을 못 했음	사용자 설정 파일에 쓸 수 없음, 다른 도구가 만들거나 읽기 전용 사본에 연결된 경우
세션을 재개했음	재개한 세션은 대개 그 세션이 쓰던 모델을 유지

둘째 줄은 확인이 쉬운 편입니다. 프로젝트나 관리 설정이 모델을 정했다면 시작할 때 머리 부분에 그 파일 이름이 찍힙니다. 이 경우에도 내 선택은 저장돼 있고, 순위에서 밀렸을 뿐입니다. 설정이 어떤 순서로 겹치는지는 설정이 덮어쓰기가 아니라 합쳐지는 규칙을 정리한 글에 있습니다. 셋째 줄은 설정 파일을 동기화 도구나 설정 관리 도구로 만들어 쓰는 분들이 겪습니다. 그 세션 동안은 고른 모델이 유지되다가 다음 실행에 옛 값을 다시 읽으니, 파일을 만드는 쪽 도구에 모델 값을 적거나 파일을 쓰기 가능하게 바꿔야 합니다. 넷째 줄은 세션을 재개할 때 무엇이 따라오고 무엇이 안 따라오는지와 같은 맥락입니다.

조직 기본 모델은 출발점일 뿐입니다

클로드 기업 요금제 관리자는 관리 콘솔에서 조직 전체나 사용자 지정 역할별로 기본 모델을 정할 수 있습니다. 정해 두면 모델 선택 창의 기본 옵션이 그 모델을 가리키고, 그 줄에 조직 기본값이라는 표시가 붙습니다. 조직 전체 값이든 역할 값이든 표시는 같습니다. 역할 기본값은 그 역할 구성원에게 조직 전체 값보다 우선하고, 여러 역할이 서로 다른 기본값을 정했다면 가장 성능이 높은 모델이 적용됩니다. 2.1.196판 이상이 필요합니다.

조직 기본 모델 절 기준, 덮어쓰기 옵션에 따른 순위

모델을 정하는 곳	덮어쓰기 꺼짐	덮어쓰기 켜짐
시작 옵션, 모델 환경 변수	조직 기본값을 이김	여전히 이김
관리 설정, 시작 시 넘긴 설정의 모델 값	조직 기본값을 이김	여전히 이김
사용자·프로젝트·로컬 설정의 모델 값, 선택 창에서 저장한 모델	조직 기본값을 이김	조직 기본값에 짐, 저장한 선택은 그 세션에만 적용

덮어쓰기가 켜진 조직에서는 선택 창에서 다른 모델을 골라도 다음 실행에 조직 기본값이 적용된다는 안내가 뜹니다. 이 옵션은 일부 조직에만 제공되고, 쓸 수 있는지는 앤트로픽 담당 팀에 문의하라고 문서에 적혀 있습니다. 조직 기본값은 시작할 때 한 번만 읽기 때문에 관리자가 세션 도중에 바꾸면 다음 실행부터 적용됩니다. 또 앤트로픽 API로 인증한 세션에만 닿고, 게이트웨이 배포처럼 다른 경로에서는 관리 설정의 모델 값으로 기본을 정해야 합니다.

관리자가 기본 모델을 바꾸면 내 저장값이 한 번 지워집니다. 덮어쓰기가 꺼진 조직이라도, 관리자가 조직 기본값을 바꾼 뒤 처음 대화형으로 실행할 때 클로드 코드가 사용자 설정 파일의 모델 값을 한 번 지웁니다. 새 기본값이 적용되게 하려는 동작이고, 파일의 다른 내용은 건드리지 않으며, 그 실행 뒤에 다시 고른 모델은 유지됩니다. 어느 날 갑자기 모델이 바뀌어 있고 설정 파일에서 모델 줄이 사라졌다면, 고장이 아니라 이 경우일 가능성이 큽니다.

허용 목록과 부딪치면

조직 기본 모델은 적용되기 전에 제한 검사를 몇 가지 거칩니다. 기본 앞자리 일치 방식에서는 허용 목록 하나만으로는 조직 기본값에 적용되지 않아서, 목록 밖의 조직 기본값도 그대로 쓰입니다. 기본 옵션까지 허용 목록에 묶는 설정을 함께 켜면, 목록 밖의 조직 기본값은 목록의 첫 항목으로 바뀝니다. 조직 차원의 모델 제한이 내 계정에 그 모델을 막았다면 같은 계열에서 허용된 가장 새 모델로, 계열 전체가 막혔다면 더 저렴한 계열로 대체됩니다. 차단 목록이나 정확 일치 목록에 막힌 경우는 지난 글에서 본 하강 순서를 따르고, 내 계정에서 아예 쓸 수 없는 모델이면 조직 기본값이 없는 것처럼 계정 종류의 기본값으로 돌아갑니다.

계정 종류별 기본값은 2.1.280판에서 바뀌었습니다. 프로·맥스·팀·엔터프라이즈와 앤트로픽 API, 그리고 아마존·구글 쪽 클라우드는 오퍼스 5.5가 기본이고, 마이크로소프트 파운드리는 소넷 4.5입니다. 2.1.280판 이전에는 프로와 팀 스탠더드가 소넷 5, 맥스·팀 프리미엄·엔터프라이즈 등이 오퍼스 5였습니다. 페이블 모델은 어느 요금제에서도 계정 기본값이 아니고, 선택 창에서 고르면 사용자 설정에 저장돼 다음 세션도 그걸로 시작합니다.

개인이 새 세션의 기본 모델을 정하는 환경 변수도 2.1.236판에 생겼습니다. 이 변수는 시작 옵션, 모델 환경 변수, 설정 파일의 모델 값, 조직 기본 모델이 모두 없을 때만 새 세션에 적용되고, 기본 옵션을 허용 목록에 묶는 설정이 켜져 있거나 조직 제한이 그 모델을 막으면 무시됩니다. 모델이 조용히 바뀌는 다른 경우로는 자동 모델 변경이 한 번 일어나면 돌아오지 않는 문제도 있으니, 세션 도중에 바뀌었다면 그쪽을 먼저 의심해 보세요.

관리 설정의 모델 값이 조직 기본 모델보다 우선한다고 했는데, 그 관리 설정이 어느 출처에서 오느냐도 따져야 합니다. 기본값에서는 정책 키를 내려준 가장 높은 관리 출처 하나만 읽고, 병합을 켜도 모델 같은 일반 키는 그 키를 정한 가장 높은 출처의 값을 씁니다. 관리 출처의 순위와 병합 규칙을 정리했으니, 모델 설정이 기대와 다르게 먹을 때 참고하세요.

클로드 코드 밖에서 에이피아이로 직접 붙인 코드의 모델을 소넷 5.5로 바꿀 계획이라면 조심할 점이 있습니다. 생각 끄기 값이나 도구 강제 호출처럼 소넷 5에서 되던 설정이 400 오류로 돌아옵니다. 소넷 5.5로 옮기면 깨지는 코드 다섯 곳을 먼저 확인해 보세요.

자주 묻는 질문

조직 기본 모델로 다른 모델 사용을 막을 수 있나요

아닙니다. 조직 기본 모델은 출발점이고 제한이 아닙니다. 고를 수 있는 모델을 좁히려면 조직 모델 제한이나 관리 설정의 허용 목록을 써야 합니다.

역할이 여러 개인데 기본 모델이 서로 다르면요

가장 성능이 높은 모델이 적용됩니다. 역할 기본값은 조직 전체 기본값보다 우선합니다.

조직 기본값이 평소와 다른 계열이면 원래 계열로 못 돌아가나요

2.1.199판부터는 선택 창에 평소 계열 줄이 따로 남아 있어서 세션 단위로 바꿀 수 있습니다. 2.1.196판부터 2.1.198판까지는 그 줄이 빠져 있었습니다.

게이트웨이를 거쳐 쓰는데 조직 기본값이 안 먹습니다

조직 기본 모델은 앤트로픽 API로 인증한 세션에만 닿습니다. 게이트웨이 배포에서는 관리 설정의 모델 값으로 기본을 정하라고 문서가 안내합니다.

모델이 내 뜻과 다르게 시작하면 대부분 버그부터 의심하게 되는데, 이 문서를 보면 대개 순위 문제입니다. 저라면 증상이 생겼을 때 시작 머리 부분에 설정 파일 이름이 찍히는지, 셸에 모델 환경 변수가 남아 있는지, 사용자 설정 파일에 모델 줄이 있는지를 이 순서로 보겠습니다. 관리자 입장이라면 조직 기본 모델만으로 비용을 통제하려 하지 말고, 허용 목록과 기본 옵션 묶기 설정을 함께 두는 편이 의도대로 동작합니다.

확인한 곳: 클로드 코드 공식 모델 설정 문서(새 세션 기본 모델 정하기, 새 세션이 다른 모델로 시작할 때, 조직 기본 모델, 기본값 설정, 모델 선택 제한). 2026년 9월 28일 기준이며 계정별 기본 모델은 판에 따라 바뀔 수 있습니다.