클로드 코드 권한 모드 — 묻게 할 일과 맡길 일 나누기

클로드 코드 권한 모드란 — 묻지 않고 해도 되는 일의 범위

공식 문서의 정의는 짧다. 권한 모드는 한 세션 안에서 클로드가 먼저 묻지 않고 할 수 있는 동작을 정한다. 수동 모드에서는 파일을 고치거나, 셸 명령을 돌리거나, 네트워크에 닿는 대부분의 동작 앞에서 클로드 코드가 멈추고 사람에게 묻는다. 자동 모드에서는 분류기(classifier)라고 부르는 두 번째 모델이 사람 대신 그 동작을 검토한다.

도구 종류마다 기본으로 묻는지도 정해져 있다. 수동 모드 기준으로 파일 읽기와 검색은 작업 폴더와 추가한 폴더 안이라면 묻지 않는다. 셸 명령은 ls · cat · pwd · 읽기 전용 git 같은 내장 읽기 전용 명령을 빼고 묻는다. 파일 수정은 묻고, 웹 페이지 가져오기는 미리 승인된 문서 도메인을 빼고 묻고, 웹 검색도 묻는다. 승인 창에서 «Yes, and don't ask again»을 고르면 셸 명령과 웹 도메인은 그 저장소에 계속 저장되지만, 파일 수정 승인은 세션이 끝날 때까지만 유효하다.

모드 6가지와 어울리는 일

권한 모드는 6가지다. 공식 문서의 표를 «묻지 않고 하는 일»과 «어울리는 일»로 옮기면 다음과 같다.

• 수동(Manual · 설정값 default) — 읽기만 묻지 않는다. 모든 동작을 직접 보고 싶을 때, 민감한 작업에 맞다. 설정과 훅에서는 default로 쓰지만 CLI에서는 manual이라고 적어도 된다.
• 편집 자동 승인(acceptEdits) — 읽기와 파일 편집, 그리고 mkdir · touch · mv · cp 같은 흔한 파일 명령까지 묻지 않는다. 고친 결과를 나중에 편집기나 git diff로 몰아서 검토하고 싶을 때 맞다.
• 계획(plan) — 읽기는 묻지 않고, 자동 모드를 쓸 수 있는 세션이라면 분류기가 승인한 명령도 돈다. 고치기 전에 코드를 살펴보고 계획부터 받고 싶을 때 맞다.
• 자동(auto) — 뒤에서 안전 점검을 하면서 모든 일을 묻지 않고 한다. 긴 작업이나 승인 창에 지쳤을 때 맞다.
• dontAsk — 작업 폴더 안 파일 읽기와 미리 허용한 도구만 돌고, 물어야 하는 동작은 모두 거부된다. 잠가 둔 CI(지속 통합)와 스크립트에 맞다.
• bypassPermissions — 모든 일을 묻지 않고 한다. 격리된 컨테이너와 VM에서만 쓰라고 문서가 못 박았다.

모범 사례 문서는 양 끝의 비용을 이렇게 설명한다. 수동 모드는 안전하지만 열 번째 승인 창쯤부터는 읽지 않고 승인하게 되고, 자리를 비우면 일이 멈춘다. bypassPermissions는 거부 · 확인 규칙에 걸리지 않는 모든 것을 승인하므로 버려도 되는 컨테이너에서만 말이 된다. 자동 모드는 그 사이에 있다.

처음이라면 고르는 기준은 단순하다. 낯선 코드나 회사 저장소처럼 하나하나 보고 싶으면 수동, 시킨 수정이 맞는지 나중에 몰아서 보겠다면 acceptEdits, 아직 무엇을 고칠지 모르겠으면 plan이다. 자동 모드는 일의 방향을 믿을 수 있는 작업에 쓰고, 클로드 코드 설치와 첫 실행이 아직이라면 클로드 코드 설치·요금제·첫 사용 (2026) — Windows에서 시작하기부터 보면 된다. 그 글에서는 모드 표를 한 번 훑었고, 이 글은 그 표 뒤의 쓰는 법과 규칙을 다룬다. 클로드 코드와 다른 AI 코딩 도구의 차이는 AI 코딩 도구 비교 2026 — Claude Code·Codex·Cursor에서 비교했다.

