---
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를 활성화하기 위한 안내에는 오류를 반환하는 요청 설정, 모든 응답의 사고 블록, 그리고 각 시작 모델별 체크리스트가 포함되어 있습니다.
---

<Note>
  이 가이드는 [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)를 사용하는 경우, 모델 이름을 업데이트하는 것 외에는 변경이 필요하지 않습니다.
</Note>

Claude Code가 코드를 대신 마이그레이션하도록 하세요

```text
/claude-api migrate 이 프로젝트를 claude-opus-5-5 모델로 마이그레이션해 줘
```

이 페이지에서는 [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로, $5 / $25 USD와 비교됩니다. [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, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed), Microsoft Foundry에서는 해당 플랫폼의 모델 ID를 사용하세요. [사용 가능 여부](https://platform.claude.com/docs/ko/models/opus-5-5/whats-new-opus-5-5#availability)를 참조하세요.
* **사고:** `thinking` 필드를 보내지 않거나, 이와 동일한 `thinking: {"type": "adaptive"}`를 보내세요. [적응형 사고](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 매개변수](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`를 미리 채운 assistant 턴으로 끝내지 마세요. 거부됩니다. 대신 [구조화된 출력](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs) 또는 시스템 프롬프트 지침을 사용하세요.
* **컴퓨터 사용:** 컴퓨터 사용을 `computer_toolset_20260801` 도구 세트로 선언하세요. Amazon Bedrock에서는 `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)가 기본값이며, 이전 모델용으로 보낸 헤더는 효과가 없습니다.

다음 요청은 목록의 모든 항목을 충족합니다. 노력 수준이 설정되어 있고 `thinking` 필드가 없습니다. 예제에서 텍스트를 출력하는 경우, `thinking` 블록이 먼저 오기 때문에 텍스트 블록을 유형으로 찾습니다.

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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.type === "text");
  console.log(textBlock?.text);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [
          new UserMessageParam
          {
              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: Anthropic::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
  ```
</CodeGroup>

## 모든 응답에서 사고 처리하기

사고는 모든 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)를 참조하세요. 사고에 사용하는 토큰을 줄이려면 [노력 수준](https://platform.claude.com/docs/ko/build-with-claude/effort)을 낮추세요. `xhigh` 또는 `max` 노력 수준으로 실행하는 경우, 모델이 사고하고 행동할 여유가 있도록 `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"`로 설정하세요:

   <CodeGroup exclude="shell">
     ```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"
     }
     ```
   </CodeGroup>

   제품이 사용자에게 추론 과정을 스트리밍하는 경우, 기본값에서는 출력이 시작되기 전에 긴 대기 시간으로 나타납니다. 사고 중에 진행 상황이 보이도록 하려면 `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`를 명시적으로 설정하세요. Claude Opus 5의 기본값은 `high`이지만, 여기서는 기본값이 `medium`입니다.
* `tool_choice` 유형 `any`와 `tool`을 `auto`와 엄격한 도구 사용 또는 구조화된 출력 조합으로 대체하세요.
* 이전 컴퓨터 사용 도구 버전을 사용하는 경우, 대신 `computer_toolset_20260801`(베타 헤더 없음)을 선언하고 도구 세트에 맞게 에이전트 루프를 업데이트하세요. Amazon Bedrock에서는 `computer_20251124`도 작동합니다.
* 라우터나 폴백이 대화를 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와 Claude Models on Google Cloud (Google managed)에서는 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) 약정이 있는 경우, 용량을 별도로 계획하세요. Priority Tier는 Claude Opus 5.5에서 지원되지 않습니다.
* `xhigh` 또는 `max` 노력 수준으로 실행하는 경우, 시작점으로 `max_tokens`를 최소 64k로 높이세요.
* 에이전트 워크로드의 경우, [작업 예산](https://platform.claude.com/docs/ko/build-with-claude/task-budgets)(베타)과 대화 중 도구 변경(베타)을 고려하세요.

### Claude Opus 4.7 이하

* 이전 모델에 맞게 조정된 설정을 그대로 가져오지 말고, 자체 평가에서 [노력 수준](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 이하

* 어시스턴트 메시지 prefill을 모두 제거하세요. 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-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, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed), 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` 필드를 제거하고 [노력 수준](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 오류로 거부합니다:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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 UserMessageParam { 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: "..." }]
  )
  ```
</CodeGroup>

변경 후:

<CodeGroup>
  ```bash cURL
  # 사고는 항상 켜져 있으며, 노력 수준(effort)으로 제어합니다
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 16000,
      "output_config": {"effort": "low"},
      "messages": [{"role": "user", "content": "..."}]
    }'
  ```

  ```bash CLI
  # 사고는 항상 켜져 있으며, 노력 수준(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 UserMessageParam { 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)
      // 사고는 항상 켜져 있으며, 노력 수준(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,
      // 사고는 항상 켜져 있으며, 노력 수준(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,
    # 사고는 항상 켜져 있으며, 노력 수준(effort)으로 제어합니다
    output_config: { effort: Anthropic::OutputConfig::Effort::LOW },
    messages: [{ role: "user", content: "..." }]
  )
  ```
</CodeGroup>

#### 강제 도구 사용이 지원되지 않음

`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`를 사용하고, 도구가 적용되는 경우를 프롬프트에 명시하세요. Strict tool use는 JSON Schema의 일부만 허용하므로, `strict: true`를 추가하기 전에 각 도구의 `input_schema`를 확인하세요. 스키마의 모든 객체는 `additionalProperties: false`를 설정해야 합니다. [JSON Schema 제한 사항](https://platform.claude.com/docs/ko/build-with-claude/structured-outputs#json-schema-limitations)을 참조하세요. [강제 도구 사용이 지원되지 않음](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 오류로 거부합니다:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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 UserMessageParam { 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?" }]
  )
  ```
</CodeGroup>

변경 후:

<CodeGroup>
  ```bash cURL
  # strict 도구 사용: 모든 호출이 도구의 input_schema와 일치합니다
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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 도구 사용: 모든 호출이 도구의 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 도구 사용: 모든 호출이 도구의 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 UserMessageParam { Content = "What's the weather in Paris? Use the get_weather tool." },
      ],
  });
  ```

  ```go Go
  // strict 도구 사용: 모든 호출이 도구의 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 도구 사용: 모든 호출이 도구의 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 도구 사용: 모든 호출이 도구의 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 도구 사용: 모든 호출이 도구의 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." }
    ]
  )
  ```
</CodeGroup>

#### 사고 블록은 모델과 대화에 연결됨

Claude API에서 Claude Opus 5.5의 사고 블록을 읽는 모델은 Claude Fable 5.1과 Claude Mythos 5.1뿐이며, 다른 모델은 읽지 않습니다. 대화를 Claude Opus 5.5에서 다른 모델로 옮기는 라우터나 폴백은 해당 턴을 이 블록 없이 실행합니다. 반대 방향으로, Claude Opus 5.5는 Claude Opus 5와 이전 Opus, Sonnet, Haiku 모델의 사고 블록을 읽습니다. Claude API와 Claude Models on Google Cloud (Google managed)에서는 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는 이미 이렇게 하고 있습니다. 2026년 8월 31일 00:00 UTC 당일 또는 그 이후에 생성된 계정에서는 Claude API 및 클라우드 플랫폼에서 이러한 편집 후 사고 블록을 재전송하면서 `thinking.block_binding.prefix_mismatch_behavior`를 설정하지 않은 요청이 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)를 참조하세요.

#### 일부 컴퓨터 사용 도구 버전은 지원되지 않습니다

Claude Opus 5.5는 `computer_toolset_20260801` 도구 세트를 통해 컴퓨터 사용을 지원합니다. Amazon Bedrock에서는 Claude Opus 5.5가 `computer-use-2025-11-24` 베타 헤더와 함께 `computer_20251124` 도구도 허용합니다. Claude Opus 5.5는 Claude API의 `computer_20251124`처럼 허용하지 않는 컴퓨터 사용 도구 버전에 대해 400 오류를 반환합니다. `computer_20250124`는 어떤 플랫폼에서도 허용하지 않습니다. Claude API에서 오류 메시지는 `'claude-opus-5-5' does not support tool types: computer_20251124.`로 시작하며, 이어서 모델이 허용하는 도구 유형을 나열합니다.

도구 세트를 사용하는 통합은 변경이 필요하지 않습니다. `computer_20251124` 통합을 도구 세트로 옮기려면 베타 헤더를 제거하고 `name`이나 디스플레이 크기 없이 `computer_toolset_20260801` 항목을 보내세요. 에이전트 루프에서는 한 턴의 모든 멤버 `tool_use` 블록을 처리하고 모든 결과에 `toolset_name`을 그대로 반환하세요. 액션은 `input.action`이 아니라 각 블록의 `name`에서 읽으세요. [`computer_20251124`에서 마이그레이션](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124)에 에이전트 루프 변경 사항이 나열되어 있습니다.

변경 전. Claude Opus 5는 이 요청을 허용하지만, Claude Opus 5.5는 Claude API에서 400 오류와 함께 이를 거부합니다:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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 BetaUserMessageParam { 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." }]
  )
  ```
