권한 모드 선택하기

권한 모드 선택하기 (Choose a permission mode)

권한 모드는 세션에서 Claude가 먼저 묻지 않고 취할 수 있는 동작을 정해요. Manual 모드에서는 파일을 편집하거나 셸 명령을 실행하거나 네트워크에 닿는 대부분의 동작 전에 Claude Code가 멈추고 물어봅니다. CLI에서 Shift+Tab, VS Code의 모드 표시기, 데스크톱의 모드 선택기로 권한 모드를 바꿀 수 있어요.

출처: 공식문서

본문

권한 모드는 세션에서 Claude가 먼저 묻지 않고 취할 수 있는 동작을 정합니다. Manual 모드에서는 파일을 편집하거나 셸 명령을 실행하거나 네트워크에 닿는 대부분의 동작 전에 Claude Code가 멈추고 묻습니다. auto 모드에서는 분류기(classifier)라는 두 번째 모델이 당신 대신 동작을 리뷰합니다. 분류기가 동작을 평가하는 방식이 어떤 동작을 리뷰하고 어떤 것을 건너뛰는지 나열합니다.

Pro, Max, Team 플랜에서 내장 시작 권한 모드는 auto 모드입니다. 세션이 어떤 모드로 시작하는지가 시작 권한 모드를 바꾸는 표면과 설정을 다룹니다. 실행 중인 세션의 권한 모드를 언제든 바꿀 수도 있습니다.

사용 가능한 모드 (Available modes)

각 모드는 편의와 감독 사이에 다른 트레이드오프를 만듭니다. 아래 표는 각 모드에서 Claude가 권한 프롬프트 없이 할 수 있는 것을 보여줍니다. Manual 모드는 그 설정 값인 default 아래에 나타납니다.

모드 물어보지 않고 실행되는 것 가장 좋은 경우
default 읽기만 모든 동작을 직접 리뷰하기, 민감한 작업
acceptEdits 읽기, 파일 편집, 흔한 파일시스템 명령(mkdir, touch, mv, cp 등) 리뷰하는 코드를 반복 작업
plan 읽기, 더하기 auto 모드가 가능할 때 분류기 승인 명령 변경 전에 코드베이스 탐색
auto 백그라운드 안전 검사와 함께 전부 긴 작업, 프롬프트 피로 줄이기
dontAsk 읽기와 사전 승인 도구. 프롬프트를 낼 것은 거부 잠긴 CI·스크립트
bypassPermissions 전부 격리된 컨테이너·VM에서만

모든 동작을 리뷰하는 모드의 이름은 CLI, claude --help, VS Code·JetBrains 확장, 데스크톱 앱에서 Manual입니다. 그 설정 값은 default이며 hooks·SDK 통합이 쓰는 값입니다. CLI는 값을 입력하는 어디서든 manual 별칭을 받습니다. 예: claude --permission-mode manual 또는 "defaultMode": "manual". Manual 라벨과 manual 별칭은 Claude Code v2.1.200 이상이 필요합니다. 데스크톱 앱의 라벨은 CLI 버전에 의존하지 않습니다.

보호 경로에 대한 쓰기는 bypassPermissions 모드와, 바이패스 권한이 가능한 plan 모드 세션에서만 자동 승인됩니다. 즉 권한 모드 사이클에 bypassPermissions를 넣는 방식으로 시작한 세션을 뜻합니다.

모드는 기준선을 정합니다. 그 위에 권한 규칙을 얹어 특정 도구를 사전 승인하거나 차단하세요. 거부(deny) 규칙은 bypassPermissions를 포함한 모든 모드에서 차단합니다. 거부·물어보기(ask) 규칙은 Claude가 아직 호출할 수 있는 다른 도구가 하나 이상 있는 한 EndConversation에는 적용되지 않습니다. 허용(allow) 규칙은 bypassPermissions에서 효력이 없습니다.

어떤 모드도 자동 승인하지 않는 동작 (Actions no mode auto-approves)

Claude Code는 bypassPermissions를 포함한 어떤 모드에서도 다음을 자동 승인하지 않습니다. 각 글머리는 각 모드에서 대신 무슨 일이 일어나는지 설명하는 섹션으로 연결됩니다.

일반적인 설정 (Common setups)

권한 모드는 동작 전에 Claude가 물을지 결정하고, Bash 샌드박스와 바깥 격리 경계는 일단 실행되면 동작이 닿을 수 있는 범위를 결정합니다. 아래 각 행은 목표를 거기에 이르는 플래그·설정과 필요한 격리와 짝지은 시작점입니다. 사용 가능한 모드가 각 모드에서 프롬프트 없이 실행되는 것을 나열합니다.

원하는 것 시작 필요한 격리 참고
모든 동작을 직접 리뷰 Manual 모드: claude --permission-mode default 없음 민감한 작업, 낯선 코드
프롬프트를 줄이고 분류기 없이 로컬 반복 Manual 모드 + auto-allow 모드의 Bash 샌드박스: claude --permission-mode default, 그다음 /sandbox 실행 후 auto-allow 선택 내장 Bash 샌드박스, macOS·Linux·WSL2 거부 규칙은 여전히 적용되고 Bash(git push *)처럼 명령을 이름으로 쓰는 ask 규칙도 여전히 프롬프트. 설정 파일에서 샌드박스를 켜려면 sandbox.enabled를 true로 설정
변경 전에 탐색 claude --permission-mode plan 없음 Claude Code는 계획을 승인할 때까지 편집 차단
auto 모드에서 손놓고 작업 claude --permission-mode auto, Pro·Max·Team의 내장 시작 권한 모드 없음. 샌드박스나 컨테이너가 심층 방어를 더함 지원 모델 필요, 조직이 auto 모드를 끌 수 있음
정확한 허용 목록으로 CI 실행 claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read" CI 러너가 주는 것 너머 없음 웹의 Claude Code는 설정 파일의 dontAsk를 무시
컨테이너 안에서 완전 무인 실행 claude -p "<prompt>" --dangerously-skip-permissions 필수: 컨테이너, VM, 샌드박스 런타임. Linux·macOS에선 비루트 사용자로 실행 웹의 Claude Code는 설정 파일에서 이 모드를 무시. 이 -p 실행에서는 여전히 프롬프트를 낼 소수의 호출이 대신 거부됨

Bash 샌드박스와 auto 모드는 독립적으로 작동하며 결합됩니다. 단 plan 모드에서는 auto-allow가 승인을 넓히지 않습니다. 전체 상호작용은 샌드박싱이 권한·권한 모드와 관련되는 방식과 격리가 권한 모드와 관련되는 방식을 참고하세요.

세션이 어떤 모드로 시작하는지 (Which mode a session starts in)

터미널에서 새 세션을 시작하면 Claude Code는 다음 중 처음 적용되는 것에서 권한 모드를 가져옵니다.

  1. --permission-mode 플래그 또는 --dangerously-skip-permissions

  2. 설정 파일의 permissions.defaultMode

    .claude/settings.json이나 .claude/settings.local.json에 "auto"를 설정하면 값이 효력없고, Claude Code는 ~/.claude/settings.json의 defaultMode 대신 내장 기본값을 씁니다. 그 두 파일에 "bypassPermissions"를 설정해도 효력없고 세션은 Manual 모드로 시작합니다. 다른 값은 어떤 설정 파일에서든 적용됩니다.

  3. 내장 기본값

VS Code 확장이 시작하는 대화는 권한 모드 전환의 확장 자체 목록을 따릅니다. Claude Code가 재개한 세션을 시작하는 권한 모드는 재개 시 권한 모드를 참고하세요.

내장 auto 기본값은 macOS, Linux, WSL에서 Claude Code v2.1.228 이상, 네이티브 Windows에서 v2.1.233 이상이 필요합니다. 이전 버전에서 내장 기본값은 Manual입니다.

내장 기본값은 Claude Code를 어떻게 실행하는지, 플랜, 기능 플래그를 가져올 수 있었는지에 따라 달라집니다. 세션과 일치하는 첫 행이 적용됩니다. 표는 터미널이나 VS Code 확장으로 시작한 세션을 다룹니다. 데스크톱 앱과 claude.ai는 권한 모드 전환의 Desktop·Web 탭을 참고하세요.

Claude Code 실행 방식 내장 시작 권한 모드
어떤 설정 파일이 disableAutoMode를 "disable"로 설정 default
기능 플래그 가져오기 꺼짐 default
이 기본값을 추가하는 버전으로 설치·업그레이드 후 첫 세션 (새 설치 후 Claude Code가 제때 플래그를 가져오는 경우 제외) default
claude -p 또는 Agent SDK default
Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude Platform on AWS, 또는 로그인한 Claude apps gateway 세션 default
터미널 또는 VS Code 확장의 Pro, Max, Team 플랜 auto
Enterprise 플랜 또는 Claude Console API 키 default

기능 플래그 가져오기가 꺼져 있거나 설치·업그레이드 후 첫 세션에서 플래그가 아직 도착하지 않았다면, VS Code 확장은 시작 권한 모드를 고를 때 모든 설정 파일을 무시합니다.

