Claude Code CLI 가이드: 설치, 설정, 명령어, 환경 변수

요약: Claude Code는 코드베이스를 읽고, 명령을 실행하며, 파일을 편집하는 에이전트형 CLI입니다. 구성, 권한, hooks, MCP, subagents라는 5가지 시스템이 이를 제어합니다. 매번 반드시 실행해야 하는 작업에는 프롬프트가 아닌 hooks를 사용하세요.

현재 상태(CLI v2.1.292, 2026년 10월 6일, npm latest와 next는 2.1.292, stable은 2.1.285):²³⁴

• 기본 모델: Claude Opus 5.5(claude-opus-5-5)는 Pro, Max, Team, Enterprise, Anthropic API, AWS의 Claude Platform, Amazon Bedrock, Google Cloud의 Agent Platform에서 기본으로 사용됩니다. Microsoft Foundry는 예외로, Sonnet 4.5가 기본이며 opus 별칭은 Opus 4.6을 의미합니다.²²¹
• Opus 5.5 요약: 토큰 100만 개당 $4/$20, 캐시 읽기는 $0.20이며, Anthropic API에서는 기본적으로 1M 컨텍스트를 제공합니다. v2.1.287부터는 Bedrock, Agent Platform, Foundry에서도 1M 컨텍스트를 기본으로 제공합니다. 기본 effort는 medium이며 thinking은 끌 수 없습니다. Fast mode에서는 $8/$40에 실행됩니다. 작업에 Opus가 필요하지 않다면 더 저렴한 Sonnet 5.5($2/$10, v2.1.284부터 Anthropic API에서 sonnet)를 선택할 수 있습니다.^{220222223228232}
• Auto mode는 모든 요금제와 제공업체에서 대화형 터미널 및 VS Code 세션의 초기 권한 모드입니다(v2.1.283-284). 반면 claude -p와 Agent SDK 세션은 --permission-mode auto를 전달하지 않으면 Manual로 시작합니다(v2.1.302에서는 서드 파티 제공업체를 사용하거나 텔레메트리를 끈 경우 Auto로 시작하도록 했던 v2.1.285의 변경을 되돌렸습니다).²⁷⁵ 안전 검사는 Enterprise와 Claude API 계정에서 무료로 서버에서 실행됩니다. AWS의 Claude Platform, Bedrock, Agent Platform, Foundry 및 게이트웨이를 통해서도 서버에서 실행되며, 불가능한 경우에는 요금이 부과되는 로컬 검사를 대신 사용합니다.^{219227228229230}
• AGENTS.md: v2.1.277부터 프로젝트에 CLAUDE.md가 없으면 AGENTS.md를 프로젝트 지침으로 읽습니다. 단, Bedrock처럼 기능 플래그를 가져오지 않는 환경과 설치 또는 업그레이드 후 첫 번째 세션은 예외입니다.²¹⁹²²³

릴리스별 변경 내역은 변경 기록에서 확인할 수 있습니다.

Claude Code는 에이전트형 시스템으로 작동합니다. 프로그래밍 지식을 갖춘 채팅 인터페이스가 아닙니다. CLI는 코드베이스를 읽고, 명령을 실행하고, 파일을 수정하고, git 워크플로를 관리하고, MCP를 통해 외부 서비스에 연결하며, 복잡한 작업을 전문 subagents에 위임합니다. 이 모든 과정은 개발자의 실제 작업 방식에 통합되는 명령줄 인터페이스를 통해 이루어집니다. 2026년 2월 기준 공개 GitHub 커밋의 4%(하루 약 135,000개)를 Claude Code가 작성하고 있습니다. 이는 연구 프리뷰 이후 13개월 만에 42,896배 성장한 수치이며, Anthropic 자체 코드의 90%도 AI가 작성했습니다.¹⁰³

Claude Code를 가볍게 사용하는 경우와 효과적으로 사용하는 경우의 차이는 5가지 핵심 시스템에서 결정됩니다. 이를 숙달하면 Claude Code를 강력한 생산성 증폭기로 활용할 수 있습니다.

1. 구성 계층 구조: 동작을 제어합니다
2. 권한 시스템: 작업 실행을 통제합니다
3. Hook 시스템: 확정적인 자동화를 구현합니다
4. MCP 프로토콜: 기능을 확장합니다
5. Subagent 시스템: 복잡한 다단계 작업을 처리합니다

핵심 요점

• 5가지 시스템이 활용 효과를 결정합니다: 구성 계층 구조, 권한, hooks, MCP, subagents는 동작부터 자동화까지 모든 것을 제어합니다.
• 작업을 위임 계층으로 넘기세요: subagents는 탐색 작업을 독립된 새 컨텍스트 창에서 수행하고 요약만 반환하므로 컨텍스트가 불필요하게 커지는 것을 방지합니다.
• Hooks는 실행을 보장하지만 프롬프트는 그렇지 않습니다: 모델의 동작과 관계없이 매번 실행해야 하는 린트, 포매팅, 보안 검사에는 hooks를 사용하세요.
• 모델을 단계별로 활용하면 품질을 유지하면서 비용을 절감할 수 있습니다: subagent의 탐색 작업은 더 저렴한 모델에 맡기고, 실제 아키텍처 추론이 필요한 작업에만 Opus를 사용하세요. 품질만이 유일한 기준이라면 Opus로 통일할 수도 있습니다.
• MCP는 Claude를 도구 체인에 연결합니다: 데이터베이스, GitHub, Sentry를 비롯한 3,000개 이상의 연동 기능으로 Claude의 기능을 파일 읽기와 bash 명령 이상으로 확장합니다.

저는 프로덕션 코드베이스, CI/CD 파이프라인, 엔터프라이즈 배포 환경에서 수개월 동안 Claude Code의 한계를 시험했습니다. 이 가이드는 그 경험을 집약해 제가 처음 시작할 때 있었으면 했던 완전한 참고 자료로 정리한 것입니다. 모든 기능에는 실제 구문, 실전 구성 예시, 숙련된 사용자도 놓치기 쉬운 예외 상황이 포함되어 있습니다.

필요한 경로 선택하기

이 가이드 활용 방법

이 문서는 5,000줄이 넘는 참고 자료이므로 처음부터 끝까지 모두 읽을 필요는 없습니다. 자신의 경험 수준에 맞는 지점부터 시작하세요.

브라우저의 Ctrl+F 또는 Cmd+F를 사용해 특정 플래그, 명령, 구성 키를 검색하세요. 마지막에 있는 빠른 참고 카드에서는 모든 주요 명령을 한눈에 확인할 수 있습니다.

관련 심층 분석

다음 블로그 게시물에서는 Claude Code의 특정 측면을 자세히 살펴봅니다.

60초 빠른 시작

Claude Code을 실행하고 결과만 확인하려면 다음 순서대로 진행하세요:

# 1. Install (pick one)
npm install -g @anthropic-ai/claude-code          # npm users
brew install anthropic/claude/claude              # macOS + Homebrew
curl -sL claude.ai/install.sh | sh                # native installer

# 2. Launch in any project directory
cd ~/your-project && claude

# 3. Authenticate (browser opens automatically on first run)
/login

# 4. Ask your first question
> What does this repo do? Read the key files and summarize.

이게 전부예요. 이 섹션 아래에서는 설치 옵션을 자세히 설명하고, 권한과 hooks를 설정하며, MCP 서버를 연결하고, 엔터프라이즈 배포까지 다뤄요. 하지만 시작하는 데는 이 내용이 필요하지 않아요.

사전 요구 사항: 기존 npm 방식에만 Node 22 이상이 필요해요(v2.1.198부터 18에서 상향되었으며, 현재 설치 문서에는 “Node.js 22 or later”라고 명시되어 있어요. 2026년 8월 7일 확인). 권장되는 네이티브 설치 프로그램은 Node에 의존하지 않아요. macOS / Linux / Windows 10 이상을 지원해요. Claude Pro, Max, Team, Enterprise 구독이나 토큰 사용량에 따라 요금을 지불하는 Anthropic API 키로 사용할 수 있어요. 플랫폼별 세부 정보, 문제 해결 방법, 네이티브 바이너리 방식(v2.1.113부터 기본값)은 Claude Code을 어떻게 설치하나요?를 참고하세요. 이 가이드의 최신 릴리스 근거는 릴리스마다 갱신돼요. 현재 확인 일자는 변경 로그의 최신 행을 참고하세요.²⁶⁷

Claude Code의 작동 방식: 이해를 위한 기본 구조

기능을 자세히 살펴보기 전에 Claude Code의 아키텍처가 모든 작업 방식에 어떤 영향을 미치는지 알아두세요. 시스템은 3개 계층으로 작동해요:

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │           Subagents (20 concurrent default)      │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

핵심 계층: 기본 대화가 이루어지는 곳이에요. 모든 메시지, 파일 읽기, 도구 출력은 공유 창의 컨텍스트를 사용해요(표준 200K 토큰⁹¹, Opus 4.6 또는 확장 컨텍스트 모델 사용 시 1M 토큰). 컨텍스트가 가득 차면 Claude는 이전 결정을 놓치기 시작하고 결과물의 품질도 떨어져요. 이 계층에서는 토큰마다 비용이 발생해요.

위임 계층: Subagents는 새로운 컨텍스트로 생성되어 특정 작업에 집중한 뒤 요약을 반환해요. 탐색 결과 전체가 기본 대화의 컨텍스트를 부풀리지 않고 결론만 돌아와요. 탐색 작업에는 더 저렴한 모델 등급을 사용하거나, 비용보다 품질이 더 중요하다면 모든 작업에 기본 모델을 사용할 수 있어요.

확장 계층: MCP는 외부 서비스(데이터베이스, GitHub, Sentry)를 연결해요. Hooks는 모델의 동작과 관계없이 셸 명령이 반드시 실행되도록 보장해요. Skills는 Claude가 자동으로 적용하는 분야별 전문 지식을 담아요. Plugins는 이 모든 요소를 배포할 수 있도록 하나로 묶어요.

핵심 요점: 대부분의 사용자는 핵심 계층에서만 작업하면서 컨텍스트와 비용이 계속 늘어나는 상황을 지켜봐요. 숙련된 사용자는 탐색과 전문 작업을 위임 계층으로 보내고, 자신의 작업 흐름에 맞게 확장 계층을 설정한 다음, 핵심 계층은 조율과 최종 결정에만 사용해요.

목차

1. Claude Code을 어떻게 설치하나요?
2. 빠른 시작: 첫 번째 세션
3. 핵심 상호작용 모드
4. 설정 시스템 자세히 알아보기
5. 어떤 모델을 선택해야 하나요?
6. Claude Code의 비용은 얼마인가요?
7. 의사 결정 프레임워크
8. 권한 시스템은 어떻게 작동하나요?
9. Hooks는 어떻게 작동하나요?
10. MCP(Model Context Protocol)란 무엇인가요?
11. Subagents란 무엇인가요?
12. 확장 사고 모드란 무엇인가요?
13. 출력 스타일
14. Slash Commands
15. Skills는 어떻게 작동하나요?
16. Plugin 시스템
17. 메모리는 어떻게 작동하나요?
18. 이미지 및 멀티모달 입력
19. 음성 모드
20. Git 연동은 어떻게 작동하나요?
21. IDE에서 Claude Code을 어떻게 사용하나요?
22. 고급 사용 패턴
23. 원격 및 백그라운드 에이전트 [연구 프리뷰]
24. Chrome의 Claude
25. Slack의 Claude Code [연구 프리뷰]
26. 웹의 Claude Code [연구 프리뷰]
27. Microsoft 365의 Claude(2026년 5월)
28. 성능 최적화
29. 문제를 어떻게 디버깅하나요?
30. 엔터프라이즈 배포
31. 키보드 단축키 참고 자료
32. 모범 사례
33. 작업 흐름 예시
34. 마이그레이션 가이드
35. 대상별 안내
36. 빠른 참조 카드
37. 변경 로그
38. 참고 자료

Claude Code를 어떻게 설치합니까?

시스템 요구 사항

Claude Code는 macOS 13 이상, Ubuntu 20.04 이상/Debian 10 이상, Windows 10 이상(네이티브 또는 WSL)에서 실행됩니다. 시스템에는 최소 4GB RAM과 활성 인터넷 연결이 필요합니다.⁹² 셸은 Bash, Zsh 또는 Fish와 가장 잘 호환됩니다.

Windows에서는 WSL 1과 WSL 2를 모두 사용할 수 있습니다. 네이티브 Windows를 선호한다면 Git Bash도 사용할 수 있습니다. Alpine Linux와 기타 musl 기반 시스템에는 추가 패키지가 필요합니다.

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

플랫폼 지원표

설치, 업데이트, 제거 한눈에 보기

한 화면에서 모든 방식과 명령, 버전 확인 방법을 빠르게 찾아볼 수 있습니다. 아래 하위 섹션에서는 방식별 세부 사항과 문제 해결 방법을 다룹니다.

v2.1.113부터 정식 CLI는 번들 JavaScript 대신 플랫폼별 선택적 의존성을 통해 네이티브 Claude Code 바이너리를 실행합니다. 테스트를 거친 배포판을 사용하려면 네이티브 설치 프로그램을 사용하세요. npm 경로도 여전히 작동하지만, v2.1.15에서 처음 추가된 사용 중단 안내가 표시됩니다.

설치 방식

네이티브 설치(권장)

네이티브 바이너리는 Node.js 의존성 없이 가장 깔끔한 환경을 제공합니다.

# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

특정 버전을 설치하려면 다음을 사용합니다.

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

프록시 또는 게이트웨이 환경에서 절대 고정해서는 안 되는 버전은 2.1.275입니다. 이 빌드에서는 ANTHROPIC_BASE_URL이 프록시나 게이트웨이를 가리킬 때 모든 요청이 400 ... Input tag 'advisor_20260301' 오류로 실패합니다. 2.1.276에서 이 회귀 문제가 수정되었습니다.²¹⁸

NPM 설치(사용 중단)

참고: v2.1.15부터 npm 설치 시 사용 중단 안내가 표시됩니다. 이제 네이티브 바이너리가 권장 설치 방식입니다. claude install을 사용해 이전하세요.

npm이 여전히 필요한 레거시 환경에서는 다음을 사용합니다.

npm install -g @anthropic-ai/claude-code

npm 설치 시 절대로 sudo를 사용하지 마세요. 이후 모든 과정이 복잡해지는 권한 문제가 발생합니다.

기존 설치에서 이전

기존 npm 기반 설치가 있다면 네이티브 바이너리로 이전하세요.

claude install

인증 옵션

Claude Code는 장단점이 서로 다른 세 가지 인증 경로를 지원합니다.

Claude Console(API 결제)

platform.claude.com(이전 주소: console.anthropic.com)을 통해 Anthropic의 API에 직접 연결합니다. 계정을 만들고 결제를 설정한 다음 CLI를 통해 인증하세요. Console은 전체 API 접근 권한과 사용량 기반 결제를 제공합니다. 전용 “Claude Code” 작업 공간이 자동으로 생성됩니다. 이 작업 공간에서는 API 키를 만들 수 없지만 사용량은 모니터링할 수 있습니다. v2.1.243부터 /login → Anthropic Console에는 API 키 생성과 함께 키가 필요 없는 “Console 계정으로 로그인”(권장) 경로가 제공되므로, API 키를 허용하지 않는 조직도 Console 자격 증명으로 로그인할 수 있습니다.²⁵⁰

Claude Pro 또는 Max 구독

claude.ai 계정 자격 증명을 사용합니다. 구독 하나로 웹 인터페이스와 CLI 사용량이 모두 월간 요금제에 포함됩니다. 예측 가능한 비용을 원하는 개인 사용자는 구독을 통해 결제를 간소화할 수 있습니다.

엔터프라이즈 플랫폼

AWS Bedrock, Google Vertex AI, Microsoft Foundry는 각각 기존 클라우드 결제 관계를 활용하는 엔터프라이즈급 접근 방식을 제공합니다. Bedrock 설정 마법사(v2.1.92 이상): 로그인 화면의 대화형 마법사가 AWS 인증, 리전 선택, 자격 증명 확인, 모델 고정을 안내합니다.¹³⁷ Vertex AI 설정 마법사(v2.1.98 이상): Google Cloud용 마법사가 GCP 인증, 프로젝트 및 리전 구성, 자격 증명 확인, 모델 고정을 안내합니다.¹⁴² Vertex AI mTLS Workload Identity Federation(v2.1.121 이상): 이제 Vertex AI는 X.509 인증서 기반 Workload Identity Federation(mTLS Application Default Credentials)을 지원합니다. 클라이언트 인증서로 수명이 짧은 GCP 토큰을 발급하므로 서비스 계정 JSON이 필요하지 않습니다.¹⁵⁴ 운영체제 CA 인증서 신뢰(v2.1.101 이상): 이제 엔터프라이즈 TLS 프록시가 기본적으로 작동하며, Claude Code는 운영체제 인증서 저장소를 신뢰합니다. 번들 CA만 사용하려면 CLAUDE_CODE_CERT_STORE=bundled를 설정하세요.¹⁴³

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

# Amazon Bedrock via Mantle (v2.1.94+)
export CLAUDE_CODE_USE_MANTLE=1

프록시 뒤에서 또는 LLM 게이트웨이를 통해 엔터프라이즈 환경에 배포하려면 다음을 사용합니다.

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

게이트웨이 힌트 헤더(v2.1.273): Claude Code는 LLM 게이트웨이가 라우팅하고 관찰할 수 있는 요청 헤더인 x-claude-code-request-class, x-claude-code-agent-type, x-claude-code-prev-tool-durations, x-claude-code-compaction, x-claude-code-context-compacted를 추가할 수 있습니다. v2.1.283부터는 하나의 사용자 프롬프트를 처리하는 모든 요청에서 공유되는 임의의 UUID인 x-claude-code-prompt-id도 추가할 수 있으며, 여기에는 subagent 턴도 포함됩니다.²¹⁷²²⁶ 사용자 지정 기본 URL이나 Bedrock 같은 타사 제공자를 통할 때는 CLAUDE_CODE_GATEWAY_HINT_HEADERS=1을 설정해야 헤더가 활성화됩니다. 게이트웨이 프로토콜 문서에 따르면 Anthropic API에 직접 연결하면 헤더가 기본적으로 전송되며, CLAUDE_CODE_GATEWAY_HINT_HEADERS=0을 설정하면 모든 연결에서 전송을 중지합니다.²²⁷

확인

claude doctor

이 명령은 설치 유형, 버전, 시스템 구성, 감지된 문제를 보고합니다.

인증 관리(v2.1.41 이상)

REPL에 들어가지 않고 인증을 관리할 수 있습니다.⁹⁰

claude auth login          # Log in or switch accounts
claude auth status         # Check current auth state (account, plan, expiry)
claude auth logout         # Clear stored credentials

v2.1.268부터 claude auth status --json에는 CLI가 실제로 읽고 있는 구성 디렉터리인 configDirectory가 포함됩니다. CLAUDE_CONFIG_DIR 간접 설정으로 인해 경로가 불분명할 때 유용합니다.²¹⁶

v2.1.273부터 Claude 계정으로 로그인할 때 claude.ai plugins에 대한 접근 권한도 요청합니다.²¹⁷

v2.1.286부터 claude auth status는 Console 로그인에 저장된 API 키를 claude.ai 대신 api_key로 보고합니다.²³¹

계정이나 조직을 전환하는 일반적인 작업 흐름은 다음과 같습니다.

claude auth logout && claude auth login

인증 실패 문제 해결은 문제를 어떻게 디버깅합니까?도 참조하세요.

업데이트

Claude Code는 기본적으로 자동 업데이트되며, 시작할 때와 세션 중에 주기적으로 업데이트를 확인합니다. 업데이트는 백그라운드에서 다운로드되고 다음 실행 시 적용됩니다.

자동 업데이트를 비활성화하려면 다음을 사용합니다.

export DISABLE_AUTOUPDATER=1

또는 settings.json에서 다음과 같이 설정합니다.

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

수동 업데이트:

claude update

제거

