권한 모드

Claude Code는 파일 수정, 명령어 실행 등 실제 시스템에 영향을 주는 작업을 합니다. 이런 작업을 얼마나 자유롭게 허용할지 결정하는 것이 권한 시스템입니다.

권한 계층

Claude Code는 도구 유형에 따라 승인 수준이 다릅니다:

도구 유형	예시	승인 필요	"다시 묻지 않기" 범위
읽기 전용	파일 읽기, Grep, Glob	불필요	-
Bash 명령	셸 실행	필요	프로젝트 디렉토리당 영구 저장
파일 수정	Edit, Write	필요	세션 종료까지

6가지 권한 모드

모드	설명	사용 시점
`manual` (구 `default`)	도구 첫 사용 시 승인 요청	일반적인 개발 작업
`acceptEdits`	파일 수정 자동 승인	신뢰할 수 있는 로컬 개발
`plan`	분석만 가능, 수정/실행 불가	코드 탐색, 아키텍처 검토
`auto`	분류기가 자동 승인/차단	장시간 작업, 프롬프트 피로 감소
`dontAsk`	사전 승인된 도구만 허용, 나머지 자동 거부	제한된 자동화
`bypassPermissions`	모든 승인 건너뜀	격리된 컨테이너/VM만

v2.1.200 — default 모드 → Manual 개칭

v2.1.200부터 기본(default) 모드의 이름이 CLI·--help·VS Code·JetBrains 전반에서 Manual 모드로 바뀌었습니다. --permission-mode manual·"defaultMode": "manual" 표기가 기존 default와 나란히 인식되므로 기존 설정은 그대로 동작합니다. v2.1.203부터는 Manual 모드일 때 푸터에 회색 ⏸ 배지가 표시되어 현재 모드를 항상 확인할 수 있습니다.

실시간 모드 전환

세션 중에 Shift+Tab 또는 Alt+M으로 모드를 실시간 전환할 수 있습니다:

Manual(기본) 모드 → Shift+Tab → 자동승인 모드 → Shift+Tab → Plan 모드 → Shift+Tab → Auto 모드 → ...

Auto 모드 표시 조건

Shift+Tab 순환에 Auto 모드가 나타나려면 계정이 사용 조건(아래 표)을 충족해야 합니다. 모든 플랜에서 쓸 수 있으며(Pro 포함), Anthropic API 기준 Opus 4.6 이상 또는 Sonnet 4.6 모델이 필요합니다.

승인 옵션 이해하기

Manual(기본) 모드에서 Claude가 승인을 요청할 때:

Claude: auth/login.ts를 생성하겠습니다. 허용하시겠습니까?
[y] Yes  [n] No  [a] Always allow this type  [d] Don't allow

Bash 명령 실행 승인 시에는 Auto 모드로의 빠른 전환 옵션이 추가로 제공됩니다 (v2.1.247+):

[y] Yes  [n] No  [a] Always allow  [s] Yes, and switch to auto mode

