노력 수준(Effort)

"effort"(노력) 매개변수를 사용하면 Claude가 요청에 응답할 때 소비하는 토큰 수를 제어할 수 있습니다. 단일 모델로 응답의 철저함과 토큰 효율성 사이에서 균형을 조절할 수 있습니다. 최상위 effort 매개변수는 지원되는 모든 모델에서 베타 헤더 없이 사용할 수 있습니다. 메시지별 effort는 베타 상태입니다.

effort 수준 설정

요청에 output_config.effort를 설정하세요. 다음 예제는 medium effort로 요청 하나를 실행하고 응답 텍스트를 출력합니다.

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)

effort 작동 방식

대부분의 Claude 모델은 기본적으로 high effort를 사용하여 탁월한 결과를 위해 필요한 만큼 토큰을 사용합니다. Claude Opus 5.5와 Claude Haiku 5.5는 기본값이 medium입니다. 절대적으로 가장 높은 성능을 위해 effort 수준을 max로 높이거나, 토큰 사용을 더 보수적으로 하기 위해 낮출 수 있으며, 이 경우 일부 성능 저하를 감수하는 대신 속도와 비용을 최적화할 수 있습니다.

effort 매개변수는 응답의 모든 토큰에 영향을 미치며, 여기에는 다음이 포함됩니다:

• 텍스트 응답 및 설명
• 도구 호출 및 함수 인수
• 사고(활성화된 경우)

effort는 모든 출력 토큰에 적용되므로 사고 활성화 여부와 관계없이 작동합니다. effort가 낮을수록 도구 호출도 더 적고 간결해집니다.

effort 수준

max를 지원하는 모든 모델이 xhigh를 지원하는 것은 아닙니다.

이어지는 모델별 권장 사항이 이 표와 다른 경우에는 모델별 권장 사항이 우선합니다.

Claude Fable 5.1 권장 effort 수준

Claude Fable 5.1은 다섯 가지 effort 수준을 모두 지원합니다. 기본값인 high로 시작하세요. 역량에 가장 민감한 에이전트 및 코딩 작업에는 xhigh 또는 max로 올리고, 평가에서 품질이 유지되는 것이 확인되면 일상적이거나 지연 시간에 민감한 작업에는 medium 또는 low로 낮추세요. high 이상에서는 큰 max_tokens를 설정하세요. 이는 총 출력(사고 + 응답 텍스트)에 대한 엄격한 한도입니다. 동일한 권장 사항이 Claude Mythos 5.1에도 적용됩니다. Claude Fable 5.1 프롬프팅을 참조하세요.

Claude Fable 5.1은 또한 메시지별 output_config를 사용한 대화 중 effort 변경을 지원하며, 이는 프롬프트 캐시를 보존합니다.

Claude Fable 5 권장 effort 수준

effort는 Claude Fable 5에서 지능, 지연 시간, 비용 간의 균형을 조절하는 주요 제어 수단입니다. 대부분의 작업에는 기본값인 high로 시작하고, 역량에 가장 민감한 워크로드에는 xhigh를 사용하며, 일상적인 작업에는 medium 또는 low로 낮추세요. Claude Fable 5의 낮은 effort 설정도 여전히 좋은 성능을 보이며 종종 이전 모델의 xhigh 성능을 능가합니다. high와 xhigh에서는 큰 max_tokens를 설정하세요. 이는 총 출력(사고 + 응답 텍스트)에 대한 엄격한 한도입니다. 비용 제어를 참조하세요.

작업이 완료되지만 필요 이상으로 오래 걸리거나, 더 빠르고 상호작용적인 작업 스타일을 원한다면 effort를 줄이세요. 동일한 권장 사항이 Claude Mythos 5에도 적용됩니다. 더 자세한 안내는 Claude Fable 5 프롬프팅을 참조하세요.

Claude Opus 5.5의 권장 effort 수준