네이티브 설치(macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

네이티브 설치(Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

구성 정리(모든 설정 제거):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

빠른 시작: 첫 세션

1. 설치하고 실행하세요:

claude                           # Launch in current directory

2. 프로젝트로 이동하세요:

cd ~/my-project && claude        # Or launch from any git repo

3. Claude에게 작업을 요청하세요:

> "Explain the architecture of this project"
> "Find all TODO comments and create a summary"
> "Add input validation to the signup form"

4. 세션 중에 키보드 단축키를 사용하세요:

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. 나중에 이어서 작업하세요:

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

전문가 팁: 프로젝트 루트에 빌드 명령어, 코딩 규칙, 아키텍처 참고 사항을 담은 CLAUDE.md 파일을 만드세요. Claude은 세션을 시작할 때마다 이 파일을 읽어요. 품질을 높이는 데 가장 큰 효과를 내는 한 가지 방법이에요.

핵심 상호작용 모드

대화형 REPL

인수 없이 Claude Code을 실행하여 대화형 읽기-평가-출력 루프로 들어갑니다.

cd your-project
claude

REPL은 여러 차례의 대화에 걸쳐 대화 맥락을 유지합니다. 쿼리를 직접 입력하고 응답을 받은 다음, /exit 또는 Ctrl+D로 종료할 때까지 계속할 수 있습니다.

초기 프롬프트와 함께 시작하여 세션의 초점을 설정합니다.

claude "explain the authentication flow in this project"

전문가 팁: REPL은 압축이 발생해도 상태를 유지합니다. 맥락이 너무 길어지면 Claude은 핵심 결정과 코드 조각을 보존하면서 이전 대화를 자동으로 요약합니다. /compact로 직접 실행하거나 보존할 내용에 관한 사용자 지정 지침을 추가할 수 있습니다.

비대화형 모드

출력 모드(-p)는 단일 쿼리를 실행한 후 종료합니다.

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

스크립트에서 파싱하기 적합한 구조화된 출력은 다음과 같이 생성합니다.

claude -p "count lines by file type" --output-format json

JSON 출력에는 자동화에 필요한 모든 정보가 포함됩니다.

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

스트리밍 출력을 실시간으로 처리하려면 다음과 같이 실행합니다.

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r 'select(.result) | .result'
done

출력 형식 옵션:

stream-json의 subagents 텍스트(v2.1.211+): 기본적으로 stream-json 출력에는 기본 세션의 이벤트만 포함되며, subagents 내부에서 수행한 작업은 요약으로 표시됩니다. --forward-subagent-text 플래그 또는 CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1을 사용하면 subagents의 텍스트와 사고 출력도 스트림으로 전달되므로, 하네스와 로그 파이프라인은 최종 보고서만 보는 대신 위임된 작업이 진행되는 과정을 관찰할 수 있습니다.¹⁸⁸

중첩된 subagents도 이제 전달됩니다(v2.1.219). 원래는 깊이 1의 subagents만 표시되었습니다. 이제 깊이 2 이상에서 생성된 subagents도 전달된 스트림에 나타나며, 각 항목은 해당 subagent를 생성한 Agent 호출의 tool_use 아이디를 키로 사용합니다. 따라서 파이프라인은 평면적인 텍스트 목록만 보는 대신 위임 트리를 재구성할 수 있습니다. 이 변경 사항은 같은 릴리스에서 기본적으로 깊이 3까지 중첩 생성을 복원한 것과 직접 연결됩니다. 이 기능이 없었다면 3개 계층 가운데 2개는 보이지 않았을 것입니다.¹⁹⁶

백그라운드로 전환된 subagents의 출력도 더 이상 사라지지 않습니다(v2.1.273): 실행 도중 subagent가 백그라운드로 이동하면(예: CLAUDE_AUTO_BACKGROUND_TASKS 사용) SDK 및 stream-json 출력에서 해당 subagent의 남은 메시지와 최종 보고서가 누락되던 문제가 해결되었습니다.²¹⁷

중단된 -p 실행은 이제 오류를 반환합니다(v2.1.277): 내부 오류가 발생한 claude -p 및 Agent SDK 세션이 이전에는 결과 없이 멈출 수 있었습니다. 외부 제한 시간이 지나야 실행이 끝나는 파이프라인에는 최악의 실패 방식이었습니다. 이제 오류를 보고하고 코드 1로 종료하므로, 아래 종료 코드 표가 다시 전체 규약을 나타냅니다. 같은 릴리스부터 헤드리스 세션은 종료할 때 비용 및 사용량 합계도 저장합니다. 따라서 헤드리스 재개(claude -p --resume, SDK, VS Code 확장 프로그램 창 다시 로드) 시 세션 합계가 더 이상 0부터 시작하지 않으며, 재개된 헤드리스 실행 전반의 비용 집계가 실제보다 적게 계산되지 않습니다.²¹⁹

종료 코드:

-p 모드에서 에이전트 동작 제어하기:

# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

# Allow specific tools without prompting
claude -p "fix lint errors" --allowedTools "Edit,Bash(npm run lint)"

# Use with a specific model
claude -p "explain this code" --model claude-sonnet-5

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+); only CLI-named MCP servers (v2.1.286)
claude -p "count files" --bare

# Channel permission relay: send approval prompts to Telegram/Discord (v2.1.81+)
claude --channels

# Restricted mode for eval harnesses and shared machines (v2.1.248+)
claude --restricted -p "query" --tools "Read,Grep,Glob"

# Unattended hosts: deny anything that would prompt (v2.1.259+)
claude -p "run the nightly checks" --permission-prompts none

제한 모드(v2.1.248+): --restricted 또는 CLAUDE_CODE_RESTRICTED=1은 공유 컴퓨터에서 claude를 구동하는 평가 하네스를 위해 만들어졌습니다. 명령이나 코드를 실행하는 기본 제공 도구와 WebFetch를 제거하며, --tools에서 각 도구를 개별적으로 지정해야만 사용할 수 있습니다. default 사전 설정은 인정되지 않습니다. 또한 기본 제공 파일 도구를 작업 디렉터리로 제한하고, 관리형 설정과 --settings만 불러오며(사용자, 프로젝트, 로컬 설정 파일은 무시), bypassPermissions와 클라우드 세션 생성을 거부합니다.²⁰⁶²⁰⁹

--permission-prompts none(v2.1.259): 무인 호스트를 위한 보조 옵션입니다. 권한 프롬프트를 표시해야 하는 모든 작업은 자동으로 거부되지만, 자동 모드를 포함한 활성 권한 모드는 사용자 없이 내릴 수 있는 모든 결정을 계속 처리합니다. 이 옵션을 권한 프롬프트를 거부하는 대신 MCP 도구에 위임하는 --permission-prompt-tool과 혼동하지 마세요. CLI 참조 문서에는 아직 새 플래그가 나와 있지 않으며, CHANGELOG가 출처입니다.²¹¹

비대화형 세션에서도 cd가 대화 간에 유지됩니다(v2.1.265): stream-json 입력을 받는 -p 세션, Agent SDK 세션 및 클라우드 세션은 새 사용자 메시지가 입력될 때마다 셸 작업 디렉터리를 더 이상 초기화하지 않습니다. 한 차례의 대화에서 실행한 cd가 이제 다음 대화에서도 유지됩니다.²¹⁵

--system-prompt-snapshot off(v2.1.267): 기본적으로 대화는 모든 요청에서 기록된 시스템 프롬프트를 재사용합니다. 이 플래그를 사용하면 요청마다 시스템 프롬프트를 새로 렌더링합니다. 프롬프트 텍스트를 반복해서 수정할 때 각 실행이 스냅샷 대신 최신 편집 내용을 반영하도록 전환하는 옵션이지만, 스냅샷이 보호하려는 프롬프트 캐시 안정성은 낮아집니다.²¹⁶

--bare가 제한 사항을 확실히 적용합니다(v2.1.286): 이제 --bare는 명령줄에서 지정한 MCP 서버에만 연결하고, 모델에 시스템 알림을 전송하지 않으며, 백그라운드 작업을 시작하지 않습니다. 제한 시간에 도달한 셸 명령은 백그라운드로 이동하지 않고 중지됩니다. 헤드리스 문서에 따르면 v2.1.286 이전에는 이러한 제한이 일부만 적용되었으며, 스크립트 및 SDK 호출에는 --bare 사용을 권장합니다.²³¹²³³

CI/CD 통합 패턴:

# In a GitHub Action or CI pipeline
result=$(claude -p "review this diff for security issues" --output-format json 2>/dev/null)
is_error=$(echo "$result" | jq -r '.is_error')
if [ "$is_error" = "true" ]; then
  echo "Review failed"
  exit 1
fi
echo "$result" | jq -r '.result'

세션 관리

세션은 나중에 이어서 작업할 수 있도록 대화 기록을 유지합니다. 복잡한 다중 세션 작업에서는 세션 유지가 필수적입니다.

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

# Open the Claude desktop app on this directory, or on a session (v2.1.285)
claude --desktop
claude --desktop --continue

/cd로 실행 중인 세션 이동하기(v2.1.169+; v2.1.246부터 설정 즉시 적용): /cd path는 프롬프트 캐시를 중단하지 않고 작업 디렉터리를 변경합니다. v2.1.246부터는 새 디렉터리의 프로젝트 설정, hooks, .mcp.json 서버(일반적인 승인 프롬프트 적용), skills 및 agents가 --resume을 기다리지 않고 이동 직후 적용됩니다.²⁶²²⁴⁹

PR 연결 세션(v2.1.27+, v2.1.119+에서 확장): 특정 풀 리퀘스트 또는 머지 리퀘스트에 연결된 세션을 시작합니다. v2.1.119부터 --from-pr은 github.com뿐만 아니라 GitLab MR, Bitbucket PR 및 GitHub Enterprise PR URL도 지원합니다.⁷⁴¹⁵²

claude --from-pr 123                                                # GitHub PR number (assumes current repo's remote)
claude --from-pr https://github.com/org/repo/pull/123               # GitHub URL
claude --from-pr https://gitlab.com/org/repo/-/merge_requests/45    # GitLab MR (v2.1.119+)
claude --from-pr https://bitbucket.org/org/repo/pull-requests/67    # Bitbucket PR (v2.1.119+)
claude --from-pr https://ghe.example.com/org/repo/pull/89           # GitHub Enterprise (v2.1.119+)

세션 도중 gh pr create로 PR을 만들면 세션이 해당 PR에 자동으로 연결됩니다. 따라서 나중에 특정 PR의 작업을 쉽게 재개할 수 있습니다. 하단의 PR 배지는 prUrlTemplate 설정(v2.1.119+)을 통해 사용자 지정 코드 검토 URL을 가리킬 수 있습니다. 팀에서 PR을 별도의 검토 도구에 연결할 때 유용합니다.¹⁵²

/resume에서 PR URL을 사용할 수 있습니다(v2.1.122+). 이제 /resume 검색 상자에 PR URL을 붙여 넣으면 해당 PR을 처음 만든 세션을 찾습니다. github.com, GitHub Enterprise, gitlab.com(자체 호스팅 GitLab 포함) 및 bitbucket.org에서 작동합니다.¹⁵⁴

이름이 지정된 세션: 시작할 때 또는 세션 도중에 세션 이름을 지정합니다.

# Name session at startup (v2.1.76+)
claude -n "auth-refactor"                  # --name flag sets display name[^125]

# Name current session
> /rename auth-refactor

# Resume by name or number
> /resume 1                    # Resume first session
> /resume auth-refactor        # Resume by name
claude --resume auth-refactor  # Resume from terminal
claude -r 3                    # Resume by number from terminal

# Fork for parallel exploration
claude --resume auth-refactor --fork-session

참고: --session-id에는 유효한 UUID(예: 550e8400-e29b-41d4-a716-446655440000)가 필요합니다. 사람이 읽을 수 있는 세션 이름을 지정하려면 /rename과 --resume을 대신 사용하세요.

/fork는 백그라운드 세션을 생성하고, /subtask는 세션 내부 포크를 수행합니다(v2.1.212). 이제 /fork 명령은 현재 대화를 새 백그라운드 세션으로 복사합니다. 이 세션은 claude agents에 별도의 행으로 표시되므로, 기본 세션에서 작업을 계속하면서 복사본을 보내 다른 대안을 탐색하게 할 수 있습니다. 현재 세션 내부에서 포크하던 이전 동작은 새로운 이름인 /subtask로 계속 제공됩니다.¹⁸⁹ v2.1.214부터 포크로 시작된 세션은 SessionStart hook 소스를 이전의 "resume" 대신 "fork"로 보고하므로, 소스를 기준으로 일치 여부를 판단하는 hooks가 둘을 구분할 수 있습니다.¹⁹⁰ v2.1.216에서는 /fork 확인 메시지가 새 세션 이름과 claude attach 아이디를 표시하는 한 줄로 간결해졌습니다.¹⁹² v2.1.221부터 포크된 세션은 원래 세션의 체크아웃에서 작업하는 대신 자체 worktree를 생성합니다. 이제 다른 대안을 탐색하는 포크가 기본 세션의 커밋되지 않은 파일과 충돌하지 않으므로, 실험을 위해 복사본을 보낼 때 발생하던 위험 요소가 사라졌습니다.¹⁹⁹ v2.1.232부터는 포크가 subagents에도 기본으로 적용됩니다. subagent_type: "fork" subagent는 전체 대화와 프롬프트 캐시를 상속하며, 대화형 세션에서 팀원이 아닌 agent를 생성하면 이제 기본적으로 백그라운드에서 실행됩니다.²⁵⁵

Claude Code은 세션을 JSONL 기록으로 저장합니다. Agent 실행에는 고유한 agentId 값이 할당되며, 기록은 agent-{agentId}.jsonl로 저장됩니다. 세션을 재개하면 이전 대화의 전체 맥락이 보존됩니다.

계획 모드

계획 모드에서는 Claude이 읽기 전용 탐색만 수행하도록 제한합니다. 파일 편집, bash 실행 및 파괴적인 작업은 할 수 없습니다. Claude은 구현 방식을 설계하고 계획 파일에 작성한 후, 작업을 실행하기 전에 사용자의 승인을 기다립니다.

계획 모드 시작하기:

# Cycle through modes during a session
Shift+Tab           # Cycles: normal → plan → auto-accept

# Or use the /plan command with an optional description (v2.1.72+)
/plan                                     # Enter plan mode
/plan refactor the auth module            # Enter plan mode with a description

# Or ask Claude directly
"Plan how to refactor the auth module"   # Claude may enter plan mode automatically

작동 방식:

1. Claude이 계획 모드로 들어갑니다(복잡한 작업에서는 자동으로 진입하거나 Shift+Tab으로 실행)
2. 읽기 전용 도구인 Read, Glob, Grep, WebSearch, WebFetch를 사용해 코드베이스를 탐색합니다
3. .claude/plans/{session-slug}.md에 계획을 작성합니다
4. ExitPlanMode로 계획 모드를 종료하고 검토할 계획을 제시합니다
5. 사용자가 승인하거나, 변경을 요청하거나, 거부합니다

계획 모드에서 사용할 수 있는 도구: Read, Glob, Grep, LS, WebSearch, WebFetch, AskUserQuestion. 편집 도구(Edit, Write, Bash, NotebookEdit)는 차단됩니다.

계획 승인 후(v2.1.32+): Claude은 다음 3가지 옵션을 제공합니다. - “예, 맥락을 지우고 편집을 자동 승인합니다”(Shift+Tab) — 계획을 실행할 수 있도록 전체 맥락을 새로 시작합니다 - “예, 편집을 직접 승인합니다” — 맥락을 유지하고 각 변경 사항을 사용자가 승인합니다 - “예, 편집을 자동 승인합니다” — 맥락을 유지하며 Claude이 변경별 승인 없이 실행합니다

승인 시 맥락 자동 지우기가 권장되는 작업 흐름입니다. 계획에 새로운 맥락 창 전체를 제공하므로 계획 준수율이 크게 향상됩니다. 이전 대화가 방해하지 않아 Claude이 더 오랫동안 계획대로 진행합니다.

계획 모드를 사용해야 할 때: - 아키텍처 결정이 필요한 새 기능 구현 - 먼저 접근 방식을 검토하려는 여러 파일의 리팩터링 - 수정하기 전에 탐색해야 하는 익숙하지 않은 코드베이스 - 유효한 접근 방식이 여러 개이고 사용자의 의견을 반영하려는 모든 작업

전문가 팁: 계획 모드에 더 많은 시간을 들일수록 Claude이 구현에 성공할 가능성이 높아집니다. 계획 모드는 사실상 부담 없이 탐색할 수 있는 환경입니다. 위험한 도구 호출도, 낭비되는 편집도 없습니다. 적극적으로 활용하세요.

화면 읽기 프로그램 모드(v2.1.208)

Claude Code에는 보조 기술에 맞게 터미널 UI를 조정하는 전용 화면 읽기 프로그램 모드가 포함되어 있습니다. 다음 3가지 방법 가운데 하나로 활성화할 수 있습니다.¹⁸⁶

# Flag at launch
claude --ax-screen-reader

# Environment variable
export CLAUDE_AX_SCREEN_READER=1

# Or persistently in settings.json
{ "axScreenReader": true }

Anthropic의 공식 문서에 새로 추가된 접근성 페이지에서 이 모드와 상호작용 방식을 설명합니다.¹⁸⁶

각 줄 앞에서 일시 정지하지 않음(v2.1.287): 이제 화면 읽기 프로그램 모드는 새 줄이나 변경된 줄을 출력하기 전에 커서를 줄 시작 부분에 두고 일시 정지하지 않습니다. CLAUDE_AX_PREPARK_MS는 해당 일시 정지 시간을 밀리초 단위로 설정합니다. 기본값이 기존 50에서 0으로 변경되었으므로, 이전 동작을 복원하려면 CLAUDE_AX_PREPARK_MS=50으로 설정하세요. 같은 릴리스에서는 검색 상자에서 커서가 입력한 텍스트와 떨어져 표시되는 문제, 편집 승인 프롬프트에서 변경된 줄이 누락되는 문제 등 여러 화면 읽기 프로그램 관련 문제도 해결되었습니다.²³²²³³

구성 시스템 심층 분석

Claude Code는 계층형 구성 시스템을 사용합니다. 상위 계층이 하위 계층을 재정의하고 엔터프라이즈 설정은 어떤 방법으로도 우회할 수 없으므로, 이 계층 구조를 반드시 이해해야 합니다.

구성 계층 구조

프롬프트에서 설정하기: /config key=value (v2.1.181)

v2.1.181부터 /config key=value를 사용하면 대화형 /config UI를 열지 않고도 프롬프트에서 바로 모든 설정을 지정할 수 있습니다. 예를 들어 /config thinking=false처럼 입력하면 되며, 대화형 세션, -p 세션, Remote Control 세션에서 모두 작동합니다. /config --help(v2.1.183)를 실행하면 사용 가능한 단축 키 목록이 표시됩니다. v2.1.183에서는 대화형 /config UI도 바뀌었습니다. 이제 Enter와 Space 모두 선택한 설정을 전환하고, Esc를 누르면 변경 사항이 저장된 뒤 창이 닫힙니다(이전에는 변경 사항이 되돌려졌습니다).¹⁷⁴

settings.json 전체 레퍼런스

주요 옵션을 모두 보여 주는 전체 구성 예시입니다:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "label": "Team tips",
    "tips": [
      "Custom tip 1",
      {"id": "tip-2", "text": "Custom tip 2", "cooldownSessions": 5, "priority": 1}
    ],
    "tipsFile": "~/.claude/team-tips.json",
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "claude-opus-5-5": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",
    "claude-sonnet-5": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

skillOverrides는 팀이 대규모 skill 라이브러리를 운영하면서도 런타임 노출 범위는 더 엄격하게 제한하고 싶을 때 유용합니다. off는 모델과 슬래시 선택기 양쪽에서 skill을 숨기고, user-invocable-only는 모델의 선택 대상에서는 제외하되 이름으로 호출할 수 있게 유지하며, name-only는 전체 설명 없이 skill 이름만 노출합니다.¹⁵⁶

새로운 설정 (v2.1.174–176): - availableModels / enforceAvailableModels (managed, v2.1.175+): availableModels 허용 목록은 세션에서 선택할 수 있는 모델을 제한합니다. enforceAvailableModels: true를 설정하면 허용 목록이 Default 모델에도 적용됩니다. Default가 허용되지 않은 모델로 결정되는 경우에는 허용된 첫 번째 모델로 대체되며, 사용자 설정이나 프로젝트 설정으로 관리형 availableModels 목록을 더 이상 넓힐 수 없습니다. 함께 배포된 수정 사항(v2.1.176)은 별칭으로 모델을 고를 때 ANTHROPIC_DEFAULT_*_MODEL을 통해 차단된 모델로 우회될 수 있던 허점을 막았고, 이제 /fast도 허용 목록 밖의 모델로는 전환되지 않습니다.¹⁷² v2.1.187부터 조직은 /model 선택기, --model, /model, ANTHROPIC_MODEL 전반에 모델 제한을 직접 적용할 수 있습니다. 제한된 모델을 선택하면 “restricted by your organization’s settings” 메시지가 표시됩니다.¹⁷⁶ - language (v2.1.176 개선): 응답 언어 설정 외에도, 이제 세션 제목이 기본적으로 대화에 사용된 언어로 생성됩니다. 제목 언어를 특정 언어로 고정하려면 language를 설정하세요.¹⁷² - footerLinksRegexes (v2.1.176): 정규식과 일치하는 링크를 푸터 행에 배지로 표시합니다. 사용자 설정 또는 관리형 설정에서 구성할 수 있습니다.¹⁷² - wheelScrollAccelerationEnabled (v2.1.174): 전체 화면 모드에서 마우스 휠 스크롤 가속을 끄려면 false로 설정하세요.¹⁷²

새로운 설정 (v2.1.207–v2.1.212): - vimInsertModeRemaps (v2.1.208): vim 삽입 모드용 사용자 지정 키 리매핑입니다. 대표적인 예는 jj를 Escape에 매핑하는 것입니다(Vim 모드 참조).¹⁸⁶ - axScreenReader (v2.1.208): 화면 낭독기 모드를 항상 켜 둡니다(화면 낭독기 모드 참조).¹⁸⁶ - processWrapper (v2.1.208): Claude Code이 자체적으로 생성하는 모든 프로세스를 래퍼 실행 파일을 거쳐 실행합니다. 기업용 런처를 위해 만들어진 설정입니다(기업용 런처 참조).¹⁸⁶ - autoMode 소스 제한 (v2.1.207): autoMode 설정은 이제 저장소의 .claude/settings.local.json에서 읽지 않습니다. 대신 ~/.claude/settings.json에서 설정하세요. 이 변경으로 복제한 저장소가 auto mode 설정을 함께 배포할 수 있던 경로가 막혔습니다.¹⁸⁵

새로운 설정 (v2.1.217):

• emojiCompletionEnabled (v2.1.217): 프롬프트 입력창의 이모지 단축 코드 자동 완성 기능입니다. :heart:를 입력하면 ❤️가 삽입되고, :hea처럼 일부만 입력하면 후보가 제안됩니다. 기본적으로 켜져 있으며, 끄려면 false로 설정하세요.¹⁹⁴

새로운 설정 (v2.1.219): - sandbox.network.strictAllowlist (v2.1.219): 샌드박스에서 실행되는 명령이 허용 목록에 없는 호스트에 접근하면 권한 대화 상자를 띄우지 않고 확인 없이 차단합니다. Sandbox Mode를 참고하세요.¹⁹⁶ - workflowSizeGuideline (v2.1.219): /config에서만이 아니라 사용자, 프로젝트, managed 등 어떤 설정 파일에서도 권고용 Dynamic workflow 크기 가이드라인을 설정할 수 있습니다. Dynamic workflow의 기본 가이드라인은 medium(“에이전트 15개 미만을 목표로 하세요”)입니다. 설정 파일이 값을 지정하는 동안에는 /config의 해당 항목이 표시되지 않습니다. 강제 상한이 아니라 권고 사항입니다. Subagents를 참조하세요.¹⁹⁶

새로운 설정 (v2.1.242–243): - modelPicker (user 또는 managed, v2.1.242+): 순서와 레이블을 지정한 모델 목록으로 /model 선택기를 구성합니다. options 배열(각 행은 필수 model과 선택적 label, description으로 이루어지며, model은 입력한 그대로 사용되므로 별칭, Anthropic ID, Bedrock/Vertex/Foundry/게이트웨이 ID를 모두 쓸 수 있습니다)과 선택적 replaceBuiltInOptions Boolean(기본값인 false는 기본 제공 목록 뒤에 행을 추가하고, true는 사용자가 지정한 행과 Default, 세션에서 이미 실행 중인 모델만 표시합니다)을 가진 객체입니다. Claude Code은 이 키를 managed settings, --settings, user settings에서 읽고 project settings와 local settings에서는 무시합니다. 따라서 복제한 저장소가 선택기의 레이블을 바꿀 수 없습니다. 이 키를 설정한 소스 중 가장 우선순위가 높은 소스가 전체 목록을 결정합니다. availableModels 허용 목록은 여전히 모든 행에 적용되며, 레이블은 선택기에 표시되는 내용만 바꿀 뿐 실제로 실행되는 모델은 바꾸지 않습니다.²⁵⁰²⁴⁸ - promptCacheTtl / subagentPromptCacheTtl (모든 파일, v2.1.242+): 요청 버킷별로 "5m" 또는 "1h"를 지정합니다. 이를 통해 API 키 사용자와 클라우드 제공업체 사용자는 메인 대화의 캐시를 1시간으로 유지하면서 subagents의 캐시는 5분으로 둘 수 있습니다. 캐싱 전략을 참고하세요.²⁵⁰²⁴⁸ - modelPricing (managed, v2.1.243+): 조직이 계약한 모델별 요금과 할인 배수입니다. /cost, 상태 표시줄, 텔레메트리 비용 수치에서 정가 대신 이 값을 사용합니다. 비용 확인을 참고하세요.²⁵⁰

새로운 설정 (v2.1.247): - feedbackDrafts (v2.1.247): 새 SendFeedback 도구를 제어합니다. 세션에서 문제가 생기면 Claude가 피드백 보고서 초안을 작성하고, 사용자는 /feedback에서 이를 검토한 뒤 보낼 수 있습니다. 초안 작성을 끄려면 이 설정을 사용하세요. Slash Commands의 /feedback 행을 참고하세요.²⁴⁵ - spinnerTipsOverride 형식 확장 (v2.1.247): 팁 항목으로 일반 문자열 외에 {id, text, cooldownSessions, priority} 객체도 쓸 수 있습니다. 객체 자체에도 tipsFile과 label 키가 추가되었습니다. 덕분에 조직은 기본 제공 팁과 함께 자체 팁을 순환 표시할 수 있습니다(위 예시가 확장된 형식입니다). 설정 레퍼런스에도 새 키가 문서화되어 있습니다.²⁴⁵²²⁷

새로운 설정 (v2.1.248–251):

• desktopSessionCleanupPeriodDays (v2.1.248): 데스크톱에서 작성된 세션이 트랜스크립트 정리 대상에서 제외되는 기간의 상한을 정합니다. 이 설정보다 함께 들어간 수정 사항이 더 중요합니다. 이전에는 Claude Desktop과 Cowork 세션이 cleanupPeriodDays(기본값 30일)가 지나면 사라졌습니다. 이제는 세션이 앱에 남아 있는 동안 정리 작업이 이를 보존합니다. 단, 조직 정책이 보존 기간을 관리하는 경우는 예외입니다.²⁰⁶
• 프로젝트 env 제한 (v2.1.251): 프로젝트 수준 .claude/settings.json의 env 블록에서는 더 이상 CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR, TMPDIR/TMP/TEMP를 설정할 수 없습니다. 이 값들은 셸, 사용자 설정 또는 관리형 설정에서 지정하세요. 이렇게 하면 복제한 저장소가 Claude Code의 설정 파일과 임시 파일 저장 위치를 바꿀 수 없습니다.²⁰⁶

새로운 설정 (v2.1.257-259):

• timeFormat / timeZone (v2.1.257): Claude Code가 시간을 표시하는 방식을 정합니다. 대상은 턴 종료 시 표시되는 완료 시각과 트랜스크립트 타임스탬프입니다. timeFormat에는 12시간제, 24시간제, 24시간제 UTC 또는 명시적인 strftime 패턴을 지정할 수 있습니다. timeZone에는 시간대 이름을 지정합니다.²¹¹ 설정 레퍼런스에도 두 키가 모두 문서화되어 있습니다.²²⁷
• permissions.blockReadsOutsideWorkingDirectories (v2.1.257): 세션의 작업 디렉터리 밖에 있는 파일 읽기를 아예 거부합니다. 이 설정이 없으면 auto mode는 세션에서 처음 그런 읽기를 시도할 때 한 번 확인을 요청합니다(Auto Mode 참고).²¹¹ v2.1.273에서는 두 가지 빈틈이 메워졌습니다. 이 설정이 켜져 있으면 검사기가 완전히 분석하지 못하는 Bash 명령은 검사를 건너뛰지 않고 확인을 요청합니다. 또한 저장소 설정이 지정한 메모리 디렉터리는 로드, 회상, 인덱싱 대상에서 모두 빠집니다.²¹⁷
• managedMcpServers / managedSourcesBehavior: 관리형 범위 키로, Enterprise Deployment에서 다룹니다. 앞의 키는 조직이 모든 사용자에게 MCP 서버를 제공할 때 쓰고(v2.1.259), 뒤의 키는 여러 관리형 소스를 옵트인 방식으로 병합할 때 씁니다(v2.1.257에서 개선).²¹¹²⁴⁴

새로운 설정 (v2.1.261):

• bashOutputMaxChars / taskOutputMaxChars (v2.1.261): Claude가 인라인으로 받는 명령 출력(후자는 백그라운드 작업 출력)의 양을 최대 128K자까지 늘립니다. 이 한도를 넘는 나머지는 파일로 저장됩니다. BASH_MAX_OUTPUT_LENGTH 환경 변수와는 다른 메커니즘입니다. 이 환경 변수는 명령의 작업 출력 파일에서 다시 읽어 오는 범위를 정합니다(기본값 30,000자, 최대 150,000자). 반면 이 키들은 출력을 인라인으로 둘지 파일로 저장할지 가르는 기준을 정합니다. 기준을 넘은 출력은 잘려 나가지 않고 파일에 저장되며, Claude가 필요할 때 읽을 수 있습니다.²¹⁴ v2.1.265부터는 저장 쪽에도 상한이 생겼습니다. 디스크에 저장되는 도구 결과는 1 GB로 제한되며, 저장된 파일이 잘렸을 때는 대화 내 미리보기에 그 사실이 표시됩니다.²¹⁵ 작업 쪽 설정은 v2.1.277에서 폐기되었습니다. 지원 중단되었던 TaskOutput 도구가 제거되어 이제 Claude는 백그라운드 작업의 출력 파일을 Read로 읽습니다. 따라서 taskOutputMaxChars와 TASK_MAX_OUTPUT_LENGTH는 더 이상 효과가 없습니다. bashOutputMaxChars는 영향을 받지 않습니다.²¹⁹

새로운 설정 (v2.1.267-269):

• maxEffortLevel (v2.1.267): 사용자가 선택할 수 있는 effort 수준의 상한을 정합니다. 최상위에 지정하거나 modelSettings 아래에 모델별로 지정할 수 있으며, Bedrock, Vertex, Foundry를 포함한 모든 제공자에 적용됩니다. 사용자는 상한보다 낮은 수준을 여전히 선택할 수 있습니다. /effort를 보완하는 관리자용 설정입니다.²¹⁶
• advisorModel: /advisor가 사용자 설정에 기록하는 저장된 advisor 모델입니다(fable, opus, sonnet 또는 전체 ID). --advisor는 한 세션 동안 이 값을 재정의하고, CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1은 도구를 끕니다. The Advisor Tool을 참고하세요.²⁷⁴
• sandbox.allowNestedUserNamespaces (v2.1.305): Linux와 WSL2에서 샌드박스 안의 명령이 사용자 네임스페이스를 만들 수 있게 합니다(Chromium, rootless podman 등). 이 설정을 켜면 해당 명령이 샌드박스의 파일 보호를 우회할 수 있으므로, 사용자 설정이나 관리형 설정에서만 읽습니다. Sandbox Mode를 참고하세요.²⁷⁸²⁷⁹
• bashEditDiffEnabled (v2.1.269): Bash 도구로 파일을 편집하면 도구 결과에 명령이 변경한 파일의 diff가 포함됩니다. 그래서 sed 같은 방식의 편집이 실제로 무엇을 바꿨는지 대화에서 확인할 수 있습니다.²¹⁶

새로운 설정 (v2.1.275):

• syncClaudeAiSkills / syncClaudeAiPlugins (v2.1.275): 이제 claude.ai 계정에서 활성화한 skills와 plugins가 같은 계정으로 로그인한 터미널 세션에 동기화됩니다. 터미널 세션에서 로컬 skills와 plugins만 쓰려면 둘 중 해당 키를 false로 설정하세요. Skills와 Plugin System을 참고하세요.²¹⁸

새로운 설정 (v2.1.282-283):

• maxProseWidth (v2.1.282): 넓은 터미널에서 Claude의 본문 텍스트 너비의 상한을 정합니다. 문단, 제목, 목록, 인용문은 지정한 열 수 안에서 줄바꿈되고, 표와 코드 블록은 전체 너비를 그대로 사용합니다. 값은 열 수를 나타내는 정수이며 최솟값은 40입니다.²²⁵²²⁷
• deniedModels / availableModelsMatch (관리형, v2.1.283): deniedModels는 availableModels가 허용하는 모델이라도 특정 모델을 차단합니다. "opus" 같은 계열 별칭을 쓰면 그 계열 전체가 차단되고, "claude-opus-5"를 쓰면 Opus 5.5도 함께 차단됩니다(Opus 5만 차단하려면 "claude-opus-5-0"으로 쓰세요). 기본적으로 "claude-opus-5" 같은 availableModels 항목은 그 이름을 확장한 이후 버전도 허용합니다. availableModelsMatch: "exact"를 지정하면 각 항목은 이름에 적힌 버전만 허용하므로, 새 릴리스는 목록에 추가할 때까지 차단됩니다. Claude Code는 두 키를 관리형 설정에서만 읽습니다.²²⁶²²⁷
• allowClaudeInChromeWithManagedMcp (관리형, v2.1.282): 독점 managed-mcp.json이 있어도 claude --chrome을 함께 실행할 수 있게 합니다. Chrome이 차단될 때 표시되는 오류에도 이제 이 키 이름이 나옵니다.²²⁵ 설정 레퍼런스에도 이 키가 문서화되었습니다. 이 키는 기기 자체의 관리형 설정에서만 읽으며, claude-in-chrome에 대한 deniedMcpServers 항목이 있으면 서버는 여전히 차단됩니다.²³³

새로운 설정 (v2.1.285):

• allowedProviders (관리형, v2.1.285): 기기에서 사용할 수 있는 API 제공자를 제한합니다. 대상은 Anthropic API, 사용자 지정 엔드포인트, Bedrock, Mantle, Vertex AI, Foundry, Claude Platform on AWS, Cloud 게이트웨이입니다.²²⁹ 이 키는 설정 레퍼런스에 문서화되어 있습니다. 서버 관리형 설정도 목록을 전달하는 경우 기기 자체의 관리자 소스에서 온 목록이 계속 적용되므로, 세션은 두 목록에 모두 있는 제공자만 사용할 수 있습니다.²³³

설정 빠른 찾기: 가장 많이 검색되는 플래그

특정 설정을 이름으로 찾고 있다면 여기서 간단히 확인하세요. 각 항목에는 해당 설정이 처음 나온 릴리스와, 특정 범위에서만 쓰는 설정이라면 그 범위가 적혀 있습니다:

주제별 공식 문서는 어디에 있습니까?

이 가이드는 현장 매뉴얼이며 공식 레퍼런스는 아닙니다. 하위 시스템에 대한 Anthropic의 정식 페이지가 필요할 때 참고할 공식 위치는 다음과 같습니다(이 가이드의 각 섹션에도 해당 문서 링크가 있습니다):

환경 변수 레퍼런스

인증 및 API:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers; credential/org/routing/API-behavior headers set from managed or project settings require approval (v2.1.251)[^238]

모델 설정:

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_MODEL=claude-opus-5-5         # Model new sessions START on; a /model pick overrides + persists (v2.1.236)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5    # What the `opus` alias resolves to (Opus 5.5 since v2.1.280; Opus 5 v2.1.219-278)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001  # pin the haiku alias; on the Anthropic API it resolves to Haiku 5.5 (claude-haiku-5-5) as of v2.1.293[^274][^275]
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Default model for subagents; an agent's model: field and per-spawn picks win (v2.1.251 demoted it from override to default)[^238]
CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1             # Turn the advisor tool off: /advisor becomes unavailable, advisorModel is ignored, --advisor is accepted but does nothing[^282]
CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1              # Force every subagent onto CLAUDE_CODE_SUBAGENT_MODEL (or the main model), ignoring agent-definition and per-spawn overrides -- the pre-v2.1.251 behavior, opt-in (v2.1.257)[^243]
CLAUDE_CODE_DISABLE_WORKFLOWS=1                 # Turn dynamic workflows off for one session; same effect as "disableWorkflows": true, and whichever of the two turned them off, the other cannot turn them back on. Workflows are on by default except on Pro, where "enableWorkflows": true (the Dynamic workflows row in /config) turns them on; the v2.1.147 opt-in CLAUDE_CODE_WORKFLOWS=1 no longer appears in the env-vars reference[^291]
MAX_THINKING_TOKENS=10000                       # (Opus 4.6 and Sonnet 4.6 only — removed in Opus 4.7)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_MAX_TURNS=10                        # Cap agentic turns when no --max-turns is passed; the flag wins when both are set, and a value that is not a positive integer is rejected at startup[^291]
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

클라우드 제공업체 설정:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Bedrock service tier (v2.1.122+): 'default', 'flex', or 'priority'; sent as X-Amzn-Bedrock-Service-Tier header[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region
VERTEX_REGION_CLAUDE_HAIKU_5_5=us-east5          # Vertex region for Claude Haiku 5.5 (v2.1.293+)[^276]
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Opt in gateway /v1/models discovery for /model picker (v2.1.129+)[^164]
CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS=3000  # Extend the LLM gateway /v1/models discovery timeout (default 3s; v2.1.269+)[^252]
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1              # Send the x-claude-code-* hint headers (request-class, agent-type, prev-tool-durations, compaction, context-compacted, and prompt-id from v2.1.283) through a gateway or third-party provider; a direct Anthropic API connection sends them by default, and =0 stops them everywhere (v2.1.273+)[^253][^262][^263]
CLAUDE_CODE_AUTO_MODE_SERVER=0                  # Opt out of the server-side auto-mode checks, the default since v2.1.278 for Enterprise and Claude API accounts, Claude Platform on AWS, Bedrock, Agent Platform, Foundry, and gateways (not charged when the server performs them; =1 was the v2.1.273-277 opt-in); also applies on a direct Anthropic API connection since v2.1.281, where server-side is the default with telemetry off since v2.1.282; the docs call it temporary[^253][^255][^259][^260][^261]
CLAUDE_CODE_AUTO_MODE_MODEL=claude-sonnet-5-5   # Model the client-side auto mode classifier uses; no effect on server-side auto mode (v2.1.302+)[^283]

동작 제어:

DISABLE_AUTOUPDATER=1                           # Prevent automatic background updates
DISABLE_UPDATES=1                               # Block ALL update paths including manual `claude update` (v2.1.118+, stricter than DISABLE_AUTOUPDATER)[^160]
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1       # Homebrew/WinGet installs run package-manager upgrade in background, then prompt restart (v2.1.129+)[^164]
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
CLAUDE_CODE_DISABLE_WEB_FETCH=1                 # Turn off the WebFetch tool; WebSearch stays available (v2.1.285+)[^265][^269]
CLAUDE_CODE_DISABLE_ARTIFACT=1                  # Turn the Artifact tool off for one session; while it is set, no settings file turns artifacts back on[^291]
CLAUDE_CODE_ARTIFACT_AUTO_OPEN=0                # Do not open the browser when a new artifact is published[^291]
CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES=2      # Cap re-sends of a non-streaming fallback request that timed out (v2.1.285+)[^265]
CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS=5000 # Starting delay of the exponential backoff between retries of a 529 overloaded request, default 500; whole milliseconds from 500 to 32000; no effect with CLAUDE_CODE_RETRY_WATCHDOG=1 or in fast mode (v2.1.292+)[^272][^276]
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS=60000 # Ceiling of that backoff, default 32000 ms (v2.1.296+; in the env-vars docs since October 14)[^274][^280]
CLAUDE_CODE_RETRY_WATCHDOG=1                     # Unattended sessions: retry 429 and 529 capacity errors indefinitely, backing off up to 5 minutes or until the limit resets (v2.1.186+)[^276]
CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=1800000   # Cap, per request, on how long the watchdog waits out 429 and 529 errors; unset means no limit (v2.1.295+)[^274][^276]
CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS=3600000 # Under the watchdog, end a request at a usage limit that resets further away than this instead of waiting it out (v2.1.301+)[^283]
CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS=60000 # Minimum interval between checks that a usage limit was lifted before its reset, while the watchdog waits on it (v2.1.305+)[^286][^287]
CLAUDE_CODE_RESTRICTED=1                        # Restricted mode: no command/code tools or WebFetch unless named in --tools; only managed settings load (v2.1.248+)[^238]
CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT=1      # Keep the dangerous-rm prompt waiting in auto mode and --dangerously-skip-permissions instead of denying after 2 minutes (v2.1.281+)[^260]
CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT=1    # Skip the prompt for a recursive rm whose target is only command-substitution output, such as rm -rf "$(pwd)" (v2.1.281+)[^260]
CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1     # Keep prompting for an rm built at run time inside a shell -c script Claude Code cannot read; such scripts no longer prompt by default (v2.1.299+; release-notes only as of 2026-10-14)[^279][^280]
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls
ENABLE_PROMPT_CACHING_1H=1                      # Opt into 1-hour prompt cache TTL (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Deprecated alias for the above; v2.1.108+ still honors it on Bedrock but logs a deprecation notice
FORCE_PROMPT_CACHING_5M=1                       # Force 5-minute cache TTL (v2.1.108+)
CLAUDE_CODE_PROMPT_CACHE_TTL=1h                 # Main-conversation cache TTL, 5m or 1h; beats the promptCacheTtl setting (v2.1.242+)[^234]
CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=5m        # TTL for subagents, workflows, forks, compaction, titles; beats subagentPromptCacheTtl (v2.1.242+)[^234]
ENABLE_TOOL_SEARCH=true                         # Re-enable tool search on Vertex AI (disabled by default v2.1.119+ to avoid unsupported beta header). Valid values: true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Hide the working directory in the startup logo (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=0                     # Turn fork subagents off; on by default in the terminal and, since v2.1.302, in claude -p, the Agent SDK, the desktop app, and VS Code (=1 was the external-build opt-in from v2.1.117; claude mcp serve never offers them)[^160][^283]
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                 # Force synchronized terminal output when auto-detection misses it, such as Emacs eat (v2.1.129+)[^164]
CLAUDE_CODE_SESSION_ID=...                      # Read-only: present in the Bash tool subprocess; matches the session_id passed to hooks (v2.1.132+)[^168]
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1          # Skip the fullscreen alternate-screen renderer; keep the conversation in the terminal's native scrollback (v2.1.132+)[^168]
CLAUDE_EFFORT=...                               # Read-only: current effort level inside hooks and Bash tool subprocess (v2.1.133+)[^169]
CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1             # Include subagent text + thinking in stream-json output; pairs with --forward-subagent-text (v2.1.211+). Covers depth-2+ nested subagents as of v2.1.219[^205][^213]
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=200    # Per-session WebSearch cap (default 200; v2.1.212+). Since v2.1.290 an interactive session's budget refills instead of ending at 200 (next line); the env-vars docs, fetched Oct 6, still describe the 200 cap[^206][^271][^273]
CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR=100     # WebSearch budget refill rate: 100 calls/hour by default in an interactive session, 0 (off) in a non-interactive one (v2.1.290+)[^271][^276]
CLAUDE_CODE_DISABLE_ATTACHMENTS=1               # Send @-mentions as plain text instead of expanding file content; a repo's .claude/settings.json or settings.local.json can no longer set it (v2.1.290)[^271][^273]
CLAUDE_CODE_DISABLE_FILE_MENTIONS=1             # Hand Claude the path of an @ mention to read with its file tools, not the file's contents, so PreToolUse hooks see the read; ignored in project and local settings (v2.1.299+)[^279][^280]
CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS=900000        # WebFetch per-URL session cache TTL (default 15 min; v2.1.233+)[^226]
CLAUDE_CODE_WEBFETCH_DEADLINE_MS=300000         # WebFetch hard deadline: a server that never finishes its response fails the fetch after 300s by default; 0 disables (v2.1.268+)[^252]
CLAUDE_CODE_PROJECT_DIR_NAME=myproj             # Short name for the per-project transcript directory, for hosts that give each session its own config dir (v2.1.234+)[^227]
CLAUDE_CODE_GOAL_CHECKIN_MINUTES=30             # How long background tasks may keep a /goal waiting before Claude checks in on them; 0 disables (v2.1.234+)[^227]
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200       # Per-session subagent-spawn cap (default 200 in v2.1.212–223; the default cap was REMOVED in v2.1.224 — set this to reimpose one)[^206][^218]
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20         # Cap on concurrently-RUNNING subagents (default 20; distinct from the per-session total above; v2.1.217+)[^211]
CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS=0        # Disable the v2.1.229 workflow fan-out stagger (same-prefix sibling agents launch staggered so they read the cached prompt prefix instead of re-paying it)[^224]
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=64   # Raise the Workflow tool's per-run concurrent agent limit, 1-256, for inference-bound fan-outs (v2.1.269+)[^252]
CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL=sonnet         # Run every workflow agent on one model while other subagents keep theirs (v2.1.296; release-notes only as of 2026-10-14)[^274][^280]
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3          # Nested subagent spawn depth. Default 3 as of v2.1.219; set 1 to disable nesting. Default history: 5 (v2.1.172–v2.1.216) → 1 (v2.1.217) → 3 (v2.1.219). Set it explicitly[^211][^213]

도구 설정:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Read-back window from the Bash working output file (default 30,000 chars, hard ceiling 150,000)
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH=8192     # Override the cap on MCP tool descriptions and server instructions, every server in the session: 4,096 chars since v2.1.296, 2,048 in v2.1.280-295; Anthropic's first-party servers at api.anthropic.com are uncut since v2.1.299[^279][^256][^274]
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=120000       # Threshold before a long MCP tool call moves to the background (default 2 min; v2.1.212+)[^206]
CLAUDE_CODE_MCP_STARTUP_WAIT_MS=10000           # Bound how long the FIRST non-interactive turn waits for still-connecting MCP servers; 0 = don't wait (v2.1.274+)[^254]
CLAUDE_CODE_TOOL_MEMORY_LIMIT=4096              # Opt-in Linux memory cgroup (MB) for Bash tool commands — a runaway build can't stall the session (v2.1.233+)[^226]
CLAUDE_CODE_ENABLE_TODO_TOOLS=1                 # Offer the TodoWrite/TaskCreate-family tools on models outside v2.1.268's allowlist (Claude 3.x, Opus 4.0-4.7, Sonnet 4.0-4.6, Haiku 4.5); elsewhere they are off unless set (first turned off on newer models in v2.1.233)[^226][^252]
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

백그라운드 명령 시간 제한(v2.1.285, v2.1.288에서 범위 축소): 백그라운드 Bash 및 PowerShell 명령은 제한 시간이 지나면 중지됩니다. 제한 시간은 run_in_background로 실행할 때 지정한 timeout이며(기본값 30분, 최대 2시간), 명령이 중지되면 Claude에 알림이 전달됩니다.²²⁹ v2.1.288부터 이 제한은 무인 세션(-p, Agent SDK, CI, 클라우드 세션)에만 적용됩니다. 터미널, 데스크톱 앱, VS Code 세션에서는 백그라운드 명령에 시간 제한이 없습니다. 도구 레퍼런스에서도 “Before v2.1.288, it applied in every session”(v2.1.288 이전에는 모든 세션에 적용되었습니다)이라고 이를 확인해 줍니다.²³⁴²³⁷

네트워크 및 프록시:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
CLAUDE_CODE_GZIP_REQUEST_BODIES=0              # Turn off gzip compression of large request bodies sent to api.anthropic.com, on even with telemetry off since v2.1.300[^281][^282]
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

UI 및 터미널:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory; not settable from project-settings env (v2.1.251)[^238]
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory; not settable from project-settings env, nor are TMPDIR/TMP/TEMP (v2.1.251)[^50][^238]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Hold ALL native-1M models to 200K via auto-compaction (v2.1.223 widened scope); also the opt-out for the v2.1.287 1M default on Bedrock/Vertex/Foundry/Claude apps gateway[^103][^217][^268]
CLAUDE_CODE_AUTO_COMPACT_WINDOW=200k           # Auto-compact window, 100000 to 1000000 tokens; k and M suffixes since v2.1.304 (200k had set a 100K window), out-of-range values warn[^286][^287]
CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1  # Let claude ultrareview run in a folder you have not trusted where it cannot ask, such as CI; environment only, not a settings env block (v2.1.309+)[^286][^287]
CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS=150000     # Context size at which idle compaction applies, default 200000; values below 100000 are raised to 100000; "idleCompaction": false in settings.json turns the feature off (v2.1.299; the docs date both to v2.1.290+)[^279][^280]
CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1  # Let unrecognized model IDs exceed the assumed context window (v2.1.223)[^217]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove built-in commit/PR instructions[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Stop scheduled cron jobs mid-session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks timeout (default varies)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Enable Windows PowerShell tool on Linux/macOS (requires pwsh on PATH; v2.1.111+)[^153]
CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1           # Disable mouse click/drag/hover in fullscreen mode; wheel scroll still works (v2.1.195+)[^196]
CLAUDE_ENABLE_STREAM_WATCHDOG=0              # Disable the streaming idle watchdog (on by default for all providers since v2.1.196: aborts+retries after 5 min of silence)[^198]
CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1 # Turn off automatic memory-pressure reaping of idle background shell commands (v2.1.193+)[^196]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Force Session Recap when telemetry disabled (v2.1.108+)[^153]
CLAUDE_CODE_BG_TASKS_REPORT_RUNNING=0         # Restore pre-v2.1.269 behavior: remote/headless sessions may report "waiting for your input" while background agents still run[^252]
CLAUDE_AX_SCREEN_READER=1                     # Enable screen reader mode; same as --ax-screen-reader or "axScreenReader": true (v2.1.208+)[^203]
CLAUDE_AX_PREPARK_MS=50                       # Screen reader mode: pause before writing a changed line; default 0 since v2.1.287 (was 50)[^268][^269]
OTEL_LOG_RAW_API_BODIES=1                     # Emit full API request/response bodies as OTel log events (v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state (v2.1.110+, SDK/headless)[^153]

OpenTelemetry 익스포터 + 민감 필드 게이팅:²⁶⁸

OTEL_LOGS_EXPORTER=none                       # OTel logs exporter (supports 'none' for disable; v2.1.85 fixed crash)
OTEL_METRICS_EXPORTER=none                    # OTel metrics exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_TRACES_EXPORTER=none                     # OTel traces exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opt in to emitting tool content in OTel spans (v2.1.101+, sensitive by default)
OTEL_LOG_TOOL_DETAILS=1                       # Opt in to tool_parameters in OTel tool_result events (v2.1.85+); as of v2.1.273 also puts real agent, skill, plugin, and MCP server names on cost and token metrics[^253]
OTEL_LOG_USER_PROMPTS=1                       # Opt in to emitting user prompts in OTel traces (v2.1.101+, sensitive by default)
OTEL_LOG_ASSISTANT_RESPONSES=0                # Gate the claude_code.assistant_response log event holding the model's response text (v2.1.193+)
OTEL_METRICS_INCLUDE_REPOSITORY=1             # Tag OTel metrics and events with vcs.* repository attributes; with OTEL_LOG_TOOL_DETAILS, commit events carry vcs.ref.head.* (v2.1.269+)[^252]
CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH=60000     # Truncation limit for OTel content attributes (default 60 KB; v2.1.214+)[^207]
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # Disable release-notes fetch (v2.0.17+); v2.1.110 also stopped the auto-title Haiku request in headless/SDK when set; v2.1.290 also skips the startup connection warm-up[^271]
CLAUDE_CODE_ATTRIBUTION_HEADER=0              # Omit the system-prompt attribution block; behind a Claude apps gateway, set it in the env of the gateway's code or cli policy (v2.1.299+)[^279][^280]

프로젝트 설정으로는 텔레메트리를 켤 수 없음 (v2.1.282): 이제 프로젝트 및 로컬 설정 파일은 내보내기를 켜거나, 엔드포인트를 지정하거나, 콘텐츠를 수집하는 OpenTelemetry 변수를 무시합니다. CLAUDE_CODE_ENABLE_TELEMETRY, OTEL_*_EXPORTER 선택자, OTEL_LOG_* 등이 여기에 해당합니다. 반대로 기능을 끄는 값(exporter 선택자의 none, 콘텐츠 플래그의 0)은 이 파일에서도 그대로 적용됩니다. 나머지는 셸, 사용자 설정 또는 관리형 설정에서 지정하세요. 프로젝트 파일이 이런 변수를 설정하면 대화형 세션은 시작 시 알림을 표시하고, /status와 claude doctor는 무시된 변수 이름을 나열합니다. 하지만 -p 세션과 Agent SDK 세션에서는 알림이 표시되지 않으므로, 업그레이드 후에는 수집기가 여전히 데이터를 받고 있는지 확인하세요.²²⁵²²⁷

v2.1.121+ LLM-request span 속성: 이제 LLM-request span에 stop_reason, gen_ai.response.finish_reasons, user_system_prompt가 기록됩니다. user_system_prompt에는 PII가 포함될 수 있으므로 OTEL_LOG_USER_PROMPTS=1을 설정한 경우에만 기록됩니다.¹⁵⁴

v2.1.122+ 이벤트 수준 변경 사항: api_request 및 api_error 로그 이벤트의 숫자 속성이 이제 문자열이 아닌 숫자로 기록됩니다. 이로써 스키마 타입을 엄격하게 검사하던 다운스트림 OTel 수집기의 문제가 해결되었습니다. 또한 Claude Code이 @-멘션을 해석할 때 새로운 claude_code.at_mention 로그 이벤트가 발생합니다.¹⁵⁴

v2.1.300 속성: api_request 이벤트는 캐시 쓰기를 cache_creation_5m_tokens와 cache_creation_1h_tokens로 나누어 기록합니다. 트레이스 span에는 GenAI 시맨틱 컨벤션 속성(gen_ai.provider.name, gen_ai.conversation.id, gen_ai.tool.name, error.type)이 포함됩니다. user_prompt 이벤트와 상호작용 span은 mod의 prompt.submit hook이 다시 쓴 형태의 프롬프트를 기록합니다. 그리고 reftable 저장소에서 git commit -q를 실행한 뒤의 tool_result 이벤트에는 git_commit_id가 포함됩니다.²⁷³

v2.1.301 및 v2.1.302 속성: tool_decision 이벤트에는 classifier_verdict와 permission_mode가 포함되므로 auto mode 분류기의 결정과 권한 규칙에 의한 결정을 구분할 수 있습니다. 또한 OTEL_LOG_TOOL_DETAILS=1을 설정하면 분류기 차단이 일치한 기본 제공 규칙의 이름을 담은 classifier_category도 포함됩니다(v2.1.301). v2.1.302는 그동안 누락되던 대부분의 분류기 차단에 classifier_category를 채우고, OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT 값이 낮을 때도 tool_use_id, tool_source, tool_parameters를 이벤트에 유지합니다. 모니터링 문서에는 아직 이 세 속성이 나와 있지 않습니다.²⁷⁵²⁷⁶

v2.1.307 이벤트: 권한 규칙, auto mode, 안전 검사, hook 또는 sandbox가 도구 호출을 중단하거나, 확인을 요청하거나, 되돌려 보낼 때마다 claude_code.safety_event가 발생합니다. 턴 종료 이벤트를 제외하면 이 이벤트에는 tool_use_id가 포함됩니다. 모니터링 문서에 이 이벤트가 나와 있으며, 이제 classifier_verdict(v2.1.301+)도 함께 나와 있습니다.²⁷⁸²⁷⁹

v2.1.193+ claude_code.assistant_response 로그 이벤트: Claude Code은 모델의 전체 응답 텍스트를 OTel 로그 이벤트로 기록할 수 있으며, 이는 OTEL_LOG_ASSISTANT_RESPONSES로 제어합니다. 이 설정에는 알아 둘 만한 업그레이드 함정이 있습니다. OTEL_LOG_ASSISTANT_RESPONSES가 설정되지 않으면 OTEL_LOG_USER_PROMPTS의 값을 따르므로, 이미 프롬프트 내용을 기록하던 배포 환경은 업그레이드와 동시에 어시스턴트 응답 내용까지 받게 됩니다. 텔레메트리에 프롬프트만 남기려면 OTEL_LOG_ASSISTANT_RESPONSES=0을 설정하세요.¹⁷⁹

v2.1.214 텔레메트리 추가 사항: 이제 OTel 로그 이벤트에 message.uuid, client_request_id, tool_source 속성이 포함되어 메시지 단위로 이벤트를 연관 짓고 도구의 출처를 추적할 수 있습니다. subagentStatusLine 페이로드에는 subagent의 추론 노력 수준이 포함되므로 사용자 지정 상태 줄에 모델과 노력 수준을 함께 표시할 수 있습니다. 새로운 CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH 환경 변수로는 OTel 콘텐츠 속성에 적용되는 60 KB 잘림 한도를 설정합니다.¹⁹⁰

v2.1.265 게이트웨이 텔레메트리: 게이트웨이의 관리형 설정이 OTEL_EXPORTER_OTLP_ENDPOINT에 수집기를 지정하면, Claude apps 게이트웨이 세션은 이제 게이트웨이의 릴레이를 거치지 않고 OpenTelemetry를 수집기로 직접 내보냅니다. 수집기가 지정되지 않은 세션은 계속 릴레이를 사용합니다. 같은 릴리스에서는 Claude Desktop과 Cowork가 Claude apps 게이트웨이를 통해 보내는 텔레메트리에도 user.email과 user.groups가 추가되어 터미널 세션과 같아졌습니다.²¹⁵

v2.1.280 hook 텔레메트리: 이제 hook_execution_complete OTel 이벤트에 hook 출력 크기와, 크기가 커서 파일로 저장된 출력의 개수가 포함됩니다.²²⁰

v2.1.287 prompt_text: 이제 user_prompt 이벤트에 prompt_text가 포함됩니다. 이는 점으로 구분된 키를 중첩 구조로 바꾸는 백엔드를 위한 prompt의 사본입니다. 파이프라인에서 prompt를 제거하거나 마스킹하는 곳이 있다면 prompt_text에도 똑같이 적용하세요.²³²

API / 모델 제어:²⁶⁸

CLAUDE_CODE_EXTRA_BODY='{...}'                # Inject extra body fields into API calls; v2.1.113 fixed 400 errors with output_config.effort on Vertex/subagent calls
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # Override max context tokens (pre-existing var; v2.1.98 fixed handling of DISABLE_COMPACT when both are set)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # Override default token limit for file read operations (v2.1.0+); a Read call with allow_large can pass it when the context has room (v2.1.296+)[^274][^276]
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Do not fall back to non-streaming API on streaming failures (v2.1.83+)
CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1      # Stop sending structured outputs, for Mantle or gateways that reject them; session titles, memory recall, and prompt hooks failed there before (v2.1.288+)[^270][^273]
ANTHROPIC_BETAS=beta1,beta2                   # Enable beta API headers; v2.1.78 fixed silent ignore on Haiku models
ANTHROPIC_SMALL_FAST_MODEL=arn:...            # Fast model ID (Bedrock ARN supported; v0.2.125 stopped escaping slashes in ARN)

Plugins / MCP:²⁶⁸

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Plugin cache directory (v2.1.72 fixed literal '~' dir on some shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Preserve plugin marketplace cache when git pull fails (offline-friendly; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Passed to MCP headersHelper scripts so one helper can serve multiple servers (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Passed to MCP headersHelper scripts alongside the name (v2.1.85+)
MCP_SDK_GENERATION=v1                         # Opt out of the v2 MCP client; v2.1.274 made v2 the default on the last holdouts (Bedrock/Vertex/Foundry + telemetry-disabled installs)[^254]
MCP_PROTOCOL_NEGOTIATION=legacy               # Opt out of MCP 2026-07-28 protocol negotiation: with direct HTTP servers (default everywhere as of v2.1.274) and, since v2.1.292, with local (stdio) servers on every install, Bedrock, Vertex, and Foundry included and, since v2.1.299, with cloud session and Remote Control connectors[^279][^254][^272]

셸 / IDE:²⁶⁸

CLAUDE_CODE_SHELL_PREFIX="time "              # Wrap every Claude-invoked shell command with a prefix (v1.0.61+)
CLAUDE_CODE_GIT_BASH_PATH=C:\Program\ Files\Git\bin\bash.exe  # Custom Git Bash path on Windows (v2.1.98+)
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=60000       # SDK: exit after N ms idle (v2.0.35+)
CLAUDE_CODE_AUTO_CONNECT_IDE=false            # Disable IDE auto-connection (v1.0.61+)

엔터프라이즈 / 인증:²⁶⁸

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # Opt into proxy-side DNS resolution (v2.0.55 moved this from default-on to opt-in)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # TTL for dynamically generated API keys via apiKeyHelper (apiKeyHelper refresh added v0.2.74 with 5-min default; env var added v0.2.117)
CLAUDE_CODE_PROCESS_WRAPPER=/path/to/wrapper  # Route all Claude Code self-spawned processes through a wrapper executable; same as the processWrapper setting (v2.1.208+)[^203]

Skill 변수 (v2.1.69+):

${CLAUDE_SKILL_DIR}                            # Self-reference for skills to locate their own directory[^117]

SDK 호출자 식별 (v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=user@example.com        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

디버깅:

ANTHROPIC_LOG=debug                             # Enable API request logging

어떤 모델을 선택해야 합니까?

작업에 맞는 모델을 선택하면 비용과 품질이 크게 달라집니다. Claude Code에서는 여러 수준에서 모델을 유연하게 전환할 수 있습니다.

사용 가능한 모델

Claude Sonnet 5.5(2026년 9월 28일): v2.1.284부터 Anthropic API의 기본 Sonnet 모델이며, sonnet 별칭이 이 모델을 가리킵니다. 모든 요금제의 기본 모델은 Opus 5.5로 유지됩니다. 모델 ID: claude-sonnet-5-5(Bedrock: anthropic.claude-sonnet-5-5). 입력 $2/MTok, 출력 $10/MTok으로 Sonnet 5와 같으며, 캐시 읽기는 $0.10/MTok입니다(요금 페이지에 따르면 입력 요금의 0.05배로, Opus 5.5와 같은 비율입니다. v2.1.296에서는 $0.20을 적용하던 Claude Code 자체 비용 계산을 수정합니다). 1M 토큰 컨텍스트 윈도우, 최대 출력 128K(Batches API에서 output-300k-2026-03-24 베타 헤더를 사용하면 최대 300K). 신뢰할 수 있는 지식 기준 시점은 Opus 5.5 및 Fable 5.1과 같은 2026년 6월입니다. 지원 종료는 빨라도 2027년 9월 28일입니다. Claude Code에서 Sonnet 5.5의 effort 기본값은 medium이며(Claude API 자체 기본값은 high), 사고 기능은 비활성화할 수 없습니다. 콘텐츠에 따른 대체 처리: 사이버 보안 관련으로 표시된 요청은 Sonnet 5에서 다시 실행됩니다. 생물학 관련으로 표시된 요청은 Sonnet 5.5에 생물학용 대체 모델이 없으므로 거부 응답으로 끝납니다. Claude Code v2.1.284 이상이 필요합니다. Sonnet 5를 계속 사용하려면 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5로 고정하세요.²²⁸²³⁰

모델 페이지는 API 코드를 Sonnet 5에서 이전할 때 발생하는 호환성을 깨뜨리는 변경 사항 5가지를 안내합니다. between_tools를 사용하면 도구 호출 전 초기 사고가 비활성화되고, 도구 사용을 강제하면 오류가 반환되며, 사고 블록이 모델과 대화에 종속됩니다. 또한 Claude API와 Google Cloud에서는 computer_20251124를 허용하지 않고, 어드바이저 도구는 Opus 4.8, Opus 4.7, Sonnet 5를 어드바이저로 허용하지 않습니다. 도구 호출 사이의 텍스트도 thinking 블록으로 반환되므로, 이 텍스트를 스트리밍하는 인터페이스는 텍스트를 반환하는 display 값을 설정하기 전까지 아무것도 표시하지 않습니다.²³⁰

Claude Opus 5.5(2026년 9월 22일): v2.1.280부터 Claude Code의 새로운 기본 Opus 모델이며, 모델 설정 문서의 요금제별 표에 따르면 모든 요금제와 퍼스트파티 제공업체의 기본 모델이기도 합니다. 적용 대상은 Pro, Max, Team, Enterprise, Anthropic API, Claude Platform on AWS, Amazon Bedrock, Google Cloud의 Agent Platform입니다(Microsoft Foundry는 Sonnet 4.5를 유지하며, 해당 환경의 opus 별칭은 Opus 4.6을 가리킵니다). 같은 릴리스에서 Pro와 Team Standard의 기본 모델도 Sonnet에서 Opus로 전환하여 “Max, Team Premium, Enterprise와 일치”시킵니다. 이로써 프리미엄 등급이 Opus로 전환된 이후 이어져 온 요금제별 차이가 사라집니다. 모델 ID: claude-opus-5-5(Bedrock: anthropic.claude-opus-5-5) – claude-opus-5와 같은 방식으로, 날짜 없이 고정된 스냅샷입니다. 요금은 Opus 5보다 낮아져 입력 $4/MTok, 출력 $20/MTok입니다(Opus 5: $5/$25). 캐시 읽기는 $0.20/MTok으로, 입력 요금의 5%이며 일반적인 10%의 절반입니다(이보다 낮은 비율은 Fable 5.1과 Mythos 5.1의 2.5%뿐입니다). 1M 토큰 컨텍스트 윈도우, 최대 출력 128K(Batches API에서 output-300k-2026-03-24 베타 헤더를 사용하면 최대 300K). 항상 활성화된 적응형 사고를 사용합니다. 모델 개요 표에는 Fable과 같은 “적응형(항상 활성화)”으로 표시되어 있으며, 기본적으로 활성화되지만 끌 수 있었던 Opus 5와는 다릅니다. effort 기본값은 medium입니다(Opus 5의 기본값은 high였습니다). v2.1.280에서는 기존 설정을 이어받는 규칙도 이에 맞춰 변경됩니다. /effort가 모델별 설정으로 바뀌기 전에 저장한 사고 수준은 더 이상 Opus 5.5 같은 신규 모델에 적용되지 않으며, 사용자가 수준을 선택하기 전까지 해당 모델의 기본값으로 시작합니다. 신뢰할 수 있는 지식 기준 시점은 2026년 6월이며(학습 데이터도 2026년 6월), 현재 모델 중 Fable 5.1과 함께 가장 최신입니다. 지원 종료는 빨라도 2027년 9월 22일입니다. Claude Code v2.1.280 이상이 필요합니다.²²⁰²²¹

API 코드를 Opus 5에서 Opus 5.5로 이전할 때 호환성을 깨뜨리는 변경 사항:²²²

1. 사고 기능을 비활성화할 수 없습니다. thinking: {type: "disabled"}와 thinking: {type: "enabled", budget_tokens: N}은 모두 400 오류를 반환합니다. thinking 필드를 제거하고 대신 사고 수준을 선택하세요.
2. 도구 사용을 강제하면 오류가 반환됩니다. tool_choice는 auto와 none만 허용합니다. any와 tool은 토큰 수 계산 엔드포인트를 포함해 400 오류를 반환합니다. 엄격한 도구 사용 또는 구조화된 출력과 함께 auto를 사용하세요.
3. 사고 블록은 모델에 종속됩니다. 라우터나 대체 처리로 대화를 Opus 5.5에서 다른 모델로 옮기면, 해당 대화 턴은 Opus 5.5의 사고 블록 없이 실행됩니다(Claude API의 Fable 5.1과 Mythos 5.1은 예외입니다).
4. Claude API와 Google Cloud에서는 computer_20251124를 허용하지 않습니다. 대신 computer_toolset_20260801 도구 세트를 선언하세요. Bedrock은 기존 도구를 유지합니다. 추가 변경 사항 하나는 요청 실패를 일으키지는 않지만 응답 형식을 바꿉니다. 모델이 도구 호출 사이에 작성하는 텍스트는 thinking 블록으로 반환되며, 기본 display 설정에서는 이 블록이 비어 있습니다. 이 설명을 스트리밍하는 인터페이스는 display: "updates"(베타) 또는 "summarized"를 설정하기 전까지 아무 내용도 표시하지 않습니다.²²²

Claude Code의 콘텐츠 기반 대체 모델 전환. Opus 5.5에는 안전 분류기가 적용되며, 주로 생물학과 사이버 보안 콘텐츠를 감지합니다. 분류기가 요청을 감지하면 Claude Code는 다른 모델로 요청을 다시 실행하고 알림을 표시합니다. 생물학 관련 요청은 Opus 5로, 사이버 보안 관련 요청은 Opus 4.8로 전환되며, /model로 원래 모델을 다시 선택할 때까지 세션은 대체 모델을 계속 사용합니다. 전환할 때마다 확인을 받으려면 /config에서 메시지가 감지되면 모델 전환을 끄세요(switchModelsOnFlag: false).²²³ v2.1.287부터는 전환 시 대체 모델의 기본 추론 강도 대신 현재 추론 강도를 유지합니다. 따라서 Opus 5.5의 기본값인 medium으로 실행하던 세션은 기본값이 high인 Opus 4.8로 전환되어도 medium을 유지합니다.²³²²³³

Claude Opus 5(2026년 7월, 이전 Opus 등급): v2.1.219(2026년 7월 24일)부터 v2.1.280에서 Opus 5.5가 기본 Opus 모델이 되기 전까지 Opus 등급을 대표했으며, opus 별칭이 가리키던 모델입니다. 다음 내용은 2026년 7월 출시 당시를 기준으로 합니다. Anthropic는 Opus 4.8을 그대로 대체할 수 있는 업그레이드로 소개합니다. 입력 $5/MTok, 출력 $25/MTok으로 가격은 동일하며, “같은 비용으로 성능을 크게 개선”했고, 최대 추론 강도에서 Opus 4.8보다 평균 토큰 사용량이 약 26% 적습니다. 이 모델은 Claude Max의 기본 모델이자 Claude Pro에서 가장 강력한 모델이었습니다. 모델 ID는 claude-opus-5입니다. 날짜가 없는 고정 스냅샷으로, claude-opus-4-8 및 claude-sonnet-5와 같은 방식이며 최신 버전을 계속 가리키는 포인터가 아닙니다. 1M 토큰 컨텍스트 윈도(베타 헤더가 필요 없으며 Opus 4.8과 동일), 최대 출력 128K(Batches API에서 output-300k-2026-03-24 베타 헤더를 사용하면 최대 300K)를 지원합니다. 적응형 사고만 지원하며, thinking.type: "enabled"를 사용하는 확장 사고는 지원하지 않습니다. 신뢰할 수 있는 지식 기준일은 2026년 5월입니다(학습 데이터 기준일도 2026년 5월). 출시 시점부터 Fable 5.1(기준일 2026년 6월)이 2026년 9월 1일에 등장하기 전까지 현행 Claude 모델 중 가장 최신 기준일이었습니다.²⁴¹ Opus 5가 출시되면서 Opus 4.8은 문서의 레거시 모델 표로 이동해 4.7, 4.6과 함께 나열됩니다. 여전히 사용할 수 있지만 더 이상 권장 기본 모델은 아닙니다.¹⁹⁷

하네스를 Opus 4.8에서 Opus 5로 이전할 때 호환성에 영향을 주는 2가지 변경 사항:¹⁹⁷

1. 사고가 기본적으로 활성화됩니다. Opus 4.8에서는 thinking 필드가 없는 요청이 사고 없이 실행되었지만, Opus 5에서는 같은 요청이 적응형 사고를 사용해 실행됩니다. max_tokens는 여전히 사고와 응답 텍스트를 합한 전체 출력의 엄격한 상한이므로, 이전에 사고 없이 실행하던 작업은 토큰 여유가 충분한지 다시 확인하세요. 이전 동작을 복원하려면 thinking: {type: "disabled"}를 전달하세요. 단, 다음 항목의 제한이 적용됩니다.
2. 사고를 비활성화하면 추론 강도는 최대 high로 제한됩니다. thinking: {type: "disabled"}를 추론 강도 xhigh 또는 max와 함께 사용하면 400 오류가 반환됩니다. 이 검사는 요청마다 적용됩니다. 같은 대화의 이전 턴이 허용되었더라도, 사고가 비활성화된 상태에서 추론 강도를 xhigh로 높이면 요청이 거부됩니다.

Claude Code에서 Opus 5의 effort 기본값은 high이며(Claude API에서도 동일), low, medium, high, xhigh, max의 모든 단계를 사용할 수 있습니다. Anthropic의 공식 마이그레이션 지침은 토큰 비용보다 성능이 우선인 작업에서 max 추론 강도를 테스트하도록 권장합니다. 빠른 모드는 Opus 5를 지원하며 요금은 MTok당 $10/$50입니다(빠른 모드 참조).¹⁹⁷¹⁹⁸

Claude Fable 5.1(2026년 9월 1일): Fable 등급의 새로운 최상위 모델이며, v2.1.257부터 fable 별칭이 가리키는 모델입니다(ANTHROPIC_DEFAULT_FABLE_MODEL로 다른 모델을 고정하지 않은 경우). 이제 best는 “사용 가능한 최신 Fable 모델”을 의미합니다. 최소 버전 요구 사항은 설명이 조금 필요합니다. 모델 설정 문서에는 별칭이 v2.1.255에서 전환되었다고 나와 있고, 모델 페이지에는 Fable 5.1에 “Claude Code v2.1.255 이상이 필요”하다고 명시되어 있습니다. 하지만 2.1.253-256은 npm에 게시된 적이 없으므로, 이를 지원하는 최초의 설치 가능한 릴리스는 v2.1.257(9월 1일)입니다. 모델 ID는 claude-fable-5-1입니다(Bedrock: anthropic.claude-fable-5-1). Fable 5와 등급 및 토큰당 가격이 동일합니다. 입력 $10/MTok, 출력 $50/MTok, 1M 컨텍스트, 최대 출력 128K, 항상 활성화되는 적응형 사고를 제공하며 effort 기본값은 high입니다. 다만 에이전트가 장시간 작업하는 세션에 영향을 주는 요금 변경이 하나 있습니다. 캐시 읽기 비용은 $0.25/MTok으로, 일반적인 입력 가격의 10%가 아니라 0.025배(2.5%)입니다. 이 요율은 Fable 5.1과 Mythos 5.1에만 적용되며, 캐시 쓰기는 기존 요금(5분 $12.50, 1시간 $20)을 유지합니다. 신뢰할 수 있는 지식 기준일은 2026년 6월입니다(학습 데이터도 2026년 6월). 현행 Claude 모델 중 가장 최신이며, 2026년 9월 22일에 Opus 5.5(기준일 2026년 6월)가, 9월 28일에 Sonnet 5.5가 같은 기준일로 합류했습니다. 지원 종료는 빨라도 2027년 9월 1일 이후입니다. v2.1.301부터는 조직에서 최신 Fable 모델을 사용할 수 없을 때 fable과 best가 오류를 반환하는 대신 이전 Fable 모델로 한 번 재시도합니다.²⁷⁵

Fable 5 대비 호환성에 영향을 주는 변경 사항은 3가지입니다. 도구 사용을 강제하면 오류가 반환되고, 이전 모델은 이 모델의 사고 블록을 읽을 수 없으며, 이전 턴을 편집하면 사고 블록이 무효화됩니다. 추가된 변경 사항은 메시지별 추론 강도(베타), 특정 턴에만 적용되는 시스템 메시지(베타), 도구 호출 사이의 진행 상황 업데이트(display: "updates", 베타), 저렴해진 캐시 읽기, 콘텐츠 출처 정보의 5가지입니다. Claude Mythos 5.1은 사양까지 동일한 모델이며, Project Glasswing을 통해 초대받은 사용자만 이용할 수 있습니다. 이번 출시와 함께 Fable 5는 문서의 레거시 모델 표로 이동해 Opus 4.8/4.7/4.6/4.5 및 Sonnet 4.6/4.5와 함께 나열됩니다.

릴리스 노트에는 게이트웨이 관련 주의 사항이 하나 있습니다. Claude 앱의 게이트웨이 세션에서는 현재 fable과 best가 계속 Fable 5를 가리킵니다. 5.1을 지원하도록 설정되지 않은 게이트웨이는 해당 모델을 거부하기 때문입니다. 따라서 이런 세션에서는 /model에서 Fable 5.1을 직접 선택하세요. 다만 v2.1.260 이전에는 /model 선택 목록에 Fable 5.1이 표시되지 않았으므로, 직접 선택하려면 /model claude-fable-5-1을 전부 입력해야 했습니다(아래의 출시 직후 수정 사항 참조). 출시 당시 요금제별 기본 모델은 프리미엄 요금제에서 Opus 5, Pro 및 Team Standard에서 Sonnet 5였습니다. 이후 v2.1.280(2026년 9월 22일)에서 모든 요금제의 기본 모델이 Opus 5.5로 변경되었습니다.^211241242221

Fable 5.1 출시 직후 수정 사항(v2.1.260, 9월 3일): 출시 후 첫 릴리스는 4가지 문제를 수정합니다. 이제 Fable 5.1을 사용할 수 있는 조직에서는 /model 선택 목록에 해당 모델이 표시됩니다. 이 수정 전에는 /model claude-fable-5-1을 전부 입력해야만 모델을 선택할 수 있었습니다. 이제 Fable 5.1의 프롬프트 캐싱은 도구 결과 뒤에 첨부된 컨텍스트에도 적용됩니다. 이전에는 이 컨텍스트가 도구를 호출하는 턴마다 캐시되지 않은 입력으로 다시 전송되어, 0.025배의 캐시 읽기 요율이 특히 유용해야 할 장시간 에이전트 세션에서 비용 절감 효과가 눈에 띄지 않게 줄어들었습니다. 세션 도중 /effort를 변경해도 더 이상 프롬프트 캐시가 무효화되지 않습니다. 또한 model: fable 에이전트는 이제 ANTHROPIC_DEFAULT_FABLE_MODEL로 고정한 모델의 [1m] 태그를 반영하며, 아무런 알림 없이 200K 컨텍스트 윈도로 실행되는 문제가 해결되었습니다.²¹²

Claude Fable 5(2026년 6월 9일, 2026년 9월 1일부터 레거시): Opus보다 상위에 있는 새로운 모델 등급입니다. Anthropic의 가장 강력하고 지능적인 모델로, 테스트한 거의 모든 벤치마크에서 최고 수준의 성능을 보이며 수백만 토큰의 컨텍스트에서도 일관성을 유지하도록 설계되었습니다. Fable 5는 일반 사용자도 안전하게 사용할 수 있도록 만든 “Mythos급” 프런티어 모델입니다. 사이버 보안, 생물학·화학, 모델 증류 관련 질의에서 Opus 4.8로 전환하는 안전 분류기가 적용됩니다(Claude Mythos 5는 승인된 연구자를 위해 이러한 보호 조치를 해제한 동일 모델입니다). v2.1.170(2026년 6월 9일)부터 Claude Code에서 선택할 수 있게 되었습니다. claude update를 실행한 다음 /model fable을 실행하세요. 이 짧은 별칭은 v2.1.257부터 Fable 5.1을 가리키므로, 현재 Fable 5를 선택하려면 /model claude-fable-5를 사용하세요. 구독 요금제에는 2026년 6월 22일까지 순차적으로 제공되었으며, 현재 배포가 완료되었습니다. 모델 ID는 claude-fable-5입니다. Fable 5는 기본적으로 1M 컨텍스트 윈도를 제공하므로 [1m] 접미사가 필요하지 않습니다. v2.1.173(2026년 6월 11일)부터는 claude-fable-5[1m] 모델 이름에서 접미사가 자동으로 제거되어 claude-fable-5로 정규화됩니다(이 접미사는 1M을 사용하려면 [1m]을 지정해야 하는 Opus/Sonnet에서만 의미가 있었습니다). 최대 출력은 128K입니다. 요금은 입력 $10/MTok, 출력 $50/MTok으로 Opus 4.8의 약 2배이므로, 일상적인 편집보다는 고난도 추론 작업에 사용하세요. 요청 매개변수는 Opus 4.8과 동일하지만(적응형 사고만 지원하며 temperature/top_p/top_k 및 budget_tokens는 제거됨), 새로운 차이점이 하나 있습니다. thinking: {type: "disabled"}를 명시하면 400 오류가 반환되므로, 사고 없이 실행하려면 thinking 매개변수를 아예 생략하세요.²⁶¹ Claude Code에서 Fable 5는 Opus 5와 마찬가지로 전체 추론 강도 범위(low/medium/high/xhigh/max, 기본값 high)를 지원합니다. Fable 5에서는 사고 기능을 끌 수 없습니다 — 세션의 사고 토글, alwaysThinkingEnabled 설정, MAX_THINKING_TOKENS=0은 모두 효과가 없으며, 항상 적응형으로 추론합니다. fable 계열의 설정 항목도 Opus와 동일하게 구성됩니다. ANTHROPIC_DEFAULT_FABLE_MODEL은 fable 별칭이 가리키는 모델을 고정하고(Bedrock/Vertex/Foundry에서 유용합니다), DISABLE_PROMPT_CACHING_FABLE은 Fable의 프롬프트 캐싱을 비활성화하며, 기업용 게이트웨이에서는 콘텐츠에 따른 자동 폴백이 적용됩니다. 이제 /model opus는 Opus 5.5를 선택합니다(v2.1.280, 기본 추론 강도는 medium이며 가장 어려운 작업에는 /effort xhigh를 사용합니다). 또한 초기 기본 모델은 더 이상 요금제에 따라 달라지지 않습니다 – Microsoft Foundry를 제외한 모든 Anthropic 운영 요금제에서 Opus 5.5가 기본값입니다. 최고 수준의 성능이 필요하다면 /model fable로 Fable 등급을 직접 선택하세요 – v2.1.257 기준으로는 Fable 5.1을 선택합니다.^{261197207242220221}

Opus 4.7(2026년 4월 16일): 이전 세대의 최상위 모델이며, 여전히 모든 기능을 사용할 수 있습니다. 1M 토큰 컨텍스트 창을 표준 요금으로 제공하며, 긴 컨텍스트에 대한 추가 요금은 없습니다. 최대 출력은 128K이며, 적응형 사고만 지원합니다(확장 사고는 제거되었습니다). 새로 도입된 xhigh 추론 강도는 코딩 및 에이전트 작업을 시작할 때 권장되는 수준입니다.¹⁴⁵ 신뢰할 수 있는 지식 기준일: 2026년 1월. 학습 데이터 기준일: 2026년 1월. 모델 ID: claude-opus-4-7. 요금은 Opus 4.6과 동일한 MTok당 $5/$25이며, MTok당 5분 캐시 쓰기는 $6.25, 1시간 캐시 쓰기는 $10, 캐시 읽기는 $0.50입니다.¹⁴⁴ Opus 4.7은 SWE-Bench에서 Opus 4.6보다 3배 많은 실무 작업을 해결하고, CursorBench에서 70%를 기록했으며(4.6은 58%), Anthropic의 93개 작업으로 구성된 내부 코딩 벤치마크에서는 해결률이 13% 향상되었습니다.¹⁴⁴ 새 토크나이저를 사용하므로 같은 텍스트의 토큰 수가 약 1~1.35배로 늘어날 수 있습니다. max_tokens에 여유를 더 두고 컨텍스트 압축이 실행되는 임계값도 높이세요.¹⁴⁵ 비전은 최대 2,576px / 3.75MP 이미지를 지원하며, 픽셀 좌표는 1:1로 대응합니다.¹⁴⁵

Opus 4.7 코딩 벤치마크(2026년 4월):¹⁵¹

요금제별 기본 모델(Claude Code):²⁰⁷²²¹

v2.1.280(2026년 9월 22일)부터 요금제별 구분이 사라졌습니다. Anthropic가 운영하는 모든 요금제와 자체 제공 서비스의 기본 모델은 Opus 5.5이며, 유일한 예외는 Microsoft Foundry입니다. 이전에는 가장 중요했던 기준인 “어떤 요금제를 사용하고 있는가?”가 이제는 답을 바꾸지 않습니다.

Opus 4.7의 Messages API 호환성이 깨지는 변경 사항(호출 측에 영향):¹⁴⁵

• 확장 사고의 budget_tokens가 제거되었습니다. 대신 thinking: {type: "adaptive"}를 사용하세요. 적응형 사고는 기본적으로 꺼져 있으며, thinking 필드가 없는 요청은 사고 없이 실행됩니다.
• temperature, top_p, top_k를 기본값이 아닌 값으로 설정하면 HTTP 400이 반환됩니다. 이 매개변수는 생략하고 프롬프트로 모델의 동작을 조정하세요.
• 사고 내용은 기본적으로 응답에서 생략됩니다. 추론 내용을 다시 표시하려면 thinking.display: "summarized"를 설정하세요(제품에서 사고 내용을 사용자에게 스트리밍하는 경우 필수입니다).

작업 예산(베타 헤더 task-budgets-2026-03-13)을 사용하면 output_config.task_budget을 통해 전체 에이전트 루프에 걸친 목표 토큰 수를 모델에 알려 줄 수 있습니다. 최솟값은 20K 토큰입니다.¹⁴⁵

Opus 4.6(레거시): claude-opus-4-6으로 계속 사용할 수 있으며, 1M 컨텍스트와 최대 128K 출력을 지원합니다. 에이전트 코딩 성능을 높이려면 Opus 4.7로의 전환을 고려하세요. Opus 4.6은 2026년 2월 5일에 처음 출시되었습니다.⁷⁹¹⁴⁴ v2.1.117(2026년 4월 22일)부터 Pro와 Max 구독자가 Opus 4.6과 Sonnet 4.6을 사용할 때 기본 추론 강도는 high입니다(이전에는 medium). Opus 4.7은 xhigh를 유지합니다. 이 변경으로 4월 23일 사후 분석에 기록된 3월 4일 → 4월 7일의 추론 강도 하향 조정 이후 저하되었던 지능 수준이 복원되었습니다.¹⁵²¹⁵³

Sonnet 5(2026년 6월 30일, 이전 Sonnet 등급): Anthropic API에서 v2.1.197부터 v2.1.284에서 Sonnet 5.5로 변경되기 전까지 sonnet 별칭이 선택하던 모델입니다. 출시 당시 Anthropic는 이를 “속도와 지능의 최상의 조합”으로 소개했습니다. Anthropic에 따르면 이 모델은 Opus 4.8에 가까운 성능을 더 낮은 가격으로 제공하며, 에이전트 추론, 도구 사용, 코딩, 지식 작업에서 Sonnet 4.6보다 크게 향상되었습니다. 동시에 바람직하지 않은 행동의 발생률은 전반적으로 더 낮고, 사이버 보안 역량은 Opus 모델보다 훨씬 약합니다(이러한 안전성 측면의 절충 덕분에 수출 통제에 막히지 않고 출시할 수 있었습니다). 모델 ID: claude-sonnet-5(날짜가 없는 고정 스냅샷). 1M 토큰 컨텍스트 창, 최대 128K 출력(Batches API에서는 output-300k-2026-03-24 베타 헤더 사용 시 최대 300K)을 지원하며, 적응형 사고만 사용할 수 있습니다. 신뢰할 수 있는 지식 기준일: 2026년 1월. 요금: 입력/출력 MTok당 $2/$10이며, 현재 표준 정가입니다. Anthropic는 출시 당시 2026년 8월 31일까지 적용되는 출시 기념 요금으로 $2/$10을 발표한 뒤, 이를 그대로 유지했습니다. 요금 페이지에는 9월 1일로 예정되었던 $3/$15 인상이 “시행되지 않는다”고 명시되어 있습니다. v2.1.243에서는 /model 선택 화면과 함께 제공되는 claude-api skill도 업데이트되어, $2/$10이 기간 한정 프로모션이 아닌 정가로 표시됩니다.²⁵¹ 이는 Opus 5.5의 $4/$20보다 50% 낮고, Opus 5의 $5/$25보다 60% 낮습니다. Claude Code에서 Sonnet 5의 effort 매개변수는 기본값이 high입니다(변경하려면 명시적으로 설정하세요). /model claude-sonnet-5로 선택할 수 있습니다.¹⁸⁰²³⁰

v2.1.197(2026년 6월 30일)에서는 Sonnet 5가 당시 Claude Code의 새 세션에 적용되는 기본 모델이 되었습니다. 이후 표준 등급(Pro, Team Standard)의 기본 모델로 유지되다가, 2026년 9월 22일 v2.1.280에서 해당 요금제의 기본 모델이 Opus로 변경되었습니다. 현재 Claude Code에서 Sonnet 5를 기본 모델로 사용하는 요금제는 없으며, v2.1.284부터 Anthropic API에서 /model sonnet은 Sonnet 5.5를 선택합니다. Sonnet 5를 계속 사용하려면 /model claude-sonnet-5 또는 ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5를 사용하세요. 위의 요금제 표를 참고하세요.^{181207220221228}

Sonnet 4.6(2026년 2월 17일, 현재는 Sonnet 5로 대체됨): 균형 잡힌 모델로, claude.ai와 Claude Cowork 전반에서 Sonnet 4.5를 대신해 기본 모델이 되었습니다.⁹³ 요금은 Sonnet 4.5와 동일합니다(MTok당 $3/$15). 더 적은 토큰을 사용하면서 에이전트 검색 성능이 향상되었습니다. 확장 사고, 적응형 사고, 1M 토큰 컨텍스트 창(베타)을 지원합니다. 최대 출력은 64K입니다(v2.1.77에서는 상한 128K).¹¹⁹ 지식 기준일: 2025년 8월(신뢰할 수 있는 지식), 2026년 1월(학습 데이터). 모델 ID: claude-sonnet-4-6. Claude Mythos Preview(2026년 4월 7일): 방어적 사이버 보안 작업을 위한 연구 프리뷰 단계의 최첨단 모델로, Project Glasswing을 통해 제공됩니다.¹³⁹ 초대받은 사용자만 이용할 수 있으며, 일반에는 공개되지 않았습니다. Anthropic는 안전성을 위한 절충으로 Opus 4.7의 사이버 보안 역량을 Mythos보다 의도적으로 낮게 설계했다고 설명하며, 더 높은 수준의 접근 권한이 필요한 정당한 보안 연구자를 위해 https://claude.com/form/cyber-use-case에서 Cyber Verification Program을 운영하고 있습니다.¹⁴⁶

이러한 가격 차이가 중요한 이유: 일반적인 코딩 세션은 입력 토큰 50K~200K와 출력 토큰 10K~50K를 사용합니다. Haiku 5.5에 100K 토큰 이하 프롬프트 요율을 적용하면 세션당 약 $0.01~$0.05입니다. $4/$20 요율의 Opus 5.5로 같은 세션을 진행하면 $0.40~$1.80로, 약 40배 더 비쌉니다(프롬프트 캐싱 할인 적용 전). Opus가 필요하지 않은 작업에는 Sonnet이나 Haiku를 사용하세요.¹²²²

모델별 사용 시점

Haiku: 탐색을 수행하는 subagents, 간단한 파일 검색, 빠른 질문에 사용하세요. 100K 토큰 이하 프롬프트 요율에서는 Opus 5.5보다 약 40배 저렴하고(100K를 초과하는 프롬프트에서는 8배), 응답도 더 빠릅니다. 깊은 추론이 필요하지 않은 백그라운드 작업에 적합합니다.

Sonnet: 비용을 고려해야 하는 일상적인 개발에 주로 사용하는 모델입니다. v2.1.284부터 Anthropic API에서는 Sonnet 5와 동일한 $2/$10 요율로 Sonnet 5.5를 제공합니다.²²⁸ 다만 v2.1.280에서 Pro와 Team Standard의 기본 모델이 Opus로 변경된 이후, Sonnet을 기본 모델로 사용하는 요금제는 없습니다(기본 1M 컨텍스트, 표준 정가 MTok당 $2/$10이며, 9월 1일로 예정되었던 가격 인상은 취소되었습니다).^181251207220 여기서 알아둘 변화는 Sonnet이 이제 직접 선택하는 모델이라는 점입니다. 선택할 이유는 비용으로 설명할 수 있습니다. 같은 1M 컨텍스트를 제공하면서 토큰당 비용은 Opus 5.5의 절반입니다. 기능 구현, 버그 수정, 테스트 작성, 코드 리뷰 등 대부분의 코딩 작업을 처리합니다. 과거 기록: v2.1.197(2026년 6월 30일)에서 Sonnet 5가 모든 요금제의 기본 모델이 되었다는 설명이 이 가이드를 포함해 오랫동안 사용되었습니다. 하지만 모델 설정 문서의 요금제별 설명에 따르면 프리미엄/API 기본 모델은 v2.1.154부터 Opus 4.8, v2.1.219부터 Opus 5로 지정되었습니다. 따라서 실제로 “모든 요금제”는 표준 등급에만 해당했으며, v2.1.280에서는 그마저도 바뀌었습니다. 2026년 6월까지는 Sonnet 4.6이 Sonnet 모델 역할을 맡았습니다.^93147207221 토큰 비용을 낮추거나, 응답 지연을 줄이거나, subagent 운영 비용을 절감하려면 Sonnet을 사용하세요.

Opus: 깊은 추론을 위한 등급입니다. v2.1.280부터 opus 별칭은 Claude Opus 5.5를 선택합니다(MTok당 $4/$20, 1M 컨텍스트, effort 기본값 medium). 같은 릴리스부터 모든 요금제도 Opus로 시작합니다. 따라서 선택의 기준은 언제 다른 모델로 전환할지입니다. 아키텍처 결정, 까다로운 디버깅, 복잡한 시스템 이해, 보안 분석, 장기적인 에이전트 작업에는 Opus를 유지하세요. 작업이 충분히 일상적이어서 추가 추론 능력보다 절반의 토큰 가격이 더 유리하다면 /model sonnet으로 전환하세요.²²⁰²²¹ (opus 별칭은 v2.1.219부터 v2.1.278까지 $5/$25 요율의 Opus 5를 가리켰습니다.)¹⁹⁷ 이 문단의 나머지 내용은 과거 기록으로 남겨 둔 2026년 4월 16일 출시 당시의 Opus 4.7 설명입니다.¹⁴⁴¹⁴⁷ Opus 4.7은 SWE-Bench에서 Opus 4.6보다 3배 많은 프로덕션 작업을 해결하고, CursorBench에서 70%를 기록했으며(기존 58%), 93개 작업으로 구성된 내부 코딩 벤치마크에서 해결률을 13% 높였습니다.¹⁴⁴ Claude Code는 Opus 4.7에서 기본 추론 수준을 xhigh로 설정하며, /effort로 조정할 수 있습니다(v2.1.111 이상).¹⁴⁶¹⁴⁷ Max 구독자는 Anthropic API를 통해 Opus 4.7에서 --enable-auto-mode 없이 Auto Mode를 사용할 수 있습니다. 다른 요금제와 제공업체에서는 요금제별 조건과 관리자 설정에 따라 사용 가능 여부가 달라집니다.¹⁴⁶ 1M 컨텍스트에도 표준 요금이 적용되며, 긴 컨텍스트에 대한 할증은 없습니다. 알아둘 동작 변경 사항: Opus 4.7은 지시를 더 문자 그대로 따르고, 작업 복잡도에 맞춰 응답 길이를 조절하며, 기본적으로 더 적은 수의 subagents를 실행합니다. 또한 사용자를 긍정하거나 동조하는 표현을 줄이고 더 직접적인 어조를 사용합니다. 프롬프트에 중간 진행 상황 보고나 재확인을 강제하기 위한 보조 지시가 있다면 제거해 보세요.¹⁴⁵

Opusplan: 추론 품질이 가장 중요한 계획 단계에서는 Opus를, 속도가 중요한 실행 단계에서는 Sonnet을 사용하는 혼합 모드입니다. 최선의 계획은 필요하지만 개별 수정마다 Opus 수준의 추론까지 필요하지는 않은 복잡한 리팩터링에 적합합니다.

모델 전환

세션 도중:

> /model opus
> /model sonnet
> /model haiku

시작 시:

claude --model opus

환경 변수로 설정:

export ANTHROPIC_MODEL=opus

settings.json에서 설정:

{
  "model": "claude-sonnet-5"
}

모델 선택 목록 직접 구성(modelPicker, v2.1.242 이상): 사용자 설정 파일이나 관리형 설정 파일에서 /model에 표시할 모델을 원하는 순서와 이름으로 지정할 수 있습니다. 기본 제공 목록만 사용할 필요가 없습니다. 각 항목에는 model을 지정하고(Vertex 및 Bedrock ID를 포함해 --model이 허용하는 모든 표기 사용 가능), 선택적으로 label과 description을 추가합니다. replaceBuiltInOptions를 true로 설정하면 지정한 항목에 기본값과 현재 세션의 모델만 추가하여 표시합니다. 이 키에는 프로젝트 설정과 로컬 설정이 적용되지 않으며, availableModels 허용 목록은 여전히 항목을 필터링합니다. Claude Code는 제공할 수 없는 항목을 제거하고, 아직 선택할 수 없는 항목은 이유와 함께 회색으로 표시하며, 남는 항목이 없으면 기본 제공 목록으로 돌아갑니다.²⁵⁰²⁴⁸

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}

subagents 전용 설정:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

v2.1.251부터 CLAUDE_CODE_SUBAGENT_MODEL은 모든 설정을 덮어쓰는 대신 subagent의 기본 모델을 지정합니다. 에이전트 정의의 model:과 생성 시 명시적으로 지정한 모델이 이 값보다 우선합니다.²⁰⁶ v2.1.257부터는 CLAUDE_CODE_SUBAGENT_MODEL_FORCE를 선택적으로 사용해 이전 동작을 복원할 수 있습니다. 이 설정은 생성 시 지정한 모델과 에이전트 정의의 model:을 무시하고, CLAUDE_CODE_SUBAGENT_MODEL의 모델(미설정 시 주 대화의 모델)을 모든 subagent에 적용합니다.²¹¹

대체 모델 체인(v2.1.166 이상): fallbackModel 설정으로 대체 모델을 최대 3개 지정할 수 있습니다. 기본 모델이 과부하 상태이거나 사용할 수 없으면 지정한 순서대로 시도합니다. 이전에는 세션 도중 전환할 때만 사용하던 --fallback-model 플래그가 이제 시작 시점부터 대화형 세션에도 적용됩니다.²⁶³

{
  "model": "claude-opus-4-8",
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

API가 예상치 못한 재시도 불가 오류를 반환하면, 이제 Claude Code는 실패를 알리기 전에 대체 모델로 해당 턴을 한 번 재시도합니다. 덕분에 기본 모델에 일시적인 문제가 생겨도 턴이 중단되는 대신 대체 모델로 처리를 이어 갑니다.²⁶³ v2.1.286부터 Anthropic API가 기본값이나 별칭이 가리키는 모델을 거부하면, Claude Code는 매 턴 실패하는 대신 같은 등급의 이전 모델로 한 번 재시도합니다. 모델 거부나 --fallback-model에 따른 재시도에서 전환된 모델이 고속 실행을 지원하지 않으면 표준 속도로 실행합니다.²³¹

v2.1.178부터는 컨텍스트 압축에도 대체 모델 체인이 적용됩니다. 압축 도중 기본 모델이 과부하 상태가 되거나 사용할 수 없으면, 해당 턴을 실패 처리하는 대신 설정된 fallbackModel/--fallback-model 체인으로 압축 작업을 이어 갑니다. 덕분에 장시간 자율 실행 중 일시적인 모델 오류가 발생하더라도, 복구 가능한 압축 작업 때문에 세션이 중단되는 문제를 막을 수 있습니다.¹⁷³

확장 컨텍스트

대규모 코드베이스나 긴 세션에서는 1M 토큰 컨텍스트를 활성화하세요.

claude --model sonnet[1m]
claude --model opus[1m]           # 1M for a model that reaches it only through [1m], such as Opus 4.6

또는 세션 내에서 설정할 수 있습니다.

> /model sonnet[1m]
> /model opus[1m]

접미사가 필요한 경우(2026년 10월): Anthropic API에서는 Fable 5.1, Fable 5, Sonnet 5.5, Sonnet 5, Opus 4.7 이상(Opus 5.5 포함)이 모든 요금제에서 1M 컨텍스트 창으로 실행되므로 [1m]을 붙여도 달라지는 점이 없습니다. v2.1.287부터는 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, Claude 앱 게이트웨이에도 동일하게 적용됩니다. Opus 4.7 이상과 Fable은 [1m] 접미사 없이도 기본적으로 1M 컨텍스트 창을 사용하며, CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하면 200K로 유지됩니다. v2.1.287 이전에는 이러한 제공업체에서 ANTHROPIC_DEFAULT_OPUS_MODEL에 고정한 모델 ID에 [1m]이 붙어 있지 않으면 Opus 4.8 이상이 200K로 실행되었습니다. 10월 1일에 확인한 Bedrock 및 Agent Platform 문서 페이지는 여전히 해당 환경에서 1M을 사용하려면 접미사가 필요하다고 설명합니다. Sonnet 5는 모든 제공업체에서 1M을 사용합니다. Opus 4.6과 Sonnet 4.6은 [1m] 변형을 통해서만 1M을 사용할 수 있으므로 접미사가 여전히 필요합니다.^223232233

Opus 4.7, Opus 4.6, Sonnet 4.6은 모두 표준 요금에 전체 1M 토큰 컨텍스트 창을 포함하며, 긴 컨텍스트에 대한 할증이 없습니다.¹⁴⁸ 900K 토큰 요청에도 9K 토큰 요청과 동일한 토큰당 요율이 적용됩니다. 프롬프트 캐싱과 배치 처리 할인도 전체 컨텍스트 창에 걸쳐 표준 할인율로 적용됩니다. [1m] 변형 모델의 이용 가능 여부는 요금제에 따라 다릅니다. 1M 컨텍스트를 지원하는 Opus 4.6은 Max, Team, Enterprise에 포함되며, 1M 컨텍스트를 지원하는 Sonnet 4.6을 사용하려면 Max를 포함한 모든 구독 요금제에서 사용량 크레딧이 필요합니다.²³³ (1M 컨텍스트를 지원하는 Opus는 2026년 3월 13일 출시된 v2.1.75부터 Max, Team, Enterprise의 기본 모델이 되었습니다.)¹¹⁷¹⁴⁷ API 및 종량제 사용자는 표준 토큰당 요금으로 전체 1M 컨텍스트를 이용할 수 있습니다.¹⁴⁷

모델 선택기에서 1M 컨텍스트 변형 모델을 비활성화하려면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하세요. v2.1.223부터 이 변수의 적용 범위가 바뀌었습니다. 미리 정해진 변형 모델 목록에만 적용되는 것이 아니라, 기본적으로 1M 컨텍스트 윈도우를 지원하는 모든 모델을 자동 압축으로 200K 이내에 유지합니다. 자동 압축이 실제로 세션을 200K 이내에 유지하지 못하면 시작 시 경고가 표시됩니다. 특정 모델 계열의 비용을 예측하기 위해 이 변수를 설정했다면, 이제 새 1M 모델이 출시되어도 제한이 조용히 풀리지 않고 출시 당일부터 적용됩니다. 같은 릴리스에서는 인식되지 않는 모델 ID를 사용하는 세션도 자동 압축을 통해 추정 컨텍스트 윈도우 안에 유지하도록 변경했습니다. 실제로 더 큰 윈도우를 지원하는 사용자 지정 ID를 등록한 게이트웨이에서는 CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1로 이전 동작을 복원할 수 있습니다.²⁰⁰ v2.1.287부터는 1M이 기본값이 된 Bedrock, Vertex, Foundry 및 Claude 앱 게이트웨이에서도 이 변수를 사용해 Opus 4.7 이상과 Fable을 200K로 유지할 수 있습니다.²³²

v2.1.247부터 Sonnet 5의 기본 자동 압축 윈도우는 전체 1M 컨텍스트입니다. 1M 윈도우를 사용하는 세션은 이제 약 934K가 아닌 약 967K 토큰에서 자동 압축됩니다.²⁴⁵ v2.1.260에서는 한도에 가까워졌을 때 자동 압축하는 동작을 나머지 1M 모델로 확대했습니다. Opus와 Fable 세션도 이제 1M 토큰 한도에 도달하기 직전에 압축되며, 매우 큰 컨텍스트에서 복구를 위한 압축을 수행할 때도 더 이상 10분 후 시간 초과가 발생하지 않습니다.²¹²

사용자 지정 기본 URL에서도 1M 윈도우가 적용됩니다(v2.1.285). 사용자 지정 ANTHROPIC_BASE_URL을 사용하는 세션은 이제 모델이 1M 컨텍스트 윈도우를 지원하면 해당 윈도우를 사용합니다(Opus 4.7 이상, Sonnet 5 이상, Fable). 게이트웨이의 한도가 200K라면 /autocompact 200k를 실행하세요.²²⁹²³³

v2.1.271부터 --resume은 [1m] 윈도우를 유지합니다. 설정된 기본 모델과 다른 모델 계열을 사용하는 세션을 재개해도 더 이상 [1m] 접미사가 사라지지 않습니다.²¹⁶

v2.1.273에서는 컨텍스트 표시기와 자동 압축이 advisor 도구 턴을 실제 컨텍스트 크기의 약 2배로 계산하던 문제를 수정했습니다. 이 문제로 자동 압축이 실제 윈도우의 약 절반 지점에서 실행되고 있었습니다.²¹⁷

현재 모델 확인

> /status

이 명령은 현재 모델, 계정 정보, 적용된 설정 및 기타 세션 상태를 표시합니다.

모델 선택기 레이블(v2.1.51+): 이제 /model 선택기는 고정된 버전의 원시 모델 ID 대신 읽기 쉬운 레이블(예: “Sonnet 4.6”)을 표시하며, 새 버전이 있으면 업그레이드 안내도 제공합니다.⁹⁸ v2.1.219에서는 통합된 Opus 행이 “Opus (1M 컨텍스트)” 대신 단순히 “Opus”로 표시되던 문제를 수정했습니다. 또한 새 릴리스 강조 표시 범위를 최신 모델 이름으로 한정해, 목록의 임의 구간이 아니라 실제로 출시된 모델을 강조하도록 변경했습니다.¹⁹⁶ v2.1.283에서는 Opus가 이미 1M 컨텍스트 윈도우를 지원하는 경우 Opus 행과 기본 모델 이름에서 “(1M 컨텍스트)”를 제거했습니다. 윈도우 자체는 달라지지 않습니다.²²⁶

빠른 모드(v2.1.36+)

빠른 모드는 동일한 모델에서 훨씬 빠른 출력을 제공합니다. 더 저렴한 모델로 전환하는 기능은 아닙니다. 세션 중 /fast로 켜거나 끌 수 있습니다.⁸⁶

> /fast            # Toggle fast mode on/off

지원 모델(v2.1.280 기준): 빠른 모드는 Claude Opus 5.5, Opus 5, Opus 4.8에 적용되며, v2.1.280부터 Opus 5.5가 빠른 모드의 기본 모델입니다(v2.1.219부터는 Opus 5가 기본 모델이었습니다). v2.1.219에서는 Opus 4.7의 빠른 모드 지원이 제거되었으며, Sonnet, Haiku, Fable에서는 이 기능을 지원한 적이 없습니다. 빠른 모드는 여전히 Claude API(Claude Managed Agents 포함)에서만 연구 프리뷰로 제공되며, Amazon Bedrock, Google Cloud, Microsoft Foundry 또는 Claude Platform on AWS에서는 사용할 수 없습니다. 이용하려면 승인이 필요합니다. 계정 담당자에게 문의하거나 대기자 명단에 등록하세요.^196198223

원격 세션(v2.1.271): 이제 클라우드 세션과 자체 호스팅 실행기를 포함한 Claude Code Remote 세션에서도 빠른 모드를 사용할 수 있습니다. 호스트의 빠른 모드 설정이 적용되며, 세션 안에서 직접 /fast를 입력할 수도 있습니다. 두 방법 모두 조직에서 빠른 모드를 허용한 경우에만 작동합니다. 같은 릴리스에서는 /fast off도 수정했습니다. 조직에서 빠른 모드를 비활성화했을 때 “빠른 모드를 사용할 수 없습니다”라고 응답하던 대신, 이제 빠른 모드를 끕니다.²¹⁶

요금(빠른 모드):^198222223

Opus 4.7의 함정(v2.1.219). 빠른 모드를 지원하지 않는 모델의 동작이 모두 같지는 않습니다. 이제 claude-opus-4-7에 speed: "fast"를 지정해 요청하면 오류가 반환됩니다. 표준 속도로 조용히 전환되지 않습니다. Opus 4.6은 예외이므로 이 차이를 알아두세요. Opus 4.6은 speed: "fast"를 받아들이지만 실제로는 표준 속도로 실행하고, 표준 요금을 부과하며, usage.speed: "standard"를 보고합니다. 하네스에서 4.7을 고정해 사용하면서 빠른 모드 요청이 별도 오류 없이 표준 속도로 처리될 것으로 기대했다면, 이제 해당 요청은 바로 실패합니다. 고정 모델을 Opus 5.5, Opus 5 또는 Opus 4.8로 변경하세요.¹⁹⁸

빠른 모드를 사용하면 좋은 경우: - 지연 시간이 병목인 상황에서 작은 변경을 빠르게 반복할 때 - 비용보다 속도가 우선인 테스트, 상용구 또는 반복 코드 생성 작업 - 비슷한 작업 목록을 순서대로 처리할 때

빠른 모드를 사용하지 않는 편이 좋은 경우: - 오래 실행되는 에이전트 작업(전체 실행에 걸쳐 비용이 2배로 늘어납니다) - 백그라운드 subagents 작업(출력을 기다리는 사람이 없습니다) - 예산을 아껴야 하는 세션

빠른 모드는 전체 1M 컨텍스트 윈도우를 포함합니다(v2.1.50+). 입력 토큰이 200K를 넘는 요청을 포함해 전체 컨텍스트에 동일한 요금 배수가 적용되며, 긴 컨텍스트에 대한 추가 할증은 없습니다. 이 배수는 프롬프트 캐싱 및 데이터 상주 위치에 따른 요금 배수에 추가로 곱해집니다.⁹⁶¹⁹⁸

운영 시 참고 사항. 빠른 모드에는 표준 Opus 한도와 별개인 자체 사용량 제한이 있습니다. 이를 초과하면 retry-after가 포함된 429가 반환됩니다(anthropic-fast-*-tokens-* 응답 헤더는 남은 용량을 알려줍니다). 빠른 모드와 표준 모드를 전환하면 프롬프트 캐시가 무효화됩니다. 속도가 다른 요청끼리는 캐시된 접두사를 공유하지 않으므로, 세션 도중 /fast를 전환하면 캐시 미스로 인한 비용이 발생합니다. 빠른 모드는 Batch API 또는 Priority Tier 약정과 함께 사용할 수 없습니다.¹⁹⁸

전문가 팁: 빠른 모드는 opusplan과 잘 맞지 않습니다(opusplan은 이미 Opus와 Sonnet을 혼합해 사용하며, 빠른 모드는 Opus가 담당하는 부분에만 영향을 줍니다). 비용보다 지연 시간이 더 중요한 경우에 사용하고, 자율 실행이나 일괄 작업에서는 비활성화하세요. /fast를 사용하려면 추가 사용량이 필요하며, Team/Enterprise 관리자가 먼저 활성화해야 할 수도 있습니다(v2.1.37에서 수정). CLAUDE_CODE_DISABLE_FAST_MODE=1로 완전히 비활성화할 수 있습니다. v2.1.218부터 Claude Code은 /config model=<x> 또는 Remote Control을 통한 모델 전환으로 빠른 모드 상태가 바뀌면 알림을 제공합니다. v2.1.219에서는 전환, 재연결 또는 조직 확인 실패 후 Remote Control 클라이언트에 이전 빠른 모드 상태가 남아 있던 문제를 수정했습니다.^86149195196

Advisor 도구(실험적 기능)

advisor 도구를 사용하면 Claude이 작업의 주요 시점에 두 번째 모델에 조언을 구할 수 있습니다. 보통 더 뛰어난 모델을 사용하며, 접근 방식을 확정하기 전, 오류가 반복될 때, 작업 완료를 선언하기 전 등이 해당됩니다. advisor는 Anthropic의 인프라에서 서버 도구로 실행되며, 모든 도구 호출과 결과를 포함한 전체 대화를 전달받아 조언을 반환합니다. Claude은 이 조언을 반영한 뒤 작업을 계속합니다. 호출 시점은 Claude이 결정합니다. 프롬프트에서 조언을 구하도록 요청할 수 있지만, 호출 횟수를 제한하거나 호출을 강제하는 설정은 없습니다. 이 도구는 실험적 기능이며, 구독 계정과 API 과금 계정이 Anthropic API에서 사용할 수 있습니다. v2.1.300부터 Claude Platform on AWS에서도 지원됩니다(문서 페이지에는 아직 해당 플랫폼을 지원하지 않는다고 나와 있습니다). 게이트웨이를 통해 사용할 때는 요청이 변경 없이 Anthropic API에 도달해야 합니다. 또한 기능 플래그를 가져올 수 있어야 하므로, DISABLE_TELEMETRY 같은 변수가 설정되어 있으면 비활성화된 상태로 유지됩니다.²⁷³²⁷⁴ 활성화 방법. 세 가지 방법이 있습니다. 세션 도중 /advisor <model>을 실행하면 사용자 설정의 advisorModel에 선택한 모델이 저장됩니다(인수 없이 /advisor를 실행하면 터미널에서는 선택기가 열리고, -p, SDK, 데스크톱, Remote Control 세션에서는 현재 어드바이저가 출력됩니다. 이러한 세션에서는 v2.1.260부터 텍스트 형식의 명령을 사용할 수 있습니다. /advisor off는 어드바이저를 끕니다). 설정 파일에 "advisorModel": "opus"를 지정할 수도 있습니다. 또는 한 세션에만 적용하려면 claude --advisor <model>을 사용합니다. 이 플래그는 --help에 표시되지 않으며, 설정보다 우선하고 모델 조합이 유효하지 않으면 시작 시 종료됩니다. 별칭으로는 fable, opus, sonnet을 사용할 수 있으며, 전체 모델 ID도 지정할 수 있습니다. CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1은 명령을 제거하고 설정을 무시하며 플래그가 아무 효과도 내지 않게 합니다.²⁷⁴

모델 조합, 비용, 표시 정보. 어드바이저는 주 모델과 동급이거나 상위 모델이어야 합니다. Opus 4.7과 4.8은 Fable, Opus 4.7 이상, Sonnet 5.5(v2.1.287부터)를 지원합니다. Sonnet 5.5는 Fable, Opus 5 이상, Sonnet 5.5를 지원합니다. Opus 5와 5.5는 Fable과 Opus 5 이상을 지원합니다. Fable 5.1은 Fable 5.1만 지원합니다. Haiku 4.5는 어드바이저를 호출할 수 있지만 어드바이저 역할을 할 수는 없습니다. 주 모델보다 하위인 어드바이저는 연결되지 않으며, 알림으로 그 사실을 안내합니다. API에서 거부한 어드바이저는 별도 알림 없이 해당 대화의 나머지 부분에서 제외됩니다. subagents도 동일한 조합 검사를 거쳐 어드바이저를 상속하며, availableModels 허용 목록도 적용됩니다. 각 호출에는 어드바이저 모델의 입력 및 출력 요금이 청구되거나 요금제 사용 한도에 반영됩니다. 다만 Fable 사용료를 사용량 크레딧으로 청구하는 요금제에서는 /model fable을 통해 한 번 동의한 후 Fable 어드바이저의 사용료도 사용량 크레딧으로 청구됩니다. 어드바이저를 켜거나 꺼도 주 모델의 프롬프트 캐시는 유지됩니다. 어드바이저 자체가 대화를 읽는 작업은 캐시되지 않습니다. 대화 기록의 Advising 줄에는 검토 완료, 거절, 사용 불가 상태가 표시되며, Ctrl+O로 조언 내용을 볼 수 있습니다. Mods에서는 어드바이저 호출이 turn.step의 serverToolUses로 표시됩니다(v2.1.290).²⁷⁴

추론 노력 제어(v2.1.111+, Opus 4.7)

Opus 4.7에는 속도와 지능 사이의 균형을 조절하는 새로운 추론 노력 설정이 도입되었습니다. 세션 중에 /effort를 사용하세요.

> /effort              # opens an interactive slider (arrow keys + Enter)
> /effort xhigh        # set directly

모델별 저장(v2.1.251+): 이제 /effort는 기본 추론 노력 수준을 모델별로 저장하므로 모델을 전환해도 각 모델의 설정이 유지됩니다. Opus에서 xhigh를 사용하던 설정이 더 이상 Haiku로 따라가지 않습니다(CHANGELOG: “모델을 전환해도 각 모델의 설정이 유지되도록 /effort가 기본 추론 노력 수준을 모델별로 저장하게 변경했습니다”). max는 세션에만 적용된다는 예외가 여전히 유지됩니다.²⁰⁶ v2.1.284 슬라이더 키: effortSlider:decreaseEffort, increaseEffort, toggleUltracode 키 바인딩 동작을 사용하면 keybindings.json에서 슬라이더의 화살표 키와 Tab 키를 다시 지정할 수 있습니다.²²⁸ v2.1.257의 두 조절 기능 개선: /effort는 /model과 같은 방식으로 s를 입력받아 현재 세션에만 적용할 수준을 선택할 수 있습니다. 또한 --effort 플래그도 이제 세션 범위로 적용됩니다. 새 모델의 기본 추론 노력 수준을 유지하는 제한을 영구적으로 해제하지 않고 해당 세션에서만 해제합니다(CLI 참조 문서에서는 기본값을 “이 세션에서만 재정의하며 저장하지 않습니다”라고 설명합니다).²¹¹²⁴³

Max의 자동 모드(v2.1.111+)

자동 모드는 모든 요금제와 제공업체에서 대화형 터미널 및 VS Code 세션에 기본으로 적용되는 시작 권한 모드입니다(v2.1.283-284). 또한 v2.1.285부터 v2.1.302에서 변경 사항을 되돌리기 전까지는 타사 제공업체를 사용하거나 원격 측정을 끈 경우의 claude -p 및 Python Agent SDK 세션에도 기본으로 적용되었습니다. Pro, Max, Team에서는 2026년 8월 14일부터 기본값이었습니다(8월 7일 발표). 발표에 포함된 연구 수치, 자동 모드를 사용하지 않도록 설정하는 방법, 여전히 수동 모드로 시작하는 세션은 권한 모드를 참조하세요.^{203226227228229}

별도의 분류 모델이 각 동작을 실행하기 전에 검토하여 사용자 의도에 부합하고 안전한지 확인합니다. v2.1.210부터는 Claude Sonnet 5가 이 역할을 담당합니다.¹⁸⁷ --permission-mode auto로 자동 모드 세션을 시작하세요. v2.1.111에서 기존 --enable-auto-mode 플래그는 제거되었습니다.

지원 범위 확대 과정:

• 사용하지 않도록 설정: CLAUDE_CODE_AUTO_MODE_SERVER=0으로 설정하면 요청이 사용량에 포함되는 로컬 분류기를 계속 사용하며, 1로 설정하면 서버 검사를 사용합니다. v2.1.281 이전에는 Anthropic API에 직접 연결할 때 이 변수를 읽지 않았습니다. v2.1.281부터는 직접 연결에도 적용되며, 자동 모드 과금 문서에도 직접 연결에서 이 변수를 사용하려면 v2.1.281 이상이 필요하다고 명시되어 있습니다.²²⁴²²⁷ 문서는 이 변수를 임시 변수로 설명합니다. 이 변수가 설정되지 않은 상태에서 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정해도 서버 검사가 중단됩니다.
• 서버 검사가 세션에 전달되지 않는 경우: 가장 흔한 원인은 게이트웨이나 프록시가 요청의 safeguards 필드를 제거하거나, 응답에서 safeguard_results를 누락하거나, 도구 사용 ID를 다시 쓰는 것입니다. Claude Code은 “이 세션은 지원 대상이 아닙니다”라는 알림을 한 번 표시하고, 게이트웨이를 식별할 수 있으면 그 이름도 알려 줍니다. 이후 세션이 끝날 때까지 자체 분류기 요청을 사용하며, 이 요청에는 요금이 부과됩니다. -p 모드에서는 알림이 stderr로 전달되고, stream-json 출력에서는 system 경고가 발생합니다. Pro, Max, Team 세션에는 이 알림이 표시되지 않습니다. 게이트웨이에서는 요청 필드와 응답 키를 변경 없이 그대로 전달하도록 수정하면 됩니다.
• 세션 확인: /status에는 자동 모드 서버 행이 표시됩니다. 서버 검사가 세션의 작업 실행 여부를 결정하는 동안에는 Enabled로, 로컬 분류기로 전환된 뒤에는 Disabled로 표시됩니다.²¹⁹

자동 모드는 보안 경계가 아닙니다. 아래에서 설명하는 내용 대부분은 분류기를 강화하는 조치이며, 분류기는 샌드박스가 아닙니다. 2026년 8월 26일, 프롬프트 인젝션 연구자 Johann Rehberger는 자동 모드의 Claude Code Opus 5를 대상으로 실제 작동하는 공격 체인을 공개했습니다. 그는 소규모 표본에서 60-80%의 공격 성공률을 보고했습니다. 격리된 python3 자식 프로세스를 생성하는 주 공격 체인은 5회 중 3회 성공했고, 페이로드가 헤드리스 claude -p 인스턴스를 생성하는 변형의 두 가지 설정은 각각 5회 중 3회와 4회 성공했습니다. 다만 본인도 이 수치는 소규모 표본의 결과이며, 보편적인 공격 성공률 측정치는 아니라고 단서를 달았습니다.²¹⁰ 이 체인은 각 단계가 개별적으로는 타당해 보이므로 살펴볼 필요가 있습니다. 서버가 WebFetch에 HTTP 415로 응답하면 에이전트는 curl로 전환합니다. 다운로드한 압축 파일은 임시 디렉터리에 풀리며, 그 안에는 매니페스트, Base85/zlib로 인코딩된 데이터 레코드 7개, 네이티브 바이너리, struct.py가 들어 있습니다. Claude은 신뢰할 수 없는 바이너리의 실행을 거부한 다음, 직접 Python 디코더를 작성하고 그 디렉터리 안에서 실행합니다. 디코더가 base64를 가져오면 base64는 struct를 가져오고, Python은 공격자의 struct.py를 먼저 찾아 불러옵니다. 이 과정에는 명백히 악의적인 지시가 없습니다. 인젝션은 공격자가 장악한 경로를 작업을 마치는 가장 합리적인 방법으로 보이게 만들기만 하면 됩니다. Rehberger는 몇 차례 실행에서 Claude이 침해를 알아차린 뒤 악성코드 프로세스를 종료하려 했지만, 자동 모드가 정리 명령을 거부했다고도 보고했습니다.²¹⁰ 그는 이 발견을 Anthropic이 홍보한 수치와 대조합니다. 의뢰를 받아 수행된 외부 기관의 평가에서는 72개 시나리오를 각각 10회 실행했을 때 자동 모드의 Opus 5가 프롬프트 인젝션 공격 성공률 0.00%를 기록했다고 보고했습니다. 그의 공격 체인은 그 평가에 포함되지 않았습니다. 따라서 벤치마크 결과가 0.00%라는 사실과 실제로 작동하는 코드 실행 공격 체인이 존재한다는 사실은 동시에 성립합니다. 그는 두 메시지가 서로 맞지 않는다고 해석합니다.²¹⁰ 공격의 분류도 살펴볼 필요가 있습니다. Simon Willison은 8월 30일 업데이트에서, 모델이 공격자의 지시를 읽고 따르는 과정이 전혀 없으므로 이는 전형적인 프롬프트 인젝션이 아니라 실행 환경을 혼동시키는 공격이라는 독자의 지적에 동의했습니다.²¹⁰

Anthropic은 해당 동작이 설계대로 작동한다며 보고서를 Informative로 종결했습니다. Rehberger가 전한 입장은 시스템 설계의 전제로 삼아야 합니다. 자동 모드는 보안을 보장하는 장치가 아니라 가능한 범위에서 최선을 다하는 분류기입니다. 개별적으로는 무해한 단계를 치밀하게 조합한 인젝션 체인은 분류기가 탐지할 것으로 기대하는 범위를 벗어나며, 실제로 피해를 격리하는 경계는 OS 수준의 격리와 외부로 나가는 네트워크 통신 제어입니다.²¹⁰ 이는 아래의 강화 조치와 모순되지 않습니다. 오히려 그 조치를 이해하는 올바른 관점입니다. 자동 모드는 사용자가 응답해야 하는 승인 요청을 줄이고, 문서에 명시된 파괴적 작업을 차단합니다. 하지만 신뢰할 수 없는 입력을 다루는 세션을 안전하게 만들어 주지는 않습니다. 세션이 가져온 웹 페이지, 다운로드한 압축 파일, 이슈 본문, 타사 MCP 서버처럼 공격자의 영향을 받을 수 있는 콘텐츠를 다룬다면, 실제로 피해 범위를 제한하는 수단은 모델 외부에 있습니다. 컨테이너나 VM, 외부로 나가는 네트워크 통신 제한, 에이전트의 실제 동작 모니터링, 그리고 유출되면 곤란한 SSH 키와 클라우드 자격 증명을 보관하지 않는 홈 디렉터리가 그 수단입니다. 자동 모드의 승인은 해당 작업이 안전했다는 증거가 아닙니다.

기본 규칙을 유지하면서 사용자 지정 규칙 추가하기 (v2.1.118+). 이전 버전에서는 autoMode.allow, autoMode.soft_deny, autoMode.environment에 기본 목록과 사용자 지정 목록 중 하나만 사용할 수 있었습니다. 직접 목록을 정의하면 내장 안전 규칙이 사라졌습니다. $defaults 특수 값은 이 문제를 해결합니다. 이 값을 넣은 바로 그 위치에 내장 목록이 펼쳐지므로, 기본 규칙 앞뒤에 사용자 지정 규칙을 추가할 수 있습니다.¹⁵²

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // your additions, prepended
      "$defaults",                // built-in allow list inserted here
      "Bash(git push:origin/feature/*)"  // appended after
    ]
  }
}

/permissions에서 분류기 규칙 편집하기 (v2.1.246). /permissions를 실행하고 자동 모드 탭을 여세요. 이 탭은 해당 세션에서 자동 모드를 사용할 수 있을 때만 나타납니다. 분류기가 읽는 모든 설정 범위의 allow, soft_deny, hard_deny, environment 항목이 나열되며, 각 섹션에서 내장 규칙이 적용 중인지도 표시됩니다. 관리형 설정이나 --settings에서 가져온 항목은 읽기 전용이며, 모든 변경 사항은 ~/.claude/settings.json에 저장됩니다. 섹션에 첫 규칙을 추가하면 "$defaults"도 함께 삽입되어 내장 규칙이 계속 적용됩니다. 섹션별로 내장 규칙을 켜거나 끌 수 있지만, 끄려면 해당 섹션에 직접 작성한 규칙이 하나 이상 있어야 합니다. environment는 편집기에서 하나의 문서로 열립니다.²⁴⁹²⁴⁷

사용 동의 시 “다시 묻지 않기” 선택 (v2.1.118+). 이제 자동 모드 사용 동의 창에 “다시 묻지 않기” 옵션이 표시됩니다. 자주 사용하는 사용자는 플래그를 지정하는 스크립트를 작성하지 않고도 설명 창이 다시 나타나지 않도록 할 수 있습니다.¹⁵²

파괴적 명령에 대한 안전장치 (v2.1.183). 이제 자동 모드는 세션에서 사용자가 명시적으로 요청하지 않은 특정 비가역적 명령을 강제로 차단합니다. 로컬 작업을 버리도록 요청하지 않았을 때의 파괴적 git 작업(git reset --hard, git checkout -- ., git clean -fd, git stash drop), 에이전트가 현재 세션에서 만든 커밋이 아닌 경우의 git commit --amend, 특정 스택을 지정하지 않았을 때의 인프라 삭제(terraform destroy, pulumi destroy, cdk destroy)가 해당됩니다. 이 조치는 작업물을 조용히 잃게 하거나 환경을 철거하는 바로 그 작업들에 대해 분류기의 오판으로 발생할 수 있는 피해 범위를 줄입니다. 에이전트는 여전히 이러한 명령을 실행할 수 있지만, 자의적으로 실행할 수는 없으며 사용자의 명시적 지시가 있어야 합니다.¹⁷⁴

모든 셸 명령 분류하기 (v2.1.193). 기본적으로 자동 모드 분류기는 임의 코드 실행 패턴과 일치하는 셸 명령만 검토하고, 일상적인 명령은 건너뜁니다. 새로운 autoMode.classifyAllShell 설정을 사용하면 모든 Bash/PowerShell 명령이 분류기를 거칩니다. 모든 셸 호출을 검토하고 싶을 때 약간의 지연을 감수하는 대신 안전장치를 강화할 수 있습니다. 같은 릴리스에서는 세션 기록, 거부 알림 토스트, /permissions의 최근 거부 내역에 자동 모드의 거부 사유도 표시하므로, 이제 명령이 차단되면 그 이유를 확인할 수 있습니다.¹⁷⁹

추가된 보안 강화 규칙 3가지 (v2.1.205). 이제 자동 모드는 세션 기록 파일의 변조를 차단하여 에이전트가 감사 기록 자체에 손대지 못하게 합니다. 또한 문맥에서 값을 확인할 수 없는 변수를 대상으로 rm -rf를 실행하기 전에 승인을 요청하여, $DIR 값을 모르는 상태에서 rm -rf $DIR을 실행하는 유형의 사고를 방지합니다. 마지막으로 백그라운드 작업 알림에 사람의 입력이 없었다는 사실을 명시하여, 기록 안에 조작된 “사용자가 승인함” 문구가 있어도 실제 실행을 허용하는 승인으로 둔갑하지 못하게 합니다.¹⁸³ 세 번째 규칙은 기억해 둘 만한 프롬프트 인젝션 방어 원칙입니다. 승인은 반드시 승인 채널을 통해 전달되어야 하며, 이제 하네스가 이 전제를 명시합니다. 명령 치환으로도 치명적인 삭제를 숨길 수 없습니다(v2.1.208). 이제 rm -rf ~처럼 치명적인 삭제 명령은 $(...), 백틱 또는 프로세스 치환(<(...)) 안에 들어 있어도 확인을 요청하며, --dangerously-skip-permissions와 자동 모드에서도 확인을 요청합니다. 파괴적인 명령을 치환 구문으로 감싸도 더 이상 안전장치를 우회할 수 없습니다.¹⁸⁶

자동 모드 상태 초기화: claude auto-mode reset(v2.1.212). 새 하위 명령으로 터미널에서 자동 모드 상태를 초기화할 수 있습니다. 확인 메시지를 건너뛰려면 --yes를 전달하세요.¹⁸⁹

claude auto-mode reset          # Confirmation prompt
claude auto-mode reset --yes    # Skip confirmation (scripts)

대화 상자는 줄이고 검토 수준은 유지합니다(v2.1.218). 이전에는 위험한 rm, 백그라운드 실행 &, 의심스러운 Windows 경로라는 3가지 검사 항목이 권한 대화 상자로 자동 모드를 중단했지만, 이제는 자동 모드 분류기가 판단합니다. 따라서 항목이 감지될 때마다 사용자가 개입하지 않아도 안전 검토는 계속 이루어집니다. 같은 릴리스에서는 이 동작을 자동 모드를 사용하는 계획 모드에도 적용합니다. 정적 분석기가 읽기 전용이라고 입증하지 못한 Bash 명령도 더 이상 확인을 요청하지 않습니다. 대화 상자로 처리를 넘기는 대신 분류기가 판단합니다.¹⁹⁵

격리 탈출 규칙(v2.1.257). 분류기의 자동 승인 금지 목록에 “격리 탈출” 규칙이 추가됩니다. 클라우드 메타데이터 자격 증명 가져오기, 네트워크 외부 통신 제한 우회, 다른 테넌트에 대한 접근은 환경에서 예상된 동작으로 표시하지 않는 한 더 이상 자동 승인되지 않습니다. 위의 주의 사항과 같은 맥락으로 이해해야 합니다. 이는 분류기를 지속적으로 강화하면서 문서화된 거부 유형을 하나 더 추가한 것이며, 자동 모드의 본질이 달라진 것은 아닙니다.²¹¹

작업 디렉터리 외부 읽기 시 한 번 확인합니다(v2.1.257). 이제 자동 모드는 세션에서 작업 디렉터리 외부의 파일을 처음 읽기 전에 한 번 확인을 요청합니다. v2.1.284부터는 이 메시지에 예, 하지만 다음에는 다시 묻기 옵션도 표시됩니다.²²⁸ 함께 제공되는 permissions.blockReadsOutsideWorkingDirectories 설정을 사용하면 확인을 요청하는 대신 해당 읽기를 전면 차단합니다.²¹¹ v2.1.273에서는 검사기가 파악할 수 없는 동작에도 이 두 가지 방식을 적용합니다. 완전히 분석할 수 없는 Bash 명령은 검사를 건너뛰는 대신 확인을 요청합니다. 또한 차단 설정이 활성화되어 있으면 저장소 설정에서 지정한 메모리 디렉터리를 프롬프트에 불러오거나, 회상하거나, 인덱싱하거나, 메모리 추출에 사용하지 않습니다.²¹⁷

다이어그램 렌더러 URL을 업로드로 취급합니다(v2.1.261). mermaid.live 방식처럼 콘텐츠를 URL 자체에 인코딩해 공개 다이어그램 렌더러로 전달하는 링크는 사용자가 요청하지 않는 한 더 이상 자동 승인되지 않습니다. 분류기는 이런 링크를 업로드로 취급합니다. 데이터가 URL 자체에 담겨 전달되고, 페이지가 열리면 렌더러 사이트의 스크립트가 이를 읽을 수 있기 때문입니다. mermaid.live 방식의 링크는 URL 프래그먼트에 데이터를 담으며, 브라우저는 이를 네트워크 요청에 실어 보내는 대신 페이지의 JavaScript에 전달합니다. 위의 주의 사항과 같은 맥락입니다. 새로운 경계를 설정한 것이 아니라 분류기를 강화하면서 또 하나의 데이터 유출 경로를 차단한 것입니다.²¹⁴

분류기의 두 가지 실패 유형에 중단 조건이 생깁니다(v2.1.280). 이 릴리스 이전에는 안전 검사에서 사용할 수 있는 판정이 돌아오지 않을 때 자동 모드가 이를 처리할 방법이 없었습니다. 사용자가 보기에는 두 허점 모두 같은 현상으로 나타났습니다. 승인될 수 없는 작업에 토큰을 소모하며 턴이 끝없이 반복되었습니다. v2.1.280에서는 각 유형에 종료 상태를 부여합니다.

서버 검토 대상 명령이 늘어납니다(v2.1.281). 분류기 검토가 서버 측에서 실행되는 경우, 읽기 전용 셸 명령과 샌드박스에서 실행되는 셸 명령도 이제 검토를 기다리며 문제가 감지되면 차단됩니다. 거부 메시지도 바뀌어 Claude가 거부 대상을 해당 명령 자체에 한정하지 않고 그 명령이 만들어 내는 결과까지 포함해 이해하도록 합니다. 새 프로세스에서 세션을 재개하면 분류기는 이전 프롬프트 캐시를 다시 작성하지 않고 재사용할 수 있습니다. 또한 /insights에는 최근 세션에서 자동 모드가 처리할 수 있었던 권한 확인 요청 수를 추정하는 자동 모드 권장 사항이 추가됩니다.²²⁴

무인 세션이 rm 확인을 무한정 기다리지 않습니다(v2.1.281). 자동 모드와 --dangerously-skip-permissions에서는 위험한 rm 확인 요청에 대한 응답을 2분 동안 기다린 다음, 명령 수정 힌트와 함께 명령을 거부하여 무인 세션이 계속 진행되도록 합니다. CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT=1을 설정하면 이 시간 제한이 비활성화됩니다. rm -rf "$(pwd)"처럼 대상이 명령 치환의 출력으로만 이루어진 재귀적 rm은 이전에는 두 모드 모두에서 확인 없이 실행되었습니다. 이제는 CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT=1을 설정하지 않는 한, Bash 허용 규칙과 일치하더라도 확인을 요청합니다. 위험한 rm 검사는 셸 변수 뒤에 최상위 디렉터리 이름이 붙은 대상, 작업 디렉터리에서 파생된 변수로 지정한 대상, 백슬래시로만 이루어진 대상을 삭제하려는 경우에도 문제를 감지합니다.²²⁴ v2.1.299부터는 rm을 실행하지 않는 셸 -c 스크립트가 더 이상 확인을 요청하지 않으며, Claude Code가 읽을 수 없는 스크립트 안에서 실행 중에 구성되는 rm은 CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1이 설정된 경우에만 확인을 요청합니다.²⁷¹

인라인 ! 셸은 분류기 검토에서 제외되고, subagents의 결과 반환은 포함됩니다(v2.1.271). 새로운 거부 유형이 아니라 처리 방식 두 가지가 바뀝니다. 이제 skills 또는 슬래시 명령의 인라인 ! 셸 명령은 분류기 대신 기본 모드의 권한 규칙을 따릅니다. 어떤 규칙으로도 허용 여부를 결정하지 못한 명령은 검토를 거치는 도구 호출로 실행됩니다. 또한 subagents는 마지막 메시지를 사후 검토받는 대신, 안전 분류기가 검토하는 전용 반환 호출을 통해 호출자에게 결과를 보고합니다. 검사 시점이 결과를 넘긴 뒤에서 넘기는 순간으로 이동한 것입니다.²¹⁶

v2.1.309 및 v2.1.310의 새로운 기능

Claude Code 2.1.309는 2026년 10월 22일(npm 20:34 UTC, GitHub 릴리스 22:18 UTC, 항목 79개)에, 2.1.310은 10월 23일(npm 21:20 UTC, GitHub 릴리스 23:39 UTC, 항목 26개)에 출시되었으며, 두 릴리스 모두 공식 CHANGELOG와 내용이 일치합니다. npm의 latest와 next는 2.1.310이며, stable은 2.1.292에서 2.1.308로 이동했습니다. 2.1.308의 릴리스 노트 전체 내용은 “버그 수정 및 안정성 개선”이며, 2.1.303(10월 18일)에도 같은 한 줄이 적혀 있습니다. 2.1.302부터 2.1.310 사이에 누락된 버전은 없습니다.²⁷⁸

샌드박스 및 권한 수정(v2.1.309). macOS와 Linux에서 샌드박스로 실행되는 Bash 명령은 더 이상 각 명령을 실행하기 전에 샌드박스 외부에서 셸 시작 파일을 실행하지 않습니다. macOS의 denyWrite 글로브 패턴은 패턴에 지정된 폴더에 심볼릭 링크를 통해 접근할 때 경로의 실제 위치에 적용됩니다. 샌드박스 명령과 자동 승인된 편집은 더 이상 --mcp-config로 전달한 MCP 설정 파일을 수정할 수 없습니다. Linux에서는 백그라운드 명령이 세션 종료 후에도 계속 실행되더라도 쓰기 거부가 해제되지 않습니다. 또한 샌드박스가 활성화되어 있지만 실행할 수 없는 경우, 설정에서 샌드박스 제외 대상으로 지정한 명령도 샌드박스의 쓰기 허용 목록에 있는 경로에 쓰기 전에 확인을 요청하며, 이 경우 샌드박스 없이 실행하는 대체 방식은 거부됩니다. Bash 권한 검사는 리디렉션이 실패할 수 있는 명령이 설정한 변수를 더 이상 신뢰하지 않으며, git 앞의 cd가 다른 명령으로 감싸져 있거나 접두사가 붙어 있으면 확인을 요청하고, 서브셸 안의 Bash 리디렉션에도 Edit(path) 거부 규칙을 적용합니다. worktree 격리 보호 장치는 로케일 접두사가 붙은 명령과 zsh 산술 명령을 더 폭넓게 거부하며, 프로필 저장소 쓰기 보호는 심볼릭 링크로 연결된 설정 디렉터리를 통해 접근할 때도 적용됩니다. 이제 sed -i는 파일 편집을 모의 실행한 미리보기 대신 표준 Bash 확인 메시지를 표시하고 작성된 그대로 실행되며, 다른 Bash 편집과 마찬가지로 /rewind로 더 이상 복원되지 않습니다. 샌드박스 모드를 참조하세요.²⁷⁸ 신뢰, worktree, skills(v2.1.309). claude ultrareview를 사용하려면 작업 공간을 신뢰해야 합니다. 터미널에서는 신뢰 여부를 묻고, 그 외 환경에서는 실행을 거부합니다. 스크립트에서는 값 없이 --trust-workspace를 전달하거나 CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1을 설정합니다. 이제 데스크톱 앱과 VS Code의 권한 우회 모드에서 위험한 rm 및 rmdir 명령에 대한 확인이 필요하면, 명령을 즉시 거부하고 수정 방법을 안내하므로 무인 세션이 계속 진행됩니다. Worktree를 생성하거나 재사용할 때 더 이상 필요에 따라 git 객체를 가져오지 않습니다(Bash 샌드박스를 사용하는 부분 클론에서는 먼저 객체를 가져옵니다). 또한 worktree와 브랜치 체크아웃은 git replace 참조를 무시합니다. 크기 제한을 초과한 하위 CLAUDE.md는 이제 앞부분만 로드하므로, 그 아래의 파일을 읽은 뒤 세션이 반복해서 압축되는 현상을 방지합니다. --add-dir 폴더의 skill 이름이 다른 skill과 겹치면 <folder>:<name>으로 제공되며, /verify와 /code-review는 하위 패키지에 있는 자체 skill을 찾습니다. 분할 창의 에이전트 팀원은 리더의 도구 거부 규칙과 --tools 규칙을 상속하며, /rewind는 /code-review --fix, subagent 또는 셸 명령을 통해 체크포인트에 기록된 파일을 변경한 턴을 표시합니다.²⁷⁸

v2.1.310. Monitor 도구와 plugin 모니터는 Bedrock, Vertex, Foundry에서도 작동하며, 텔레메트리나 비필수 트래픽을 비활성화한 경우에도 작동합니다. 이러한 환경에서는 이제 포그라운드에서 장시간 대기하는 작업도 차단됩니다. 게이트웨이 또는 호환 서버가 effort-2025-11-24 베타 값이나 대화 도중의 시스템 메시지를 거부하면, 해당 요소를 제외하고 요청을 재시도합니다. “Prompt is too long” 오류 후 압축할 때 base64나 SVG처럼 밀도 높은 텍스트를 과도하게 남기지 않습니다. cleanupPeriodDays가 매우 커도 백그라운드 정리 작업이 붙여넣은 이미지 같은 최근 파일을 삭제하지 않습니다. 파일 읽기 권한 요청에는 심볼릭 링크가 가리키는 경로가 표시됩니다. 자동 모드에서 작업 디렉터리 외부를 처음 읽기 전에 표시되는 안내는 해당 읽기를 차단하면 셸 명령이 권한을 요청하게 되는 경우를 설명합니다. 비대화형 세션은 매우 큰 대화 기록을 압축할 때 메모리를 덜 사용합니다. Ubuntu에서는 /sandbox와 시작 경고에 사용자 네임스페이스에 대한 AppArmor 제한과 해제 방법이 표시됩니다. mod의 Image는 allow-passthrough와 focus-events가 켜진 tmux 내부에서 렌더링되며, kitty, Ghostty, iTerm2 3.5+에서는 전체 화면 렌더링으로 표시됩니다. 또한 비대화형 세션에서 서버의 추가 입력 요청에 응답하지 않은 채 MCP 도구 호출이 시간 초과되면, Claude에 해당 호출을 반복하지 말라고 알립니다. Enterprise 사용자 지정 역할에 클라우드 세션 및 Remote Control 권한이 추가됩니다.²⁷⁸

v2.1.307의 새로운 기능

Claude Code 2.1.307은 2026년 10월 21일에 출시되었습니다(npm 20:47 UTC, GitHub 릴리스 22:17 UTC, 공식 CHANGELOG와 동일한 43개 항목). 앞서 출시된 2.1.306(10월 21일 02:28 UTC)에는 2가지 수정 사항이 있습니다. 클라우드 세션 안에서 claude -p를 실행할 때 세션 환경 변수가 없어도 더 이상 “Not logged in” 오류가 발생하지 않으며, MCP 도구가 많은 세션에서 API 오류가 “prompt is too long” 오류로 바뀌면서 불필요한 압축이 실행되던 문제가 해결되었습니다. 2.1.308(10월 22일 04:19 UTC)은 변경 내역이 한 줄인 안정성 개선 릴리스이며, stable로 지정되었습니다.²⁷⁸

텔레메트리와 API skill. 권한 규칙, 자동 모드, 안전 검사, hook 또는 샌드박스가 도구 호출을 중단하거나, 확인을 요청하거나, 되돌려 보낼 때마다 claude_code.safety_event OpenTelemetry 이벤트가 발생합니다(환경 변수 참조 참고). /claude-api api-version은 Claude API 코드를 API 버전 2026-10-21로 전환합니다. /claude-api managed-agents-secure(v2.1.304)는 아무것도 변경하지 않고 Managed Agents 에이전트의 설정을 Anthropic에서 공개한 보안 가이드와 비교합니다. 이제 이 skill은 multiagent_20261001을 기반으로 Managed Agents subagent 팀을 구성하며, 동적 워크플로를 기본으로 활성화합니다(v2.1.309).²⁷⁸²⁷⁹

수정 사항과 동작. opus[1m]처럼 [1m] 접미사가 붙은 별칭과 함께 CLAUDE_CODE_DISABLE_1M_CONTEXT를 사용해도 더 이상 모델을 찾을 수 없다는 오류가 발생하지 않습니다. 사용자 지정 ANTHROPIC_BASE_URL 게이트웨이를 통하거나 Foundry를 사용할 때는 prompt-caching-scope 베타 헤더를 더 이상 전송하지 않습니다. macOS 로그인 키체인이 잠겨 있어 연결할 수 없었던 MCP 서버는 이제 그 이유를 알려주며, 잠금을 해제한 후 다음 실행에서는 다시 로그인하지 않아도 연결됩니다. HTTP MCP 도구 호출 도중 연결이 끊어져도 호출을 중복 전송하지 않습니다. 읽기 전용 또는 멱등성을 갖춘 도구만 재시도합니다. PDF 페이지나 이미지를 많이 읽는 턴에서 발생하던 “Autocompact is thrashing” 오류가 수정되었습니다. 파싱할 수 없는 도구 호출은 최대 2번 재시도한 후 오류와 함께 턴을 종료합니다. 함께 실행된 fork subagents에는 각자 어느 실행에 해당하는지 알려줍니다. /permissions > 최근 거부됨에는 거부된 셸 명령이 표시됩니다. axScreenReader 설정과 설정의 env 블록에 있는 CLAUDE_AX_SCREEN_READER는 사용자 설정, 관리형 설정 또는 --settings로 지정한 설정에서만 적용됩니다(2.1.305부터). 자체 호스팅 runner의 체크아웃 hooks는 기본적으로 30분 후 중단됩니다(--checkout-hook-timeout-min, 제한을 없애려면 0). Code Review에는 @claude review always 구독을 종료하는 @claude review stop이 추가되었습니다(off와 pause도 사용 가능).²⁷⁸

v2.1.304 및 v2.1.305의 새로운 기능

Claude Code 2.1.304는 2026년 10월 19일에 출시되었으며(npm 19:47 UTC, GitHub 릴리스 21:34 UTC, 76개 항목), 2.1.305는 10월 20일에 출시되었습니다(npm 19:29 UTC, GitHub 릴리스 20:46 UTC, 38개 항목). 두 릴리스의 변경 내역은 모두 공식 CHANGELOG와 동일합니다. 2.1.303(10월 18일)은 변경 내역이 한 줄인 안정성 개선 릴리스입니다.²⁷⁸

자동 모드 설정과 /usage 수정 사항. /auto-mode-setup(v2.1.304)은 프로젝트와 최근 세션을 읽어 autoMode.environment 항목의 초안을 작성하는 설정 안내 기능입니다. Bedrock, Vertex, Foundry, Claude 앱 게이트웨이, 텔레메트리가 비활성화된 세션에서도 사용할 수 있으며, 자동 모드 설정 문서에서 다룹니다. /usage(v2.1.305)는 각 경고에 대해 발생 원인을 명시한 한 줄짜리 해결 방법을 제시하며, f를 누르면 해결 방법이 적용됩니다. 이 안내는 VS Code와 /doctor에도 표시됩니다. /usage는 사용량 데이터 조회에 대한 요청 제한이 언제 해제되는지도 알려줍니다. Pro와 Max에서는 비활성 대화를 재개할 때 5시간 사용량 한도의 상당 부분을 사용하게 된다면, 새 대화를 시작하는 선택지와 함께 경고를 표시합니다(v2.1.304). Max의 자동 모드와 슬래시 명령의 /usage 행을 참고하세요.²⁷⁸²⁷⁹

설정과 환경. sandbox.allowNestedUserNamespaces(v2.1.305)를 사용하면 Linux에서 샌드박스 내부의 명령이 사용자 네임스페이스를 생성할 수 있습니다(Chromium, rootless podman). 다만 해당 명령이 샌드박스의 파일 보호를 우회할 수도 있습니다. CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS(v2.1.305)를 사용하면 무인 재시도 모드가 예정된 초기화 시점 전에 해제된 사용량 제한을 감지할 수 있습니다. CLAUDE_CODE_AUTO_COMPACT_WINDOW는 --autocompact처럼 k와 M 접미사를 허용하며, 범위를 벗어난 값에는 경고를 표시합니다(이전에는 200k를 지정하면 경고 없이 100K 윈도우가 설정되었습니다). allowedMcpServers는 ${VAR}를 env에서만 사용하는 managed-mcp.json의 stdio 서버를 더 이상 필터링하지 않습니다. 따라서 허용 목록에서 제외했던 서버가 업그레이드 후 로드될 수 있습니다(계속 비활성화하려면 deniedMcpServers를 사용하세요). 사용자 지정 ANTHROPIC_BASE_URL을 통해 연결할 때 도구 검색이 기본으로 활성화됩니다(v2.1.304). 또한 v2.1.305에서는 엔드포인트가 도구 검색을 거부하는 Vertex, Bedrock 및 기타 제공자에서 모든 요청이 실패하던 2.1.304의 회귀 문제가 수정되었습니다. 이제 Claude Code는 도구 검색을 제외하고 재시도합니다. Claude Desktop이 경로로 마운트하는 plugins의 allowed-tools는 allowManagedPermissionRulesOnly가 적용되면 제거됩니다. 도구 검색의 기본 활성화를 제외한 모든 내용은 10월 23일 기준으로 문서에 반영되어 있습니다.²⁷⁸²⁷⁹

Mods, skills, hooks. mod의 tool.check 이벤트에는 e.isReadOnly가 포함됩니다. 응답에 decider: "person"을 설정하면 권한 대화 상자나 호스트 콜백을 통해서만 승인할 수 있습니다. settings.read hooks는 각 설정 계층을 전달받아 병합된 설정을 다시 작성합니다. 대화 기록에는 사용자의 hooks 중 하나를 건너뛴 plugin의 이름이 표시되며, 고정된 창의 너비는 터미널 너비의 45% 이내로 유지됩니다(v2.1.305). 압축 후에는 Claude에 skills 목록을 다시 전송하며, /reload-skills는 새로 추가되거나 변경된 skills만 전송합니다. 동일한 출처의 skills는 세션당 최대 1,024개의 hooks와 총 16,384자의 매처 문자열을 등록할 수 있습니다. 이제 한 skill의 once hook이 다른 skill의 동일한 hook을 제거하지 않습니다. 워크플로를 재개할 때는 완료된 pipeline() 및 parallel() 에이전트를 다시 실행하지 않고 실행 저널에서 결과를 가져옵니다(v2.1.305). 자체적으로 간격을 조절하는 /loop는 최대 간격인 1시간으로 대기하더라도 프롬프트 캐시가 만료된 직후에 깨어나지 않습니다. HEAD가 분리되어 있거나 다른 브랜치에 있는 경우, claude --worktree는 종료 시 확인 없이 worktree와 해당 브랜치를 제거하지 않습니다. 마운트된 드라이브나 그 최상위 폴더에 rm -r을 실행하면 안전 확인 메시지가 표시됩니다. Code Review에는 검토 수준(Quick, Standard, Deep)과 GitHub 조직의 모든 저장소를 검토하는 옵션이 추가됩니다. Opus 5.5에서는 /fast 대화 상자의 “(research preview)” 표시가 제거됩니다.²⁷⁸

v2.1.302의 새로운 기능

Claude Code 2.1.302는 2026년 10월 16일에 출시되었습니다. npm에는 16:48 UTC에 게시되었고, GitHub 릴리스는 공식 CHANGELOG와 동일한 63개 항목을 담아 20:53 UTC에 공개되었습니다. npm의 latest와 next는 모두 이 버전을 가리키며, stable은 2.1.292를 유지합니다. 이전 버전은 2.1.301(10월 15일, 51개 항목)이며, 건너뛴 버전은 없습니다. 10월 17일에 확인한 문서에는 2.1.301의 vim 모션과 VS Code 수식 렌더링이 반영되어 있지만 아래 항목은 아직 하나도 반영되지 않았으므로, 각 항목의 출처는 CHANGELOG입니다.²⁷⁵²⁷⁶

claude -p와 SDK가 다시 수동 모드로 시작합니다. 권한 모드를 지정하지 않은 claude -p 또는 Agent SDK 세션은 이제 타사 제공업체를 사용하거나, 텔레메트리를 끄거나, 새로 설치한 환경에서 default(수동)로 시작합니다. --permission-mode auto를 지정하면 자동 모드를 유지합니다. 이는 해당 세션이 자동 모드로 시작하도록 한 v2.1.285의 규칙을 되돌리는 변경입니다. 대화형 터미널과 VS Code 세션은 기존과 같이 모든 요금제와 제공업체에서 자동 모드를 사용합니다. 권한 모드 문서는 여전히 v2.1.285의 동작을 설명합니다. 권한 모드를 참고하세요.²⁷⁵²⁷⁶

Fork subagents와 백그라운드 실행 기본값. Fork subagents(subagent_type: "fork")는 기존 터미널에 이어 claude -p, Agent SDK, 데스크톱 앱, VS Code에서도 기본으로 활성화됩니다. CLAUDE_CODE_FORK_SUBAGENT=0으로 비활성화할 수 있으며, claude mcp serve에서는 제공되지 않습니다. 데스크톱 앱과 VS Code는 이제 Claude가 실행 방식을 선택하게 두지 않고, 터미널처럼 기본 대화의 subagents를 항상 백그라운드에서 실행합니다. 반면 claude -p, SDK, 데스크톱 앱, VS Code에서 subagent 자체가 수행하는 Agent 호출은 기본적으로 포그라운드에서 실행됩니다. 프롬프트 및 에이전트 hooks는 이제 동일한 이벤트에 대해 한 번에 최대 12개까지 실행되며, 나머지는 차례를 기다립니다. 환경 변수와 subagents 문서는 여전히 fork 모드가 대화형 세션에서만 활성화된다고 설명합니다. Subagents란 무엇입니까?를 참고하세요.²⁷⁵²⁷⁶

자동 모드와 압축. CLAUDE_CODE_AUTO_MODE_MODEL은 클라이언트 측 자동 모드 분류기가 사용할 모델을 지정하며, 서버 측 자동 모드의 모델은 변경하지 않습니다. 서버 측 분류기를 사용할 때 대화가 너무 길어 안전 검사를 수행할 수 없으면, 이제 검사 대상 도구 호출을 모두 거부하는 대신 대화를 압축합니다. /config에는 유휴 상태 압축을 끄거나 다시 켤 수 있는 유휴 상태 압축 항목이 추가되었으며, 유휴 상태 압축 후 표시되는 알림에도 비활성화 방법이 안내됩니다. 압축 도중 턴을 중지할 때 발생하던 “프롬프트가 너무 깁니다” 오류가 수정되었습니다. 또한 게이트웨이가 anthropic/claude-opus-4-1처럼 접두사를 붙여 Opus 4 또는 4.1을 식별하는 경우에도 /autocompact와 /effort가 올바른 모델에 설정을 저장합니다.²⁷⁵

Claude Design이 2026년 12월 14일까지 종료됩니다. /design-sync와 /design-login은 이제 독립형 Claude Design(claude.ai/design)이 해당 날짜까지 종료된다는 알림을 표시합니다. 또한 /design consent와 /design revoke는 클라우드 세션을 /design-login 대신 claude.ai/design/settings로 안내합니다. 슬래시 명령어의 /design 항목을 참고하세요.²⁷⁵

알아두면 유용한 수정 사항. Read 도구는 더 이상 크기와 관계없이 이미지 전체를 메모리에 로드하거나, 이미지처럼 이름이 지정된 파이프나 장치의 내용을 전부 메모리에 로드하지 않습니다. 128 MB를 초과하는 이미지 소스는 거부합니다. 세션 도중 추가한 도구를 ToolSearch를 통해 또는 압축 후 다시 로드해도 더 이상 프롬프트 캐시 미스가 발생하지 않습니다. claude plugin과 기타 하위 명령어는 대기 중인 설정 쓰기가 완료될 때까지 기다린 후 종료하므로, 변경 사항이 유실되거나 .tmp 파일로 남지 않습니다. git의 기본 참조 형식이 reftable인 경우에도 plugins 마켓플레이스가 새로고침할 때마다 다시 복제되지 않으며, git plugins의 버전이 “알 수 없음”으로 표시되지 않습니다. git 2.56 이상에서는 불필요하게 남은 .git 파일이 존재하지 않는 디렉터리를 가리키더라도 worktree 격리가 작동합니다. 프로토콜 버전 2026-07-28을 협상하면서 resultType, ttlMs 또는 cacheScope를 생략하는 MCP 서버도 이제 도구를 표시합니다. 사용량 크레딧이 청구된 응답 뒤에는 프롬프트 제안을 생략합니다. 세션 도중 Vertex 또는 Bedrock으로 전환한 후 요청이 “diagnostics: 추가 입력은 허용되지 않습니다” 오류로 실패하던 문제가 수정되었습니다. plugins가 많을 때 시작 속도가 빨라졌으며, 특히 Windows에서 개선 폭이 큽니다. Windows의 exFAT 또는 FAT32 드라이브에서 파일 쓰기가 거부되던 문제도 해결되었습니다.²⁷⁵

클라우드 세션과 Claude Tag. 루틴 페이지에는 조직의 동시 클라우드 세션 수 제한 등 마지막 실행이 시작되지 않은 이유를 설명하는 배너가 표시됩니다. “여기까지 되돌리기”는 모든 메시지에서 작동합니다(자체 호스팅 러너는 v2.1.246 이상이 필요합니다). 도중에 실패한 실행이 1시간 후 처음부터 반복되던 문제가 해결되었으며, 클라우드 세션이 새 프로세스에서 재개된 후 비용과 사용량이 0부터 다시 집계되던 문제도 수정되었습니다. Claude Tag 관리자 설정은 번들, 커넥터, skills 및 plugins, 채널 탭으로 재구성되었습니다. Slack에 첨부한 HEIC, SVG, TIFF, BMP 이미지는 이제 파일로 Claude에 전달됩니다. 조직에서 역할에 따라 사용을 제한하는 경우, 이제 관리자 역할에도 Slack의 Claude Tag 사용 권한이 부여됩니다.²⁷⁵

v2.1.301의 새로운 기능

Claude Code 2.1.301은 2026년 10월 15일에 출시되었습니다(npm 14:34 UTC, GitHub 릴리스 19:22 UTC). GitHub 릴리스에는 공식 CHANGELOG와 동일한 51개 항목이 포함되어 있습니다. npm의 latest가 다음 날 2.1.302로 변경되었으므로, 여기서는 두 릴리스를 함께 다룹니다.²⁷⁵

무인 재시도에 사용량 제한 대기 상한이 추가되었습니다. CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS를 사용하면 무인 재시도 모드(CLAUDE_CODE_RETRY_WATCHDOG)에서 사용량 한도 초기화까지 남은 시간이 너무 길 때 기다리지 않고 요청을 종료합니다. 이 변수는 환경 변수 참조의 CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS 옆에 설명되어 있습니다. 운영자를 위한 변경 사항도 있습니다. 컨텍스트 윈도우가 더 작은 모델로 전환할 때 대화가 새 모델에 담기에는 너무 길면, 이제 확인 없이 사용량 크레딧을 소모해 요약하는 대신 이전 모델이 대화를 요약합니다. 조직에서 최신 Fable 모델을 사용할 수 없는 경우 fable과 best 별칭은 이전 Fable 모델로 한 번 재시도합니다. 또한 LLM 게이트웨이가 응답에서 요청한 모델과 다른 모델 이름을 반환하더라도 대화가 반복해서 압축되지 않습니다.²⁷⁵

텔레메트리, vim, 모드. OpenTelemetry의 tool_decision 이벤트에 classifier_verdict와 permission_mode가 추가되어 자동 모드 분류기의 판단과 권한 규칙을 구분할 수 있습니다. OTEL_LOG_TOOL_DETAILS=1이면 분류기의 차단 판단에 일치한 내장 규칙 이름을 나타내는 classifier_category도 추가됩니다. Vim 모드에는 % 모션이 추가되었습니다. 단독으로 사용하거나 d, c, y와 함께 사용해 짝이 맞는 괄호로 이동할 수 있습니다(대화형 모드 문서에는 이미 기재되어 있습니다). 모드의 Input에는 터미널에서 여러 줄 텍스트 필드를 만들 수 있는 rows가 추가되었습니다. Enter로 제출하고 Shift+Enter 또는 역슬래시 뒤의 Enter로 줄을 바꿀 수 있습니다. 모드 hook의 .catch 핸들러는 이제 hook이 예외를 던지거나 시간이 초과된 경우에만 실행됩니다. $.env.set은 변수가 설정되거나 해제되면 {}로, 거부되면 이유를 담은 { deny }로 완료됩니다. $.model.fork는 새 프로세스의 첫 응답 전에 더 이상 nothing-to-fork를 반환하지 않습니다. 또한 VS Code와 데스크톱 및 모바일 앱에서는 질문 대화 상자 위에 그려지는 트리에 Markdown과 최대 48개 행을 담을 수 있습니다. 모드와 Vim 모드를 참고하세요.²⁷⁵²⁷⁶

알아두면 유용한 수정 사항. WorktreeCreate hook이 만든 worktree에 푸시하지 않은 커밋이 있을 수 있는 경우, 종료 시 확인 없이 해당 worktree를 삭제하지 않습니다. Grep과 Glob은 검색 프로그램이 실패하면 “일치하는 항목 없음” 대신 오류를 보고합니다. 인수 이름이 아주 많거나 긴 skills와 명령어가 몇 초 동안 멈추던 문제가 해결되었습니다. 이제 처음 64개 이름만 각각 최대 64자까지 자동 완성합니다. Read 도구는 더 이상 .xlsm, .parquet, .epub, .heic 같은 바이너리 파일을 텍스트로 읽지 않습니다. /rewind 후 모델에 skills 목록이 다시 제공됩니다. 권한 검사 중에 사용자가 턴 도중 보낸 메시지로 도구 호출이 중단되더라도, 이를 사용자가 거부했다고 모델에 보고하지 않습니다. Vim 모드에서 Esc를 눌러도 입력한 AskUserQuestion 답변이 사라지지 않습니다. 자유 입력 필드는 NORMAL 모드를 지원하며, Esc는 해당 모드에서만 입력을 취소합니다. 디스크가 가득 차면 오해를 유발하는 “/login을 실행하세요” 대신 해당 디스크를 명시하는 오류가 표시됩니다. 관리형 설정에서 MCP 서버를 제한하더라도 Slack에서 시작한 자체 호스팅 러너는 저장소를 연결할 수 있습니다(해당 도구를 비활성화하려면 deniedMcpServers를 사용하세요). VS Code는 $$와 \[ ... \] 블록을 포함한 응답 내 LaTeX 수식을 렌더링하며, Pro와 Max의 사용량 제한 배너에 “사용량 추가” 링크를 표시합니다.²⁷⁵

v2.1.300의 새로운 기능

Claude Code 2.1.300은 2.1.299가 나온 지 몇 시간 뒤인 2026년 10월 14일에 출시되었습니다. npm에는 14:27 UTC에 next로 게시되었고, GitHub 릴리스는 공식 CHANGELOG와 동일한 88개 항목을 담아 18:24 UTC에 공개되었습니다. 저녁 무렵에는 npm의 latest와 next가 모두 2.1.300을 가리켰으며, stable은 2.1.287에서 2.1.292로 변경되었습니다. 건너뛴 버전은 없습니다.²⁷³ advisor 도구가 AWS의 Claude Platform에서도 지원됩니다. 이제 AWS의 Claude Platform에서 /advisor를 사용할 수 있습니다. /advisor, advisorModel 또는 --advisor로 advisor를 선택하기 전에는 실행되지 않으며, CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1로 도구를 끌 수 있습니다. 10월 14일 기준으로 advisor 문서 페이지에는 여전히 AWS의 Claude Platform이 지원되지 않는 제공업체로 나열되어 있습니다. Claude가 의사 결정 시점에 두 번째 모델에 자문을 구할 수 있게 해 주는 이 도구는 이번 릴리스 이전부터 제공되었으며, Advisor 도구에서 설명합니다.²⁷³²⁷⁴

Mods와 텔레메트리. Mods에 virtualText 프롬프트 장식(프롬프트 입력란에 표시되지만 초안에는 포함되지 않는 텍스트), 에이전트의 대화 기록을 기본 화면에 표시하는 $.ui.view({ agentId })($.ui.view({})로 돌아갑니다), 오른쪽에서 왼쪽으로 표시되는 행을 위한 Text의 dir 속성, 직접 입력한 편집 이외의 프롬프트 입력란 변경(이전 입력 불러오기, 지우기, 실행 취소, plugin의 내용 채우기)을 감지하는 prompt.change hook이 추가되었습니다. 이제 agent.spawn은 워크플로 에이전트를 거부하는 것뿐 아니라 해당 에이전트의 prompt와 model을 다시 작성할 수도 있으며, mods 참조 문서에는 next.error.cause의 rewritten 원인이 v2.1.300에 도입된 것으로 명시되어 있습니다. OpenTelemetry의 api_request 이벤트는 캐시 쓰기를 cache_creation_5m_tokens와 cache_creation_1h_tokens로 나누어 기록하고, 추적 스팬에는 gen_ai.provider.name, gen_ai.conversation.id, gen_ai.tool.name, error.type 같은 GenAI 의미 규약 속성이 포함됩니다. 또한 mod의 prompt.submit hook이 다시 작성하거나 삭제한 프롬프트는 더 이상 user_prompt 이벤트에 사용자가 입력한 내용으로 기록되지 않습니다. 이제 로컬 대화 기록에는 각 API 요청의 시스템 프롬프트, 도구, 매개변수도 기록되므로, 공유한 대화 기록으로 요청을 정확히 재현할 수 있습니다(Mods 및 텔레메트리 참조).²⁷³²⁷⁴

운영 및 동작 변경 사항. api.anthropic.com으로 보내는 대용량 요청은 텔레메트리가 꺼져 있어도 gzip을 사용합니다. CLAUDE_CODE_GZIP_REQUEST_BODIES=0으로 끌 수 있습니다. PreToolUse 및 PermissionRequest hooks의 updatedInput은 Claude 자체 입력과 같은 방식으로 검증됩니다. 알 수 없는 키는 제거되며, 도구가 입력을 거부하면 호출도 거부됩니다. 종료 시 중지 요청 후 1.5초가 지나도 실행 중인 백그라운드 명령은 강제 종료됩니다. claude remote-control에서 아무 효과가 없었던 --sandbox 및 --no-sandbox 플래그가 제거됩니다. 둘 중 하나를 전달하면 오류와 함께 종료되며, 이러한 세션에 샌드박스를 적용하려면 설정의 sandbox.enabled를 사용해야 합니다. CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST가 적용된 세션은 설정에 지정된 SSL_CERT_FILE 등의 CA 번들, 도구 프록시, git TLS, git 설정 변수를 무시합니다. Cowork 클라우드 세션에서는 PermissionRequest hook의 setMode가 무시되지만 나머지 승인 내용은 적용됩니다. Claude Desktop의 Code 탭은 forceLoginGatewayUrl이 세션의 호스트 이름을 제공하는 Anthropic 운영 게이트웨이를 가리킬 때 관리형 설정을 적용하며, claude gateway는 사용할 수 없는 desktop: 정책 키가 있으면 시작 단계에서 중단됩니다. /sandbox 옵션의 문구는 “명령에 샌드박스 적용”으로 바뀝니다. VS Code에는 편집기에서 선택한 내용을 메시지에 포함하지 않도록 하는 claudeCode.attachSelection이 추가됩니다. Slack에서는 관리자가 허용하면 Claude Tag가 Slack Connect 채널에서 답변할 수 있습니다.²⁷³

알아 두면 유용한 수정 사항. 백그라운드 명령이 실행 중인 상태에서 종료해도 SessionEnd hooks가 실행됩니다. ENABLE_TOOL_SEARCH=auto가 대화 도중 꺼지는 문제가 해결되었습니다. forceLoginOrgUUID가 로그인을 거부한 경우 해당 조직의 토큰이 저장된 채로 남지 않습니다. 압축 후 재개한 헤드리스 및 SDK 세션은 압축 시 보존한 메시지와 요약을 유지합니다. API가 MCP 도구의 입력 스키마를 거부해도 매 턴마다 400 오류로 대화가 실패하지 않습니다. 대신 해당 도구가 매개변수 없이 전송됩니다. 에이전트 hooks는 지정된 model을 따릅니다. 태그나 브랜치 이름이 커밋 ID와 같아도 --worktree 세션은 올바른 커밋에서 시작하며, reftable 저장소에서도 다시 열립니다. claude daemon stop --any는 서비스가 종료되기를 기다리고, 멈춘 서비스를 강제 종료하며, 그래도 서비스가 남아 있으면 종료 코드 1을 반환합니다. Cowork 클라우드 세션의 Write와 Edit는 더 이상 사용자 컴퓨터의 경로에 대해 성공했다고 보고하지 않습니다. 조직 정책을 읽을 수 없을 때 클라우드 세션이 매 턴마다 5분씩 멈추는 문제가 해결되었습니다. 자체 호스팅 실행기는 출력을 읽는 대상이 없어도 더 이상 멈추지 않습니다.²⁷³

v2.1.299의 새로운 기능

Claude Code 2.1.299는 2026년 10월 14일에 출시되었습니다(npm은 UTC 00:23, GitHub 릴리스는 UTC 02:49이며 공식 CHANGELOG와 동일한 190개 항목이 포함되어 있습니다). 2.1.297과 2.1.298은 배포되지 않았으므로 빠진 버전은 없습니다. npm의 latest는 같은 날 나중에 2.1.300으로 변경되기 전까지 2.1.299였습니다(v2.1.300의 새로운 기능 참조).²⁷¹²⁷³ 2.1.296을 사용 중이라면 업그레이드하세요. 이번 릴리스는 해당 버전에서 발생한 두 가지 회귀 버그를 수정합니다. 하나는 Cowork 및 claude.ai 클라우드 세션에서 UserPromptSubmit 또는 mod의 prompt.submit hooks가 실행되는 동안 메시지를 중지하면 Edit와 Retry가 실패하는 문제입니다. 다른 하나는 클라우드 또는 헤드리스 세션이 재시작 후 재개되는 순간 새 메시지가 도착하면 승인된 도구 호출이 두 번 실행되는 문제입니다.

유휴 상태 압축(v2.1.299). 토큰이 200K 이상인 터미널 대화를 약 54분 동안 사용하지 않으면, 이제 1시간짜리 프롬프트 캐시가 만료되기 전에 대화가 압축되어 다음 메시지에서 전체 컨텍스트를 다시 처리하지 않습니다. CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS로 최소 기준인 200K를 변경할 수 있으며(100,000보다 작은 값은 100,000으로 올림), settings.json에서 "idleCompaction": false로 끌 수 있습니다. 설정 참조 문서와 환경 변수 페이지에는 두 항목 모두 v2.1.290 이상에서 제공되는 것으로 명시되어 있습니다. CLAUDE_CODE_DISABLE_FILE_MENTIONS=1을 설정하면 @ 멘션이 파일 내용 대신 경로를 Claude에 전달하고 Claude가 파일 도구로 읽게 되므로, 읽기 작업 시 PreToolUse hooks가 실행됩니다. 이 값은 프로젝트 설정과 로컬 설정에서는 지정할 수 없습니다(환경 변수 참조 참조).²⁷¹²⁷² v2.1.302에서는 /config에 유휴 상태 압축 항목이 추가되어 기능을 끄거나 다시 켤 수 있으며, 유휴 상태 압축 후 표시되는 알림에서도 그 방법을 안내합니다.²⁷⁵

권한과 MCP. 이제 mcp__a 같은 허용 규칙은 이름이 a인 서버에만 적용되며, a__b나 a_에는 적용되지 않습니다. 서버의 정규화된 전체 이름을 사용해 mcp__<server>__*로 작성하세요. 이름에 __가 포함된 서버도 에이전트의 tools: 목록에 같은 방식으로 지정하면 이제 해당 서버의 도구만 추가됩니다. 정규화된 이름에 이중 밑줄이 포함된 서버에도 거부 및 확인 요청 규칙이 다시 적용됩니다. api.anthropic.com에 있는 Anthropic의 자사 MCP 서버가 제공하는 도구 설명과 서버 지침은 4,096자에서 잘리지 않고 Claude에 전체 내용이 전달됩니다. 플래그를 가져오지 않는 설치 환경에서 클라우드 세션과 Remote Control 커넥터는 기본적으로 MCP 프로토콜 2026-07-28을 협상합니다(MCP_PROTOCOL_NEGOTIATION=legacy로 기존 방식 사용). claude.ai의 커넥터 프록시와 Anthropic가 호스팅하는 MCP 서버로 보내는 요청은 더 이상 HTTP 리디렉션을 따르지 않습니다. MCP OAuth는 이제 설정된 headers 및 headersHelper 값을 전송하고, 빈 .mcp.json을 잘못된 파일로 보고하지 않으며, 이름이 constructor 또는 prototype인 서버도 연결됩니다. 샌드박스가 적용된 명령은 더 이상 --plugin-dir 폴더에 쓰거나 심볼릭 링크를 통해 접근이 거부된 경로에 도달할 수 없습니다. rm을 실행하지 않는 셸 -c 스크립트에서는 더 이상 rm 확인 메시지가 표시되지 않으며, Claude Code가 읽을 수 없는 스크립트 안에서 실행 시점에 구성되는 rm 명령은 CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1인 경우에만 확인 메시지를 표시합니다.²⁷¹

Hooks와 mods. UserPromptSubmit hooks는 skill이나 사용자 지정 슬래시 명령이 확장되기 전에 실행되므로, hook이 프롬프트를 차단하면 그 안에 포함된 셸 명령도 중단됩니다. skill 자체의 프런트매터에 정의된 UserPromptSubmit hook은 해당 skill을 호출한 프롬프트의 다음 프롬프트부터 실행됩니다. 작업을 전달받지 못하거나 응답을 돌려줄 수 없는 plugin hook은 이제 작업을 통과시키지 않고 거부합니다. 도구가 이미 실행되었다면 결과 전달을 보류합니다. Mods의 turn.start hook은 이제 subagents와 팀원의 턴도 감지하며(e.agentId로 구분), skill.prompt는 skill의 프런트매터, 소스, plugin 이름, 파일 경로를 전달받습니다(mods 참조 문서에는 이러한 항목이 v2.1.299에 도입된 것으로 명시되어 있습니다). $.prompt.media를 통해 관리형 설정 mod의 prompt.submit hook이 첨부된 이미지나 문서를 읽을 수 있고, $.session.identity()는 세션의 로그인 방식을 알려 줍니다. Text는 size, weight, mono, tabular를 지원하고 Box는 이름이 지정된 간격 단계를 지원합니다(bold는 사용 중단 예정이며 weight로 대체됩니다). session.append에는 queue 진입점이 추가되고, subagent나 팀원이 재개되면 resume이 설정된 상태로 agent.spawn이 실행됩니다. 원격으로 꺼진 mods는 턴 사이에 언로드되며, 조직이 Claude Code를 관리하는 환경에서는 /plugin과 claude plugin validate가 건너뛴 hooks의 이름을 표시합니다(Mods 참조).²⁷¹²⁷² 명령어, 인터페이스, 운영. /usage는 최대 추론 강도, 워크플로, 상시 포함되는 컨텍스트, 대용량 도구 결과에 관해 경고합니다. 에이전트 보기에서 /effort와 /fast는 새 세션의 시작 설정을 지정하며, 인자 없이 /model, /effort, /fast를 실행하면 선택기가 열립니다. 미리 보기 패널에는 --safe-mode로 시작한 세션의 안전 모드 표시줄이 나타납니다. Plan 모드에서는 권한 검사 우회가 가능해 대부분의 편집 전에 확인을 요청하지 않을 경우, 이를 알리는 안내를 한 번 표시합니다. claude plugin eval은 --disallow-tools와 테스트 케이스의 disallowed_tools 필드를 지원하며, API 오류로 종료된 실행은 0점으로 처리되고 테스트 모음 전체가 실패합니다. claude self-hosted-runner orchestrator --shutdown-drain-sec는 SIGTERM 수신 시 진행 중인 폴링과 생성 hooks가 완료될 시간을 제공합니다. Claude 앱 게이트웨이를 사용하는 환경에서는 code 또는 cli 정책의 env에 CLAUDE_CODE_ATTRIBUTION_HEADER=0을 설정하면 출처 표시 블록이 제거됩니다. Cowork 클라우드 세션에서는 자동 모드의 PermissionRequest hook이 더 이상 셸 명령이나 subagents를 승인할 수 없습니다. 또한 승인된 사이트에서 안전 분류기가 문제로 표시한 Claude in Chrome 작업은 바로 거부되지 않고 사용자에게 확인을 요청합니다. 종료 시 출력되는 재개 명령은 ID로 세션을 지정합니다. 비대화형 세션의 /btw는 11분 후 시간 초과됩니다. 로컬 세션에서 모니터링할 수 있는 게시된 아티팩트 수는 10개에서 25개로 늘어났으며, 사이버 안전장치 안내는 더 이상 Cyber Verification Program에 신청하라고 요청하지 않습니다.²⁷¹

알아둘 만한 수정 사항. 사용자 지정 ANTHROPIC_BASE_URL을 통한 스트리밍은 180초에 중단되는 대신 데이터를 300초 동안 기다립니다. Anthropic로 보내는 기능 플래그, 시작, 빠른 모드, 프로필, 서버 관리 설정 요청에는 더 이상 타사 게이트웨이의 API 키가 포함되지 않습니다. /usage와 상태 표시줄에는 더 이상 사용량이 100%를 초과해 표시되지 않습니다. 일광 절약 시간제 종료로 같은 시간대가 반복될 때 예약 작업과 루프가 매 턴마다 다시 실행되는 문제가 수정되었습니다. --debug를 사용하거나 상위 프로세스가 stderr 읽기를 중단했을 때 메모리가 무제한으로 증가하던 문제도 수정되었습니다. SendMessage는 재시작 후에도 이름으로 subagent를 찾습니다. Read는 바이트 순서 표시가 있는 UTF-16LE 파일을 처리하며, Write는 Windows-1252, Shift-JIS, GBK, UTF-16BE 파일을 알림 없이 UTF-8로 변환하지 않습니다. Windows에서는 셸을 지정하지 않은 PreToolUse 및 PermissionRequest hooks가 Git for Windows를 찾지 못하면 호출을 허용하는 대신 차단합니다.²⁷¹

v2.1.293-v2.1.296의 새로운 기능

2026년 10월 7일부터 10월 9일까지 4개 버전이 출시되었습니다. npm의 latest와 next는 2.1.296이며, stable은 2.1.285에서 2.1.287로 변경되었습니다.²³⁸ 가장 큰 변화는 새 모델입니다. v2.1.293에 Claude Haiku 5.5가 추가되어 Anthropic API에서 haiku를 선택하면 이 모델이 사용됩니다(사용 가능한 모델 참조). 관리 설정을 통해 Claude 앱 게이트웨이에 로그인한다면 v2.1.296으로 업그레이드하세요. 이 버전은 forceLoginMethod가 gateway이고 forceLoginGatewayUrl이 없을 때 저장된 게이트웨이 로그인을 무시하던 v2.1.295의 회귀 오류를 수정합니다.

v2.1.296(10월 9일). /cost, 상태 표시줄, --max-budget-usd, SDK의 비용 수치에서 Sonnet 5.5 캐시 읽기 요금이 기존의 100만 토큰당 $0.20에서 $0.10으로 수정되었습니다. 처음에 전송하는 MCP 도구 설명과 MCP 서버 지침의 기본 길이 제한은 2,048자에서 4,096자로 늘어났습니다. Subagent frontmatter와 --agents 정의는 autoCompactWindow를 지원하므로, subagent가 주 대화보다 먼저 자동 압축을 수행할 수 있습니다. CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL은 모든 워크플로 에이전트를 하나의 모델로 실행하며, 다른 subagents는 기존 모델을 유지합니다. CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS로는 529 오류의 백오프 최대 대기 시간을 더 길게 설정할 수 있습니다. Read 도구는 allow_large를 지원하므로, 컨텍스트에 여유가 있으면 Claude가 일반적인 크기 제한을 넘는 텍스트 파일을 한 번의 호출로 읽을 수 있습니다. 관리 설정의 PreToolUse hooks가 "continue": false로 도구 호출을 거부하거나 관리형 prompt hooks가 호출을 차단하면, 이제 호출을 거부하는 동시에 턴도 종료합니다. --debug는 사용자 지정 에이전트 파일에서 인식하지 못한 frontmatter 필드의 이름을 표시하고, 각 명령 hook의 명령, plugin, 결과, 실행 시간을 기록합니다. Claude 앱 게이트웨이의 managed.policies[]에 code 키가 추가되었습니다. 이 키는 cli와 동일한 설정을 제공하며 Claude Desktop의 Code 탭에도 적용됩니다. ←로 세션을 백그라운드로 이동하는 동안 시작된 턴이나 ! 명령은 이제 보이지 않는 곳에서 완료되는 대신 중지됩니다. 이후 문서에도 이 중 2가지가 반영되었습니다. hooks 참조 문서는 hook별 --debug 로그가 v2.1.296부터 제공된다고 명시하며, Claude 앱 게이트웨이 문서는 code 정책 키를 설명합니다. autoCompactWindow와 CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS는 10월 14일까지 각각 subagents 문서와 환경 변수 문서에 반영되었습니다. CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL은 2026년 10월 14일 기준으로 릴리스 노트에만 기재되어 있습니다.^238240270272

v2.1.295(10월 8일). 명령 hooks와 HTTP hooks는 onFailure: "block"을 지원합니다. hook을 시작할 수 없거나, 시간이 초과되거나, 예상하지 못한 코드로 종료되면 작업을 허용하는 대신 차단합니다(Hook 입력/출력 프로토콜 참조). CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS는 무인 재시도 모드에서 429 및 529 오류가 해소되기를 기다리는 최대 시간을 제한합니다. Subagents는 skills 필드에서 최대 32개의 skills를 미리 로드하며, 도구 검색으로 로드한 MCP 도구 설명은 2,048자가 아닌 16,384자에서 잘립니다. 관리 설정이 없는 컴퓨터에서도 개인 사용자 설정의 forceLoginMethod: "gateway"와 forceLoginGatewayUrl이 작동하므로, /login을 실행하면 해당 게이트웨이가 열립니다. 게이트웨이 문서에도 이 설정 방법이 반영되었습니다. 모든 게이트웨이 업스트림은 *를 와일드카드로 사용하는 선택적 models 목록을 지원하며, 클라우드 업스트림은 timeouts.upstream_ttfb_ms를 적용합니다. Program Status Protocol(OSC 7501)을 구현한 터미널은 Claude Code가 작업 중인지, 사용자 응답을 기다리는지, 작업을 마쳤는지 표시할 수 있습니다. Claude 앱 게이트웨이를 통한 백그라운드 요청은 게이트웨이에서 Haiku 4.5를 제공하는 경우 세션 모델 대신 해당 모델을 사용합니다. 게이트웨이, Bedrock, Vertex, Foundry가 [1m] 모델의 context-1m 베타를 거부하면, 요청이 실패하는 대신 해당 베타 옵션 없이 다시 전송됩니다. 연결된 백그라운드 세션의 유휴 프롬프트에서 Ctrl+C를 눌러도 대기 중인 /loop 재실행 예약은 유지됩니다. 따라서 2번 누르면 연결이 해제되고 루프는 계속 실행됩니다. Esc를 누르면 루프가 중지됩니다. 플래그를 가져오지 않는 설치 환경에서 claude.ai 커넥터는 기본적으로 MCP 프로토콜 2026-07-28로 협상합니다. /copy는 인용된 텍스트를 선택지로 제공하고, claude -p는 마지막 턴 이후 무엇을 기다리는지 stderr에 표시하며, mods에는 $.ui.notify가 추가되었습니다. xhigh 및 max 추론 강도에서 웹 검색과 agent hook 평가가 지나치게 오래 걸리던 문제도 수정되었습니다.²³⁸²⁴⁰

v2.1.294(10월 8일). 지침 형태로 작성된 prompt 및 agent hooks의 문제 2가지가 수정되었습니다. “다음과 같은 명령을 차단하세요…”와 같은 hook이 차단해야 할 작업을 허용하던 문제가 수정되었습니다. 또한 “빌드가 실패한 상태라면 계속 진행하세요”와 같은 Stop 및 SubagentStop hooks의 판정 방식이 개선되어 Claude가 너무 일찍 중단할 가능성이 줄었습니다.²³⁸

v2.1.293(10월 7일). Claude Haiku 5.5(claude-haiku-5-5)가 Anthropic API의 기본 Haiku 모델이 되었습니다. 컨텍스트는 1M이며, 요금은 100만 토큰당 $0.10/$0.50, 100K를 초과하는 프롬프트는 $0.50/$2.50입니다. subagentStatusLine 페이로드에 agentType이 추가되어 상태 표시줄 스크립트가 사용자 지정 subagent 유형을 구분할 수 있습니다. mods의 $.tool.register에는 isDeferred가 추가되었습니다. 변경 사항 2개가 되돌려졌습니다. 하나는 거부가 정확히 일치하는 명령뿐 아니라 그 결과에도 적용된다고 Claude에 알리던 v2.1.281의 자동 모드 거부 메시지입니다. 다른 하나는 컨테이너 재시작 후 /loop 재실행 예약이 사라지던 문제를 해결한 v2.1.290의 클라우드 세션 수정 사항으로, 이 변경이 되돌려지면서 해당 세션은 다시 대기 상태에 머무르게 됩니다. 이 밖에도 Claude가 압축 직전의 마지막 작업을 압축 후에 완료된 것으로 간주하던 문제가 수정되었습니다. HTTP MCP 연결은 더 이상 종료될 때까지 전송한 모든 요청을 보관하지 않습니다. claude purge는 아무 안내 없이 중단되는 대신 제거하지 못한 항목을 나열하고 종료 코드 1로 종료합니다. 사용 중인 세션이 없을 때 claude.ai skills 동기화 확인 간격은 10분에서 40분으로 늘어났습니다. Team과 Enterprise는 시작 시 정책과 관리 설정을 더 일찍 가져오며, 요청이 멈추면 3초 후 재시도합니다.²³⁸²⁴⁰

v2.1.288-v2.1.292의 새로운 기능

2026년 10월 2일부터 10월 6일까지 5개 버전이 출시되었습니다. npm의 latest와 next는 2.1.292이며, stable은 2.1.285로 유지됩니다.²³⁴ 2.1.288, 2.1.289, 2.1.290을 사용 중이라면 업그레이드하세요. v2.1.291은 종료 시 세션의 마지막 메시지가 유실될 수 있었던 2.1.288의 회귀 오류와 클라우드 세션에서 권한 확인 요청에 대한 응답이 유실될 수 있었던 2.1.290의 회귀 오류를 수정합니다.²³⁵ v2.1.292 (10월 6일). CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS를 설정하면 과부하(529) 요청을 재시도할 때 백오프의 기본 대기 시간을 늘릴 수 있습니다. 환경 변수 문서에는 이제 기본값인 500ms와 허용 범위인 500~32000이 명시되어 있습니다. Agent 도구는 effort 매개변수를 지원하므로 Claude가 요청한 추론 노력 수준으로 subagent를 실행할 수 있습니다. subagents 문서에는 이제 호출별 매개변수가 설명되어 있습니다. 이 매개변수는 프런트매터 필드보다 우선하며 subagent를 재개해도 유지되고, CLAUDE_CODE_EFFORT_LEVEL은 이 둘보다 우선합니다. claude plugin install --marketplace <source>는 셸 명령 하나로 마켓플레이스를 추가하고 해당 마켓플레이스에서 설치합니다. 이제 Bedrock, Vertex, Foundry를 포함한 모든 설치 환경에서 로컬(stdio) MCP 서버는 기본적으로 프로토콜 2026-07-28을 협상하며, MCP_PROTOCOL_NEGOTIATION=legacy로 이 동작을 해제할 수 있습니다. MCP 문서에도 이제 stdio 서버에 기본적으로 해당 버전을 요청한다고 명시되어 있습니다. 에이전트 이름은 256자로 제한됩니다. 이보다 긴 이름은 거부되고, skill 또는 plugin 파일에서 더 긴 name은 무시됩니다. subagents 문서에는 이제 name 필드의 길이 제한과 함께, 이름이 제한을 초과하는 subagent 파일은 건너뛰고 디버그 로그에 오류를 기록한다고 명시되어 있습니다. 보안 수정으로 PreToolUse hook 승인과 자동 모드가 네트워크(UNC) 경로의 파일 읽기 승인 요청을 우회하지 못하도록 했습니다. Mods에는 prompt.autocomplete, $.model.complete의 프롬프트 캐싱, agent.spawn의 워크플로 에이전트가 추가되었으며, 이제 claude plugin test는 스텁 응답이 거부 응답이면 실패합니다. 나머지 항목은 2026년 10월 6일 기준으로 릴리스 노트에만 기재되어 있었습니다.^236237240

v2.1.290 (10월 5일). 대화형 WebSearch의 호출 한도는 200회 사용 후 소진되는 대신 시간당 100회씩 보충됩니다(CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR; 0으로 설정하면 보충이 비활성화됩니다). claude attach와 claude logs는 세션 이름의 일부만 입력해도 됩니다. /claude-api managed-agents-onboard <url>은 Managed Agents 패턴을 설명하는 페이지를 ant apply 파일로 변환하며, /claude-api managed-agents-onboard <quickstart-name>은 ant CLI를 사용해 deep-researcher 같은 Console 빠른 시작 템플릿을 구성합니다. 여러 기본 동작의 제한이 강화되었습니다. 프로젝트 설정으로는 더 이상 Chrome에서 Claude를 활성화할 수 없고, 저장소의 .claude/settings.json 또는 .claude/settings.local.json에서는 CLAUDE_CODE_DISABLE_ATTACHMENTS를 설정할 수 없습니다. pyright와 더 많은 형태의 ps 명령은 실행 전에 승인을 요청하며, 관리형 설정 파일이 관리형 설정 폴더 외부로 연결되면 경고가 표시됩니다. WebFetch는 이전에는 100,000자를 초과하는 페이지 내용을 알림 없이 버렸지만, 이제 읽지 못한 분량을 알려 주며 offset으로 이어서 읽을 수 있습니다. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC는 시작 시 연결을 미리 준비하는 단계도 건너뛰며, CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS=5m은 더 이상 5ms로 해석되지 않습니다. 단위 접미사가 있는 값은 dialogExpiry 설정으로 대체됩니다.²³⁵²³⁷

v2.1.290, 팀과 게이트웨이. Claude 앱 게이트웨이의 로그인 승인 페이지에 거부 버튼이 추가되었으며, 지원하는 PostgreSQL 최소 버전이 14에서 11로 낮아졌습니다. 자체 호스팅 러너에서 claude --environment <id>는 현재 Sessions API를 통해 세션을 생성합니다. claude --teleport와 /teleport는 추적 중인 파일을 같은 이름의 폴더로 대체한 경우, 그 폴더 안의 파일을 삭제하게 되는 스태시를 거부합니다. --channels 릴레이는 중복된 응답 ID가 들어오면 다른 승인 요청을 승인하는 대신 해당 응답을 무시합니다. Slack에서는 !fast로 스레드를 빠른 모드로 전환하고 !fast off로 되돌립니다. VS Code는 기본적으로 메시지 타임스탬프를 표시합니다(Claude Code: 메시지 타임스탬프 표시 설정으로 끌 수 있습니다).²³⁵

v2.1.289 (10월 3일). Mods에 팀원용 agent.spawn, plugin hook 이벤트 전반에서 유지되는 단일 에이전트 ID, $.agent.list()의 유휴 및 대기 상태가 추가되었습니다. claude plugin validate는 폴더에 마켓플레이스 매니페스트가 함께 있는 plugin도 더 이상 건너뛰지 않습니다. 샌드박스 자동 허용 시 발생하던 Bash 거부 규칙의 허점 2개도 해결되었습니다.²³⁵²³⁷

v2.1.288 (10월 2일). claude project purge가 이제 claude purge로 변경되었습니다. 이전 이름도 계속 작동하며 안내 메시지를 출력합니다. 백그라운드 명령의 시간 제한은 무인 세션(-p, Agent SDK, CI, 클라우드)에만 적용됩니다. /code-review --max-findings <n>|all은 --max-findings default를 지정할 때까지 지적 사항 수 제한을 변경합니다. /autocompact는 모델별로 윈도 설정을 저장합니다. CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS는 구조화된 출력을 거부하는 Mantle 또는 게이트웨이에서 해당 출력을 비활성화합니다. 경로별 규칙과 하위 폴더의 CLAUDE.md 파일은 Read뿐 아니라 Write와 Edit에서도 로드됩니다. 언어 서버는 무한정 대기하는 대신 60초 후 시간 초과 처리됩니다(서버별 requestTimeout). 자동 모드에서 대화가 너무 길어 클라이언트 측 분류기가 처리할 수 없으면, 도구를 호출할 때마다 승인을 요청하는 대신 대화를 압축합니다. 또한 클라이언트 측 분류기는 ANTHROPIC_DEFAULT_SONNET_MODEL이 Claude Sonnet 5.5 또는 Opus 5.5로 고정되어 있어도 이를 무시하고 Claude Sonnet 5를 사용합니다. Mods에는 $.ui.selection()이 추가되었고, GitHub CLI가 없는 클라우드 세션에는 내장 gh api가 제공됩니다. 빈 프롬프트에서 위쪽 화살표를 누르면 Ctrl+C로 지운 초안이 복원됩니다.²³⁴²³⁷

v2.1.105–v2.1.114의 새 명령¹⁴⁶¹⁵⁰

세션 요약 (v2.1.108+)

일시 중지한 세션으로 돌아왔을 때 맥락을 보여 주는 새로운 세션 단위 기능입니다. 기본적으로 활성화되며, /config 또는 CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0으로 비활성화할 수 있습니다. 모델은 Skill 도구를 통해 내장 슬래시 명령(/init, /review, /security-review)도 호출할 수 있어 subagent/skill 패턴의 활용 범위가 넓어집니다.¹⁴⁶

푸시 알림 (v2.1.110+)

Remote Control에서 “Claude가 판단할 때 푸시 알림 보내기”를 활성화하면, 이제 Claude가 새로운 푸시 알림 도구를 통해 자체 판단에 따라 모바일 푸시 알림을 보낼 수 있습니다. 기존 Remote Control 모바일/웹 인터페이스와 함께 사용할 수 있습니다.¹⁴⁶ 이제 /context, /exit, /reload-plugins도 Remote Control 클라이언트에서 작동합니다.

Windows PowerShell 도구 (v2.1.111+, 순차 배포)

Claude Code는 네이티브 Windows PowerShell 도구를 순차적으로 배포하고 있습니다. Linux/macOS에서는 CLAUDE_CODE_USE_POWERSHELL_TOOL=1로 활성화합니다(PATH에 pwsh가 있어야 합니다). Windows에서는 순차 배포 기간에 같은 변수로 활성화 여부를 제어합니다.¹⁴⁶

권한 모드 자동 승인 (v2.1.119+). 이제 PowerShell 도구 명령도 Bash 명령과 같은 방식으로 권한 모드에서 자동 승인을 받을 수 있습니다. PowerShell(Get-*:*) 같은 허용 규칙과 기존 패턴 구문을 사용하면 읽기 전용 작업의 승인 요청을 생략할 수 있어, 팀이 Linux/macOS에서 이미 누리던 운영 편의성을 동일하게 활용할 수 있습니다.¹⁵²

권한 요청 줄이기: 읽기 전용 Bash (v2.1.111+)

glob 인수가 포함된 읽기 전용 Bash 패턴(예: ls *.ts, cat src/*.md)과 cd <project-dir> &&로 시작하는 명령은 더 이상 권한 확인 메시지를 표시하지 않습니다.¹⁴⁶ /less-permission-prompts와 함께 사용하면 일상적인 작업 흐름에서 중단되는 횟수가 크게 줄어듭니다.

분산 추적 (v2.1.110+)

SDK 및 헤드리스 세션은 이제 환경에서 TRACEPARENT와 TRACESTATE를 읽어 Claude Code 실행을 분산 추적에 연결합니다. OTEL_LOG_RAW_API_BODIES=1(v2.1.111+)을 함께 사용하면 디버깅을 위해 API 요청/응답 본문 전체를 OpenTelemetry 로그 이벤트로 출력할 수 있습니다.¹⁴⁶

네이티브 바이너리 배포 (v2.1.113+)¹⁵⁰

v2.1.113에서는 CLI의 실행 방식이 바뀝니다. 이제 claude는 번들로 제공되는 JavaScript을 실행하는 대신 플랫폼별 선택적 의존성을 통해 네이티브 Claude Code 바이너리를 실행합니다. 설치 및 업데이트 명령은 그대로이며, 팀에서 배포 스크립트를 변경할 필요도 없습니다.

프롬프트 편집기 단축키 (v2.1.113+)¹⁵⁰

프롬프트 편집기에 여러 줄 입력 시 readline 방식으로 이동하는 기능과 전체 화면에서 뷰포트를 스크롤하는 기능이 추가됩니다.

subagents 정체 시간 제한 (v2.1.113+)¹⁵⁰

스트리밍 도중 멈춘 subagents는 이제 아무런 알림 없이 멈춰 있는 대신 10분 후 명확한 오류와 함께 실패 처리됩니다. CLAUDE_STREAM_IDLE_TIMEOUT_MS(v2.1.84+)를 함께 사용하면 스트리밍 API에서 발생하는 프로세스 정체에 더 폭넓게 대응할 수 있습니다.

v2.1.114 안정성 수정¹⁵⁰

v2.1.114(2026년 4월 18일)에는 수정 사항이 1개 포함됩니다. agent-teams의 팀원이 도구 사용 권한을 요청할 때 권한 대화상자가 비정상 종료될 수 있던 문제를 해결합니다. Agent Teams를 사용한다면 업그레이드하세요.

콘텐츠 표시: 텍스트 워터마크와 C2PA 파일 메타데이터 (2026년 8월)

Anthropic는 EU AI Act 제50조에 따라 Claude 생성 콘텐츠에 기계 판독이 가능한 표시를 도입한다고 발표했습니다. 이 조항은 새로 출시되는 AI 시스템에 대해 2026년 8월 2일부터 적용됩니다. 표시 체계는 2가지 요소로 구성됩니다. 생성된 텍스트에 삽입되는 보이지 않는 통계적 워터마크와, .svg, .png, .jpg 등의 생성 파일에 C2PA 개방형 표준에 따라 첨부되는 서명된 출처 메타데이터입니다.²⁵²²⁰⁴ 기사 제목만으로는 놓치기 쉬운 세부 사항이 있습니다. 두 요소 모두 모델 출시 시점을 기준으로 동일하게 적용됩니다. 지원 페이지에 따르면 “2026년 8월 2일 이후 출시되는 Claude 모델은 출시 시점부터 기계 판독이 가능한 표시를 지원”합니다. 해당 날짜 이전에 출시된 모델, 즉 현재 라인업 전체(Fable 5, Opus 5, Sonnet 5, Haiku 4.5)에는 EU 법의 전환 기간이 적용되며, Anthropic는 “이 모델들에도 표시 기능을 지원하기 위해 작업 중”입니다.²⁰⁴

이 목록은 8월 기준입니다. Fable 5.1(9월 1일), Opus 5.5(9월 22일), Sonnet 5.5(9월 28일)는 기준일 이후 출시되었으므로 이 규칙에 따르면 출시 시점부터 표시가 적용되는 모델에 해당합니다. Fable 5.1의 출시 노트에는 추가 기능으로 콘텐츠 출처 정보가 명시되어 있지만, Opus 5.5의 모델 페이지와 마이그레이션 가이드, Sonnet 5.5의 모델 페이지와 새 기능 소개 페이지에는 표시 기능에 대한 언급이 없습니다.^241222230 8월 이전 모델의 출력에는 텍스트든 파일이든 표시가 없습니다. 이후 모델의 출력에는 표시가 적용되며, 이는 모델 수준에서 이루어지므로 Claude Platform(API), claude.ai, Claude Code, Claude Cowork, Claude Tag, 클라우드 게이트웨이 등 모든 사용 환경에 적용됩니다. 널리 퍼진 한 스레드가 이를 거꾸로 설명했으므로 다음 사실도 짚고 넘어가야 합니다. 8월 이전 모델에서 문체나 동작이 달라졌다고 느끼더라도 그 원인은 워터마크일 수 없습니다. 해당 모델에는 아직 표시 기능이 적용되지 않았기 때문입니다.

작동 방식은 Google DeepMind의 SynthID-Text를 변형한 것입니다. Claude가 의미상 동등한 표현 중 하나를 선택할 때 워터마크는 “단어를 고르는 데 쓰이는 무작위성의 원천”을 바꿉니다. 문자를 추가하거나 후처리를 하지 않으며, Anthropic의 내부 테스트에 따르면 “워터마크는 콘텐츠, 창의성 수준, 가독성에 영향을 미치지 않습니다.”²⁵²

Claude Code 사용자에게 중요한 점은 코드에는 워터마크가 드문드문 삽입된다는 것입니다. 정상적으로 작동하는 코드는 임의로 선택할 여지가 적으므로, 표시는 주석이나 이름 짓기처럼 선택의 여지가 있는 부분에 집중됩니다. Anthropic는 이를 두고 “실제로 생성되는 코드에 미치는 영향은 무시할 만한 수준”이라고 설명합니다.²⁵² 표시가 유지될 가능성은 확률적이며 요소에 따라 다릅니다. 텍스트의 경우 가벼운 편집만으로는 “워터마크가 완전히 사라지지 않을 가능성이 높지만”, 전면적으로 다시 쓰면 사라집니다. Claude가 번역한 텍스트에는 새로운 표시가 들어갑니다. 파일 메타데이터의 경우 형식 변환, 다시 저장, 스크린샷 촬영으로 C2PA 서명이 사라질 수 있습니다.²⁰⁴ 탐지용 API도 계획되어 있습니다. 탐지 결과가 양성이면 “Claude가 어느 시점에 해당 콘텐츠에 관여했을 가능성이 높다”는 점을 보여주지만, “Claude가 작성했다”와 “Claude가 대폭 수정했다”를 구분할 수는 없다고 명시합니다. 또한 지원 페이지에 따르면 표시가 없다는 사실만으로도 아무것도 입증할 수 없습니다. 어떤 고객 등급에서도 표시를 해제하는 옵션은 언급되지 않았습니다.²⁵²²⁰⁴

Claude Code의 비용은 얼마입니까?

지속적으로 Claude Code을 사용하려면 비용을 파악하고 관리해야 합니다. 모델 기능은 모델 선택을, 작업별로 적합한 모델을 선택하는 방법은 결정 프레임워크를 참고하세요.

비용 확인

> /cost

출력:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

구독 사용자는 /cost에서 모델별 사용량과 캐시 적중 내역을 확인할 수 있어, 어떤 모델이 토큰을 얼마나 사용했고 캐시에서 얼마나 제공되었는지 정확히 알 수 있습니다(v2.1.92+).¹³⁷

정가 대신 계약 요율 적용(modelPricing, 관리형 설정, v2.1.243+): 모델별 협상 요율이나 할인 배수가 있는 조직은 이를 modelPricing 관리형 설정으로 배포할 수 있습니다. 그러면 /cost, 상태 표시줄, 원격 측정 비용 수치에 정가 대신 해당 요율이 적용되어 개발자가 보는 금액과 조직이 실제로 지불하는 금액이 일치합니다.²⁵⁰ v2.1.271부터는 내부 팀에 할증 요율을 부과하는 조직을 위해 배수를 1보다 크게, 최대 10까지 설정할 수도 있습니다.²¹⁶

세션별 프롬프트 캐시 표시줄(v2.1.251+): /cost에는 세션의 프롬프트 캐시 적중률, 누락 횟수, 다시 캐시된 토큰 수, 캐시 준비 상태를 보여 주는 표시줄이 추가되며, 상태 표시줄 스크립트에도 이에 대응하는 prompt_cache 객체가 제공됩니다. 이 객체는 기본 대화에서 첫 번째 API 응답을 받은 후 나타나고 subagents 요청은 집계하지 않으며, API 응답에 포함된 캐시 토큰 수를 기준으로 계산되므로 모든 제공업체에서 작동합니다. /usage도 Prompt cache (main) 줄에 같은 통계를 표시합니다.²⁰⁶²⁰⁹ v2.1.260부터는 /cost 표시줄과 상태 표시줄의 prompt_cache 객체에 캐시 누락의 추정 원인도 표시됩니다. 예를 들어 도구 정의나 시스템 프롬프트가 변경되었거나, 세션이 캐시 TTL을 넘겨 유휴 상태로 유지된 경우입니다.²¹²

에이전트 트래픽으로 인한 자체 캐시 접두부 손상 방지(v2.1.265): 위임 작업에서 발생하던 프롬프트 캐시 누수를 2가지 수정으로 해결했습니다. 포그라운드에서 생성한 subagent를 재개해도 더 이상 도구 목록과 시스템 프롬프트 접두부가 변경되지 않으며, 에이전트 팀원과 재개된 subagents는 이후 차례에서 SubagentStart hook 컨텍스트와 미리 불러온 skills를 프롬프트 접두부 밖으로 옮기지 않습니다. 두 문제 모두 접두부가 변경되면서 이후의 모든 내용이 캐시되지 않은 입력으로 다시 전송되어 프롬프트 캐시 재사용을 방해했습니다. 이는 캐시의 경제성이 가장 중요한 장시간 에이전트 세션에서 발생했으며, v2.1.260에서 Fable 5.1의 도구 호출 차례에 대해 해결한 문제와 같은 유형입니다.²¹⁵

v2.1.267 캐시 안정성 수정 묶음: 한 번의 릴리스에서 약 10가지 문제를 수정했으며, 모두 대화 도중 무언가가 프롬프트 접두부를 다시 작성해 이후의 모든 내용이 캐시되지 않은 입력으로 재전송되는 같은 유형의 문제였습니다. 이제 재개된 세션은 커넥터가 다시 연결되기 전에 도구 목록이나 도구 설명을 다시 만들거나 이전 MCP 도구 알림을 다시 작성하지 않습니다. /model로 모델을 전환해도 모든 도구 정의를 다시 전송하지 않습니다. 커밋과 PR 출처 표시는 이제 모델이 변경될 때 갱신되는 대화 메모로 전달됩니다. --system-prompt 또는 --append-system-prompt로 시작한 subagents와 세션은 시스템 프롬프트와 도구 정의를 한 번만 기록합니다. 또한 세션 도중 추가되는 MCP 및 plugin 도구는 ToolSearch가 없는 세션에 다시 작성된 도구 목록이 아니라 지연 정의로 전달됩니다. 이 수정 묶음은 v2.1.260과 v2.1.265의 개선 범위를 세션 재개, 모델 전환, MCP 재연결 영역까지 확장합니다.²¹⁶

v2.1.273에서 대화 흐름 유지: /login, /upgrade, /extra-usage가 대화의 이전 사고 내용을 삭제해 다음 요청에서 프롬프트 캐시 전체를 다시 작성하게 만들던 문제를 해결했습니다.²¹⁷

v2.1.277에서 접두부 누수 3가지 추가 해결: /clear 이후 계속된 세션에서 재시작, --continue, --resume을 사용할 때 SessionStart hook이 출력을 표시하면 첫 메시지 일부가 누락되어 프롬프트 캐시가 완전히 빗나가던 문제를 해결했습니다. 재개된 subagents와 팀원이 이미 불러온 MCP 도구 정의를 다시 만들어 해당 에이전트의 프롬프트 캐시를 손상하던 문제도 해결했습니다. 또한 대화 초기에 기록된 첨부 파일을 세션 재개나 재실행 후 다시 만들면서 확장 사고가 사라지고 프롬프트 캐시가 빗나가던 문제도 해결했습니다. v2.1.265-267 수정 묶음과 동일하게 무언가가 접두부를 다시 작성하고 이후의 모든 내용이 캐시되지 않은 상태로 재전송되던 문제이며, 이제 SessionStart 출력, 재개된 에이전트의 MCP 정의, 기록된 첨부 파일까지 처리합니다.²¹⁹

v2.1.280에서 2가지 추가 해결: Claude이 작업 중일 때 호스트 앱(Claude Desktop, VS Code, SDK)에서 모델을 전환해도 다음 프롬프트에서 더 이상 프롬프트 캐시가 빗나가지 않습니다. 또한 재개된 포크 subagent는 도구 목록을 다시 구성하지 않고 처음 사용했던 목록을 재전송하므로, 해당 에이전트의 프롬프트 캐시가 손상되지 않습니다.²²⁰

v2.1.281에서 3가지 추가 해결: 권한 요청이 대기 중일 때 재시작한 뒤 재개한 세션이 이전과 다른 기록을 전송해 그 지점부터 프롬프트 캐시를 손상하던 문제를 해결했습니다. 대화 도중 연결이 끊기거나 재개 후에도 연결 중인 MCP 서버는 도구 검색이 꺼져 있을 때 프록시나 게이트웨이 뒤에서도 더 이상 캐시 비용을 유발하지 않습니다. 또한 재개된 세션이 이전 차례를 변경된 형태로 다시 전송해 API이 대화의 이전 추론을 누락할 수 있던 문제도 해결했습니다.²²⁴

구독 요금제

사용량 제한(2025년 8월): Anthropic은 유료 구독자에게 주간 사용량 제한을 도입했습니다. Max 구독자는 제한을 초과한 추가 사용량을 표준 API 요율로 구매할 수 있습니다.¹⁴

사용량 제한 2배 상향(2026년 5월 6일): Code with Claude SF 행사에서 Anthropic은 Pro, Max, Team, 좌석 기반 Enterprise 요금제의 Claude Code 5시간 사용량 제한을 2배로 늘리고, Pro와 Max 계정의 사용량이 많은 시간대 감축 정책을 폐지했으며, Claude Opus 모델의 API 사용량 제한을 “상당히” 높였습니다. 이를 뒷받침하는 처리 용량은 SpaceX Colossus 1 계약에서 나옵니다. “한 달 안에 300메가와트가 넘는 신규 용량(NVIDIA GPU 220,000개 이상)”을 확보하는 계약입니다.¹⁵⁷

2026년 9월 14일부터 적용되는 주간 제한(8월 29일 발표): 5월 상향 이후 적용된 임시 주간 제한 50% 증가는 9월 14일에 종료되고, Pro, Max, Team, 좌석 기반 Enterprise 요금제에는 상향 전 기준보다 25% 높은 제한이 영구 적용됩니다. 변경에 대한 Anthropic의 계산은 다음과 같습니다. “현재와 비교하면 Claude Code의 주간 제한이 17% 줄어듭니다.” 현재 주간 상한이 150단위라면 9월 14일부터 125단위가 됩니다. 이번 발표에는 5시간 제한이 포함되지 않으므로 5월의 2배 상향은 유지됩니다. 오랫동안 무인 세션을 실행한다면 지금부터 낮아진 상한에 대비하세요. 자동으로 제한 초기화 시점에 계속 실행하는 전환 옵션(v2.1.234)과 /usage가 핵심적인 2가지 제어 수단입니다.²¹³

API 토큰 가격(2026년 10월)^1144222239

API 사용량에 따라 요금이 청구되는 사용자의 100만 토큰당 가격은 다음과 같습니다.

1M 컨텍스트 가격(2026년 4월): Opus 4.7, Opus 4.6, Sonnet 4.6, Mythos Preview는 모두 표준 100만 토큰당 요율로 1M 컨텍스트를 제공합니다. 긴 컨텍스트 추가 요금은 없습니다.¹⁴⁸ 이는 최근에 통합된 정책이므로, 입력 토큰이 200K를 넘으면 Opus 4.6 또는 Sonnet 4.6에 입력 2배, 출력 1.5배의 요금이 부과된다는 이전 안내는 더 이상 유효하지 않습니다. 레거시 Opus 4.5와 그 이전 모델은 기존 가격 체계를 유지합니다.

데이터 저장 지역 가격: inference_geo로 미국 내 추론만 지정하면 캐시 읽기와 쓰기를 포함한 모든 토큰 가격에 1.1배가 적용됩니다(Opus 4.6 이상 모델).¹⁴⁸

프롬프트 캐싱은 반복되는 입력 비용을 크게 줄입니다. 캐시 쓰기에는 기본 가격의 1.25배(5분 캐시) 또는 2배(1시간 캐시)가 들지만, 캐시 읽기에는 0.1배만 부과되어 90% 절감됩니다. 예외적으로 더 낮은 2가지 경우가 있습니다. Claude Opus 5.5의 읽기는 0.05배($0.20/MTok, 95% 절감)이며, Claude Fable 5.1과 Mythos 5.1의 읽기는 0.025배(Fable 5.1 기준 $0.25/MTok, 97.5% 절감)입니다.²⁴¹²²² 컨텍스트를 반복해서 사용하는 RAG 시스템과 코딩 도우미에서는 캐싱으로 비용을 88-95% 줄일 수 있습니다.

Batch API는 야간 테스트 모음처럼 긴급하지 않은 작업에 24시간 내 처리 조건으로 50% 할인을 제공합니다.

여러 계정 정책⁵²

Claude 계정을 여러 개 보유할 수 있습니까? 예. 정당한 사용 사례라면 가능합니다. Anthropic은 서로 다른 용도로 사용하는 여러 계정을 명시적으로 허용합니다.

허용되는 경우:

기술적 제한: - 동일한 전화번호로 최대 3개 계정을 인증할 수 있습니다. - 동일한 IP나 네트워크에서 여러 유료 구독을 사용하는 것이 명시적으로 지원됩니다. - 계정은 완전히 분리되며 계정 간에 채팅이나 프로젝트를 이전할 수 없습니다.

금지되는 행위(사용 정책 기준): - 이용 정지 후 제재를 회피하기 위해 계정을 만드는 행위 - 탐지를 피하려고 여러 계정에서 악의적인 활동을 조직적으로 수행하는 행위 - 여러 계정을 사용해 사용량 제한이나 무료 요금제 크레딧을 우회하는 행위

실제 사례: 2026년 1월, 고급 사용자 Jeffrey Emanuel(@doodlestein)이 보유한 Max 계정 22개가 자동 감지되어 일시적으로 이용 정지되었습니다. Anthropic 직원 Thariq(@trq212)은 정당한 사용임을 확인한 뒤 4시간 이내에 문제를 해결했습니다. 업무와 개인 프로젝트 모두에서 여러 계정으로 Claude Code을 광범위하게 사용하는 것은 서비스가 의도한 사용 방식에 정확히 부합하지만, 시스템을 악용하려고 해서는 안 됩니다.

확실하지 않은 경우: Anthropic 지원팀에 문의하여 사용 중인 구성이 허용되는지 서면으로 확인하세요.

비용 요인

실제 비용 예시

프롬프트 캐싱 할인을 적용하기 전의 정가 기준입니다(100K 토큰 이하 프롬프트에서 Haiku 5.5 $0.10/$0.50, Sonnet 5.5 $2/$10, Opus 5.5 $4/$20, 각 MTok 기준).

비용 절감 팁: 탐색용 subagents에는 Haiku를, 구현에는 Sonnet을 사용하면 모든 작업에 Sonnet을 사용할 때보다 일반적으로 비용을 40-50% 줄일 수 있습니다.

팀 비용 관리

팀 규모별 권장 TPM/RPM:

숨겨진 도구 요금

토큰당 가격 외에도 일부 도구에는 별도 요금이 부과됩니다.⁹

에이전트 반복 작업에서는 이러한 비용이 누적됩니다. Bash를 사용하는 100회 반복 디버깅 주기는 추가 부담만으로 약 24,500개의 입력 토큰을 소비합니다.

비용 절감 전략

1. subagents에 Haiku 사용: 대부분의 탐색에는 Sonnet이 필요하지 않습니다.
2. 프롬프트 캐싱 활성화: 기본적으로 활성화되지만 비활성화되지 않았는지 확인하세요.
3. 최대 차례 수 설정: claude --max-turns 5로 제어되지 않는 대화 확장을 방지합니다.
4. 금액 상한 설정: claude --max-budget-usd 5로 지출 상한에 도달하면 세션을 강제 종료합니다. v2.1.217부터 이 상한은 백그라운드 subagents에도 적용됩니다. 상한에 도달하면 새 에이전트 생성을 거부하고 실행 중인 백그라운드 에이전트를 중단합니다. 이전에는 백그라운드 에이전트가 예산 제한을 벗어났습니다.¹⁹⁴
5. 탐색에 계획 모드 사용: 실행하지 않으므로 의도하지 않은 고비용 작업을 방지할 수 있습니다.
6. 선제적으로 압축: 컨텍스트가 작을수록 토큰이 적게 필요합니다.
7. 출력 제한: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. 긴급하지 않은 작업에 Batch API 사용: 입력과 출력 토큰 모두 50% 할인됩니다.
9. 프로젝트의 Claude API 지출 분석: /claude-api cost-optimize(v2.1.247+)는 기존 프로젝트의 Claude API 지출을 분석하고 캐싱, 토큰 관리, batch, effort, 모델 선택 등의 비용 절감 수단을 측정 가능한 변경 단위로 하나씩 적용합니다. 이는 Claude Code 세션 자체가 아니라 API으로 구축하는 앱을 위한 기능입니다.²⁴⁵

사용량 모니터링

• Claude Console: platform.claude.com(Admin 또는 Billing 역할 필요)
• Workspace 제한: Workspace별 지출 한도를 설정합니다.
• Bedrock/Vertex: 각 클라우드의 자체 비용 모니터링을 사용합니다.
• LiteLLM: 외부 제공업체에서 사용자별 사용량을 자세히 추적할 때 사용합니다.

백그라운드 토큰 사용량

일부 작업은 백그라운드에서 토큰을 소비합니다. - /resume을 위한 대화 요약 - /cost 및 /status 명령 - 자동 압축

일반적으로 세션당 $0.04 미만입니다.

Claude Code 분석 API(Team/Enterprise)⁴⁶

Admin API을 통해 조직의 Claude Code 사용량 분석 및 생산성 지표에 프로그래밍 방식으로 접근할 수 있습니다.

엔드포인트: GET /v1/organizations/usage_report/claude_code

요구 사항: - Admin API 키(sk-ant-admin...) - Team 또는 Enterprise 요금제 - Admin, Billing 또는 Developer 역할

제공되는 지표:

요청 예시:

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

사용 사례: - 개발자 생산성 분석(세션, 커밋, PR) - 도구 사용 지표(Edit, Write 등의 수락률과 거부율) - 팀별 비용 추적 및 배분 - AI 코딩 도구의 ROI 타당성 입증

참고: 데이터는 활동 완료 후 1시간 이내에 나타납니다. 일관성을 위해 응답에는 1시간보다 오래된 데이터만 포함됩니다.

의사 결정 프레임워크

기능이 있다는 사실만 알아서는 충분하지 않습니다. 각 기능을 언제 사용해야 하는지도 알아야 합니다. 다음 의사 결정 트리는 지식을 실행으로 전환합니다.

어떤 모델을 사용해야 합니까?

START → Is the task simple? (file search, quick question, formatting)
         │
         ├── YES → Use Haiku
         │         Cost: ~$0.03/task
         │         Speed: Fastest
         │
         └── NO → Does it require deep reasoning?
                  (architecture, complex debugging, security analysis)
                  │
                  ├── YES → Use Opus 5.5 (medium effort default; /effort high or xhigh for harder)
                  │         Cost: ~$1.60/task
                  │         Quality: Highest (1M context at standard price, adaptive reasoning)
                  │
                  └── NO → Use Sonnet
                           Cost: ~$0.50/task
                           Balance: Best overall when cost matters

경험 법칙: v2.1.280부터 기본 모델은 더 이상 사용 중인 요금제를 따르지 않으며, Microsoft Foundry를 제외한 모든 세션이 Opus 5.5로 시작합니다. 따라서 예전에 “Opus로 올리기”였던 전략이 이제는 반대로 바뀌었습니다. 작업에 높은 수준의 추론이 필요하지 않다면 /model sonnet으로 낮춰서 토큰 비용을 절반으로 줄이세요.^{181197207220221} subagents에는 Haiku를 사용하세요. 모델을 낮춘 뒤 답변이 피상적으로 느껴진다면 Opus를 계속 사용하세요. agent teams(v2.1.32 이상)를 사용하면 Opus가 서로 다른 하위 작업을 병렬로 수행하는 여러 agents를 조율할 수 있습니다.⁷⁹

Command, Skill, Subagent, Agent Team 중 무엇을 사용해야 합니까?

Do you want explicit control over when it runs?
│
├── YES → Use Slash Command
│         Example: /deploy, /test, /security-review
│         You invoke it. You control timing.
│
└── NO → Should the expertise apply automatically based on context?
         │
         ├── YES → Use Skill
         │         Example: Security patterns, domain rules, code standards
         │         Claude recognizes context and applies expertise.
         │
         └── NO → Does the work need isolated context?
                  │
                  ├── YES → Is there one subtask or many parallel subtasks?
                  │         │
                  │         ├── ONE → Use Subagent (Task tool)
                  │         │         Example: Deep exploration, parallel analysis
                  │         │         Prevents context bloat in main conversation.
                  │         │
                  │         └── MANY → Use Agent Team (v2.1.32+)
                  │                   Example: 5 agents reviewing different modules simultaneously
                  │                   Opus coordinates; each agent works independently.
                  │
                  └── NO → Just prompt directly
                           Not everything needs abstraction.

Hook과 Prompt 중 무엇을 사용해야 합니까?

Must the action ALWAYS happen, regardless of Claude's judgment?
│
├── YES → Use Hook (deterministic)
│         Examples:
│         - Format code after every edit
│         - Log all bash commands
│         - Block access to .env files
│         Claude cannot skip, forget, or decide otherwise.
│
└── NO → Use Prompt (probabilistic)
         Examples:
         - "Consider adding tests"
         - "Think about edge cases"
         - "Review for security if relevant"
         Claude decides based on context.

Extended Thinking은 언제 사용해야 합니까?

Is this a genuinely hard problem?
│
├── Architectural decision with many tradeoffs → YES, use thinking
├── Complex debugging with unclear root cause → YES, use thinking
├── Security analysis requiring careful reasoning → YES, use thinking
├── Understanding unfamiliar codebase → YES, use thinking
│
├── Routine bug fix → NO, skip thinking
├── Simple refactoring → NO, skip thinking
├── Code formatting → NO, skip thinking
└── Quick questions → NO, skip thinking

세션 중에 Alt+T로 전환하세요. thinking 예산을 높이면 비용도 증가하므로, 최소값으로 시작하고 응답이 성급하다고 느껴질 때만 늘리세요.

Opus 4.6 adaptive thinking: Opus 4.6은 문제의 복잡도에 따라 thinking 깊이를 자동으로 조절합니다. 대부분의 작업에서는 thinking 예산을 명시적으로 제어할 필요가 없습니다. 어려운 문제에는 더 많은 추론을 사용하고 간단한 문제에는 빠르게 응답합니다. 수동 thinking 전환은 Sonnet에서 더 깊이 분석하도록 강제하려는 경우에 가장 유용합니다.

어떤 실행 환경을 사용해야 합니까?

Where should this work happen?
│
├── Requires YOUR local files and tools
│   │
│   ├── Interactive, iterative work → Main REPL session
│   ├── One-shot scripted task → claude -p "prompt" (print mode)
│   ├── CI/CD automation → claude -p --json (non-interactive + structured output)
│   └── Parallel isolated tasks → Subagents via Task tool
│
├── Requires SOMEONE ELSE'S environment
│   │
│   └── Remote codebase or server → Background agent (cloud)
│
└── Doesn't require any environment
    │
    ├── Research or analysis → Subagent with Explore type
    └── Web content extraction → WebFetch / WebSearch tools

Agent Teams, Subagents, 병렬 Sessions 비교

Do you need multiple agents working on related subtasks?
│
├── YES → Are the subtasks independent (no shared state)?
│         │
│         ├── YES → Can they share the same codebase?
│         │         │
│         │         ├── YES → Use Agent Team (v2.1.32+)
│         │         │         Opus coordinates. Agents share repo access.
│         │         │         Example: "Review auth, API, and DB modules in parallel"
│         │         │
│         │         └── NO → Use Parallel Sessions (separate terminals)
│         │                  Each has its own working directory.
│         │                  Example: "Fix repo-A and repo-B simultaneously"
│         │
│         └── NO → Use Sequential Subagents
│                  Results from one feed into the next.
│                  Example: "Explore → Plan → Implement"
│
└── NO → Use Single Subagent or Main REPL