플래그, 설정 파일, 내장 기본값이 auto를 선택했지만 세션에서 auto 모드를 쓸 수 없다면 Claude Code는 대신 Manual로 세션을 시작합니다. auto 모드는 세션이 가용성 요구사항을 충족하지 못할 때(설정 파일이 끄거나 모델이 지원하지 않는 경우, Anthropic이 서버 측에서 일시적으로 끈 경우) 쓸 수 없습니다.

내장 기본값이 세션 중 하나를 auto 모드로 처음 시작하면 Claude Code가 이 페이지로 연결되는 안내를 보여줍니다.

  • 터미널에서는 세션 맨 위에 한 번
  • VS Code 확장에서는 없앨 때까지 새 대화 화면의 카드로

Pro, Max, Team 플랜에서 ~/.claude/settings.json이 auto가 아닌 defaultMode를 설정하고 다른 설정 파일이 설정하지 않았다면 세션은 그 모드로 계속 시작합니다. Claude Code가 터미널이나 VS Code 확장에서 설정을 auto 모드로 바꿀지 한 번 물어봅니다. 거절하면 설정이 그대로 유지됩니다.

다른 권한 모드로 시작 (Start in a different permission mode)

한 세션의 시작 권한 모드를, 또는 머신·프로젝트·조직의 모든 세션 기본값으로 설정할 수 있습니다. 둘 이상의 설정 파일이 permissions.defaultMode를 설정하면 설정 우선순위가 결정하므로 프로젝트나 관리 값이 ~/.claude/settings.json보다 위입니다. 이미 실행 중인 세션의 권한 모드를 바꾸려면 권한 모드 전환을 참고하세요.

시작 권한 모드를 설정할 대상 하는 일
막 시작할 한 세션 권한 모드를 플래그로 전달. 예: claude --permission-mode default
이 머신에서 시작하는 모든 터미널 세션 ~/.claude/settings.json에 permissions.defaultMode 설정. VS Code 확장이 읽는 것은 권한 모드 전환 참고
한 프로젝트에서 시작하는 모든 터미널 세션 프로젝트의 .claude/settings.json에 permissions.defaultMode 설정. 터미널에서 시작한 세션은 auto·bypassPermissions를 제외한 모든 값을 존중. VS Code 확장이 시작한 세션은 시작 권한 모드에 프로젝트 설정을 읽지 않음
조직의 모든 터미널 세션 관리 설정에 permissions.defaultMode 설정. 터미널 세션은 그 모드로 시작하고 사람들은 여전히 auto 모드로 전환 가능. VS Code 확장이 읽는 것은 권한 모드 전환 참고. 아무도 선택할 수 없게 auto 모드를 제거하려면 permissions.disableAutoMode를 "disable"로 설정

다음 예시는 머신의 모든 터미널 세션을 Manual 모드(설정 값 default)로 시작하게 합니다. ~/.claude/settings.json에 저장하세요.

{
  "permissions": {
    "defaultMode": "default"
  }
}

다음에 시작하는 세션은 상태 바에 ⏸ manual mode on을 표시합니다.

권한 모드 전환 (Switch permission modes)

각 인터페이스는 세션 중 권한 모드를 바꾸는 자체 제어와 새 세션이 시작하는 권한 모드를 고르는 자체 방식을 가집니다. 인터페이스를 선택해 제어를 보세요.

CLI — 세션 중: Shift+Tab을 눌러 권한 모드를 순환합니다. auto에서 첫 번째 누름은 default로 전환되고, 순환은 default → acceptEdits → plan → default로 돌아갑니다. 선택적 모드(아래 설명)는 plan 뒤에 끼어듭니다. 상태 바는 활성 모드를 default의 경우 회색 ⏸ manual mode on, 또는 ⏵⏵ accept edits on, ⏸ plan mode on, ⏵⏵ auto mode on, ⏵⏵ don't ask on, ⏵⏵ bypass permissions on으로 표시합니다.

모든 모드가 기본 순환에 있는 것은 아닙니다.

  • auto: auto 모드가 가능할 때 나타나며, 순환해 들어가면 확인 프롬프트 없이 권한 모드를 전환
  • bypassPermissions: --permission-mode bypassPermissions, --dangerously-skip-permissions, --allow-dangerously-skip-permissions, 또는 user, --settings, managed 설정의 permissions.defaultMode: "bypassPermissions"로 시작한 뒤 나타남. --allow- 변형은 활성화하지 않고 권한 모드를 순환에 추가
  • dontAsk: 순환에 절대 나타나지 않음. --permission-mode dontAsk로 설정

활성화된 선택적 모드는 plan 뒤에 끼어듭니다. bypassPermissions가 먼저, auto가 마지막입니다. 둘 다 활성화했다면 auto로 가는 길에 bypassPermissions를 통과해 순환합니다.

Bash 권한 프롬프트에서: Manual과 acceptEdits 권한 모드에서 auto 모드가 가능하면 Claude Code가 Bash 명령의 권한 프롬프트에 Yes, and switch to auto mode를 추가합니다. 선택하면 명령을 승인하고 세션을 auto 모드로 전환합니다. PowerShell 도구 프롬프트는 그 옵션을 제공하지 않습니다. Claude Code v2.1.247 이상 필요.

Claude Code는 ask 규칙 중 하나나 hook이 강제한 프롬프트에는 그 옵션을 추가하지 않습니다. auto 모드도 그 프롬프트를 여전히 보여주므로, 전환해도 제거되지 않기 때문입니다.

시작 시: 권한 모드를 플래그로 전달하세요.

claude --permission-mode plan

기본값으로: 다른 권한 모드로 시작에서 설명한 대로 원하는 범위에 permissions.defaultMode를 설정하세요.

같은 --permission-mode 플래그는 비인터랙티브 실행의 -p에서도 동작합니다.

VS Code — 세션 중: 프롬프트 상자의 아래쪽 모드 표시기를 클릭하세요. 이 페이지의 모드에 이 라벨을 씁니다.

UI 라벨 모드
Manual default
Edit automatically acceptEdits
Plan plan
Auto auto
Bypass permissions bypassPermissions

기본값으로: 대화가 시작하는 권한 모드를 고정하려면 VS Code 사용자 설정에서 claudeCode.initialPermissionMode를 default, manual, acceptEdits, plan, bypassPermissions 중 하나로 설정하세요. 이 설정은 auto를 받지 않습니다. Auto로 시작하려면 설정을 비워 두고 아래 item 2처럼 모드 표시기에서 Auto를 한 번 고르세요. 확장은 각 새 대화를 다음 중 처음 적용되는 것으로 시작합니다.

  1. claudeCode.initialPermissionMode
  2. 모드 표시기에서 마지막으로 고른 모드(Manual, Edit automatically, Auto였다면). Plan이나 Bypass permissions를 고르면 그 대화에만 적용
  3. 관리 설정 또는 ~/.claude/settings.json의 permissions.defaultMode(기능 플래그 가져오기 가능한 Pro, Max, Team 플랜에서)
  4. 플랜·제공자·조직 설정의 내장 기본값

확장은 시작 권한 모드에 프로젝트의 .claude/settings.json이나 .claude/settings.local.json을 절대 읽지 않고, item 3 조건을 충족하지 않는 대화에서는 어떤 설정 파일도 읽지 않습니다. claudeCode.claudeProcessWrapper가 설정되면 item 3과 4도 적용되지 않습니다. 그 대화는 item 1이나 item 2가 권한 모드를 정하지 않으면 Manual로 시작합니다.

Auto는 auto 모드가 가능할 때 모드 표시기에 나타납니다.

Bypass permissions는 확장 설정의 Allow dangerously skip permissions 토글이 필요합니다. 없으면 권한 모드가 표시기에 나타나지 않고, item 1이나 item 3의 bypassPermissions 값은 대화를 대신 Manual로 시작합니다. auto 모드가 없을 때 어느 item의 Auto도 마찬가지로 대화를 Manual로 시작합니다.

확장별 상세는 VS Code 가이드를 참고하세요.

JetBrains — JetBrains 플러그인은 IDE 터미널에서 Claude Code를 실행하므로 권한 모드 전환이 CLI와 동일합니다. Shift+Tab으로 순환하거나 실행 시 --permission-mode를 전달하세요.

Desktop — 세션 중: Code 탭에서 보내기 버튼 옆의 모드 선택기를 사용하세요. 모든 모드가 선택기에 나타나는 것은 아닙니다.

  • Auto: auto 모드가 가능할 때 나타남
  • Bypass permissions: Pro·Max 플랜에서 Desktop 설정의 Allow bypass permissions mode 토글이 필요. Team·Enterprise 플랜에서는 조직 정책이 대신 제어

Cowork 탭은 이 모드를 쓰지 않습니다. Cowork는 별도로 활성화되는 고유 권한 모드를 가지며, 기본 너머의 모드가 계정에 활성화되기 전까지 Cowork 탭에는 모드 선택기가 전혀 없습니다. Cowork 문서 참고.

