클로드 코드 권한 모드와 허용 규칙 설정하기
클로드 코드의 권한 모드는 도구를 쓰기 전에 사람에게 물어볼 범위를 정하는 설정이고, 허용 규칙은 특정 명령과 파일을 늘 허용하거나 막는 목록입니다. 모드는 Shift+Tab과 시작 옵션으로 바꾸고, 규칙은 settings.json의 allow, ask, deny에 적습니다.
같은 말:클로드 코드 권한 모드Shift+Tab 모드 전환acceptEditspermissions allow denydefaultMode
목차
이 글은 앤트로픽이 운영하는 code.claude.com/docs의 Permission modes, Permissions, Settings 문서를 한국어 사용자가 실무에 바로 옮길 수 있도록 정리한 글입니다. 모드 이름과 버전은 2026년 9월 28일 공식 문서 기준이고, 원문 링크는 글 끝 참고 자료에 모았습니다.
🤔 승인 창을 줄이고 싶은데 어디까지 열어도 될지 모를 때
클로드 코드를 며칠 쓰다 보면 npm test나 git status 같은 명령마다 승인 창이 뜨는 것이 번거로워집니다. 그렇다고 모든 행동을 자동으로 허락하자니 git push나 파일 삭제까지 묻지 않고 실행될까 걱정됩니다. 필요한 것은 모드 하나를 고르는 일이 아니라, 모드와 규칙을 조합해 자주 쓰는 명령은 열고 위험한 명령은 닫는 것입니다.
지금부터 여섯 가지 권한 모드의 차이와 전환 방법, 세션을 어떤 모드로 시작할지 정하는 법, allow와 ask와 deny 규칙을 쓰는 문법을 정리합니다. 자동 승인이 왜 위험한지, 무엇부터 막을지 같은 원칙은 코딩 에이전트 권한과 안전에 따로 정리했으므로 여기서는 설정 방법에 집중합니다.
🔑 권한 모드와 허용 규칙의 정의
클로드 코드의 권한 모드는 도구를 쓰기 전에 사람에게 물어볼 범위를 정하는 설정이고, 허용 규칙은 특정 명령과 파일을 늘 허용하거나 막는 목록입니다.
둘은 층이 다릅니다. 모드는 "대체로 얼마나 묻느냐"를 정하고, 규칙은 "이 명령은 항상 이렇게"를 정합니다. 공식 문서는 권한 규칙을 모델이 아니라 클로드 코드 프로그램이 강제한다고 적습니다. CLAUDE.md에 "push하지 마"라고 적는 것과 달리, deny 규칙은 모델이 어떻게 판단하든 막습니다.
🎚️ 여섯 가지 모드의 차이
| 모드 | 묻지 않고 하는 일 | 상태 표시 | 맞는 상황 |
|---|---|---|---|
default (화면 이름 Manual) | 읽기만 | ⏸ manual mode on | 처음 여는 저장소, 민감한 작업 |
acceptEdits | 읽기, 파일 수정, mkdir, mv, cp 같은 파일 명령 | ⏵⏵ accept edits on | 수정 결과를 나중에 한꺼번에 볼 때 |
plan | 읽기와 탐색 (소스는 고치지 않음) | ⏸ plan mode on | 고치기 전에 계획부터 볼 때 |
auto | 전부, 단 분류 모델이 실행 전 검사 | ⏵⏵ auto mode on | 긴 작업을 맡기고 승인 창을 줄일 때 |
dontAsk | 읽기와 미리 허용한 도구만, 물어볼 일은 모두 거부 | ⏵⏵ don't ask on | CI처럼 사람이 없는 환경 |
bypassPermissions | 전부, 검사 없음 | ⏵⏵ bypass permissions on | 격리된 컨테이너나 가상 머신 |
플랜 모드의 흐름은 입문 코스의 플랜 모드 활용하기에 있습니다. 중급에서 알아 둘 것은 계획을 승인하는 선택지가 세 가지로 나뉜다는 점입니다. Yes, and use auto mode를 고르면 auto로, Yes, manually approve edits를 고르면 수정마다 묻는 방식으로 실행되고, No, keep planning은 계획을 이어 갑니다. Ctrl+G를 누르면 계획을 기본 편집기에서 직접 고칠 수 있습니다.
dontAsk는 이름과 달리 "묻지 않고 다 한다"가 아니라 "물어볼 만한 일은 모두 거부한다"는 뜻입니다. 사람이 승인해 줄 수 없는 자동화 환경에서 쓰는 모드입니다.
🔁 세션 중에 모드를 바꾸는 방법
세션 안에서는 Shift+Tab으로 모드를 돌아가며 바꿉니다. 공식 문서가 적은 순서는 다음과 같습니다.
- auto에서 시작했다면 첫 번째 누름이
default로 바꿉니다 - 그다음부터
default→acceptEdits→plan→ 다시default순서로 돕니다 bypassPermissions나auto가 켜질 수 있는 세션이면plan뒤에 끼어듭니다
dontAsk는 이 순환에 나오지 않고 시작 옵션으로만 켭니다. bypassPermissions도 시작할 때 --permission-mode bypassPermissions나 --dangerously-skip-permissions를 주었거나 사용자 설정에 적어 둔 경우에만 순환에 들어갑니다. 플랜 모드는 프롬프트 앞에 /plan을 붙여 바로 들어갈 수도 있습니다(예: /plan 로그인 오류 원인 찾기).
v2.1.247 이상에서는 Manual이나 acceptEdits 상태에서 Bash 승인 창이 떴을 때 Yes, and switch to auto mode를 고르면 세션을 다시 시작하지 않고 auto로 넘어갑니다.
🚦 세션을 어떤 모드로 시작할지 정하기
시작 모드는 아래 순서에서 먼저 해당하는 것으로 정해집니다.
- 시작 옵션:
claude --permission-mode plan처럼 주거나--dangerously-skip-permissions - 설정 파일의
permissions.defaultMode - 내장 기본값: 대화형 터미널과 VS Code는 v2.1.283부터
auto,claude -p와 Agent SDK는default
늘 Manual로 시작하고 싶다면 사용자 설정(~/.claude/settings.json)에 이렇게 적습니다.
{
"permissions": {
"defaultMode": "default"
}
}여기에 함정이 하나 있습니다. 프로젝트 설정 파일(.claude/settings.json, .claude/settings.local.json)에 auto를 적으면 적용되지 않고, bypassPermissions를 적으면 Manual로 시작합니다. 저장소를 내려받은 사람이 모르는 사이 위험한 모드로 시작하지 않도록 막아 둔 것입니다. 이 두 모드를 기본으로 쓰려면 사용자 설정이나 시작 옵션을 씁니다. VS Code 확장은 프로젝트 설정의 시작 모드를 읽지 않으므로, 플랜 모드로 시작하려면 확장 설정의 claudeCode.initialPermissionMode를 plan으로 둡니다.
📝 allow, ask, deny 규칙 쓰는 법
규칙은 설정 파일의 permissions 안에 세 목록으로 적습니다.
{
"permissions": {
"allow": ["Bash(npm run *)", "Bash(git commit *)"],
"ask": ["Bash(git push *)"],
"deny": ["Read(./.env)", "Bash(rm -rf *)"]
}
}형식은 도구 또는 도구(조건)입니다. 알아 둘 문법은 다음과 같습니다.
- 평가 순서: deny, ask, allow 순서로 보고 처음 맞는 규칙이 결과를 정합니다. 규칙이 더 구체적이라고 순서가 바뀌지 않아서, 넓은 deny
Bash(aws *)는 좁은 allowBash(aws s3 ls)보다 우선합니다 - 와일드카드 위치:
Bash(git log *)는 git log만,Bash(git *)는 모든 git 명령을 잡습니다.Bash(ls *)는lsof를 잡지 않지만 공백 없는Bash(ls*)는 잡습니다 - 도구 이름만 쓴 deny:
Bash처럼 조건 없이 막으면 그 도구를 아예 쓰지 못하게 치웁니다 - 경로 패턴:
//경로는 루트 기준 절대 경로,~/경로는 홈 폴더,/경로는 설정 파일 기준,./경로는 현재 폴더 기준입니다 - 파일 쓰기 규칙: 수정과 쓰기를 막는 규칙은
Edit(docs/**)처럼Edit으로 적습니다.Write(...)로 적은 규칙은 검사에 쓰이지 않습니다
공식 문서가 스스로 밝히는 한계도 있습니다. Bash(git push *)를 막아도 git -C . push처럼 다르게 쓴 명령은 이 규칙에 걸리지 않습니다. Read(./.env) 규칙은 cat, head 같은 명령까지는 막지만 파이썬 스크립트가 여는 파일은 막지 못합니다. 이런 빈틈은 운영체제 수준에서 막는 샌드박스나 훅으로 메웁니다.
🗂️ 설정 파일 네 곳과 우선순위
| 파일 | 경로 | 적용 범위 |
|---|---|---|
| 사용자 | ~/.claude/settings.json | 내 모든 프로젝트 |
| 프로젝트 공유 | .claude/settings.json | 저장소에 올려 팀이 공유 |
| 프로젝트 로컬 | .claude/settings.local.json | 이 프로젝트의 나만, git에서 제외 |
| 관리 정책 | managed-settings.json 등 | 조직이 배포 |
우선순위는 관리 정책, 시작 옵션, 프로젝트 로컬, 프로젝트 공유, 사용자 순서로 높습니다. 다만 allow 같은 목록은 덮어쓰지 않고 여러 파일의 값을 합칩니다. 그리고 층이 달라도 deny가 먼저라서, 사용자 설정에서 허용하고 프로젝트 설정에서 막으면 막힙니다.
승인 창에서 "Yes, and don't ask again"을 고르면 Bash 명령과 웹 도메인 허용은 .claude/settings.local.json에 규칙으로 저장됩니다. 그런데도 계속 묻는다면 프로젝트나 관리 정책 쪽에 같은 명령의 ask 규칙이 있는 경우입니다. 지금 걸려 있는 규칙과 그 규칙이 어느 파일에서 왔는지는 /permissions로 한 화면에서 봅니다.
⚠️ 자주 하는 실수
- 프로젝트 설정에
defaultMode: "auto"를 적고 적용됐다고 생각합니다: 프로젝트 설정에서는 무시됩니다 - 와일드카드를 명령 이름에 붙여 씁니다:
Bash(git*)는gitk같은 다른 명령까지 잡습니다. 하위 명령 뒤에 공백과 함께 둡니다 - deny 규칙만 믿고 샌드박스를 켜지 않습니다: 규칙은 명령 문자열을 보고 판단하므로 우회 표기에 약합니다
- 프로젝트 allow가 바로 적용된다고 생각합니다: 프로젝트 설정의 allow는 작업 공간 신뢰 창을 수락한 뒤에만 적용됩니다
❓ 자주 묻는 질문
auto 모드와 acceptEdits는 무엇이 다른가요?
acceptEdits는 파일 수정과 몇 가지 파일 명령만 묻지 않고, 그 밖의 셸 명령은 여전히 묻습니다. auto는 모든 행동을 묻지 않는 대신 별도 분류 모델이 요청 범위를 넘는 행동이나 읽은 콘텐츠의 지시로 보이는 행동을 실행 전에 막습니다. 공식 문서는 auto가 승인 창을 줄여 줄 뿐 안전을 보장하지는 않는다고 적습니다.
팀 전체가 bypassPermissions를 못 쓰게 할 수 있나요?
할 수 있습니다. 관리 정책 설정에 permissions.disableBypassPermissionsMode를 "disable"로 두면 막히고, auto 모드는 disableAutoMode로 막습니다. 관리 정책의 deny 규칙은 시작 옵션으로도 풀 수 없습니다.
규칙이 어느 파일에서 왔는지 어떻게 확인하나요?
세션 안에서 /permissions를 입력하면 모든 규칙과 각 규칙이 들어 있는 설정 파일이 함께 보입니다. 작업 도중 규칙을 바꾸면 같은 턴의 다음 도구 호출부터 적용됩니다.
📋 3줄 요약
-
클로드 코드 권한 모드는 default와 acceptEdits, plan과 auto, dontAsk와 bypassPermissions 여섯 가지이고 v2.1.283부터 터미널과 VS Code 세션은 auto로 시작합니다.
-
허용 규칙은 deny, ask, allow 순서로 평가되어 처음 맞는 규칙이 결과를 정하므로 넓은 deny 하나가 좁은 allow보다 우선합니다.
-
프로젝트 설정 파일에 defaultMode로 auto나 bypassPermissions를 적으면 적용되지 않아서, 이 두 모드는 사용자 설정이나 시작 옵션으로 켭니다.
📚 참고 자료
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
settings.json에 allow 규칙 "Bash(git *)"와 deny 규칙 "Bash(git push *)"를 함께 넣었습니다. 클로드가 git push origin main을 실행하려 하면 어떻게 될까요?