권한 모드 바꾸는 법 — Shift+Tab, 시작 모드, 허용 규칙

실행 중인 세션에서는 Shift+Tab으로 모드를 돌아가며 바꾼다. 자동 모드에서 시작했다면 첫 번째 누름에 default(수동)로 바뀌고, 그다음은 default → acceptEdits → plan 순서로 돈다. 지금 모드는 프롬프트 아래 상태 표시줄에 회색 ⏸ manual mode on, ⏵⏵ accept edits on, ⏸ plan mode on, ⏵⏵ auto mode on 같은 글자로 보인다. bypassPermissions는 시작할 때 켜 둔 경우에만 순환에 들어가고, dontAsk는 순환에 아예 없어서 --permission-mode dontAsk로 시작해야 한다.

VS Code 확장에서는 입력창 아래의 모드 표시를 눌러 Manual · Edit automatically · Plan · Auto · Bypass permissions 가운데 고른다. 데스크톱 앱의 Code 탭에서는 입력창 아래 줄의 모드 선택기를 쓰고, 고른 모드는 폴더마다 기억된다. claude.ai/code에서는 입력창 아래의 모드 드롭다운을 쓴다.

계획 모드는 승인 창에서 끝이 갈린다. 계획이 준비되면 클로드가 계획을 보여 주고, «Yes, and use auto mode»(승인하고 자동 모드로), «Yes, manually approve edits»(승인하고 편집은 하나씩 확인), «No, keep planning»(계획 계속) 가운데 고르게 한다. Ctrl+G를 누르면 제안된 계획을 기본 텍스트 편집기로 열어 직접 고친 뒤 진행시킬 수 있다. 프롬프트 한 번만 계획 모드로 보내고 싶으면 앞에 /plan을 붙인다.

시작 모드 정하기와 허용 · 확인 · 거부 규칙

새 세션이 어떤 모드로 시작할지는 정해진 순서로 결정된다. --permission-mode 플래그가 가장 먼저이고, 다음이 설정 파일의 permissions.defaultMode, 마지막이 기본값이다. Claude Code v2.1.283 이상에서는 대화형 터미널과 VS Code 세션의 기본 시작 모드가 자동 모드다. 반면 claude -p나 Agent SDK로 돌리는 실행은 기본값이 수동 모드다.

이 PC의 모든 터미널 세션을 수동 모드로 시작하고 싶다면 ~/.claude/settings.json에 다음을 넣는다. Windows에서 ~/.claude는 %USERPROFILE%\.claude 폴더를 뜻한다.

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

다음 세션의 상태 표시줄에 ⏸ manual mode on이 보이면 적용된 것이다. 한 프로젝트에서만 바꾸려면 그 프로젝트의 .claude/settings.json에 같은 값을 넣는다. 단, 프로젝트 설정 파일에서는 auto와 bypassPermissions 두 값이 듣지 않는다. 남이 올린 저장소의 설정이 내 세션을 마음대로 풀어 두지 못하게 막아 둔 것이다.

모드가 큰 틀이라면, 그 위에 규칙을 얹어 도구 하나하나를 미리 허락하거나 막는다. 세션에서 /permissions를 입력하면 모든 권한 규칙과 각 규칙이 들어 있는 settings.json 파일을 보여 주는 창이 열린다. 규칙은 세 종류다.

• 허용(allow) — 묻지 않고 쓰게 한다.
• 확인(ask) — 쓸 때마다 묻게 한다.
• 거부(deny) — 쓰지 못하게 한다.

평가 순서는 거부 → 확인 → 허용이고, 이 순서에서 먼저 맞는 규칙이 결과를 정한다. 규칙이 더 구체적이라고 순서가 바뀌지는 않는다. 그래서 Bash(aws *)를 거부해 두면 Bash(aws s3 ls)를 따로 허용해도 막힌다. 모범 사례 문서가 드는 예시는 이렇게 생겼다.

