Ch1. 플랜 & 환경 설정

플랜 선택 가이드

Claude Code는 Pro/Max 개인 플랜과 Team Premium 좌석에서 제공됩니다. 가격과 포함 기능은 수시로 변경될 수 있으므로, 구매 전 공식 페이지를 확인하세요.

플랜	Claude Code	월 구독(기준)	비고
Pro	포함	$20 (월간) /$ 17 (연간 환산)	개인용
Max 5x	포함	$100 (월간)	개인용, 고급 기능 얼리 액세스
Max 20x	포함	$200 (월간)	개인용, 최대 사용량
Team Standard	미포함	$25 (월간) /$ 20 (연간 환산)	팀용, 5~150명
Team Premium	포함	$125 (월간) /$ 100 (연간 환산)	팀용, 5~150명
Enterprise	포함	$20/좌석 + 사용량 기반	관리자 지출 한도, SCIM, 감사 로그

가격 기준

위 가격은 공식 페이지의 표기(미국 기준)입니다. 지역/과금 방식에 따라 다를 수 있습니다.

설치 & 업데이트

권장 설치 (네이티브 인스톨러)

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

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

대안 설치: Homebrew / WinGet

brew install --cask claude-code

winget install Anthropic.ClaudeCode

npm 설치 (레거시)

공식 문서에서는 npm 설치가 deprecated로 표시됩니다. 레거시 환경에서만 사용하고, 가능하면 네이티브 인스톨러로 전환하세요.

v2.1.113부터는 CLI가 플랫폼별 네이티브 Claude Code binary를 실행하는 방향으로 정리되었습니다. 신규 배포나 팀 표준 환경은 npm 글로벌 패키지보다 네이티브 인스톨러/Homebrew/WinGet 기준으로 맞추는 편이 안전합니다.

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

설치 검증

claude doctor

업데이트

네이티브 설치는 기본적으로 자동 업데이트됩니다.
Homebrew / WinGet 설치는 자동 업데이트되지 않으므로 brew upgrade claude-code, brew upgrade claude-code@latest, winget upgrade Anthropic.ClaudeCode를 주기적으로 실행해야 합니다.
채널 변경: /config → Auto-update channel 또는 autoUpdatesChannel 설정
latest가 기본 채널이며, stable은 보통 약 1주일 늦고 큰 회귀가 있는 릴리스를 건너뜁니다.
수동 업데이트: claude update
자동 업데이트 완전 비활성화: DISABLE_AUTOUPDATER=1

API 빌링 인증

claude auth login --console 명령으로 Anthropic Console(API 빌링) 계정으로 인증할 수 있습니다. (v2.1.79)

AWS Bedrock 로그인 마법사 (v2.1.92)

로그인 화면에서 **"3rd-party platform"**을 선택하면 Bedrock 설정 마법사가 열립니다. AWS 인증 방식, 리전 선택, 자격증명 검증, 모델 pinning까지 순서대로 안내하므로 Bedrock을 처음 붙이는 팀의 초기 설정 실수를 줄이는 데 유용합니다.

모델 선택

