CoreCode블로그

가이드

Claude Code 권한 모드: default, acceptEdits, plan, auto, bypassPermissions

게시일 · 최종 확인

권한 확인 프롬프트를 건너뛰는 방법을 찾는 사람 대부분은 동작마다 승인하는 데 지친 경우입니다. 이 글은 Anthropic의 Choose a permission mode 문서를 따라, 각 권한 모드에서 Claude가 묻지 않고 할 수 있는 일, 모드를 전환하는 방법, 그리고 bypassPermissions를 격리된 환경에서만 써야 하는 이유를 설명합니다. 모드 이름, 플래그, 설정 키, 동작은 모두 그 문서에서 가져왔으며 2026년 10월 30일에 확인했습니다.

핵심 요약
  • 권한 모드는 세션에서 Claude가 먼저 묻지 않고 할 수 있는 동작을 정합니다. default는 CLI에서 Manual로 표시되며, 읽기만 프롬프트 없이 실행됩니다.
  • 문서에 따르면 Claude Code v2.1.283 이상에서는 대화형 터미널과 VS Code 세션의 내장 시작 권한 모드가 auto 모드입니다. 프롬프트가 여전히 많이 보인다면 이미 auto 모드인지 확인해 보세요.
  • 무방비 상태로 가지 않고 프롬프트를 줄이려면 acceptEdits를 쓰거나, 별도의 분류기 모델이 동작을 대신 검토해 주는 auto를 쓰세요. 문서는 bypassPermissions가 프롬프트 인젝션이나 의도치 않은 동작에 대한 보호를 전혀 제공하지 않는다고 밝힙니다.
  • bypassPermissions는 컨테이너나 VM 같은 격리된 환경에서만 쓰세요. deny 규칙은 이 모드를 포함한 모든 모드에서 차단합니다.
  • 모드는 Shift+Tab으로 순환하고, 시작 모드는 --permission-mode나 permissions.defaultMode로 정합니다.

권한 모드

문서에 따르면 권한 모드는 세션에서 Claude가 먼저 묻지 않고 할 수 있는 동작을 정합니다. Manual 모드에서 Claude Code는 파일 편집, 셸 명령 실행, 네트워크 접근 같은 대부분의 동작 전에 멈추고 묻습니다. 아래 표는 문서의 표를 옮긴 것으로, 모드별로 권한 프롬프트 없이 실행되는 동작을 보여 줍니다. Manual 모드는 설정 값인 default로 표시됩니다.

모드묻지 않고 실행되는 것적합한 용도
default읽기만모든 동작을 직접 검토할 때, 민감한 작업
acceptEdits읽기, 파일 편집, 일반적인 파일 시스템 명령(mkdir, touch, mv, cp 등)검토하면서 코드를 반복 수정할 때
plan읽기, 그리고 auto 모드를 쓸 수 있을 때 분류기가 승인한 명령변경하기 전에 코드베이스를 파악할 때
auto모든 것(백그라운드 안전 검사 포함)긴 작업, 프롬프트 피로 줄이기
dontAsk작업 디렉터리 안의 파일 읽기와 사전 승인된 도구. 프롬프트가 뜰 만한 것은 모두 거부잠긴 CI와 스크립트
bypassPermissions모든 것격리된 컨테이너와 VM에서만

모든 동작을 검토하는 모드는 CLI, claude --help, VS Code와 JetBrains 확장, 데스크톱 앱에서 Manual이라고 부릅니다. 설정 값은 default이며, hook과 SDK 연동은 이 값을 씁니다. CLI는 값을 입력하는 곳이면 어디서나 별칭 manual을 받습니다. 예를 들어 claude --permission-mode manual이나 "defaultMode": "manual"입니다.

모드 전환

세션 중: Shift+Tab을 눌러 권한 모드를 순환합니다. auto에서는 처음 누르면 default로 전환되고, 이후 default → acceptEdits → plan 순으로 순환합니다. 선택적 모드는 plan 뒤에 끼어듭니다. 상태 표시줄에 현재 모드가 나타납니다.

모드상태 표시줄
default회색 ⏸ manual mode on
acceptEdits⏵⏵ accept edits on
plan⏸ plan mode on
auto⏵⏵ auto mode on
dontAsk⏵⏵ don't ask on
bypassPermissions⏵⏵ bypass permissions on

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

활성화된 선택적 모드는 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 이상이 필요합니다. 내 ask 규칙이나 hook이 강제한 프롬프트에는 이 옵션을 추가하지 않습니다. auto 모드에서도 그런 프롬프트는 계속 표시되므로 전환해도 사라지지 않기 때문입니다.

시작할 때: 권한 모드를 플래그로 전달합니다. 같은 --permission-mode 플래그는 비대화형 실행의 -p와도 함께 쓸 수 있습니다.

claude --permission-mode plan

