권한 구성

세밀한 권한 규칙, 모드, 관리형 정책으로 Claude Code가 접근하고 수행할 수 있는 작업을 제어하세요.

Claude Code는 세밀한 권한을 지원하여 에이전트가 할 수 있는 것과 할 수 없는 것을 정확하게 지정할 수 있습니다. 권한 설정은 버전 관리에 체크인하여 조직 내 모든 개발자에게 배포할 수 있으며, 개별 개발자가 커스터마이즈할 수도 있습니다.

권한 시스템

Claude Code는 계층형 권한 시스템을 사용하여 기능과 안전성의 균형을 맞춥니다:

도구 유형	예시	승인 필요 여부	"네, 다시 묻지 마세요" 동작
읽기 전용	파일 읽기, Grep	아니오	해당 없음
Bash 명령어	셸 실행	예	프로젝트 디렉토리 및 명령어별 영구 적용
파일 수정	파일 편집/쓰기	예	세션 종료까지

권한 관리

/permissions로 Claude Code의 도구 권한을 확인하고 관리할 수 있습니다. 이 UI는 모든 권한 규칙과 해당 규칙이 참조하는 settings.json 파일을 나열합니다.

• Allow 규칙은 Claude Code가 수동 승인 없이 지정된 도구를 사용할 수 있게 합니다.
• Ask 규칙은 Claude Code가 지정된 도구를 사용하려 할 때마다 확인을 요청합니다.
• Deny 규칙은 Claude Code가 지정된 도구를 사용하지 못하게 합니다.

규칙은 다음 순서로 평가됩니다: deny -> ask -> allow. 첫 번째로 일치하는 규칙이 적용되므로, deny 규칙이 항상 우선합니다.

권한 모드

Claude Code는 도구 승인 방식을 제어하는 여러 권한 모드를 지원합니다. 설정 파일에서 defaultMode를 설정하세요:

모드	설명
default	표준 동작: 각 도구 첫 사용 시 권한을 요청합니다
acceptEdits	세션 동안 파일 편집 권한을 자동으로 수락합니다
plan	Plan 모드: Claude가 파일을 분석할 수 있지만 수정하거나 명령을 실행할 수 없습니다
dontAsk	/permissions 또는 permissions.allow 규칙으로 사전 승인되지 않은 도구를 자동 거부합니다
bypassPermissions	모든 권한 프롬프트를 건너뜁니다 (안전한 환경 필요, 아래 경고 참조)

주의:

bypassPermissions 모드는 모든 권한 검사를 비활성화합니다. Claude Code가 손상을 일으킬 수 없는 컨테이너나 VM 같은 격리된 환경에서만 사용하세요. 관리자는 관리형 설정에서 disableBypassPermissionsMode를 "disable"로 설정하여 이 모드를 차단할 수 있습니다.

권한 규칙 구문

권한 규칙은 Tool 또는 Tool(specifier) 형식을 따릅니다.

도구의 모든 사용에 매칭

도구의 모든 사용에 매칭하려면 괄호 없이 도구 이름만 사용하세요:

규칙	효과
Bash	모든 Bash 명령어에 매칭
WebFetch	모든 웹 페치 요청에 매칭
Read	모든 파일 읽기에 매칭

Bash(*)는 Bash와 동일하며 모든 Bash 명령어에 매칭됩니다.

세밀한 제어를 위한 지정자 사용

괄호 안에 지정자를 추가하여 특정 도구 사용에 매칭하세요:

규칙	효과
Bash(npm run build)	정확히 npm run build 명령어에 매칭
Read(./.env)	현재 디렉토리의 .env 파일 읽기에 매칭
WebFetch(domain:example.com)	example.com에 대한 페치 요청에 매칭

와일드카드 패턴

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

Bash 권한 규칙은 *를 사용한 와일드카드 매칭을 지원합니다. 와일드카드는 명령어의 시작, 중간, 끝 등 어느 위치에나 사용할 수 있습니다:

• Bash(npm run build)는 정확히 npm run build Bash 명령어에 매칭됩니다
• Bash(npm run test *)는 npm run test로 시작하는 Bash 명령어에 매칭됩니다
• Bash(npm *)는 npm 으로 시작하는 모든 명령어에 매칭됩니다
• Bash(* install)는 install로 끝나는 모든 명령어에 매칭됩니다
• Bash(git * main)는 git checkout main, git merge main 같은 명령어에 매칭됩니다

*가 앞에 공백과 함께 끝에 나타나면 (Bash(ls *)처럼), 단어 경계를 강제하여 접두사 뒤에 공백이 오거나 문자열이 끝나야 합니다. 예를 들어 Bash(ls *)는 ls -la에 매칭되지만 lsof에는 매칭되지 않습니다. 반면 공백 없이 Bash(ls*)는 단어 경계 제약이 없으므로 ls -la와 lsof 모두에 매칭됩니다.

팁:

Claude Code는 셸 연산자(&& 등)를 인식하므로 Bash(safe-cmd *) 같은 접두사 매칭 규칙은 safe-cmd && other-cmd 명령어에 대한 권한을 부여하지 않습니다.

