AI Weekly
가이드 ·
Claude Code 권한 모드 6가지 — Manual·acceptEdits·plan·auto·dontAsk·bypassPermissions 차이와 고르는 법
Claude Code가 무엇을 묻지 않고 실행하는지는 권한 모드가 정한다. 모드 6가지가 각각 무엇을 허락하는지, Shift+Tab·--permission-mode·settings.json으로 바꾸는 법, 하이아이오가 실제로 어떤 일에 어떤 모드를 쓰는지까지 표 하나로 정리했다.
Claude Code의 권한 모드는 6가지다. default(화면 이름 Manual)는 읽기만 묻지 않고, acceptEdits는 파일 수정과 mkdir·mv 같은 흔한 파일 명령까지, plan은 읽기와 분석만, auto는 백그라운드 안전 검사를 거쳐 거의 모두, dontAsk는 미리 허락한 도구만(나머지는 거절), bypassPermissions는 전부를 묻지 않고 실행한다. 대화 중에는 Shift+Tab으로 바꾸고, 시작할 때는 --permission-mode, 기본값은 settings.json의 permissions.defaultMode로 정한다. bypassPermissions는 인터넷이 막힌 컨테이너·VM에서만 쓰라고 공식 문서가 경고한다.
Claude Code 한국어 실전 가이드 · 2/10편
결론부터. 권한 모드는 "Claude Code가 나한테 묻지 않고 해도 되는 일의 범위"다. 처음엔 묻는 게 많은 Manual로 시작하고, 믿을 만한 작업에서만 범위를 넓히면 된다. 이 글은 AI(Claude)가 썼고, 내용은 Claude Code 공식 문서 — Permission modes와 대조했다. 하이아이오는 1인 앱 스튜디오 일을 Claude Code로 돌리면서 이 모드들을 실제로 바꿔 가며 쓰고 있다.
모드 6가지 한눈에
| 설정 값 | 묻지 않고 하는 일 | 어울리는 때 |
|---|---|---|
default (화면 이름 Manual) |
파일 읽기만 | 모든 동작을 직접 확인하고 싶을 때 |
acceptEdits |
읽기 + 파일 수정 + 흔한 파일 명령(mkdir, touch, mv, cp 등) |
내가 보면서 코드를 고쳐 나갈 때 |
plan |
읽기(분석만, 고치기 전 계획) | 바꾸기 전에 먼저 살펴볼 때 |
auto |
거의 전부, 백그라운드 안전 검사를 거쳐서 | 긴 작업, 확인 요청이 너무 잦을 때 |
dontAsk |
작업 폴더 안 읽기 + 미리 허락한 도구만. 물어야 할 일은 거절 | 사람이 없는 CI·스크립트 |
bypassPermissions |
전부 | 격리된 컨테이너·VM에서만 |
설정 파일에는 default 대신 manual이라고 써도 같다.
바꾸는 법 세 가지
1. 대화 중: Shift+Tab
터미널에서 Shift+Tab을 누르면 차례로 바뀐다. 공식 문서 기준으로 default → acceptEdits → plan 순서로 돌고, auto는 쓸 수 있는 환경에서만 끼어든다. bypassPermissions는 시작할 때 켜 둔 경우에만 보이고, dontAsk는 이 순환에 아예 나오지 않는다.
2. 시작할 때: --permission-mode
claude --permission-mode plan
claude -p "테스트 돌려 줘" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"
두 번째 줄처럼 dontAsk는 --allowedTools와 같이 써야 쓸모가 있다. 허락하지 않은 일은 묻지 않고 그냥 거절되기 때문이다.
3. 기본값: settings.json
{
"permissions": {
"defaultMode": "default"
}
}
~/.claude/settings.json에 넣으면 이 컴퓨터의 모든 세션이 그 모드로 시작한다. 프로젝트 설정이 있으면 그쪽이 먼저다. 다만 공식 문서에 따르면 프로젝트의 .claude/settings.json이나 .claude/settings.local.json에 auto나 bypassPermissions를 써 두면 적용되지 않는다(남이 만든 저장소가 위험한 모드를 몰래 켜지 못하게 한 것).
시작 모드를 정하는 순서는 --permission-mode 플래그 → 설정 파일의 defaultMode → 기본값이다.
우리는 이렇게 쓴다
| 일 | 모드 | 이유 |
|---|---|---|
| 처음 보는 저장소 살펴보기 | plan |
아무것도 안 바뀐다는 확신이 필요해서 |
| 블로그 글·문서 고치기 | acceptEdits |
파일 수정만 하니까, 수정마다 묻는 건 귀찮다 |
| 앱 배포·스토어 제출 | default (Manual) |
되돌리기 어려운 일은 한 번씩 직접 본다 |
| 매일 정해진 시간 자동 작업 | dontAsk + 허락 목록 |
사람이 없으니 묻는 순간 멈추면 안 된다 |
bypassPermissions |
안 씀 | 우리 맥은 격리된 환경이 아니다 |
auto는 편하지만 공식 문서도 "확인 요청은 줄여 주지만 안전을 보장하지는 않는다"고 적어 둔다. 결제·삭제·외부 게시처럼 되돌리기 어려운 일은 모드와 상관없이 hooks로 막거나 알림을 받는 편이 안전하다.
조심할 것
- bypassPermissions: 공식 문서는 "인터넷이 없는 컨테이너·VM·dev container처럼 호스트를 망가뜨릴 수 없는 곳에서만" 쓰라고 한다. 이 모드에서도 거절(deny) 규칙은 지켜지지만 허락(allow) 규칙은 의미가 없어진다. 리눅스·맥에서 root나 sudo로 실행하면 아예 거부된다.
- 보호된 경로:
.git,.vscode,.claude,.bashrc,.mcp.json같은 곳에 쓰는 일은 bypassPermissions 등 몇 경우를 빼면 자동 허락되지 않는다. - auto 조건: 지원 모델에서만 켜진다(공식 문서 기준 Opus 4.6·Sonnet 4.6 이상 등). 팀·회사 관리자가 끌 수 있다.
자주 묻는 질문
처음 쓰는 사람은 어떤 모드가 좋나요?
Manual(default)로 시작해 Claude가 무엇을 하려는지 몇 번 보고, 파일 수정을 믿을 만하면 acceptEdits로 넓히는 걸 권한다. 바꾸기 전에 계획부터 보고 싶으면 plan.
plan 모드에서는 파일이 절대 안 바뀌나요?
plan은 읽고 분석해서 계획을 내는 모드다. 공식 문서 표에 따르면 묻지 않고 하는 일은 읽기(그리고 auto를 쓸 수 있는 환경에서는 안전 검사를 통과한 명령)다. 고치기 시작하려면 다른 모드로 바꾸거나 계획을 승인해야 한다.
dontAsk와 bypassPermissions는 뭐가 다른가요?
둘 다 묻지 않는다. 그런데 dontAsk는 묻는 대신 거절하고, bypassPermissions는 묻는 대신 실행한다. 사람 없이 돌리는 스크립트라면 dontAsk + 허락 목록이 훨씬 안전하다.
프로젝트 settings.json에 auto를 써 뒀는데 왜 안 켜지나요?
공식 문서에 따르면 .claude/settings.json·.claude/settings.local.json의 auto·bypassPermissions는 적용되지 않는다. 내 사용자 설정(~/.claude/settings.json)이나 --permission-mode 플래그로 켜야 한다.