Claude Opus 5.5는 다섯 가지 effort 수준을 모두 지원하며, 기본값은 medium입니다(Claude Opus 5 및 이전 Opus 모델의 기본값은 high이므로, effort를 생략한 요청은 Claude Opus 5에서보다 한 단계 낮은 수준으로 실행됩니다). 적응형 사고는 항상 켜져 있으며 끌 수 없으므로, effort는 모델이 얼마나 추론하는지와 요청 비용을 결정하는 주요 제어 수단입니다. 이전 모델의 설정을 그대로 가져오지 말고 자체 평가에서 effort 스윕을 실행하세요. 또한 높은 수준에서는 max_tokens를 크게 설정하세요. 이는 전체 출력(사고와 응답 텍스트의 합)에 대한 엄격한 한도입니다. thinking: {"type": "disabled"}를 설정한 요청은 모든 effort 수준에서 400 오류를 반환합니다. Claude Opus 5.5는 메시지별 output_config를 사용한 대화 중 effort 변경도 지원하며, 이 방식은 프롬프트 캐싱을 유지합니다. Claude Opus 5.5 프롬프팅을 참조하세요.

Claude Opus 5 권장 effort 수준

Claude Opus 5는 다섯 가지 effort 수준을 모두 지원합니다. 기본값인 high로 시작하고, 평가 결과에 따라 조정하세요. 까다로운 코딩 및 에이전트 작업에는 xhigh로, 작업이 제약 없는 토큰 사용을 정당화할 때는 max로 높이고, 평가 결과 품질이 유지되는 곳에서는 토큰 비용과 응답 시간을 위한 주요 제어 수단으로 low와 medium을 적극적으로 사용하세요. 이전 모델의 effort 설정을 가져왔다면, 이를 재사용하지 말고 평가에서 새로 effort 스윕을 실행하세요.

effort는 보이는 응답 길이가 아니라 사고량을 제어합니다. Claude Opus 5에서는 effort를 변경해도 응답이 안정적으로 짧아지지 않으므로, 대신 길이에 대해 프롬프트로 지시하세요.

API 기본값은 high입니다. 다른 수준을 사용하려면 effort를 명시적으로 설정하세요. 전달한 값이 기본값보다 우선합니다.

Claude Opus 5에서는 xhigh 또는 max effort에서 사고를 비활성화할 수 없습니다. 해당 수준에서 thinking: {"type": "disabled"}를 설정한 요청은 400 오류를 반환합니다. 사고와 함께 사용하는 effort를 참조하세요.

Claude Opus 5를 xhigh 또는 max effort로 실행할 때는 모델이 서브에이전트와 도구 호출 전반에서 사고하고 행동할 여유가 있도록 큰 max_tokens를 설정하세요. 64k 토큰에서 시작하여 조정하는 것이 합리적인 기본값입니다.

Claude Opus 5는 메시지별 output_config를 사용한 대화 중 effort 변경도 지원하며, 이 방식은 프롬프트 캐시를 유지합니다. Amazon Bedrock의 Claude Opus 5에서는 메시지별 effort를 사용할 수 없습니다.

Claude Opus 4.8 권장 effort 수준

Claude Opus 4.7에 대한 안내는 Claude Opus 4.8에도 적용됩니다. 코딩 및 에이전트 사용 사례에는 xhigh로 시작하고, 대부분의 다른 지능 민감 워크로드에는 high를 사용하며, 평가에서 낮은 수준이 품질을 유지한다는 것을 측정한 경우에만 medium 또는 low로 낮추세요.

API 기본값은 high입니다. 다른 수준을 사용하려면 effort를 명시적으로 설정하세요. 전달한 값이 기본값을 재정의합니다.

Claude Opus 4.8을 xhigh 또는 max effort로 실행할 때는 모델이 서브에이전트와 도구 호출 전반에 걸쳐 사고하고 행동할 여유가 있도록 큰 max_tokens를 설정하세요. 64k 토큰에서 시작하여 거기서부터 조정하는 것이 합리적인 기본값입니다.