기본값으로: 원하는 범위에서 permissions.defaultMode를 설정합니다. VS Code에서는 프롬프트 상자 하단의 모드 표시기를 클릭하거나, claudeCode.initialPermissionMode로 시작 모드를 고정하세요.

세션이 어떤 모드로 시작하는가

터미널에서 새 세션을 시작하면 Claude Code는 다음 중 먼저 해당하는 항목에서 권한 모드를 가져옵니다.

  1. --permission-mode 플래그, 또는 --dangerously-skip-permissions
  2. 설정 파일의 permissions.defaultMode
  3. 내장 기본값

Claude Code v2.1.283 이상에서 터미널이나 VS Code 확장의 내장 기본값은 auto입니다. 이전 버전에서는 기능 플래그를 가져오는 세션의 Pro, Max, Team 플랜에서는 auto, 그 외에는 default입니다. claude -p와 Agent SDK의 내장 기본값은 default입니다. 어느 설정 파일에서든 disableAutoMode가 "disable"로 설정된 경우에도 default입니다. 플래그, 설정 파일, 내장 기본값이 auto를 선택했지만 세션에서 auto 모드를 쓸 수 없으면 Claude Code는 세션을 Manual로 시작합니다.

설정을 어디에 두느냐가 중요하며, 문서는 이를 구체적으로 밝힙니다.

시작 권한 모드를 정할 대상방법
곧 시작할 한 세션권한 모드를 플래그로 전달합니다. 예: claude --permission-mode default
이 컴퓨터에서 시작하는 모든 터미널 세션~/.claude/settings.json에 permissions.defaultMode를 설정합니다
한 프로젝트에서 시작하는 모든 터미널 세션프로젝트의 .claude/settings.json에 permissions.defaultMode를 설정합니다. 터미널에서 시작하는 세션은 auto와 bypassPermissions를 제외한 모든 값을 따릅니다
조직 내 모든 터미널 세션관리형 설정에 permissions.defaultMode를 설정합니다

.claude/settings.json이나 .claude/settings.local.json에 "auto"를 설정하면 그 값은 적용되지 않습니다. 그 두 파일에 "bypassPermissions"를 설정해도 적용되지 않으며, 세션은 Manual 모드로 시작합니다. 다음 예시는 이 컴퓨터의 모든 터미널 세션이 Manual 모드로 시작하게 합니다. ~/.claude/settings.json에 저장하세요.

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

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

acceptEdits: 파일 편집 자동 승인

acceptEdits 모드에서는 Claude가 작업 디렉터리의 파일을 묻지 않고 만들고 편집할 수 있습니다. 이 모드가 활성화되어 있는 동안 상태 표시줄에 ⏵⏵ accept edits on이 표시됩니다. 파일 편집 외에도 일반적인 파일 시스템 Bash 명령인 mkdir, touch, rm, rmdir, mv, cp, sed를 자동 승인합니다. 파일 편집과 마찬가지로 자동 승인은 작업 디렉터리나 additionalDirectories 안의 경로에만 적용됩니다.

다음은 여전히 프롬프트가 뜹니다.

편집을 하나씩 인라인으로 승인하기보다 나중에 편집기나 git diff로 변경 사항을 검토하고 싶을 때 acceptEdits를 쓰라고 문서는 권합니다. Manual 모드에서 Shift+Tab을 한 번 눌러 진입하거나, 바로 이 모드로 시작하세요.

claude --permission-mode acceptEdits

plan: 먼저 조사하고, 편집은 하지 않음

plan 모드는 Claude가 변경을 실행하지 않고 조사하고 제안하게 합니다. Claude는 파일을 읽고, 탐색을 위해 셸 명령을 실행하고, 계획을 작성하지만 소스는 편집하지 않습니다. bypass permissions를 쓸 수 있는 대화형 터미널 세션을 제외하면, 계획을 승인할 때까지 편집은 계속 차단됩니다.

계획 중 셸 명령이 어떻게 처리되는지는 세션에 따라 다르며, 아래 경우 중 먼저 일치하는 것이 적용됩니다.

Shift+Tab을 누르거나 프롬프트 하나 앞에 /plan을 붙여 plan 모드로 들어갑니다. CLI에서 plan 모드로 바로 시작할 수도 있습니다.

claude --permission-mode plan

계획을 승인하지 않고 plan 모드를 나가려면 Shift+Tab을 다시 누르세요. 계획이 준비되면 Claude가 계획을 제시하고 어떻게 진행할지 묻습니다.

Claude가 진행하기 전에 제안된 계획을 기본 텍스트 편집기에서 열어 직접 수정하려면 Ctrl+G를 누르세요. 프로젝트의 터미널 세션에서 plan 모드를 기본값으로 만들려면 .claude/settings.json에서 defaultMode를 plan으로 설정하세요.

