Claude Code 권한 구성

Claude Code 권한 구성

Claude Code가 접근·수행할 수 있는 것을 세밀한 권한 규칙·모드·관리 정책으로 제어하는 방법을 다루는 페이지입니다. 권한 설정을 버전 컨트롤에 체크인해 조직 전 개발자와 공유하고, 각 개발자는 자신의 설정을 개인화할 수 있습니다.

출처: 공식문서

본문

권한 시스템

Claude Code는 계층적 권한 시스템으로 강력함과 안전함을 균형 잡습니다. 각 도구 유형에 대해 Manual 모드가 액션 실행 전에 묻는지가 표에 나옵니다. 다른 권한 모드는 어떤 것을 물어보는지 바꿉니다 — 자동 모드에서는 분류기가 액션을 검토합니다.

도구 유형 예 승인 필요 "예, 다시 묻지 않기" 동작
읽기 전용 파일 읽기, Grep 아니오 (작업 디렉터리·추가 디렉터리 내) N/A
Bash 명령 셸 실행 예 (내장 읽기 전용 명령 제외) 저장소·명령별 영구
파일 수정 편집/쓰기 예 세션 종료까지
웹 fetch WebFetch 예 (사전 승인 문서 도메인 제외) 저장소·도메인별 영구
웹 검색 WebSearch 예 저장소별 영구

"예, 다시 묻지 않기"로 영구 저장되는 승인(Bash 명령·WebFetch 도메인 등)은 git 저장소 루트의 .claude/settings.local.json에 저장됩니다. 파일 수정 승인은 파일에 저장되지 않고 세션 종료까지 유지됩니다. v2.1.211 이전에는 항상 시작 디렉터리에 저장해 워크트리·하위 디렉터리 승인이 저장소 전체에 적용되지 않았습니다.

때로 권한 프롬프트는 1회 승인만 제공합니다. Claude Code는 프롬프트가 허용 범위를 모두 보여줄 수 있을 때만 옵션을 제공하므로, 저장하는 규칙은 옵션이 가리키는 범위만 덮습니다.

권한 프롬프트에 댓글 달기

단일 액션을 승인·거부할 때 Claude에게 메모를 달 수 있습니다. Bash·PowerShell·파일·MCP 도구 프롬프트에서 Yes/No로 이동한 뒤 Tab을 눌러 댓글 필드를 엽니다. Enter는 댓글과 함께 제출, Tab은 답 없이 닫기, Shift+Tab은 파일 프롬프트에서 동일하게 닫음. Yes면 액션 실행 후 댓글을 결과 뒤에 전송, No면 댓글을 거부 사유로 전송합니다.

권한 관리

/permissions로 도구 권한을 보고 관리합니다. Allow 규칙은 승인 없이 사용, Ask 규칙은 매번 확인, Deny 규칙은 사용 차단. 규칙은 deny → ask → allow 순으로 평가되며, 첫 매치가 결과를 결정하고 규칙 특이성이 순서를 바꾸지 않습니다. Bash(rm *) 같은 광범위 deny가 Bash(aws s3 ls) 같은 좁은 allow보다 우선입니다.

도구 이름만 있는 deny 규칙(Bash)은 그 도구를 컨텍스트에서 완전히 제거합니다. EndConversation 도구는 예외로 제거할 수 없습니다. 범위 규칙(Bash(rm *))은 도구를 남기고 매칭 호출만 차단합니다.

참고: 권한 규칙은 Claude Code가 강제하며 모델이 강제하지 않습니다. 프롬프트·CLAUDE.md 지시는 Claude가 시도하는 것을 정형화하지만 허용을 바꾸진 않습니다. 접근 부여·회수는 /permissions, 규칙, 권한 모드, PreToolUse 훅으로.

권한 모드

모드 설명
default 각 도구 첫 사용 시 권한 질문. CLI·VS Code·JetBrains 확장·데스크톱 앱에서 Manual로 표시, manual 별칭 허용(v2.1.200+)
acceptEdits 작업 디렉터리·additionalDirectories 내 파일 편집·일반 파일시스템 명령(mkdir, touch, mv, cp) 자동 수락
plan 파일 읽기·읽기 전용 셸 명령만 실행, 소스 편집 안 함
auto 요청과 일치하는지 백그라운드 안전 검사로 도구 호출 자동 승인
dontAsk 물어볼 모든 호출을 자동 거부. 작업 디렉터리 내 읽기·승인 불필요 액션은 실행
bypassPermissions 권한 프롬프트 건너뜀 (자동 승인되지 않는 액션 제외)

