사고 끄면 Opus 5 호출이 400 될 수 있음

한 줄짜리 모델 변경처럼 보이는 마이그레이션도 에이전트가 토큰 하나를 쓰기 전에 실패할 수 있습니다. 문제의 핵심은 Opus 5의 effort 수준과 thinking 비활성화가 맞물리는 지점입니다.

어떤 Opus 5 API 설정에서 HTTP 400이 발생하나?

HTTP 400을 유발하는 Opus 5 API 설정은 thinking을 비활성화하면서 `xhigh` 또는 `max` effort를 함께 요청하는 경우입니다. Anthropic은 thinking 비활성화가 `high` effort 이하에서만 허용된다고 설명합니다 . 실무적으로 Opus 5 마이그레이션에서는 `output_config.effort`와 `thinking`을 서로 독립적인 토글이 아니라 함께 움직이는 제어값으로 봐야 합니다.

빠른 답변: Opus 5 호출은 `thinking`을 disabled로 설정하고 effort를 `high`보다 높게, 구체적으로 `xhigh` 또는 `max`로 설정하면 HTTP 400을 반환할 수 있습니다. Opus 5는 2026년 7월 24일 출시됐으며 adaptive thinking이 기본으로 켜져 있습니다 .

Claude Opus 5는 복잡한 코딩과 에이전트형 작업을 위한 Anthropic의 프로덕션 모델 대상이며, 2026년 7월 24일 API 모델 ID `claude-opus-5`로 출시됐습니다 . 모델 개요에는 100만 토큰 컨텍스트 창, 최대 128k 동기 출력 토큰, 기본 활성화된 adaptive thinking이 명시되어 있습니다 .

그래서 Opus 5는 Opus 4.1에서 단순히 모델 이름만 바꾸는 업그레이드가 아닙니다. 기존 Messages API 코드는 model 필드 변경으로 시작할 수 있지만, 프로덕션 에이전트에는 effort, thinking 동작, 도구 사용, 거부 처리, 토큰 예산에 대한 새 테스트가 여전히 필요합니다 . 위험한 지름길은 새 effort 계약을 확인하지 않은 채 “토큰을 아끼려고 reasoning을 끄던” 기존 습관을 그대로 가져오는 것입니다.

"thinking 비활성화는 도구 호출 동작에 영향을 줄 수 있습니다." — Anthropic, Claude effort guidance (source: Anthropic)

Anthropic은 또한 thinking을 비활성화하면 도구 호출이 구조화된 도구 invocation 대신 보이는 텍스트처럼 나타날 수 있다고 경고합니다 . 에이전트가 여전히 도구를 올바르게 호출한다는 eval 결과가 있을 때만 thinking 비활성화를 사용하세요.

아래 스니펫은 설명용이며 실행된 코드는 아닙니다. 자체 API 키로 실패 경로를 재현하거나 점검할 때 사용할 수 있는 요청 형태를 보여줍니다.

import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("ANTHROPIC_API_KEY")
if not api_key:
    print("Set ANTHROPIC_API_KEY to run this against the Anthropic API.")
    sys.exit(2)

payload = {
    "model": os.environ.get("ANTHROPIC_MODEL", "claude-opus-5-20260729"),
    "max_tokens": 64,
    "thinking": {"type": "disabled"},
    "messages": [{"role": "user", "content": "Say hello."}],
}

req = urllib.request.Request(
    "https://api.anthropic.com/v1/messages",
    data=json.dumps(payload).encode(),
    headers={
        "x-api-key": api_key,
        "anthropic-version": "2023-06-01",
        "content-type": "application/json",
    },
    method="POST",
)

try:
    with urllib.request.urlopen(req, timeout=30) as r:
        print(r.status, r.read().decode())
except urllib.error.HTTPError as e:
    print(e.code, e.read().decode())

Opus 5 API 설정 전 준비 사항

Opus 5 API 설정에는 Anthropic API 키, 최신 Anthropic SDK 또는 직접 HTTPS 클라이언트, Messages API, 그리고 claude-opus-5로 설정된 model 필드가 필요합니다. Anthropic은 Claude Opus 5가 Claude API와 주요 클라우드 채널을 통해 제공된다고 안내하므로, 프로덕션 팀은 트래픽을 보내기 전에 실제 계정, 리전, 배포 경로를 확인해야 합니다 .