주의:

명령어 인수를 제한하려는 Bash 권한 패턴은 취약합니다. 예를 들어 Bash(curl http://github.com/ *)는 curl을 GitHub URL로 제한하려 하지만 다음과 같은 변형에는 매칭되지 않습니다:

• URL 앞 옵션: curl -X GET http://github.com/...
• 다른 프로토콜: curl https://github.com/...
• 리다이렉트: curl -L http://bit.ly/xyz (github로 리다이렉트)
• 변수: URL=http://github.com && curl $URL
• 추가 공백: curl http://github.com

보다 안정적인 URL 필터링을 위해 다음을 고려하세요:

• Bash 네트워크 도구 제한: deny 규칙으로 curl, wget 및 유사 명령어를 차단하고, 허용된 도메인에 대해 WebFetch(domain:github.com) 권한과 함께 WebFetch 도구를 사용하세요
• PreToolUse 훅 사용: Bash 명령어의 URL을 검증하고 허용되지 않은 도메인을 차단하는 훅을 구현하세요
• CLAUDE.md를 통해 허용된 curl 패턴에 대해 Claude Code에 지시하세요

WebFetch만 사용해도 네트워크 접근을 방지하지 못합니다. Bash가 허용되면 Claude는 여전히 curl, wget 또는 다른 도구를 사용하여 모든 URL에 접근할 수 있습니다.

Read와 Edit

Edit 규칙은 파일을 편집하는 모든 내장 도구에 적용됩니다. Claude는 Grep과 Glob 같은 파일을 읽는 모든 내장 도구에 Read 규칙을 최선을 다해 적용합니다.

Read와 Edit 규칙은 모두 네 가지 패턴 유형이 있는 gitignore 명세를 따릅니다:

패턴	의미	예시	매칭 대상
//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

주의:

/Users/alice/file 같은 패턴은 절대 경로가 아닙니다. 프로젝트 루트 기준 상대 경로입니다. 절대 경로를 사용하려면 //Users/alice/file을 사용하세요.

예시:

• Edit(/docs/**): <project>/docs/에서의 편집 (/docs/가 아니고 <project>/.claude/docs/도 아님)
• Read(~/.zshrc): 홈 디렉토리의 .zshrc 읽기
• Edit(//tmp/scratch.txt): 절대 경로 /tmp/scratch.txt 편집
• Read(src/**): <current-directory>/src/에서 읽기

참고:

gitignore 패턴에서 *는 단일 디렉토리 내 파일에 매칭되고 **는 디렉토리를 재귀적으로 넘어 매칭됩니다. 모든 파일 접근을 허용하려면 괄호 없이 도구 이름만 사용하세요: Read, Edit, 또는 Write.

WebFetch

• WebFetch(domain:example.com)는 example.com에 대한 페치 요청에 매칭됩니다

MCP

• mcp__puppeteer는 puppeteer 서버(Claude Code에서 구성된 이름)가 제공하는 모든 도구에 매칭됩니다
• mcp__puppeteer__*는 puppeteer 서버의 모든 도구에 매칭되는 와일드카드 구문입니다
• mcp__puppeteer__puppeteer_navigate는 puppeteer 서버가 제공하는 puppeteer_navigate 도구에 매칭됩니다

Agent (서브에이전트)

Agent(AgentName) 규칙을 사용하여 Claude가 사용할 수 있는 서브에이전트를 제어하세요:

• Agent(Explore)는 Explore 서브에이전트에 매칭됩니다
• Agent(Plan)는 Plan 서브에이전트에 매칭됩니다
• Agent(my-custom-agent)는 my-custom-agent라는 이름의 커스텀 서브에이전트에 매칭됩니다

이 규칙을 설정의 deny 배열에 추가하거나 --disallowedTools CLI 플래그를 사용하여 특정 에이전트를 비활성화하세요. Explore 에이전트를 비활성화하려면:

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

훅으로 권한 확장

Claude Code 훅은 런타임에 권한 평가를 수행하는 커스텀 셸 명령어를 등록하는 방법을 제공합니다. Claude Code가 도구를 호출하면 PreToolUse 훅이 권한 시스템보다 먼저 실행되며, 훅 출력이 권한 시스템 대신 도구 호출의 승인 또는 거부 여부를 결정할 수 있습니다.

작업 디렉토리

기본적으로 Claude는 실행된 디렉토리의 파일에 접근할 수 있습니다. 다음과 같이 접근 범위를 확장할 수 있습니다:

• 시작 시: --add-dir <path> CLI 인수 사용
• 세션 중: /add-dir 명령어 사용
• 영구 구성: 설정 파일의 additionalDirectories에 추가

추가 디렉토리의 파일은 원래 작업 디렉토리와 동일한 권한 규칙을 따릅니다: 프롬프트 없이 읽기가 가능하며, 파일 편집 권한은 현재 권한 모드를 따릅니다.

권한과 샌드박싱의 상호작용

권한과 샌드박싱은 상호 보완적인 보안 레이어입니다:

• 권한은 Claude Code가 사용할 수 있는 도구와 접근할 수 있는 파일이나 도메인을 제어합니다. 모든 도구(Bash, Read, Edit, WebFetch, MCP 등)에 적용됩니다.
• 샌드박싱은 Bash 도구의 파일시스템 및 네트워크 접근을 제한하는 OS 수준 강제를 제공합니다. Bash 명령어와 그 자식 프로세스에만 적용됩니다.

심층 방어를 위해 둘 다 사용하세요:

• 권한 deny 규칙은 Claude가 제한된 리소스에 접근을 시도하는 것조차 차단합니다
• 샌드박스 제한은 프롬프트 인젝션이 Claude의 의사결정을 우회하더라도 Bash 명령어가 정의된 경계 밖의 리소스에 접근하는 것을 방지합니다
• 샌드박스의 파일시스템 제한은 별도의 샌드박스 구성이 아닌 Read 및 Edit deny 규칙을 사용합니다
• 네트워크 제한은 WebFetch 권한 규칙과 샌드박스의 allowedDomains 목록을 결합합니다

관리형 설정

조직에서 Claude Code 구성을 중앙 집중식으로 제어해야 하는 경우, 관리자는 사용자나 프로젝트 설정으로 재정의할 수 없는 관리형 설정을 배포할 수 있습니다. 이러한 정책 설정은 일반 설정 파일과 동일한 형식을 따르며 MDM/OS 수준 정책, 관리형 설정 파일 또는 서버 관리형 설정을 통해 전달할 수 있습니다. 전달 메커니즘과 파일 위치는 설정 파일을 참조하세요.

관리형 전용 설정

일부 설정은 관리형 설정에서만 유효합니다:

설정	설명
disableBypassPermissionsMode	"disable"로 설정하면 bypassPermissions 모드와 --dangerously-skip-permissions 플래그를 차단합니다
allowManagedPermissionRulesOnly	true일 때 사용자 및 프로젝트 설정에서 allow, ask, deny 권한 규칙 정의를 차단합니다. 관리형 설정의 규칙만 적용됩니다
allowManagedHooksOnly	true일 때 사용자, 프로젝트, 플러그인 훅 로딩을 차단합니다. 관리형 훅과 SDK 훅만 허용됩니다
allowManagedMcpServersOnly	true일 때 관리형 설정의 allowedMcpServers만 적용됩니다. deniedMcpServers는 여전히 모든 소스에서 병합됩니다. 관리형 MCP 구성 참조
blockedMarketplaces	마켓플레이스 소스의 차단 목록입니다. 차단된 소스는 다운로드 전에 확인되므로 파일시스템에 접근하지 않습니다. 관리형 마켓플레이스 제한 참조
sandbox.network.allowManagedDomainsOnly	true일 때 관리형 설정의 allowedDomains와 WebFetch(domain:...) allow 규칙만 적용됩니다. 허용되지 않은 도메인은 사용자에게 프롬프트 없이 자동 차단됩니다. 거부된 도메인은 여전히 모든 소스에서 병합됩니다
strictKnownMarketplaces	사용자가 추가할 수 있는 플러그인 마켓플레이스를 제어합니다. 관리형 마켓플레이스 제한 참조
allow_remote_sessions	true일 때 사용자가 원격 제어 및 웹 세션을 시작할 수 있습니다. 기본값은 true입니다. 원격 세션 접근을 방지하려면 false로 설정하세요

설정 우선순위

권한 규칙은 다른 모든 Claude Code 설정과 동일한 설정 우선순위를 따릅니다:

1. 관리형 설정: 명령줄 인수를 포함하여 다른 어떤 레벨로도 재정의할 수 없습니다
2. 명령줄 인수: 임시 세션 재정의
3. 로컬 프로젝트 설정 (.claude/settings.local.json)
4. 공유 프로젝트 설정 (.claude/settings.json)
5. 사용자 설정 (~/.claude/settings.json)

도구가 어떤 레벨에서든 거부되면, 다른 레벨에서 허용할 수 없습니다. 예를 들어 관리형 설정의 deny는 --allowedTools로 재정의할 수 없으며, --disallowedTools는 관리형 설정이 정의한 것 이상으로 제한을 추가할 수 있습니다.

권한이 사용자 설정에서 허용되었지만 프로젝트 설정에서 거부된 경우, 프로젝트 설정이 우선하여 해당 권한이 차단됩니다.

예시 구성

이 저장소에는 일반적인 배포 시나리오를 위한 시작용 설정 구성이 포함되어 있습니다. 이를 시작점으로 사용하고 필요에 맞게 조정하세요.

함께 보기

• 설정: 권한 설정 테이블을 포함한 전체 구성 레퍼런스
• 샌드박싱: Bash 명령어를 위한 OS 수준 파일시스템 및 네트워크 격리
• 인증: Claude Code에 대한 사용자 접근 설정
• 보안: 보안 보호 장치 및 모범 사례
• 훅: 워크플로 자동화 및 권한 평가 확장