⚠️ bypassPermissions는 .git·.claude 같은 보호 경로에 쓰기도 포함해 권한 프롬프트를 건너뜁니다. 컨테이너·VM처럼 피해가 없는 격리 환경에서만 사용하세요.

permissions.disableBypassPermissionsMode·permissions.disableAutoMode를 "disable"로 설정해 bypassPermissions·auto 사용을 막을 수 있습니다.

권한 규칙 문법

규칙 형식은 Tool 또는 Tool(specifier)입니다. 괄호 안은 리터럴이라 이스케이프 불필요.

도구 전체 매칭

Bash       # 모든 Bash 명령
WebFetch   # 모든 웹 fetch
Read       # 모든 파일 읽기

Bash(*)는 Bash와 동일.

세밀한 제어용 specifier

규칙 효과
Bash(npm run build) 정확한 명령 npm run build와 매칭
Read(./.env) 현재 디렉터리의 .env 읽기 매칭
WebFetch(domain:example.com) example.com fetch 매칭

입력 파라미터 매칭

deny·ask 규칙은 내장 도구의 최상위 입력 파라미터를 Tool(param:value)로 매칭할 수 있습니다.

규칙 매칭
Agent(model:opus) Opus 모델 계층 요청
Agent(isolation:worktree) git 워크트리 요청
Bash(run_in_background:true) 백그라운드 실행 Bash

파라미터 규칙은 값이 그 정확한 값일 때 매칭됩니다. *는 어떤 문자 시퀀스든 매칭하는 와일드카드입니다. 도구의 기본 콘텐츠 필드(command, file_path, path, url 등)는 이 방식으로 매칭할 수 없습니다 — Bash(command:rm *)는 복합 명령으로 우회 가능해 무시됩니다.

와일드카드 패턴

Bash 규칙의 *는 공백 포함 어떤 텍스트든 매칭해 한 규칙으로 명령군을 덮습니다. *를 하위 명령 뒤에 두세요: Bash(git log *)는 git log 명령만, Bash(git *)는 모든 git 명령 허용.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

Bash(ls *)는 ls(끝 * 앞 공백이 규칙의 일부라 lsof는 매칭 안 됨)도 매칭하고, Bash(ls*)는 lsof도 매칭합니다. trailing *와 동등한 :* 접미사도 있습니다: Bash(ls:*)는 Bash(ls *)와 동일.

도구 이름 와일드카드

deny·ask 규칙은 도구 이름 위치에 glob 패턴도 허용합니다. "*"는 모든 도구, "mcp__*"는 모든 서버의 모든 MCP 도구 매칭. 아래는 모든 MCP 도구를 거부합니다:

{
  "permissions": {
    "deny": ["mcp__*"]
  }
}

allow 규칙은 mcp__<server>__ 리터럴 접두사 뒤 glob만 허용합니다.

도구별 권한 규칙

Bash

Bash 규칙은 전체 명령 텍스트를 매칭하고 *는 어떤 텍스트든 대신합니다.

복합 명령: Claude Code는 셸 연산자를 인지하므로 Bash(safe-cmd *)가 safe-cmd && other-cmd 실행 권한을 주진 않습니다. 인식 구분자는 &&, ||, ;, |, |&, &, 줄바꿈. 각 하위 명령이 독립적으로 매칭돼야 합니다. deny·ask 규칙은 하위 셸·명령 대체·for 루프 본문처럼 중첩된 하위 명령도 적용됩니다.

래퍼: 매칭 전에 고정 래퍼 세트를 제거합니다: timeout, time, nice, nohup, stdbuf + 내장 command·builtin + zsh noglob. xargs(플래그 없을 때)와 안전한 환경변수 할당(NODE_ENV=test npm test)도 제거합니다. direnv exec·devbox run·mise exec·npx·docker exec는 목록에 없습니다 — Bash(devbox run npm test)처럼 러너와 내부 명령을 함께 쓰세요. watch·setsid·ionice·flock 실행 래퍼와 find -exec·-delete는 접두사 규칙으로 자동 승인 불가 — 정확히 일치하는 규칙 필요.

Bash 규칙이 매칭하지 않는 것: 규칙은 Claude가 쓰는 명령 텍스트를 매칭하지, 같은 프로그램의 다른 형식을 매칭하지 않습니다. Bash(curl *)는 curl https://example.com을 막지만 /usr/bin/curl ...·sh -c 'curl ...'은 못 막습니다. 명령 텍스트와 무관한 파일시스템·네트워크 강제는 샌드박싱을 씁니다.