선택	의미
`y` (Yes)	이번 한 번만 허용
`n` (No)	거절, Claude가 다른 방법 시도
`a` (Always)	이 세션에서 같은 종류 작업 자동 허용
`s` (Switch to Auto)	명령을 승인함과 동시에 세션을 Auto 모드로 즉시 전환 (Bash 프롬프트 전용)
`d` (Don't allow)	이 세션에서 이 종류 작업 항상 거절

bypassPermissions 주의

bypassPermissions 모드는 모든 권한 검사를 비활성화합니다. 격리된 환경(Docker, VM)에서만 사용하세요. 조직 관리자는 managed settings에서 disableBypassPermissionsMode: "disable"로 이 모드를 차단할 수 있습니다.

Auto 모드 — 분류기 기반 자동 승인

Auto 모드는 매번 수동으로 승인하는 대신, 백그라운드 분류기(Anthropic이 서버 측에서 결정하는 모델로, 사용자의 /model 선택과 무관)가 각 도구 호출을 자동으로 평가합니다. bypassPermissions처럼 모든 걸 허용하는 것이 아니라, 작업 맥락에 맞는지 판단한 뒤 안전한 것만 실행합니다.

분류기 호출 쿼터 미차감

Auto 모드에서 도구 호출의 안전성을 평가하기 위해 백그라운드로 호출되는 분류기(classifier) 사용량은 플랜의 사용량 한도(Usage Limits)에 전혀 차감되지 않습니다. 비용 부담 없이 안심하고 Auto 모드를 켜둘 수 있습니다.

Claude Code v2.1.83+ 필요 (v2.1.224+ 기본값)

Auto 모드는 v2.1.83 이상에서 동작하며, 2026년 8월 14일(v2.1.224+)부터 Pro, Max, Team 플랜의 새 세션 기본 권한 모드가 Auto 모드로 전환되었습니다 (사용자가 명시적으로 defaultMode를 지정한 경우는 제외).

사용 조건 (전부 충족 필요)

항목	요구사항
플랜	모든 플랜 (Pro 포함 — 이전엔 Team 이상이었으나 확대됨)
모델	Anthropic API: Opus 4.6 이상 또는 Sonnet 4.6 Bedrock·Vertex·Foundry: Opus 4.7·4.8만 Sonnet 4.5·Opus 4.5·Haiku·claude-3 계열은 미지원
Provider	Anthropic API·Bedrock·Vertex AI·Foundry 모두 기본 사용 가능 — v2.1.207부터 Bedrock·Vertex·Foundry도 `CLAUDE_CODE_ENABLE_AUTO_MODE=1` opt-in 없이 동작. 차단하려면 settings의 `disableAutoMode` 사용
Admin (Team/Enterprise)	관리자가 Claude Code Admin Settings에서 활성화 필요. `permissions.disableAutoMode: "disable"`로 lock 가능
활성화	CLI: `--permission-mode auto` 또는 세션 중 `Shift+Tab`으로 모드 사이클. Desktop/VS Code: 모드 선택기에서 "자동 모드" 또는 "Auto mode" 선택

# CLI에서 Auto 모드로 시작 (Pro/Max/Team은 기본값이므로 별도 플래그 없이 바로 적용)
claude

평가 순서

각 도구 호출은 다음 순서로 평가됩니다:

allow/deny 규칙에 매칭 → 즉시 허용/차단
읽기 전용 + 작업 디렉토리 내 파일 수정 → 자동 승인
그 외 → 분류기 평가
분류기 차단 시 → Claude가 대안 시도

v2.1.193 — 거부 사유 표시·셸 전수 분류

분류기가 차단하면 거부 사유가 transcript·거부 토스트·/permissions(최근 거부 내역)에 표시되어 왜 막혔는지 바로 확인할 수 있습니다. 또 settings의 autoMode.classifyAllShell을 켜면 모든 Bash·PowerShell 명령이 분류기를 거치도록 할 수 있습니다.

기본 차단 목록

분류기가 기본적으로 차단하는 행위:

다운로드한 코드 실행 (curl | bash, 클론한 repo의 스크립트)
외부 엔드포인트로 민감 데이터 전송
프로덕션 배포/마이그레이션
클라우드 스토리지 대량 삭제
IAM/repo 권한 변경
main 브랜치 직접 push, force push
세션 시작 전 존재하던 파일의 비가역적 삭제
로컬 작업물을 버리는 파괴적 git 명령 (git reset --hard·git checkout -- .·git clean -fd·git stash drop) — "버려달라"고 명시적으로 요청하지 않은 경우 (v2.1.183 강화)
git commit --amend — 이번 세션에서 에이전트가 만든 커밋이 아닌 경우 (v2.1.183 강화)
인프라 파괴 명령 (terraform destroy·pulumi destroy·cdk destroy) — 특정 스택을 지정해 요청하지 않은 경우 (v2.1.183 강화)
세션 transcript(대화 기록) 파일 변조 (v2.1.205 강화)
값을 확인할 수 없는 변수 대상 rm -rf — 차단 대신 실행 전 확인을 요청 (v2.1.206 강화)
격리 탈출(Containment Escape) 시도 차단 (v2.1.257 강화) — 클라우드 인스턴스 메타데이터 자격 증명 탈취(예: AWS 169.254.169.254, GCP metadata), 네트워크 송신 우회(egress evasion), 테넌트 경계를 넘는 비인가 접근은 환경에서 명시적으로 허용하지 않는 한 자동 승인되지 않고 차단
작업 디렉토리 외부 읽기 차단 (permissions.blockReadsOutsideWorkingDirectories) (v2.1.257) — Auto 모드에서 작업 디렉토리 바깥의 파일을 처음 읽으려 할 때 1회 확인 프롬프트가 표시되며, 설정을 통해 외부 파일 읽기를 완전 차단 가능

v2.1.183 ~ v2.1.257 — Auto 모드 안전 강화

(v2.1.183 강화) 핵심은 "시키지 않았는데 작업물을 날리는" 명령을 막는다는 것입니다. 사용자가 직접 "이 변경 전부 버려줘", "이 스택 destroy 해줘"라고 요청하면 통과하고, 그런 맥락 없이 분류기가 보기에 비가역적 파괴면 차단합니다. v2.1.257부터는 클라우드 메타데이터 조회나 네트워크 우회 같은 격리 탈출(Containment Escape) 공격 패턴이 차단 목록에 포함되었고, 작업 디렉토리 바깥의 파일을 읽으려 할 때도 1회성 확인을 거치도록 보강되었습니다.

분류기가 기본적으로 허용하는 행위:

작업 디렉토리 내 파일 작업
lock 파일에 선언된 의존성 설치
.env 읽기 및 해당 API로 인증 전송
읽기 전용 HTTP 요청
현재 브랜치 또는 Claude가 생성한 브랜치에 push

기본 규칙 확인

claude auto-mode defaults 명령으로 분류기가 사용하는 전체 규칙 목록을 확인할 수 있습니다. 설정을 만졌다가 초기 상태로 되돌리고 싶으면 claude auto-mode reset을 쓰세요 (v2.1.212 — 확인 프롬프트가 뜨며 --yes로 생략 가능).

폴백 동작

분류기가 연속 3회 또는 세션 내 총 20회 차단하면, Auto 모드가 일시 중지되고 수동 승인으로 전환됩니다. 수동 승인 후 카운터가 리셋되어 Auto 모드를 계속 사용할 수 있습니다.

Auto 모드 vs bypassPermissions

	Auto	bypassPermissions
안전 검사	분류기가 매 행위 평가	없음
사용 환경	일반 개발 환경	격리된 컨테이너/VM만
토큰 비용	분류기 호출로 추가 비용	표준
프롬프트	폴백 시에만	없음

Auto 모드 주의사항

Auto 모드는 research preview입니다. 수동 검토보다 보호 수준이 낮으며, 민감한 작업에는 Manual(기본) 모드를 사용하세요. 관리자는 disableAutoMode: "disable" 설정으로 이 모드를 차단할 수 있습니다.

권한 규칙 관리

/permissions 커맨드로 현재 규칙을 확인하고 관리합니다:

/permissions

[Permissions] [Auto mode]  <-- v2.1.246+ 탭 분리

Allow:
  - Read(*)
  - Edit(/src/**)
  - Bash(npm test *)

Deny:
  - Bash(rm *)
  - Bash(git push *)

Auto mode 탭 (v2.1.246+): 일반 권한 규칙 탭 옆에 Auto mode 탭이 신설되어, 자동 모드 분류기(classifier)가 참조하는 규칙 목록을 직접 조회하고 편집할 수 있습니다.
규칙 평가 순서: deny → ask → allow. deny가 항상 우선합니다.

Bash 규칙 작성 시 주의사항 (v2.1.246+)

Bash(git * main)처럼 서브커맨드 앞에 와일드카드가 들어간 allow 규칙은 서브커맨드 사이에 다른 옵션이 끼어들어도 매칭될 수 있어 시작 시 경고를 출력합니다. 가급적 Bash(git checkout main)처럼 서브커맨드를 명확히 지정하세요.

권한 규칙 문법

기본 형식

도구명 또는 도구명(지정자) 형식입니다.

{
  "permissions": {
    "allow": [
      "Read",                    // 모든 파일 읽기 허용
      "Bash(npm run *)",         // npm run으로 시작하는 모든 명령
      "Edit(/src/**/*.ts)"       // src 하위 TypeScript 파일만 수정
    ],
    "deny": [
      "Bash(rm *)",              // rm 명령 차단
      "Bash(git push *)"         // git push 차단
    ]
  }
}

