6.7 KiB
설정 파일 (settings.json)
사용자, 프로젝트, Managed 레벨의 JSON 설정 파일로 Claude Code 동작 설정.
Claude Code는 여러 범위의 JSON 파일에서 설정을 읽습니다. 낮은 우선순위에서 높은 우선순위 순으로 병합됩니다.
설정 파일 위치
전역(사용자): ~/.claude/settings.json
모든 프로젝트에 걸쳐 실행하는 모든 Claude Code 세션에 적용됩니다. 선호 모델, 테마, 정리 정책 같은 개인 설정을 여기에 설정합니다.
프로젝트(공유): .claude/settings.json (프로젝트 루트)
소스 컨트롤에 체크인됩니다. 프로젝트 작업자 모두에게 적용되어야 하는 설정 — 권한 규칙, 훅 설정, MCP 서버, 환경 변수.
로컬(개인 프로젝트): .claude/settings.local.json (프로젝트 루트)
소스 컨트롤에 체크인되지 않습니다(자동으로 .gitignore에 추가됨). 특정 프로젝트 내의 개인 재정의.
Managed(엔터프라이즈): 플랫폼별 시스템 경로 MDM, 레지스트리(Windows), plist(macOS), 또는 Managed 설정 파일을 통해 관리자가 설정합니다. Managed 설정은 최고 우선순위를 가지며 사용자나 프로젝트가 재정의할 수 없습니다.
설정 우선순위
플러그인 기본값 → 사용자 설정 → 프로젝트 설정 → 로컬 설정 → Managed(정책) 설정
Managed(정책) 설정은 항상 최종 우선순위를 가집니다.
설정 열기
세션 내에서 /config를 실행해 설정 UI를 엽니다. 각 범위의 현재 활성 설정을 찾아볼 수 있습니다. JSON 파일을 직접 편집할 수도 있습니다 — Claude Code가 파일 변경을 감지하면 자동으로 설정을 다시 로드합니다.
설정 레퍼런스
model
타입: string | 범위: 모든 범위
Claude Code가 사용하는 기본 모델 재정의. 설정된 공급자가 지원하는 모든 모델 ID 허용.
{ "model": "claude-opus-4-5" }
permissions
타입: object | 범위: 모든 범위
Claude가 사용할 수 있는 도구와 모드를 제어합니다. 규칙 구문은 권한 시스템 참조.
| 필드 | 타입 | 설명 |
|---|---|---|
allow |
string[] |
Claude가 확인 없이 수행할 수 있는 작업 규칙 |
deny |
string[] |
Claude가 항상 차단되는 작업 규칙 |
ask |
string[] |
항상 확인을 요청하는 작업 규칙 |
defaultMode |
string |
기본 권한 모드: "default", "acceptEdits", "plan", "bypassPermissions" |
disableBypassPermissionsMode |
"disable" |
사용자가 bypass permissions 모드에 들어가는 것을 방지 |
additionalDirectories |
string[] |
Claude가 접근할 수 있는 추가 디렉토리 |
hooks
타입: object | 범위: 모든 범위
도구 실행 전후에 커스텀 셸 커맨드를 실행합니다. 지원 훅 이벤트: PreToolUse, PostToolUse, Notification, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStop, PreCompact, PostCompact.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [{ "type": "command", "command": "prettier --write $CLAUDE_FILE_PATHS" }]
}
]
}
}
cleanupPeriodDays
타입: integer | 기본값: 30 | 범위: 모든 범위
채팅 트랜스크립트 보관 일수. 0으로 설정하면 세션 영속성이 완전히 비활성화됩니다.
env
타입: object | 범위: 모든 범위
모든 Claude Code 세션에 주입할 환경 변수. 값은 문자열로 변환됩니다.
{
"env": {
"NODE_ENV": "development",
"MY_API_URL": "https://api.example.com"
}
}
availableModels
타입: string[] | 범위: Managed만
사용자가 선택 가능한 모델의 엔터프라이즈 허용 목록. 패밀리 별칭("opus"는 모든 Opus 버전 허용), 버전 프리픽스, 또는 전체 모델 ID 허용.
worktree
타입: object | 범위: 모든 범위
--worktree 플래그 동작 설정.
| 필드 | 타입 | 설명 |
|---|---|---|
symlinkDirectories |
string[] |
worktree에 메인 저장소에서 심링크할 디렉토리 (예: "node_modules") |
sparsePaths |
string[] |
대규모 모노레포에서 빠른 worktree를 위한 sparse 체크아웃 경로 |
attribution
타입: object | 범위: 모든 범위
Claude가 커밋과 PR 설명에 추가하는 어트리뷰션 텍스트를 커스터마이징합니다.
{
"attribution": {
"commit": "Co-Authored-By: Claude <noreply@anthropic.com>",
"pr": ""
}
}
language
Claude 응답과 음성 받아쓰기에 선호되는 언어. { "language": "korean" }
alwaysThinkingEnabled
기본값: true — false로 설정해 확장 thinking 비활성화.
effortLevel
"low" | "medium" | "high" — thinking 예산을 지원하는 모델의 effort 레벨.
autoMemoryEnabled
범위: 사용자, 로컬 — 이 프로젝트의 자동 메모리 활성화 또는 비활성화.
respectGitignore
기본값: true — 파일 피커가 .gitignore 파일을 존중할지 여부.
defaultShell
"bash" | "powershell" — 입력 박스의 ! 커맨드용 기본 셸.
apiKeyHelper
범위: 사용자, Managed — API 키를 동적으로 검색하는 스크립트 경로. 스크립트는 stdout에 API 키만 출력하고 코드 0으로 종료해야 합니다.
Managed 설정 (엔터프라이즈)
관리자는 플랫폼 네이티브 메커니즘을 통해 모든 사용자에게 설정을 배포할 수 있습니다.
macOS: /Library/Preferences/에 plist 파일 배포 또는 MDM을 통해 com.anthropic.claudecode 타겟
Windows: HKLM\Software\Anthropic\Claude Code 레지스트리 키에 설정 작성
파일 기반: Managed 설정 파일을 플랫폼별 managed 경로에 배치. 드롭인 설정 조각에는 managed-settings.d/ 디렉토리 사용(알파벳 순으로 정렬 및 병합됨).
Managed 전용 잠금 설정
| 설정 | 설명 |
|---|---|
allowManagedHooksOnly |
true로 설정 시 Managed 설정의 훅만 실행 |
allowManagedPermissionRulesOnly |
true로 설정 시 Managed 설정의 권한 규칙만 존중 |
allowManagedMcpServersOnly |
true로 설정 시 허용 MCP 서버 목록을 Managed 설정에서만 읽음 |
strictPluginOnlyCustomization |
특정 커스터마이징 표면을 플러그인 전용 소스로 잠금 |
JSON 스키마
에디터 자동완성 및 유효성 검사를 위해 설정 파일에 $schema 추가:
{
"$schema": "https://schemas.anthropic.com/claude-code/settings.json"
}