auto: 분류기가 대신 검토

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

문서의 경고: auto 모드는 권한 프롬프트를 줄여 주지만 안전을 보장하지는 않습니다. 대체로 방향을 신뢰하는 작업에 쓰고, 민감한 작업에서 검토를 대신하는 용도로 쓰지 마세요.

auto 모드는 계정이 다음 요건을 모두 충족할 때만 쓸 수 있습니다.

문서의 더 긴 목록 중 기본적으로 차단되는 것은 curl | bash 같은 코드 다운로드 및 실행, 민감한 데이터의 외부 엔드포인트 전송, 프로덕션 배포와 마이그레이션, force push, IAM이나 저장소 권한 부여, 세션 이전부터 있던 파일의 되돌릴 수 없는 삭제입니다. 기본적으로 허용되는 것은 작업 디렉터리 안의 로컬 파일 작업, lock 파일이나 매니페스트에 선언된 의존성 설치, 읽기 전용 HTTP 요청입니다. 전체 규칙 목록을 JSON으로 출력하려면 claude auto-mode defaults를 실행하세요.

분류기는 대화에서 밝힌 경계를 차단 신호로 취급합니다. Claude에게 "푸시하지 마"라고 하면 기본 규칙이 허용하는 경우에도 해당하는 동작을 차단합니다. 다만 경계는 규칙으로 저장되지 않으며, 컨텍스트 압축으로 그 경계를 밝힌 메시지가 사라질 수 있습니다. 확실한 보장이 필요하면 대신 deny 규칙을 추가하라고 문서는 안내합니다.

대체 동작(fallback): 차단된 동작은 알림으로 표시되고 /permissions의 Recently denied 탭에 나열되며, 거기서 r을 눌러 수동 승인으로 다시 시도할 수 있습니다. 분류기가 연속 3번 또는 총 20번 동작을 차단하면 auto 모드가 일시 중지되고 Claude Code가 다시 프롬프트를 띄웁니다. 프롬프트가 뜬 동작을 승인하면 auto 모드가 재개됩니다. 이 임계값은 설정할 수 없습니다.

비용과 지연: 문서에 따르면 분류기 요청은 /model에서 선택한 것과 다른 모델에서 실행될 수 있습니다. Enterprise 플랜과 Claude API, Claude Platform on AWS, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry를 쓰는 계정에서는 분류기 호출이 토큰 사용량에 포함됩니다. 각 검사는 대화 기록의 일부와 대기 중인 동작을 보내므로 실행 전에 왕복이 한 번 추가됩니다. 읽기와 보호된 경로 밖의 작업 디렉터리 편집은 분류기를 건너뛰므로, 오버헤드는 주로 셸 명령과 네트워크 작업에서 생깁니다. 서버가 세션의 모델 요청의 일부로 동작을 검토하는 경우에는 별도의 분류기 호출이 없습니다. ANTHROPIC_BASE_URL을 LLM 게이트웨이나 프록시로 지정하면 Claude Code v2.1.278 이상은 기본적으로 서버에 묻지만, 게이트웨이나 프록시가 검토 요청이나 결과를 버리면 자체 분류기 요청으로 대체합니다. /status에서 Auto mode server가 Enabled로 표시되면 서버의 검토 대상이 아닌 호출에만 분류기 요청이 전송됩니다. 비용 측면은 토큰을 덜 쓰는 방법을 참고하세요.

bypassPermissions: 모든 검사 건너뛰기

bypassPermissions 모드는 권한 프롬프트와 안전 검사를 끄므로, 보호된 경로에 대한 쓰기를 포함해 도구 호출이 즉시 실행됩니다. "권한 프롬프트 건너뛰기"를 검색하는 대부분의 사람이 찾는 모드가 바로 이것이며, 문서의 경고는 단호합니다.

문서의 경고: 이 모드는 Claude Code가 호스트 시스템을 손상시킬 수 없는, 인터넷에 접근할 수 없는 컨테이너, VM, dev container 같은 격리된 환경에서만 쓰세요.

문서의 경고: bypassPermissions는 프롬프트 인젝션이나 의도치 않은 동작에 대한 보호를 전혀 제공하지 않습니다. 권한 프롬프트를 훨씬 줄이면서 백그라운드 안전 검사를 원한다면 대신 auto 모드를 쓰세요. 관리자는 관리형 설정에서 permissions.disableBypassPermissionsMode를 "disable"로 설정해 이 모드를 막을 수 있습니다.

활성화하는 방법과 제한은 다음과 같습니다.

이 모드에서도 어떤 모드도 자동 승인하지 않는 동작은 각각 프롬프트나 거부가 따릅니다. 명시적인 ask 규칙에 일치하는 도구, AskUserQuestion처럼 사용자 상호작용이 필요한 도구, rm -rf /나 rm -rf ~ 같은 인식된 rm과 rmdir의 핵심 경로 삭제가 그렇습니다. 또 핵심 경로 검사가 일부 명령을 놓칠 수 있으므로 샌드박싱 같은 운영 체제 수준 통제를 대신하지 못한다고 문서는 지적합니다.