데스크톱별 상세는 Desktop 가이드의 권한 모드 선택을 참고하세요.

기본값으로: 설정에 defaultMode를 설정하세요. 데스크톱 앱은 CLI와 같은 설정 파일을 읽고 새 로컬 세션에 권한 모드를 적용합니다.

모드 선택기에서 고른 모드는 폴더별로 기억되며 그 폴더의 defaultMode보다 우선합니다. Plan이 예외입니다. 고르면 현재 세션에만 적용됩니다.

defaultMode가 설정 파일 어디에 가는지는 다른 권한 모드로 시작의 예시를 참고하세요.

Web과 mobile — claude.ai/code이나 모바일 앱의 프롬프트 상자 옆 모드 드롭다운을 사용하세요. 권한 프롬프트가 승인용으로 claude.ai에 나타납니다. 어떤 모드가 나타나는지는 세션이 어디서 실행되는지에 달려 있습니다.

  • 웹의 Claude Code의 클라우드 세션: Accept edits, Plan, Auto. Accept edits는 default 모드에 해당합니다. 클라우드 세션은 모드와 무관하게 파일 편집을 사전 승인하므로 드롭다운이 Manual 대신 Accept edits를 보여줍니다. 클라우드 세션은 설정의 defaultMode: "acceptEdits"도 존중합니다. Auto 모드는 조직이 허용하고 선택한 모델이 지원할 때만 나타납니다. Bypass permissions는 사용할 수 없습니다.
  • 로컬 머신의 Remote Control 세션: Manual, Accept edits, Plan. 앱에서 Auto나 Bypass permissions를 선택할 수 없습니다.
    • Bypass permissions를 제외하고, 드롭다운은 로컬 세션이 있는 권한 모드를 보여줍니다(터미널에서 설정한 것 포함). 앱이나 터미널에서 권한 모드가 바뀌면 갱신됩니다. 세션은 claude.ai에 Bypass permissions를 절대 보고하지 않으므로 터미널에서 그 모드로 전환해도 드롭다운 표시가 바뀌지 않습니다.
    • 데스크톱 앱이나 VS Code 확장이 호스팅하는 세션은 터미널에서 호스팅하는 세션과 마찬가지로 권한 모드 변경이 일어나면 claude.ai에 보고합니다.
    • v2.1.202 이전에는 /remote-control이나 claude --remote-control로 연결한 세션이 권한 모드를 전혀 보고하지 않아 claude.ai와 모바일 앱이 세션이 아닌 권한 모드를 보여줄 수 있었습니다. 불일치는 라벨에만 영향이 있었습니다. Claude Code는 세션의 실제 권한 모드에서 권한 프롬프트를 생성했고 그것은 여전히 앱에 나타나 승인됐습니다.

Remote Control의 경우 세션을 실행하는 로컬 머신이 claude.ai 계정으로 로그인해야 합니다. API 키는 지원되지 않습니다. 그 로컬 세션을 실행할 때 시작 권한 모드를 설정할 수도 있습니다.

claude remote-control --permission-mode acceptEdits

acceptEdits 모드로 파일 편집 자동 승인 (Auto-approve file edits with acceptEdits mode)

acceptEdits 모드는 Claude가 작업 디렉토리에서 프롬프트 없이 파일을 만들고 편집하게 합니다. 이 모드가 활성화된 동안 상태 바는 ⏵⏵ accept edits on을 표시합니다.

파일 편집 외에 acceptEdits 모드는 흔한 파일시스템 Bash 명령을 자동 승인합니다. mkdir, touch, rm, rmdir, mv, cp, sed입니다. 이 명령들은 LANG=C·NO_COLOR=1 같은 안전한 환경 변수나 timeout·nice·nohup 같은 프로세스 래퍼가 접두사일 때도 자동 승인됩니다. 파일 편집처럼 자동 승인은 작업 디렉토리나 additionalDirectories 안 경로에만 적용됩니다. 그 범위 밖 경로, 보호 경로 쓰기, 중요 경로를 대상으로 하는 rm·rmdir 제거, 내장 읽기 전용 집합을 제외한 다른 모든 Bash 명령은 여전히 프롬프트를 냅니다.

PowerShell 도구가 활성화되면 acceptEdits 모드는 범위 안 경로의 Set-Content, Add-Content, Clear-Content, Remove-Item과 그 흔한 별칭도 자동 승인합니다. 같은 범위·보호 경로 규칙이 적용되고 Remove-Item은 자체 검사를 받습니다. Set-Content .\notes.txt "It's done"의 아포스트로피처럼 따옴표 문자를 포함한 위치 인자는 범위 안 경로에서도 여전히 프롬프트를 냅니다. Claude Code가 따옴표가 있는 읽기와 없는 읽기가 다른 인자를 정적으로 검증할 수 없기 때문입니다. -Value 같은 이름 있는 파라미터로 내용을 전달해 프롬프트를 피하세요.

각 편집을 인라인으로 승인하는 대신 나중에 편집기나 git diff로 변경을 리뷰하고 싶을 때 acceptEdits를 쓰세요.

Manual 모드에서 Shift+Tab을 한 번 눌러 들어가거나 바로 시작하세요.

claude --permission-mode acceptEdits

plan 모드로 편집 전 분석 (Analyze before you edit with plan mode)

Plan 모드는 Claude에게 변경을 만들지 않고 조사하고 제안하라고 지시합니다. Claude는 파일을 읽고 탐색을 위해 셸 명령을 실행하며 계획을 쓰지만 소스를 편집하지는 않습니다. 바이패스 권한이 가능한 세션을 제외하고 계획을 승인할 때까지 편집이 차단됩니다.

auto 모드가 가능하고 useAutoModeDuringPlan 설정이 켜져 있으면(기본값) 분류기가 계획 중 셸 명령을 프롬프트 대신 리뷰합니다. 승인된 명령은 실행되고 거부된 것은 차단됩니다. 그렇지 않으면 내장 읽기 전용 집합 밖 명령이, 샌드박스의 auto-allow 모드가 활성화된 경우에도 승인을 위해 프롬프트를 냅니다. 바이패스 권한이 가능한 세션에서는 분류기나 프롬프트 모두 계획 명령에 적용되지 않습니다. bypassPermissions 모드로 모든 검사 건너뛰기가 거기서 여전히 프롬프트를 내는 몇 가지를 다룹니다. v2.1.212~v2.1.217에서는 바이패스 권한이 없는 세션이 auto 모드 가능 여부와 무관하게 읽기 전용 집합 밖 모든 명령에서 프롬프트를 냈습니다.

Shift+Tab을 누르거나 단일 프롬프트를 /plan으로 접두사해 plan 모드에 들어갑니다. CLI에서 plan 모드로 시작할 수도 있습니다.

claude --permission-mode plan

계획을 승인하지 않고 plan 모드를 떠나려면 Shift+Tab을 다시 누르세요.

계획 검토·승인 (Review and approve a plan)

계획이 준비되면 Claude는 그것을 제시하고 진행 방법을 묻습니다. 그 프롬프트에서 고를 수 있는 것:

  • Yes, and use auto mode: 승인하고 auto 모드로 시작. auto 모드가 없으면 옵션이 Yes, auto-accept edits로 읽힘. 바이패스 권한을 켜고 세션을 시작했다면 옵션이 Yes, and switch to BYPASS PERMISSIONS (no further prompts) for this session으로 읽힘.
  • Yes, manually approve edits: 승인하고 각 편집을 개별적으로 리뷰.
  • No, keep planning: plan 모드에 머물며 Claude에게 무엇을 바꿀지 말함.

계획을 승인하면 plan 모드를 나가고 세션이 각 승인 옵션이 설명하는 권한 모드로 전환되어 Claude가 편집을 시작합니다. 다시 계획하려면 Shift+Tab으로 plan 모드로 순환하거나 다음 프롬프트를 /plan으로 접두사하세요.

Ctrl+G를 누르면 제안된 계획을 기본 텍스트 편집기로 열고 Claude가 진행하기 전에 직접 편집할 수 있습니다. showClearContextOnPlanAccept가 활성화되면 목록에 첫 옵션이 추가되어 계획을 승인하고 계획 컨텍스트를 지웁니다.

계획을 수락하면 세션에 계획에 기반한 생성된 제목도 주어집니다. 세션 이름을 이미 정하지 않은 경우입니다.

plan 모드를 기본값으로 설정 (Set plan mode as the default)

프로젝트의 터미널 세션에 plan 모드를 기본으로 만들려면 다른 권한 모드로 시작의 예시가 보여주는 것처럼 .claude/settings.json에 defaultMode를 plan으로 설정하세요. VS Code 확장이 시작하는 대화는 시작 권한 모드에 프로젝트 설정을 읽지 않습니다. 거기서는 VS Code 사용자 설정의 claudeCode.initialPermissionMode를 plan으로 설정하세요.

auto 모드로 권한 프롬프트 없애기 (Eliminate permission prompts with auto mode)