Claude Opus 4.7 권장 effort 수준

코딩 및 에이전트 사용 사례에는 xhigh로 시작하고, 지능에 민감한 대부분의 워크로드에는 최소 high를 사용하세요. 비용에 민감한 워크로드에는 medium으로 낮추고, 평가에서 xhigh 대비 측정 가능한 개선 여지가 확인될 때만 max로 높이세요.

API 기본값은 high입니다. xhigh를 사용하려면 effort를 명시적으로 설정하세요. 전달한 값이 기본값보다 우선합니다.

Claude Opus 4.7은 또한 Claude Opus 4.6보다 effort 수준을 더 엄격하게 따르며, 특히 low와 medium에서 그렇습니다. 낮은 effort 수준에서 모델은 요청된 것 이상을 하기보다는 요청된 범위로 작업을 한정합니다. Claude Opus 4.7에서 복잡한 문제에 대해 얕은 추론이 관찰된다면, 프롬프트로 우회하기보다는 effort를 높이세요. 지연 시간 때문에 effort를 낮게 유지해야 한다면 "This task involves multistep reasoning. Think carefully before responding."과 같은 구체적인 안내를 추가하세요.

Claude Opus 4.7을 xhigh 또는 max effort로 실행할 때는 모델이 서브에이전트와 도구 호출 전반에서 사고하고 행동할 여유가 있도록 큰 max_tokens를 설정하세요. 64k 토큰에서 시작하여 조정하는 것이 합리적인 기본값입니다.

Claude Sonnet 5.5의 권장 effort 수준

Claude Sonnet 5.5는 다섯 가지 effort 수준을 모두 지원하며, Claude API에서의 기본값은 high입니다. 수준이 재보정되었으므로, 같은 수준이라도 Claude Sonnet 5에서와 같은 양의 사고를 생성하지 않습니다. Claude Sonnet 5에서 사용하던 설정을 그대로 가져오지 말고 평가에서 새로 effort 스윕을 실행하세요. 워크로드가 에이전트 작업이거나 지연 시간에 민감한 경우가 아니라면 high로 시작하세요. 에이전트 코딩과 다단계 도구 사용의 경우, 명확하게 정의된 작업에는 medium으로 시작하고 더 어렵거나 긴 작업에는 high로 올리세요. 채팅 및 기타 지연 시간에 민감한 작업에는 medium 또는 low로 시작하세요. xhigh 또는 max는 평가에서 품질 향상이 확인되는 경우에만 사용하세요. 사고와 응답을 위한 여유를 두고 max_tokens를 설정하세요. 사고 내용이 반환되지 않더라도 사고는 max_tokens에 포함됩니다. 에이전트 코딩의 경우 max_tokens를 모델의 최대값인 128,000으로 설정하고 응답을 스트리밍하세요.

사전 사고를 끄려면 "disabled" 대신 thinking: {"type": "between_tools"}를 보내세요. 이는 Claude Sonnet 5.5에서 가장 낮은 사고 설정이며, low, medium, high effort에서 작동합니다. xhigh 또는 max에서는 이 설정을 사용한 요청이 400 오류를 반환하므로, 해당 수준에서는 적응형 사고를 사용하세요. thinking 필드를 생략하거나 thinking: {"type": "adaptive"}를 보내면 됩니다. 사전 사고 없이 실행하기를 참조하세요.

Claude Sonnet 5.5는 메시지별 output_config를 사용한 대화 중 effort 변경도 지원하며, 이 방식은 프롬프트 캐시를 유지합니다. between_tools를 사용하면 대화 중에 effort를 변경할 수 없습니다. 현재 적용 중인 수준과 다른 메시지별 output_config.effort는 400 오류를 반환합니다. 턴마다 effort를 다르게 하려면 적응형 사고를 사용하세요. Claude Sonnet 5.5 프롬프팅을 참조하세요.

Claude Sonnet 5 권장 effort 수준

Claude Sonnet 5는 Claude API와 Claude Code에서 기본적으로 high effort를 사용합니다.

