권한 구성
세분화된 권한 규칙, 모드 및 관리형 정책을 통해 Claude Code가 액세스하고 수행할 수 있는 작업을 제어합니다.
Claude Code는 에이전트가 수행할 수 있는 작업과 수행할 수 없는 작업을 정확하게 지정할 수 있도록 세분화된 권한을 지원합니다. 권한 설정은 버전 제어에 체크인할 수 있으며 조직의 모든 개발자에게 배포할 수 있을 뿐만 아니라 개별 개발자가 사용자 정의할 수 있습니다.
권한 시스템
Claude Code는 강력함과 안전성의 균형을 맞추기 위해 계층화된 권한 시스템을 사용합니다:
| 도구 유형 | 예시 | 승인 필요 | "예, 다시 묻지 않기" 동작 |
|---|---|---|---|
| 읽기 전용 | 파일 읽기, Grep | 아니오 | 해당 없음 |
| Bash 명령 | 셸 실행 | 예 | 프로젝트 디렉토리 및 명령당 영구적 |
| 파일 수정 | Edit/Write 파일 | 예 | 세션 종료까지 |
권한 관리
/permissions를 사용하여 Claude Code의 도구 권한을 보고 관리할 수 있습니다. 이 UI는 모든 권한 규칙과 이들이 출처한 settings.json 파일을 나열합니다.
- Allow 규칙을 사용하면 Claude Code가 수동 승인 없이 지정된 도구를 사용할 수 있습니다.
- Ask 규칙은 Claude Code가 지정된 도구를 사용하려고 할 때마다 확인을 요청합니다.
- Deny 규칙은 Claude Code가 지정된 도구를 사용하지 못하도록 방지합니다.
규칙은 순서대로 평가됩니다: deny, ask, allow. 해당 순서의 첫 번째 일치 항목이 결과를 결정하며, 규칙 특이성은 순서를 변경하지 않습니다. Bash(aws *)와 같은 광범위한 deny 규칙은 Bash(aws s3 ls)와 같은 더 좁은 allow 규칙과도 일치하는 호출을 포함하여 모든 일치하는 호출을 차단하므로, deny 규칙은 허용 목록 예외를 포함할 수 없습니다. ask와 allow 사이에도 동일한 우선순위가 적용됩니다: 일치하는 ask 규칙은 동일한 호출과도 일치하는 더 구체적인 allow 규칙이 있을 때도 프롬프트를 표시합니다.
Deny 규칙은 도구 이름을 지정하는지 또는 도구 내의 패턴 범위를 지정하는지에 따라 다르게 작동합니다. Bash와 같은 단순 도구 이름은 도구를 Claude의 컨텍스트에서 완전히 제거하므로 Claude는 이를 볼 수 없습니다. Bash(rm *)와 같은 범위 지정 규칙은 도구를 사용 가능하게 유지하고 Claude가 시도할 때 일치하는 호출을 차단합니다.
권한 모드
Claude Code는 도구 승인 방식을 제어하는 여러 권한 모드를 지원합니다. 권한 모드에서 각 모드를 사용할 시기를 확인합니다. 설정 파일에서 defaultMode를 설정합니다:
| 모드 | 설명 |
|---|---|
default |
표준 동작: 각 도구를 처음 사용할 때 권한을 요청합니다 |
acceptEdits |
작업 디렉토리 또는 additionalDirectories의 경로에 대해 파일 편집 및 일반적인 파일 시스템 명령(mkdir, touch, mv, cp 등)을 자동으로 수락합니다 |
plan |
Plan Mode: Claude는 파일을 읽고 읽기 전용 셸 명령을 실행하여 탐색하지만 소스 파일을 편집하지 않습니다 |
auto |
배경 안전 검사를 통해 도구 호출을 자동으로 승인하여 작업이 요청과 일치하는지 확인합니다. 현재 연구 미리보기입니다 |
dontAsk |
/permissions 또는 permissions.allow 규칙을 통해 사전 승인되지 않은 한 도구를 자동으로 거부합니다 |
bypassPermissions |
명시적 ask 규칙으로 강제되는 권한 프롬프트를 제외한 모든 권한 프롬프트를 건너뜁니다. 파일 시스템 루트 또는 홈 디렉토리 제거(예: rm -rf / 및 rm -rf ~)는 모델 오류에 대한 회로 차단기로 여전히 프롬프트합니다 |
bypassPermissions 또는 auto 모드가 사용되는 것을 방지하려면 설정 파일에서 permissions.disableBypassPermissionsMode 또는 permissions.disableAutoMode를 "disable"로 설정합니다. 이들은 재정의될 수 없는 관리형 설정에서 가장 유용합니다.
권한 규칙 구문
권한 규칙은 Tool 또는 Tool(specifier) 형식을 따릅니다.
도구의 모든 사용 일치
도구의 모든 사용을 일치시키려면 괄호 없이 도구 이름만 사용합니다:
| 규칙 | 효과 |
|---|---|
Bash |
모든 Bash 명령과 일치합니다 |
WebFetch |
모든 웹 가져오기 요청과 일치합니다 |
Read |
모든 파일 읽기와 일치합니다 |
Bash(*)는 Bash와 동등하며 모든 Bash 명령과 일치합니다. 거부 규칙으로서, 두 형식 모두 Claude의 컨텍스트에서 도구를 제거합니다.
세분화된 제어를 위해 지정자 사용
괄호 안에 지정자를 추가하여 특정 도구 사용과 일치시킵니다:
| 규칙 | 효과 |
|---|---|
Bash(npm run build) |
정확한 명령 npm run build와 일치합니다 |
Read(./.env) |
현재 디렉토리의 .env 파일 읽기와 일치합니다 |
WebFetch(domain:example.com) |
example.com으로의 가져오기 요청과 일치합니다 |
입력 매개변수로 일치
거부 및 요청 규칙은 Tool(param:value)를 사용하여 모든 도구의 최상위 입력 매개변수와 일치할 수 있습니다. 규칙은 Claude가 해당 매개변수가 정확한 값으로 설정된 도구를 호출할 때 일치합니다. 이 구문은 거부 및 요청 규칙용입니다. 한 매개변수 값에 대한 허용 규칙은 호출이 전반적으로 안전하다는 것을 확립하지 않으므로, 허용 규칙은 각 도구의 자체 지정자 구문을 계속 사용합니다. 이는 도구가 허용하는 모든 스칼라 매개변수에 대해 작동합니다:
| 규칙 | 일치 |
|---|---|
Agent(model:opus) |
Opus 모델 계층을 요청하는 Agent 호출 |
Agent(isolation:worktree) |
git worktree를 요청하는 Agent 호출 |
Bash(run_in_background:true) |
백그라운드에서 실행되는 Bash 호출 |
매개변수 일치는 다음 규칙을 따릅니다:
- 매개변수 이름은 Agent 도구의
model과 같이 도구 입력의 직접 필드여야 합니다. 객체 또는 배열 내에 중첩된 필드는 일치 가능하지 않습니다 - 각 규칙은 하나의 매개변수를 지정합니다.
model과isolation모두에 대해 게이트하려면, 한 규칙에 결합하는 대신Agent(model:opus)및Agent(isolation:worktree)두 규칙을 작성합니다 - 값은
*를 와일드카드로 지원하여 모든 문자 시퀀스와 일치하므로,Agent(isolation:*)는 모든 명시적 격리 값과 일치합니다.*없으면 일치는 정확합니다 - 모델이 생략한 매개변수는 절대 일치하지 않으므로,
Agent(model:*)는model을 설정하지 않은 호출과 일치하지 않습니다 - 값은 정규화 전에 Claude가 보내는 리터럴 입력과 비교됩니다.
Agent(model:opus)는 별칭opus와 일치하지만 전체 모델 ID와는 일치하지 않습니다.--verbose로 실행하여 각 도구 호출의 정확한 매개변수 이름과 값을 확인합니다 - 콜론 주위의 공백은 무시됩니다
도구가 자체 정규화 규칙으로 이미 일치하는 필드는 이 방식으로 일치 가능하지 않습니다: Bash 및 PowerShell의 command, Read, Edit 및 Write의 file_path, Grep 및 Glob의 path, NotebookEdit의 notebook_path, WebFetch의 url. Bash(command:rm *)와 같은 규칙은 복합 명령으로 우회 가능하므로, Claude Code는 이를 무시하고 시작 경고를 발생시킵니다. 대신 Bash(rm *), Read(./path) 또는 WebFetch(domain:host)를 사용합니다.
와일드카드 패턴
Bash 규칙은 *를 사용한 glob 패턴을 지원합니다. 와일드카드는 명령의 어느 위치에나 나타날 수 있습니다. 이 구성은 npm 및 git commit 명령을 허용하면서 git push를 차단합니다:
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git commit *)",
"Bash(git * main)",
"Bash(* --version)",
"Bash(* --help *)"
],
"deny": [
"Bash(git push *)"
]
}
}
* 앞의 공백이 중요합니다: Bash(ls *)는 ls -la와 일치하지만 lsof와는 일치하지 않으며, Bash(ls*)는 둘 다 일치합니다. :* 접미사는 뒤에 오는 와일드카드를 작성하는 동등한 방법이므로 Bash(ls:*)는 Bash(ls *)와 동일한 명령과 일치합니다.
권한 대화 상자는 명령 접두사에 대해 "예, 다시 묻지 않기"를 선택할 때 공백으로 구분된 형식을 작성합니다. :* 형식은 패턴의 끝에서만 인식됩니다. Bash(git:* push)와 같은 패턴에서 콜론은 리터럴 문자로 취급되며 git 명령과 일치하지 않습니다.
도구 이름 와일드카드
거부 및 요청 규칙은 도구 이름 위치에서도 glob 패턴을 허용합니다. 패턴은 전체 도구 이름과 일치해야 합니다: "*"는 모든 도구와 일치하며, "mcp__*"는 모든 서버의 모든 MCP 도구와 일치합니다. 단순 이름 glob 거부 규칙과 일치하는 도구는 Claude의 컨텍스트에서 제거되며, 이는 단순 도구 이름과 동일합니다. 이 구성은 모든 MCP 도구를 거부합니다:
{
"permissions": {
"deny": [
"mcp__*"
]
}
}
허용 규칙은 리터럴 mcp__<server>__ 접두사 이후에만 도구 이름 glob을 허용합니다. 서버 세그먼트는 glob이 없어야 하므로 규칙이 구성한 특정 서버를 지정합니다. mcp__puppeteer__*는 puppeteer 서버의 모든 도구와 일치하며, mcp__github__get_*는 해당 get_ 도구와 일치합니다. "*", "B*", 또는 "mcp__*"와 같은 고정되지 않은 허용 glob은 경고와 함께 건너뛰어지며 자동으로 승인되지 않습니다.
도구 이름이 알려진 도구와 일치하지 않는 거부 또는 요청 규칙은 오타를 포착하기 위해 시작 경고를 생성합니다. _ 또는 *를 포함하는 도구 이름은 확인에서 제외됩니다.
트랜스크립트 및 권한 대화 상자에서 도구에 대해 표시되는 레이블은 정규 이름과 다를 수 있습니다. 예를 들어, 트랜스크립트에서 Stop Task로 표시되는 도구의 정규 이름은 TaskStop입니다. 권한 규칙 및 hook 매처는 정규 이름만 일치시키므로, Stop Task로 작성된 규칙은 일치하지 않습니다. 거부 및 요청 규칙의 경우, 위의 시작 경고가 불일치를 포착합니다. 도구 참조에 나열된 정규 이름을 사용합니다.
도구별 권한 규칙
Bash
Bash 권한 규칙은 *를 사용한 와일드카드 일치를 지원합니다. 와일드카드는 명령의 시작, 중간 또는 끝을 포함하여 어느 위치에나 나타날 수 있습니다:
Bash(npm run build)는 정확한 Bash 명령npm run build와 일치합니다Bash(npm run test *)는npm run test로 시작하는 Bash 명령과 일치합니다Bash(npm *)는npm로 시작하는 모든 명령과 일치합니다Bash(* install)은install로 끝나는 모든 명령과 일치합니다Bash(git * main)은git checkout main및git log --oneline main과 같은 명령과 일치합니다
단일 *는 공백을 포함한 모든 문자 시퀀스와 일치하므로 하나의 와일드카드가 여러 인수에 걸칠 수 있습니다. Bash(git *)는 git log --oneline --all과 일치하며, Bash(git * main)은 git push origin main 및 git merge main과 일치합니다.
*가 앞에 공백이 있는 끝에 나타날 때(예: Bash(ls *)), 단어 경계를 적용하여 접두사 뒤에 공백이나 문자열 끝이 필요합니다. 예를 들어, Bash(ls *)는 ls -la와 일치하지만 lsof와는 일치하지 않습니다. 반대로, 공백이 없는 Bash(ls*)는 단어 경계 제약이 없으므로 ls -la와 lsof 모두와 일치합니다.
복합 명령
"예, 다시 묻지 않기"로 복합 명령을 승인하면 Claude Code는 전체 복합 문자열에 대한 단일 규칙이 아니라 승인이 필요한 각 서브명령에 대해 별도의 규칙을 저장합니다. 예를 들어, git status && npm test를 승인하면 npm test에 대한 규칙을 저장하므로 향후 npm test 호출은 && 앞에 무엇이 있든 인식됩니다. cd를 서브디렉토리로 이동하는 것과 같은 서브명령은 해당 경로에 대한 자체 Read 규칙을 생성합니다. 단일 복합 명령에 대해 최대 5개의 규칙이 저장될 수 있습니다.
프로세스 래퍼
Bash 규칙을 일치시키기 전에 Claude Code는 고정된 프로세스 래퍼 집합을 제거하므로 Bash(npm test *)와 같은 규칙은 timeout 30 npm test도 일치합니다. 인식되는 래퍼는 timeout, time, nice, nohup 및 stdbuf입니다.
베어 xargs도 제거되므로 Bash(grep *)는 xargs grep pattern과 일치합니다. 제거는 xargs에 플래그가 없을 때만 적용됩니다: xargs -n1 grep pattern과 같은 호출은 xargs 명령으로 일치되므로 내부 명령에 대해 작성된 규칙은 이를 포함하지 않습니다.
이 래퍼 목록은 기본 제공되며 구성할 수 없습니다. direnv exec, devbox run, mise exec, npx 및 docker exec과 같은 개발 환경 러너는 목록에 없습니다. 이러한 도구는 인수를 명령으로 실행하므로 Bash(devbox run *)와 같은 규칙은 devbox run rm -rf .를 포함하여 run 뒤에 오는 모든 것과 일치합니다. 환경 러너 내에서 작업을 승인하려면 Bash(devbox run npm test)와 같이 러너와 내부 명령을 모두 포함하는 특정 규칙을 작성합니다. 허용하려는 각 내부 명령에 대해 하나의 규칙을 추가합니다.
watch, setsid, ionice 및 flock과 같은 Exec 래퍼는 항상 프롬프트하며 Bash(watch *)와 같은 접두사 규칙으로 자동 승인될 수 없습니다. 동일한 사항이 -exec 또는 -delete를 사용하는 find에 적용됩니다: Bash(find *) 규칙은 이러한 형식을 포함하지 않습니다. 특정 호출을 승인하려면 전체 명령 문자열에 대한 정확한 일치 규칙을 작성합니다.
읽기 전용 명령
Claude Code는 기본 제공 Bash 명령 집합을 읽기 전용으로 인식하고 모든 모드에서 권한 프롬프트 없이 실행합니다. 여기에는 ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd 및 git의 읽기 전용 형식이 포함됩니다. 집합은 구성할 수 없습니다. 이러한 명령 중 하나에 대해 프롬프트를 요구하려면 ask 또는 deny 규칙을 추가합니다.
따옴표 없는 glob 패턴은 모든 플래그가 읽기 전용인 명령에 대해 허용되므로 ls *.ts 및 wc -l src/*.py는 프롬프트 없이 실행됩니다. find, sort, sed 및 git과 같이 쓰기 가능하거나 실행 가능한 플래그가 있는 명령은 glob이 -delete와 같은 플래그로 확장될 수 있으므로 따옴표 없는 glob이 있을 때 여전히 프롬프트합니다.
작업 디렉토리 또는 추가 디렉토리 내의 경로로의 cd도 읽기 전용입니다. cd packages/api && ls와 같은 복합 명령은 각 부분이 자체적으로 적격일 때 프롬프트 없이 실행됩니다. 하나의 복합 명령에서 cd와 git을 결합하면 대상 디렉토리와 관계없이 항상 프롬프트합니다.
PowerShell
PowerShell 권한 규칙은 Bash 규칙과 동일한 형태를 사용합니다. *를 사용한 와일드카드는 어느 위치에나 일치하고, :* 접미사는 후행 *와 동등하며, 베어 PowerShell 또는 PowerShell(*)는 모든 명령과 일치합니다. 이 구성은 Get-ChildItem 및 git commit 명령을 허용하면서 Remove-Item을 차단합니다:
{
"permissions": {
"allow": [
"PowerShell(Get-ChildItem *)",
"PowerShell(git commit *)"
],
"deny": [
"PowerShell(Remove-Item *)"
]
}
}
일반적인 별칭은 일치하기 전에 정규화됩니다. cmdlet 이름에 대해 작성된 규칙은 해당 별칭과도 일치하므로 PowerShell(Get-ChildItem *)는 gci, ls 및 dir과도 일치합니다. 일치는 대소문자를 구분하지 않습니다.
Claude Code는 PowerShell AST를 구문 분석하고 복합 명령의 각 명령을 독립적으로 확인합니다. 파이프라인 연산자 |, 문 구분자 ; 및 PowerShell 7+ 이상의 체인 연산자 && 및 ||는 복합 명령을 서브명령으로 분할합니다. 복합 명령이 허용되려면 규칙이 모든 서브명령과 일치해야 합니다.
Read 및 Edit
Edit 규칙은 파일을 편집하는 모든 기본 제공 도구에 적용됩니다. Claude는 Grep 및 Glob과 같이 파일을 읽는 모든 기본 제공 도구에 Read 규칙을 적용하기 위해 최선을 다합니다. 또한 프롬프트의 @file 언급 및 연결된 IDE가 Claude와 공유하는 선택 및 열린 파일 컨텍스트에도 적용합니다.
Read 및 Edit 규칙은 모두 gitignore 사양을 따르며 4가지 고유한 패턴 유형이 있습니다:
| 패턴 | 의미 | 예시 | 일치 |
|---|---|---|---|
//path |
파일 시스템 루트의 절대 경로 | Read(//Users/alice/secrets/**) |
/Users/alice/secrets/** |
~/path |
홈 디렉토리의 경로 | Read(~/Documents/*.pdf) |
/Users/alice/Documents/*.pdf |
/path |
프로젝트 루트에 상대적인 경로 | Edit(/src/**/*.ts) |
<project root>/src/**/*.ts |
path 또는 ./path |
현재 디렉토리에 상대적인 경로 | Read(*.env) |
<cwd>/*.env |
Windows에서 경로는 일치하기 전에 POSIX 형식으로 정규화됩니다. C:\Users\alice는 /c/Users/alice가 되므로 //c/**/.env를 사용하여 해당 드라이브의 어디든 .env 파일과 일치시킵니다. 모든 드라이브에서 일치시키려면 //**/.env를 사용합니다.
예시:
Edit(/docs/**):<project>/docs/의 편집 (NOT/docs/and NOT<project>/.claude/docs/)Read(~/.zshrc): 홈 디렉토리의.zshrc읽기Edit(//tmp/scratch.txt): 절대 경로/tmp/scratch.txt편집Read(src/**):<current-directory>/src/에서 읽기
규칙은 해당 앵커 아래의 파일만 일치하므로 앵커는 deny 규칙이 얼마나 멀리 도달하는지를 결정합니다. 베어 파일명은 gitignore 의미론을 따르고 어느 깊이에서나 일치하므로 Read(.env) 및 Read(**/.env)는 동등합니다:
| Deny 규칙 | 차단 | 차단하지 않음 |
|---|---|---|
Read(.env) 또는 Read(**/.env) |
현재 디렉토리 또는 그 아래의 모든 .env |
상위 디렉토리 또는 다른 프로젝트의 .env |
Read(//**/.env) |
파일 시스템의 어디든 모든 .env |
없음; 규칙은 파일 시스템 루트에 앵커됨 |
Claude가 심볼릭 링크에 액세스할 때 권한 규칙은 두 경로를 확인합니다: 심볼릭 링크 자체와 이것이 해결되는 파일입니다. Allow 및 deny 규칙은 해당 쌍을 다르게 취급합니다: allow 규칙은 프롬프트로 폴백하고 deny 규칙은 즉시 차단합니다.
- Allow 규칙: 심볼릭 링크 경로와 해당 대상이 모두 일치할 때만 적용됩니다. 허용된 디렉토리 내의 심볼릭 링크가 외부를 가리키면 여전히 프롬프트합니다.
- Deny 규칙: 심볼릭 링크 경로 또는 대상이 일치할 때 적용됩니다. 거부된 파일을 가리키는 심볼릭 링크는 자체적으로 거부됩니다.
예를 들어, Read(./project/**) allowed 및 Read(~/.ssh/**) denied를 사용하면 ./project/key의 심볼릭 링크가 ~/.ssh/id_rsa를 가리킬 때 차단됩니다: 대상이 allow 규칙에 실패하고 deny 규칙과 일치합니다.
WebFetch
WebFetch 규칙은 domain: 접두사를 사용하고 요청된 URL의 호스트명과 일치합니다. 일치는 대소문자를 구분하지 않으며, * 와일드카드를 지원하고, 규칙과 호스트명 모두에서 후행 .을 제거하므로 example.com.과 example.com은 동일하게 취급됩니다.
WebFetch(domain:example.com)은example.com으로의 요청과 일치합니다WebFetch(domain:*.example.com)은api.example.com또는a.b.example.com과 같은 모든 깊이의 모든 서브도메인과 일치하지만example.com자체는 일치하지 않습니다WebFetch(domain:*)는 모든 도메인과 일치하며 베어WebFetch규칙과 동등합니다
*는 선행 *. 또는 전체 패턴으로서만 .을 가로질러 일치합니다. 다른 곳에서는 하나의 레이블 내에 머물므로 WebFetch(domain:github.*)는 github.io와 일치하지만 공격자가 등록할 수 있는 도메인인 github.evil.com과는 일치하지 않습니다.
MCP
mcp__puppeteer는puppeteer서버(Claude Code에서 구성된 이름)에서 제공하는 모든 도구와 일치합니다mcp__puppeteer__*와일드카드 구문은puppeteer서버의 모든 도구와도 일치합니다mcp__puppeteer__puppeteer_navigate는puppeteer서버에서 제공하는puppeteer_navigate도구와 일치합니다
Agent (subagents)
Agent(AgentName) 규칙을 사용하여 Claude가 사용할 수 있는 subagents를 제어합니다:
Agent(Explore)는 Explore subagent와 일치합니다Agent(Plan)은 Plan subagent와 일치합니다Agent(my-custom-agent)는my-custom-agent라는 사용자 정의 subagent와 일치합니다
이러한 규칙을 설정의 deny 배열에 추가하거나 --disallowedTools CLI 플래그를 사용하여 특정 에이전트를 비활성화합니다. Explore 에이전트를 비활성화하려면:
{
"permissions": {
"deny": ["Agent(Explore)"]
}
}
Cd
Cd 규칙은 /cd 명령이 세션을 이동할 수 있는 디렉토리를 제어합니다. Cd는 모델 호출 가능 도구가 아닙니다: Claude는 이를 호출할 수 없으며 규칙은 사용자가 직접 /cd를 실행할 때만 적용됩니다.
베어 Cd deny 규칙은 /cd를 완전히 비활성화합니다. Cd(<path-pattern>) deny 규칙은 일치하는 대상을 차단합니다. Deny 규칙은 대상의 모든 철자를 확인하며, 이것이 해결되는 각 심볼릭 링크 홉을 포함하므로 한 경로에 대해 작성된 규칙은 그것으로 해결되는 대상도 차단합니다.
Cd allow 규칙을 추가하면 /cd를 허용 목록 모드로 전환합니다: 해결된 대상 디렉토리는 allow 규칙 중 하나와 일치해야 하거나 /cd는 거부합니다. Cd 규칙이 구성되지 않으면 /cd는 기본 동작을 유지하고 익숙하지 않은 디렉토리를 신뢰하도록 프롬프트합니다.
경로 패턴은 Read 및 Edit 규칙의 //, ~/ 및 / 앵커를 공유하지만 일치는 gitignore 스타일이 아닌 전체 디렉토리 경로에 앵커됩니다. *는 정확히 하나의 경로 세그먼트와 일치하고 **는 세그먼트 전체에서 일치합니다. 후행 /**는 또한 명명된 루트와 일치합니다.
| 규칙 | 일치 | 일치하지 않음 |
|---|---|---|
Cd(~/code/*) |
~/code/app |
~/code/app/src, ~/code |
Cd(~/code/**) |
~/code 및 그 아래의 모든 디렉토리 |
~/code 외부의 디렉토리 |
Cd(**/node_modules) |
어느 깊이에서나 모든 node_modules 디렉토리 |
node_modules/pkg |
훅으로 권한 확장
Claude Code 훅은 런타임에 권한 평가를 수행하기 위해 사용자 정의 셸 명령을 등록하는 방법을 제공합니다. Claude Code가 도구 호출을 할 때, PreToolUse 훅은 권한 프롬프트 전에 실행됩니다. 훅 출력은 도구 호출을 거부하거나, 프롬프트를 강제하거나, 프롬프트를 건너뛰어 호출을 진행하도록 할 수 있습니다.
훅 결정은 권한 규칙을 우회하지 않습니다. Deny 및 ask 규칙은 훅이 "allow" 또는 "ask"를 반환한 후에도 여전히 평가되므로 일치하는 deny 규칙은 호출을 차단하고 일치하는 ask 규칙은 훅이 "allow" 또는 "ask"를 반환했을 때도 여전히 프롬프트합니다. 이는 권한 관리에서 설명한 deny 우선 우선순위를 유지하며, 관리형 설정에서 설정한 deny 규칙을 포함합니다.
차단 훅은 또한 allow 규칙보다 우선합니다. 종료 코드 2로 종료되는 훅은 권한 규칙이 평가되기 전에 도구 호출을 중지하므로 allow 규칙이 호출을 허용할 수 있는 경우에도 차단이 적용됩니다. 모든 Bash 명령을 프롬프트 없이 실행하되 차단하려는 몇 가지를 제외하려면 allow 목록에 "Bash"를 추가하고 해당 특정 명령을 거부하는 PreToolUse 훅을 등록합니다. 적응할 수 있는 훅 스크립트는 보호된 파일에 대한 편집 차단을 참조합니다.
작업 디렉토리
기본적으로 Claude는 시작된 디렉토리의 파일에 액세스할 수 있습니다. 이 액세스를 확장할 수 있습니다:
- 시작 중:
--add-dir <path>CLI 인수 사용 - 세션 중:
/add-dir명령 사용 - 영구 구성: 설정 파일의
additionalDirectories에 추가
추가 디렉토리의 파일은 원래 작업 디렉토리와 동일한 권한 규칙을 따릅니다: 프롬프트 없이 읽을 수 있게 되며, 파일 편집 권한은 현재 권한 모드를 따릅니다.
세션의 기본 작업 디렉토리를 다른 디렉토리를 추가하는 대신 변경하려면 /cd를 사용합니다. /cd 명령은 Claude Code v2.1.169 이상이 필요합니다. /add-dir과 달리 세션을 재배치합니다: 새 디렉토리의 CLAUDE.md가 로드되고 --resume은 해당 위치에서 세션을 찾습니다.
추가 디렉토리는 파일 액세스를 부여하며, 구성은 아닙니다
디렉토리를 추가하면 Claude가 파일을 읽고 편집할 수 있는 위치가 확장됩니다. 해당 디렉토리를 전체 구성 루트로 만들지는 않습니다: 대부분의 .claude/ 구성은 추가 디렉토리에서 발견되지 않지만 몇 가지 유형은 예외로 로드됩니다.
이러한 예외는 --add-dir 플래그 또는 /add-dir 명령으로 추가된 디렉토리에만 적용됩니다. 설정 파일의 permissions.additionalDirectories에 나열된 디렉토리는 파일 액세스만 부여하며 아래의 구성을 로드하지 않습니다.
다음 구성 유형은 --add-dir 디렉토리에서 로드됩니다:
| 구성 | --add-dir에서 로드됨 |
|---|---|
.claude/skills/의 Skills |
예, 라이브 리로드 포함 |
.claude/agents/의 Subagents |
예 |
.claude/settings.json의 플러그인 설정 |
enabledPlugins 및 extraKnownMarketplaces만 |
CLAUDE.md 파일, .claude/rules/ 및 CLAUDE.local.md |
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1이 설정된 경우에만. CLAUDE.local.md는 추가로 local 설정 소스가 필요하며, 이는 기본적으로 활성화됩니다 |
명령 및 출력 스타일은 현재 작업 디렉토리 및 해당 부모, ~/.claude/의 사용자 디렉토리 및 관리형 설정에서 발견됩니다. Hooks 및 기타 settings.json 키는 현재 작업 디렉토리의 .claude/ 폴더에서 로드되며 부모 디렉토리 폴백이 없고, 사용자 ~/.claude/settings.json 및 관리형 설정과 함께 로드됩니다. 프로젝트 전체에서 해당 구성을 공유하려면 다음 방법 중 하나를 사용합니다:
- 사용자 수준 구성:
~/.claude/agents/,~/.claude/output-styles/또는~/.claude/settings.json에 파일을 배치하여 모든 프로젝트에서 사용 가능하게 합니다 - Plugins: 팀이 설치할 수 있는 plugin으로 구성을 패키징하고 배포합니다
- 구성 디렉토리에서 시작: 원하는
.claude/구성이 포함된 디렉토리에서 Claude Code를 실행합니다
권한이 샌드박싱과 상호 작용하는 방식
권한과 샌드박싱은 상호 보완적인 보안 계층입니다:
- 권한은 Claude Code가 사용할 수 있는 도구와 액세스할 수 있는 파일 또는 도메인을 제어합니다. 모든 도구(Bash, Read, Edit, WebFetch, MCP 등)에 적용됩니다.
- 샌드박싱은 Bash 도구의 파일 시스템 및 네트워크 액세스를 제한하는 OS 수준 적용을 제공합니다. Bash 명령 및 해당 자식 프로세스에만 적용됩니다.
심층 방어를 위해 둘 다 사용합니다:
- 권한 deny 규칙은 Claude가 제한된 리소스에 액세스하려고 시도하는 것을 차단합니다
- 샌드박스 제한은 프롬프트 주입이 Claude의 의사 결정을 우회하더라도 Bash 명령이 정의된 경계 외부의 리소스에 도달하는 것을 방지합니다
- 샌드박스의 파일 시스템 제한은
sandbox.filesystem설정을 Read 및 Edit deny 규칙과 결합합니다. 둘 다 최종 샌드박스 경계로 병합됩니다 - 네트워크 제한은 WebFetch 권한 규칙을 샌드박스의
allowedDomains및deniedDomains목록과 결합합니다
샌드박싱이 autoAllowBashIfSandboxed: true로 활성화되면(기본값), 권한에 Bash ask 규칙이 포함되어 있거나 동등한 Bash(*) 형식이 포함되어 있어도 샌드박스된 Bash 명령은 프롬프트 없이 실행됩니다. 샌드박스 경계는 전체 도구 프롬프트를 대체합니다. Bash(git push *)와 같은 콘텐츠 범위 ask 규칙은 여전히 프롬프트를 강제하고, 명시적 deny 규칙은 여전히 적용되며, /, 홈 디렉터리 또는 기타 중요한 시스템 경로를 대상으로 하는 rm 또는 rmdir 명령은 여전히 프롬프트를 트리거합니다. 제외된 명령과 같이 샌드박스에서 실행되지 않는 명령은 일반적인 Bash ask 규칙을 따릅니다. 샌드박스 모드를 참조하여 이 동작을 변경합니다.
관리형 설정
Claude Code 구성에 대한 중앙 집중식 제어가 필요한 조직의 경우, 관리자는 사용자 또는 프로젝트 설정으로 재정의할 수 없는 관리형 설정을 배포할 수 있습니다. 이러한 정책 설정은 일반 설정 파일과 동일한 형식을 따르며 MDM/OS 수준 정책, 관리형 설정 파일 또는 서버 관리형 설정을 통해 전달될 수 있습니다. 전달 메커니즘 및 파일 위치는 설정 파일을 참조합니다.
관리형 전용 설정
다음 설정은 관리형 설정에서만 읽혀집니다. 사용자 또는 프로젝트 설정 파일에 배치하면 효과가 없습니다.
| 설정 | 설명 |
|---|---|
allowAllClaudeAiMcps |
true일 때, claude.ai 커넥터는 배포된 managed-mcp.json과 함께 로드되며 그 배타적 제어에 의해 억제되지 않습니다. 관리형 MCP 구성 참조 |
allowedChannelPlugins |
메시지를 푸시할 수 있는 채널 플러그인의 허용 목록입니다. channelsEnabled: true가 필요할 때 기본 Anthropic 허용 목록을 대체합니다. 채널 플러그인이 실행될 수 있는 것을 제한합니다 참조 |
allowManagedHooksOnly |
true일 때, 관리형 훅, SDK 훅 및 관리형 설정 enabledPlugins에서 강제 활성화된 플러그인의 훅만 로드됩니다. 사용자, 프로젝트 및 다른 모든 플러그인 훅은 차단됩니다 |
allowManagedMcpServersOnly |
true일 때, 관리형 설정의 allowedMcpServers만 존중됩니다. deniedMcpServers는 여전히 모든 소스에서 병합됩니다. 관리형 MCP 구성 참조 |
allowManagedPermissionRulesOnly |
true일 때, 사용자 및 프로젝트 설정이 allow, ask 또는 deny 권한 규칙을 정의하는 것을 방지합니다. 관리형 설정의 규칙만 적용됩니다. MCP 서버 허용 목록에는 영향을 주지 않습니다. 그 경우 allowManagedMcpServersOnly를 설정합니다 |
blockedMarketplaces |
마켓플레이스 소스의 차단 목록입니다. 차단된 소스는 다운로드 전에 확인되므로 파일 시스템에 닿지 않습니다. 관리형 마켓플레이스 제한 참조 |
channelsEnabled |
조직을 위한 채널을 허용합니다. 각 플랜의 기본값은 엔터프라이즈 제어를 참조합니다 |
forceRemoteSettingsRefresh |
true일 때, 원격 관리형 설정이 새로 가져올 때까지 CLI 시작을 차단하고 가져오기에 실패하면 종료합니다. 실패 폐쇄 적용 참조 |
pluginTrustMessage |
설치 전에 표시되는 플러그인 신뢰 경고에 추가되는 사용자 정의 메시지 |
sandbox.filesystem.allowManagedReadPathsOnly |
true일 때, 관리형 설정의 filesystem.allowRead 경로만 존중됩니다. denyRead는 여전히 모든 소스에서 병합됩니다 |
sandbox.network.allowManagedDomainsOnly |
true일 때, 관리형 설정의 allowedDomains 및 WebFetch(domain:...) allow 규칙만 존중됩니다. 허용되지 않은 도메인은 사용자에게 프롬프트하지 않고 자동으로 차단됩니다. 거부된 도메인은 여전히 모든 소스에서 병합됩니다 |
strictKnownMarketplaces |
사용자가 추가하고 플러그인을 설치할 수 있는 플러그인 마켓플레이스 소스를 제어합니다. 관리형 마켓플레이스 제한 참조 |
strictPluginOnlyCustomization |
사용자 및 프로젝트 소스에서 스킬, 에이전트, 훅 및 MCP 서버를 차단하므로 플러그인 또는 관리형 설정에서만 올 수 있습니다. true는 네 가지 모두를 잠금; ["skills", "hooks"]와 같은 배열은 명명된 것만 잠금. strictPluginOnlyCustomization 참조 |
wslInheritsWindowsSettings |
Windows HKLM 레지스트리 키 또는 C:\Program Files\ClaudeCode\managed-settings.json에서 true일 때, WSL은 /etc/claude-code에 추가로 Windows 정책 체인에서 관리형 설정을 읽습니다. 설정 파일 참조 |
disableBypassPermissionsMode는 일반적으로 조직 정책을 적용하기 위해 관리형 설정에 배치되지만 모든 범위에서 작동합니다. 사용자는 자신의 설정에서 이를 설정하여 자신을 우회 모드에서 잠글 수 있습니다.
설정 우선순위
권한 규칙은 다른 모든 Claude Code 설정과 동일한 설정 우선순위를 따릅니다:
- 관리형 설정: 명령줄 인수를 포함한 다른 수준으로 재정의할 수 없습니다
- 명령줄 인수: 임시 세션 재정의
- 로컬 프로젝트 설정 (
.claude/settings.local.json) - 공유 프로젝트 설정 (
.claude/settings.json) - 사용자 설정 (
~/.claude/settings.json)
도구가 어느 수준에서든 거부되면 다른 수준은 이를 허용할 수 없습니다. 예를 들어, 관리형 설정 deny는 --allowedTools로 재정의할 수 없으며, --disallowedTools는 관리형 설정이 정의하는 것 이상의 제한을 추가할 수 있습니다.
Embedding hosts는 parentSettingsBehavior가 "merge"로 설정되어 있을 때 SDK managedSettings 옵션을 통해 추가 관리형 정책을 제공할 수 있습니다. Embedder 값은 정책을 강화할 수 있지만 완화할 수는 없습니다.
예를 들어, 사용자 설정에서 도구가 허용되고 프로젝트 설정에서 거부되면, deny 규칙이 이를 차단합니다. 그 반대도 마찬가지입니다: 사용자 수준의 deny는 프로젝트 수준의 allow를 차단합니다. 왜냐하면 모든 범위의 deny 규칙이 allow 규칙보다 먼저 평가되기 때문입니다.
예시 구성
이 저장소에는 일반적인 배포 시나리오에 대한 시작 설정 구성이 포함되어 있습니다. 이를 시작점으로 사용하고 필요에 맞게 조정합니다.