dontAsk: 사전 승인된 도구만

dontAsk 모드를 설정하면 Claude Code는 원래라면 프롬프트가 떴을 모든 도구 호출을 자동으로 거부합니다. 작업 디렉터리 안의 파일 읽기, 읽기 전용 Bash 명령, permissions.allow 규칙에 일치하는 동작, PreToolUse hook이 승인한 호출은 계속 실행됩니다. Claude가 할 수 있는 일을 미리 정의해 두는 CI 파이프라인이나 제한된 환경에서 쓰라고 문서는 권하며, 세션이 입력을 기다리는 일은 없습니다. hook 작성법은 hooks 가이드를 참고하세요. 시작할 때 플래그로 설정합니다.

claude --permission-mode dontAsk

정확한 허용 목록을 쓰는 CI에 대한 문서의 예시입니다.

claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"

일괄 모드 대신 규칙

문서에 따르면 모드는 기준선을 정하고, 그 위에 권한 규칙을 겹쳐 특정 도구를 사전 승인하거나 차단할 수 있습니다.

규칙 문법은 Anthropic의 Permissions 문서에 있습니다. /permissions 명령은 Claude Code 명령어를 참고하세요.

보호된 경로

일부 경로에 대한 쓰기는 bypassPermissions 모드(그리고 bypass permissions를 쓸 수 있는 대화형 터미널 세션의 plan 모드)를 제외하고는 자동 승인되지 않습니다. 저장소 상태와 Claude 자체 설정이 실수로 손상되는 것을 막기 위해서입니다. default와 acceptEdits에서는 프롬프트가 뜨고, auto에서는 분류기로 가고, dontAsk에서는 거부됩니다. 보호된 디렉터리에는 .git, .vscode, .idea, .husky, .claude(몇 가지 예외 있음)가 있고, 보호된 파일에는 .gitconfig, .bashrc, .zshrc, .npmrc, .mcp.json, .claude.json 등이 있습니다. 전체 목록은 문서의 Protected paths 절에 있습니다. 설정 파일의 permissions.allow 규칙은 보호된 경로에 대한 쓰기를 사전 승인하지 않습니다.

어떤 모드를 써야 할까

다음 제안은 위 절을 우리가 해석한 것이며, 공식 의사결정 트리가 아닙니다.

FAQ

Claude Code가 계속 권한을 묻지 않게 하려면 어떻게 하나요?

먼저 현재 모드를 확인하세요. 상태 표시줄에 표시되고 Shift+Tab으로 순환합니다. 프롬프트를 줄이는 문서의 옵션은 덜 열린 것부터 가장 열린 것 순으로 acceptEdits(파일 편집과 일반적인 파일 시스템 명령은 프롬프트 없음), auto(분류기가 대신 검토), bypassPermissions(모든 검사 해제, 격리된 환경 전용)입니다. 문서는 bypassPermissions가 프롬프트 인젝션에 대한 보호를 제공하지 않는다고 분명히 밝히며, 백그라운드 안전 검사와 함께 프롬프트를 훨씬 줄이려면 auto 모드를 쓰라고 합니다.

auto 모드를 쓸 수 없거나 세션이 Manual로 시작한 이유는 무엇인가요?

문서가 드는 원인은 이렇습니다. 세션이 사용 가능 요건을 충족하지 못하거나(지원되지 않는 모델, 또는 설정 파일의 disableAutoMode), Anthropic이 서버 쪽에서 일시적으로 껐을 수 있습니다. 놓치기 쉬운 점이 하나 있습니다. .claude/settings.json이나 .claude/settings.local.json의 defaultMode: "auto"는 적용되지 않으므로, 터미널 세션은 오류 없이 Manual로 시작합니다. ~/.claude/settings.json으로 옮기세요. VS Code에서 claudeCode.initialPermissionMode는 auto를 받지 않으므로, 대신 모드 표시기에서 Auto를 한 번 선택하세요.

bypassPermissions는 정말 한 번도 묻지 않나요?

아닙니다. 문서에 따르면 이 모드에서도 명시적인 ask 규칙, AskUserQuestion처럼 사용자 상호작용이 필요한 도구, 인식된 rm과 rmdir의 핵심 경로 삭제는 여전히 프롬프트가 뜨거나 거부되며, deny 규칙도 계속 차단합니다. 그렇다고 안전하다는 뜻은 아닙니다. 문서는 이 모드가 프롬프트 인젝션이나 의도치 않은 동작에 대한 보호를 제공하지 않는다고도 하며, 그래서 격리된 환경에서만 써야 합니다.

출처