Bash 규칙: 와일드카드 매칭

*는 글로브 패턴으로 동작합니다. 명령어 어디에서든 사용 가능합니다:

규칙	매칭
`Bash(npm run build)`	정확히 `npm run build`만
`Bash(npm run *)`	`npm run test`, `npm run lint` 등
`Bash(* --version)`	`node --version`, `npm --version` 등
`Bash(git * main)`	`git checkout main`, `git merge main` 등

공백+* vs *

Bash(ls *)는 ls -la에 매칭되지만 lsof에는 매칭되지 않습니다. 공백이 단어 경계를 강제합니다. Bash(ls*)는 둘 다 매칭됩니다.

셸 연산자 인식

Claude Code는 && 같은 셸 연산자를 인식합니다. Bash(safe-cmd *)는 safe-cmd && dangerous-cmd를 허용하지 않습니다.

Read/Edit 규칙: gitignore 스타일 패턴

파일 경로 규칙은 gitignore 스펙을 따릅니다:

패턴	의미	예시
`//path`	파일시스템 절대 경로	`Read(//Users/alice/secrets/**)`
`~/path`	홈 디렉토리 기준	`Read(~/Documents/*.pdf)`
`/path`	프로젝트 루트 기준	`Edit(/src/*/.ts)`
`path`	현재 디렉토리 기준	`Read(*.env)`

