---
title: Claude Opus 5.5 마이그레이션 가이드
url: https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide
description: 이 마이그레이션 가이드를 통해 이전 Opus 모델 또는 Claude Sonnet 5에서 Claude Opus 5.5로 전환하세요. Claude Opus 5.5를 활성화하기 위한 안내에는 오류를 반환하는 요청 설정, 모든 응답에 포함되는 사고 블록, 그리고 각 시작 모델별 체크리스트가 포함되어 있습니다.
---
이 가이드는 [Messages API](https://platform.claude.com/docs/ko/build-with-claude/working-with-messages) 코드 마이그레이션을 다룹니다. [Claude Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview)를 사용하는 경우, 모델 이름을 업데이트하는 것 외에는 변경이 필요하지 않습니다.
**Claude API 스킬로 마이그레이션을 자동화하세요.** Claude Code에서 `/claude-api migrate`를 실행하여 번들로 제공되는 [Claude API 스킬](https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model)을 호출하세요. 현재 제공되는 모든 Claude 모델을 대상으로 사용할 수 있습니다:
Claude Code가 코드를 대신 마이그레이션하도록 하세요
```text
/claude-api migrate 이 프로젝트를 claude-opus-5-5 모델로 마이그레이션해 줘
```
이 스킬은 코드베이스 전반에 걸쳐 모델 ID 교체를 적용하고, 필요에 따라 호환성이 깨지는 매개변수 변경, 프리필(prefill) 대체, 대상 모델에 맞춘 effort 보정을 수행한 다음, 수동으로 확인해야 할 항목의 체크리스트를 생성합니다. 파일을 편집하기 전에 마이그레이션 범위(전체 작업 디렉터리, 하위 디렉터리 또는 특정 파일 목록)를 확인하도록 요청합니다. 또한 이 스킬은 Amazon Bedrock 및 Claude Platform on AWS 클라이언트를 감지하여 해당 플랫폼에 맞게 모델 ID 형식과 기능 변경 사항을 조정합니다.
이 페이지는 [Claude Opus 5](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), [Claude Opus 4.8](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8), [Claude Opus 4.7](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-47), [Claude Opus 4.6 및 이전 Opus 모델](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-46) 또는 [Claude Sonnet 5](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-sonnet-5)에서 Claude Opus 5.5로 전환할 때 필요한 코드 변경 사항을 설명합니다. 모든 독자는 [Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#request-requirements)과 [모든 응답에서 사고 처리하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#thinking-in-every-response)를 확인해야 합니다. 그런 다음 현재 사용 중인 모델의 섹션으로 이동하세요. 각 섹션의 첫 문장에 함께 적용되는 다른 섹션이 안내되어 있습니다. [마이그레이션 체크리스트](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migration-checklist)에는 시작 모델별로 모든 변경 사항이 정리되어 있습니다.
Claude Opus 5.5는 Claude Opus 5보다 비용이 저렴합니다(입력/출력 토큰 100만 개당 $4 / $20 USD이며, Claude Opus 5는 $5 / $25입니다. [Claude 가격](https://platform.claude.com/docs/ko/about-claude/pricing)을 참조하세요). 기능 지원 여부는 [Claude Opus 5.5의 새로운 기능](https://platform.claude.com/docs/ko/models/opus-5-5/whats-new-opus-5-5#feature-support)을 참조하세요. 동작상의 차이점과 모델별 프롬프팅 패턴은 [Claude Opus 5.5 프롬프팅](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/prompting-claude-opus-5-5)을 참조하세요.
## Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항
어떤 모델에서 전환하든 `claude-opus-5-5`에 대한 요청은 다음 사항을 충족해야 합니다. 항목에서 설정이 거부된다고 명시된 경우 API는 400 오류를 반환합니다.
* **모델 ID:** 날짜 접미사가 없는 고정 모델 ID인 `claude-opus-5-5`를 사용하세요. Amazon Bedrock, Claude Platform on AWS, Google Cloud, Microsoft Foundry에서는 해당 플랫폼의 모델 ID를 사용하세요. [가용성](https://platform.claude.com/docs/ko/models/opus-5-5/whats-new-opus-5-5#availability)을 참조하세요.
* **사고:** `thinking` 필드를 보내지 않거나, 이와 동일한 `thinking: {"type": "adaptive"}`를 보내세요. [adaptive thinking](https://platform.claude.com/docs/ko/build-with-claude/thinking)(적응형 사고)은 항상 켜져 있습니다. `thinking: {"type": "disabled"}`와 수동 사고 예산(`thinking: {"type": "enabled", "budget_tokens": N}`)은 거부됩니다. [사고 설정의 변경 전후 비교](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#thinking-cant-be-disabled)를 참조하세요.
* **Effort:** 사고 깊이는 이를 제어하는 유일한 요청 매개변수인 [effort 매개변수](https://platform.claude.com/docs/ko/build-with-claude/effort)로 제어하세요. 다섯 가지 수준(`low`, `medium`, `high`, `xhigh`, `max`)이 모두 지원되며 기본값은 `medium`입니다. [Claude Opus 5.5 권장 effort 수준](https://platform.claude.com/docs/ko/build-with-claude/effort#recommended-effort-levels-for-claude-opus-5-5)을 참조하세요.
* **도구 선택:** `tool_choice`로 `{"type": "auto"}`(기본값) 또는 `{"type": "none"}`을 사용하세요. `{"type": "any"}` 또는 `{"type": "tool", "name": "..."}`로 도구 호출을 강제하면 거부됩니다. [도구 선택의 변경 전후 비교](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#forced-tool-use)를 참조하세요.
* **샘플링 매개변수:** `temperature`, `top_p`, `top_k`를 생략하거나 기본값으로 두세요. 다른 값은 모두 거부됩니다. 모델의 동작은 프롬프트로 유도하세요.
* **프리필:** `messages`를 미리 채운 어시스턴트 턴으로 끝내지 마세요. 이는 거부됩니다. 대신 [structured outputs](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs)(구조화된 출력) 또는 시스템 프롬프트 지침을 사용하세요. Amazon Bedrock에서는 Claude Opus 5.5에 구조화된 출력을 사용할 수 없으므로, 시스템 프롬프트 지침을 사용하세요.
* **컴퓨터 사용:** Claude API와 Google Cloud에서는 컴퓨터 사용을 `computer_toolset_20260801` 도구 세트로 선언하세요. 해당 플랫폼에서는 이전 `computer_20251124` 도구가 거부됩니다. [컴퓨터 사용 관련 호환성이 깨지는 변경 사항](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#computer-use-toolset)을 참조하세요.
* **컨텍스트 윈도우:** 컨텍스트 윈도우 베타 헤더가 필요하지 않습니다. [1M 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/ko/build-with-claude/context-windows)가 기본값이며, 이전 모델용으로 보낸 헤더는 아무런 효과가 없습니다.
다음 요청은 목록의 모든 항목을 충족합니다. effort가 설정되어 있고 `thinking` 필드가 없습니다. 텍스트를 출력하는 SDK 탭은 `thinking` 블록이 먼저 오기 때문에 블록 유형으로 텍스트를 선택합니다.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"messages": [{
"role": "user",
"content": "Analyze the trade-offs between microservices and monolithic architectures"
}],
"output_config": {
"effort": "medium"
}
}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 4096 \
--output-config '{effort: medium}' \
--message '{role: user, content: "Analyze the trade-offs between microservices and monolithic architectures"}'
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Analyze the trade-offs between microservices and monolithic architectures",
}
],
output_config={"effort": "medium"},
)
for block in response.content:
if block.type == "text":
print(block.text)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
messages: [
{
role: "user",
content: "Analyze the trade-offs between microservices and monolithic architectures"
}
],
output_config: {
effort: "medium"
}
});
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = [
new() {
Role = Role.User,
Content = "Analyze the trade-offs between microservices and monolithic architectures"
}
],
OutputConfig = new OutputConfig
{
Effort = Effort.Medium
}
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the trade-offs between microservices and monolithic architectures")),
},
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortMedium,
},
})
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fmt.Println(textBlock.Text)
}
}
```
```java Java
import com.anthropic.models.messages.OutputConfig;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addUserMessage("Analyze the trade-offs between microservices and monolithic architectures")
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.MEDIUM)
.build())
.build();
Message response = client.messages().create(params);
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Analyze the trade-offs between microservices and monolithic architectures']
],
model: 'claude-opus-5-5',
outputConfig: ['effort' => 'medium'],
);
foreach ($message->content as $block) {
if ($block->type === 'text') {
echo $block->text, PHP_EOL;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
messages: [
{ role: "user", content: "Analyze the trade-offs between microservices and monolithic architectures" }
],
output_config: {
effort: "medium"
}
)
message.content.each do |block|
puts block.text if block.type == :text
end
```
## 모든 응답에서 사고 처리하기
Claude Opus 5.5에서는 모든 요청에서 사고가 실행되므로 모든 응답이 `thinking` 블록으로 시작할 수 있으며, `max_tokens`는 사고와 텍스트를 합한 양에 적용됩니다. 코드가 이미 사고를 켠 상태로 실행되고 있다면 1\~3번 항목은 이미 반영되어 있을 가능성이 높으므로 4번과 5번 항목을 확인하세요. 이전 모델에서 사고 없이 실행되었다면 모든 항목이 변경 사항입니다.
1. **`max_tokens`는 사고와 텍스트를 합한 양에 적용됩니다:** Claude Opus 4.8 및 이전 Opus 모델에서는 `thinking` 필드가 없는 요청이 사고 없이 실행됩니다. Claude Opus 5와 Claude Sonnet 5는 `thinking: {"type": "disabled"}`를 허용합니다. Claude Opus 5.5에서는 모든 요청이 [적응형 사고](https://platform.claude.com/docs/ko/build-with-claude/thinking)로 실행됩니다. `max_tokens`는 여전히 사고와 응답 텍스트를 합한 전체 출력에 대한 엄격한 제한이므로, 사고 없이 실행되던 워크로드에서는 이 값을 다시 검토하세요. 사고 토큰은 사고 텍스트가 반환되지 않더라도 출력 토큰으로 청구되므로, 이러한 워크로드는 요청당 더 많은 출력 토큰을 생성할 수 있습니다. [비용 제어](https://platform.claude.com/docs/ko/build-with-claude/thinking-steering-and-cost#cost-control)를 참조하세요. 사고에 사용하는 토큰을 줄이려면 [effort](https://platform.claude.com/docs/ko/build-with-claude/effort) 수준을 낮추세요. `xhigh` 또는 `max` effort로 실행하는 경우 모델이 사고하고 행동할 여유를 갖도록 `max_tokens`를 크게 설정하세요. 64k 토큰에서 시작하여 조정하세요. 프롬프트가 사고 없이 실행되도록 조정되어 있었다면 [사고 비활성화를 전제로 작성된 프롬프트](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#prompts-written-for-thinking-disabled)를 참조하세요.
2. **응답이 사고 블록으로 시작합니다:** 응답은 첫 번째 `text` 블록 앞에 하나 이상의 `thinking` 블록으로 시작할 수 있습니다. `content[0].text`처럼 위치로 응답을 읽는 코드나, 첫 번째 `content_block_start` 이벤트를 텍스트로 취급하는 스트림 핸들러는 이러한 응답에서 오작동합니다. 대신 `type` 필드로 콘텐츠 블록을 선택하세요. `type`이 `"text"`인 블록에서 `text`를 읽고, 스트림 이벤트를 처리할 때는 블록 유형에 따라 분기하세요.
3. **도구 사용 루프에서 사고 블록을 수정하지 않고 반환하세요:** 도구 사용 루프를 실행하는 경우, 도구 결과를 반환할 때 각 어시스턴트 응답의 `thinking` 블록을 `thinking` 필드가 비어 있는 블록까지 포함하여 완전하고 수정되지 않은 상태로 API에 다시 전달하세요. 콘텐츠 블록을 유형별로 필터링하거나 메시지를 재구성하지 말고, 받은 그대로 어시스턴트 메시지를 되돌려 보내세요. API는 편집되었거나 순서가 바뀌었거나 일부가 누락된 사고 블록을 400 오류로 거부합니다. [사고 블록 보존](https://platform.claude.com/docs/ko/build-with-claude/thinking#preserving-thinking-blocks)을 참조하세요.
4. **사고 텍스트는 기본적으로 생략됩니다:** `thinking.display`의 기본값은 `"omitted"`이므로 `thinking` 블록은 `signature`와 함께 빈 `thinking` 필드로 도착합니다. `thinking` 필드는 표시용 텍스트로만 취급하세요. 대신 읽을 수 있는 요약을 받으려면 `thinking.display`를 `"summarized"`로 설정하세요:
```python Python
thinking = {
"type": "adaptive",
"display": "summarized",
}
```
```typescript TypeScript
const thinking = {
type: "adaptive",
display: "summarized"
};
```
```csharp C#
var thinking = new ThinkingConfigAdaptive { Display = Display.Summarized };
```
```go Go
thinking := anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{
Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized,
},
}
```
```java Java
ThinkingConfigAdaptive thinking = ThinkingConfigAdaptive.builder()
.display(ThinkingConfigAdaptive.Display.SUMMARIZED)
.build();
```
```php PHP
$thinking = ['type' => 'adaptive', 'display' => 'summarized'];
```
```ruby Ruby
thinking = {
type: "adaptive",
display: "summarized"
}
```
제품에서 추론 과정을 사용자에게 스트리밍하는 경우, 기본값에서는 출력이 시작되기 전에 긴 멈춤이 나타납니다. 사고 중에 진행 상황이 보이도록 하려면 `display: "summarized"`를 설정하세요. [사고 표시 제어](https://platform.claude.com/docs/ko/build-with-claude/thinking#controlling-thinking-display)를 참조하세요.
5. **도구 호출 사이의 텍스트는 사고 블록으로 도착합니다:** 모델이 도구 호출 사이에 작성하는 짧은 메모는 `thinking` 블록으로 반환되며, 기본 표시 설정에서는 비어 있습니다. [도구 호출 사이의 텍스트가 사고 블록으로 반환됨](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#text-between-tool-calls)을 참조하세요.
## 시작 모델별 마이그레이션 체크리스트
그룹을 위에서부터 차례로 진행하고, 현재 모델이 명시된 그룹에서 멈추세요. 그 지점까지의 모든 항목이 적용됩니다. Claude Opus 5를 사용 중이라면 첫 번째 그룹이 전체 목록입니다. Claude Sonnet 5를 사용 중이라면 첫 번째 그룹과 마지막 그룹을 적용하세요.
### 모든 시작 모델
* 모델 ID를 `claude-opus-5-5`로 업데이트하세요.
* `thinking: {"type": "disabled"}`와 `thinking: {"type": "enabled", ...}`를 제거하고, 대신 effort 수준을 선택하세요.
* `effort`를 명시적으로 설정하세요. 기본값은 `medium`이며, Claude Opus 5의 기본값은 `high`입니다.
* `tool_choice` 유형 `any`와 `tool`을 `auto`와 엄격한 도구 사용 또는 구조화된 출력의 조합으로 대체하거나, Amazon Bedrock에서는 `auto`만으로 대체하세요.
* Claude API 또는 Google Cloud에서 컴퓨터 사용을 사용하는 경우, `computer_20251124` 대신 `computer_toolset_20260801`(베타 헤더 없음)을 선언하고 도구 세트에 맞게 에이전트 루프를 업데이트하세요. Amazon Bedrock에서는 `computer_20251124`를 유지하세요. 다른 플랫폼은 컴퓨터 사용 도구의 [호환성](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#compatibility) 섹션을 확인하세요.
* 라우터나 폴백이 대화를 Claude Opus 5.5에서 다른 모델로 옮길 수 있는 경우, 해당 모델은 Claude Opus 5.5의 사고 블록 없이 실행된다고 예상하세요(Claude API의 Claude Fable 5.1과 Claude Mythos 5.1은 예외로 이를 유지합니다). Claude Opus 5.5 자체는 Claude Opus 5, 이전 Opus, Sonnet, Haiku 모델, 그리고 Claude API와 Google Cloud에서는 Claude Sonnet 5.5와 Claude Haiku 5.5의 사고를 읽지만, Claude Fable 또는 Claude Mythos 모델의 사고는 읽지 않습니다.
* 콘텐츠 블록을 `type`으로 읽고, 도구 사용 루프에서 `thinking` 블록을 수정하지 않고 다시 전달하세요.
* 인터페이스에서 도구 호출 사이의 텍스트를 렌더링하는 경우, `display: "updates"`(베타) 또는 `"summarized"`를 설정하고 비어 있지 않은 `thinking` 블록을 렌더링하세요.
* 코드가 대화 도중에 이전 턴, `system` 프롬프트 또는 `tools`를 편집하는 경우 [보존된 사고](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking)를 따르세요.
* `stop_reason: "refusal"`을 처리하고 폴백을 구성하세요.
* 선택한 effort 수준에서 비용과 지연 시간의 기준선을 다시 설정하세요.
* 코드에서 사고를 비활성화했다면, 사고와 응답 텍스트를 합한 양에 적용되는 `max_tokens`를 다시 검토하세요. `xhigh` 또는 `max` effort에서는 64k에서 시작하세요. [모든 응답에서 사고 처리하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#thinking-in-every-response)를 참조하세요.
### Claude Opus 4.8 이하
* `thinking` 필드 없이 실행되던 워크로드를 검토하세요. Claude Opus 5.5에서는 이러한 워크로드가 사고와 함께 실행되며, 사고를 비활성화할 수 없습니다. 전체 출력(사고와 응답 텍스트)에 대한 엄격한 제한으로 유지되는 `max_tokens`를 다시 검토하고, 사고를 줄이고 싶은 곳에서는 `effort`를 낮추세요. 사고 토큰은 출력 토큰으로 청구되므로 이러한 워크로드는 요청당 더 많은 출력 토큰을 생성할 수 있습니다.
* `thinking` 필드를 파싱하는 코드가 이를 표시용 텍스트로만 취급하는지 확인하세요. 읽을 수 있는 요약을 받으려면 `display: "summarized"`를 설정하세요.
* 캐싱 최소 길이에 가까운 프롬프트를 검토하세요. 512 토큰 이상의 프롬프트는 캐시 항목을 생성할 수 있습니다.
* 조직에 [Priority Tier](https://platform.claude.com/docs/ko/api/service-tiers#supported-models) 약정이 있다면 용량을 별도로 계획하세요. Claude Opus 5.5에서는 Priority Tier가 지원되지 않습니다.
* `xhigh` 또는 `max` effort로 실행하는 경우, 시작점으로 `max_tokens`를 최소 64k로 높이세요.
* 에이전트 워크로드의 경우 [작업 예산](https://platform.claude.com/docs/ko/build-with-claude/task-budgets)(베타)과 대화 중간 도구 변경(베타)을 고려하세요.
### Claude Opus 4.7 이하
* 이전 모델에 맞게 조정된 설정을 그대로 가져오지 말고, 자체 평가에서 [effort](https://platform.claude.com/docs/ko/build-with-claude/effort) 스윕을 새로 실행하세요.
* 컨텍스트 윈도우 베타 헤더를 모두 제거하세요.
* 지침을 업데이트하기 위해 대화 기록을 재구성하는 경우, 프롬프트 캐시 적중을 유지하기 위해 대화 중간 시스템 메시지로 전환하는 것을 고려하세요.
* 중지 사유 처리 코드가 거부 시 `stop_details`를 읽는지 확인하세요.
* Claude Opus 4.7에서 거부되는 fast mode를 사용하려면 Claude API 요청에 `speed: "fast"`를 설정하세요. Claude Opus 5.5에는 베타 헤더가 필요하지 않습니다.
### Claude Opus 4.6 이하
* 요청 페이로드에서 `temperature`, `top_p`, `top_k`를 제거하세요.
* `thinking: {"type": "enabled", "budget_tokens": N}`을 `thinking: {"type": "adaptive"}`와 [effort 매개변수](https://platform.claude.com/docs/ko/build-with-claude/effort)의 조합으로 대체하거나, `thinking` 필드를 완전히 제거하세요. 적응형 사고는 항상 켜져 있습니다.
* UI에 사고 내용을 표시하는 경우, 사고 요약을 명시적으로 활성화하세요.
* 업데이트된 토큰화 방식에서 엔드투엔드 비용과 지연 시간을 다시 벤치마크하세요.
* 압축 트리거를 포함하여, 업데이트된 토큰화 방식을 고려해 `max_tokens`를 다시 조정하세요.
* 클라이언트 측 토큰 수 추정을 다시 테스트하세요.
* 애플리케이션에서 이미지를 보내는 경우, [고해상도 이미지 지원](https://platform.claude.com/docs/ko/build-with-claude/vision#high-resolution-image-support-on-claude-opus-4-7)에 맞게 예산을 다시 책정하세요(전체 해상도 이미지당 이미지 토큰이 최대 약 3배 증가). 추가 충실도가 필요하지 않다면 보내기 전에 다운샘플링하세요.
* 모델의 포인팅 또는 바운딩 박스 좌표를 사용하는 경우, 배율 변환을 모두 제거하세요. Claude Opus 4.7 이상 모델에서는 좌표가 실제 이미지 픽셀과 1:1로 대응합니다.
* Claude Opus 4.7부터 시작된 [동작 변경 사항](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#behavior-changes)을 검토하세요.
* 제품이 정당한 보안 작업을 수행하는 경우, 사이버 콘텐츠에 대한 제한 완화를 받으려면 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet)에 신청하세요.
### Claude Opus 4.5 이하
* 어시스턴트 메시지 프리필을 모두 제거하세요. Claude Opus 4.6에서 이미 거부됩니다.
* 도구 호출 JSON 파싱에 표준 JSON 파서를 사용하는지 확인하세요.
* `client.beta.messages.create()` (csharp: `client.Beta.Messages.Create()`; go: `client.Beta.Messages.New()`; java: `client.beta().messages().create()`; php: `$client->beta->messages->create()`; cli: `ant beta:messages create`)에서 `client.messages.create()` (csharp: `client.Messages.Create()`; go: `client.Messages.New()`; java: `client.messages().create()`; php: `$client->messages->create()`; cli: `ant messages create`)로 이전하세요. 적응형 사고와 effort에는 베타 네임스페이스가 필요하지 않습니다.
* `effort-2025-11-24` 베타 헤더를 제거하세요(effort 매개변수에는 필요하지 않습니다).
* `fine-grained-tool-streaming-2025-05-14` 베타 헤더를 제거하세요.
* `interleaved-thinking-2025-05-14` 베타 헤더를 제거하세요(적응형 사고는 인터리브 사고를 자동으로 활성화합니다).
* `output_format`을 `output_config.format`으로 마이그레이션하세요(해당하는 경우).
### Claude 4.1 이하
* 도구 버전을 업데이트하세요(`text_editor_20250728`, `code_execution_20260521`).
* `refusal` 중지 사유를 처리하세요.
* `model_context_window_exceeded` 중지 사유를 처리하세요.
* 도구 문자열 매개변수의 후행 줄바꿈 처리를 확인하세요.
* 레거시 베타 헤더(`token-efficient-tools-2025-02-19`, `output-128k-2025-02-19`)를 제거하세요.
* [프롬프팅 모범 사례](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/claude-prompting-best-practices)에 따라 프롬프트를 검토하고 업데이트하세요.
### Claude Sonnet 5만 해당
* 지침을 업데이트하기 위해 대화 기록을 재구성하는 경우, 프롬프트 캐시 적중을 유지하기 위해 대화 중간 시스템 메시지로 전환하는 것을 고려하세요.
* 캐싱 최소 길이에 가까운 프롬프트를 검토하세요. 512 토큰 이상의 프롬프트는 캐시 항목을 생성할 수 있습니다.
## Claude Opus 5에서 Claude Opus 5.5로 마이그레이션하기
먼저 [Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#request-requirements)과 [모든 응답에서 사고 처리하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#thinking-in-every-response)를 진행하세요. 모든 시작 모델에 이 섹션의 변경 사항이 필요합니다. 이는 Claude Opus 5.5가 거부하는 요청 설정과 그에 따른 응답 변경 사항입니다. 이 섹션의 체크리스트는 [마이그레이션 체크리스트](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migration-checklist)의 첫 번째 그룹입니다.
### 모델 이름 업데이트
```python
model = "claude-opus-5" # Before
model = "claude-opus-5-5" # After
```
`claude-opus-5-5`는 날짜 접미사가 없는 고정 모델 ID로, `claude-opus-5`와 동일한 체계입니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud 및 Microsoft Foundry에서는 해당 플랫폼의 모델 ID를 사용하세요. [가용성](https://platform.claude.com/docs/ko/models/opus-5-5/whats-new-opus-5-5#availability)을 참조하세요.
### 호환성이 깨지는 변경 사항
각 변경 사항은 [Claude Opus 5.5의 새로운 기능](https://platform.claude.com/docs/ko/models/opus-5-5/whats-new-opus-5-5#breaking-changes)에서 설명하며, 이 섹션에서는 각 변경 사항에 대한 코드 변경을 제공합니다.
#### 사고를 비활성화할 수 없음
`thinking: {"type": "disabled"}`와 `thinking: {"type": "enabled", "budget_tokens": N}`는 모두 400 오류(`"thinking.type.disabled" is not supported for this model.` 또는 `"thinking.type.enabled" is not supported for this model.`)를 반환합니다. `thinking` 필드를 제거하고 [effort](https://platform.claude.com/docs/ko/build-with-claude/effort) 수준을 선택하세요. 토큰을 절약하기 위해 사고를 비활성화했던 경우에는 더 낮은 수준을 사용하세요. 그러면 응답이 `thinking` 블록으로 시작하므로, `type`으로 콘텐츠 블록을 선택하고 도구 결과와 함께 `thinking` 블록을 수정하지 않은 채로 다시 전달하세요. [사고를 비활성화할 수 없음](https://platform.claude.com/docs/ko/models/opus-5-5/whats-new-opus-5-5#thinking-cant-be-disabled)을 참조하세요.
변경 전. Claude Opus 5는 이 요청을 허용하지만, Claude Opus 5.5는 400 오류로 거부합니다:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 16000,
"thinking": {"type": "disabled"},
"messages": [{"role": "user", "content": "..."}]
}'
```
```bash CLI
ant messages create \
--model claude-opus-5 \
--max-tokens 16000 \
--thinking '{type: disabled}' \
--message '{role: user, content: "..."}'
```
```python Python
client.messages.create(
model="claude-opus-5",
max_tokens=16000,
thinking={"type": "disabled"},
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5",
max_tokens: 16000,
thinking: { type: "disabled" },
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 16000,
Thinking = new ThinkingConfigDisabled(),
Messages = [new() { Role = Role.User, Content = "..." }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfDisabled: &anthropic.ThinkingConfigDisabledParam{},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(16000L)
.thinking(ThinkingConfigDisabled.builder().build())
.addUserMessage("...")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 16000,
thinking: ThinkingConfigDisabled::with(),
messages: [['role' => 'user', 'content' => '...']],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 16000,
thinking: Anthropic::ThinkingConfigDisabled.new,
messages: [{ role: "user", content: "..." }]
)
```
변경 후:
```bash cURL
# thinking은 항상 켜져 있으며, effort로 제어합니다
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 16000,
"output_config": {"effort": "low"},
"messages": [{"role": "user", "content": "..."}]
}'
```
```bash CLI
# 사고(thinking)는 항상 켜져 있으며, effort 값으로 제어합니다
ant messages create \
--model claude-opus-5-5 \
--max-tokens 16000 \
--output-config '{effort: low}' \
--message '{role: user, content: "..."}'
```
```python Python
client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
output_config={"effort": "low"}, # thinking is always on; effort is the control
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
output_config: { effort: "low" }, // thinking is always on; effort is the control
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
OutputConfig = new() { Effort = Effort.Low }, // thinking is always on; effort is the control
Messages = [new() { Role = Role.User, Content = "..." }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortLow, // thinking is always on; effort is the control
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
// thinking은 항상 켜져 있으며, effort로 제어합니다
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.LOW)
.build())
.addUserMessage("...")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 16000,
// thinking(사고)은 항상 켜져 있으며, effort로 제어합니다
outputConfig: OutputConfig::with(effort: Effort::LOW),
messages: [['role' => 'user', 'content' => '...']],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 16000,
# thinking은 항상 켜져 있으며, effort로 제어합니다
output_config: { effort: Anthropic::OutputConfig::Effort::LOW },
messages: [{ role: "user", content: "..." }]
)
```
#### 강제 도구 사용은 지원되지 않음
`tool_choice` 유형 `any`와 `tool`은 토큰 카운팅 엔드포인트를 포함하여 400 오류(`tool_choice: type "tool" and "any" are not supported for this model.`)를 반환합니다. [엄격한 도구 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/strict-tool-use) 또는 [구조화된 출력](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs)과 함께 `auto`를 사용하고, 도구가 적용되는 경우를 프롬프트에 명시하세요. 엄격한 도구 사용은 JSON Schema의 하위 집합을 허용하므로, `strict: true`를 추가하기 전에 각 도구의 `input_schema`를 확인하세요. 스키마의 모든 객체는 `additionalProperties: false`를 설정해야 합니다. [JSON Schema 제한 사항](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs#json-schema-limitations)을 참조하세요. Amazon Bedrock에서는 엄격한 도구 사용을 포함한 구조화된 출력을 Claude Opus 5.5에서 사용할 수 없습니다. 해당 플랫폼에서는 `strict` 없이 `auto`를 보내고, 도구가 적용되는 경우를 프롬프트에 명시하며, 코드에서 도구 입력을 검증하세요. [강제 도구 사용은 지원되지 않음](https://platform.claude.com/docs/ko/models/opus-5-5/whats-new-opus-5-5#forced-tool-use-is-not-supported)을 참조하세요.
변경 전. Claude Opus 5는 이 요청을 허용하지만, Claude Opus 5.5는 400 오류로 거부합니다:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 1024,
"tools": [{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": ["location"],
"additionalProperties": false
}
}],
"tool_choice": {"type": "tool", "name": "get_weather"},
"messages": [{"role": "user", "content": "What'\''s the weather in Paris?"}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5
max_tokens: 1024
tools:
- name: get_weather
description: Get the current weather in a given location
input_schema:
type: object
properties:
location:
type: string
description: The city and state, e.g. San Francisco, CA
required: [location]
additionalProperties: false
tool_choice:
type: tool
name: get_weather
messages:
- role: user
content: What's the weather in Paris?
YAML
```
```python Python
client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "tool", "name": "get_weather"},
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5",
max_tokens: 1024,
tools,
tool_choice: { type: "tool", name: "get_weather" },
messages: [{ role: "user", content: "What's the weather in Paris?" }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 1024,
Tools = [.. tools],
ToolChoice = new ToolChoiceTool { Name = "get_weather" },
Messages = [new() { Role = Role.User, Content = "What's the weather in Paris?" }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 1024,
Tools: tools,
ToolChoice: anthropic.ToolChoiceParamOfTool("get_weather"),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in Paris?")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(1024L)
.tools(tools)
.toolChoice(ToolChoiceTool.of("get_weather"))
.addUserMessage("What's the weather in Paris?")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 1024,
tools: $tools,
toolChoice: ToolChoiceTool::with(name: 'get_weather'),
messages: [['role' => 'user', 'content' => "What's the weather in Paris?"]],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 1024,
tools: tools,
tool_choice: Anthropic::ToolChoiceTool.new(name: "get_weather"),
messages: [{ role: "user", content: "What's the weather in Paris?" }]
)
```
변경 후:
```bash cURL
# strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"tools": [{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": ["location"],
"additionalProperties": false
},
"strict": true
}],
"tool_choice": {"type": "auto"},
"messages": [{
"role": "user",
"content": "What'\''s the weather in Paris? Use the get_weather tool."
}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
tools:
- name: get_weather
description: Get the current weather in a given location
input_schema:
type: object
properties:
location:
type: string
description: The city and state, e.g. San Francisco, CA
required: [location]
additionalProperties: false
# strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
strict: true
tool_choice:
type: auto
messages:
- role: user
content: What's the weather in Paris? Use the get_weather tool.
YAML
```
```python Python
client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
# strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
tools=[{**tool, "strict": True} for tool in tools],
tool_choice={"type": "auto"},
messages=[
{
"role": "user",
"content": "What's the weather in Paris? Use the get_weather tool.",
}
],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
// strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
tools: tools.map((tool) => ({ ...tool, strict: true })),
tool_choice: { type: "auto" },
messages: [
{
role: "user",
content: "What's the weather in Paris? Use the get_weather tool."
}
]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
// strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
Tools = [.. tools.Select(tool => tool with { Strict = true })],
ToolChoice = new ToolChoiceAuto(),
Messages =
[
new()
{
Role = Role.User,
Content = "What's the weather in Paris? Use the get_weather tool.",
},
],
});
```
```go Go
// strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
var strictTools []anthropic.ToolUnionParam
for _, tool := range tools {
strictTool := *tool.OfTool
strictTool.Strict = anthropic.Bool(true)
strictTools = append(strictTools, anthropic.ToolUnionParam{OfTool: &strictTool})
}
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: strictTools,
ToolChoice: anthropic.ToolChoiceUnionParam{OfAuto: &anthropic.ToolChoiceAutoParam{}},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.NewTextBlock("What's the weather in Paris? Use the get_weather tool."),
),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
// strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
.tools(tools.stream()
.map(tool -> tool.tool()
.map(customTool -> customTool.toBuilder().strict(true).build())
.map(ToolUnion::ofTool)
.orElse(tool))
.toList())
.toolChoice(ToolChoiceAuto.builder().build())
.addUserMessage("What's the weather in Paris? Use the get_weather tool.")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
// strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
tools: array_map(fn (Tool $tool) => $tool->withStrict(true), $tools),
toolChoice: ToolChoiceAuto::with(),
messages: [
[
'role' => 'user',
'content' => "What's the weather in Paris? Use the get_weather tool.",
],
],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
# strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
tools: tools.map { |tool| tool.merge(strict: true) },
tool_choice: Anthropic::ToolChoiceAuto.new,
messages: [
{ role: "user", content: "What's the weather in Paris? Use the get_weather tool." }
]
)
```
#### 사고 블록은 모델 및 대화에 연결됨
Claude API에서는 Claude Fable 5.1과 Claude Mythos 5.1이 Claude Opus 5.5의 사고 블록을 읽으며, 다른 모델은 읽지 않습니다. 대화를 Claude Opus 5.5에서 다른 모델로 옮기는 라우터나 폴백은 해당 턴을 사고 블록 없이 실행합니다. 반대 방향으로, Claude Opus 5.5는 Claude Opus 5, 이전 Opus, Sonnet, Haiku 모델, 그리고 Claude API와 Google Cloud에서는 Claude Sonnet 5.5와 Claude Haiku 5.5의 사고 블록을 읽지만, Claude Fable 또는 Claude Mythos 모델의 사고 블록은 읽지 않습니다. 블록이 유효하게 유지되도록 대화를 추가 전용(append-only)으로 유지하세요(대화 도중 `system` 프롬프트, `tools` 또는 이전 메시지를 편집하지 않음). Claude Code, claude.ai, Claude Managed Agents, Claude Agent SDK는 이미 그렇게 하고 있습니다. 적용 방식은 모든 플랫폼에서 Claude Fable 5.1과 동일합니다. 2026년 8월 31일 00:00 UTC 이후에 생성된 계정의 경우, 이러한 편집 후 사고 블록을 재전송하면 기본적으로 400 오류가 반환됩니다. 추가 전용 통합에는 코드 변경이 필요하지 않습니다. [사고 블록이 모델 및 대화에 연결됨](https://platform.claude.com/docs/ko/models/opus-5-5/whats-new-opus-5-5#thinking-blocks-are-tied-to-the-model-that-produced-them)과 [보존된 사고](https://platform.claude.com/docs/ko/build-with-claude/preserved-thinking)를 참조하세요.
#### `computer_20251124` 컴퓨터 사용 도구는 Claude API 및 Google Cloud에서 지원되지 않음
Claude API 및 Google Cloud에서 유형이 `computer_20251124`인 `tools` 항목은 400 오류(`'claude-opus-5-5' does not support tool types: computer_20251124.`와 그 뒤에 모델이 허용하는 도구 유형)를 반환합니다. 대신 `computer_toolset_20260801` 도구 세트를 선언하세요: 베타 헤더를 제거하고 `name`이나 디스플레이 크기 없이 항목을 전송하세요. 에이전트 루프에서는 멤버 `tool_use` 블록(액션은 `input.action`이 아니라 블록의 `name`입니다)을 턴당 여러 개 처리하고, 모든 결과에 `toolset_name`을 그대로 반환하세요. 요청 변경 사항은 아래에 나와 있으며, 에이전트 루프 변경 사항은 [`computer_20251124`에서 마이그레이션](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124)에 나열되어 있습니다. Amazon Bedrock에서는 이전 `computer_20251124` 도구가 Claude Opus 5에서와 마찬가지로 Claude Opus 5.5에서도 계속 작동하므로 변경이 필요하지 않습니다. 다른 플랫폼의 경우 컴퓨터 사용 도구의 [호환성](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#compatibility) 섹션을 참조하세요. [Claude API 및 Google Cloud에서 `computer_20251124` 컴퓨터 사용 도구는 지원되지 않음](https://platform.claude.com/docs/ko/models/opus-5-5/whats-new-opus-5-5#computer-20251124-is-not-supported)을 참조하세요.
변경 전. Claude Opus 5는 이 요청을 허용하지만, Claude API와 Google Cloud에서 Claude Opus 5.5는 400 오류로 거부합니다:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: computer-use-2025-11-24" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 4096,
"tools": [{
"type": "computer_20251124",
"name": "computer",
"display_width_px": 1024,
"display_height_px": 768
}],
"messages": [{"role": "user", "content": "Open the display settings."}]
}'
```
```bash CLI
ant beta:messages create \
--model claude-opus-5 \
--max-tokens 4096 \
--beta computer-use-2025-11-24 \
--tool '{
type: computer_20251124,
name: computer,
display_width_px: 1024,
display_height_px: 768
}' \
--message '{role: user, content: "Open the display settings."}'
```
```python Python
client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["computer-use-2025-11-24"],
tools=[
{
"type": "computer_20251124",
"name": "computer",
"display_width_px": 1024,
"display_height_px": 768,
}
],
messages=[{"role": "user", "content": "Open the display settings."}],
)
```
```typescript TypeScript
await client.beta.messages.create({
model: "claude-opus-5",
max_tokens: 4096,
betas: ["computer-use-2025-11-24"],
tools: [
{
type: "computer_20251124",
name: "computer",
display_width_px: 1024,
display_height_px: 768
}
],
messages: [{ role: "user", content: "Open the display settings." }]
});
```
```csharp C#
await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 4096,
Betas = [AnthropicBeta.ComputerUse2025_11_24],
Tools =
[
new BetaToolComputerUse20251124
{
DisplayWidthPx = 1024,
DisplayHeightPx = 768,
},
],
Messages = [new() { Role = Role.User, Content = "Open the display settings." }],
});
```
```go Go
client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaComputerUse2025_11_24},
Tools: []anthropic.BetaToolUnionParam{
{OfComputerUseTool20251124: &anthropic.BetaToolComputerUse20251124Param{
DisplayWidthPx: 1024,
DisplayHeightPx: 768,
}},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Open the display settings.")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(4096L)
.addBeta(AnthropicBeta.COMPUTER_USE_2025_11_24)
.addTool(BetaToolComputerUse20251124.builder()
.displayWidthPx(1024L)
.displayHeightPx(768L)
.build())
.addUserMessage("Open the display settings.")
.build();
client.beta().messages().create(params);
```
```php PHP
$client->beta->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 4096,
betas: [AnthropicBeta::COMPUTER_USE_2025_11_24],
tools: [
BetaToolComputerUse20251124::with(
displayWidthPx: 1024,
displayHeightPx: 768,
),
],
messages: [['role' => 'user', 'content' => 'Open the display settings.']],
);
```
```ruby Ruby
client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 4096,
betas: [Anthropic::AnthropicBeta::COMPUTER_USE_2025_11_24],
tools: [
Anthropic::Beta::BetaToolComputerUse20251124.new(
name: :computer,
display_width_px: 1024,
display_height_px: 768
)
],
messages: [{ role: "user", content: "Open the display settings." }]
)
```
변경 후:
```bash cURL
# 베타 헤더가 필요 없습니다. toolset 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"tools": [{"type": "computer_toolset_20260801"}],
"messages": [{"role": "user", "content": "Open the display settings."}]
}'
```
```bash CLI
# 베타 헤더가 필요 없으며, toolset 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
ant messages create \
--model claude-opus-5-5 \
--max-tokens 4096 \
--tool '{type: computer_toolset_20260801}' \
--message '{role: user, content: "Open the display settings."}'
```
```python Python
client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
# beta 헤더가 필요 없으며, toolset 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
tools=[{"type": "computer_toolset_20260801"}],
messages=[{"role": "user", "content": "Open the display settings."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 4096,
// 베타 헤더가 필요 없으며, toolset 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
tools: [{ type: "computer_toolset_20260801" }],
messages: [{ role: "user", content: "Open the display settings." }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
// 베타 헤더가 없습니다. toolset 항목은 이름이나 표시 크기를 받지 않습니다
Tools = [new ComputerToolset20260801()],
Messages = [new() { Role = Role.User, Content = "Open the display settings." }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
// 베타 헤더가 필요 없으며, toolset 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
Tools: []anthropic.ToolUnionParam{
{OfComputerToolset20260801: &anthropic.ComputerToolset20260801Param{}},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Open the display settings.")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
// 베타 헤더가 필요 없으며, toolset 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
.addTool(ComputerToolset20260801.builder().build())
.addUserMessage("Open the display settings.")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 4096,
// 베타 헤더가 필요 없으며, toolset 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
tools: [ComputerToolset20260801::with()],
messages: [['role' => 'user', 'content' => 'Open the display settings.']],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 4096,
# 베타 헤더가 필요 없으며, toolset 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
tools: [Anthropic::ComputerToolset20260801.new],
messages: [{ role: "user", content: "Open the display settings." }]
)
```
### 도구 호출 사이의 텍스트가 사고 블록으로 반환됨
Claude Opus 5에서는 모델이 도구 호출 사이에 작성하는 텍스트가 `text` 블록으로 반환됩니다. Claude Opus 5.5에서는 Claude Fable 5.1과 마찬가지로 이러한 설명이 [진행 상황 업데이트 `thinking` 블록](https://platform.claude.com/docs/ko/build-with-claude/thinking#progress-updates)으로 반환되며, 각 도구 호출 앞에 최대 하나씩 반환됩니다. 기본 `thinking.display` 값인 `"omitted"`에서는 해당 블록의 `thinking` 필드가 비어 있습니다. 요청이 실패하지는 않지만, 해당 텍스트를 진행 상황 업데이트로 사용자에게 스트리밍하는 애플리케이션은 도구 호출 사이에 아무것도 표시하지 않게 됩니다. 업데이트를 복원하려면 `thinking` 블록에서 업데이트를 읽고, 해당 텍스트를 반환하는 `display` 값을 설정하세요: `"updates"`(베타, `thinking-display-updates-2026-08-18` 헤더)는 추론은 숨긴 채 진행 상황 업데이트를 반환하고, `"summarized"`는 둘 다 섞어서 반환합니다. 그런 다음 비어 있지 않은 각 `thinking` 블록을 그 뒤에 오는 `tool_use` 블록보다 먼저 렌더링하고, 어시스턴트 턴의 나머지 부분과 함께 블록을 변경하지 않은 채로 다시 전달하세요. [사용자 대상 진행 상황 업데이트](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates)를 참조하세요.
### 안전 분류기 및 폴백
Claude Opus 5.5는 `stop_details` 카테고리와 함께 `stop_reason: "refusal"`을 반환할 수 있습니다. 분류기가 Claude Opus 5보다 더 넓은 범위의 카테고리를 다루므로, `"cyber"`와 `"reasoning_extraction"` 외에도 `"bio"`와 같은 `stop_details.category` 값을 예상하세요. [거부 카테고리 표](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback#refusal-response)를 참조하세요. 거부를 처리하고 [서버 측 폴백](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback#server-side-fallback) 또는 자체 재시도를 구성하세요(서버 측 폴백은 `"reasoning_extraction"`으로 거부된 요청을 재시도하지 않으며, 해당 거부는 그대로 반환됩니다). [거부와 폴백](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback)과 [안전장치 거부](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#safeguard-refusals)를 참조하세요.
### 권장 변경 사항
1. **effort 스윕을 다시 실행하세요.** Effort는 Claude Opus 5.5에서 유일한 사고 제어 수단이며, 기본값이 Claude Opus 5의 `high`와 달리 `medium`이므로 `effort`를 생략한 요청은 이제 `medium`으로 실행됩니다. 품질이 유지되는 경우에는 수준을 낮추고, 가장 까다로운 작업에는 수준을 높이세요. [Effort](https://platform.claude.com/docs/ko/build-with-claude/effort)를 참조하세요.
2. **모델별 프롬프트 지침을 재평가하세요.** Claude Opus 5의 동작에 맞춰 조정된 지침은 더 이상 필요하지 않을 수 있습니다. [Claude Opus 5.5 프롬프팅](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/prompting-claude-opus-5-5)을 참조하세요. 사고를 비활성화한 상태로 실행했다면 [사고 비활성화를 전제로 작성된 프롬프트](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#prompts-written-for-thinking-disabled)도 참조하세요.
3. 프로덕션 트래픽을 전환하기 전에 **개발 환경에서 테스트하세요**.
## Claude Opus 4.8에서 Claude Opus 5.5로 마이그레이션하기
먼저 [Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#request-requirements), [모든 응답에서 사고 처리하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#thinking-in-every-response), [Claude Opus 5에서 Claude Opus 5.5로 마이그레이션하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-5)를 진행하세요. 교체할 모델 ID로 `claude-opus-4-8`을 사용하세요. 마지막 섹션은 Claude Opus 4.8의 코드에도 그대로 적용됩니다. Claude Opus 4.8은 Claude Opus 5와 마찬가지로 다음과 같기 때문입니다:
* `thinking: {"type": "disabled"}`, 강제 도구 선택, `computer_20251124` 도구를 허용합니다.
* 도구 호출 사이의 텍스트를 `text` 블록으로 반환합니다.
* 기본 effort가 `high`입니다.
이 섹션에서는 Claude Opus 4.8과 Claude Opus 5 사이에 변경된 사항을 추가로 설명합니다. 체크리스트는 [마이그레이션 체크리스트](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migration-checklist)의 처음 두 그룹을 참조하세요.
### 변경된 사항
1. **사고를 생략했던 요청에서도 사고가 실행됩니다:** Claude Opus 4.8에서는 요청하지 않는 한 사고가 꺼져 있습니다. Claude Opus 5.5에서는 `thinking` 필드가 없는 요청도 사고와 함께 실행되므로, [모든 응답에서 사고 처리하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#thinking-in-every-response)의 모든 항목이 해당 코드의 변경 사항입니다. 코드에서 `thinking` 필드를 보낸 적이 없다면 [사고 설정의 변경 전후 비교](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#thinking-cant-be-disabled)에서 제거할 것이 없습니다.
2. **더 낮은 프롬프트 캐싱 최소 길이:** Claude Opus 5.5의 최소 캐시 가능 프롬프트 길이는 512 토큰으로, Claude Opus 4.8의 1,024 토큰보다 낮습니다. Claude Opus 4.8에서 캐시하기에 너무 짧았던 프롬프트도 코드 변경 없이 캐시 항목을 생성할 수 있습니다. 모델별 최소 길이는 [프롬프트 캐싱](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching#cache-limitations)을 참조하세요.
3. **Priority Tier는 지원되지 않습니다:** [Priority Tier](https://platform.claude.com/docs/ko/api/service-tiers#supported-models)는 Claude Opus 5.5에서 지원되지 않지만, Claude Opus 4.8에서는 계속 지원됩니다. 조직에 Priority Tier 약정이 있다면 용량을 별도로 계획하세요.
### 권장 변경 사항
다음 사항은 필수는 아니지만 사용 경험을 개선합니다:
1. **작업 예산(베타)을 고려하세요:** 에이전트 워크로드의 경우, [작업 예산](https://platform.claude.com/docs/ko/build-with-claude/task-budgets)은 전체 에이전트 루프에 사용할 수 있는 토큰 수를 모델에 알려줍니다. `task-budgets-2026-03-13` 베타 헤더가 필요합니다.
2. **대화 중간 도구 변경(베타)을 고려하세요:** 대화 중간 도구 변경을 사용하면 이전 턴의 [프롬프트 캐시](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching) 적중을 무효화하지 않고 대화의 턴 사이에 도구를 추가하거나 제거할 수 있습니다. `tools` 배열 자체를 변경하면 캐시된 접두사가 무효화됩니다. Claude API에서는 `inline-tools-2026-09-15` 베타 헤더를 보내세요. 이전 `mid-conversation-tool-changes-2026-07-01` 헤더는 Claude API, Amazon Bedrock, Google Cloud에서 참조로 도구를 지정하는 변경에 대해 여전히 작동합니다.
## Claude Opus 4.7에서 Claude Opus 5.5로 마이그레이션하기
먼저 [Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#request-requirements), [모든 응답에서 사고 처리하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#thinking-in-every-response), [Claude Opus 5에서 Claude Opus 5.5로 마이그레이션하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), [Claude Opus 4.8에서 Claude Opus 5.5로 마이그레이션하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8)를 진행하세요. 교체할 모델 ID로 `claude-opus-4-7`을 사용하세요. 이 섹션들은 Claude Opus 4.7의 코드에도 그대로 적용됩니다. Claude Opus 4.7은 Claude Opus 4.8과 마찬가지로 `thinking: {"type": "disabled"}`, 강제 도구 선택, `computer_20251124` 도구를 허용합니다. 기본 effort는 `high`이며, 요청하지 않는 한 사고 없이 실행됩니다.
이 섹션에서는 Claude Opus 4.7 이후에 변경된 사항을 추가로 설명합니다. 코드가 Claude Opus 4.6 이하에서 실행 중이라면, 이 섹션 다음에 [Claude Opus 4.6 및 이전 Opus 모델에서 Claude Opus 5.5로 마이그레이션하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-46)를 계속 진행하세요. 해당 섹션에서는 Claude Opus 4.7에서 적용된 호환성이 깨지는 변경 사항을 추가로 설명합니다. 체크리스트는 [마이그레이션 체크리스트](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migration-checklist)의 처음 세 그룹을 참조하세요.
### 변경된 사항
다음 항목 중 어느 것도 앞선 섹션의 변경 사항 외에 호환성이 깨지는 변경 사항을 추가하지 않지만, 모델 ID를 교체한 후 확인해 볼 가치가 있습니다.
1. **effort 수준 재조정:** Claude Opus 5.5에서는 Claude Opus 4.7과 비교하여 각 effort 수준에 할당되는 토큰이 달라집니다. 기본값은 `medium`이며, Claude Opus 4.7의 기본값은 `high`입니다. Claude Opus 4.7에 맞게 조정된 설정을 그대로 가져오지 말고, 자체 평가에서 effort 스윕을 새로 실행하세요. [Effort](https://platform.claude.com/docs/ko/build-with-claude/effort)를 참조하세요.
2. **1M 컨텍스트 윈도우가 기본값입니다:** Claude Opus 5.5는 베타 헤더 없이 기본적으로 전체 1M 토큰 [컨텍스트 윈도우](https://platform.claude.com/docs/ko/build-with-claude/context-windows)를 제공합니다. 클라이언트가 이전 모델과의 호환성을 위해 컨텍스트 윈도우 베타 헤더를 전달하고 있다면 제거하세요.
3. **대화 중간 시스템 메시지:** Claude API, Amazon Bedrock, Google Cloud에서 Claude Opus 5.5는 `messages` 배열에서 사용자 턴 바로 뒤에 오는 `role: "system"` 메시지를 허용합니다([배치 규칙](https://platform.claude.com/docs/ko/build-with-claude/mid-conversation-system-messages#limitations)이 적용됨). 처음부터 적용되는 지침에는 최상위 `system` 필드를 사용하세요. Claude Opus 4.7은 `messages`의 `role: "system"`을 400 오류로 거부합니다. 지침을 업데이트하기 위해 전체 메시지 기록을 재구성하는 코드 경로를 유지하고 있다면, 이를 단순화하고 이전 턴의 [프롬프트 캐시](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching) 적중을 유지할 수 있습니다.
4. **거부 중지 세부 정보:** 모델이 요청을 거부하면 Claude Opus 5.5는 `refusal` 중지 사유와 함께 거부 카테고리를 명시하는 `stop_details` 객체를 반환합니다. Claude Opus 4.7도 동일한 객체를 반환하므로, 이는 중지 사유 처리 코드가 아직 이 객체를 읽지 않는 경우에만 중요합니다. 베타 헤더가 필요하지 않으며, 비활성화할 수 없습니다. 중지 사유 처리 코드가 아직 이 객체를 읽지 않는다면 [중지 사유 처리](https://platform.claude.com/docs/ko/build-with-claude/handling-stop-reasons)를 참조하세요. Claude Opus 5.5는 더 많은 카테고리에서 거부합니다. [안전 분류기 및 폴백](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#safety-classifiers-and-fallback)을 참조하세요.
5. **Fast mode:** Claude Opus 5.5는 Claude API에서 [fast mode](https://platform.claude.com/docs/ko/build-with-claude/fast-mode)를 지원합니다. Fast mode는 Claude Opus 4.7에서는 사용할 수 없으며, `speed: "fast"`가 포함된 요청은 오류를 반환합니다. 요청에 `speed: "fast"`를 설정하세요. Claude Opus 5.5에는 베타 헤더가 필요하지 않습니다.
6. **컴퓨터 사용 도구 세트 및 브라우저 사용 도구:** Claude API와 Google Cloud에서 Claude Opus 5.5는 `computer_toolset_20260801` 도구 세트 형태의 [컴퓨터 사용](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool)과 웹페이지 내 작업을 위한 [브라우저 사용 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-tool)를 지원합니다. Claude Opus 4.7은 둘 다 지원하지 않습니다. 해당 플랫폼에서 Claude Opus 5.5는 이전 `computer_20251124` 도구를 허용하지 않습니다. [컴퓨터 사용 관련 호환성이 깨지는 변경 사항](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#computer-use-toolset)을 참조하세요.
## Claude Opus 4.6 및 이전 Opus 모델에서 Claude Opus 5.5로 마이그레이션하기
먼저 앞선 모든 섹션을 페이지 순서대로 진행하세요. 해당 섹션은 [Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#request-requirements), [모든 응답에서 사고 처리하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#thinking-in-every-response), 그리고 [Claude Opus 5](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), [Claude Opus 4.8](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8), [Claude Opus 4.7](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-47)에 대한 섹션입니다. 이 섹션들은 Claude Opus 4.6의 코드에도 그대로 적용됩니다. Claude Opus 4.6은 Claude Opus 4.7과 마찬가지로 `thinking: {"type": "disabled"}`, 강제 도구 선택, `computer_20251124` 도구를 허용합니다. 기본 effort는 `high`이며, 요청하지 않는 한 사고 없이 실행됩니다. Claude Opus 4.5 및 이전 Opus 모델도 `thinking: {"type": "disabled"}`와 강제 도구 선택을 허용하고 요청하지 않는 한 사고 없이 실행되므로, 이 섹션들은 해당 모델에도 적용됩니다.
이 섹션에서는 `claude-opus-4-6`을 교체할 모델 ID로 하여 Claude Opus 4.7에서 변경된 사항을 추가로 설명합니다. 두 하위 섹션에서는 [Claude Opus 4.5 이하](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-45) 및 [Claude 4.1 이하](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-4-1-or-earlier)를 사용하는 독자를 위해 그 이전에 변경된 사항을 추가로 설명합니다. 체크리스트는 [마이그레이션 체크리스트](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migration-checklist)에서 사용 중인 모델이 명시된 그룹까지를 참조하세요.
### 호환성이 깨지는 변경 사항
1. **확장 사고 제거:** `thinking: {"type": "enabled", "budget_tokens": N}`는 Claude Opus 4.7 이상 모델에서 더 이상 지원되지 않으며 400 오류를 반환합니다. [적응형 사고](https://platform.claude.com/docs/ko/build-with-claude/thinking)(`thinking: {"type": "adaptive"}`)로 전환하고, [effort 매개변수](https://platform.claude.com/docs/ko/build-with-claude/effort)를 사용하여 사고 깊이를 제어하세요. Claude Opus 5.5에서는 적응형 사고가 항상 켜져 있습니다. `thinking: {"type": "adaptive"}`는 유효하며, `thinking` 필드를 완전히 생략하는 것과 동일합니다.
이전 (Claude Opus 4.6):
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-6",
"max_tokens": 16000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"messages": [
{
"role": "user",
"content": "..."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-4-6
max_tokens: 16000
thinking:
type: enabled
budget_tokens: 10000
messages:
- role: user
content: "..."
YAML
```
```python Python
client.messages.create(
model="claude-opus-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-4-6",
max_tokens: 16000,
thinking: { type: "enabled", budget_tokens: 10000 },
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_6,
MaxTokens = 16000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
Messages = [new() { Role = Role.User, Content = "..." }]
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_6,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(10000),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.maxTokens(16000L)
.enabledThinking(10000L)
.addUserMessage("...")
.build();
Message response = client.messages().create(params);
IO.println(response);
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 16000,
messages: [['role' => 'user', 'content' => '...']],
model: 'claude-opus-4-6',
thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
);
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-4-6",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000
},
messages: [
{ role: "user", content: "..." }
]
)
```
이후(Claude Opus 5.5)에는 모델 ID, `thinking`, `output_config` 줄이 달라집니다:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 16000,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "high"
},
"messages": [
{
"role": "user",
"content": "..."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 16000
thinking:
type: adaptive
output_config:
effort: high
messages:
- role: user
content: "..."
YAML
```
```python Python
client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"}, # or "max", "xhigh", "medium", "low"
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: { type: "adaptive" },
output_config: { effort: "high" }, // or "max", "xhigh", "medium", "low"
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
Thinking = new ThinkingConfigAdaptive(),
OutputConfig = new OutputConfig { Effort = Effort.High }, // or Max, Xhigh, Medium, Low
Messages = [new() { Role = Role.User, Content = "..." }]
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
},
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortHigh, // or Max, Xhigh, Medium, Low
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.HIGH) // or MAX, XHIGH, MEDIUM, LOW
.build())
.addUserMessage("...")
.build();
Message response = client.messages().create(params);
IO.println(response);
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 16000,
messages: [['role' => 'user', 'content' => '...']],
model: 'claude-opus-5-5',
thinking: ['type' => 'adaptive'],
outputConfig: ['effort' => 'high'], // or 'max', 'xhigh', 'medium', 'low'
);
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: {
type: "adaptive"
},
output_config: {
effort: "high" # or "max", "xhigh", "medium", "low"
},
messages: [
{ role: "user", content: "..." }
]
)
```
적응형 사고는 프롬프팅과 [effort 매개변수](https://platform.claude.com/docs/ko/build-with-claude/effort)를 통해 조정할 수 있습니다. effort 매개변수는 모델의 추론량을 제어하는 방법으로서 "thinking budget"(사고 예산)을 대체합니다. `budget_tokens` 값을 그대로 변환하기보다는 자체 평가(eval)에서 effort 스윕을 실행하세요. [effort 수준 표](https://platform.claude.com/docs/ko/build-with-claude/effort#effort-levels)는 각 수준을 언제 사용해야 하는지 설명하며, [Claude Opus 5.5 권장 effort 수준](https://platform.claude.com/docs/ko/build-with-claude/effort#recommended-effort-levels-for-claude-opus-5-5)에서 이 모델을 다룹니다.
2. **샘플링 매개변수 제거:** Claude Opus 5.5를 포함한 Claude Opus 4.7 이상 모델에서 `temperature`, `top_p`, `top_k`를 기본값이 아닌 값으로 설정하면 400 오류가 반환됩니다. Python SDK(v1.0 이상)는 이 매개변수들을 정의하지 않으며, 이를 전달하면 `TypeError`가 발생합니다. 가장 안전한 마이그레이션 방법은 요청 페이로드에서 이 매개변수들을 완전히 생략하는 것입니다. Claude Opus 5.5에서 모델 동작을 안내하는 권장 방법은 프롬프팅입니다. 결정론적 출력을 위해 `temperature = 0`을 사용하고 있었다면, 이전 모델에서도 이 설정이 동일한 출력을 보장한 적은 없다는 점에 유의하세요.
3. **사고 내용 기본 생략:** Claude Opus 4.7 이상 모델에서도 사고 블록은 여전히 응답 스트림에 나타나지만, 명시적으로 옵트인하지 않는 한 `thinking` 필드는 비어 있습니다. 이는 요약된 사고 텍스트를 반환하는 것이 기본값이었던 Claude Opus 4.6과 비교해 별도의 알림 없이 적용되는 변경 사항입니다. 이를 복원하려면 [모든 응답에서 사고 처리하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#thinking-in-every-response)의 4번 항목을 참조하세요.
4. **토큰 계산 방식 업데이트:** Claude Opus 4.7은 새로운 "tokenizer"(토크나이저)를 도입했으며, Claude Opus 5.5를 포함한 이후 Opus 모델도 이를 사용합니다. 이 토크나이저는 광범위한 작업에서 성능 향상에 기여하며, Claude Opus 4.7 이전 모델과 비교해 텍스트를 처리할 때 약 1배에서 1.35배의 토큰을 사용할 수 있습니다(콘텐츠에 따라 다르며 최대 약 35% 증가).
[`/v1/messages/count_tokens`](https://platform.claude.com/docs/ko/build-with-claude/token-counting)는 Claude Opus 5.5에 대해 Claude Opus 4.6과 다른 토큰 수를 반환합니다. 토큰 효율성은 워크로드 형태에 따라 달라질 수 있습니다.
"compaction"(압축) 트리거를 포함하여 추가 여유 공간을 확보하도록 `max_tokens` 매개변수를 업데이트하고, 클라이언트 측에서 토큰을 추정하거나 고정된 토큰 대 문자 비율을 가정하는 모든 코드 경로를 다시 테스트하세요. [토큰 계산 엔드포인트](https://platform.claude.com/docs/ko/build-with-claude/token-counting)를 사용하여 확인하세요. 프롬프팅 조정, [`task_budget`](https://platform.claude.com/docs/ko/build-with-claude/task-budgets), [`effort`](https://platform.claude.com/docs/ko/build-with-claude/effort)는 비용 제어에 도움이 될 수 있으며, 이러한 제어 수단은 모델 지능과 트레이드오프 관계에 있을 수 있습니다.
5. **프리필 제거(Claude Opus 4.6에서 이미 적용됨):** Claude Opus 5.5를 포함한 Claude Opus 4.6 이상 Opus 모델에서 어시스턴트 메시지를 프리필하면 400 오류가 반환되므로, 이는 Claude Opus 4.5 이하에서 마이그레이션하는 경우에만 변경 사항입니다. 대신 [구조화된 출력](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs) 또는 시스템 프롬프트 지침을 사용하세요. Amazon Bedrock에서는 Claude Opus 5.5에 구조화된 출력을 사용할 수 없으므로, 그곳에서는 시스템 프롬프트 지침을 사용하세요.
### 동작 변경 사항
Claude Opus 4.7은 API 호환성을 깨는 변경은 아니지만 Claude Opus 4.6과 다른 동작상의 차이를 도입했습니다. 다음 세 가지는 코드나 스캐폴딩에 영향을 줍니다:
1. **에이전트 트레이스의 기본 제공 진행 상황 업데이트:** Claude Opus 4.7은 긴 에이전트 트레이스 전반에 걸쳐 사용자에게 더 규칙적이고 품질 높은 업데이트를 제공합니다. 중간 상태 메시지를 강제하기 위한 스캐폴딩("도구 호출 3회마다 진행 상황을 요약하세요")을 추가했다면 제거해 보세요. Claude Opus 5.5에서는 이러한 업데이트가 `thinking` 블록으로 전달되며, 기본 `thinking.display` 설정에서는 비어 있습니다. 이를 받으려면 [도구 호출 사이의 텍스트가 사고 블록으로 반환됨](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#text-between-tool-calls)를 참조하세요. 업데이트의 길이와 내용을 조정하려면 [사용자 대상 진행 상황 업데이트](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates)를 참조하세요.
2. **실시간 사이버 보안 안전장치:** Claude Opus 4.7에 새로 추가된 기능으로, 금지되었거나 고위험 주제와 관련된 요청은 거부될 수 있습니다. 침투 테스트, 취약점 연구, 레드팀 활동과 같은 정당한 보안 작업의 경우 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet)에 신청하여 제한 완화를 요청하세요. 신청 경로는 Claude에 액세스하는 방식에 따라 다릅니다.
3. **고해상도 이미지 지원:** Claude Opus 4.7은 고해상도 이미지를 지원하는 최초의 Claude 모델입니다. 최대 이미지 해상도는 긴 변 기준 2,576픽셀로, 이전 모델의 1,568픽셀에서 증가했습니다. 이를 통해 비전 중심 워크로드에서 성능이 향상되며, 특히 "computer use"(컴퓨터 사용), 스크린샷 이해, 문서 분석에 유용합니다.
고해상도 지원은 자동이며 베타 헤더나 클라이언트 측 옵트인이 필요하지 않습니다. 계획해야 할 두 가지 사항:
* 전체 해상도 이미지는 이전 모델보다 최대 약 3배 더 많은 이미지 토큰을 사용할 수 있습니다(이미지당 최대 4,784 토큰, 이전 상한인 이미지당 약 1,600 토큰과 비교). 이미지 중심 워크로드에 대해 `max_tokens`와 비용 예상을 재조정하거나, 추가 충실도가 필요하지 않다면 전송 전에 다운샘플링하세요.
* 모델이 반환하는 포인팅 및 바운딩 박스 좌표는 Claude Opus 4.7에서 실제 이미지 픽셀과 1:1이므로 스케일 팩터 변환이 필요하지 않습니다.
자세한 내용은 [Claude Opus 4.7의 고해상도 이미지 지원](https://platform.claude.com/docs/ko/build-with-claude/vision#high-resolution-image-support-on-claude-opus-4-7)을 참조하세요.
프롬프트 측면의 차이점은 [Claude Opus 5.5 프롬프팅](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/prompting-claude-opus-5-5) 및 [프롬프팅 모범 사례](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/claude-prompting-best-practices)를 참조하세요.
### Claude Opus 4.5 이하에서 마이그레이션
Claude Opus 4.5, Claude Opus 4.1 또는 그 이전 모델에서 Claude Opus 5.5로 직접 마이그레이션하는 경우 이 페이지를 처음부터 읽으세요. 먼저 앞의 모든 섹션을 페이지 순서대로 진행하세요. 그런 다음 이 섹션 앞부분의 [Claude Opus 4.6에서 마이그레이션하기 위한 호환성이 깨지는 변경 사항](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#opus-46-breaking-changes)을 진행하세요. 그다음 Claude Opus 4.5와 Claude Opus 4.7 사이에 적용된 다음 누적 변경 사항을 적용하세요. Claude Opus 4.1 이하를 사용 중이라면 이 하위 섹션 이후 [Claude 4.1 이하에서 마이그레이션](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-4-1-or-earlier)으로 계속 진행하세요.
#### 호환성이 깨지는 변경 사항
1. **프리필 제거**는 [Claude Opus 4.6에서 마이그레이션하기 위한 호환성이 깨지는 변경 사항](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#opus-46-breaking-changes)에서 다룹니다.
2. **도구 매개변수 인용:** Claude Opus 4.6 이상 모델은 도구 호출 인수에서 약간 다른 JSON 문자열 이스케이프를 생성할 수 있습니다(예: 유니코드 이스케이프 또는 슬래시 이스케이프의 다른 처리). 도구 호출 `input`을 JSON 파서를 사용하지 않고 원시 문자열로 파싱하는 경우 파싱 로직을 확인하세요. 표준 JSON 파서(`json.loads()` 또는 `JSON.parse()` 등)는 이러한 차이를 자동으로 처리합니다.
#### 권장 변경 사항
첫 번째 항목은 Claude Opus 5.5에서 필수이며, 나머지는 권장 사항입니다.
1. **적응형 사고로 마이그레이션(필수):** `thinking: {"type": "enabled", "budget_tokens": N}`은 Claude Opus 4.7 이상 모델에서 400 오류를 반환합니다. 변경 전후 예시는 [Claude Opus 4.6에서 마이그레이션할 때의 호환성이 깨지는 변경 사항](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#opus-46-breaking-changes)의 1번 항목에 있습니다. 이 마이그레이션은 또한 `client.beta.messages.create()` (csharp: `client.Beta.Messages.Create()`; go: `client.Beta.Messages.New()`; java: `client.beta().messages().create()`; php: `$client->beta->messages->create()`; cli: `ant beta:messages create`)에서 `client.messages.create()` (csharp: `client.Messages.Create()`; go: `client.Messages.New()`; java: `client.messages().create()`; php: `$client->messages->create()`; cli: `ant messages create`)로 이동합니다. 적응형 사고와 effort는 베타 SDK 네임스페이스나 베타 헤더가 필요하지 않습니다.
2. **effort 베타 헤더 제거:** effort 매개변수는 베타 헤더가 필요하지 않습니다. 요청에서 `effort-2025-11-24` 베타를 제거하세요.
3. **세분화된 도구 스트리밍 베타 헤더 제거:** 세분화된 도구 스트리밍은 베타 헤더가 필요하지 않습니다. 요청에서 `fine-grained-tool-streaming-2025-05-14` 베타를 제거하세요.
4. **인터리브 사고 베타 헤더 제거:** 적응형 사고를 사용하면 적응형 사고를 지원하는 모든 모델에서 인터리브 사고가 자동으로 적용됩니다. 요청에서 `interleaved-thinking-2025-05-14` 베타를 제거하세요.
5. **output\_config.format으로 마이그레이션:** 구조화된 출력을 사용하는 경우 `output_format={...}`를 `output_config={"format": {...}}`로 업데이트하세요. `output_format` 매개변수는 지원 중단되었으며 향후 제거될 예정입니다. 그래도 이 매개변수를 사용하려면 `structured-outputs-2025-11-13` 베타 헤더를 추가하세요. 이 헤더가 없으면 API가 400 오류를 반환합니다. Python SDK(v1.0 이상)는 `client.beta.messages.create()` 또는 `count_tokens()`에서 `output_format={...}`를 허용하지 않습니다. `parse()` 및 `stream()` 헬퍼의 `output_format=Model` 인수는 변경되지 않았습니다.
### Claude 4.1 이하에서 마이그레이션
Claude Opus 4.1 이하 모델에서 Claude Opus 5.5로 직접 마이그레이션하는 경우, 먼저 [Claude Opus 4.5 이하에서 마이그레이션](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-45)의 모든 내용을 적용하세요. 해당 하위 섹션은 앞의 모든 섹션부터 시작하므로, 사실상 이 페이지를 처음부터 읽게 됩니다. 그런 다음 이 하위 섹션의 추가 변경 사항을 적용하세요.
#### 추가 호환성이 깨지는 변경 사항
1. **샘플링 매개변수 제거:** [샘플링 매개변수 제거](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#opus-46-breaking-changes)에서 다룹니다.
2. **도구 버전 업데이트**
이는 Claude 3.x 모델에서 마이그레이션할 때 호환성이 깨지는 변경 사항입니다.
현재 도구 버전으로 업데이트하세요. `undo_edit` 명령을 사용하는 코드를 모두 제거하세요.
```python Python
# 변경 전
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
# 변경 후
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
```
```typescript TypeScript
// 변경 전
const legacyTools = [{ type: "text_editor_20250124", name: "str_replace_editor" }];
// 변경 후
const tools = [{ type: "text_editor_20250728", name: "str_replace_based_edit_tool" }];
```
```csharp C#
var parameters = new MessageCreateParams
{
// 변경 전: {"type": "text_editor_20250124", "name": "str_replace_editor"}
// 변경 후:
Tools = [new ToolTextEditor20250728()],
// ...
};
```
```go Go
params := anthropic.MessageNewParams{
// 변경 전: {"type": "text_editor_20250124", "name": "str_replace_editor"}
// 변경 후:
Tools: []anthropic.ToolUnionParam{
{OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
},
// ...
}
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
// 변경 전: {"type": "text_editor_20250124", "name": "str_replace_editor"}
// 변경 후:
.addTool(ToolTextEditor20250728.builder().build())
// ...
.build();
```
```php PHP
$message = $client->messages->create(
// 변경 전: ['type' => 'text_editor_20250124', 'name' => 'str_replace_editor']
// 변경 후:
tools: [new ToolTextEditor20250728()],
// ...
);
```
```ruby Ruby
# 변경 전
legacy_tools = [{type: "text_editor_20250124", name: "str_replace_editor"}]
# 변경 후
tools = [{type: "text_editor_20250728", name: "str_replace_based_edit_tool"}]
```
* **텍스트 편집기:** `text_editor_20250728` 및 `str_replace_based_edit_tool`을 사용하세요. 자세한 내용은 [텍스트 편집기 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/text-editor-tool) 문서를 참조하세요.
* **코드 실행:** `code_execution_20260521`로 업그레이드하세요. 마이그레이션 지침은 [코드 실행 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version) 문서를 참조하세요.
* **컴퓨터 사용:** Claude API와 Google Cloud에서 Claude Opus 5.5는 컴퓨터 사용을 `computer_toolset_20260801` 도구 세트로만 허용하며, 이전의 `computer_20250124` 및 `computer_20251124` 도구는 해당 플랫폼에서 거부됩니다. [컴퓨터 사용 관련 호환성이 깨지는 변경 사항](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#computer-use-toolset)을 참조하세요.
3. **`refusal` 중지 사유 처리**
[`refusal` 중지 사유를 처리](https://platform.claude.com/docs/ko/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)하도록 애플리케이션을 업데이트하세요:
```python Python
response = client.messages.create(...)
if response.stop_reason == "refusal":
# 거부를 적절히 처리합니다
pass
```
```typescript TypeScript
const response = await client.messages.create(/* ... */);
if (response.stop_reason === "refusal") {
// 거부를 적절히 처리합니다
}
```
```csharp C#
var response = await client.Messages.Create(...);
if (response.StopReason?.Value() == StopReason.Refusal)
{
// 거부를 적절히 처리합니다
}
```
```go Go
response, _ := client.Messages.New(ctx, params) // your existing request
if response.StopReason == anthropic.StopReasonRefusal {
// 거부를 적절히 처리합니다
}
```
```java Java
Message response = client.messages().create(...);
StopReason reason = response.stopReason().orElse(StopReason.END_TURN);
if (reason.equals(StopReason.REFUSAL)) {
// 거부를 적절히 처리합니다
}
```
```php PHP
$response = $client->messages->create(...);
if ($response->stopReason === 'refusal') {
// 거부를 적절히 처리합니다
}
```
```ruby Ruby
response = client.messages.create(...)
if response.stop_reason == :refusal
# 거부를 적절히 처리합니다
end
```
4. **`model_context_window_exceeded` 중지 사유 처리**
Claude 4.5 이상 모델은 요청된 `max_tokens` 한도가 아니라 컨텍스트 윈도우 한도에 도달하여 생성이 중지되면 `model_context_window_exceeded` 중지 사유를 반환합니다. 이 새로운 중지 사유를 처리하도록 애플리케이션을 업데이트하세요:
```python Python
response = client.messages.create(...)
if response.stop_reason == "model_context_window_exceeded":
# 컨텍스트 윈도우 한도를 적절히 처리합니다
pass
```
```typescript TypeScript
const response = await client.messages.create(/* ... */);
if (response.stop_reason === "model_context_window_exceeded") {
// 컨텍스트 윈도우 한도를 적절히 처리합니다
}
```
```csharp C#
var response = await client.Messages.Create(...);
if (response.StopReason?.Raw() == "model_context_window_exceeded")
{
// 컨텍스트 윈도우 한도를 적절히 처리합니다
}
```
```go Go
response, _ := client.Messages.New(ctx, params) // your existing request
if response.StopReason == "model_context_window_exceeded" {
// 컨텍스트 윈도우 한도를 적절히 처리합니다
}
```
```java Java
Message response = client.messages().create(...);
StopReason reason = response.stopReason().orElse(StopReason.END_TURN);
if (reason.equals(StopReason.of("model_context_window_exceeded"))) {
// 컨텍스트 윈도우 한도를 적절히 처리합니다
}
```
```php PHP
$response = $client->messages->create(...);
if ($response->stopReason === 'model_context_window_exceeded') {
// 컨텍스트 윈도우 한도를 적절히 처리합니다
}
```
```ruby Ruby
response = client.messages.create(...)
if response.stop_reason == :model_context_window_exceeded
# 컨텍스트 윈도우 한도를 적절히 처리합니다
end
```
5. **도구 매개변수 처리 확인 (후행 줄바꿈)**
Claude 4.5 이상 모델은 이전에는 제거되던 도구 호출 문자열 매개변수의 후행 줄바꿈을 유지합니다. 도구가 도구 호출 매개변수에 대한 정확한 문자열 일치에 의존하는 경우, 로직이 후행 줄바꿈을 올바르게 처리하는지 확인하세요.
6. **동작 변경 사항에 맞춰 프롬프트 업데이트**
Claude 4 이상 모델은 더 간결하고 직접적인 커뮤니케이션 스타일을 가지며 명시적인 지시가 필요합니다. 최적화 지침은 [프롬프팅 모범 사례](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/claude-prompting-best-practices)를 검토하세요.
#### 추가 권장 변경 사항
* **레거시 베타 헤더 제거:** `token-efficient-tools-2025-02-19` 및 `output-128k-2025-02-19`를 제거하세요. 모든 Claude 4 이상 모델에는 토큰 효율적인 도구 사용이 기본 제공되며, 이러한 헤더는 아무런 효과가 없습니다.
## Claude Sonnet 5에서 Claude Opus 5.5로 마이그레이션하기
[Claude Opus 5.5에 대한 모든 요청이 충족해야 하는 사항](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#request-requirements), [모든 응답에서 사고 처리하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#thinking-in-every-response), [Claude Opus 5에서 Claude Opus 5.5로 마이그레이션하기](https://platform.claude.com/docs/ko/models/opus-5-5/migration-guide#migrating-from-claude-opus-5)를 진행하세요. 교체할 모델 ID로 `claude-sonnet-5`를 사용하세요. 마지막 섹션은 Claude Sonnet 5의 코드에 그대로 적용됩니다. Claude Sonnet 5는 Claude Opus 5와 마찬가지로 다음과 같기 때문입니다:
* 기본적으로 사고가 켜진 상태로 실행되며 `thinking: {"type": "disabled"}`를 허용합니다(Claude Sonnet 5의 경우 모든 effort 수준에서 허용).
* 강제 도구 선택과 `computer_20251124` 도구를 허용합니다.
* 도구 호출 사이의 텍스트를 `text` 블록으로 반환합니다.
* 기본 effort가 `high`입니다.
수동 확장 사고, 기본값이 아닌 샘플링 매개변수, 어시스턴트 프리필은 두 모델 모두에서 400 오류를 반환하므로 이 부분은 달라지지 않습니다. Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 섹션의 필수 변경 사항은 어느 것도 해당되지 않습니다.
### 변경된 사항
1. **대화 중간 시스템 메시지:** Claude API, Amazon Bedrock, Google Cloud에서 Claude Opus 5.5는 `messages` 배열에서 사용자 턴 바로 뒤에 오는 `role: "system"` 메시지를 허용합니다([배치 규칙](https://platform.claude.com/docs/ko/build-with-claude/mid-conversation-system-messages#limitations) 적용). 이 기능은 Claude Sonnet 5에서는 사용할 수 없습니다. 지침을 업데이트하기 위해 전체 메시지 기록을 다시 구성하는 코드 경로를 유지 관리하고 있다면, 이를 단순화하고 이전 턴에서 [프롬프트 캐싱](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching) 적중을 유지할 수 있습니다.
2. **더 낮은 프롬프트 캐싱 최소 길이:** Claude Opus 5.5의 최소 캐시 가능 프롬프트 길이는 512 토큰으로, Claude Sonnet 5의 1,024 토큰보다 낮아졌습니다. Claude Sonnet 5에서 캐시하기에 너무 짧았던 프롬프트도 코드 변경 없이 캐시 항목을 생성할 수 있습니다. 모델별 최소 길이는 [프롬프트 캐싱](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching#cache-limitations)을 참조하세요.