{
  "permissions": {
    "allow": ["Bash(pnpm tsc --noEmit)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.local)"]
  }
}

타입 검사는 묻지 않고 돌리고, git push는 매번 묻고, .env 파일은 읽지 못하게 한 설정이다. 문서의 원래 예시에는 secrets 폴더 전체를 막는 거부 줄이 하나 더 들어 있다. 이렇게 저장하면 .env 내용을 물어도 Read 도구로든 cat .env로든 실패한다. 셸 규칙의 *는 하위 명령 뒤에 둔다. Bash(git log *)는 git log만 허용하지만 Bash(git *)는 모든 git 명령을 허용한다.

인용 — Claude Code Docs «Configure permissions»

«Permission rules are enforced by Claude Code, not by the model.» — 권한 규칙은 모델이 아니라 Claude Code가 적용한다.

문서는 이어서 프롬프트나 CLAUDE.md의 지시는 클로드가 무엇을 하려 하는지를 바꿀 뿐, Claude Code가 허락하는 범위를 바꾸지는 않는다고 적었다. 접근을 주거나 거두려면 /permissions와 규칙, 권한 모드, PreToolUse 훅을 쓴다.

권한 모드가 잘 안 될 때 — 먼저 확인할 곳

가장 흔한 문의는 «자동 모드가 안 보인다»다. 자동 모드는 모든 요금제에서 쓸 수 있지만 조건이 더 있다. Team과 Enterprise에서는 기본으로 켜져 있되 관리자가 관리 설정에서 permissions.disableAutoMode를 "disable"로 두면 조직 전체에서 꺼진다. 모델도 맞아야 한다. Anthropic API에서는 Claude Opus 4.6 이상, Sonnet 4.6 이상, Haiku 5.5, Fable 모델이 지원되고, Sonnet 4.5 · Opus 4.5 · Haiku 4.5 같은 이전 모델은 어느 곳에서도 지원되지 않는다. Anthropic이 서버 쪽에서 잠시 꺼 둔 경우도 있어서, 그런 답을 받은 세션은 끝날 때까지 자동 모드가 꺼진 채이므로 나중에 새 세션을 연다.

두 번째는 «설정에 auto를 넣었는데 수동으로 시작한다»다. 오류 없이 수동으로 시작했다면 그 값이 .claude/settings.json이나 .claude/settings.local.json에 들어 있을 가능성이 크다. 앞에서 본 대로 이 두 파일의 auto는 듣지 않으니 ~/.claude/settings.json으로 옮긴다. VS Code 확장은 시작 모드를 정할 때 프로젝트의 설정 파일을 아예 읽지 않으므로, 확장에서 시작하는 대화는 VS Code 사용자 설정의 claudeCode.initialPermissionMode로 정한다.

승인 창이 너무 많거나, 자동 모드가 자꾸 막을 때

수동 모드에서 같은 명령의 승인 창이 계속 뜬다면 그 명령을 허용 규칙으로 옮긴다. 승인 창에서 «Yes, and don't ask again»을 고르면 그 규칙이 git 저장소 맨 위의 .claude/settings.local.json에 저장되어 다음 세션에도 적용된다. git 저장소 밖이나 Windows처럼 저장소 맨 위를 쓰지 않는 경우가 있어서, 실제로 어느 파일에 들어갔는지는 /permissions 창의 규칙별 파일 이름으로 확인한다. 모범 사례 문서는 /fewer-permission-prompts도 소개한다. 그동안의 대화 기록에서 자주 쓴 읽기 전용 셸 명령과 MCP 호출을 찾아 .claude/settings.json의 허용 목록에 넣어 주는 명령이다. 승인하거나 거절할 때 이유를 남기고 싶으면 Yes나 No로 옮긴 뒤 Tab을 눌러 메모를 적는다. 거절과 함께 적은 메모는 거절 이유로 클로드에게 전달되고 클로드는 일을 이어 간다.