</CodeGroup>

변경 후:

<CodeGroup>
  ```bash cURL
  # 베타 헤더 불필요, 도구 세트 항목은 이름이나 디스플레이 크기를 받지 않습니다
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -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
  # 베타 헤더 없음. 도구 세트 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
  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,
      # 베타 헤더 없음. 도구 세트 항목은 이름이나 디스플레이 크기를 받지 않습니다
      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,
    // 베타 헤더 없음. 도구 세트 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
    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,
      // 베타 헤더 없음. 도구 세트 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
      Tools = [new ComputerToolset20260801()],
      Messages = [new UserMessageParam { Content = "Open the display settings." }],
  });
  ```

  ```go Go
  client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	// 베타 헤더 없음. 도구 세트 항목은 이름이나 디스플레이 크기를 받지 않습니다
  	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)
      // 베타 헤더 없음. 도구 세트 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
      .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,
      // 베타 헤더 없음; 도구 세트 항목은 이름이나 디스플레이 크기를 받지 않습니다
      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,
    # 베타 헤더 없음. 도구 세트 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
    tools: [Anthropic::ComputerToolset20260801.new],
    messages: [{ role: "user", content: "Open the display settings." }]
  )
  ```
</CodeGroup>

### 도구 호출 사이의 텍스트는 사고 블록으로 반환됩니다

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. **노력 수준 스윕을 다시 실행하세요.** 노력 수준은 Claude Opus 5.5에서 유일한 사고 제어 수단이며, 기본값은 `medium`입니다(Claude Opus 5의 기본값은 `high`). 따라서 `effort`를 생략한 요청은 이제 `medium`으로 실행됩니다. 품질이 유지되는 곳에서는 수준을 낮추고, 가장 까다로운 작업에서는 수준을 높이세요. [노력 수준](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` 블록으로 반환합니다.
* 기본 노력 수준이 `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. **작업 예산 고려(베타):** 에이전트 워크로드의 경우, [“task budget”(작업 예산)](https://platform.claude.com/docs/ko/build-with-claude/task-budgets)은 전체 에이전트 루프에서 사용할 수 있는 토큰 수를 모델에 알려줍니다. 작업 예산을 사용하려면 `task-budgets-2026-03-13` 베타 헤더가 필요합니다.

2. **대화 중 도구 변경 고려(베타):** “Mid-conversation tool changes”(대화 중 도구 변경)를 사용하면 이전 턴의 [“prompt caching”(프롬프트 캐싱)](https://platform.claude.com/docs/ko/build-with-claude/prompt-caching) 적중을 무효화하지 않고 대화 턴 사이에 도구를 추가하거나 제거할 수 있습니다. `tools` 배열 자체를 변경하면 캐시된 접두사가 무효화됩니다. Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed)에서는 `inline-tools-2026-09-15` 베타 헤더를 보내세요. `mid-conversation-tool-changes-2026-07-01` 헤더는 Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed)에서 참조로 도구 이름을 지정하는 변경에 대해 작동합니다.

## 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.8과 마찬가지로 Claude Opus 4.7은 `thinking: {"type": "disabled"}`, 강제 도구 선택, `computer_20251124` 도구를 허용합니다. 기본 노력 수준은 `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”(노력) 수준 재조정:** 각 effort 수준의 토큰 할당이 Claude Opus 4.7에 비해 Claude Opus 5.5에서 변경됩니다. 기본값은 `medium`이며, Claude Opus 4.7의 기본값은 `high`입니다. Claude Opus 4.7에 맞춰 조정된 설정을 그대로 가져오기보다는 자체 평가에서 effort를 새로 비교 테스트하세요. [노력 수준](https://platform.claude.com/docs/ko/build-with-claude/effort)을 참조하세요.

2. **1M 컨텍스트 윈도우가 기본값:** Claude Opus 5.5는 베타 헤더 없이 기본적으로 전체 1M 토큰 [“context window”(컨텍스트 윈도우)](https://platform.claude.com/docs/ko/build-with-claude/context-windows)를 제공합니다. 이전 모델과의 호환성을 위해 클라이언트가 컨텍스트 윈도우 베타 헤더를 전달하고 있다면 이를 제거하세요.

3. **대화 중 시스템 메시지:** Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed)에서 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. **빠른 모드:** Claude Opus 5.5는 Claude API에서 [“fast mode”(빠른 모드)](https://platform.claude.com/docs/ko/build-with-claude/fast-mode)를 지원합니다. 빠른 모드는 Claude Opus 4.7에서는 사용할 수 없으며, `speed: "fast"`를 포함한 요청은 오류를 반환합니다. 요청에 `speed: "fast"`를 설정하세요. Claude Opus 5.5에는 베타 헤더가 필요하지 않습니다.

6. **컴퓨터 사용 도구 세트 및 브라우저 사용 도구:** Claude Opus 5.5는 [“computer use”(컴퓨터 사용)](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool)를 `computer_toolset_20260801` 도구 세트로 지원하며, 웹 페이지 내 작업을 위한 [“browser use tool”(브라우저 사용 도구)](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/browser-use-tool)도 지원합니다. Claude Opus 4.7은 둘 다 지원하지 않습니다. `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.7과 마찬가지로 Claude Opus 4.6은 `thinking: {"type": "disabled"}`, 강제 도구 선택(forced tool choice), `computer_20251124` 도구를 허용합니다. 기본 노력 수준은 `high`이며, 요청하지 않는 한 사고 없이 실행됩니다. Claude Opus 4.5 및 이전 Opus 모델도 `thinking: {"type": "disabled"}`와 강제 도구 선택을 허용하고 요청하지 않는 한 사고 없이 실행되므로, 이 섹션들은 해당 모델에도 적용됩니다.

이 섹션은 Claude Opus 4.7에서 변경된 사항을 추가로 다루며, 교체할 모델 ID는 `claude-opus-4-6`입니다. 두 개의 하위 섹션은 [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"}`)로 전환하고 [노력 수준 매개변수](https://platform.claude.com/docs/ko/build-with-claude/effort)를 사용하여 사고 깊이를 제어하세요. Claude Opus 5.5에서는 적응형 사고가 항상 켜져 있습니다. `thinking: {"type": "adaptive"}`는 유효하며 `thinking` 필드를 완전히 생략하는 것과 동일합니다.

   이전(Claude Opus 4.6):

   <CodeGroup>
     ```bash cURL
     curl https://api.anthropic.com/v1/messages \
       -H "x-api-key: $ANTHROPIC_API_KEY" \
       -H "anthropic-version: 2026-10-21" \
       -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 UserMessageParam { 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: "..." }
       ]
     )
     ```
   </CodeGroup>

   이후(Claude Opus 5.5), 모델 ID, `thinking`, `output_config` 줄이 다릅니다:

   <CodeGroup>
     ```bash cURL
     curl https://api.anthropic.com/v1/messages \
       -H "x-api-key: $ANTHROPIC_API_KEY" \
       -H "anthropic-version: 2026-10-21" \
       -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 UserMessageParam { 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: 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: Anthropic::Model::CLAUDE_OPUS_5_5,
       max_tokens: 16000,
       thinking: {
         type: "adaptive"
       },
       output_config: {
         effort: "high" # or "max", "xhigh", "medium", "low"
       },
       messages: [
         { role: "user", content: "..." }
       ]
     )
     ```
   </CodeGroup>

   적응형 사고는 프롬프트와 [노력 수준 매개변수](https://platform.claude.com/docs/ko/build-with-claude/effort)를 통해 조정할 수 있으며, 노력 수준 매개변수는 모델이 추론하는 양을 제어하는 방식으로서 사고 예산을 대체합니다. `budget_tokens` 값을 변환하는 대신 자체 평가에서 노력 수준 스윕(effort sweep)을 실행하세요. [노력 수준 표](https://platform.claude.com/docs/ko/build-with-claude/effort#effort-levels)는 각 수준을 언제 사용해야 하는지 설명하며, [Claude Opus 5.5에 권장되는 노력 수준](https://platform.claude.com/docs/ko/build-with-claude/effort#recommended-effort-levels-for-claude-opus-5-5)은 이 모델에 대해 다룹니다.

2. **샘플링 매개변수 제거:** `temperature`, `top_p`, `top_k`를 생략하세요. 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은 새로운 토크나이저를 도입했으며, 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)이나 시스템 프롬프트 지침을 사용하세요.

### 동작 변경 사항

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픽셀에서 증가했습니다. 이를 통해 비전 중심 워크로드에서 성능이 향상되며, 특히 컴퓨터 사용, 스크린샷 이해, 문서 분석에 유용합니다.

   고해상도 지원은 자동으로 적용되며 베타 헤더나 클라이언트 측 옵트인이 필요하지 않습니다. 대비해야 할 두 가지 사항은 다음과 같습니다:

   * 전체 해상도 이미지는 이전 모델보다 최대 약 3배 많은 이미지 토큰을 사용할 수 있습니다(이전 상한인 약 1,600 토큰 대비 이미지당 최대 4,784 토큰). 이미지 중심 워크로드의 경우 `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`)로 이동합니다. 적응형 사고와 노력 수준은 베타 SDK 네임스페이스나 베타 헤더가 필요하지 않습니다.

2. **노력 수준 베타 헤더 제거:** 노력 수준 매개변수는 베타 헤더가 필요하지 않습니다. 요청에서 `effort-2025-11-24` 베타를 제거하세요.

3. **세분화된 도구 스트리밍 베타 헤더 제거:** 세분화된 도구 스트리밍(fine-grained tool streaming)은 베타 헤더가 필요하지 않습니다. 요청에서 `fine-grained-tool-streaming-2025-05-14` 베타를 제거하세요.

4. **인터리브드 사고 베타 헤더 제거:** 적응형 사고를 사용하면 적응형 사고를 지원하는 모든 모델에서 인터리브드 사고(interleaved thinking)가 자동으로 적용됩니다. 요청에서 `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. **도구 버전 업데이트**

   <Warning>
     이는 Claude 3.x 모델에서 마이그레이션할 때 호환성이 깨지는 변경 사항입니다.
   </Warning>

   현재 도구 버전으로 업데이트하세요. `undo_edit` 명령을 사용하는 코드를 모두 제거하세요.

   <CodeGroup exclude="shell">
     ```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"}]
     ```
   </CodeGroup>

   * **텍스트 편집기:** `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`로 업그레이드하세요. 마이그레이션 지침은 [Code execution 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version) 문서를 참조하세요.
   * **컴퓨터 사용:** Claude Opus 5.5가 허용하지 않는 `computer_20250124` 대신 `computer_toolset_20260801` 도구 세트를 사용하세요. Amazon Bedrock에서는 `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)하도록 업데이트하세요:

   <CodeGroup exclude="shell">
     ```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
     ```
   </CodeGroup>

4. **`model_context_window_exceeded` 중지 이유 처리**

   Claude 4.5 이상 모델은 요청된 `max_tokens` 제한이 아니라 컨텍스트 윈도우 한도에 도달하여 생성이 중지되면 `model_context_window_exceeded` 중지 이유를 반환합니다. 애플리케이션이 이 새로운 중지 이유를 처리하도록 업데이트하세요:

   <CodeGroup exclude="shell">
     ```python Python
     response = client.messages.create(...)

     if response.stop_reason == "model_context_window_exceeded":
         # context window(컨텍스트 윈도우) 한도를 적절히 처리합니다
         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" {
     	// context window(컨텍스트 윈도우) 한도를 적절히 처리합니다
     }
     ```

     ```java Java
     Message response = client.messages().create(...);

     StopReason reason = response.stopReason().orElse(StopReason.END_TURN);
     if (reason.equals(StopReason.of("model_context_window_exceeded"))) {
         // context window(컨텍스트 윈도우) 한도를 적절히 처리합니다
     }
     ```

     ```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
       # context window(컨텍스트 윈도우) 한도를 적절히 처리합니다
     end
     ```
   </CodeGroup>

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의 경우 모든 노력 수준에서 허용됩니다.
* 강제 도구 선택과 `computer_20251124` 도구를 허용합니다.
* 도구 호출 사이의 텍스트를 `text` 블록으로 반환합니다.
* 기본 노력 수준은 `high`입니다.

수동 확장 사고, 샘플링 매개변수, 어시스턴트 prefill은 두 모델 모두에서 400 오류를 반환하므로 이 부분은 변경되지 않습니다. Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 섹션의 필수 변경 사항은 어느 것도 적용되지 않습니다.

### 변경된 사항

1. **대화 중 시스템 메시지:** Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed)에서 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)을 참조하세요.