SpyBara
Go Premium

permission-modes.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 178 additions and 178 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Sat 3 23:57 Sun 4 23:58 Mon 5 23:58 Tue 6 23:59 Wed 7 23:59 Sat 10 23:01 Sun 11 23:57 Wed 14 22:58 Sat 17 23:57 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58 Mon 26 22:57 Tue 27 22:59 Wed 28 23:57 Fri 30 23:01

권한 모드 선택

Claude가 작업하기 전에 묻는지 여부를 제어합니다. CLI에서 Shift+Tab, VS Code의 모드 표시기 또는 Desktop의 모드 선택기로 권한 모드를 전환합니다.

권한 모드는 Claude가 먼저 묻지 않고 세션에서 수행할 수 있는 작업을 설정합니다. Manual 모드에서는 Claude Code가 파일을 편집하거나 셸 명령을 실행하거나 네트워크에 접근하는 대부분의 작업 전에 멈추고 사용자에게 묻습니다. auto 모드에서는 두 번째 모델인 분류기가 사용자 대신 작업을 검토합니다. 분류기가 작업을 평가하는 방식에서는 분류기가 검토하는 작업과 건너뛰는 작업을 나열합니다.

Claude Code v2.1.283 이상에서는 auto 모드가 대화형 터미널 및 VS Code 세션의 기본 제공 시작 권한 모드입니다. 이전 버전에서는 Pro, Max, Team 플랜에서만 기본 제공되는 시작 권한 모드입니다. 세션이 시작되는 모드에서는 시작 권한 모드를 변경하는 표면과 설정을 다룹니다. 실행 중인 세션의 권한 모드는 언제든지 변경할 수 있습니다.

사용 가능한 모드

각 모드는 편의성과 감시 사이에서 서로 다른 트레이드오프를 만듭니다. 아래 표는 각 모드에서 Claude가 권한 프롬프트 없이 수행할 수 있는 작업을 보여줍니다. 수동 모드는 구성 값인 default 아래에 나타납니다.

모드 요청 없이 실행되는 작업 최적 사용 사례
default 읽기만 모든 작업을 직접 검토, 민감한 작업
acceptEdits 읽기, 파일 편집, 일반적인 파일시스템 명령어 (mkdir, touch, mv, cp 등) 검토 중인 코드 반복 작업
plan 읽기, 그리고 자동 모드를 사용할 수 있을 때 분류기 승인 명령어 변경 전 코드베이스 탐색
auto 백그라운드 안전 검사를 포함한 모든 작업 장시간 작업, 프롬프트 피로 감소
dontAsk 작업 디렉터리 내부의 파일 읽기 및 사전 승인된 도구; 프롬프트를 표시할 모든 작업은 거부됨. 단, 설치한 mod는 이러한 호출 중 일부를 여전히 승인할 수 있음 잠금된 CI 및 스크립트
bypassPermissions 모든 작업 격리된 컨테이너 및 VM만 해당

모든 작업을 검토하는 모드는 CLI에서 Manual이라고 명명되며, claude --help에서, VS Code 및 JetBrains 확장 프로그램에서, 그리고 데스크톱 앱에서도 Manual이라고 명명됩니다. 구성 값은 default이며, 이는 훅 및 SDK 통합이 사용하는 값입니다. CLI는 값을 입력하는 모든 곳에서 manual을 별칭으로 허용합니다. 예를 들어 claude --permission-mode manual 또는 "defaultMode": "manual"입니다.

보호된 경로에 대한 쓰기는 bypassPermissions 모드에서와 bypass 권한을 사용할 수 있는 plan-mode 세션에서를 제외하고는 자동 승인되지 않습니다. 이는 모드 사이클에 bypassPermissions를 배치하는 방식으로 시작된 대화형 터미널 세션을 의미합니다.