반대로 자동 모드가 평소 하는 일을 자꾸 막는 경우도 있다. 막힌 동작은 알림이 뜨고 /permissions의 Recently denied 탭에 남으며, 거기서 r을 누르면 수동 승인으로 다시 시도한다. 분류기가 연속 3번 또는 세션 전체에서 20번 막으면 자동 모드가 잠시 멈추고 다시 승인 창이 뜬다. 이 기준은 바꿀 수 없다. 막힘이 되풀이된다면 분류기가 내 환경을 잘 모른다는 뜻이라서, 오탐은 /feedback으로 알리거나 관리자가 믿을 수 있는 저장소와 도메인을 자동 모드 설정에 적어 준다.

claude -p로 돌리는 스크립트에서 «도구 호출이 거부됐다»가 나오는 경우도 같은 원리다. v2.1.302 이상에서 모드를 정하지 않은 claude -p 실행은 수동 모드로 시작하고, 승인이 필요한 호출은 허용 규칙이나 훅으로 미리 승인하지 않으면 거부된다. 문서는 --allowedTools "Bash(npm test)"처럼 돌릴 명령을 콕 집어 허용하거나, --permission-mode auto로 시작하는 두 가지 길을 안내한다.

표의 위 세 줄은 설정 위치 문제이고, 아래 세 줄은 «얼마나 맡길지»를 다시 고르는 문제다. 승인 창이 많다고 바로 자동 모드로 넘어가기보다, 자주 쓰는 명령을 좁은 허용 규칙으로 옮기는 쪽이 범위를 직접 쥔 채로 승인 창을 줄이는 방법이다.

알아 둘 한도와 주의 — 어떤 모드에서도 지켜지는 선

모드를 어떻게 고르든 클로드 코드가 대신 승인하지 않는 것들이 있다. bypassPermissions를 포함한 어떤 모드에서도 명시한 확인(ask) 규칙에 걸린 도구, 사람의 답이 꼭 필요한 질문 도구, 파일 시스템 맨 위나 홈 폴더처럼 중요 경로를 지우는 rm · rmdir은 자동 승인되지 않는다. 거부 규칙도 bypassPermissions를 포함한 모든 모드에서 막는다. 반대로 허용 규칙은 bypassPermissions에서는 아무 효과가 없다.

보호 경로도 있다. .git · .vscode · .claude 같은 폴더와 .gitconfig · .bashrc · .mcp.json 같은 파일에 쓰는 동작은 bypassPermissions와 일부 계획 모드 세션을 빼면 자동 승인되지 않는다. 수동 모드와 acceptEdits에서는 묻고, 자동 모드에서는 분류기로 넘어가고, dontAsk에서는 거부된다. 저장소 상태와 클로드 자신의 설정이 실수로 망가지는 것을 막으려는 장치다.

자동 모드의 분류기가 기본으로 막는 일도 정해져 있다. curl | bash처럼 코드를 받아 바로 실행하기, 민감한 데이터를 외부로 보내기, 운영 환경 배포와 마이그레이션, 강제 푸시, 세션 전부터 있던 파일을 되돌릴 수 없게 지우기 등이 기본 차단 목록에 있다. 작업 폴더 안 파일 작업, 잠금 파일에 적힌 의존성 설치, 읽기 전용 HTTP 요청은 기본 허용이다. 그래도 문서는 자동 모드가 승인 창을 줄여 줄 뿐 안전을 보장하지 않으며, 민감한 작업의 검토를 대신하지 않는다고 경고한다.

대화로 한 말과 셸 규칙의 빈틈

자동 모드에서 «푸시하지 마», «검토가 끝나기 전엔 배포하지 마»라고 말하면 분류기는 그 말을 막을 신호로 다룬다. 하지만 그 경계는 규칙으로 저장되지 않고 매번 대화 기록에서 다시 읽히기 때문에, 대화 압축으로 그 메시지가 빠지면 사라질 수 있다. 그래서 문서는 꼭 지켜야 하는 것은 거부 규칙에 두라고 권한다. 같은 이유로 «이건 절대 하지 마»를 CLAUDE.md에 굵게 적는 것보다 규칙이나 훅으로 옮기는 편이 확실하다. 클로드가 판단하는 지시와 클로드 코드가 직접 적용하는 설정의 차이는 바로 앞 글 클로드 코드 CLAUDE.md 쓰는 법 — 무엇을 적고 어디에 두나의 «예외 없이 지켜야 하는 규칙» 절에서도 다뤘다.

