# Claude Code에서 top_p deprecated? 먼저 Opus 4.7 request contract부터 확인하세요

> Claude Code에서 Opus 4.7의 top_p deprecated 오류가 나면 실제 모델과 연결 경로부터 확인하세요. 최종 요청의 샘플링 항목만 제거하고 메시지·도구·출력 제한은 보존한 뒤, 같은 경로에서 원래 작업이 완료되는지 확인해야 합니다.

- URL: https://blog.laozhang.ai/ko/posts/claude-code-top-p-deprecated
- Published: 2026-04-17
- Updated: 2026-10-07
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ko/about)
- Topic: Claude Code
- Tags: Claude Code, Opus 4.7, top_p deprecated, Anthropic, 문제 해결

---
Claude Code에서 `top_p deprecated` 오류가 나고 **실제 요청 대상이 Opus 4.7이라면, 요청을 보내기 직전에 `top_p`, `temperature`, `top_k`를 넣는 코드를 찾아 해당 샘플링 항목을 빼세요.** 설정 파일에서 지웠더라도 어댑터가 기본값을 다시 넣으면 오류가 계속됩니다. 먼저 모델 ID와 연결 경로를 확인하고, 수정 뒤에는 같은 경로에서 원래 작업을 다시 확인해야 합니다.

Anthropic의 현재 [Messages 안내](https://platform.claude.com/docs/es/build-with-claude/working-with-messages)는 Opus 4.7 이상과 Mythos Preview에서 비기본값 샘플링 파라미터를 보내면 400 오류가 난다고 설명하며, 해당 항목의 생략을 권합니다. [AWS의 Opus 4.7 문서](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-opus-4-7.html)는 세 샘플링 파라미터를 지원하지 않는다고 명시합니다. 숫자를 `0`이나 `1`로 바꾸거나 `null`을 보내는 방식보다, 해당 경로의 요청에서 항목 자체를 생략하는 것이 맞습니다.

이 글의 JSON 처리 예시는 네트워크 호출 없이 로컬에서 확인할 수 있습니다. 실제 계정의 API 호출이나 Claude Code 작업이 복구됐다는 실측 결과는 아닙니다.

## 오류가 난 위치와 실제 모델부터 확인하세요

`deprecated`라는 문구만으로 Claude Code 전체의 버그나 모델 서비스 종료를 판단할 수는 없습니다. 서버의 400 오류인지, SDK가 요청을 만들다가 낸 예외인지에 따라 고칠 위치가 달라집니다.

| 확인한 증상 | 먼저 확인할 곳 | 다음 조치 |
| --- | --- | --- |
| HTTP 400과 `top_p`, `temperature`, `top_k` 관련 오류가 함께 나옴 | 실제 모델 ID와 서버에 전달된 최종 요청 | 그 모델이 받지 않는 샘플링 항목을 올바른 위치에서 생략 |
| Python의 `unexpected keyword argument` 또는 `TypeError` | HTTP 전송 전 SDK 호출 인자 | 사용 중인 SDK의 메서드에서 제거된 인자를 전달하는지 확인 |
| 설정에서 지웠는데 요청에는 여전히 들어 있음 | 설정을 합치는 코드, SDK 기본값, 프록시·어댑터 | 모든 설정 병합이 끝난 다음의 요청 생성 부분 수정 |
| `opus`를 선택했지만 모델 ID가 예상과 다름 | 제공자별 별칭과 현재 세션의 모델 선택 | 실제 ID에 맞는 문서로 요청 형식 확인 |
| 오류가 샘플링 항목이 아닌 역할·권한·버전 문제를 가리킴 | 해당 오류의 원문 | 샘플링 항목 제거와 별개로 원인 구분 |

Anthropic의 [파라미터 지원 중단 안내](https://platform.claude.com/docs/zh-CN/about-claude/model-deprecations)는 Python SDK v1 이상에서 샘플링 키워드 인자를 전달하면 `TypeError`가 날 수 있다고 설명합니다. 이는 설치된 SDK를 이 글에서 검사했다는 뜻이 아니며, 서버의 400과도 다릅니다. 요청 전 예외가 났다면 프록시가 나중에 JSON을 고쳐 주는 방식으로는 해결되지 않습니다.

Claude Code의 실행 버전, 실행한 클라이언트, 제공자, 모델 ID를 각각 확인하세요. 터미널에서 사용한 버전과 에디터가 실행하는 버전이 같다고 단정하지 마세요. 4월의 `v2.1.111+` 안내를 모든 현재 모델에 통용되는 최소 버전으로 쓰는 것도 맞지 않습니다. 필요한 버전은 선택한 모델과 현재 [공식 모델 설정](https://code.claude.com/docs/en/model-config)에 맞춰 확인해야 합니다.

### `opus`를 선택했다고 Opus 4.7인 것은 아닙니다

별칭이 가리키는 모델은 제공자와 시점에 따라 바뀝니다. “Anthropic API는 언제나 4.7, 모든 클라우드는 4.6”처럼 고정된 표로 판단하지 말고, 실제 요청에 쓰인 모델 ID를 확인하세요. 직접 API의 모델 ID, Bedrock의 추론 프로필 ID·ARN, Foundry의 배포 이름은 같은 문자열이 아닙니다. [제공자별 모델 지정 방식](https://code.claude.com/docs/en/model-config)

모델을 확인하려고 `/model`을 조작할 때도 저장 범위를 알아야 합니다. 현재 문서에서는 Enter로 선택하거나 모델 이름을 직접 지정하면 사용자 기본값이 저장되고, 선택 화면의 `s`는 이번 세션에만 적용됩니다. 오류 조사 중 무심코 다음 실행의 모델까지 바꾸지 않도록 주의하세요. 설정 우선순위나 게이트웨이 연결을 먼저 정리해야 한다면 [Claude Code의 모델·게이트웨이 설정 확인 방법](https://blog.laozhang.ai/ko/posts/claude-code-api-configuration)을 참고할 수 있습니다.

## 설정 파일이 아니라 최종 요청에서 제거해야 합니다

Claude Code가 보여 준 오류의 원인이 어느 구성 요소인지는 실제 요청을 봐야 알 수 있습니다. 래퍼 스크립트, 제공자 어댑터, 프록시가 값을 추가할 수 있지만, 이들이 언제나 원인인 것은 아닙니다.

설정에서 전송까지 다음 순서로 확인하세요.

1. 오류가 난 실행의 제공자와 모델 ID를 기록합니다.
2. 설정과 모델별 옵션이 합쳐지는 부분을 찾습니다.
3. SDK 호출 인자 또는 HTTP 전송 직전 JSON에 샘플링 항목이 남는지 확인합니다.
4. 해당 모델에만 적용되도록 요청 생성 코드를 수정합니다.
5. 같은 위치에서 다시 확인해 항목이 재삽입되지 않는지 봅니다.

요청 내용을 확인할 때 API 키나 인증 헤더를 출력할 필요는 없습니다. 모델 ID와 문제 필드의 위치부터 확인하고, 사용자 메시지나 파일 내용이 포함된 전체 로그의 불필요한 공유도 피하세요.

| 요청 형식 | 샘플링 항목을 확인할 위치 | 함께 보존할 항목 |
| --- | --- | --- |
| Anthropic Messages | 요청 본문의 최상위 `top_p`, `temperature`, `top_k` | `model`, `messages`, `system`, `tools`, `max_tokens`, `stop_sequences` 등 |
| Bedrock InvokeModel의 Anthropic 본문 | JSON 본문의 최상위 `top_p`, `temperature`, `top_k` | `anthropic_version`, `messages`, `max_tokens` 등 해당 형식의 필수·지원 필드 |
| Bedrock Converse·ConverseStream | `inferenceConfig.topP`, `inferenceConfig.temperature`; 모델별 추가 항목은 `additionalModelRequestFields` | `modelId`, `messages`, `toolConfig`, `inferenceConfig.maxTokens`, `inferenceConfig.stopSequences` 등 |

Converse의 `topP`와 Anthropic Messages 본문의 `top_p`는 철자가 다릅니다. AWS의 [일반 InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_InferenceConfiguration.html)에 `topP`가 선택 항목으로 존재한다고 해서 Opus 4.7이 그 값을 받는 것은 아닙니다. 모델별 지원 조건이 우선합니다.

AWS의 [Converse 요청 문서](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html)는 모델별 추가 항목을 `additionalModelRequestFields`로 전달하며, 이전 Sonnet 예시의 `top_k`도 이 위치에 있습니다. 이 예시는 필드 위치를 보여 줄 뿐 Opus 4.7의 `top_k` 지원을 뜻하지 않습니다. 사용 중인 어댑터가 다른 이름이나 위치로 변환한다면, 변환을 마친 뒤 위의 실제 요청 형태에서 확인하세요.

## 필요한 데이터는 남기고 샘플링 항목만 빼는 예시

다음 코드는 **이미 Opus 4.7로 확인한 모델의 최종 요청 JSON**을 로컬에서 정리합니다. 모델 이름만 보고 Opus 4.7 여부를 추측하지 않으며, 전달한 정확한 모델 ID와 요청의 ID가 다르면 중단합니다. 파일 이름은 `omit_sampling.py`로 저장합니다.

```python
import argparse
import copy
import json
from pathlib import Path


def omit_sampling(request, request_format, expected_model):
    result = copy.deepcopy(request)
    model_key = "modelId" if request_format == "converse" else "model"
    if result.get(model_key) != expected_model:
        raise ValueError("Expected model does not match the request")

    if request_format == "messages":
        for key in ("top_p", "temperature", "top_k"):
            result.pop(key, None)
    else:
        for container, keys in (
            ("inferenceConfig", ("topP", "temperature")),
            ("additionalModelRequestFields", ("top_p", "temperature", "top_k")),
        ):
            if container not in result:
                continue
            fields = result[container]
            if not isinstance(fields, dict):
                raise ValueError(f"{container} must be an object")
            for key in keys:
                fields.pop(key, None)
            if not fields:
                result.pop(container)
    return result


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("input", type=Path)
    parser.add_argument("--format", choices=("messages", "converse"), required=True)
    parser.add_argument("--opus47-model", required=True)
    args = parser.parse_args()
    request = json.loads(args.input.read_text(encoding="utf-8"))
    cleaned = omit_sampling(request, args.format, args.opus47_model)
    print(json.dumps(cleaned, ensure_ascii=False, indent=2))
```

직접 Anthropic Messages를 사용하는 Opus 4.7 요청이라면 다음처럼 실행할 수 있습니다. `request.json`은 해당 요청 본문이며, 출력 파일은 API로 전송하지 않습니다.

```bash
python3 omit_sampling.py request.json --format messages \
  --opus47-model claude-opus-4-7 > cleaned.json
```

Converse에서는 `--format converse`를 사용하고 `--opus47-model`에 실제 `modelId`와 일치하는, Opus 4.7로 확인한 모델·추론 프로필 ID를 넣습니다. 위 코드는 Messages와 Converse용이며, `model`이 본문에 없는 Bedrock InvokeModel 본문에 그대로 적용하는 도구는 아닙니다. InvokeModel에서는 호출 인자의 대상 모델을 먼저 확인한 뒤, 그 모델의 직렬화할 본문 최상위에서 세 항목만 생략해야 합니다.

삭제 대상을 재귀적으로 찾지 않는 점이 중요합니다. 도구 입력 스키마의 `properties.top_p`, 사용자가 입력한 JSON 문자열의 `temperature`는 생성 제어 파라미터가 아닙니다. 이를 삭제하면 도구의 의미나 사용자 데이터가 달라집니다. 반대로 `max_tokens`·`maxTokens`, 종료 문자열, 도구 설정, 지원되는 우선순위 항목은 이번 샘플링 오류만을 이유로 지우지 않습니다.

실제 연동에서는 이 처리를 **모든 기본값과 옵션을 합친 뒤, 전송 직전**에 넣으세요. 로컬에서 만든 `cleaned.json`에 항목이 없더라도 SDK나 프록시가 이후에 값을 추가하면 수정이 완성된 것이 아닙니다. Python SDK가 키워드 인자 단계에서 거절한다면 JSON 파일을 나중에 정리하는 대신 SDK 메서드에 전달하는 인자에서 먼저 빼야 합니다.

## `effort`는 `top_p`의 숫자 대체값이 아닙니다

![Opus 4.7에서 오래된 샘플링 항목을 제거하는 그림](https://blog.laozhang.ai/posts/ko/claude-code-top-p-deprecated/img/removed-params-board.webp)

`top_p=0.9`를 특정 `effort` 값으로 바꾸는 대응표는 없습니다. `top_p`는 토큰 후보 선택에 쓰이는 샘플링 제어이고, `output_config.effort`는 응답의 상세함, 작업량, 사고와 토큰 사용을 조절하는 신호입니다. Anthropic도 effort를 엄격한 토큰 예산으로 설명하지 않습니다. [공식 effort 안내](https://platform.claude.com/docs/en/build-with-claude/effort)

API의 Opus 4.7 기본 effort가 `high`라는 문서 설명을 Claude Code 전체의 현재 기본값으로 확대하면 안 됩니다. CLI의 설정, 선택한 모델, 제공 경로를 따로 확인해야 합니다. 과거 버전에서 `xhigh` 기본값이 바뀌었다는 기록도 현재 실행의 값을 증명하지 않습니다.

샘플링 항목을 제거한 다음에는 원래 작업이 요구하는 결과를 명확히 적으세요. 예를 들어 코드 수정이라면 허용하는 변경 범위와 통과해야 할 테스트를, JSON 생성이라면 필수 키와 허용값을 지정합니다. 필요할 때 해당 모델과 경로가 지원하는 effort를 별도로 조정하되, 오류 수정을 이유로 출력 한도를 자동으로 64,000 토큰으로 늘리거나 다른 사고 설정까지 바꾸지는 마세요. `temperature=0`이나 특정 effort가 매번 동일한 답을 보장한다고도 볼 수 없습니다.

## 같은 경로에서 원래 작업이 끝나야 복구입니다

![샘플링 항목 제거 후 같은 요청 경로에서 작업을 확인하는 흐름](https://blog.laozhang.ai/posts/ko/claude-code-top-p-deprecated/img/cleanup-flow.webp)

복구 확인은 “400이 사라졌다”에서 끝나지 않습니다. 서버가 요청을 받았는지와 원래 작업을 제대로 완료했는지는 별개의 확인 항목입니다.

먼저 오프라인에서 수정 전후 JSON을 비교하세요. 삭제된 항목이 위의 샘플링 필드뿐인지, 모델 ID·메시지·도구 스키마·출력 제한이 그대로인지 확인합니다. 합성 데이터로 같은 이름의 도구 속성과 사용자 입력을 넣어 보존되는지도 확인할 수 있습니다. 이 글의 코드는 이런 로컬 구문·JSON 변환을 확인했으며 실제 모델을 호출하지 않았습니다.

그다음 실제 작업을 다시 실행할 수 있는 환경에서 다음 순서로 확인합니다.

1. 기존 제공자, 모델, 어댑터를 유지하고 오류가 났던 작업을 다시 실행합니다.
2. 전송 직전 요청에서 금지된 샘플링 항목이 빠졌는지 확인합니다.
3. 같은 샘플링 오류가 사라졌는지 봅니다. 역할·사고 설정 등 다른 오류가 나오면 그 오류를 따로 해결합니다.
4. 필요한 도구 호출, 출력 형식, 코드의 테스트 등 원래 작업의 완료 조건을 확인합니다.
5. 새 실행에서도 오래된 기본값이 다시 들어오지 않는지 확인합니다.

설정 파일이 깨끗해도 최종 요청이 깨끗하다는 보장은 없습니다. AWS 문서 처리 샘플의 [이슈 #304](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/issues/304)에서는 설정에 `top_p`가 없는데도 Strands 기반 에이전트의 ConverseStream 경로에서 오류가 보고됐고, 유지보수자는 샘플 v0.5.10의 수정 내용을 안내했습니다. 이 버전은 해당 샘플의 버전이며 Claude Code 전체의 수정 버전이 아닙니다.

### 다른 모델로 우회해야 한다면 무엇을 확인하나요?

당장 요청 생성 부분을 고칠 수 없고 작업을 진행해야 한다면, 사용 권한이 있고 해당 요청 형식을 지원하는 다른 모델을 임시로 선택할 수 있습니다. 다만 모델을 바꾸면 출력 품질, 도구 동작, 비용, 제공 경로의 기능도 달라질 수 있으므로 원래 작업의 완료 조건으로 다시 판단해야 합니다.

다른 모델에서 성공한 결과는 그 우회 경로가 동작한다는 증거입니다. 원래 Opus 4.7 경로의 문제가 해결됐다는 증거로 쓰지는 마세요. 이후 원래 경로로 돌아와 최종 요청의 항목과 작업 결과를 다시 확인해야 합니다.

## 자주 묻는 질문

### `top_p deprecated`면 Opus 4.7 서비스가 종료된 건가요?

아닙니다. 파라미터 지원 중단과 모델 서비스 종료는 다릅니다. 2026년 10월 6일 확인한 [Anthropic 모델 상태 표](https://platform.claude.com/docs/zh-CN/about-claude/model-deprecations)에서는 Opus 4.7과 4.6이 활성 상태입니다. 다만 활성 상태가 모든 계정·리전·제공 경로의 접근 권한을 보장하지는 않습니다.

### `top_p: null`이나 기본값을 넣으면 해결되나요?

항목 생략으로 처리하세요. Anthropic의 [Messages 안내](https://platform.claude.com/docs/es/build-with-claude/working-with-messages)는 비기본값 오류와 생략을 설명하지만, 이 글에서는 `null`, `0`, `1`을 실제 호출로 검증하지 않았습니다. [AWS Opus 4.7](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-opus-4-7.html)는 샘플링 파라미터 자체를 지원하지 않습니다. SDK에서 `None`을 줬다면 실제로 생략됐는지, JSON `null`로 직렬화됐는지도 구분해야 합니다.

### `max_tokens`나 도구 설정도 같이 지워야 하나요?

아니요. 샘플링 오류에서는 해당 샘플링 항목만 제거합니다. 출력 한도, 종료 문자열, 메시지, 도구와 입력 스키마는 보존하세요. 특히 도구 스키마에 정의한 `top_p`라는 속성은 모델의 최상위 샘플링 파라미터와 다릅니다.

### Claude Code를 업데이트하면 프록시의 기본값도 사라지나요?

별도로 확인해야 합니다. 클라이언트가 모델을 지원하더라도 프록시나 어댑터가 전송 직전에 값을 다시 넣을 수 있습니다. 현재 버전과 모델을 확인한 뒤 실제 요청 생성 위치에서 항목이 빠지는지 확인하세요. 소프트웨어 버전 변경과 제공자 변경을 동시에 하면 어느 변경이 결과에 영향을 줬는지 구분하기 어렵습니다.

## 참고 자료

이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026-10-07.

- [Messages 안내](https://platform.claude.com/docs/es/build-with-claude/working-with-messages) (platform.claude.com)
- [AWS의 Opus 4.7 문서](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-opus-4-7.html) (docs.aws.amazon.com)
- [파라미터 지원 중단 안내](https://platform.claude.com/docs/zh-CN/about-claude/model-deprecations) (platform.claude.com)
- [공식 모델 설정](https://code.claude.com/docs/en/model-config) (code.claude.com)
- [일반 InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_InferenceConfiguration.html) (docs.aws.amazon.com)
- [Converse 요청 문서](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) (docs.aws.amazon.com)
- [공식 effort 안내](https://platform.claude.com/docs/en/build-with-claude/effort) (platform.claude.com)
- [이슈 #304](https://github.com/aws-solutions-library-samples/accelerated-intelligent-document-processing-on-aws/issues/304) (github.com)