Claude Code 권한 설정 — allow·deny 규칙과 권한 모드

Claude Code는 파일 편집, 명령 실행, 웹 접근 같은 도구 사용을 권한 규칙으로 통제합니다. 무엇을 자동으로 허용하고, 무엇을 매번 확인하며, 무엇을 아예 차단할지를 settings.json과 권한 모드로 정할 수 있습니다. 이 글은 권한 규칙 세 종류와 평가 순서, 설정 파일 레벨, 권한 모드를 공식 문서 기준으로 정리합니다. (세부 옵션은 변동될 수 있으니 공식 권한 문서에서 최신 내용을 확인하세요.)

세 가지 권한 규칙

Claude Code의 권한은 settings.json의 permissions 객체 안에서 세 가지 목록으로 나뉩니다.

• allow — 해당 도구를 확인 없이 자동으로 사용합니다. 매번 승인을 누르는 번거로움을 줄입니다.
• ask — 도구를 사용하려 할 때마다 확인을 묻습니다.
• deny — 해당 도구를 차단합니다. 가장 강력한 규칙입니다.

터미널에서 /permissions 명령을 실행하면 현재 적용된 규칙과 그 규칙이 어떤 settings.json에서 왔는지를 한눈에 볼 수 있습니다.

평가 순서 — deny → ask → allow

규칙은 항상 deny → ask → allow 순서로 검사되며, 처음 매치된 규칙이 결과를 정합니다. 규칙의 구체성(specificity)은 이 순서를 바꾸지 않습니다. 예를 들어 어떤 명령에 매치되는 ask 규칙이 있으면, 같은 명령에 더 구체적인 allow 규칙이 있더라도 확인을 먼저 묻습니다. 또한 deny 규칙은 권한 우회 모드에서도 차단됩니다.

규칙 형식과 와일드카드

규칙은 Tool(도구 전체) 또는 Tool(specifier)(범위 지정) 형식으로 씁니다. * 와일드카드를 쓸 수 있습니다.

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git status)"],
    "ask":   ["Bash(git push *)"],
    "deny":  ["Read(./.env)", "Read(./.env.*)", "Bash(rm -rf *)"]
  }
}

한 가지 중요한 차이가 있습니다. deny에 도구 이름만 적으면(예: Bash) 그 도구가 Claude의 컨텍스트에서 통째로 사라져 Claude가 아예 인식하지 못합니다. 반면 범위를 지정하면(예: Bash(rm *)) 도구는 그대로 쓸 수 있되 매치되는 호출만 차단됩니다. MCP 도구는 괄호 없이 더블 언더스코어 형식으로 표기합니다. MCP를 처음 다룬다면 MCP 연결 방법을 참고하세요.

설정 파일은 레벨이 있다

설정은 한 곳이 아니라 여러 레벨에 둘 수 있습니다. 대표적으로 사용자 레벨 ~/.claude/settings.json(모든 프로젝트에 적용), 프로젝트 레벨 .claude/settings.json(레포에 커밋해 팀과 공유), 그리고 조직이 강제하는 관리형(enterprise) 설정이 있습니다. 관리형 설정의 deny는 사용자가 임의로 풀 수 없어, 팀 차원의 안전선을 강제하는 데 쓰입니다. 정확한 우선순위 규칙은 버전에 따라 달라질 수 있으므로 공식 문서를 확인하세요. "무엇을 만들지"는 CLAUDE.md, "어떻게 동작할지"는 settings.json으로 나눠 관리하면 깔끔합니다.

권한 모드

(2026년 9월 7일 갱신 — 이 절은 공식 권한 모드 문서 최신본 기준으로 다시 정리했습니다.)

권한 모드(permission mode) — 세션 안에서 Claude가 묻지 않고 실행할 수 있는 작업 범위를 정하는 설정입니다. 앞의 규칙(allow·ask·deny)이 "어떤 도구를"이라면, 모드는 "기본적으로 얼마나 자율적으로"를 정합니다. 공식 문서 기준 모드는 여섯 가지입니다.