셸 규칙에도 빈틈이 있다. Bash(rm *) 거부 규칙은 rm -rf build/는 막지만 /bin/rm -rf build/나 bash -c 'rm -rf build/'처럼 다른 형태로 부른 명령은 막지 못한다. Read 거부 규칙도 클로드의 파일 도구와 cat · head 같은 알려진 명령에는 적용되지만, 파이썬 스크립트가 직접 파일을 여는 경우까지는 막지 못한다. 문서는 이런 경우 운영체제 수준에서 막는 샌드박스(/sandbox)를 함께 쓰라고 안내한다. 샌드박스는 macOS · Linux · WSL2에서 셸 명령을 가둔다.

마지막으로 bypassPermissions다. 문서는 이 모드를 인터넷이 없는 컨테이너 · VM · 개발 컨테이너처럼 클로드 코드가 호스트 시스템을 망가뜨릴 수 없는 격리된 환경에서만 쓰라고 경고한다. 이 모드는 프롬프트 인젝션이나 의도하지 않은 동작을 막아 주지 않으므로, 승인 창을 크게 줄이면서 뒤에서 안전 점검을 받고 싶다면 자동 모드를 쓰라는 것이 문서의 안내다. 회사 PC라면 관리자가 permissions.disableBypassPermissionsMode를 "disable"로 두어 이 모드를 막아 둘 수 있다. 클로드 코드 밖에서 브라우저 일을 맡길 때 사람이 멈춰 확인해야 할 자리는 브라우저 에이전트가 멈춰야 할 곳 5가지 — 사람이 확인할 자리에 따로 정리했다.

보안 문서는 민감한 저장소에는 프로젝트별 권한 설정을 쓰고, /permissions로 권한 설정을 틈틈이 점검하라고 권한다. 처음 쓰는 사람이라면 수동이나 acceptEdits로 시작해 자주 쓰는 명령 몇 개를 좁은 허용 규칙으로 옮기고, .env 같은 비밀 파일은 거부 규칙으로 막아 두는 것으로 충분하다. 자동 모드는 그다음, 일의 방향을 믿을 수 있는 작업부터 써 보면 된다.

자주 묻는 것

처음 쓸 때는 어떤 권한 모드가 좋나요?

공식 문서는 모든 동작을 직접 보고 싶거나 민감한 작업이라면 수동 모드, 고친 결과를 나중에 몰아서 검토하겠다면 acceptEdits, 고치기 전에 살펴보고 싶다면 plan을 권합니다. 자동 모드는 일의 방향을 믿을 수 있는 작업에 쓰라고 안내합니다.

자동 모드에서도 클로드가 마음대로 위험한 일을 하나요?

자동 모드에서는 별도의 분류기 모델이 동작을 검토해 요청 범위를 넘거나 낯선 인프라를 건드리는 일을 막고, 강제 푸시나 운영 배포 같은 일은 기본으로 차단합니다. 다만 문서는 자동 모드가 안전을 보장하지 않으며 민감한 작업의 검토를 대신하지 않는다고 경고합니다.

자동 모드 선택지가 안 보이면 어떻게 하나요?

지원 모델인지(예: Anthropic API의 Opus 4.6 이상 · Sonnet 4.6 이상), 설정 파일에 disableAutoMode가 있는지, 조직 관리자가 꺼 두지 않았는지 확인합니다. Anthropic이 서버 쪽에서 잠시 꺼 둔 경우에는 그 세션이 끝날 때까지 꺼져 있으므로 나중에 새 세션을 엽니다.

같은 명령의 승인 창을 그만 보고 싶어요.

승인 창에서 «Yes, and don't ask again»을 고르면 그 명령이 허용 규칙으로 저장됩니다. /permissions에서 직접 허용 규칙을 더하거나, /fewer-permission-prompts로 자주 쓴 읽기 전용 명령을 허용 목록에 넣을 수도 있습니다.