세션 중 /model로 모델을 전환할 수 있습니다.
기본 모델은 settings.json의 model로 지정할 수 있습니다.
Opus 4.6이 Max/Team 구독자에게 medium effort 기본값으로 적용됩니다. (v2.1.68)
Opus 4.7이 최신 고성능 경로로 반영되었고, xhigh effort 레벨이 추가되었습니다. xhigh는 high와 max 사이 단계이며 /effort, --effort, 모델 피커에서 선택합니다. (v2.1.111)
Opus 4.6 1M 컨텍스트 기본: Max, Team, Enterprise 플랜에서 Opus 4.6의 1M 컨텍스트 윈도우가 기본 활성화됩니다. (v2.1.75)
Sonnet 4.6이 2026-02-17에 출시되었으며, Sonnet 4.5 사용자는 자동으로 Sonnet 4.6으로 마이그레이션됩니다. (v2.1.69)
Opus 4, 4.1은 first-party API에서 제거되었으며, Opus 4.6으로 자동 마이그레이션됩니다. (v2.1.68)
Bedrock, Vertex, Microsoft Foundry의 기본 Opus 모델도 Opus 4.6으로 변경되었습니다. (v2.1.73)
modelOverrides 설정으로 모델 피커 항목을 커스텀 프로바이더 모델 ID에 매핑할 수 있습니다 (예: Bedrock 추론 프로필 ARN). (v2.1.73)
/model 피커가 raw 모델 ID 대신 읽기 좋은 라벨(예: "Sonnet 4.5" → "Sonnet 4.6")을 표시하며, 새 버전이 있으면 업그레이드 힌트를 보여줍니다. (v2.1.51)
Opus 4.6의 기본 최대 출력 토큰이 64k로 증가했습니다(상한 128k). (v2.1.77)
ANTHROPIC_CUSTOM_MODEL_OPTION 환경변수로 /model 피커에 커스텀 모델 항목을 추가할 수 있습니다. (v2.1.78)

추론 강도(Effort) 조절

/effort 명령으로 추론 강도를 조절할 수 있습니다: low (○), medium (◐), high (●) (v2.1.72)
Opus 4.7에서는 xhigh가 추가되며, max는 세션 한정으로 노출될 수 있습니다. 사용 가능한 레벨은 모델마다 다릅니다. (v2.1.111, 공식 commands 기준)
"ultrathink" 키워드를 입력하면 다음 턴에 high effort가 활성화됩니다. (v2.1.68)
/effort 명령에서 "auto"가 현재 어떤 값으로 해석되는지 표시됩니다. (v2.1.80)
/effort를 인수 없이 실행하면 인터랙티브 슬라이더가 열려 화살표 키로 레벨을 바꾸고 Enter로 확정합니다. (v2.1.111)
스킬과 슬래시 커맨드의 frontmatter에 effort 필드를 지정해 effort 레벨을 오버라이드할 수 있습니다. (v2.1.80)

퍼미션 모드 이해

모드	동작
`default`	도구 최초 사용 시 승인 요청
`acceptEdits`	파일 편집 승인 자동화
`plan`	분석만 가능, 수정/명령 실행 불가
`auto`	AI 분류기가 위험도를 판단해 안전한 작업은 자동 진행, 위험한 작업은 차단 (2026-03-24)
`bypassPermissions`	모든 승인 생략 (격리 환경에서만 사용 권장)

Auto 모드 (2026-03-24)

Auto 모드는 백그라운드 AI 분류기가 각 도구 호출의 위험도를 평가하여, 안전한 작업은 프롬프트 없이 진행하고 위험한 작업은 차단합니다. default와 bypassPermissions의 중간 지점입니다.

OS 수준 샌드박스와 결합된 다층 방어 구조
거부된 명령은 /permissions → Recent 탭에 기록되고, r로 재시도 가능 (v2.1.89)
PermissionDenied 훅으로 거부 이벤트를 커스텀 처리 가능 (v2.1.88)
최신 릴리스 기준으로 Max 사용자는 Opus 4.7 세션에서 Auto 모드 접근이 단순화되었고, 더 이상 --enable-auto-mode 플래그가 필요하지 않습니다. (v2.1.111)

claude --permission-mode auto

자동 메모리 저장 디렉토리

autoMemoryDirectory 설정으로 자동 메모리가 저장되는 디렉토리를 커스터마이즈할 수 있습니다. (v2.1.74)

세션 이름 지정

-n / --name CLI 플래그로 세션에 표시 이름을 부여할 수 있습니다. 프롬프트 바에 세션 이름이 표시되며, /rename으로 변경도 가능합니다. (v2.1.76)

턴 소요 시간 표시

/config 메뉴의 "Show turn duration" 토글로 각 턴의 소요 시간을 표시할 수 있습니다. (v2.1.79)

Managed Settings (기업 관리)

macOS에서는 plist, Windows에서는 Registry를 통해 Managed settings를 설정할 수 있습니다. 조직 전체에 일관된 정책을 배포할 때 유용합니다. (v2.1.51)