모드는 기준선을 설정합니다. 특정 도구를 사전 승인하거나 차단하기 위해 권한 규칙을 위에 계층화합니다. 거부 규칙은 bypassPermissions를 포함한 모든 모드에서 차단합니다. 거부 및 요청 규칙은 Claude가 호출할 수 있는 다른 도구가 최소 하나 이상 있는 한 EndConversation에 적용되지 않습니다. 허용 규칙은 bypassPermissions에서 효과가 없습니다.

어떤 모드도 자동 승인하지 않는 작업

Claude Code는 bypassPermissions를 포함한 어떤 모드에서도 다음을 자동 승인하지 않습니다. 각 항목은 각 모드에서 대신 어떤 일이 발생하는지를 설명하는 섹션으로 연결됩니다:

  • 명시적 요청 규칙과 일치하는 도구

  • 조직이 ask로 설정한 커넥터 도구, 해당 설정이 Claude Code에 도달하는 세션에서

  • 사용자 상호작용이 필요한 도구: 기본 제공 AskUserQuestion 도구 및 requiresUserInteraction으로 표시된 MCP 도구

  • 인식된 rm 및 rmdir 중요 경로 제거, 어떤 허용 규칙이나 PreToolUse 훅 "allow"도 승인하지 않음

  • 세션 간 메시징 보안 조치

  • permissions.blockReadsOutsideWorkingDirectories가 켜져 있는 동안 작업 디렉토리 외부의 읽기: 인식된 파일 읽기 Bash 명령어는 자동 모드 및 bypassPermissions 모드에서도 프롬프트하며, 샌드박스 외부에서 실행하기 위해 승인이 필요한 모든 샌드박스 해제 재시도도 마찬가지입니다. Claude Code v2.1.257 이상이 필요합니다.

    셸 파서가 추적할 수 없는 명령어(예: 두 번 이상 디렉토리를 변경하거나 서브셸을 실행하는 명령어)는 외부 경로를 명명하지 않더라도 동일한 방식으로 프롬프트합니다. 이 프롬프트는 명령어가 샌드박스에서 실행되고 샌드박스가 블록을 적용할 때는 적용되지 않습니다.

일반적인 설정

권한 모드는 Claude가 작업 전에 물어보는지 여부를 결정하고, Bash sandbox 및 외부 isolation boundaries는 작업이 실행되면 도달할 수 있는 것을 결정합니다. 아래의 각 행은 목표를 시작점으로 그곳에 도달하는 플래그 또는 설정 및 필요한 격리와 쌍을 이룹니다. 사용 가능한 모드는 각 모드에서 프롬프트 없이 실행되는 것을 나열합니다.

원하는 것 시작 필요한 격리 참고
모든 작업을 직접 검토 Manual 모드: claude --permission-mode default 없음 민감한 작업, 낯선 코드
분류기 없이 더 적은 프롬프트로 로컬에서 반복 Manual 모드 + auto-allow mode의 Bash sandbox: claude --permission-mode default, 그 다음 /sandbox 실행 및 auto-allow 선택 기본 제공 Bash sandbox, macOS, Linux, WSL2 Deny 규칙은 여전히 적용되고, Bash(git push *)와 같이 명령을 지정하는 ask 규칙은 여전히 프롬프트합니다. 확인을 요청할 수 있는 그 밖의 명령은 Auto-allow mode에서 다룹니다. 설정 파일에서 대신 sandbox를 켜려면 sandbox.enabled를 true로 설정합니다.
변경 전에 탐색 claude --permission-mode plan 없음 Claude Code는 계획을 승인할 때까지 편집을 차단합니다.
auto mode에서 자동 실행 claude --permission-mode auto, 기본 제공 시작 권한 모드 v2.1.283 이상 없음; sandbox 또는 컨테이너는 심층 방어를 추가합니다. 지원되는 모델이 필요하고, 조직이 auto mode를 끌 수 있습니다.
정확한 allowlist로 CI에서 실행 claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read" CI 러너가 제공하는 것 이상 없음 Cloud sessions는 설정 파일의 dontAsk를 무시합니다.
컨테이너 내에서 완전히 자동 실행 claude -p "<prompt>" --dangerously-skip-permissions 필수: 컨테이너, VM, 또는 sandbox runtime; Linux 및 macOS에서 non-root user로 실행 Cloud sessions는 설정 파일의 이 모드를 무시합니다. 이 -p 실행에서 여전히 프롬프트할 몇 가지 호출은 대신 거부됩니다.

