132 lines
5.8 KiB
Markdown
132 lines
5.8 KiB
Markdown
# 권한 시스템
|
|
|
|
> Claude Code가 어떤 작업을 자동으로 수행하고 어떤 작업에 명시적 승인이 필요한지 제어하는 방법.
|
|
|
|
Claude Code는 로컬 머신에서 도구를 실행합니다 — 셸 커맨드 실행, 파일 편집, URL 가져오기. 권한 시스템은 Claude가 자동으로 수행하는 작업과 명시적 승인이 필요한 작업을 정밀하게 제어합니다.
|
|
|
|
## 권한이 제어하는 것
|
|
|
|
권한은 세 가지 작업 범주에 적용됩니다:
|
|
|
|
- **파일 작업** — `Read`, `Edit`, `Write` 도구를 통한 로컬 파일시스템 읽기, 편집, 쓰기
|
|
- **Bash 커맨드** — `Bash` 도구를 통한 셸 커맨드 실행(설치, 빌드, git 작업, 임의 스크립트 포함)
|
|
- **MCP 도구 호출** — 연결된 MCP 서버가 노출한 도구(데이터베이스 쿼리, API 호출, 브라우저 자동화 등)
|
|
|
|
## 권한 모드
|
|
|
|
권한 모드는 특정 허용/차단 규칙과 일치하는 도구 호출이 없을 때의 기본 동작을 결정합니다. 모드를 한 번 설정하면 세션 전체에 적용됩니다.
|
|
|
|
**`default` — 잠재적으로 위험한 작업에 확인 요청**
|
|
표준 모드. 셸 커맨드 실행, 파일 편집, 네트워크 요청 등 부작용이 있을 수 있는 작업에 확인을 요청합니다. 파일 읽기, 검색 등 읽기 전용 작업은 자동 승인됩니다. 일상적인 사용에 권장됩니다.
|
|
|
|
**`acceptEdits` — 파일 편집 자동 승인**
|
|
`Edit`, `Write` 도구가 프롬프트 없이 자동 승인됩니다. Bash 커맨드는 여전히 확인이 필요합니다. Claude가 파일을 자유롭게 편집하도록 하되 셸 커맨드는 검토하고 싶을 때 유용합니다.
|
|
|
|
**`plan` — 읽기 전용 계획 모드**
|
|
Claude가 파일을 읽고, 코드베이스를 검색하고, 변경 사항에 대해 논의할 수 있지만 쓰기 또는 bash 작업을 실행할 수 없습니다. 모든 변경 도구 호출이 차단됩니다. Claude가 문제를 분석하고 변경 사항을 승인하기 전에 계획을 만들도록 할 때 사용하세요.
|
|
|
|
**`bypassPermissions` — 모든 권한 검사 건너뛰기**
|
|
모든 권한 검사가 비활성화됩니다. 모든 도구 호출이 확인 프롬프트 없이 즉시 실행됩니다.
|
|
> ⚠️ 이 모드는 Claude가 수행할 작업을 미리 감사한 완전 스크립트화된 자동화 워크플로우 전용입니다. Claude가 예기치 않은 작업을 취할 수 있는 대화형 세션에서는 절대 사용하지 마세요.
|
|
|
|
## 권한 모드 설정 방법
|
|
|
|
**CLI 플래그:**
|
|
```bash
|
|
claude --permission-mode acceptEdits
|
|
claude --permission-mode bypassPermissions
|
|
claude --permission-mode plan
|
|
```
|
|
|
|
**`/permissions` 커맨드 (세션 중):**
|
|
```
|
|
/permissions
|
|
```
|
|
재시작 없이 모드를 변경합니다.
|
|
|
|
**settings.json:**
|
|
```json
|
|
{
|
|
"defaultMode": "acceptEdits"
|
|
}
|
|
```
|
|
유효한 값: `"default"`, `"acceptEdits"`, `"bypassPermissions"`, `"plan"`, `"dontAsk"`
|
|
|
|
## 권한 규칙 (허용/차단 목록)
|
|
|
|
전역 모드 외에도, 활성 모드에 관계없이 특정 도구 호출을 항상 허용하거나 항상 차단하는 세분화된 규칙을 만들 수 있습니다.
|
|
|
|
규칙은 세 가지 구성 요소를 가집니다:
|
|
|
|
| 필드 | 설명 |
|
|
|------|------|
|
|
| `toolName` | 규칙이 적용되는 도구 이름 (예: `"Bash"`, `"Edit"`, `"mcp__myserver"`) |
|
|
| `ruleContent` | 도구 입력과 일치해야 하는 선택적 패턴 |
|
|
| `behavior` | `"allow"`, `"deny"`, 또는 `"ask"` |
|
|
|
|
규칙은 권한 모드보다 **먼저** 평가됩니다. 일치하는 규칙이 있으면 해당 동작이 즉시 적용됩니다.
|
|
|
|
### 예시: 특정 git 커맨드 항상 허용
|
|
|
|
```json
|
|
{
|
|
"permissions": {
|
|
"allow": [
|
|
"Bash(git status)",
|
|
"Bash(git diff *)",
|
|
"Bash(git log *)",
|
|
"Read(*)"
|
|
],
|
|
"deny": [
|
|
"Bash(rm -rf *)",
|
|
"Bash(sudo *)"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Bash 권한 작동 방식
|
|
|
|
**패턴 매칭:**
|
|
- `git status` — 정확한 일치만
|
|
- `git *` — 모든 `git` 서브커맨드와 일치
|
|
- `npm run *` — 모든 `npm run` 스크립트와 일치
|
|
- `*` — 모든 bash 커맨드와 일치 (극도의 주의 필요)
|
|
|
|
**복합 커맨드:**
|
|
`&&`, `||`, `;`, 파이프(`|`)로 연결된 복합 커맨드는 각 서브커맨드가 독립적으로 검사됩니다. 하나의 서브커맨드라도 차단되면 전체 복합 커맨드가 차단됩니다.
|
|
|
|
**항상 차단/에스컬레이션되는 작업:**
|
|
- 프로젝트 디렉토리 외부 경로로의 출력 리다이렉션(`>`, `>>`)
|
|
- 워킹트리 외부로의 디렉토리 변경(`cd`)
|
|
- `sed -i` 편집 인플레이스 커맨드(파일 수정 추적을 위해 특별 처리)
|
|
- `.claude/` 또는 `.git/` 설정 디렉토리를 대상으로 하는 커맨드
|
|
- 셸 설정 파일 수정(`.bashrc`, `.zshrc` 등)
|
|
|
|
## MCP 도구 권한
|
|
|
|
MCP 도구는 내장 도구와 동일한 규칙 시스템을 따릅니다:
|
|
|
|
```json
|
|
{
|
|
"permissions": {
|
|
"deny": [
|
|
"mcp__myserver"
|
|
],
|
|
"allow": [
|
|
"mcp__myserver__read_database"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
`mcp__servername`을 규칙으로 사용하면(특정 도구 이름 없이) 해당 서버의 모든 도구가 차단됩니다 — 모델이 보기 전에 도구 목록에서 필터링됩니다.
|
|
|
|
## 보안 권장 사항
|
|
|
|
- **`default` 모드**로 모든 대화형 세션을 시작하세요
|
|
- 익숙하지 않은 코드베이스를 탐색하거나 큰 변경 사항을 설계할 때는 **`plan` 모드**를 사용하세요
|
|
- Claude가 파일을 자유롭게 편집하도록 하되 셸 커맨드는 검토하려면 **`acceptEdits`**를 사용하세요
|
|
- 광범위한 모드 에스컬레이션 대신 **세분화된 허용 규칙**을 선호하세요. `Bash(git *)`를 허용하는 것이 `bypassPermissions`로 전환하는 것보다 안전합니다
|
|
- 친숙하지 않은 저장소를 클론할 때 `.claude/settings.json`을 검토하세요 — 권한 규칙이 미리 설정되어 있을 수 있습니다
|