최소 로컬 체크리스트는 단순합니다. ANTHROPIC_API_KEY를 설정하고, 이미 사용하는 공식 SDK를 설치하거나 업데이트하고, 요청은 Messages API에 유지하며, 모델 선택자를 claude-opus-5로 바꾸면 됩니다. Anthropic의 API primer는 Claude 애플리케이션 호출의 표준 요청 경로로 Messages API를 설명합니다 .

프로덕션 라우팅을 바꾸기 전에 실제로 운영하는 채널에서 Opus 5 사용 가능 여부를 확인하세요. Claude API, Amazon Bedrock, Google Cloud, Microsoft Foundry 또는 다른 관리형 Claude 배포가 여기에 해당합니다. Anthropic의 Opus 5 릴리스 노트는 Claude API와 클라우드 파트너 배포 전반에서 접근할 수 있다고 밝히지만, 클라우드 모델 ID, 리전, 할당량, 활성화 단계는 제공업체마다 다를 수 있습니다 .

Opus 5는 단순한 모델 이름 교체가 아니므로 구현 전에 한도를 먼저 정하세요. Anthropic은 기본값이자 최대값인 1M 토큰 컨텍스트 창, 128k 최대 동기 출력 토큰, prompt-cache 항목의 512 토큰 최소값을 문서화하고 있습니다 . 이 한도들은 첫 라이브 롤아웃 전에 요청 검증, 로깅, 캐시 청킹, 예산 알림의 기준이 되어야 합니다.

Claude Code 라우팅을 위한 Opus 5 단계별 도입 절차

Opus 5용 Claude Code 라우팅은 명확하고 측정 가능해야 하며, 작업 유형별로 나누어야 한다. 모델을 고정하고, effort 수준을 훑어 보며, 불확실성이 큰 작업에 Opus를 배정하고, fast mode는 별도로 벤치마크해야 한다. Claude Code는 대화형, CLI, 환경 변수, 설정 기반 제어를 통해 모델 선택을 지원하며, Anthropic은 Opus 5의 기본 effort 수준을 high로 문서화하고 있다 .

1. 테스트 전에 모델 선택을 고정한다. Claude Code에서는 /model, claude --model, ANTHROPIC_MODEL, 설정의 model 필드, 또는 ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, CLAUDE_CODE_SUBAGENT_MODEL 같은 계열별 override 변수를 사용해 Opus 5를 의도적으로 지정한다 . 이렇게 하면 한 개발자는 Opus를 테스트하는데 다른 개발자는 조용히 provider 기본값을 쓰는 식의 도입을 피할 수 있다.
2. Opus 4.1 설정을 그대로 복사하지 말고 effort 수준을 비교한다. 같은 작업 세트에 대해 low, medium, high, xhigh, max를 테스트한다. Anthropic은 high를 기본값으로 제시하지만, 그렇다고 모든 저장소 작업에서 그 값이 비용 대비 품질의 최적점이라는 뜻은 아니다 .
3. 이름값이 아니라 작업 성격으로 라우팅한다. 계획 수립, 진단, 리뷰, 아키텍처, 모호한 디버깅에는 Opus 5를 사용한다. 평가에서 품질 저하가 없다고 확인되면 일반 수정, 테스트 반복, 더 저렴한 실행 경로는 Sonnet이나 Haiku로 보낸다. Claude Code에 문서화된 모델 제어와 비용 가이드는 이런 계층형 라우팅을 뒷받침한다 .
4. fast mode는 별도 경로로 벤치마크한다. Opus 5 fast mode는 Claude API에서만 사용할 수 있으며, 가격은 입력 토큰 100만 개당 10달러, 출력 토큰 100만 개당 50달러다. Anthropic은 초당 출력 토큰 수가 최대 2.5배 높아질 수 있다고 설명한다 . 표준 라우팅을 그대로 대체하는 옵션이 아니라 처리량을 높이는 선택지로 다뤄야 한다.

출시 전에 확인해야 할 Opus 5 벤치마크와 비용 통제

Opus 5 벤치마크는 마이그레이션 판단에 유용한 신호이지만, 그것만으로 프로덕션 출시를 승인하기에는 충분하지 않습니다. Anthropic은 Opus 4.1이 SWE-bench Verified에서 74.5%를 기록했다고 발표했습니다 . 반면 Opus 5 자료에서는 SWE-bench Verified 96.0%, SWE-bench Pro 79.2%, SWE-bench Multilingual 89.5%, SWE-bench Multimodal 59.4%를 제시합니다 . 이 숫자들은 Opus 5를 자체 코딩 에이전트 하네스에서 테스트해볼 이유로 받아들여야지, 저장소 수준의 근거를 대체하는 자료로 봐서는 안 됩니다.