Bash sandbox와 auto mode는 독립적으로 작동하고 결합합니다. Sandbox modes에 나열된 예외가 있습니다. 전체 상호작용은 How sandboxing relates to permissions and permission modes 및 How isolation relates to permission modes를 참조하세요.

세션이 시작되는 모드

터미널에서 새 세션을 시작할 때 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"를 설정하면 역시 적용되지 않으며, 세션은 수동 모드에서 시작됩니다. 다른 값들은 모든 설정 파일에서 적용됩니다.

  3. 기본 제공 기본값

VS Code 확장 프로그램이 시작하는 대화는 권한 모드 전환의 확장 프로그램 자체 목록을 따릅니다. Claude Code가 재개된 세션을 시작하는 권한 모드에 대해서는 재개 시 권한 모드를 참조하세요.

기본 제공 auto 기본값은 macOS, Linux 및 WSL에서 Claude Code v2.1.228 이상이 필요하며, 기본 Windows에서는 v2.1.233 이상이 필요합니다. 이전 버전에서는 기본 제공 기본값이 수동입니다.

기본 제공 기본값은 Claude Code를 실행하는 방식에 따라 달라집니다. 세션과 일치하는 첫 번째 행이 적용됩니다. 이 표는 터미널이나 VS Code 확장 프로그램을 통해 시작하는 세션을 다룹니다. 데스크톱 앱 및 claude.ai의 경우 권한 모드 전환의 데스크톱 및 웹 탭을 참조하세요.

Claude Code를 실행하는 방식 기본 제공 시작 권한 모드
모든 설정 파일이 disableAutoMode를 "disable"로 설정 default
claude -p 또는 Agent SDK default
조직에 HIPAA 구성이 적용되어 있고 세션이 적용 대상인 경우 Claude Code v2.1.285 이상에서 default. 자동 모드로 전환하는 것은 계속 가능합니다
터미널 또는 VS Code 확장 프로그램을 통해 Claude Code v2.1.283 이상에서 auto; 이전 버전에서는 기능 플래그를 가져오는 세션에서 Pro, Max 또는 Team 플랜의 auto, 그 외에는 default

플래그, 설정 파일 또는 기본 제공 기본값이 auto를 선택하지만 자동 모드를 세션에서 사용할 수 없는 경우, Claude Code는 대신 수동 모드에서 세션을 시작합니다. 자동 모드는 세션이 가용성 요구 사항을 충족하지 않을 때(예: 설정 파일이 자동 모드를 비활성화하거나 지원하지 않는 모델) 또는 Anthropic이 서버 측에서 임시로 자동 모드를 비활성화했을 때 사용할 수 없습니다.

기본 제공 기본값이 처음으로 세션 중 하나를 자동 모드에서 시작할 때, Claude Code는 이 페이지로 연결되는 알림을 표시합니다.

  • 터미널에서 세션 맨 위에 한 번
  • VS Code 확장 프로그램에서 새 대화 화면의 카드로 표시되며, 이를 닫을 때까지 유지됩니다.

~/.claude/settings.json이 auto 이외의 defaultMode를 설정하고 다른 설정 파일이 설정하지 않으면, 세션은 계속해서 해당 모드에서 시작됩니다. Pro, Max 및 Team 플랜에서, 그리고 기능 플래그를 가져오지 않는 세션에서 Claude Code는 터미널 또는 VS Code 확장 프로그램에서 한 번 설정을 자동 모드로 변경할지 여부를 묻습니다. 거절하면 설정은 그대로 유지됩니다.

claude -p 및 Agent SDK 실행에서 거부되는 도구 호출