읽기 전용 명령: 모든 모드에서 권한 프롬프트 없이 실행되는 내장 읽기 전용 명령 세트: ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd, git 읽기 전용 형태. 세트는 설정 불가 — 질문이 필요하면 ask·deny 규칙 추가. 다음은 Manual 모드에서도 질문합니다: 쓰기 가능 플래그가 있는 명령의 unquoted glob(find, sort, sed, git), 다른 데몬을 가리키는 docker(-H·--context), file -m/-f, Windows 네트워크(UNC) 경로, 10,000자 초과 명령.

리다이렉션: > file·>> file·2> file 출력 리다이렉션은 대상 파일을 직접 쓰는 것처럼 Edit 규칙·보호 경로·작업 디렉터리로 검사. < file 입력 리다이렉션은 Read 규칙·작업 디렉터리 검사.

PowerShell

Bash 규칙과 동일한 형태. * 와일드카드, :* 접미사, bare PowerShell·PowerShell(*)는 모든 명령 매칭. 별칭은 정규화돼 PowerShell(Get-ChildItem *)가 gci, ls, dir도 매칭하며 대소문자 무시.

Read·Edit

Read(./.env)·Read(./secrets/**) 같은 Read deny 규칙으로 파일·디렉터리 읽기를 차단합니다. Edit 규칙은 파일을 편집하는 모든 내장 도구에 적용됩니다. Read deny 규칙은 같은 경로의 Edit·Write 도구도 차단합니다(v2.1.208+ 편집, v2.1.228+ 쓰기).

Read·Edit 규칙은 gitignore 패턴 문법을 씁니다:

패턴 의미 예
//path 파일시스템 루트 절대 경로 Read(//Users/alice/secrets/**)
~/path 홈 기준 Read(~/Documents/*.pdf)
/path 설정 소스 기준 상대 Edit(/src/**/*.ts)
path·./path 현재 디렉터리 기준 Read(*.env)

⚠️ /Users/alice/file은 절대 경로가 아닙니다. 단일 선행 슬래시는 설정 소스에 앵커됩니다. 절대 경로는 //Users/alice/file을 쓰세요.

Windows에서 경로는 POSIX 형태로 정규화됩니다. C:\Users\alice → /c/Users/alice, .env 매칭엔 //c/**/.env, 모든 드라이브엔 //**/.env.