• High effort(기본값): 속도나 비용보다 품질이 더 중요한 복잡한 추론, 코딩, 에이전트 작업에 적합합니다.
• Xhigh effort: 가장 어려운 코딩 및 에이전트 작업용. Claude Sonnet 5 프롬프팅을 참조하세요.
• Medium effort: 기본값에서 비용을 절감하는 하향 단계. high effort의 Claude Sonnet 4.6과 비슷합니다.
• Low effort: 대용량 또는 지연 시간에 민감한 워크로드용. 더 빠른 처리가 우선시되는 채팅 및 비코딩 사용 사례에 적합합니다.
• Max effort: 토큰 소비에 제약 없이 절대적으로 가장 높은 역량이 필요한 작업용.

Claude Sonnet 4.6 권장 effort 수준

Sonnet 4.6은 기본적으로 high effort를 사용합니다. 예상치 못한 지연 시간을 피하려면 Sonnet 4.6을 사용할 때 effort를 명시적으로 설정하세요:

• Medium effort(권장 기본값): 대부분의 애플리케이션에 대해 속도, 비용, 성능의 최적 균형. 에이전트 코딩, 도구 중심 워크플로, 코드 생성에 적합합니다.
• Low effort: 대용량 또는 지연 시간에 민감한 워크로드용. 더 빠른 처리가 우선시되는 채팅 및 비코딩 사용 사례에 적합합니다.
• High effort: 속도나 비용보다 품질이 더 중요한 복잡한 추론 및 작업용.
• Max effort: 토큰 소비에 제약 없이 절대적으로 가장 높은 역량이 필요한 작업용.

Claude Haiku 5.5 권장 effort 수준

Claude Haiku 5.5는 다섯 가지 effort 수준을 모두 지원하며, Claude API와 Claude Code에서의 기본값은 medium입니다. effort는 모델이 얼마나 사고하는지, 그리고 그에 따른 품질, 지연 시간, 비용을 제어하는 주요 수단입니다. 에이전트 코딩을 포함한 대부분의 작업에는 medium으로 시작하세요. 가장 저렴하고 빠른 수준인 low는 채팅, 짧은 도구 작업, 단순한 대량 요청에 사용하세요. 긴 에이전트 프롬프트에서는 low일 때 모델이 검색을 건너뛰거나, 일찍 멈추거나, 확인을 건너뛸 가능성이 더 높습니다. 지식 작업, 더 긴 에이전트 작업, 엄격한 지시 준수에는 high를 사용하세요. xhigh 또는 max는 평가에서 품질 향상이 확인되는 경우에만 사용하고, 성능, 비용, 속도 측면에서 Claude Sonnet 5.5와 비교하세요. 사고는 기본적으로 켜져 있으며 max_tokens에 포함되므로 이를 위한 여유를 남겨 두세요. Claude Haiku 5.5 프롬프팅을 참조하세요.

사고를 줄이려면 effort 수준을 낮추세요. high effort 이하에서는 thinking: {"type": "disabled"}를 보낼 수도 있습니다. xhigh 또는 max에서는 이 설정을 사용한 요청이 400 오류를 반환하므로, 해당 수준에서는 적응형 사고를 사용하세요. thinking 필드를 생략하거나 thinking: {"type": "adaptive"}를 보내면 됩니다.

Claude API와 Google Cloud에서 Claude Haiku 5.5는 메시지별 output_config를 사용한 대화 중 effort 변경도 지원하며, 이 방식은 프롬프트 캐시를 유지합니다. thinking: {"type": "disabled"}를 사용하면 대화 중에 effort를 변경할 수 없습니다. 현재 적용 중인 수준과 다른 메시지별 output_config.effort는 400 오류를 반환합니다. 턴마다 effort를 다르게 하려면 적응형 사고를 사용하세요.

도구 사용과 함께 사용하는 effort