Auto 모드는 Claude가 일상적인 권한 프롬프트 없이 실행하게 합니다. 별도의 분류기 모델이 동작이 실행되기 전에 리뷰하며, 요청을 넘어서는 확대, 인식되지 않는 인프라 대상, Claude가 읽은 적대적 콘텐츠로 보이는 것을 차단합니다. 명시적 ask 규칙은 여전히 프롬프트를 강제합니다.

Pro, Max, Team 플랜에서 auto 모드는 내장 시작 권한 모드입니다.

분류기는 Claude가 SendMessage로 다른 에이전트에게 보내는 각 메시지도(평문이든 구조화된 에이전트 팀 메시지든) Claude Code가 전달하기 전에, auto 모드와 분류기가 명령을 리뷰하는 plan 모드 모두에서 리뷰합니다. 이 보내기 리뷰는 Claude Code v2.1.222 이상이 필요합니다.

분류기는 중요 경로를 대상으로 하는 rm·rmdir 제거(rm -rf /, rm -rf ~ 등)도, 명령·프로세스 치환 안에 있어도 리뷰하고 승인하거나 차단합니다.

Auto 모드는 또한 Claude가 명확화 질문을 위해 멈추지 않고 계속 작업하도록 유도합니다. 그래도 프롬프트나 스킬이 명시적으로 의존하면 Claude는 여전히 묻습니다. 여전히 프롬프트를 내는 모드에서 더 강한 자율 동작을 원하면 Proactive 출력 스타일을 설정하세요.

Auto 모드는 권한 프롬프트를 줄이지만 안전을 보장하지는 않습니다. 일반 방향을 신뢰하는 작업에 쓰고, 민감한 작업에서 리뷰를 대체하지 마세요.

Auto 모드는 계정이 다음 요구사항을 모두 충족할 때만 사용할 수 있습니다.

  • 플랜: 모든 플랜.
  • 조직: Team·Enterprise에서 auto 모드는 기본적으로 가능합니다. 관리자는 관리 설정에서 permissions.disableAutoMode를 "disable"로 설정해 조직에 대해 끌 수 있습니다.
  • 모델: Anthropic API와 Claude Platform on AWS에서는 Claude Opus 4.6 이상, Sonnet 4.6 이상, Fable 모델. Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, 로그인한 Claude apps gateway 세션에서는 Claude Sonnet 5, Opus 4.7 이상, Fable 모델만. Sonnet 4.5, Opus 4.5, Haiku, claude-3 모델 같은 오래된 모델은 어떤 제공자에서도 지원되지 않습니다.
  • 제공자: Anthropic API, Claude Platform on AWS, Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, 로그인한 Claude apps gateway 세션에서 기본적으로 가능.

Claude Code가 auto 모드가 불가능하다고 보고하면 먼저 이 요구사항과 어떤 설정 파일이 disableAutoMode를 설정하는지 확인하세요. Anthropic이 서버 측에서 auto 모드를 껐거나 서버가 계정에 auto 모드를 거부했을 수도 있습니다. 두 응답 중 하나를 받은 세션은 세션이 끝날 때까지 auto 모드를 끈 채 유지하므로 나중에 새 세션을 시작하세요.

모델 이름을 정하고 auto 모드가 동작의 "안전을 판단할 수 없다"고 말하는 별도 메시지는 분류기 요청이 실패했음을 뜻합니다. 그 실패는 보통 일시적이지만 Amazon Bedrock에서는 계정이 이름 붙은 모델을 호출할 수 있을 때까지 반복될 수 있습니다. 원인과 할 일은 오류 레퍼런스를 참고하세요.

설정에 defaultMode: "auto"를 설정했는데 터미널 세션이 오류 없이 Manual로 시작한다면, 설정이 .claude/settings.json이나 .claude/settings.local.json에 있을 가능성이 높습니다. auto는 그 파일들에서 효력이 없습니다. ~/.claude/settings.json으로 옮기세요. VS Code 확장이 시작한 대화는 권한 모드 전환의 확장 자체 목록을 확인하세요.

Bedrock, Agent Platform, Foundry에서 auto 모드 (Auto mode on Bedrock, Agent Platform, or Foundry)

Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, 로그인한 Claude apps gateway 세션에서 auto 모드는 기본적으로 Shift+Tab 순환에 나타납니다. 순환에 나타나는 것은 세션이 시작하는 권한 모드를 바꾸지 않습니다. 이 제공자에서 터미널 세션은 defaultMode로 시작하고, 바꾸지 않으면 Manual이며, VS Code 확장의 대화는 claudeCode.initialPermissionMode나 확장에서 고른 모드가 설정하지 않으면 Manual로 시작합니다. 이 제공자에서는 Claude Sonnet 5, Opus 4.7 이상, Fable 모델만 지원됩니다.

auto 모드를 기본 시작 권한 모드로 만들려면 user 또는 managed 설정에 "permissions": {"defaultMode": "auto"}를 설정하세요. VS Code 확장이 시작하는 세션에서는 모드 표시기에서 Auto를 선택하세요. 권한 모드 전환이 무엇이 그 선택보다 위인지 다룹니다.

/doctor 체크업은 이 제공자에서도 Anthropic API에서와 같은 방식으로 이 user 설정 기본값을 제안합니다.

개발자가 auto 모드를 쓰지 못하게 하려면 관리 설정에서 disableAutoMode를 "disable"로 설정하세요. 이는 Shift+Tab 순환에서 auto를 제거하고, --permission-mode auto로 시작한 세션은 대신 Manual로 시작합니다. 이미 auto 모드로 실행 중인 세션은 관리 배포 소스에서 그 설정이 세션에 닿으면 auto 모드를 떠나고 auto mode disabled by settings를 표시합니다. v2.1.251 이전에는 실행 중인 세션이 끝날 때까지 auto 모드를 유지했습니다.

v2.1.158~v2.1.206에서는 이 제공자에서 CLAUDE_CODE_ENABLE_AUTO_MODE=1을 설정하기 전까지 auto 모드가 꺼져 있었고, 변수도 설정하지 않으면 이 제공자에서 defaultMode: "auto"를 무시했습니다. 변수는 호환성을 위해 여전히 받아들여지며 v2.1.207부터는 효과가 없습니다.

분류기가 기본으로 차단하는 것 (What the classifier blocks by default)

분류기는 작업 디렉토리와 세션 시작 시 그것을 위해 구성된 리모트를 신뢰합니다. 세션 중 git remote add나 git remote set-url로 추가·변경된 리모트는 신뢰되지 않고, 신뢰 인프라를 구성할 때까지 다른 모든 것은 외부로 취급됩니다. v2.1.200 이전에는 세션 중간에 추가된 리모트도 신뢰됐습니다.

기본적으로 차단되는 것:

  • curl | bash 같은 코드 다운로드·실행
  • 민감한 데이터를 외부 엔드포인트로 전송
  • 프로덕션 배포·마이그레이션
  • 클라우드 스토리지 대량 삭제
  • IAM 또는 리포지토리 권한 부여
  • 공유 인프라 수정
  • 세션 전에 존재하던 파일의 비가역적 파괴
  • Force push
  • 실행 시 시크릿이나 민감한 데이터를 리포지토리 밖으로 보내거나 배포가 노출하는 것을 넓히는 변경의 커밋·푸시. 이는 아직 받지 않는 대상에 시크릿을 넘기는 CI 워크플로우·배포 구성, 시크릿 저장소를 읽고 데이터를 내보내는 스크립트·설정 단계, 레지스트리·가시성·아티팩트·소스맵 설정처럼 배포가 게시하는 것을 넓히는 구성 변경을 다룹니다. 이 검사는 어떤 브랜치에서든 적용되고 리포지토리가 공개여도 적용되며, 착륙이 파이프라인을 트리거하는지와 무관하게 변경이 착륙할 때 발화합니다. 해제하려면 커밋·푸시만이 아니라 실행 효과를 이름으로 정해야 합니다. v2.1.211 이전에는 이 검사가 기본 브랜치로 한정됐습니다. 거기 푸시는 민감한 내용을 실었거나, 요청한 것에 비해 숨기거나 오설명하는 변경, 리포지토리 밖에서 들여온 내용, 요청한 리뷰를 우회한 경우 차단됐습니다.
  • 커밋되지 않은 변경을 버린다고 분류기가 가정하는 git reset --hard, git checkout -- ., git restore ., git clean -fd, git stash drop, git stash clear
  • HEAD의 커밋이 이 세션에서 만들어지지 않았을 때의 git commit --amend
  • v2.1.198부터, HEAD의 커밋이 이미 푸시됐을 때의 git commit --amend. 새로 스테이지된 것이 없는 --amend -m의 메시지만 개정은 차단되지 않습니다.
  • terraform destroy, pulumi destroy, cdk destroy, terragrunt destroy와 리소스를 파괴하는 플랜 적용

