Claude Code를 Opus 5.5로 전환하고 모델을 고정하는 방법

/model에서 Opus를 선택했는데도 Claude Code가 다른 모델처럼 동작하거나, 첫 응답 전에 400 오류가 날 수 있습니다. Opus 5.5로 안정적으로 전환하려면 모델 명령, Claude Code 버전, 안전 거부 뒤에 발생할 수 있는 fallback을 서로 분리해 확인해야 합니다.

재현 가능한 설정이 필요하면 전체 모델 ID를 사용하세요. opus 별칭은 실제로 어떤 모델에 연결되는지 확인한 뒤에만 쓰는 편이 안전합니다. 또한 Opus 5.5의 기본 effort는 Opus 5의 high가 아니라 medium입니다.

전체 모델 ID로 Opus 5.5를 고정하세요

가장 명확한 명령은 다음과 같습니다.

/model claude-opus-5-5

Anthropic은 claude-opus-5-5를 날짜 접미사가 없는 고정 모델 ID로 문서화합니다. 팀 운영 문서, 프로젝트 설정, 사용자 지정 공급자에서는 모두가 같은 모델을 요청하는지 확인하기 쉬우므로 이 방식이 적합합니다.

더 짧은 명령은 다음과 같습니다.

/model opus

Claude Code 또는 사용자 지정 Base URL 뒤의 서비스가 이 별칭을 Opus 5.5로 해석한다고 표시할 때만 사용하세요. 대화형 작업에는 편하지만, 세션이나 게이트웨이 동작이 예상과 다를 때는 전체 ID가 원인 추적에 유리합니다.

목적	권장 선택	이유
정확한 모델 고정	/model claude-opus-5-5	요청한 ID가 명시적이고 재현 가능함
현재 Opus를 빠르게 선택	/model opus	입력은 짧지만 실제 해석 결과를 확인해야 함
외부 공급자 문제 진단	전체 ID부터 사용	별칭 매핑 문제와 모델 미제공을 구분할 수 있음

BetterToken처럼 Anthropic 호환 Base URL을 통해 Claude Code를 사용해도 /model 절차는 같습니다. 다만 별칭 결과만 믿지 말고 공급자가 실제로 claude-opus-5-5를 제공하는지 먼저 확인하세요.

전환 전에 Claude Code를 업데이트하세요

모델 출시 전에 배포된 클라이언트는 계정이나 공급자가 이미 지원하더라도 선택을 거부할 수 있습니다. 먼저 다음을 실행하세요.

claude update

업데이트 뒤에는 현재 Claude Code 세션을 다시 시작합니다. Claude 데스크톱 앱을 사용한다면 앱도 업데이트한 후 전체 ID 명령을 다시 실행하세요.

2026년 9월 22일의 한 커뮤니티 issue에는 구체적인 사례가 기록되어 있습니다. Claude Code 2.1.257이 claude_code_version_too_old로 거부되었고, 응답은 2.1.280 이상을 요구했습니다. 이는 버전 제한이 존재한다는 한 사례일 뿐, 영구적이고 보편적인 최소 버전이라는 뜻은 아닙니다. 이후 릴리스에서 기준이 달라질 수 있으므로 실제 오류에 적힌 최소 버전을 따르세요.

모델을 전환한 뒤 결과를 확인하세요

한 문제가 다른 문제를 가리지 않도록 다음 순서로 진행하세요.

1. claude update를 실행하고 Claude Code를 다시 시작합니다.
2. 작업할 세션에서 /model claude-opus-5-5를 입력합니다.
3. 명령 뒤 Claude Code가 표시하는 모델 선택을 확인합니다. 명령이 접수되었다는 사실만으로 성공을 판단하지 마세요.
4. 오래 걸리거나 비용이 큰 작업을 시작하기 전에 /model을 다시 열어 현재 선택을 한 번 더 확인합니다.

전체 ID는 동작하지만 /model opus가 예상과 다른 모델을 선택한다면 전체 ID를 계속 사용하세요. 이는 Opus 5.5 자체를 사용할 수 없는 문제가 아니라 별칭 해석 문제일 가능성이 큽니다.

두 방식 모두 동작하지 않고 서드파티 endpoint를 사용한다면 해당 공급자의 모델 제공 여부와 매핑을 확인하세요. 공식 Claude API가 표준 ID를 제공하더라도 호환 게이트웨이는 별도 카탈로그를 쓰거나 아직 새 모델을 활성화하지 않았을 수 있습니다.