`managed-settings.d/` 드롭인 디렉토리 (v2.1.83)

managed-settings.d/ 디렉토리에 개별 JSON 파일을 드롭인하여 managed settings를 조합할 수 있습니다. MDM 도구로 부분적인 정책 파일을 배포하거나, 여러 팀의 설정을 병합할 때 유용합니다.

`forceRemoteSettingsRefresh` fail-closed 정책 (v2.1.92)

원격 managed settings를 쓰는 조직은 forceRemoteSettingsRefresh 정책으로 최신 정책을 다시 받아오기 전에는 CLI가 시작되지 않도록 강제할 수 있습니다. fetch에 실패하면 그대로 종료되므로, 캐시된 옛 정책으로 실행되면 안 되는 환경에 적합합니다.

Windows 경로 변경 (Breaking)

Windows의 deprecated managed settings 경로 C:\ProgramData\ClaudeCode\가 v2.1.75에서 제거되었습니다. Windows를 사용하는 팀은 Registry 기반으로 마이그레이션해야 합니다.

샌드박스 설정

`sandbox.failIfUnavailable` (v2.1.83)

샌드박스를 사용할 수 없는 환경에서 Claude Code가 실행을 거부하도록 강제할 수 있습니다. 보안 정책이 엄격한 조직에서 샌드박스 없는 실행을 방지합니다.

{
  "sandbox": {
    "failIfUnavailable": true
  }
}

`sandbox.network.deniedDomains` (v2.1.113)

넓은 allowedDomains allowlist를 쓰더라도, 특정 목적지 도메인만 예외적으로 차단할 수 있습니다. deniedDomains는 동일한 wildcard 문법을 사용하며, allowedDomains보다 우선 적용됩니다.

{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["uploads.github.com"]
    }
  }
}

배포/CI 환경에서 넓은 네트워크 허용이 필요하지만 업로드·외부 전송 엔드포인트만 막고 싶을 때 유용합니다.
공식 설정 문서 기준으로 deniedDomains는 allowManagedDomainsOnly와 무관하게 모든 settings source에서 병합됩니다.

서브프로세스 환경 정리 (v2.1.83)

CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 환경변수를 설정하면 서브프로세스에서 자격증명 관련 환경변수를 제거합니다. CI/CD에서 API 키가 하위 프로세스에 노출되는 것을 방지합니다.

상태 표시줄 커스터마이징

/statusline 명령으로 커스텀 상태 표시줄을 설정할 수 있습니다. 설정 파일에 statusLine을 직접 추가하는 방식도 지원됩니다.

statusline 스크립트에서 rate_limits 필드를 사용해 5시간/7일 윈도우의 rate limit 사용량(used_percentage, resets_at)을 표시할 수 있습니다. (v2.1.80)

Thinking Summaries 기본 비활성화 (v2.1.88)

모델의 thinking(추론 과정) 요약이 기본적으로 생성되지 않습니다. 이전에는 각 턴에서 thinking summary가 표시되었지만, 이제는 showThinkingSummaries: true 설정으로 복원해야 합니다.

렌더링 최적화 (v2.1.88)

CLAUDE_CODE_NO_FLICKER=1 환경변수를 설정하면 alt-screen 렌더링에 가상 스크롤백을 사용하여 화면 깜빡임이 제거됩니다. 스크롤이 많은 작업에서 시각적 안정성이 향상됩니다.

유휴 복귀 프롬프트 (v2.1.84)

세션이 75분 이상 유휴 상태이면 /clear를 제안하는 프롬프트가 표시됩니다. 오래 방치된 세션의 컨텍스트를 정리하도록 유도합니다.

참고 문서

Claude 요금제(개인/팀): https://claude.com/ko-kr/pricing (한국어)
설치/업데이트: https://code.claude.com/docs/ko/setup (한국어)
설정 파일과 /config: https://code.claude.com/docs/ko/settings (한국어)
/statusline 설정: https://docs.claude.com/ko/docs/claude-code/statusline (한국어)
/model 명령: https://code.claude.com/docs/ko/slash-commands (한국어)
Max 플랜(Claude Code 포함): https://support.claude.com/en/articles/11049741-what-is-the-max-plan (영어)
퍼미션 모드: https://docs.claude.com/en/docs/claude-code/team (영어)