{
  "permissions": {
    "allow": [
      "Edit(/docs/**)",          // 프로젝트 docs/ 하위만 수정 허용
      "Read(~/.zshrc)"           // 홈 디렉토리 .zshrc 읽기 허용
    ],
    "deny": [
      "Read(.env)",              // .env 파일 읽기 차단
      "Edit(//etc/*)"            // /etc/ 수정 차단
    ]
  }
}

* vs **

*는 한 디렉토리 내 파일만 매칭, **는 하위 디렉토리까지 재귀적으로 매칭합니다.

MCP 도구 규칙

{
  "permissions": {
    "allow": [
      "mcp__puppeteer",                       // puppeteer 서버의 모든 도구
      "mcp__github__github_list_repos"         // github 서버의 특정 도구만
    ]
  }
}

서브에이전트(Task) 규칙

{
  "permissions": {
    "deny": [
      "Agent(Explore)"           // Explore 서브에이전트 비활성화
    ]
  }
}

파라미터 매칭 규칙 — `Tool(param:value)`

v2.1.178부터 도구의 입력 파라미터 값으로 규칙을 매칭할 수 있습니다. 도구(파라미터:값) 형식이며 값에 * 와일드카드를 쓸 수 있습니다.

{
  "permissions": {
    "deny": [
      "Agent(model:opus)"        // Opus 모델을 쓰는 서브에이전트 차단
    ]
  }
}

Agent(model:opus)는 서브에이전트가 Opus 모델로 실행되는 것을 막습니다(비용 통제 등). 기존 Agent(Explore)가 서브에이전트 종류로 매칭한다면, Tool(param:value)는 입력 값 단위로 더 세밀하게 제어합니다.

settings.json 계층

권한 규칙은 여러 위치에 정의할 수 있으며, 우선순위는:

Managed (조직) → CLI 인수 → Local 프로젝트 → Shared 프로젝트 → User 전역

위치	파일	우선순위
조직 관리형	MDM/서버 정책	최고
CLI 인수	`--allowedTools`, `--disallowedTools`	높음
로컬 프로젝트	`.claude/settings.local.json`	중간
공유 프로젝트	`.claude/settings.json`	중간
전역 사용자	`~/.claude/settings.json`	낮음

프로젝트 설정이 사용자 설정보다 우선합니다. 사용자 settings에서 허용하더라도 프로젝트 settings에서 거부하면 차단됩니다.

추가 디렉토리 접근

기본적으로 Claude는 실행 디렉토리의 파일만 접근합니다. 추가 디렉토리를 열려면:

# 시작 시 추가
claude --add-dir /path/to/other-project

# 세션 중 추가
/add-dir /path/to/other-project

샌드박스와의 관계

권한(permissions)과 샌드박스(sandboxing)는 상호 보완적입니다:

	권한	샌드박스