기본 effort는 medium입니다

Claude Opus 5.5에서는 adaptive thinking이 항상 켜져 있고, 문서상 기본 effort는 medium입니다. Opus 5의 기본값은 high였으므로 Claude Code의 눈에 보이는 설정을 바꾸지 않아도 지연 시간, 토큰 사용량, 추론 깊이가 달라질 수 있습니다.

일반적인 Claude Code 사용에서는 전환 자체를 위해 임의의 effort 값을 만들 필요가 없습니다. 먼저 모델을 확인하고 실제 작업에서 기본 동작이 적절한지 평가하세요. 클라이언트나 API 게이트웨이가 effort 설정을 제공한다면 예전 Opus 기본값이 이어진다고 가정하지 말고 의도적으로 선택하세요.

사용자 지정 통합은 Opus 5.5의 요청 규칙도 지켜야 합니다. 이 모델은 thinking 비활성화와 수동 thinking budget을 거부합니다. 모델 선택은 성공했는데 첫 요청이 400을 반환한다면 /model을 반복하기보다 상위 게이트웨이의 payload 변환을 확인하세요.

메시지가 표시되면 fallback 경로일 수 있습니다

안전 거부는 일반적인 모델 선택과 별개의 경로입니다. API 수준에서 Opus 5.5는 HTTP 200과 함께 stop_reason: "refusal", 그리고 stop_details 객체를 반환할 수 있습니다. 클라이언트나 공급자가 fallback을 활성화했다면 해당 요청만 다른 모델로 재시도될 수 있습니다.

이를 요청 단위 fallback으로 이해하고, 저장된 /model 선택이 영구적으로 바뀌었다는 증거로 보지 마세요. 중요한 작업을 계속하기 전에 /model을 다시 열어 활성 모델을 확인하세요. Anthropic은 Opus 5.5에서 대부분의 다른 모델로 이동하면 이후 턴이 이전 Opus 5.5 thinking blocks 없이 실행된다고 설명합니다. 내부 추론이 모두 이어졌다고 가정하지 말고 핵심 조건을 다시 적어 주세요.

실제 대응 순서는 다음과 같습니다.

1. 거부 또는 표시 안내를 읽고 같은 요청을 수정 없이 다시 보내지 않습니다.
2. 정당한 요청이라면 안전 분류기를 자극한 부분을 제거하거나 다시 표현합니다.
3. 클라이언트나 공급자가 fallback 모델을 사용했는지 확인합니다.
4. 고정 모델이 필요한 작업을 재개하기 전에 Opus 5.5를 다시 확인합니다.

자주 발생하는 문제를 해결하세요

증상	먼저 확인할 항목	다음 조치
claude_code_version_too_old가 포함된 400	Claude Code 또는 데스크톱 버전	claude update 실행, 재시작, 전체 ID 재시도
목록에 Opus 5.5가 없음	클라이언트 또는 공급자 카탈로그	클라이언트 업데이트 후 공급자 제공 여부 확인
/model opus가 예상 밖 모델을 선택	별칭 해석	/model claude-opus-5-5 사용 후 표시 결과 확인
전체 ID는 접수되지만 첫 요청이 400	상위 payload 비호환	thinking 비활성/수동 설정과 게이트웨이 재작성 확인
메시지가 표시된 뒤 다른 모델이 응답	refusal 후 fallback	거부 내용 확인, 모델 재확인, 핵심 조건 재전달
세션 중간 전환 뒤 흐름이 끊김	thinking blocks가 이전되지 않았을 수 있음	모델을 확인하고 새 턴에 필요한 문맥 제공

실제 작업 전 최종 점검

• Claude Code를 업데이트하고 다시 시작했습니다.
• /model claude-opus-5-5가 버전 오류 없이 접수됩니다.
• 화면에 표시된 선택이 실제로 Opus 5.5로 해석됩니다.
• 별도 설정이 없다면 기본 medium effort를 예상합니다.
• 표시되거나 거부된 요청 뒤 fallback 사용 여부를 확인했습니다.

다섯 항목이 모두 확인되면 전체 모델 ID가 세션을 재현 가능하게 유지하는 가장 안전한 방법입니다. opus 별칭은 빠른 전환에 유용하지만 결과를 추측하지 말고 확인해야 합니다.

출처

• Anthropic: Opus 5.5 마이그레이션 가이드
• Anthropic: Claude Opus 5.5의 새로운 변경 사항
• GitHub issue #12870: 구형 클라이언트 버전 오류 사례