실무 평가 방식은 리더보드보다 릴리스 게이트에 가까워야 합니다. 통과율, 회귀 수, 도구 호출 규율, 실제 소요 시간, 재시도 횟수, 완료된 작업당 비용을 추적하세요. SWE-bench Verified는 유용한 공개 기준점이지만, Claude Code 라우팅 결정은 특히 서브에이전트, 장기 세션, 커스텀 모델 오버라이드가 워크플로에 포함된다면 자신의 코드베이스, 도구, 실패 양상을 기준으로 내려야 합니다 .

"복잡한 작업에는 Opus를, 일상적인 작업에는 Sonnet을 사용하세요." — Anthropic Claude Code 문서 (source: Anthropic Support)

비용도 같은 방식으로 다뤄야 합니다. Opus 5는 입력 토큰 100만 개당 5달러, 출력 토큰 100만 개당 25달러로 표시되어 있습니다 . 이는 Opus 4.1의 입력 토큰 100만 개당 15달러, 출력 토큰 100만 개당 75달러보다 훨씬 낮습니다 . 하지만 에이전트가 100만 토큰 컨텍스트 창을 공격적으로 사용하거나 고노력 시도를 반복하면, 낮은 단가에도 총 청구액은 더 커질 수 있습니다 .

• 모든 프로덕션 경로에 엄격한 max_tokens를 설정한 뒤, 평가에서 잘림이 확인되는 경우에만 늘리세요.
• 높은 노력 수준이 항상 지연 시간과 토큰 비용을 감수할 만큼 가치 있다고 가정하지 말고, 노력 수준별로 훑어보세요 .
• 저장소 평가에서 품질 저하가 없다고 확인되면 일상적인 구현, 테스트, 기계적 수정은 더 저렴한 모델로 라우팅하세요.
• 반복되는 대규모 컨텍스트에는 프롬프트 캐싱을 사용하세요. 캐시 읽기는 기본 입력 비용의 0.1배로 책정됩니다 .
• 적절한 비동기 워크로드는 Batch API로 옮기세요. Anthropic은 배치 처리에 입력과 출력 모두 50% 할인을 제시합니다 .
• Console 사용량을 과금 기준 소스로 삼고, 이를 자체 작업별 텔레메트리와 비교하세요 .

좋은 출시 결정은 단순합니다. Opus 5는 벤치마크 백분율뿐 아니라 달러당 완료한 작업량에서도 이겨야 합니다. 더 어려운 계획 수립과 리뷰 작업을 더 적은 재시도로 해결한다면 프리미엄 경로에 배치할 만합니다. 이미 통과하던 일상 작업에서만 개선된다면 그런 루프는 Sonnet이나 Haiku에 두고, 측정된 차이가 분명한 작업에 Opus 5를 남겨두세요.

Opus 4.1 대체 계획과 거절 처리

실제로 쓸 수 있는 Opus 5 대체 계획이라면 장기 프로덕션 경로에서 Opus 4.1을 제거해야 합니다. Anthropic은 2026년 6월 5일 Claude Opus 4.1을 지원 중단 대상으로 지정했고, Claude API 종료일을 2026년 8월 5일로 예정했습니다 . Opus 4.1은 임시 회귀 비교 대상 정도로만 다루세요. 프로덕션 대체 경로는 작업 가치, 비용, 실패 유형에 따라 라우팅해야 합니다.

실무 라우팅 패턴은 단순합니다. 불확실성이 높은 계획, 진단, 리뷰, 아키텍처, 어려운 에이전트 루프는 Opus 5로 보내고, 평가에서 품질 저하가 없다고 확인되면 더 저렴한 실행 경로는 Sonnet이나 Haiku에 유지하세요. 레거시 Opus 동작이 여전히 중요한 곳에서만 Opus 4.8을 단기 호환성 대체 모델로 사용하세요 . Claude Code는 설정, 환경 변수, 슬래시 명령, 모델 오버라이드 제어를 통한 명시적 모델 선택을 지원하므로, 대체 경로는 설치된 기본값에 맡기지 말고 의도적으로 구성해야 합니다 .