도구를 사용할 때 effort 매개변수는 도구 호출 주변의 설명과 도구 호출 자체 모두에 영향을 미칩니다. 낮은 effort 수준은 다음과 같은 경향이 있습니다:

• 여러 작업을 더 적은 도구 호출로 결합
• 더 적은 도구 호출 수행
• 서두 없이 바로 행동으로 진행
• 완료 후 간결한 확인 메시지 사용

높은 effort 수준은 다음과 같을 수 있습니다:

• 더 많은 도구 호출 수행
• 행동하기 전에 계획 설명
• 변경 사항에 대한 상세한 요약 제공
• 더 포괄적인 코드 주석 포함

사고와 함께 사용하는 effort

thinking 매개변수는 Claude가 답변하기 전에 thinking 블록에서 사고할지 여부를 제어합니다. effort 매개변수는 Claude가 전체 응답에 얼마나 많은 노력을 기울일지를 제어하며, adaptive 모드에서는 얼마나 자주, 얼마나 깊이 사고할지도 여기에 포함됩니다. adaptive를 effort 값으로 전달하지 마세요. adaptive는 사고 모드이지 effort 수준이 아닙니다.

높은 effort 수준에서 Claude는 더 적극적으로, 더 길게 사고합니다. 도구 사용 루프에서 도구 결과만 처리하는 후속 요청은 어떤 수준에서든 사고를 건너뛸 수 있습니다. 낮은 수준에서 Claude는 더 단순한 문제에 대해 사고를 완전히 건너뛸 수 있습니다. 두 제어 수단이 함께 작동하는 방식에 대한 전체 안내는 사고와 effort를 참조하세요.

effort를 지원하는 유일한 확장 사고 전용 모델인 Claude Opus 4.5에서는 budget_tokens와 함께 작동합니다. 작업에 맞는 effort 수준을 설정한 다음, 작업에 필요한 추론 깊이에 따라 사고 토큰 예산을 설정하세요.

모델별 사고 사용 가능 여부는 모델별 구성 표를 참조하세요. effort는 사고 유무와 관계없이 작동합니다. effort 작동 방식을 참조하세요.

대화 중 effort 변경

대화의 이후 턴을 다른 effort 수준으로 실행하는 방법은 두 가지입니다. Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Haiku 5.5에서는 프롬프트 캐시를 유지하는 메시지별 effort 변경을 사용하세요. 다른 모델에서는 다음 요청에 새로운 최상위 값을 설정하며, 이 경우 캐시가 처음부터 다시 시작됩니다.

메시지별 effort(베타)

메시지별 effort는 베타 상태입니다. Claude API와 Google Cloud에서는 Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Haiku 5.5에서 사용할 수 있습니다. Amazon Bedrock에서는 Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5에서 사용할 수 있습니다. 베타 헤더 mid-conversation-output-config-2026-07-01이 필요합니다. Amazon Bedrock InvokeModel API에서는 Claude Fable 5.1과 Claude Opus 5.5에서 사용할 수 있으며, 대신 요청 본문의 anthropic_beta 배열에 해당 값을 보냅니다.

베타 값이 없으면 메시지별 output_config는 400 오류 messages.N.output_config: Extra inputs are not permitted를 반환하며, 여기서 N은 messages 내 system 메시지의 인덱스입니다. 베타 값이 있더라도 Claude Fable 5를 포함하여 메시지별 effort를 지원하지 않는 모델은 400 오류 output_config.effort requires a model that supports per-turn effort; this model does not를 반환합니다. Amazon Bedrock에서는 해당 모델들과 Claude Opus 5가 대신 Extra inputs are not permitted 오류를 반환합니다. thinking: {"type": "between_tools"}를 사용하는 Claude Sonnet 5.5 및 thinking: {"type": "disabled"}를 사용하는 Claude Haiku 5.5에서는 대화 중에 effort를 변경할 수 없습니다. 현재 적용 중인 수준과 다른 메시지별 output_config.effort는 400 오류를 반환합니다. 턴마다 effort를 다르게 하려면 적응형 사고를 사용하세요.