Claude Code v2.1.195 이상이 기본으로 더 많은 범주를 차단합니다. 여러 개는 환경 항목에 의존합니다(민감한 리모트 대상, 보호된 IaC 범위 등). 구체적 이름으로 좁힐 수 있습니다.

  • 시크릿 매니저에 쓰기, 또는 DNS 레코드·TLS 인증서 변경
  • 사람이 승인하지 않은 풀 리퀘스트 머지, Claude 자신의 풀 리퀘스트 승인, CI 검사 비활성화
  • atlantis apply나 봇의 /deploy·/merge처럼 그 자체가 자동화에 대한 명령인 댓글 게시
  • 프로덕션 기능 플래그 토글·램프·삭제
  • 보호된 IaC 범위에 인프라 변경 적용, 클러스터 노드 드레이닝·제거
  • 다른 사용자의 잡을 잡는 라벨 선택기·--all처럼 이름을 정한 리소스 너머로 닿는 공유 컴퓨트 클러스터에 쓰기
  • DaemonSet·admission webhook처럼 모든 노드에서 실행되거나 클러스터 트래픽을 가로채는 Kubernetes 리소스 생성
  • 민감한 리모트 대상으로의 인터랙티브 셸·포트 포워드
  • 로컬 서비스를 공개 인터넷에서 접근 가능하게 만드는 터널·리버스 셸 열기
  • 라이브 자격 증명·토큰을 트랜스크립트나 파일에 출력
  • 환경에서 민감한 데이터 위치로 나열된 위치에 접근하거나 그곳에서 데이터 복사. v2.1.198부터 항목이 제외하는 수신자에게 데이터를 보내는 것도 차단.
  • 내부 패키지 레지스트리를 우회해 공용 레지스트리로 패키지 설치 라우팅. v2.1.198부터 대화에서 내부 레지스트리·미러가 있다고 Claude에게 말한 경우에도, 환경에 나열된 경우에만이 아니라 적용.
  • --insecure처럼 안전 가드를 해제하는 플래그로 명령 실행
  • 사람 승인이나 샌드박스 없이 실행되는 자율 에이전트 루프 시작. --dangerously-skip-permissions나 --no-sandbox로 시작한 것 같은. v2.1.198부터 격리와 동작별 승인이 비활성화된 타사 에이전트·eval 하네스(--yes-always로 시작한 러너 같은)의 실행도 포함.
  • Claude in Chrome 브라우저 동작 중 페이지 콘텐츠·쿠키·자격 증명을 off-origin으로 보낼 수 있는 것

Claude Code v2.1.198 이상은 기본으로 다음도 차단합니다.

  • /tmp, $TMPDIR, 다른 공유 스크래치·캐시 디렉토리의 파일을 특정 이름 경로가 아니라 와일드카드·glob·연령 필터로 삭제
  • 자기 메시지가 그 수신자에게 승인하지 않은 민감한 세부사항을, 리포지토리가 신뢰 경계 밖이거나 공개면(조직의 공개 리포지토리 포함) 다른 사람이나 공유 시스템으로 보내는 콘텐츠에 포함. PR·이슈 본문, 커밋 메시지, 댓글이 이 종류의 아웃바운드 콘텐츠입니다. 내부 파일 경로, 코드 이름, 이메일·계정 식별자 같은 라이브 API 응답 데이터, 인프라 식별자는 민감한 세부사항으로 간주. PR·이슈·커밋 메시지 범위는 Claude Code v2.1.200 이상 필요. 리포지토리 가시성·신뢰 경계와 무관하게 PR·이슈 본문의 API 응답 라이브 개인 데이터(이메일 주소, 계정·조직 식별자, 사용량 메트릭)는 그 세부사항과 수신자를 이름으로 정해야 함. 그 검사는 Claude Code v2.1.203 이상 필요.
  • Claude Code 자신의 tmux 패널에 키 입력을 보내 자신의 인터페이스를 구동하는 것. 분류기가 Claude가 자신의 권한·감독을 바꾸는 것으로 취급.

Claude Code v2.1.200 이상은 기본으로 다음도 차단합니다.

  • auth, 접근 제어, 입력 검증, 샌드박싱 같은 보안 동작을 지키는 테스트·단언을 주석 처리·삭제·강제 통과
  • 세션에서 Claude가 만들지 않은 상태 유지 리소스의 삭제·해체(더 구체적인 삭제 규칙이 없고 그 리소스를 이름으로 정하지 않았을 때)
  • task에 맞지 않는 타사 호스트로 API 기본 URL, 프록시 엔드포인트, 웹훅 수신자, 레지스트리 미러를 변경(.env.example 같은 예시 파일 포함)
  • 새 리모트를 이름으로 정하지 않으면 git remote set-url·git remote add로 푸시 대상 변경
  • 공개로 알려진 리포지토리에 시크릿·개인·신탁 데이터 푸시, 그 리포지토리 자체 작업이 아닌 기밀 자료를 공개 표면에 푸시. dotfiles 리포지토리 자체 주제는 개인·신탁 데이터의 유일한 예외이고, 개인 리포지토리 콘텐츠가 어떤 공개 표면에 닿는 것은 같은 방식으로 차단. 두 개선 모두 Claude Code v2.1.203 이상 필요. v2.1.203 이전에는 개인 데이터가 기밀 자료와 묶여 그 리포지토리 자체 작업이 아닌 경우에만 차단됐습니다. 리포지토리 가시성이 확립되지 않으면 분류기는 그 이유만으로 차단하지 않고 다른 규칙에 대해 콘텐츠를 판단합니다.
  • 외부 대상을 이름으로 정하지 않으면 다른 리포지토리·조직에 대한 풀 리퀘스트 열기, gh repo fork로 포킹, 타사 리포지토리로 푸시

Claude Code v2.1.203 이상은 기본으로 다음도 차단합니다.

  • 소스와 대상 모두 이름으로 정하지 않으면, 민감한 로컬 저장소 콘텐츠 또는 이름·경로·유형이 민감함을 표시하는 파일의 콘텐츠가 커밋·푸시·PR·이슈 텍스트·gist·paste·패키지 게시에 들어감. 세션 트랜스크립트·대화 로그, SSH 키·클라우드 자격 증명·브라우저 프로필·셸 기록 같은 자격 증명·구성 dot-folder, 사용자 데이터 내보내기가 모두 포함되고, 리포지토리가 비공개여도 해제되지 않습니다.