플랜 선택 가이드

플랜	Claude Code	월 구독(기준)	비고
Pro	포함	$20 (월간) /$ 17 (연간 환산)	개인용
Max 5x	포함	$100 (월간)	개인용, 고급 기능 얼리 액세스
Max 20x	포함	$200 (월간)	개인용, 최대 사용량
Team Standard	미포함	$25 (월간) /$ 20 (연간 환산)	팀용, 5~150명
Team Premium	포함	$125 (월간) /$ 100 (연간 환산)	팀용, 5~150명
Enterprise	포함	$20/좌석 + 사용량 기반	관리자 지출 한도, SCIM, 감사 로그

가격 기준

위 가격은 공식 페이지의 표기(미국 기준)입니다. 지역/과금 방식에 따라 다를 수 있습니다.

설치 & 업데이트

권장 설치 (네이티브 인스톨러)

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

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

대안 설치: Homebrew / WinGet

brew install --cask claude-code

winget install Anthropic.ClaudeCode

npm 설치 (레거시)

공식 문서에서는 npm 설치가 deprecated로 표시됩니다. 레거시 환경에서만 사용하고, 가능하면 네이티브 인스톨러로 전환하세요.

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

설치 검증

claude doctor

업데이트

네이티브 설치는 기본적으로 자동 업데이트됩니다.
Homebrew / WinGet 설치는 자동 업데이트되지 않으므로 brew upgrade claude-code, brew upgrade claude-code@latest, winget upgrade Anthropic.ClaudeCode를 주기적으로 실행해야 합니다.
채널 변경: /config → Auto-update channel 또는 autoUpdatesChannel 설정
latest가 기본 채널이며, stable은 보통 약 1주일 늦고 큰 회귀가 있는 릴리스를 건너뜁니다.
수동 업데이트: claude update
자동 업데이트 완전 비활성화: DISABLE_AUTOUPDATER=1

API 빌링 인증

claude auth login --console 명령으로 Anthropic Console(API 빌링) 계정으로 인증할 수 있습니다. (v2.1.79)

AWS Bedrock 로그인 마법사 (v2.1.92)

모델 선택

세션 중 /model로 모델을 전환할 수 있습니다.
기본 모델은 settings.json의 model로 지정할 수 있습니다.
Opus 4.6이 Max/Team 구독자에게 medium effort 기본값으로 적용됩니다. (v2.1.68)
Opus 4.7이 최신 고성능 경로로 반영되었고, xhigh effort 레벨이 추가되었습니다. xhigh는 high와 max 사이 단계이며 /effort, --effort, 모델 피커에서 선택합니다. (v2.1.111)
Opus 4.6 1M 컨텍스트 기본: Max, Team, Enterprise 플랜에서 Opus 4.6의 1M 컨텍스트 윈도우가 기본 활성화됩니다. (v2.1.75)
Sonnet 4.6이 2026-02-17에 출시되었으며, Sonnet 4.5 사용자는 자동으로 Sonnet 4.6으로 마이그레이션됩니다. (v2.1.69)
Opus 4, 4.1은 first-party API에서 제거되었으며, Opus 4.6으로 자동 마이그레이션됩니다. (v2.1.68)
Bedrock, Vertex, Microsoft Foundry의 기본 Opus 모델도 Opus 4.6으로 변경되었습니다. (v2.1.73)
modelOverrides 설정으로 모델 피커 항목을 커스텀 프로바이더 모델 ID에 매핑할 수 있습니다 (예: Bedrock 추론 프로필 ARN). (v2.1.73)
/model 피커가 raw 모델 ID 대신 읽기 좋은 라벨(예: "Sonnet 4.5" → "Sonnet 4.6")을 표시하며, 새 버전이 있으면 업그레이드 힌트를 보여줍니다. (v2.1.51)
Opus 4.6의 기본 최대 출력 토큰이 64k로 증가했습니다(상한 128k). (v2.1.77)
ANTHROPIC_CUSTOM_MODEL_OPTION 환경변수로 /model 피커에 커스텀 모델 항목을 추가할 수 있습니다. (v2.1.78)