단일 세그먼트 디렉터리 패턴의 매칭 깊이는 규칙 유형에 따라 다릅니다: allow 규칙 Edit(src/**)는 <cwd>/src 아래만 매칭하고, deny·ask 규칙 Read(secrets/**)는 모든 깊이의 secrets 디렉터리를 매칭합니다. gitignore에서 *는 한 경로 세그먼트 내, **는 디렉터리 간 매칭.

심볼릭 링크는 심링크 자체와 해석 대상 두 경로를 검사합니다: allow 규칙은 둘 다 매칭돼야 하고, deny 규칙은 하나라도 매칭되면 차단합니다.

WebFetch

domain: 접두사로 호스트명을 매칭하며 대소문자 무시, * 와일드카드, trailing . 제거.

  • WebFetch(domain:example.com) — example.com
  • WebFetch(domain:*.example.com) — 모든 하위 도메인 (api.example.com), 단 example.com 자신은 아님
  • WebFetch(domain:*) — 모든 도메인

다른 위치의 와일드카드(domain:example.*)는 두 점 사이 텍스트만 매칭해 공격자가 등록할 수 있는 도메인과 매칭되지 않습니다.

MCP

mcp__puppeteer는 서버의 모든 도구, mcp__puppeteer__puppeteer_navigate는 특정 도구 매칭.

Agent(서브에이전트)

Agent(Explore)·Agent(Plan)·Agent(my-custom-agent): deny 배열 또는 --disallowedTools로 특정 에이전트를 비활성화.

{
  "permissions": { "deny": ["Agent(Explore)"] }
}

Cd

Cd 규칙은 /cd 명령이 세션을 이동할 수 있는 디렉터리를 제어합니다. bare Cd deny는 /cd 전체 비활성화. Cd(<path-pattern>) deny는 매칭 대상을 차단. 아무 Cd allow 규칙을 넣으면 /cd가 allowlist 모드가 됩니다. 패턴의 *는 정확히 한 경로 세그먼트, **는 세그먼트 간 매칭.

훅으로 권한 확장

PreToolUse 훅은 권한 프롬프트 전에 실행돼 도구 호출을 거부·강제 질문·건너뛸 수 있습니다. 다만 훅 결정이 권한 규칙을 우회하진 않습니다: deny 규칙은 훅이 "allow"를 반환해도 차단하고, ask 규칙은 여전히 질문합니다. exit code 2로 끝나는 차단 훅은 권한 규칙 평가 전에 도구 호출을 중지하므로 allow 규칙보다 우선합니다.

작업 디렉터리

기본적으로 Claude는 시작한 디렉터리 파일에 접근합니다. --add-dir <path>·/add-dir·additionalDirectories로 확장할 수 있습니다. 추가 디렉터리 파일은 질문 없이 읽을 수 있고 편집 권한은 현재 권한 모드를 따릅니다. 예:

{
  "permissions": {
    "additionalDirectories": ["/path/to/other"]
  }
}

permissions.blockReadsOutsideWorkingDirectories는 파일 도구가 펜스 친 경로를 모든 모드에서 거부하게 합니다.

세션을 다른 디렉터리로 이동

/cd <path>로 기본 작업 디렉터리를 이동합니다. 대화를 유지하고 새 디렉터리의 CLAUDE.md·프로젝트 설정·훅·.mcp.json 서버·플러그인·스킬·env를 적용합니다. 이전 디렉터리의 MCP 서버는 연결 해제하고, 이동으로 활성화되는 훅은 ${CLAUDE_PROJECT_DIR}을 계속 받습니다. Cd 규칙으로 타깃을 제한할 수 있습니다.

추가 디렉터리는 파일 접근이지 설정이 아님

--add-dir·/add-dir·SDK 플래그로 추가한 디렉터리에서만 일부 설정이 로드됩니다(스킬 .claude/skills/, 명령 .claude/commands/, 서브에이전트 .claude/agents/ 로드. settings.json의 enabledPlugins·extraKnownMarketplaces 키만, CLAUDE.md는 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1일 때만). permissions.additionalDirectories 설정 키에 나열된 디렉터리는 파일 접근만 부여하고 위 설정을 로드하지 않습니다.

구성 공유 방법: 유저 레벨(~/.claude/agents/·~/.claude/output-styles/·~/.claude/settings.json), 플러그인, 또는 .claude/ 구성이 있는 디렉터리에서 시작.

권한과 샌드박싱 상호작용

권한은 어떤 도구·파일·도메인을 쓸 수 있는지 제어하고, 샌드박싱은 OS 레벨에서 Bash 명령·자식 프로세스의 파일시스템·네트워크 접근을 제한합니다. 방어 심층을 위해 둘 다 사용하세요. 샌드박싱을 켜고 autoAllowBashIfSandboxed가 기본값 true면 샌드박스 Bash 명령은 bare Bash ask 규칙이 있어도 스코프 규칙(Bash(git push *))이 아닌 한 질문 없이 실행됩니다.

관리 설정

조직 중앙 통제를 위해 관리자는 관리 설정을 배포하며 유저·프로젝트 설정이 덮어쓰지 못합니다. allowManagedPermissionRulesOnly는 권한 규칙의 유일한 소스를 관리 설정으로 만듭니다. disableBypassPermissionsMode는 보통 관리 설정에 둡니다. 권한 규칙은 모든 설정과 같은 우선순위를 따르며 관리 설정이 최상위입니다 — 어떤 레벨에서든 거부되면 다른 레벨이 허용할 수 없습니다.

프로젝트 allow 규칙과 워크스페이스 신뢰

permissions.allow 규칙·permissions.additionalDirectories는 능력을 부여하므로 Claude Code는 그 폴더의 워크스페이스 신뢰 대화상자를 수락한 뒤에만 적용합니다. 신뢰는 git 저장소 루트 기준으로 저장됩니다(워크트리는 메인 체크아웃 루트). 홈 디렉터리에서 시작하면 신뢰가 세션에만 유지됩니다. 신뢰 대화상자는 대화형 세션에서만 표시되고 claude -p·SDK 세션은 절대 표시하지 않습니다.

~/.claude/settings.local.json은 보통 자신의 파일이라 신뢰 단계 없이 규칙을 적용하지만, git 추적되거나 .claude가 심링크면 저장소 공급으로 취급해 신뢰할 때까지 규칙을 보류합니다. 신뢰하지 않은 저장소에서 claude -p를 실행하기 전에 --setting-sources user, --bare, --settings '{"disableAllHooks": true}', 또는 disabledMcpjsonServers를 고려하세요.

예시 설정

예시 저장소에 일반 배포 시나리오용 시드 설정이 있습니다.

더 알아보기