Claude Code 권한 설정

Claude Code 공식 문서 "Configure permissions". 규칙 평가 순서와 문법, 도구별 규칙(Bash·PowerShell·Read/Edit·WebFetch·MCP·Agent·Cd), 규칙·훅·mod 우선순위, plan 모드 훅 승인, 작업 디렉터리, 샌드박스와의 관계, 작업 공간 신뢰

확인 2026-10-21원본 자료 1건의 요약갱신 2026-10-21언급 29곳

한 줄 요약: Claude Code 공식 문서 "Configure permissions". allow·ask·deny 권한 규칙의 문법(도구 이름, 지정자, 입력 파라미터, 와일드카드)과 도구별 규칙(Bash, PowerShell, Read·Edit, WebFetch, MCP, Agent, Cd), 규칙·훅·mod 사이의 우선순위, plan 모드에서의 훅 승인, 작업 디렉터리, 샌드박스와의 관계, 작업 공간 신뢰(신뢰 전에 무엇이 도는가)를 다룬다.

원본 정보#

제목: Configure permissions
발행: Anthropic, Claude Code 공식 문서. 본문에 날짜 없음(원본 날짜 미상). 서버 Last-Modified 2026-10-20
URL: https://code.claude.com/docs/en/permissions (새 창)
수집(fetch)일: 2026-10-21. 본문의 규칙 문법, 설정 키, 버전 조건(v2.1.172~v2.1.292)은 이 날짜 기준이다.
구성: 권한 시스템과 확인 창 → 권한 관리(/permissions, 평가 순서) → 권한 모드 표 → 규칙 문법 → 도구별 규칙 → 훅으로 확장(규칙·훅·mod 우선순위, plan 모드 훅 승인) → 작업 디렉터리(/cd, --add-dir) → 샌드박스와의 관계 → managed settings·설정 우선순위 → 작업 공간 신뢰 → 예시 설정.

핵심 주장#

규칙은 deny → ask → allow 순으로 평가되고, 처음 맞는 규칙이 정한다. 구체성은 순서를 바꾸지 않는다. 넓은 deny Bash(aws *)는 좁은 allow Bash(aws s3 ls)에도 맞는 호출을 막고, allow로 deny에 예외를 낼 수 없다. ask와 allow 사이도 같다. 규칙은 모델이 아니라 Claude Code가 강제하고, 프롬프트나 CLAUDE.md는 Claude가 하려는 일을 이끌 뿐 Claude Code가 허용하는 범위를 바꾸지 않는다. → Claude Code 권한 규칙 문법
Bash 규칙은 명령 텍스트를 맞출 뿐 프로그램 둘레의 보안 경계가 아니다. 복합 명령은 하위 명령마다 따로 맞추고, 정해진 래퍼(timeout, nice, 맨 xargs 등)는 벗긴 뒤 맞춘다. 하지만 Bash(curl *)는 /usr/bin/curl …이나 sh -c 'curl …'을 막지 않고, Bash(git push *)는 git -C . push origin main을 막지 않는다. 명령 텍스트와 무관한 파일 시스템·네트워크 강제는 샌드박스로, 명령 전체를 자기 로직으로 검사하려면 PreToolUse 훅을 쓰라고 원본은 말한다. Read·Edit deny도 파일 이름을 대지 않는 grep -r이나 임의 스크립트의 파일 접근에는 닿지 않는다. → Claude Code 권한 규칙 문법, Claude Code 관리자 권한 통제
훅은 규칙을 풀지 못하지만, mod는 세션 조건에 따라 풀 수 있다. PreToolUse 훅이 무엇을 돌려주든 deny·ask 규칙은 평가된다(managed deny 포함). 종료 코드 2로 막는 훅은 권한 규칙 평가 전에 호출을 멈추므로 allow 규칙보다 앞선다. tool.check를 다루는 mod는 훅 뒤에 답한다. 기기에 managed settings가 있거나 Team·Enterprise /login이 세션 자격 증명이면 deny 거부·ask 확인·훅 차단·--permission-prompt-tool 질의가 기본으로 유지되고, 둘 다 없으면(API 키·CLAUDE_CODE_OAUTH_TOKEN 세션 포함) mod가 deny 규칙이 거부한 호출과 훅이 막은 호출도 승인할 수 있다. 훅 가이드의 "managed settings에 있는 훅은 예외" 문장과 기준이 달라 상충으로 표시했다가, 가이드가 세부 기준을 이 문서로 넘기므로 이 문서 기준으로 해소로 닫았다. → 훅, 권한 모드
plan 모드에서는 훅의 "allow"와 mod 승인이 읽기 전용이 아닌 호출을 풀지 못한다. ExitPlanMode를 빼면 파일 편집 같은 호출은 훅이 없을 때와 같은 확인·차단·승인을 받고, 훅이 돌려준 updatedInput은 적용된다. 계획을 승인하거나 다른 모드로 바꾸면 이 제한이 풀린다. → 훅 이벤트 레퍼런스, Claude Code 훅 설정 레시피
저장소가 주는 "능력"은 작업 공간 신뢰를 기다리지만, 신뢰 전에도 도는 것이 있다. 프로젝트 .claude/settings.json의 permissions.allow와 additionalDirectories는 신뢰 대화상자를 수락한 뒤에만 적용되고(deny·ask는 바로), 대화상자는 대화형 세션에서만 뜬다. 상위 폴더만 신뢰했거나 claude -p·SDK로 돌리면 settings 파일 훅, env, apiKeyHelper 같은 헬퍼, 프로젝트 스킬의 훅과 allowed-tools는 쓰이고, -p·SDK에서는 .mcp.json 서버가 묻지 않고 연결된다. 원본은 남이 만든 저장소에 claude -p를 돌리기 전에 네 가지 방법을 권한다. → 작업 공간 신뢰