• auto — 분류기(classifier, 작업의 위험도를 판단하는 별도 모델)가 사용자 대신 각 작업을 검토합니다. 안전하다고 판단한 작업은 그대로 진행하고, 위험해 보이는 작업은 차단합니다. 긴 작업을 맡겨 두고 자리를 비울 때 쓰는 모드입니다. 명시적 ask 규칙에 걸리는 작업은 auto 모드에서도 여전히 확인을 묻습니다.
• default(화면 표기 Manual) — 허용 규칙에 없는 파일 편집·명령 실행·네트워크 접근을 매번 확인합니다. 민감한 작업이나 낯선 코드베이스에 맞습니다. 설정값은 default이고, Claude Code v2.1.200 이상에서는 manual이라는 별칭도 받아들입니다.
• acceptEdits — 작업 폴더 안의 파일 편집과 mkdir·mv·cp 같은 흔한 파일 명령은 묻지 않고 승인합니다. 편집 결과를 나중에 git diff로 검토하는 방식에 맞습니다.
• plan — 파일을 읽고 조사해 계획만 제시하고, 계획을 승인하기 전까지는 소스를 수정하지 않습니다. 상태 표시줄에 ⏸ plan mode on이 표시되며, claude --permission-mode plan으로 처음부터 이 모드로 시작할 수도 있습니다.
• dontAsk — 확인이 필요한 작업을 묻지 않고 자동 거부합니다. allow 규칙에 미리 적어 둔 도구와 읽기 전용 명령만 실행되므로, 사람이 답할 수 없는 CI 파이프라인이나 스크립트용입니다.
• bypassPermissions(CLI의 --dangerously-skip-permissions, 흔히 "YOLO 모드") — 확인과 안전 검사를 모두 건너뜁니다. 컨테이너, VM, 일회성 CI 러너처럼 환경 자체가 안전 경계를 제공하는 격리 환경에서만 쓰는 것이 안전합니다.

새 세션은 어떤 모드로 시작하나요?

공식 문서에 따르면 Pro·Max·Team 플랜은 터미널이나 VS Code 확장에서 새 세션을 열 때 auto 모드가 기본 시작 모드입니다(Claude Code v2.1.228 이상, 네이티브 Windows는 v2.1.233 이상). 반면 Enterprise 플랜이나 Console API 키로 쓰는 경우, 그리고 Amazon Bedrock 같은 외부 제공자 경유 세션과 claude -p 비대화형 실행은 Manual(default)로 시작합니다. 이 기본값 앞에 다음 두 가지가 우선합니다.

• claude --permission-mode <모드> 플래그(또는 --dangerously-skip-permissions)로 그 세션만 지정
• 설정 파일의 permissions.defaultMode로 기본값 지정 — 단 auto와 bypassPermissions는 프로젝트의 .claude/settings.json·settings.local.json에 적어도 적용되지 않으므로, 사용자 ~/.claude/settings.json이나 관리형 설정에 둬야 합니다

사용자 설정에 auto가 아닌 defaultMode를 이미 지정해 뒀다면 그 값이 그대로 유지되고, Claude Code가 auto로 바꿀지 한 번만 묻습니다. 조직이 관리형 설정에서 permissions.disableAutoMode를 "disable"로 두면 auto 모드 자체가 사라지고 Manual로 시작합니다. auto 모드는 지원 모델(Anthropic API 기준 Opus 4.6 이상·Sonnet 4.6 이상·Fable 계열 — 현행 Opus 5·Sonnet 5·Fable 5.1 포함)에서만 켜지며, 분류기 자체는 기본적으로 Claude Sonnet 5로 실행됩니다, 조건이 맞지 않으면 auto를 지정해도 Manual로 시작합니다.

세션 중 모드 바꾸기

터미널에서는 Shift+Tab을 누를 때마다 모드가 바뀝니다. 공식 문서가 밝힌 순환 순서는 다음과 같습니다.