추론 강도(Effort) 조절

/effort 명령으로 추론 강도를 조절할 수 있습니다: low (○), medium (◐), high (●) (v2.1.72)
Opus 4.7에서는 xhigh가 추가되며, max는 세션 한정으로 노출될 수 있습니다. 사용 가능한 레벨은 모델마다 다릅니다. (v2.1.111, 공식 commands 기준)
"ultrathink" 키워드를 입력하면 다음 턴에 high effort가 활성화됩니다. (v2.1.68)
/effort 명령에서 "auto"가 현재 어떤 값으로 해석되는지 표시됩니다. (v2.1.80)
/effort를 인수 없이 실행하면 인터랙티브 슬라이더가 열려 화살표 키로 레벨을 바꾸고 Enter로 확정합니다. (v2.1.111)
스킬과 슬래시 커맨드의 frontmatter에 effort 필드를 지정해 effort 레벨을 오버라이드할 수 있습니다. (v2.1.80)

퍼미션 모드 이해

모드	동작
`default`	도구 최초 사용 시 승인 요청
`acceptEdits`	파일 편집 승인 자동화
`plan`	분석만 가능, 수정/명령 실행 불가
`auto`	AI 분류기가 위험도를 판단해 안전한 작업은 자동 진행, 위험한 작업은 차단 (2026-03-24)
`bypassPermissions`	모든 승인 생략 (격리 환경에서만 사용 권장)

Auto 모드 (2026-03-24)

OS 수준 샌드박스와 결합된 다층 방어 구조
거부된 명령은 /permissions → Recent 탭에 기록되고, r로 재시도 가능 (v2.1.89)
PermissionDenied 훅으로 거부 이벤트를 커스텀 처리 가능 (v2.1.88)
최신 릴리스 기준으로 Max 사용자는 Opus 4.7 세션에서 Auto 모드 접근이 단순화되었고, 더 이상 --enable-auto-mode 플래그가 필요하지 않습니다. (v2.1.111)

claude --permission-mode auto

{
  "sandbox": {
    "failIfUnavailable": true
  }
}

`sandbox.network.deniedDomains` (v2.1.113)

{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["uploads.github.com"]
    }
  }
}

배포/CI 환경에서 넓은 네트워크 허용이 필요하지만 업로드·외부 전송 엔드포인트만 막고 싶을 때 유용합니다.
공식 설정 문서 기준으로 deniedDomains는 allowManagedDomainsOnly와 무관하게 모든 settings source에서 병합됩니다.

서브프로세스 환경 정리 (v2.1.83)

상태 표시줄 커스터마이징

/statusline 명령으로 커스텀 상태 표시줄을 설정할 수 있습니다. 설정 파일에 statusLine을 직접 추가하는 방식도 지원됩니다.

statusline 스크립트에서 rate_limits 필드를 사용해 5시간/7일 윈도우의 rate limit 사용량(used_percentage, resets_at)을 표시할 수 있습니다. (v2.1.80)

Claude 요금제(개인/팀): https://claude.com/ko-kr/pricing (한국어)
설치/업데이트: https://code.claude.com/docs/ko/setup (한국어)
설정 파일과 /config: https://code.claude.com/docs/ko/settings (한국어)
/statusline 설정: https://docs.claude.com/ko/docs/claude-code/statusline (한국어)
/model 명령: https://code.claude.com/docs/ko/slash-commands (한국어)
Max 플랜(Claude Code 포함): https://support.claude.com/en/articles/11049741-what-is-the-max-plan (영어)
퍼미션 모드: https://docs.claude.com/en/docs/claude-code/team (영어)

Ch1. 플랜 & 환경 설정

목차

Ch1. 플랜 & 환경 설정

목차