서버 측 대체 경로는 유용하지만 해결하는 문제의 범위는 좁습니다. Anthropic의 fallback beta는 server-side-fallback-2026-07-01 헤더를 사용하며, 기본 대체 모델 또는 최대 3개의 명시적 대체 모델 목록을 받습니다 . 이 경로는 지원되는 거절 범주에 적용되며, 모든 실패한 요청에 적용되는 것은 아닙니다.

• 거절 경로: stop_reason: "refusal"이 포함된 HTTP 200 응답은 네트워크 실패가 아니라 정책 또는 안전 결과로 처리하세요 .
• 신뢰성 경로: 429, 과부하, 5xx 오류는 클라이언트 측 재시도, 지수 백오프, 텔레메트리, 필요하다면 모델 또는 제공업체 페일오버로 처리하세요 .
• 비용 경로: Claude Code 비용 가이드는 단일 모델 라우팅보다 사용량 대시보드, 모델 계층화, 압축된 세션, 지출 한도를 권장하므로 달러당 완료 작업 수를 추적하세요 .

핵심은 이렇습니다. 더 깊은 추론이 필요한 작업에는 Opus 5를 프리미엄 경로로 두고, 일상 루프는 더 저렴한 모델에 유지하며, 거절 처리는 전송 신뢰성과 분리하세요. 여전히 Opus 4.1에 의존하는 대체 경로는 이미 종료 기한을 안고 있는 셈입니다.

자주 묻는 질문

Opus 5에서 thinking을 비활성화하면 왜 HTTP 400이 반환되나요?

Opus 5에서 thinking을 비활성화하면 HTTP 400이 반환될 수 있습니다. Anthropic은 effort가 high 이하로 설정된 경우에만 thinking: {"type":"disabled"}를 허용하며, xhigh와 max에서는 thinking 동작이 계속 활성화되어 있어야 하기 때문입니다 . 실제로는 output_config.effort를 high, medium, 또는 low로 낮추거나, 더 높은 effort 실행에서는 thinking을 활성화한 상태로 두면 해결됩니다.

모델 이름만 바꾸면 Opus 4.1에서 마이그레이션할 수 있나요?

기본적인 Messages API 호출은 모델 ID를 Opus 5로 바꾸는 것부터 시작할 수 있지만, 프로덕션 마이그레이션에서는 배포 전에 effort 설정, 토큰 제한, 도구 동작, 거부 처리, 지연 시간, 비용을 다시 테스트해야 합니다 . Opus 5에서는 effort가 품질, 지연 시간, 비용을 제어하는 핵심 요소가 되었고, 지원 값은 low부터 max까지입니다 .

Opus 5는 Opus 4.1보다 저렴한가요?

공개된 토큰 가격 기준으로는 Opus 5가 Opus 4.1보다 저렴합니다. Anthropic은 Opus 5를 입력 토큰 100만 개당 5달러, 출력 토큰 100만 개당 25달러로 제시하고 있으며, Opus 4.1은 입력 토큰 100만 개당 15달러, 출력 토큰 100만 개당 75달러로 제시되어 있었습니다 . 다만 더 큰 컨텍스트 창, 더 높은 effort, 더 긴 출력, 약한 프롬프트 캐싱, 광범위한 재시도, 일상적인 작업까지 기본적으로 Opus로 라우팅하는 방식 때문에 실제 비용은 여전히 늘어날 수 있습니다.

Claude Code는 모든 작업에 Opus 5를 써야 하나요?

아닙니다. Claude Code에서는 계획, 진단, 리뷰, 아키텍처, 어려운 추론에 Opus 5를 사용하고, 반복적인 구현 루프, 테스트, 기계적인 편집, 서브에이전트 작업은 저장소 평가에서 품질 저하가 없다고 확인될 때 더 저렴한 모델로 옮기는 것이 좋습니다. Claude Code는 설정, 환경 변수, 모델 오버라이드, 서브에이전트 모델 제어를 통한 명시적 모델 라우팅을 지원합니다 .

Opus 4.1의 대체 fallback은 무엇이 적절한가요?

필요한 경우 단기 호환성 fallback으로 Opus 4.8을 사용하고, 평가 결과 해당 라우팅이 가능하다고 확인되면 더 낮은 비용의 실행 경로에는 Sonnet 또는 Haiku를 사용하세요. Anthropic은 Opus 4.1을 2026년 6월 5일에 deprecated로 표시했고 2026년 8월 5일에 Claude API에서 retirement 예정이라고 명시했으므로, Opus 4.1은 임시 회귀 비교 용도로만 남겨두는 것이 좋습니다 .

이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.

구독하기