Claude Code v2.1.302 이상에서는 권한 모드가 설정되지 않은 claude -p 및 Agent SDK 실행이 수동 모드에서 시작됩니다. 이 모드는 SDK 옵션과 설정에서 default로 표시됩니다. 승인이 필요한 호출은 허용 규칙, 훅, canUseTool 콜백 또는 --permission-prompt-tool로 승인하지 않는 한 거부됩니다.

이러한 호출이 승인되도록 하려면 허용 규칙을 추가하거나 자동 모드에서 시작합니다.

다음 예제는 CLI와 각 SDK에서 자동 모드를 사용하는 형태를 보여 줍니다.

CLI

claude -p "Run the test suite and fix any failures" --permission-mode auto

TypeScript

const options = {
  permissionMode: "auto"
};

Python

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(permission_mode="auto")

v2.1.302 이전에는 이러한 실행이 기능 플래그를 가져오지 않는 경우(예: 타사 공급자 사용 시 또는 DISABLE_TELEMETRY 설정 시) 자동 모드에서 시작될 수 있었습니다.

다른 권한 모드에서 시작

한 세션에 대해 또는 머신, 프로젝트 또는 조직의 모든 세션에 대한 기본값으로 시작 권한 모드를 설정할 수 있습니다. 둘 이상의 설정 파일이 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를 설정합니다. 터미널 세션은 해당 모드에서 시작되며 사용자는 여전히 자동 모드로 전환할 수 있습니다. VS Code 확장 프로그램이 읽는 내용은 권한 모드 전환을 참조하세요. 자동 모드를 제거하여 아무도 선택할 수 없도록 하려면 대신 permissions.disableAutoMode를 "disable"로 설정합니다.

이 예제는 머신의 모든 터미널 세션이 수동 모드(구성 값은 default)에서 시작되도록 합니다. ~/.claude/settings.json에 저장합니다.

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

다음 세션을 시작하면 상태 표시줄에 ⏸ manual mode on이 표시됩니다.

HIPAA 구성에서의 권한 모드

HIPAA 구성이 적용된 조직에서는 기본 제공 auto 기본값이 적용되지 않습니다. 시작 권한 모드를 선택하는 다른 항목이 없으면 터미널 또는 VS Code 세션은 수동 모드에서 시작됩니다. 터미널 세션에는 Auto mode isn't the default for your organization · Shift+Tab to switch도 표시되며, VS Code 확장 프로그램에는 알림이 표시되지 않습니다. 이 내용이 적용되는 세션은 개발자의 로그인 및 연결 방식 확인에 나와 있습니다.

자동 모드와 bypassPermissions는 계속 사용할 수 있습니다.

HIPAA 구성의 최소 버전인 Claude Code v2.1.285 이상이 필요합니다.

권한 모드 전환

각 인터페이스는 세션 중에 권한 모드를 전환하기 위한 자체 컨트롤과 새 세션이 시작되는 권한 모드를 선택하는 자체 방법을 가집니다. 인터페이스를 선택하여 컨트롤을 확인하세요.

CLI

세션 중: Shift+Tab을 눌러 권한 모드를 순환합니다. auto에서 처음 누르면 default로 전환되고, 이후 순환은 default → acceptEdits → plan 순으로 진행됩니다. 선택적 모드는 plan 뒤에 들어갑니다. 상태 표시줄은 활성 모드를 default의 경우 회색 ⏸ manual mode on으로, 또는 ⏵⏵ accept edits on, ⏸ plan mode on, ⏵⏵ auto mode on, ⏵⏵ don't ask on, 또는 ⏵⏵ bypass permissions on으로 표시합니다.

자동 모드에서 시작한 세션을 담은 이 클립에서 상태 표시줄을 확인하세요. Shift+Tab을 누를 때마다 상태 표시줄이 auto mode on에서 manual mode on, accept edits on, plan mode on으로 바뀌었다가 다시 auto mode on으로 돌아옵니다.