Claude Opus 5 API 전환 가이드: 1M 컨텍스트와 effort 설정에서 먼저 바꿀 것

Claude Opus 5가 공개되면서 Anthropic API를 쓰는 팀은 단순히 모델명만 바꾸면 되는 상황이 아니다. 공식 릴리스 노트 기준으로 claude-opus-5는 1M 토큰 컨텍스트, 128k 최대 출력, 기본 활성화된 thinking, effort 제어, mid-conversation tool changes, server-side fallback 베타를 함께 가져왔다. 가격은 Opus 4.8과 같은 입력 $5/MTok, 출력 $25/MTok로 제시됐다.

핵심 키워드는 “Claude Opus 5 API 마이그레이션”이다. 검색 의도는 명확하다. 이미 Claude API를 쓰고 있고, 운영 중인 프롬프트·툴·캐시·비용 제어가 깨질지 확인하려는 개발자가 찾는 글이다. 이번 변경에서 중요한 건 성능 자랑보다 운영 인터페이스 변화다.

출처: Anthropic Platform release notes(2026-07-24), Anthropic Claude Opus 5 announcement.

무엇이 바뀌었나: 모델 스펙보다 운영 옵션이 중요하다

Opus 5는 기본 컨텍스트와 최대 컨텍스트가 모두 1M 토큰이다. 긴 레포지토리 분석, 계약서 묶음 검토, 로그 기반 장애 분석처럼 입력이 커지는 작업에는 분명히 유리하다. 최대 출력도 128k라서 긴 리팩터링 계획, 상세 보고서, 테스트 케이스 생성에 여유가 생긴다.

하지만 실제 운영에서 먼저 봐야 할 항목은 세 가지다.

• effort가 주요 제어 축이 됐다.
• thinking을 끄는 조건에 제한이 생겼다.
• 툴 구성과 fallback 정책을 런타임에 더 세밀하게 다룰 수 있다.

특히 Opus 5에서는 thinking: {"type":"disabled"}를 xhigh나 max effort와 같이 쓰면 400 에러가 난다. 기존 Opus 4.8에서 “강한 모델 + thinking off” 조합으로 지연시간을 맞추던 팀은 요청 빌더부터 점검해야 한다.

마이그레이션에서 먼저 터질 가능성이 높은 지점

첫 번째는 하드코딩된 모델 옵션이다. 모델명만 claude-opus-5로 바꿨는데, 기존 코드가 speed, thinking, temperature, max_tokens를 조합해서 보내면 일부 요청은 바로 실패할 수 있다. Anthropic은 Opus 4.7 fast mode도 제거했다. claude-opus-4-7에 speed:"fast"를 넣으면 fallback 없이 에러가 난다.

두 번째는 비용 추정이다. 1M 컨텍스트가 가능해졌다고 해서 매 요청에 레포 전체를 넣으면 비용은 바로 커진다. 1M 입력 토큰을 매번 보내면 입력만 요청당 $5 수준이다. 여기에 긴 출력이 붙으면 자동화 배치에서는 하루 예산이 쉽게 흔들린다.

세 번째는 prompt cache다. 이번 베타에서 mid-conversation tool changes는 대화 중 툴을 추가하거나 제거하면서도 prompt cache를 보존할 수 있게 한다. 이건 에이전트 워크플로우에 꽤 실용적이다. 예를 들어 첫 턴에는 읽기 도구만 열고, 분석 결과가 나오면 배포 도구를 추가하는 식의 단계형 권한 설계가 가능하다.

effort 설계: low부터 max까지 어떻게 나눌까

실무에서는 모델을 “좋은 모델 하나”로 쓰면 비용 제어가 어렵다. Opus 5의 effort를 작업 등급으로 나누는 게 낫다.

중요한 건 effort를 프롬프트 안에서 감으로 정하지 말고, 애플리케이션 라우터에서 정해야 한다는 점이다. 요청 유형, 입력 크기, 사용자 플랜, 실패 시 재시도 가능성을 기준으로 effort를 계산하면 운영이 훨씬 안정적이다.

fallback 베타는 “실패 숨기기”가 아니라 정책 라우팅이다

새 fallbacks 파라미터의 default 모드는 Anthropic 권장 fallback 모델을 거절 사유별로 적용한다. 안전 분류기에 걸린 요청이 무조건 차단되는 대신 다른 모델로 라우팅될 수 있다. 다만 이걸 켜면 응답 품질과 비용이 요청마다 달라질 수 있다.

따라서 운영 로그에는 최소한 다음 필드를 남겨야 한다.

• 최초 요청 모델
• 실제 응답 모델
• fallback 발생 여부
• stop reason과 refusal category
• 입력/출력 토큰
• 사용자에게 보여준 최종 메시지

이걸 남기지 않으면 “어제는 됐는데 오늘은 왜 다른 답이 나왔나”를 디버깅할 수 없다. fallback은 안정성을 높이는 장치지만, 관측성이 없으면 재현 불가능한 장애가 된다.

mid-conversation tool changes를 어디에 쓰면 좋은가

이 기능은 에이전트 보안 설계에 특히 맞다. 기존에는 대화 시작 시 모든 툴을 열어두거나, 툴 구성이 바뀔 때 캐시를 포기해야 했다. 이제는 대화 흐름에 맞춰 권한을 점진적으로 열 수 있다.

예시는 이렇다.

1. 첫 턴: 읽기 전용 도구만 허용한다.
2. 분석 완료: 테스트 실행 도구를 추가한다.
3. 사용자 승인 후: PR 생성 도구를 추가한다.
4. 배포 전: 배포 도구는 별도 세션에서만 허용한다.

이 구조는 비용과 보안을 같이 잡는다. 공통 시스템 프롬프트와 레포 컨텍스트는 캐시로 유지하고, 위험한 도구만 필요한 순간에 열면 된다.

바로 적용할 마이그레이션 체크리스트

• 모델명 변경 전에 요청 빌더에서 thinking, effort, speed 조합을 검증한다.
• xhigh 또는 max effort에서 thinking disabled를 보내지 않도록 테스트를 추가한다.
• 1M 컨텍스트 요청은 별도 예산 라우트로 분리한다.
• prompt cache hit/miss와 실제 청구 토큰을 로그에 남긴다.
• fallback 사용 시 최초 모델과 최종 모델을 모두 저장한다.
• 툴 권한은 “처음부터 전체 허용”이 아니라 단계별 추가 방식으로 재설계한다.
• Opus 4.7 fast mode 의존 코드가 있으면 Opus 5 또는 Opus 4.8로 옮긴다.

Opus 5 전환은 모델 업그레이드가 아니라 운영 계약 변경에 가깝다. 오늘 할 일은 벤치마크를 돌리는 것보다 요청 스키마와 로그를 먼저 고치는 것이다.