Claude Code v2.1.205 이상은 기본으로 다음도 차단합니다.

  • 셸 명령을 통해 직접이든 간접이든 Claude Code 세션 트랜스크립트, ~/.claude/projects/ 아래 .jsonl 기록 파일(또는 구성된 구성 디렉토리)에 쓰기. 규칙은 Claude Code가 각 트랜스크립트 항목에 자기 검사를 위해 추가하는 메타데이터 줄도 다룹니다. 트랜스크립트 읽기는 차단되지 않습니다.
  • 분류기가 보는 대화 어디에도 할당되지 않은 셸 변수를 대상으로 하는 rm -rf "$VAR"·Remove-Item -Recurse -Force $dir 같은 재귀 강제 삭제, 또는 그 루트의 glob. 값이 이전 명령 출력에서만 왔는데 분류기는 그것을 받지 못하므로 삭제 대상을 다른 삭제 규칙에 대해 검증할 수 없습니다. 삭제되는 정확한 경로를 이름으로 정하거나, Claude가 명령에 해석된 리터럴 경로를 써서 삭제를 다시 실행하면 차단이 해제됩니다. 분류기가 해결할 수 있는 대상의 삭제는 영향받지 않습니다. 대상이 단순 *이거나 /*·\*로 끝나는 Remove-Item은 분류기에 도달하지 않습니다. Claude Code가 아예 거부합니다.

Claude Code v2.1.257 이상은 기본으로 다음도 차단합니다.

  • 169.254.169.254 같은 클라우드 인스턴스 메타데이터 엔드포인트에서 자격 증명 요청, 또는 머신 고유의 서비스 계정·노드 아이덴티티로 클라우드·클러스터·레지스트리 호출을 명시적으로 인증
  • 터널, 리버스 셸, 밖을 가리키도록 재작성된 리졸버·프록시 구성 같은 직접 요청이 아닌 경로로 공개 호스트에 닿기
  • 노드 인증서나 노드의 컨테이너 레지스트리 인증처럼 작업이 아닌 호스트에 속한 자격 증명 읽기
  • Claude가 시작하지 않은 형제 컨테이너·팟·VM, 또는 컨테이너 아래 노드에 연결·스캔

Claude Code가 이런 것 중 하나가 허용되게 돌아가는 곳이 있다면, 그 설정을 autoMode.environment의 Host containment 항목에 설명하세요.

Claude Code v2.1.261 이상은 기본으로 다음도 차단합니다.

  • 그 서비스를 이름으로 정하지 않으면, URL 자체가 공유되는 콘텐츠를 담을 때 공용 paste·다이어그램·데이터 공유 서비스에 대한 링크를 메시지, PR·이슈 텍스트, 문서, 링크가 열리거나 가져와질 다른 어디든 게시·작성

기본적으로 허용되는 것:

  • 작업 디렉토리의 로컬 파일 작업
  • lock 파일·매니페스트에 선언된 의존성 설치
  • .env 읽기와 그에 대응하는 API에 자격 증명 보내기
  • 읽기 전용 HTTP 요청
  • 작업 중인 리포지토리의 어떤 브랜치로든(기본 브랜치 포함) 푸시. production·gh-pages처럼 배포·게시 대상임을 이름이 표시하는 비기본 브랜치는 포함되지 않습니다. 분류기는 거기 푸시를 그 자체 조건으로 판단합니다. 푸시 내용은 여전히 다른 규칙에 대해 점검되고, permissions.deny 규칙이 모든 모드에서 작성 그대로 푸시 명령을 차단할 수 있으며, 리모트 자체 브랜치 보호는 여전히 적용됩니다. v2.1.211 이전에는 시작한 브랜치, Claude가 만든 브랜치, 기본 브랜치에 대한 일상 푸시만 기본으로 허용됐고, v2.1.203 이전에는 기본 브랜치로의 어떤 직접 푸시도 차단됐습니다.

Claude Code v2.1.195 이상은 기본으로 다음도 허용합니다.

  • 같은 세션에서 Claude가 앞서 만든 정확한 잡 삭제
  • 작업의 일부로 보안 관련 코드·구성·위협 모델 읽기·리뷰·작성
  • 같은 다중 에이전트 세션에서 함께 작업하는 에이전트 간 메시지
  • environment에 나열한 신뢰 도메인·버킷·서비스로 데이터 전송. 이는 데이터 흐름만 다루고 같은 인프라의 파괴적·자격 증명 작업은 다루지 않습니다.
  • Claude in Chrome의 신뢰 내부 도메인, localhost, 이름을 정한 URL로 탐색

샌드박스 네트워크 접근 요청은 기본으로 허용하는 대신 분류기를 통과합니다. v2.1.198부터 분류기는 네트워크 호스트·포트의 판정을 매 연결마다 다시 실행하는 대신 재사용합니다.

  • 허용(allow)은 새 콘텐츠가 대화에 들어올 때까지 재사용되며, 그 시점에 그 호스트가 다시 점검됨
  • Claude Code v2.1.234 이상은 대화가 분류기의 컨텍스트 창을 넘어서 자란 것에 의한 거부를, 새 콘텐츠가 대화에 들어오거나 컴팩션이 분류기가 읽는 것을 줄일 때까지 재사용합니다. 그런 다음 Claude Code가 호스트를 다시 점검합니다.
  • 분류기가 요청 평가로 도달한 거부는 인터랙티브 CLI에서 그 턴 동안 지속됩니다. 비인터랙티브 모드와 Agent SDK 세션에서는 그 세션이 턴 경계가 없으므로 Claude Code가 나머지 실행 동안 그 거부를 재사용합니다.
  • 권한 모드·규칙을 바꾸면 모든 캐시된 판정이 버려집니다.

claude auto-mode defaults를 실행해 전체 규칙 목록을 JSON으로 출력하세요. 일상 동작이 차단되면 관리자가 autoMode.environment 설정으로 신뢰 리포지토리·버킷·서비스를 추가할 수 있습니다. auto 모드 구성 참고.

작업 중인 리포지토리의 어떤 브랜치로든 푸시하고 요청과 일치하는 풀 리퀘스트 만들기는 프롬프트 없이 실행됩니다. 푸시·풀 리퀘스트가 차단 목록(시크릿·민감한 데이터가 리포지토리 밖으로 나가는 것, 다른 리포지토리·조직을 대상으로 하는 풀 리퀘스트 같은)에 해당하지 않는 한 말이죠. auto 모드에 머물면서 이 명령들 전에 사람 체크포인트를 요구하려면 permissions.ask 규칙을 추가하세요. 작성 그대로 명령을 매칭합니다. 일반 경계 참고.

작업 디렉토리 밖 첫 읽기 (The first read outside the working directories)

permissions.blockReadsOutsideWorkingDirectories가 꺼져 있는 동안 파일 읽기는 auto 모드에서 작업 디렉토리 밖 읽기를 포함해 프롬프트 없이 실행됩니다. Claude가 Read·Grep·Glob 도구를 그 밖 경로에 처음 쓰면 Claude Code가 그 읽기를 계속 허용할지 묻습니다.

이 프롬프트는 비인터랙티브 -p 실행이나 백그라운드 세션에는 나타나지 않습니다. 거기 읽기는 이전처럼 실행됩니다.

무엇을 답해도 Claude는 계속 작업합니다.

  • Keep allowing: 읽기가 실행되고, 이후 작업 디렉토리 밖 읽기도 이전처럼 실행되며, Claude Code가 답을 기록해 프롬프트가 다시 나타나지 않음
  • Block from now on: 읽기가 거부되고, Claude Code가 사용자 설정에서 permissions.blockReadsOutsideWorkingDirectories를 true로 설정해, 이후 모든 세션·모드에서 파일 도구가 그런 읽기를 거부하게 함. 나중에 Claude가 그 경로를 읽게 하려면 /add-dir로 디렉토리를 추가하거나 설정을 제거하세요.
  • Ask again next time: 읽기가 거부되고 다음 작업 디렉토리 밖 읽기에서 다시 프롬프트
대화에서 정하는 경계 (Boundaries you state in conversation)

분류기는 대화에서 정한 경계를 차단 신호로 취급합니다. "don't push"나 "deploy하기 전에 내가 리뷰할 때까지 기다려"라고 말하면 기본 규칙이 허용해도 분류기가 매칭 동작을 차단합니다. 경계는 나중 메시지에서 해제할 때까지 유효합니다. 조건이 충족됐다는 Claude 자신의 판단은 해제하지 않습니다.

경계는 규칙으로 저장되지 않습니다. 분류기가 각 검사마다 트랜스크립트에서 다시 읽으므로, 컨텍스트 컴팩션이 그것을 말한 메시지를 제거하면 경계가 사라질 수 있습니다. 확실한 보장이 필요하면 거부 규칙을 추가하세요.

auto 모드가 폴백할 때 (When auto mode falls back)

auto 모드가 세션의 동작을 승인할 수 없을 때 무슨 일이 일어나는지는 경우에 따라 다릅니다.

  • 차단된 동작: Claude Code가 알림을 보여주고 /permissions의 Recently denied 탭에 동작을 나열합니다. 여기서 r을 눌러 수동 승인으로 재시도할 수 있습니다. 분류기가 동작에 대해 판정을 내지 못하면(auto 모드와 별개의 안전 검사가 분류기 자신의 요청을 거부했거나 응답이 파싱되지 않아서) Claude Code는 알림이나 Recently denied 항목 없이 동작을 거부합니다.
  • 반복 차단: 분류기가 동작을 3번 연속 또는 총 20번 차단하면 auto 모드가 일시 중지되고 Claude Code가 프롬프트를 재개합니다. 프롬프트된 동작을 승인하면 auto 모드가 재개됩니다. 이 임계값은 설정할 수 없습니다. 허용된 동작은 연속 카운터를 리셋하지만 총 카운터는 세션 동안 지속되고 자체 한도가 폴백을 트리거할 때만 리셋됩니다. Claude Code는 auto 모드와 별개의 안전 검사가 분류기 자신의 요청을 거부할 때 그 거부를 두 임계값 중 어느 쪽에도 세지 않습니다. 링크된 항목이 Claude Code가 그 거부를 어떻게 처리하는지 다룹니다.
  • 프롬프트할 수 없는 세션: --permission-prompt-tool이 없는 비인터랙티브 -p 실행은 폴백할 프롬프트가 없습니다. 반복 차단이 임계값에 닿으면 동작이 실행되지 않고 Claude는 계속 작업합니다. auto 모드와 별개의 안전 검사가 분류기의 요청을 거부할 때도 같습니다. Claude Code는 어느 경우에도 실행을 멈추지 않습니다.
  • 검사 중 모드 전환: 분류기 검사가 대기 중일 때 권한 모드를 바꾸면 Claude Code는 새 모드가 요청하지 않았을 판정을 적용하는 대신 버립니다. 대신 승인 프롬프트가 나오거나, dontAsk 모드에서는 동작이 자동 거부됩니다.

반복 차단은 보통 분류기가 인프라에 대한 컨텍스트가 부족함을 뜻합니다. /feedback으로 오탐을 보고하거나 관리자가 신뢰 인프라를 구성하게 하세요.

분류기가 동작을 평가하는 방식 (How the classifier evaluates actions)

각 동작은 고정된 결정 순서를 거칩니다. 첫 번째 매칭 단계가 이깁니다.

  1. allow, ask, deny 규칙과 일치하는 동작은 즉시 해결됩니다. 보호 경로 쓰기는 allow 규칙이 매칭돼도 분류기로 라우팅되며, Claude Code v2.1.218 이상에서 중요 경로를 대상으로 하는 rm·rmdir 제거도 그렇습니다. requiresUserInteraction로 표시된 MCP 도구는 allow 규칙이 매칭돼도 직접 프롬프트하며, 조직이 ask로 설정한 커넥터 도구도 그 설정이 Claude Code에 닿는 세션에서 그렇습니다. Bash(git push *)처럼 명령 내용에 매칭하는 ask 규칙은 권한 프롬프트로 폴백합니다.
  2. 작업 디렉토리의 읽기 전용 동작·파일 편집은 보호 경로 쓰기와 프롬프트하는 작업 디렉토리 밖 첫 읽기를 제외하고 자동 승인됩니다.
  3. 그 외 모든 것은 분류기로 갑니다. step 1에서 직접 프롬프트하는 커넥터 도구·requiresUserInteraction MCP 도구는 분류기에 도달하지 않으므로 조직 필수 승인이나 동의 단계가 자동 승인되지 않습니다.
  4. 분류기가 차단하면 Claude는 이유를 받고 대안을 시도합니다. 대부분 세션에서 이유는 서면 설명 대신 분류기가 매칭한 규칙([Data Exfiltration] 같은)을 이름으로 정합니다. 거부 검토 참고.

auto 모드에 들어가면 임의 코드 실행을 부여하는 광범위한 allow 규칙이 버려집니다.

  • 포괄적인 Bash(*)·PowerShell(*)
  • Bash(python*) 같은 와일드카드 인터프리터
  • 패키지 매니저 실행 명령
  • Agent allow 규칙
  • Monitor allow 규칙. Claude Code가 Monitor 명령을 셸을 통해 실행하기 때문입니다.

Bash(npm test) 같은 좁은 규칙은 유지됩니다. Claude Code는 auto 모드를 떠날 때 버려진 규칙을 복원합니다. v2.1.236 이전에는 Claude Code가 auto 모드에서 Monitor allow 규칙을 유지해, 전체 도구를 매칭하는 규칙이 분류기 리뷰 없이 Monitor 명령을 승인했습니다.

Claude Code는 또한 git reset --hard·rm -rf처럼 커밋되지 않은 작업을 버릴 명령 전에 git status를 스스로 실행하고, 스테이지·수정·추적 안 된 작업이 있는지 분류기에 보여줍니다. Claude Code는 리포지토리 git 구성이 status.showUntrackedFiles=no로 설정해도 그 검사에서 추적 안 된 파일을 보고합니다.

분류기는 사용자 메시지, 파일 읽기·검색 같은 읽기 전용 조회가 아닌 도구 호출, CLAUDE.md 내용을 봅니다. 도구 결과는 제거되므로 파일이나 웹 페이지의 적대적 콘텐츠가 직접 조작할 수 없습니다. 호출의 결과를 PostToolUse hook의 classifierContext 필드로 주석할 수 있으며, 분류기가 애플리케이션 제공 컨텍스트로 읽습니다.

별도의 서버 측 프로브가 들어오는 도구 결과를 스캔해 Claude가 읽기 전에 의심스러운 콘텐츠를 플래그합니다. 이 계층들이 함께 작동하는 방식은 auto mode 발표와 엔지니어링 딥다이브를 참고하세요.

auto 모드가 서브에이전트를 처리하는 방식 (How auto mode handles subagents)

분류기는 서브에이전트 작업을 세 지점에서 검사합니다.

  1. 서브에이전트가 시작되기 전에 위임된 작업 설명이 평가되므로, 위험해 보이는 작업은 스폰 시점에 차단됩니다.
  2. 서브에이전트가 실행되는 동안 각 동작이 부모 세션과 같은 규칙으로 분류기를 통과하며, 서브에이전트 frontmatter의 어떤 permissionMode도 무시됩니다.
  3. 서브에이전트가 끝나면 분류기가 전체 동작 기록을 리뷰합니다. 그 반환 검사가 문제를 플래그하면 서브에이전트 결과 앞에 보안 경고가 붙습니다. 별도의 API 안전 검사가 검사 요청 자체를 거부하면 Claude Code는 여전히 서브에이전트 결과를, 작업이 미검토이며 신뢰할 수 없는 것으로 취급하라는 경고를 앞에 붙여 반환합니다.

step 1은 Claude Code v2.1.178 이상이 필요합니다. 이전 버전은 step 2·3에서 분류기를 적용했지만 서브에이전트가 시작되기 전에 작업 설명을 평가하지 않았습니다.

비용과 대기 시간 (Cost and latency)

분류기는 기본적으로 /model 선택이 아니라 Claude Sonnet 5에서 실행됩니다. Anthropic이 서버 측에서 구성하는 분류기 모델이 그 기본값보다 우선합니다. 세션 모델이 Claude Sonnet 4.6이거나 availableModels이 Sonnet 5를 제외하면 분류기는 대신 세션 모델에서 실행되고, 세션이 Fable 모델에서 실행되면 Opus 모델에서 실행됩니다. Anthropic API가 아닌 제공자에서 그 Opus 폴백은 제공자의 기본 Opus 모델입니다.

세션의 첫 auto 모드 요청이 Sonnet 5 기본값을 검증합니다. 요청이 성공하면 Sonnet 5가 세션의 분류기 모델로 유지되고, 모델을 쓸 수 없어 실패하면 세션은 폴백을 씁니다. 그 검증이 확정된 후 분류기 모델은 세션 동안 바뀌지 않습니다.

Enterprise 플랜과 Claude API, Claude Platform on AWS, Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry를 쓰는 계정에서 분류기 호출은 토큰 사용량에 계산됩니다. 각 검사는 트랜스크립트 일부와 대기 중인 동작을 보내 실행 전에 왕복을 추가합니다. 보호 경로 밖 읽기와 작업 디렉토리 편집은 분류기를 건너뛰므로 오버헤드는 주로 셸 명령·네트워크 작업에서 와야 합니다.

분류기는 호스트·포트의 샌드박스 네트워크 판정을 재사용하므로 같은 호스트로의 반복 연결이 각각 검사를 추가하지 않습니다. 분류기가 기본으로 차단하는 것이 허용·거부가 얼마나 지속되는지 설명합니다.

dontAsk 모드로 사전 승인 도구만 허용 (Allow only pre-approved tools with dontAsk mode)

dontAsk 모드를 설정하면 Claude Code가 평소 프롬프트를 낼 모든 도구 호출을 자동 거부합니다. Claude는 여전히 Manual 모드에서 승인이 필요 없는 동작(작업 디렉토리 안 파일 읽기, 읽기 전용 Bash 명령)과 permissions.allow 규칙에 매칭하는 동작, PreToolUse hook이 승인한 호출을 실행합니다. CI 파이프라인이나 Claude가 무엇을 할지 미리 정의한 제한된 환경에 이 모드를 쓰세요. 세션은 입력을 기다리지 않습니다. 이 모드가 활성화된 동안 상태 바는 ⏵⏵ don't ask on을 표시합니다.

Claude Code는 명시적 ask 규칙에 매칭하는 호출을 프롬프트하는 대신 거부합니다. 내장 AskUserQuestion 도구도 allow 규칙이 매칭해도 거부하며, 조직이 ask로 설정한 커넥터 도구도 그 설정이 Claude Code에 닿는 세션에서 그렇게 합니다. _meta["anthropic/requiresUserInteraction"]로 표시된 MCP 도구도 같은 방식으로 거부합니다. 그 승인 카드는 이 모드가 수집하지 않는 답이 필요하기 때문입니다. Claude Code v2.1.199 이상 필요.

rm -rf /와 rm -rf ~처럼 중요 경로를 대상으로 하는 rm·rmdir 제거는 allow 규칙이 매칭하거나 PreToolUse hook이 허용해도 거부됩니다.

웹의 Claude Code의 클라우드 세션은 defaultMode: "dontAsk"를 무시합니다. 상세는 bypassPermissions 참고.

시작 시 플래그로 설정하세요.

claude --permission-mode dontAsk

bypassPermissions 모드로 모든 검사 건너뛰기 (Skip all checks with bypassPermissions mode)

bypassPermissions 모드는 권한 프롬프트와 안전 검사를 비활성화해 도구 호출이 즉시 실행되게 합니다. 보호 경로 쓰기 포함입니다.

어떤 모드도 자동 승인하지 않는 동작은 이 모드에서도 여전히 프롬프트를 냅니다.

두 크로스 세션 메시징 안전장치가 이 모드와, 바이패스 권한이 가능한 plan 모드 세션에서 여전히 적용됩니다.

  • 이 머신 너머 세션으로의 메시지에 대한 isolatePeerMachines 승인 프롬프트가 여전히 나타납니다.
  • 적용되는 crossSessionInbound 값이 없으면 Claude Code는 다른 내 세션에서 온 인바운드 메시지를 승인을 위해 보류하고, 보내는 세션이 자기 자신도 권한 프롬프트를 우회한다고 식별할 때만 묻지 않고 전달합니다. 메시지가 보류된 동안 권한 모드를 떠나면 Claude Code가 인바운드 규칙을 다시 적용하고 이제 받아들이는 보류 메시지를 전달합니다.

바이패스 권한이 가능한 세션에서 Claude Code는 plan 모드의 차단도 강제하지 않습니다. Claude에게 계획하는 동안 편집하지 말라고 지시는 하지만, 계획 중 시도하는 파일 편집·셸 명령은 프롬프트 없이 실행됩니다. 명시적 ask 규칙과 중요 경로를 대상으로 하는 rm·rmdir 제거는 여전히 프롬프트를 냅니다.

Claude Code가 호스트 시스템을 손상시킬 수 없는, 인터넷 없는 컨테이너·VM·dev 컨테이너 같은 격리 환경에서만 이 모드를 쓰세요.

활성화 없이 시작한 세션에서 bypassPermissions로 들어갈 수 없습니다. 실행 시 permissions.defaultMode: "bypassPermissions"나 활성화 플래그로 켜세요.

claude --permission-mode bypassPermissions

--dangerously-skip-permissions 플래그는 동등합니다.

Claude Code는 --restricted로 시작한 세션에서 bypassPermissions를 거부합니다. --restricted는 Claude Code v2.1.248 이상이 필요합니다.

이 모드를 켜고 인터랙티브 세션을 처음 시작하면 Claude Code가 권한 검사 없이 취한 동작에 대한 책임을 수락하라는 경고 대화상을 보여줍니다. Claude Code는 수락을 사용자 설정에 저장하므로 대화상자는 한 번만 나타납니다. 거절하면 Claude Code가 종료합니다. 비인터랙티브 모드에서는 대화상자가 없고, --bg로 시작한 백그라운드 세션은 인터랙티브 세션에서 대화상자를 수락할 때까지 거부됩니다.

Linux·macOS에서 Claude Code는 root나 sudo로 실행 중일 때 이 모드로 시작을 거부합니다.

--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons

이 검사는 인식된 샌드박스 안에서 자동으로 건너뜁니다. 컨테이너에서 자율적으로 실행하려면 Claude Code를 비루트 사용자로 실행하는 dev container 구성을 쓰세요.

웹의 Claude Code는 설정 파일의 defaultMode: "bypassPermissions"나 "dontAsk"를 존중하지 않으므로, 체크인된 설정이 클라우드 세션을 바이패스 권한 모드로 시작할 수 없습니다. 설정은 조용히 무시되고 세션은 모드 드롭다운이 보여주는 권한 모드로 시작합니다. 클라우드 세션이 제공하는 모드는 권한 모드 전환 참고.

`bypassPermissions`는 프롬프트 인젝션이나 의도하지 않은 동작에 대한 보호를 제공하지 않습니다. 권한 프롬프트가 훨씬 적은 백그라운드 안전 검사를 원하면 [auto 모드](#eliminate-prompts-with-auto-mode)를 쓰세요. 관리자는 [관리 설정](/docs/en/managed-settings)에서 `permissions.disableBypassPermissionsMode`를 `"disable"`로 설정해 이 모드를 차단할 수 있습니다.

보호 경로 (Protected paths)

작은 경로 집합에 대한 쓰기는 bypassPermissions 모드와 바이패스 권한이 가능한 계획 세션을 제외하고 절대 자동 승인되지 않습니다. 이는 리포지토리 상태와 Claude 자신의 구성의 우발적 손상을 막습니다.

모드 보호 경로 쓰기
default, acceptEdits 프롬프트
plan 바이패스 권한이 가능한 세션에서는 허용. 그렇지 않으면 계획 중 auto 모드가 가능하면 분류기로 라우팅되고, 아니면 프롬프트
auto 분류기로 라우팅
dontAsk 거부
bypassPermissions 허용

--restricted(Claude Code v2.1.248 이상 필요)로 시작한 세션에서 분류기는 보호 경로 쓰기를 승인할 수 없습니다.

설정 파일의 permissions.allow 규칙은 보호 경로 쓰기를 사전 승인하지 않습니다. 안전 검사가 Claude Code가 설정의 allow 규칙을 평가하기 전에 실행되므로, ~/.claude/settings.json이나 .claude/settings.json의 Edit(.claude/**) 같은 항목은 위 표의 모드별 결과를 바꾸지 않습니다. 프롬프트하는 모드에서 .claude/ 쓰기 프롬프트는 Yes, and allow Claude to edit its own settings for this session을 제공하며, 이를 승인하면 그 세션에서 이후 .claude/ 쓰기를 다시 묻지 않고 승인합니다.

보호 디렉토리:

  • .git
  • .config/git
  • .vscode
  • .idea
  • .husky
  • .cargo
  • .devcontainer
  • .yarn
  • .mvn
  • .claude — 단, Claude가 자기 git 워크트리를 저장하는 .claude/worktrees 제외

보호 파일:

  • .gitconfig, .gitmodules
  • .bashrc, .bash_profile, .bash_login, .bash_aliases, .bash_logout, .zshrc, .zprofile, .zshenv, .zlogin, .zlogout, .profile, .envrc
  • .npmrc, .yarnrc, .yarnrc.yml, .pnp.cjs, .pnp.loader.mjs, .pnpmfile.cjs, bunfig.toml, .bunfig.toml
  • .bazelrc, .bazelversion, .bazeliskrc
  • .pre-commit-config.yaml, lefthook.yml, lefthook.yaml, .lefthook.yml, .lefthook.yaml
  • gradle-wrapper.properties, maven-wrapper.properties
  • .devcontainer.json
  • .ripgreprc, pyrightconfig.json
  • .mcp.json, .claude.json

중요 경로 (Critical paths)

Claude Code는 permissions.allow 규칙이나 "allow"를 반환하는 PreToolUse hook이 중요 경로를 대상으로 하는 rm·rmdir 명령을 승인하게 하지 않습니다. 다른 프롬프트를 건너뛰는 모드에서도 그렇습니다. 이 회로 차단기는 모델 오류를 막습니다. 매칭되는 거부 규칙은 여전히 명령을 아예 차단합니다.

대신 일어나는 일은 권한 모드에 따라 다릅니다.

모드 Claude Code가 중요 경로 제거에 하는 일
default, acceptEdits 승인 요청
plan 승인 요청. 계획 중 auto 모드가 가능하고 바이패스 권한이 없으면 분류기로 보냄
auto 분류기로 보냄
dontAsk 거부
bypassPermissions 승인 요청

명시적 ask 규칙이 명령을 매칭하면 Claude Code는 auto 모드에서도 묻습니다. 묻는 모드에서 PermissionRequest hook이 다른 어떤 프롬프트처럼 답할 수 있습니다.

Claude Code는 rm·rmdir 대상이 다음 중 하나일 때 중요 경로로 취급합니다.

  • 파일시스템 루트
  • 최상위 디렉토리, 즉 루트의 직접 자식(/usr, /etc, /data 등)
  • 홈 디렉토리
  • Windows 드라이브 루트와 그 최상위 디렉토리(C:\, C:\Windows 등)
  • 작업 디렉토리와 그 부모
  • 추가 작업 디렉토리와 그 부모 — 단, 제거가 그 중 하나 아래의 glob일 때만(rm -rf <dir>/*처럼). 디렉토리 자체의 rm -rf <dir>은 이 검사를 트리거하지 않습니다.

Claude Code는 rm -rf "$DIR"/*처럼 셸 변수 바로 아래의 glob·끝 슬래시도 중요 경로 제거로 취급합니다. 변수가 비면 파일시스템 루트에서의 제거가 되기 때문입니다.

$(...)·백틱의 명령 치환이나 <(...)의 프로세스 치환 안에 제거를 숨겨도 검사를 건너뛰지 않습니다. Claude Code는 echo "$(rm -rf ~)"처럼 치환 안에 있든 같은 명령의 다른 곳에 있든 중요 경로 제거를 찾습니다.

PowerShell의 Remove-Item (Remove-Item in PowerShell)

PowerShell 도구를 켜면 Claude Code는 Remove-Item에 rm 중요 경로 목록과 별개의 자체 검사를 줍니다. 결과는 대상에 달려 있으며 첫 번째 매칭 사례가 적용됩니다.

  • 시스템 경로: 파일시스템 루트와 그 최상위 디렉토리, 드라이브 루트와 그 최상위 디렉토리, 홈 디렉토리. Claude Code는 묻지 않고 모든 모드에서 명령을 거부합니다.
  • 와일드카드: 단순 *, 또는 /*·\*로 끝나는 어떤 대상($dir/* 같은 셸 변수 아래 glob 포함). Claude Code는 분류기가 보기 전에 묻지 않고 모든 모드에서 명령을 거부합니다.
  • -Recurse가 있는 작업 디렉토리 또는 그 부모 중 하나: Claude Code는 명령을 권한 모드에서 승인이 필요한 다른 것처럼 취급합니다. 묻는 모드에서 묻고, auto 모드에서 분류기로 보내며, dontAsk 모드에서 거부합니다. bypassPermissions 모드는 이 검사를 건너뜁니다.

더 알아보기