• auto 모드에서 처음 누르면 default로 가고, 그다음부터 default → acceptEdits → plan → 다시 default 순으로 돕니다.
• auto는 사용할 수 있는 계정·모델일 때 plan 다음 자리에 끼어들고, bypassPermissions는 그 모드로 시작한 세션에서만 순환에 나타납니다. 둘 다 켜져 있으면 plan → bypassPermissions → auto 순입니다.
• dontAsk는 순환에 나타나지 않으며 --permission-mode dontAsk로만 지정합니다.

순환 순서를 외울 필요는 없습니다. 원하는 모드가 상태 표시줄에 표시될 때까지 누르면 됩니다. VS Code 확장은 입력창 아래 모드 표시기, 데스크톱 앱은 전송 버튼 옆 모드 선택기로 같은 일을 합니다. 대화창에서 "auto 모드로 바꿔 줘"라고 말하는 방식은 동작하지 않습니다.

어느 모드에서도 지켜지는 것

• deny 규칙은 여섯 모드 전부에서, 우회 모드를 포함해 차단됩니다.
• .git/·.claude/ 같은 보호 경로(protected paths) 쓰기는 bypassPermissions를 제외한 어떤 모드에서도 자동 승인되지 않습니다. Manual·acceptEdits에서는 확인을 묻고, auto에서는 분류기가 검토하며, dontAsk에서는 거부됩니다. 반대로 우회 모드에서는 보호 경로 쓰기도 허용되므로, 우회 모드를 격리 환경 밖에서 쓰지 말아야 하는 이유가 하나 더 있습니다.
• 루트·홈 폴더·작업 폴더 같은 핵심 경로(critical paths)를 지우는 rm·rmdir는 우회 모드에서도 확인을 묻고, auto 모드에서는 분류기로 넘어갑니다. allow 규칙으로도 이 확인을 없앨 수 없습니다.

안전하게 쓰는 기본 원칙

• 비밀 파일은 deny로 보호하세요 — 예: Read(./.env), Read(./.env.*), SSH 키 경로.
• 되돌리기 어려운 명령은 deny에 두세요 — 예: Bash(rm -rf *), 강제 푸시.
• 자주 반복 승인하는 안전한 명령(테스트·린트 등)은 allow로 올려 흐름을 끊지 않게 하세요.
• 우회 모드는 격리 환경에서만. 일상 작업에서는 auto(분류기 검토)나 Manual·acceptEdits처럼 확인 체계가 남아 있는 모드를 쓰세요.
• 샌드박싱은 권한과 별개의 보완 레이어입니다. 자동화 워크플로를 짠다면 훅(hooks)으로 도구 실행 전후에 검증을 끼워 넣을 수 있습니다.

Claude Code를 처음 쓰는 경우 Claude Code란 무엇인가와 설치 가이드를 먼저 보면 전체 그림이 잡힙니다.

권한 모드 절은 2026년 9월 7일 공식 권한 모드 문서 기준으로 다시 확인했고, 그 밖의 옵션·동작(권한 규칙 문법·defaultMode·disableAutoMode·/permissions)도 2026년 9월 9일 공식 permissions 문서와 재대조했으며 버전에 따라 달라질 수 있습니다. 파일 우선순위, 샌드박스 설정 등 세부 사항은 공식 권한 문서에서 최신 내용을 확인하세요. 본 사이트는 Anthropic 공식 사이트가 아닙니다.

관련 글

• Claude Code 설치 가이드: native vs npm, Windows까지
• 클로드 코드 사용법: 설치 후 실제로 쓰는 법 (명령·VS Code)
• Claude Code란? — 터미널에서 코딩하는 AI 에이전트 입문
• Claude Code IDE 연동: VS Code·JetBrains에서 쓰는 법 (2026)
• Claude Code vs Cursor(커서): 무엇이 다르고 뭘 골라야 할까