CLAUDE.md에 «절대 하지 마»라고 적으면 막히나요?

막히지 않을 수 있습니다. 권한 규칙은 모델이 아니라 Claude Code가 적용하고, CLAUDE.md의 지시는 클로드가 하려는 일을 바꿀 뿐 허락하는 범위를 바꾸지 않습니다. 꼭 막아야 하는 일은 거부 규칙이나 PreToolUse 훅으로 옮깁니다.

정리 — 범위는 모드로, 예외는 규칙으로

권한 모드는 클로드 코드가 묻지 않고 해도 되는 일의 범위이고, 수동 · acceptEdits · plan · auto · dontAsk · bypassPermissions 6가지가 있다. 실행 중에는 Shift+Tab으로, 시작할 때는 --permission-mode로, 늘 쓰려면 permissions.defaultMode로 정하며, 프로젝트 설정 파일의 auto와 bypassPermissions는 듣지 않는다. 모드 위에는 /permissions의 허용 · 확인 · 거부 규칙을 얹고, 규칙은 거부 → 확인 → 허용 순서로 평가된다. 거부 규칙은 어떤 모드에서도 유지되고, bypassPermissions는 격리된 환경에서만 쓴다. 메뉴 이름과 기본값은 자주 바뀌므로 이 글은 2026년 10월 30일 기준으로 읽고, 쓰기 전에 공식 문서를 한 번 더 확인한다. 승인 창에 지쳤다면 모드를 통째로 풀기 전에, 자주 누른 그 명령 하나를 허용 규칙으로 옮기는 것부터 해 보자.

참고 자료

1. Claude Code Docs. Choose a permission mode — 모드 6가지 표 · 수동(Manual)과 default · v2.1.283 기본 자동 모드 · 시작 모드 순서 · 프로젝트 설정의 auto · bypassPermissions 무시 · Shift+Tab 순환과 상태 표시줄 · VS Code · 데스크톱 · 웹 선택기 · 계획 승인 선택지 · Ctrl+G · 자동 모드 조건(모델 · 조직) · 기본 차단 · 허용 목록 · 연속 3번 · 모두 20번 · Recently denied · 대화로 말한 경계 · 어떤 모드도 자동 승인하지 않는 것 · 보호 경로 · 중요 경로 삭제 2분 · v2.1.302 claude -p 수동 시작(2026-10-30 확인). code.claude.com
2. Claude Code Docs. Configure permissions — 도구 종류별 승인 표 · 승인 창 Tab 메모 · /permissions · 거부 → 확인 → 허용 · 규칙은 모델이 아니라 Claude Code가 적용 · 규칙 문법과 * 위치 · 복합 명령 · 읽기 전용 명령 · Bash 규칙이 못 막는 형태 · Read 거부 규칙 · settings.local.json 저장 · 설정 우선순위 · 작업 폴더 · 프로젝트 허용 규칙과 폴더 신뢰(2026-10-30 확인). code.claude.com
3. Claude Code Docs. Best practices for Claude Code — 허용 · 확인 · 거부 예시(.env) · 수동 모드와 bypassPermissions의 비용 · 자동 모드가 막는 것 · 대화로 말한 경계는 압축되면 사라질 수 있음 · /fewer-permission-prompts(2026-10-30 확인). code.claude.com
4. Claude Code Docs. Security — 수동 모드는 읽기 전용으로 시작 · 작업 폴더 경계 · 분석 못 하는 명령은 물음 · /permissions로 정기 점검(2026-10-30 확인). code.claude.com
5. Claude Code 문서. 권한 모드 선택 — 한국어판 «수동 모드» «자동 모드» «기본 제공 시작 권한 모드» 용어와 v2.1.283 · v2.1.302 설명(2026-10-30 확인). code.claude.com
6. Claude Code Docs. Settings files and precedence — Windows에서 ~/.claude = %USERPROFILE%\.claude(2026-10-30 확인). code.claude.com