원본의 예시 규칙 (원문 그대로, 2026-10-21 기준)#

npm 스크립트와 git 커밋은 묻지 않고, git push로 시작하는 명령은 거부: "allow": ["Bash(npm run *)", "Bash(git commit *)"], "deny": ["Bash(git push *)"]
모든 MCP 도구 거부: "deny": ["mcp__*"]
PowerShell: "allow": ["PowerShell(Get-ChildItem *)", "PowerShell(git commit *)"], "deny": ["PowerShell(Remove-Item *)"]
샌드박스 허용 목록은 그대로 두고 WebFetch만 자유롭게: "allow": ["WebFetch"]
Explore 서브에이전트 끄기: "deny": ["Agent(Explore)"]

전체 문법과 표는 Claude Code 권한 규칙 문법에 원문 규칙 그대로 옮겼다.

원본에 없는 것#

자동 모드 분류기 규칙의 형식(autoMode.environment 등): 원본은 Configure auto mode 문서로 넘긴다(→ Claude Code 자동 모드 설정).
샌드박스 설정 전체: 원본은 Sandboxing 문서로 넘긴다(→ Claude Code 샌드박스).
mod가 무엇이고 조직이 mod의 deny 우회를 어떻게 바꾸는지: 원본은 mods 개요·관리 문서로 넘긴다.
어떤 모드도 자동 승인하지 않는 동작의 전체 목록: 원본은 권한 모드 문서로 링크만 한다(→ Claude Code 권한 모드).

원본이 링크한 관련 문서#

Configure auto mode(→ Claude Code 자동 모드 설정), Sandboxing(→ Claude Code 샌드박스), Plugins mods(overview, events, admin), Tools reference, Errors, Prompt caching(도구 전체 deny), Artifacts, Worktrees, Agent view, Authentication, Security, MCP(조직 커넥터 통제, 프로젝트 서버 승인, headersHelper), Claude apps gateway, Agent SDK(user input, settingSources).