빈 content와 output_config.effort에 새 수준을 지정한 role: "system" 메시지를 추가하세요. 새 수준은 다음 user 턴부터 적용되며, 이후 메시지가 변경할 때까지 유지됩니다. 해당 메시지 이전의 모든 내용은 변경되지 않으므로 캐시된 접두사가 여전히 일치합니다.

다음 예제는 high로 시작한 다음, 일상적인 후속 요청에서 low로 낮춥니다:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=4096,
    output_config={"effort": "high"},
    messages=[
        {
            "role": "user",
            "content": "Plan a migration from SQLite to PostgreSQL in three short steps.",
        },
        {
            "role": "assistant",
            "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.",
        },
        # Effort 전용 시스템 메시지: 새 수준은 다음 사용자 턴부터 적용됩니다.
        {"role": "system", "content": [], "output_config": {"effort": "low"}},
        {"role": "user", "content": "Summarize the plan in one sentence."},
    ],
    betas=["mid-conversation-output-config-2026-07-01"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

effort 전용 시스템 메시지는 텍스트를 포함하지 않으므로 대화 중 시스템 메시지의 배치 규칙이 적용되지 않습니다. 첫 번째 항목이나 assistant 턴과 다음 user 턴 사이를 포함하여 messages의 어디에나 배치할 수 있습니다. 값은 수준 이름(low, medium, high, xhigh, max)입니다.

Claude Fable 5.1에서는 요청 간에 최상위 값을 변경하는 것보다 이 방식을 사용하는 것이 좋습니다. 최상위 값을 변경하면 캐시가 다시 시작될 뿐만 아니라 모델을 덜 안정적으로 유도합니다. 모델의 이전 응답은 이전 수준에서 작성되었으며, 모델은 그 응답과 일관성을 유지하려는 경향이 있기 때문입니다.

다음 요청의 최상위 effort

최상위 output_config.effort는 요청 전체에 적용됩니다. 대화의 이후 부분을 다른 수준으로 실행하려면 다음 요청에 새 값을 설정하세요. 최상위 effort는 렌더링된 프롬프트를 형성하므로, 요청 간에 이를 변경하면 이전 턴의 캐시된 접두사가 보존되지 않습니다. 긴 세션에 걸쳐 프롬프트 캐싱에 의존하고 모델이 메시지별 effort를 지원하지 않는다면, 시작 시 effort 수준을 선택하고 일정하게 유지하세요.

모범 사례

1. effort를 명시적으로 설정하세요: API 기본값은 high(Claude Opus 5.5와 Claude Haiku 5.5에서는 medium)이지만, 적절한 시작점은 모델과 워크로드에 따라 다릅니다.
2. 속도에 민감하거나 단순한 작업에는 low를 사용하세요: 지연 시간이 중요하거나 작업이 간단한 경우, low effort는 응답 시간과 비용을 크게 줄일 수 있습니다.
3. 사용 사례를 테스트하세요: effort 수준의 영향은 작업 유형에 따라 다릅니다. 배포하기 전에 특정 사용 사례에서 성능을 평가하세요.
4. 동적 effort를 고려하세요: 작업 복잡도에 따라 effort를 조정하세요. 단순한 쿼리에는 low effort가 적합할 수 있고, 에이전트 코딩과 복잡한 추론에는 high effort가 유리합니다. 하나의 대화 내에서 effort를 변경하기 전에 다음 항목을 참조하세요.
5. 캐시된 대화 내에서는 최상위 effort를 일정하게 유지하세요: 요청 간에 최상위 effort 값을 변경하면 프롬프트 캐싱이 무효화되므로, 캐시 적중에 의존하는 대화 내에서가 아니라 워크로드 간에 변경하세요. 지원하는 모델에서는 대신 캐시를 유지하는 메시지별 effort 변경을 사용하세요. 사고와 프롬프트 캐싱을 참조하세요.

다음 단계

Compatibility