적용 대상	모든 도구	Bash 명령만
동작	Claude의 도구 사용 제어	OS 수준 파일/네트워크 격리
방어	Claude의 의사결정 제한	프롬프트 인젝션 우회 방지

둘을 함께 사용하면 **심층 방어(defense-in-depth)**를 구현할 수 있습니다.

📬 매주 Claude Code 실전 팁을 이메일로

권한 설정부터 자동화까지 — 실제 사용 경험을 정리해서 보내드립니다. 무료 구독 →

모드 선택 가이드

지금 뭘 하려고?
│
├─ 새 코드베이스 탐색/이해
│   → Plan 모드 (읽기 전용)
│
├─ 혼자 로컬에서 빠르게 개발
│   → acceptEdits 또는 Manual(기본) 모드 (git 커밋 먼저)
│
├─ 장시간 리팩토링, 승인 피로 줄이기
│   → Auto 모드 (분류기가 대신 판단)
│
├─ 팀 프로젝트, 중요한 코드
│   → Manual(기본) 모드 + 프로젝트 settings.json에 규칙 정의
│
├─ CI/CD, 자동화 스크립트
│   → 헤드리스 모드 + allowedTools 지정
│
└─ 격리된 Docker/VM 테스트 환경
    → bypassPermissions (주의!)

실전 설정 예시

안전한 개발 환경

{
  "permissions": {
    "allow": [
      "Read",
      "Edit(/src/**)",
      "Bash(npm test *)",
      "Bash(npm run lint *)",
      "Bash(git diff *)",
      "Bash(git status *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(git push *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Edit(*.env)"
    ]
  }
}

CI/CD 환경 (헤드리스)

claude -p "코드 리뷰해줘" \
  --allowedTools "Read,Grep,Glob" \
  --disallowedTools "Bash,Edit,Write"

무인 헤드리스 환경 (`--permission-prompts none`)

CI 러너나 백그라운드 워커처럼 사용자가 터미널 입력을 줄 수 없는 환경에서는 --permission-prompts none을 지정합니다 (v2.1.259+):

claude -p "테스트 및 빌드 검증" --permission-prompts none

사람의 승인 입력이 필요한 상황이 발생하면 세션이 멈춰서 기다리는 대신 **해당 도구 호출을 즉시 자동 거부(deny)**합니다.
Auto 모드를 포함한 현재 권한 판정 엔진은 그대로 작동하므로, 안전한 명령은 정상 실행되면서 입력 대기 교착(hang)만 원천 방지합니다.

신뢰할 수 없는 저장소 격리 (`--restricted`)

외부에서 클론한 오픈소스나 검증되지 않은 리포지토리를 열 때는 --restricted 플래그(또는 CLAUDE_CODE_RESTRICTED=1)를 사용합니다 (v2.1.248+):

claude --restricted

셸 명령 실행(Bash), 임의 코드 실행, WebFetch 등 외부 영향을 줄 수 있는 내장 도구가 완전 제거됩니다 (--tools로 명시하지 않는 한 비활성).
파일 도구(Read, Edit, Write)는 현재 작업 디렉토리 내부로만 강제 제한됩니다.
bypassPermissions 모드 진입이 거부되며, 사용자/프로젝트/로컬의 settings.json 권한 재정의를 무시합니다.

이 페이지에 오류가 있나요? 오류 제보하기 →

권한 계층​

6가지 권한 모드​

실시간 모드 전환​

승인 옵션 이해하기​

Auto 모드 — 분류기 기반 자동 승인​

사용 조건 (전부 충족 필요)​

평가 순서​

기본 차단 목록​

폴백 동작​

Auto 모드 vs bypassPermissions​

권한 규칙 관리​

권한 규칙 문법​

기본 형식​

Bash 규칙: 와일드카드 매칭​

Read/Edit 규칙: gitignore 스타일 패턴​

MCP 도구 규칙​

서브에이전트(Task) 규칙​

파라미터 매칭 규칙 — Tool(param:value)​

settings.json 계층​

추가 디렉토리 접근​

샌드박스와의 관계​

모드 선택 가이드​

실전 설정 예시​

안전한 개발 환경​

CI/CD 환경 (헤드리스)​

무인 헤드리스 환경 (--permission-prompts none)​

신뢰할 수 없는 저장소 격리 (--restricted)​