> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Claude Code 설정
> 전역 및 프로젝트 수준 설정과 환경 변수로 Claude Code를 구성합니다.
Claude Code는 사용자의 필요에 맞게 동작을 구성할 수 있는 다양한 설정을 제공합니다. 대화형 REPL을 사용할 때 `/config` 명령을 실행하여 Claude Code를 구성할 수 있으며, 이는 상태 정보를 보고 구성 옵션을 수정할 수 있는 탭 형식의 설정 인터페이스를 엽니다.
## 구성 범위
Claude Code는 **범위 시스템**을 사용하여 구성이 어디에 적용되고 누가 공유하는지 결정합니다. 범위를 이해하면 개인 사용, 팀 협업 또는 엔터프라이즈 배포를 위해 Claude Code를 구성하는 방법을 결정하는 데 도움이 됩니다.
### 사용 가능한 범위
| 범위 | 위치 | 영향을 받는 대상 | 팀과 공유? |
| :---------- | :-------------------------------------------------------- | :------------ | :--------------- |
| **Managed** | 서버 관리 설정, plist / 레지스트리 또는 시스템 수준 `managed-settings.json` | 머신의 모든 사용자 | 예 (IT에서 배포) |
| **User** | `~/.claude/` 디렉토리 | 모든 프로젝트에서 사용자 | 아니오 |
| **Project** | 저장소의 `.claude/` | 이 저장소의 모든 협업자 | 예 (git에 커밋됨) |
| **Local** | `.claude/settings.local.json` | 이 저장소에서만 사용자 | 아니오 (gitignored) |
### 각 범위를 사용할 때
**Managed 범위**는 다음을 위한 것입니다:
* 조직 전체에서 적용해야 하는 보안 정책
* 재정의할 수 없는 규정 준수 요구 사항
* IT/DevOps에서 배포한 표준화된 구성
**User 범위**는 다음에 가장 적합합니다:
* 모든 곳에서 원하는 개인 설정 (테마, 편집기 설정)
* 모든 프로젝트에서 사용하는 도구 및 플러그인
* API 키 및 인증 (안전하게 저장됨)
**Project 범위**는 다음에 가장 적합합니다:
* 팀 공유 설정 (권한, hooks, MCP servers)
* 전체 팀이 가져야 할 플러그인
* 협업자 간 도구 표준화
**Local 범위**는 다음에 가장 적합합니다:
* 특정 프로젝트에 대한 개인 재정의
* 팀과 공유하기 전에 구성 테스트
* 다른 사용자에게는 작동하지 않을 머신 특정 설정
### 범위가 상호 작용하는 방식
동일한 설정이 여러 범위에서 구성되면 더 구체적인 범위가 우선합니다:
1. **Managed** (최고) - 아무것도 재정의할 수 없음
2. **명령줄 인수** - 임시 세션 재정의
3. **Local** - 프로젝트 및 사용자 설정 재정의
4. **Project** - 사용자 설정 재정의
5. **User** (최저) - 다른 것이 설정을 지정하지 않을 때 적용
예를 들어, 사용자 설정에서는 권한이 허용되지만 프로젝트 설정에서는 거부되면, 프로젝트 설정이 우선하고 권한이 차단됩니다.
### 범위를 사용하는 것
범위는 많은 Claude Code 기능에 적용됩니다:
| 기능 | 사용자 위치 | 프로젝트 위치 | Local 위치 |
| :-------------- | :------------------------ | :--------------------------------- | :---------------------------- |
| **Settings** | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |
| **Subagents** | `~/.claude/agents/` | `.claude/agents/` | 없음 |
| **MCP servers** | `~/.claude.json` | `.mcp.json` | `~/.claude.json` (프로젝트별) |
| **Plugins** | `~/.claude/settings.json` | `.claude/settings.json` | `.claude/settings.local.json` |
| **CLAUDE.md** | `~/.claude/CLAUDE.md` | `CLAUDE.md` 또는 `.claude/CLAUDE.md` | `CLAUDE.local.md` |
***
## 설정 파일
`settings.json` 파일은 계층적 설정을 통해 Claude Code를 구성하기 위한 공식 메커니즘입니다:
* **사용자 설정**은 `~/.claude/settings.json`에 정의되며 모든 프로젝트에 적용됩니다.
* **프로젝트 설정**은 프로젝트 디렉토리에 저장됩니다:
* 소스 제어에 체크인되고 팀과 공유되는 설정을 위한 `.claude/settings.json`
* 체크인되지 않은 설정을 위한 `.claude/settings.local.json`으로, 개인 설정 및 실험에 유용합니다. Claude Code는 `.claude/settings.local.json`이 생성될 때 git을 구성하여 이를 무시하도록 합니다.
* **Managed 설정**: 중앙 집중식 제어가 필요한 조직의 경우 Claude Code는 managed 설정을 위한 여러 전달 메커니즘을 지원합니다. 모두 동일한 JSON 형식을 사용하며 사용자 또는 프로젝트 설정으로 재정의할 수 없습니다:
* **서버 관리 설정**: Anthropic의 서버에서 Claude.ai 관리 콘솔을 통해 전달됩니다. [서버 관리 설정](/ko/server-managed-settings)을 참조하세요.
* **MDM/OS 수준 정책**: macOS 및 Windows의 기본 장치 관리를 통해 전달됩니다:
* macOS: `com.anthropic.claudecode` managed preferences domain. plist의 최상위 키는 `managed-settings.json`을 반영하며, 중첩된 설정은 딕셔너리이고 배열은 plist 배열입니다. Jamf, Kandji (Iru) 또는 유사한 MDM 도구의 구성 프로필을 통해 배포합니다.
* Windows: `HKLM\SOFTWARE\Policies\ClaudeCode` 레지스트리 키와 JSON을 포함하는 `Settings` 값 (REG\_SZ 또는 REG\_EXPAND\_SZ) (그룹 정책 또는 Intune을 통해 배포)
* Windows (사용자 수준): `HKCU\SOFTWARE\Policies\ClaudeCode` (최저 정책 우선순위, 관리자 수준 소스가 없을 때만 사용)
* **파일 기반**: 시스템 디렉토리에 배포된 `managed-settings.json` 및 `managed-mcp.json`:
* macOS: `/Library/Application Support/ClaudeCode/`
* Linux 및 WSL: `/etc/claude-code/`
* Windows: `C:\Program Files\ClaudeCode\`
레거시 Windows 경로 `C:\ProgramData\ClaudeCode\managed-settings.json`은 v2.1.75부터 더 이상 지원되지 않습니다. 해당 위치에 설정을 배포한 관리자는 파일을 `C:\Program Files\ClaudeCode\managed-settings.json`으로 마이그레이션해야 합니다.
파일 기반 managed 설정은 `managed-settings.json`과 동일한 시스템 디렉토리에 `managed-settings.d/` 드롭인 디렉토리도 지원합니다. 이를 통해 별도의 팀이 단일 파일 편집을 조정하지 않고 독립적인 정책 조각을 배포할 수 있습니다.
systemd 규칙을 따르면 `managed-settings.json`이 먼저 기본으로 병합되고, 드롭인 디렉토리의 모든 `*.json` 파일이 알파벳순으로 정렬되어 위에 병합됩니다. 스칼라 값의 경우 나중 파일이 이전 파일을 재정의합니다. 배열은 연결되고 중복 제거됩니다. 객체는 깊게 병합됩니다. `.`로 시작하는 숨겨진 파일은 무시됩니다.
병합 순서를 제어하려면 숫자 접두사를 사용합니다 (예: `10-telemetry.json` 및 `20-security.json`).
[managed 설정](/ko/permissions#managed-only-settings) 및 [Managed MCP 구성](/ko/mcp#managed-mcp-configuration)을 참조하세요.
이 [저장소](https://github.com/anthropics/claude-code/tree/main/examples/mdm)에는 Jamf, Kandji (Iru), Intune 및 그룹 정책에 대한 시작 배포 템플릿이 포함되어 있습니다. 이를 시작점으로 사용하고 필요에 맞게 조정합니다.
Managed 배포는 `strictKnownMarketplaces`를 사용하여 **플러그인 마켓플레이스 추가**를 제한할 수도 있습니다. 자세한 내용은 [Managed 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요.
* **기타 구성**은 `~/.claude.json`에 저장됩니다. 이 파일에는 OAuth 세션, [MCP server](/ko/mcp) 구성 (사용자 및 local 범위), 프로젝트별 상태 (허용된 도구, 신뢰 설정) 및 다양한 캐시가 포함됩니다. 프로젝트 범위 MCP 서버는 `.mcp.json`에 별도로 저장됩니다.
Claude Code는 자동으로 구성 파일의 타임스탬프가 지정된 백업을 생성하고 데이터 손실을 방지하기 위해 가장 최근의 5개 백업을 유지합니다.
```JSON 예제 settings.json theme={null}
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)",
"Read(~/.zshrc)"
],
"deny": [
"Bash(curl *)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
]
},
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_METRICS_EXPORTER": "otlp"
},
"companyAnnouncements": [
"Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
"Reminder: Code reviews required for all PRs",
"New security policy in effect"
]
}
```
위의 예제에서 `$schema` 줄은 Claude Code 설정에 대한 [공식 JSON 스키마](https://json.schemastore.org/claude-code-settings.json)를 가리킵니다. 이를 `settings.json`에 추가하면 VS Code, Cursor 및 JSON 스키마 검증을 지원하는 다른 편집기에서 자동 완성 및 인라인 검증이 활성화됩니다.
게시된 스키마는 주기적으로 업데이트되며 가장 최근 CLI 릴리스에서 추가된 설정을 포함하지 않을 수 있으므로, 최근에 문서화된 필드에 대한 검증 경고가 반드시 구성이 유효하지 않음을 의미하지는 않습니다.
### 사용 가능한 설정
`settings.json`은 여러 옵션을 지원합니다:
| 키 | 설명 | 예제 |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| `agent` | 메인 스레드를 명명된 subagent로 실행합니다. 해당 subagent의 시스템 프롬프트, 도구 제한 및 모델을 적용합니다. [subagents 명시적으로 호출](/ko/sub-agents#invoke-subagents-explicitly)을 참조하세요 | `"code-reviewer"` |
| `allowedChannelPlugins` | (Managed 설정만) 메시지를 푸시할 수 있는 채널 플러그인의 허용 목록입니다. 설정되면 기본 Anthropic 허용 목록을 대체합니다. 정의되지 않음 = 기본값으로 폴백, 빈 배열 = 모든 채널 플러그인 차단. `channelsEnabled: true`가 필요합니다. [채널 플러그인 실행 제한](/ko/channels#restrict-which-channel-plugins-can-run)을 참조하세요 | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |
| `allowedHttpHookUrls` | HTTP hooks가 대상으로 할 수 있는 URL 패턴의 허용 목록입니다. `*`를 와일드카드로 지원합니다. 설정되면 일치하지 않는 URL을 가진 hooks는 차단됩니다. 정의되지 않음 = 제한 없음, 빈 배열 = 모든 HTTP hooks 차단. 배열은 설정 소스 전체에서 병합됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `["https://hooks.example.com/*"]` |
| `allowedMcpServers` | Managed 설정에서 설정되면 사용자가 구성할 수 있는 MCP 서버의 허용 목록입니다. 정의되지 않음 = 제한 없음, 빈 배열 = 잠금. 모든 범위에 적용됩니다. 거부 목록이 우선합니다. [Managed MCP 구성](/ko/mcp#managed-mcp-configuration)을 참조하세요 | `[{ "serverName": "github" }]` |
| `allowManagedHooksOnly` | (Managed 설정만) Managed hooks, SDK hooks 및 managed 설정 `enabledPlugins`에서 강제 활성화된 플러그인의 hooks만 로드됩니다. 사용자, 프로젝트 및 다른 모든 플러그인 hooks는 차단됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `true` |
| `allowManagedMcpServersOnly` | (Managed 설정만) Managed 설정의 `allowedMcpServers`만 존중됩니다. `deniedMcpServers`는 여전히 모든 소스에서 병합됩니다. 사용자는 여전히 MCP 서버를 추가할 수 있지만 관리자 정의 허용 목록만 적용됩니다. [Managed MCP 구성](/ko/mcp#managed-mcp-configuration)을 참조하세요 | `true` |
| `allowManagedPermissionRulesOnly` | (Managed 설정만) 사용자 및 프로젝트 설정이 `allow`, `ask` 또는 `deny` 권한 규칙을 정의하는 것을 방지합니다. Managed 설정의 규칙만 적용됩니다. [Managed 전용 설정](/ko/permissions#managed-only-settings)을 참조하세요 | `true` |
| `alwaysThinkingEnabled` | 모든 세션에 대해 기본적으로 [확장 사고](/ko/common-workflows#use-extended-thinking-thinking-mode)를 활성화합니다. 일반적으로 직접 편집하기보다는 `/config` 명령을 통해 구성됩니다 | `true` |
| `apiKeyHelper` | `/bin/sh`에서 실행될 사용자 정의 스크립트로 인증 값을 생성합니다. 이 값은 모델 요청에 대해 `X-Api-Key` 및 `Authorization: Bearer` 헤더로 전송됩니다 | `/bin/generate_temp_api_key.sh` |
| `attribution` | git 커밋 및 pull request에 대한 attribution을 사용자 정의합니다. [Attribution 설정](#attribution-settings)을 참조하세요 | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |
| `autoMemoryDirectory` | [자동 메모리](/ko/memory#storage-location) 저장소를 위한 사용자 정의 디렉토리입니다. `~/` 확장 경로를 허용합니다. 공유 저장소가 메모리 쓰기를 민감한 위치로 리디렉션하는 것을 방지하기 위해 프로젝트 설정 (`.claude/settings.json`)에서는 허용되지 않습니다. 정책, local 및 사용자 설정에서 허용됨 | `"~/my-memory-dir"` |
| `autoMode` | [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기가 차단하고 허용하는 것을 사용자 정의합니다. `environment`, `allow` 및 `soft_deny` 배열의 산문 규칙을 포함합니다. 배열에 리터럴 문자열 `"$defaults"`를 포함하여 해당 위치에서 기본 제공 규칙을 상속합니다. [자동 모드 구성](/ko/auto-mode-config)을 참조하세요. 공유 프로젝트 설정에서는 읽지 않음 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |
| `autoScrollEnabled` | [fullscreen 렌더링](/ko/fullscreen)에서 새 출력을 대화의 맨 아래로 따릅니다. 기본값: `true`. `/config`에 **자동 스크롤**로 표시됩니다. 이것이 꺼져 있을 때도 권한 프롬프트는 여전히 보기로 스크롤됩니다 | `false` |
| `autoUpdatesChannel` | 업데이트를 따를 릴리스 채널입니다. 일반적으로 약 1주일 된 버전이고 주요 회귀가 있는 버전을 건너뛰는 `"stable"`을 사용하거나 가장 최근 릴리스인 `"latest"` (기본값)을 사용합니다 | `"stable"` |
| `availableModels` | `/model`, `--model` 또는 `ANTHROPIC_MODEL`을 통해 사용자가 선택할 수 있는 모델을 제한합니다. 기본 옵션에는 영향을 주지 않습니다. [모델 선택 제한](/ko/model-config#restrict-model-selection)을 참조하세요 | `["sonnet", "haiku"]` |
| `awaySummaryEnabled` | 몇 분 동안 터미널에서 떨어져 있다가 돌아올 때 한 줄 세션 요약을 표시합니다. 비활성화하려면 `false`로 설정하거나 `/config`에서 세션 요약을 끕니다. [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/ko/env-vars)와 동일합니다 | `true` |
| `awsAuthRefresh` | `.aws` 디렉토리를 수정하는 사용자 정의 스크립트 ([고급 자격 증명 구성](/ko/amazon-bedrock#advanced-credential-configuration) 참조) | `aws sso login --profile myprofile` |
| `awsCredentialExport` | AWS 자격 증명이 포함된 JSON을 출력하는 사용자 정의 스크립트 ([고급 자격 증명 구성](/ko/amazon-bedrock#advanced-credential-configuration) 참조) | `/bin/generate_aws_grant.sh` |
| `blockedMarketplaces` | (Managed 설정만) 마켓플레이스 소스의 차단 목록입니다. 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용되므로 정책이 설정되기 전에 추가된 마켓플레이스는 플러그인을 가져오는 데 사용할 수 없습니다. 차단된 소스는 다운로드 전에 확인되므로 파일 시스템에 닿지 않습니다. [Managed 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요 | `[{ "source": "github", "repo": "untrusted/plugins" }]` |
| `channelsEnabled` | (Managed 설정만) Team 및 Enterprise 사용자를 위해 [channels](/ko/channels)를 허용합니다. 설정되지 않거나 `false`이면 사용자가 `--channels`에 전달하는 것과 관계없이 채널 메시지 전달을 차단합니다 | `true` |
| `cleanupPeriodDays` | 이 기간보다 오래 비활성 상태인 세션 파일은 시작 시 삭제됩니다 (기본값: 30일, 최소 1). `0`으로 설정하면 검증 오류가 발생합니다. 또한 시작 시 [고아 subagent worktrees](/ko/common-workflows#worktree-cleanup)의 자동 제거에 대한 나이 기준을 제어합니다. 트랜스크립트 쓰기를 완전히 비활성화하려면 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/ko/env-vars) 환경 변수를 설정하거나 비대화형 모드 (`-p`)에서 `--no-session-persistence` 플래그 또는 `persistSession: false` SDK 옵션을 사용합니다. | `20` |
| `companyAnnouncements` | 시작 시 사용자에게 표시할 공지사항입니다. 여러 공지사항이 제공되면 무작위로 순환됩니다. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |
| `defaultShell` | 입력 상자 `!` 명령의 기본 셸입니다. `"bash"` (기본값) 또는 `"powershell"`을 허용합니다. `"powershell"`을 설정하면 Windows에서 대화형 `!` 명령을 PowerShell을 통해 라우팅합니다. `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`이 필요합니다. [PowerShell 도구](/ko/tools-reference#powershell-tool)를 참조하세요 | `"powershell"` |
| `deniedMcpServers` | Managed 설정에서 설정되면 명시적으로 차단된 MCP 서버의 거부 목록입니다. Managed 서버를 포함한 모든 범위에 적용됩니다. 거부 목록이 허용 목록보다 우선합니다. [Managed MCP 구성](/ko/mcp#managed-mcp-configuration)을 참조하세요 | `[{ "serverName": "filesystem" }]` |
| `disableAllHooks` | 모든 [hooks](/ko/hooks) 및 사용자 정의 [상태 줄](/ko/statusline) 비활성화 | `true` |
| `disableAutoMode` | [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode)가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. `Shift+Tab` 순환에서 `auto`를 제거하고 시작 시 `--permission-mode auto`를 거부합니다. [managed 설정](/ko/permissions#managed-settings)에서 사용자가 재정의할 수 없을 때 가장 유용합니다 | `"disable"` |
| `disableDeepLinkRegistration` | Claude Code가 시작 시 운영 체제에 `claude-cli://` 프로토콜 핸들러를 등록하는 것을 방지하려면 `"disable"`로 설정합니다. 딥 링크를 사용하면 외부 도구가 `claude-cli://open?q=...`를 통해 사전 채워진 프롬프트로 Claude Code 세션을 열 수 있습니다. `q` 매개변수는 URL 인코딩된 줄 바꿈 (`%0A`)을 사용하여 여러 줄 프롬프트를 지원합니다. 프로토콜 핸들러 등록이 제한되거나 별도로 관리되는 환경에서 유용합니다 | `"disable"` |
| `disabledMcpjsonServers` | `.mcp.json` 파일에서 거부할 특정 MCP 서버 목록 | `["filesystem"]` |
| `disableSkillShellExecution` | [skills](/ko/skills) 및 사용자, 프로젝트, 플러그인 또는 추가 디렉토리 소스의 사용자 정의 명령에서 `` !`...` `` 및 ` ```! ` 블록에 대한 인라인 셸 실행을 비활성화합니다. 명령은 실행되는 대신 `[shell command execution disabled by policy]`로 대체됩니다. 번들 및 managed skills는 영향을 받지 않습니다. [managed 설정](/ko/permissions#managed-settings)에서 사용자가 재정의할 수 없을 때 가장 유용합니다 | `true` |
| `editorMode` | 입력 프롬프트의 키 바인딩 모드: `"normal"` 또는 `"vim"`. 기본값: `"normal"`. `/config`에 **편집기 모드**로 표시됩니다 | `"vim"` |
| `effortLevel` | [노력 수준](/ko/model-config#adjust-effort-level)을 세션 간에 유지합니다. `"low"`, `"medium"`, `"high"` 또는 `"xhigh"`를 허용합니다. `/effort`를 이러한 값 중 하나로 실행할 때 자동으로 작성됩니다. [노력 수준 조정](/ko/model-config#adjust-effort-level)에서 지원되는 모델을 참조하세요 | `"xhigh"` |
| `enableAllProjectMcpServers` | 프로젝트 `.mcp.json` 파일에 정의된 모든 MCP 서버를 자동으로 승인합니다 | `true` |
| `enabledMcpjsonServers` | `.mcp.json` 파일에서 승인할 특정 MCP 서버 목록 | `["memory", "github"]` |
| `env` | 모든 세션에 적용될 환경 변수 | `{"FOO": "bar"}` |
| `fastModePerSessionOptIn` | `true`일 때 빠른 모드는 세션 간에 지속되지 않습니다. 각 세션은 빠른 모드가 꺼진 상태로 시작되며 사용자가 `/fast`로 활성화해야 합니다. 사용자의 빠른 모드 설정은 여전히 저장됩니다. [세션별 옵트인 필요](/ko/fast-mode#require-per-session-opt-in)를 참조하세요 | `true` |
| `feedbackSurveyRate` | [세션 품질 설문조사](/ko/data-usage#session-quality-surveys)가 적격일 때 나타날 확률 (0–1). 완전히 억제하려면 `0`으로 설정합니다. Bedrock, Vertex 또는 Foundry를 사용할 때 유용하며 기본 샘플 레이트가 적용되지 않습니다 | `0.05` |
| `fileSuggestion` | `@` 파일 자동 완성을 위한 사용자 정의 스크립트를 구성합니다. [파일 제안 설정](#file-suggestion-settings)을 참조하세요 | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |
| `forceLoginMethod` | `claudeai`를 사용하여 Claude.ai 계정으로만 로그인을 제한하거나, `console`을 사용하여 Claude Console (API 사용 청구) 계정으로만 제한합니다 | `claudeai` |
| `forceLoginOrgUUID` | 로그인이 특정 조직에 속하도록 요구합니다. 단일 UUID 문자열을 허용하며, 이는 로그인 중에 해당 조직을 사전 선택하거나, 나열된 조직이 사전 선택 없이 허용되는 UUID 배열을 허용합니다. Managed 설정에서 설정되면 인증된 계정이 나열된 조직에 속하지 않으면 로그인이 실패합니다. 빈 배열은 실패하고 잘못된 구성 메시지로 로그인을 차단합니다 | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` 또는 `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |
| `forceRemoteSettingsRefresh` | (Managed 설정만) 원격 managed 설정이 서버에서 새로 가져올 때까지 CLI 시작을 차단합니다. 가져오기가 실패하면 캐시된 또는 설정 없이 계속하는 대신 CLI가 종료됩니다. 설정되지 않으면 시작이 원격 설정을 기다리지 않고 계속됩니다. [실패 폐쇄 적용](/ko/server-managed-settings#enforce-fail-closed-startup)을 참조하세요 | `true` |
| `hooks` | 라이프사이클 이벤트에서 실행할 사용자 정의 명령을 구성합니다. 형식은 [hooks 문서](/ko/hooks)를 참조하세요 | [hooks](/ko/hooks) 참조 |
| `httpHookAllowedEnvVars` | HTTP hooks가 헤더에 보간할 수 있는 환경 변수 이름의 허용 목록입니다. 설정되면 각 hook의 유효한 `allowedEnvVars`는 이 설정과의 교집합입니다. 정의되지 않음 = 제한 없음. 배열은 설정 소스 전체에서 병합됩니다. [Hook 구성](#hook-configuration)을 참조하세요 | `["MY_TOKEN", "HOOK_SECRET"]` |
| `includeCoAuthoredBy` | **더 이상 사용되지 않음**: 대신 `attribution`을 사용하세요. git 커밋 및 pull request에 `co-authored-by Claude` 바이라인을 포함할지 여부 (기본값: `true`) | `false` |
| `includeGitInstructions` | Claude의 시스템 프롬프트에 기본 제공 커밋 및 PR 워크플로우 지침 및 git 상태 스냅샷을 포함합니다 (기본값: `true`). 예를 들어 자신의 git 워크플로우 skills을 사용할 때 이를 `false`로 설정하여 둘 다 제거합니다. `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` 환경 변수가 설정되면 이 설정보다 우선합니다 | `false` |
| `language` | Claude의 선호 응답 언어를 구성합니다 (예: `"japanese"`, `"spanish"`, `"french"`). Claude는 기본적으로 이 언어로 응답합니다. 또한 [음성 받아쓰기](/ko/voice-dictation#change-the-dictation-language) 언어를 설정합니다 | `"japanese"` |
| `minimumVersion` | 배경 자동 업데이트 및 `claude update`가 이 버전 아래로 설치되는 것을 방지하는 하한입니다. `"latest"` 채널에서 `"stable"`로 전환할 때 `/config`를 통해 현재 버전에 머물기 또는 다운그레이드를 허용하라는 메시지가 표시됩니다. 머물기를 선택하면 이 값이 설정됩니다. 또한 [managed 설정](/ko/permissions#managed-settings)에서 조직 전체 최소값을 고정하는 데 유용합니다 | `"2.1.100"` |
| `model` | Claude Code에 사용할 기본 모델을 재정의합니다 | `"claude-sonnet-4-6"` |
| `modelOverrides` | Anthropic 모델 ID를 Bedrock 추론 프로필 ARN과 같은 공급자 특정 모델 ID로 매핑합니다. 각 모델 선택기 항목은 공급자 API를 호출할 때 매핑된 값을 사용합니다. [버전별 모델 ID 재정의](/ko/model-config#override-model-ids-per-version)를 참조하세요 | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |
| `otelHeadersHelper` | 동적 OpenTelemetry 헤더를 생성하는 스크립트입니다. 시작 시 및 주기적으로 실행됩니다 ([동적 헤더](/ko/monitoring-usage#dynamic-headers) 참조) | `/bin/generate_otel_headers.sh` |
| `outputStyle` | 시스템 프롬프트를 조정하기 위한 출력 스타일을 구성합니다. [출력 스타일 문서](/ko/output-styles)를 참조하세요 | `"Explanatory"` |
| `permissions` | 권한의 구조는 아래 표를 참조하세요. | |
| `plansDirectory` | 계획 파일이 저장되는 위치를 사용자 정의합니다. 경로는 프로젝트 루트에 상대적입니다. 기본값: `~/.claude/plans` | `"./plans"` |
| `pluginTrustMessage` | (Managed 설정만) 설치 전에 표시되는 플러그인 신뢰 경고에 추가될 사용자 정의 메시지입니다. 이를 사용하여 조직 특정 컨텍스트를 추가합니다. 예를 들어 내부 마켓플레이스의 플러그인이 검증되었음을 확인합니다. | `"All plugins from our marketplace are approved by IT"` |
| `prefersReducedMotion` | 접근성을 위해 UI 애니메이션 (스피너, shimmer, flash 효과) 감소 또는 비활성화 | `true` |
| `prUrlTemplate` | PR 배지에 대한 URL 템플릿으로 바닥글 및 도구 결과 요약에 표시됩니다. `gh`에서 보고한 PR URL에서 `{host}`, `{owner}`, `{repo}`, `{number}` 및 `{url}`을 대체합니다. `github.com` 대신 내부 코드 검토 도구를 가리키도록 사용합니다. Claude의 산문에서 `#123` 자동 링크에는 영향을 주지 않습니다 | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |
| `respectGitignore` | `@` 파일 선택기가 `.gitignore` 패턴을 존중할지 여부를 제어합니다. `true` (기본값)일 때 `.gitignore` 패턴과 일치하는 파일은 제안에서 제외됩니다 | `false` |
| `showClearContextOnPlanAccept` | 계획 수락 화면에서 "컨텍스트 지우기" 옵션을 표시합니다. 기본값: `false`. 옵션을 복원하려면 `true`로 설정합니다 | `true` |
| `showThinkingSummaries` | 대화형 세션에서 [확장 사고](/ko/common-workflows#use-extended-thinking-thinking-mode) 요약을 표시합니다. 설정되지 않거나 `false` (대화형 모드의 기본값)일 때 사고 블록은 API에 의해 편집되고 축소된 스텁으로 표시됩니다. 편집은 표시되는 내용만 변경하고 모델이 생성하는 내용은 변경하지 않습니다. 사고 지출을 줄이려면 [예산을 낮추거나 사고를 비활성화](/ko/common-workflows#use-extended-thinking-thinking-mode)하세요. 비대화형 모드 (`-p`) 및 SDK 호출자는 이 설정과 관계없이 항상 요약을 받습니다 | `true` |
| `showTurnDuration` | 응답 후 턴 지속 시간 메시지를 표시합니다 (예: "Cooked for 1m 6s"). 기본값: `true`. `/config`에 **턴 지속 시간 표시**로 표시됩니다 | `false` |
| `skipWebFetchPreflight` | [WebFetch 도메인 안전 검사](/ko/data-usage#webfetch-domain-safety-check)를 건너뜁니다. 이 검사는 각 요청된 호스트명을 가져오기 전에 `api.anthropic.com`으로 전송합니다. Bedrock, Vertex AI 또는 Foundry 배포와 같이 Anthropic으로의 트래픽을 차단하는 환경에서 `true`로 설정합니다. 건너뛰면 WebFetch는 차단 목록을 참조하지 않고 모든 URL을 시도합니다 | `true` |
| `spinnerTipsEnabled` | Claude가 작업 중일 때 스피너에 팁을 표시합니다. 팁을 비활성화하려면 `false`로 설정합니다 (기본값: `true`) | `false` |
| `spinnerTipsOverride` | 사용자 정의 문자열로 스피너 팁을 재정의합니다. `tips`: 팁 문자열 배열. `excludeDefault`: `true`이면 사용자 정의 팁만 표시하고, `false`이거나 없으면 사용자 정의 팁이 기본 제공 팁과 병합됩니다 | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |
| `spinnerVerbs` | 스피너 및 턴 지속 시간 메시지에 표시되는 작업 동사를 사용자 정의합니다. `mode`를 `"replace"`로 설정하여 동사만 사용하거나 `"append"`로 설정하여 기본값에 추가합니다 | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |
| `sshConfigs` | [Desktop](/ko/desktop#pre-configure-ssh-connections-for-your-team) 환경 드롭다운에 표시할 SSH 연결입니다. 각 항목에는 `id`, `name` 및 `sshHost`가 필요하며, `sshPort`, `sshIdentityFile` 및 `startDirectory`는 선택 사항입니다. Managed 설정에서 설정되면 연결은 사용자에게 읽기 전용입니다. Managed 및 사용자 설정에서만 읽음 | `[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]` |
| `statusLine` | 컨텍스트를 표시하기 위한 사용자 정의 상태 줄을 구성합니다. [`statusLine` 문서](/ko/statusline)를 참조하세요 | `{"type": "command", "command": "~/.claude/statusline.sh"}` |
| `strictKnownMarketplaces` | (Managed 설정만) 플러그인 마켓플레이스 소스의 허용 목록입니다. 정의되지 않음 = 제한 없음, 빈 배열 = 잠금. 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용되므로 정책이 설정되기 전에 추가된 마켓플레이스는 플러그인을 가져오는 데 사용할 수 없습니다. [Managed 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요 | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |
| `teammateMode` | [에이전트 팀](/ko/agent-teams) 팀원이 표시되는 방식: `auto` (tmux 또는 iTerm2에서 분할 창 선택, 그 외에는 in-process), `in-process` 또는 `tmux`. [디스플레이 모드 선택](/ko/agent-teams#choose-a-display-mode)을 참조하세요 | `"in-process"` |
| `terminalProgressBarEnabled` | 지원되는 터미널에서 터미널 진행률 표시줄을 표시합니다: ConEmu, Ghostty 1.2.0+ 및 iTerm2 3.6.6+. 기본값: `true`. `/config`에 **터미널 진행률 표시줄**로 표시됩니다 | `false` |
| `tui` | 터미널 UI 렌더러입니다. 깜박임 없는 [alt-screen 렌더러](/ko/fullscreen)가 있는 가상화된 스크롤백을 위해 `"fullscreen"`을 사용합니다. 클래식 메인 화면 렌더러를 위해 `"default"`를 사용합니다. `/tui`를 통해 설정합니다 | `"fullscreen"` |
| `useAutoModeDuringPlan` | 자동 모드를 사용할 수 있을 때 계획 모드가 자동 모드 의미론을 사용할지 여부입니다. 기본값: `true`. 공유 프로젝트 설정에서는 읽지 않음. `/config`에 "계획 중 자동 모드 사용"으로 표시됨 | `false` |
| `viewMode` | 시작 시 기본 트랜스크립트 보기 모드: `"default"`, `"verbose"` 또는 `"focus"`. 설정되면 sticky `/focus` 선택을 재정의합니다 | `"verbose"` |
| `voice` | [음성 받아쓰기](/ko/voice-dictation) 설정: `enabled`는 받아쓰기를 켜고, `mode`는 `"hold"` 또는 `"tap"`을 선택하고, `autoSubmit`은 hold 모드에서 키 릴리스 시 프롬프트를 전송합니다. `/voice`를 실행할 때 자동으로 작성됩니다. Claude.ai 계정이 필요합니다 | `{ "enabled": true, "mode": "tap" }` |
| `voiceEnabled` | `voice.enabled`에 대한 레거시 별칭입니다. `voice` 객체를 선호합니다 | `true` |
| `wslInheritsWindowsSettings` | (Windows managed 설정만) `true`일 때 WSL의 Claude Code는 `/etc/claude-code`에 추가하여 Windows 정책 체인에서 managed 설정을 읽으며 Windows 소스가 우선합니다. Windows 관리자가 작성해야 하는 HKLM 레지스트리 키 또는 `C:\Program Files\ClaudeCode\managed-settings.json`에서 설정된 경우에만 적용됩니다. HKCU 정책도 WSL에 적용되려면 플래그를 HKCU 자체에도 설정해야 합니다. 기본 Windows에는 영향을 주지 않습니다 | `true` |
### 전역 구성 설정
이러한 설정은 `settings.json`이 아닌 `~/.claude.json`에 저장됩니다. 이들을 `settings.json`에 추가하면 스키마 검증 오류가 발생합니다.
v2.1.119 이전 버전은 `autoScrollEnabled`, `editorMode`, `showTurnDuration`, `teammateMode` 및 `terminalProgressBarEnabled`를 `settings.json` 대신 여기에 저장합니다.
| 키 | 설명 | 예제 |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |
| `autoConnectIde` | Claude Code가 외부 터미널에서 시작될 때 실행 중인 IDE에 자동으로 연결합니다. 기본값: `false`. VS Code 또는 JetBrains 터미널 외부에서 실행할 때 `/config`에 \*\*IDE에 자동 연결 (외부 터미널)\*\*로 표시됩니다 | `true` |
| `autoInstallIdeExtension` | VS Code 터미널에서 실행할 때 Claude Code IDE 확장을 자동으로 설치합니다. 기본값: `true`. VS Code 또는 JetBrains 터미널 내에서 실행할 때 `/config`에 **IDE 확장 자동 설치**로 표시됩니다. [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/ko/env-vars) 환경 변수도 설정할 수 있습니다 | `false` |
| `externalEditorContext` | `Ctrl+G`로 외부 편집기를 열 때 Claude의 이전 응답을 `#` 주석 처리된 컨텍스트로 앞에 붙입니다. 기본값: `false`. `/config`에 **외부 편집기에 마지막 응답 표시**로 표시됩니다 | `true` |
### Worktree 설정
`--worktree`가 git worktrees를 생성하고 관리하는 방식을 구성합니다. 이러한 설정을 사용하여 대규모 monorepos에서 디스크 사용량 및 시작 시간을 줄입니다.
| 키 | 설명 | 예제 |
| :---------------------------- | :-------------------------------------------------------------------------------------------------------- | :------------------------------------ |
| `worktree.symlinkDirectories` | 각 worktree에서 중복을 피하기 위해 메인 저장소에서 symlink할 디렉토리입니다. 기본적으로 디렉토리는 symlink되지 않습니다 | `["node_modules", ".cache"]` |
| `worktree.sparsePaths` | git sparse-checkout (cone mode)을 통해 각 worktree에서 체크아웃할 디렉토리입니다. 나열된 경로만 디스크에 작성되므로 대규모 monorepos에서 더 빠릅니다 | `["packages/my-app", "shared/utils"]` |
worktrees에 `.env`와 같은 gitignored 파일을 복사하려면 설정 대신 프로젝트 루트의 [`.worktreeinclude` 파일](/ko/common-workflows#copy-gitignored-files-to-worktrees)을 사용합니다.
### 권한 설정
| 키 | 설명 | 예제 |
| :---------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |
| `allow` | 도구 사용을 허용하는 권한 규칙 배열입니다. 패턴 매칭 세부 사항은 아래 [권한 규칙 구문](#permission-rule-syntax)을 참조하세요 | `[ "Bash(git diff *)" ]` |
| `ask` | 도구 사용 시 확인을 요청하는 권한 규칙 배열입니다. 패턴 매칭 세부 사항은 아래 [권한 규칙 구문](#permission-rule-syntax)을 참조하세요 | `[ "Bash(git push *)" ]` |
| `deny` | 도구 사용을 거부하는 권한 규칙 배열입니다. 이를 사용하여 Claude Code 액세스에서 민감한 파일을 제외합니다. [권한 규칙 구문](#permission-rule-syntax) 및 [Bash 권한 제한](/ko/permissions#tool-specific-permission-rules)을 참조하세요 | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |
| `additionalDirectories` | Claude가 액세스할 수 있는 추가 [작업 디렉토리](/ko/permissions#working-directories)입니다. 대부분의 `.claude/` 구성은 이러한 디렉토리에서 [발견되지 않습니다](/ko/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |
| `defaultMode` | Claude Code를 열 때 기본 [권한 모드](/ko/permission-modes)입니다. 유효한 값: `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`. `--permission-mode` CLI 플래그는 단일 세션에 대해 이 설정을 재정의합니다 | `"acceptEdits"` |
| `disableBypassPermissionsMode` | `bypassPermissions` 모드가 활성화되는 것을 방지하려면 `"disable"`로 설정합니다. 이는 `--dangerously-skip-permissions` 명령줄 플래그를 비활성화합니다. 일반적으로 [managed 설정](/ko/permissions#managed-settings)에 배치되어 조직 정책을 적용하지만 모든 범위에서 작동합니다 | `"disable"` |
| `skipDangerousModePermissionPrompt` | `--dangerously-skip-permissions` 또는 `defaultMode: "bypassPermissions"`를 통해 bypass permissions 모드에 들어가기 전에 표시되는 확인 프롬프트를 건너뜁니다. 신뢰할 수 없는 저장소가 프롬프트를 자동으로 우회하는 것을 방지하기 위해 프로젝트 설정 (`.claude/settings.json`)에서 설정되면 무시됩니다 | `true` |
### 권한 규칙 구문
권한 규칙은 `Tool` 또는 `Tool(specifier)` 형식을 따릅니다. 규칙은 순서대로 평가됩니다: 먼저 거부 규칙, 그 다음 요청, 그 다음 허용. 첫 번째 일치 규칙이 우승합니다.
빠른 예제:
| 규칙 | 효과 |
| :----------------------------- | :--------------------------- |
| `Bash` | 모든 Bash 명령과 일치 |
| `Bash(npm run *)` | `npm run`으로 시작하는 명령과 일치 |
| `Read(./.env)` | `.env` 파일 읽기와 일치 |
| `WebFetch(domain:example.com)` | example.com에 대한 fetch 요청과 일치 |
Read, Edit, WebFetch, MCP 및 Agent 규칙에 대한 와일드카드 동작, 도구 특정 패턴 및 Bash 패턴의 보안 제한을 포함한 완전한 규칙 구문 참조는 [권한 규칙 구문](/ko/permissions#permission-rule-syntax)을 참조하세요.
### Sandbox 설정
고급 샌드박싱 동작을 구성합니다. 샌드박싱은 bash 명령을 파일 시스템 및 네트워크에서 격리합니다. 자세한 내용은 [Sandboxing](/ko/sandboxing)을 참조하세요.
| 키 | 설명 | 예제 |
| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------- |
| `enabled` | bash 샌드박싱 활성화 (macOS, Linux 및 WSL2). 기본값: false | `true` |
| `failIfUnavailable` | `sandbox.enabled`가 true이지만 샌드박스를 시작할 수 없는 경우 (종속성 누락, 지원되지 않는 플랫폼) 시작 시 오류로 종료합니다. false (기본값)일 때 경고가 표시되고 명령이 샌드박싱되지 않은 상태로 실행됩니다. Managed 설정 배포에서 샌드박싱을 하드 게이트로 요구하는 경우를 위한 것입니다 | `true` |
| `autoAllowBashIfSandboxed` | 샌드박싱되면 bash 명령 자동 승인. 기본값: true | `true` |
| `excludedCommands` | 샌드박스 외부에서 실행해야 하는 명령 | `["docker *"]` |
| `allowUnsandboxedCommands` | `dangerouslyDisableSandbox` 매개변수를 통해 샌드박스 외부에서 명령을 실행하도록 허용합니다. `false`로 설정되면 `dangerouslyDisableSandbox` 이스케이프 해치가 완전히 비활성화되고 모든 명령은 샌드박싱되거나 `excludedCommands`에 있어야 합니다. 엄격한 샌드박싱이 필요한 엔터프라이즈 정책에 유용합니다. 기본값: true | `false` |
| `filesystem.allowWrite` | 샌드박싱된 명령이 쓸 수 있는 추가 경로입니다. 배열은 모든 설정 범위에서 병합됩니다: 사용자, 프로젝트 및 managed 경로가 결합되고 대체되지 않습니다. `Edit(...)` 허용 권한 규칙의 경로와도 병합됩니다. [경로 접두사](#sandbox-path-prefixes)를 참조하세요. | `["/tmp/build", "~/.kube"]` |
| `filesystem.denyWrite` | 샌드박싱된 명령이 쓸 수 없는 경로입니다. 배열은 모든 설정 범위에서 병합됩니다. `Edit(...)` 거부 권한 규칙의 경로와도 병합됩니다. | `["/etc", "/usr/local/bin"]` |
| `filesystem.denyRead` | 샌드박싱된 명령이 읽을 수 없는 경로입니다. 배열은 모든 설정 범위에서 병합됩니다. `Read(...)` 거부 권한 규칙의 경로와도 병합됩니다. | `["~/.aws/credentials"]` |
| `filesystem.allowRead` | `denyRead` 영역 내에서 읽기를 다시 허용할 경로입니다. `denyRead`보다 우선합니다. 배열은 모든 설정 범위에서 병합됩니다. 이를 사용하여 작업 공간 전용 읽기 액세스 패턴을 만듭니다. | `["."]` |
| `filesystem.allowManagedReadPathsOnly` | (Managed 설정만) Managed 설정의 `filesystem.allowRead` 경로만 존중됩니다. `denyRead`는 여전히 모든 소스에서 병합됩니다. 기본값: false | `true` |
| `network.allowUnixSockets` | (macOS만) Unix 소켓 경로 샌드박스에서 액세스 가능. Linux 및 WSL2에서는 무시되며, seccomp 필터가 소켓 경로를 검사할 수 없습니다. 대신 `allowAllUnixSockets`를 사용합니다. | `["~/.ssh/agent-socket"]` |
| `network.allowAllUnixSockets` | 샌드박스에서 모든 Unix 소켓 연결을 허용합니다. Linux 및 WSL2에서 이는 `socket(AF_UNIX, ...)` 호출을 차단하는 seccomp 필터를 건너뛰므로 Unix 소켓을 허용하는 유일한 방법입니다. 기본값: false | `true` |
| `network.allowLocalBinding` | localhost 포트에 바인딩 허용 (macOS만). 기본값: false | `true` |
| `network.allowMachLookup` | 샌드박스가 조회할 수 있는 추가 XPC/Mach 서비스 이름 (macOS만). 접두사 일치를 위해 단일 후행 `*`를 지원합니다. iOS Simulator 또는 Playwright와 같이 XPC를 통해 통신하는 도구에 필요합니다. | `["com.apple.coresimulator.*"]` |
| `network.allowedDomains` | 아웃바운드 네트워크 트래픽을 허용할 도메인 배열입니다. 와일드카드를 지원합니다 (예: `*.example.com`). | `["github.com", "*.npmjs.org"]` |
| `network.deniedDomains` | 아웃바운드 네트워크 트래픽을 차단할 도메인 배열입니다. `allowedDomains`와 동일한 와일드카드 구문을 지원합니다. 둘 다 일치할 때 `allowedDomains`보다 우선합니다. 모든 설정 소스와 관계없이 병합됩니다 | `["sensitive.cloud.example.com"]` |
| `network.allowManagedDomainsOnly` | (Managed 설정만) Managed 설정의 `allowedDomains` 및 `WebFetch(domain:...)` 허용 규칙만 존중됩니다. 사용자, 프로젝트 및 local 설정의 도메인은 무시됩니다. 허용되지 않은 도메인은 사용자에게 메시지를 표시하지 않고 자동으로 차단됩니다. 거부된 도메인은 여전히 모든 소스에서 존중됩니다. 기본값: false | `true` |
| `network.httpProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 HTTP 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8080` |
| `network.socksProxyPort` | 자신의 프록시를 가져오려는 경우 사용되는 SOCKS5 프록시 포트입니다. 지정되지 않으면 Claude가 자신의 프록시를 실행합니다. | `8081` |
| `enableWeakerNestedSandbox` | 권한이 없는 Docker 환경에서 더 약한 샌드박스를 활성화합니다 (Linux 및 WSL2만). **보안을 감소시킵니다.** 기본값: false | `true` |
| `enableWeakerNetworkIsolation` | (macOS만) 샌드박스에서 시스템 TLS 신뢰 서비스 (`com.apple.trustd.agent`)에 대한 액세스를 허용합니다. MITM 프록시 및 사용자 정의 CA를 사용하는 `httpProxyPort`를 사용할 때 `gh`, `gcloud` 및 `terraform`과 같은 Go 기반 도구가 TLS 인증서를 확인하는 데 필요합니다. **보안을 감소시킵니다** 잠재적 데이터 유출 경로를 열어서. 기본값: false | `true` |
#### Sandbox 경로 접두사
`filesystem.allowWrite`, `filesystem.denyWrite`, `filesystem.denyRead` 및 `filesystem.allowRead`의 경로는 다음 접두사를 지원합니다:
| 접두사 | 의미 | 예제 |
| :------------- | :------------------------------------------------------ | :------------------------------------------------------------------ |
| `/` | 파일 시스템 루트의 절대 경로 | `/tmp/build`는 `/tmp/build`로 유지됨 |
| `~/` | 홈 디렉토리에 상대적 | `~/.kube`는 `$HOME/.kube`가 됨 |
| `./` 또는 접두사 없음 | 프로젝트 설정의 경우 프로젝트 루트에 상대적이거나 사용자 설정의 경우 `~/.claude`에 상대적 | `./output`은 `.claude/settings.json`에서 `/output`으로 해결됨 |
이전 `//path` 접두사는 절대 경로에 대해 여전히 작동합니다. 이전에 프로젝트 상대 해결을 기대하면서 단일 슬래시 `/path`를 사용한 경우 `./path`로 전환합니다. 이 구문은 `/path`를 프로젝트 상대로 사용하는 [Read 및 Edit 권한 규칙](/ko/permissions#read-and-edit)과 다릅니다. Sandbox 파일 시스템 경로는 표준 규칙을 사용합니다: `/tmp/build`는 절대 경로입니다.
**구성 예제:**
```json theme={null}
{
"sandbox": {
"enabled": true,
"autoAllowBashIfSandboxed": true,
"excludedCommands": ["docker *"],
"filesystem": {
"allowWrite": ["/tmp/build", "~/.kube"],
"denyRead": ["~/.aws/credentials"]
},
"network": {
"allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
"deniedDomains": ["uploads.github.com"],
"allowUnixSockets": [
"/var/run/docker.sock"
],
"allowLocalBinding": true
}
}
}
```
**파일 시스템 및 네트워크 제한**은 함께 병합되는 두 가지 방식으로 구성할 수 있습니다:
* **`sandbox.filesystem` 설정** (위에 표시됨): OS 수준 샌드박스 경계에서 경로를 제어합니다. 이러한 제한은 Claude의 파일 도구뿐만 아니라 모든 하위 프로세스 명령 (예: `kubectl`, `terraform`, `npm`)에 적용됩니다.
* **권한 규칙**: `Edit` 허용/거부 규칙을 사용하여 Claude의 파일 도구 액세스를 제어하고, `Read` 거부 규칙을 사용하여 읽기를 차단하고, `WebFetch` 허용/거부 규칙을 사용하여 네트워크 도메인을 제어합니다. 이러한 규칙의 경로도 샌드박스 구성에 병합됩니다.
### Attribution 설정
Claude Code는 git 커밋 및 pull request에 attribution을 추가합니다. 이들은 별도로 구성됩니다:
* 커밋은 기본적으로 [git trailers](https://git-scm.com/docs/git-interpret-trailers) (예: `Co-Authored-By`)를 사용하며 사용자 정의하거나 비활성화할 수 있습니다
* Pull request 설명은 일반 텍스트입니다
| 키 | 설명 |
| :------- | :------------------------------------------------------------------------ |
| `commit` | git 커밋에 대한 attribution으로 모든 trailers를 포함합니다. 빈 문자열은 커밋 attribution을 숨깁니다 |
| `pr` | Pull request 설명에 대한 attribution입니다. 빈 문자열은 pull request attribution을 숨깁니다 |
**기본 커밋 attribution:**
```text theme={null}
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.6
```
**기본 pull request attribution:**
```text theme={null}
🤖 Generated with [Claude Code](https://claude.com/claude-code)
```
**예제:**
```json theme={null}
{
"attribution": {
"commit": "Generated with AI\n\nCo-Authored-By: AI ",
"pr": ""
}
}
```
`attribution` 설정은 더 이상 사용되지 않는 `includeCoAuthoredBy` 설정보다 우선합니다. 모든 attribution을 숨기려면 `commit` 및 `pr`을 빈 문자열로 설정합니다.
### 파일 제안 설정
`@` 파일 경로 자동 완성을 위한 사용자 정의 명령을 구성합니다. 기본 제공 파일 제안은 빠른 파일 시스템 순회를 사용하지만 대규모 monorepos는 사전 구축된 파일 인덱스 또는 사용자 정의 도구와 같은 프로젝트 특정 인덱싱의 이점을 얻을 수 있습니다.
```json theme={null}
{
"fileSuggestion": {
"type": "command",
"command": "~/.claude/file-suggestion.sh"
}
}
```
명령은 `CLAUDE_PROJECT_DIR`을 포함한 [hooks](/ko/hooks)와 동일한 환경 변수로 실행됩니다. stdin을 통해 `query` 필드가 있는 JSON을 받습니다:
```json theme={null}
{"query": "src/comp"}
```
stdout에 줄 바꿈으로 구분된 파일 경로를 출력합니다 (현재 15개로 제한됨):
```text theme={null}
src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx
```
**예제:**
```bash theme={null}
#!/bin/bash
query=$(cat | jq -r '.query')
your-repo-file-index --query "$query" | head -20
```
### Hook 구성
이러한 설정은 어떤 hooks가 실행될 수 있는지와 HTTP hooks가 액세스할 수 있는 것을 제어합니다. `allowManagedHooksOnly` 설정은 [managed 설정](#settings-files)에서만 구성할 수 있습니다. URL 및 env var 허용 목록은 모든 설정 수준에서 설정할 수 있으며 소스 전체에서 병합됩니다.
**`allowManagedHooksOnly`가 `true`일 때의 동작:**
* Managed hooks 및 SDK hooks가 로드됨
* Managed 설정 `enabledPlugins`에서 강제 활성화된 플러그인의 hooks가 로드됩니다. 이를 통해 관리자는 조직 마켓플레이스를 통해 검증된 hooks를 배포하면서 다른 모든 것을 차단할 수 있습니다. 신뢰는 전체 `plugin@marketplace` ID로 부여되므로 다른 마켓플레이스의 동일한 이름의 플러그인은 차단된 상태로 유지됩니다
* 사용자 hooks, 프로젝트 hooks 및 다른 모든 플러그인 hooks는 차단됩니다
**HTTP hook URL 제한:**
HTTP hooks가 대상으로 할 수 있는 URL을 제한합니다. 일치를 위해 `*`를 와일드카드로 지원합니다. 배열이 정의되면 일치하지 않는 URL을 대상으로 하는 HTTP hooks는 자동으로 차단됩니다.
```json theme={null}
{
"allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}
```
**HTTP hook 환경 변수 제한:**
HTTP hooks가 헤더 값에 보간할 수 있는 환경 변수 이름을 제한합니다. 각 hook의 유효한 `allowedEnvVars`는 이 설정과의 교집합입니다.
```json theme={null}
{
"httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}
```
### 설정 우선순위
설정은 우선순위 순서대로 적용됩니다. 가장 높음에서 가장 낮음:
1. **Managed 설정** ([서버 관리](/ko/server-managed-settings), [MDM/OS 수준 정책](#configuration-scopes) 또는 [managed 설정](/ko/settings#settings-files))
* IT에서 서버 전달, MDM 구성 프로필, 레지스트리 정책 또는 managed 설정 파일을 통해 배포한 정책
* 명령줄 인수를 포함한 다른 수준으로 재정의할 수 없음
* Managed 계층 내에서 우선순위는: 서버 관리 > MDM/OS 수준 정책 > 파일 기반 (`managed-settings.d/*.json` + `managed-settings.json`) > HKCU 레지스트리 (Windows만). 하나의 managed 소스만 사용되며 소스는 병합되지 않습니다. 파일 기반 계층 내에서 드롭인 파일과 기본 파일이 함께 병합됩니다.
2. **명령줄 인수**
* 특정 세션에 대한 임시 재정의
3. **Local 프로젝트 설정** (`.claude/settings.local.json`)
* 개인 프로젝트 특정 설정
4. **공유 프로젝트 설정** (`.claude/settings.json`)
* 소스 제어의 팀 공유 프로젝트 설정
5. **사용자 설정** (`~/.claude/settings.json`)
* 개인 전역 설정
이 계층 구조는 조직 정책이 항상 적용되면서도 팀과 개인이 자신의 경험을 사용자 정의할 수 있도록 보장합니다. CLI, [VS Code 확장](/ko/vs-code) 또는 [JetBrains IDE](/ko/jetbrains)에서 Claude Code를 실행하든 동일한 우선순위가 적용됩니다.
예를 들어 사용자 설정이 `Bash(npm run *)`을 허용하지만 프로젝트의 공유 설정이 이를 거부하면 프로젝트 설정이 우선하고 명령이 차단됩니다.
**배열 설정은 범위 전체에서 병합됩니다.** 동일한 배열 값 설정 (예: `sandbox.filesystem.allowWrite` 또는 `permissions.allow`)이 여러 범위에 나타나면 배열은 **연결되고 중복 제거되며** 대체되지 않습니다. 이는 낮은 우선순위 범위가 높은 우선순위 범위에서 설정한 항목을 재정의하지 않고 항목을 추가할 수 있음을 의미하며 그 반대도 마찬가지입니다. 예를 들어 managed 설정이 `allowWrite`를 `["/opt/company-tools"]`로 설정하고 사용자가 `["~/.kube"]`를 추가하면 두 경로 모두 최종 구성에 포함됩니다.
### 활성 설정 확인
Claude Code 내에서 `/status`를 실행하여 어떤 설정 소스가 활성화되어 있고 어디에서 오는지 확인합니다. 출력은 각 구성 계층 (managed, user, project)을 `Enterprise managed settings (remote)`, `Enterprise managed settings (plist)`, `Enterprise managed settings (HKLM)`, `Enterprise managed settings (HKCU)` 또는 `Enterprise managed settings (file)`과 같은 출처와 함께 표시합니다. 설정 파일에 오류가 포함되어 있으면 `/status`는 문제를 보고하여 수정할 수 있습니다.
### 구성 시스템의 핵심 포인트
* **메모리 파일 (`CLAUDE.md`)**: Claude가 시작 시 로드하는 지침 및 컨텍스트를 포함합니다
* **설정 파일 (JSON)**: 권한, 환경 변수 및 도구 동작을 구성합니다
* **Skills**: `/skill-name`으로 호출하거나 Claude가 자동으로 로드할 수 있는 사용자 정의 프롬프트
* **MCP servers**: 추가 도구 및 통합으로 Claude Code를 확장합니다
* **우선순위**: 높은 수준 구성 (Managed)이 낮은 수준 (User/Project)을 재정의합니다
* **상속**: 설정은 병합되며 더 구체적인 설정이 더 광범위한 설정을 추가하거나 재정의합니다
### 시스템 프롬프트
Claude Code의 내부 시스템 프롬프트는 게시되지 않습니다. 사용자 정의 지침을 추가하려면 `CLAUDE.md` 파일 또는 `--append-system-prompt` 플래그를 사용합니다.
### 민감한 파일 제외
API 키, 비밀 및 환경 파일과 같은 민감한 정보가 포함된 파일에서 Claude Code가 액세스하는 것을 방지하려면 `.claude/settings.json` 파일에서 `permissions.deny` 설정을 사용합니다:
```json theme={null}
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Read(./config/credentials.json)",
"Read(./build)"
]
}
}
```
이는 더 이상 사용되지 않는 `ignorePatterns` 구성을 대체합니다. 이러한 패턴과 일치하는 파일은 파일 검색 및 검색 결과에서 제외되며 이러한 파일에 대한 읽기 작업이 거부됩니다.
## Subagent 구성
Claude Code는 사용자 및 프로젝트 수준 모두에서 구성할 수 있는 사용자 정의 AI subagents를 지원합니다. 이러한 subagents는 YAML frontmatter가 있는 Markdown 파일로 저장됩니다:
* **사용자 subagents**: `~/.claude/agents/` - 모든 프로젝트에서 사용 가능
* **프로젝트 subagents**: `.claude/agents/` - 프로젝트에 특정이며 팀과 공유할 수 있음
Subagent 파일은 사용자 정의 프롬프트 및 도구 권한이 있는 특화된 AI 어시스턴트를 정의합니다. [subagents 문서](/ko/sub-agents)에서 subagents 생성 및 사용에 대해 자세히 알아보세요.
## 플러그인 구성
Claude Code는 skills, agents, hooks 및 MCP servers로 기능을 확장할 수 있는 플러그인 시스템을 지원합니다. 플러그인은 마켓플레이스를 통해 배포되며 사용자 및 저장소 수준 모두에서 구성할 수 있습니다.
### 플러그인 설정
`settings.json`의 플러그인 관련 설정:
```json theme={null}
{
"enabledPlugins": {
"formatter@acme-tools": true,
"deployer@acme-tools": true,
"analyzer@security-plugins": false
},
"extraKnownMarketplaces": {
"acme-tools": {
"source": "github",
"repo": "acme-corp/claude-plugins"
}
}
}
```
#### `enabledPlugins`
어떤 플러그인이 활성화되는지 제어합니다. 형식: `"plugin-name@marketplace-name": true/false`
**범위**:
* **사용자 설정** (`~/.claude/settings.json`): 개인 플러그인 설정
* **프로젝트 설정** (`.claude/settings.json`): 팀과 공유되는 프로젝트 특정 플러그인
* **Local 설정** (`.claude/settings.local.json`): 머신별 재정의 (커밋되지 않음)
* **Managed 설정** (`managed-settings.json`): 모든 범위에서 설치를 차단하고 마켓플레이스에서 플러그인을 숨기는 조직 전체 정책 재정의
**예제**:
```json theme={null}
{
"enabledPlugins": {
"code-formatter@team-tools": true,
"deployment-tools@team-tools": true,
"experimental-features@personal": false
}
}
```
#### `extraKnownMarketplaces`
저장소에서 사용 가능하게 해야 할 추가 마켓플레이스를 정의합니다. 일반적으로 팀 멤버가 필요한 플러그인 소스에 액세스할 수 있도록 저장소 수준 설정에서 사용됩니다.
**저장소에 `extraKnownMarketplaces`가 포함되면**:
1. 팀 멤버는 폴더를 신뢰할 때 마켓플레이스를 설치하라는 메시지를 받습니다
2. 그 다음 팀 멤버는 해당 마켓플레이스에서 플러그인을 설치하라는 메시지를 받습니다
3. 사용자는 원하지 않는 마켓플레이스 또는 플러그인을 건너뛸 수 있습니다 (사용자 설정에 저장됨)
4. 설치는 신뢰 경계를 존중하고 명시적 동의가 필요합니다
**예제**:
```json theme={null}
{
"extraKnownMarketplaces": {
"acme-tools": {
"source": {
"source": "github",
"repo": "acme-corp/claude-plugins"
}
},
"security-plugins": {
"source": {
"source": "git",
"url": "https://git.example.com/security/plugins.git"
}
}
}
}
```
**마켓플레이스 소스 유형**:
* `github`: GitHub 저장소 (`repo` 사용)
* `git`: 모든 git URL (`url` 사용)
* `directory`: 로컬 파일 시스템 경로 (`path` 사용, 개발 전용)
* `hostPattern`: 마켓플레이스 호스트와 일치하는 정규식 패턴 (`hostPattern` 사용)
* `settings`: 별도의 호스팅 저장소 없이 settings.json에 직접 선언된 인라인 마켓플레이스 (`name` 및 `plugins` 사용)
`source: 'settings'`를 사용하여 호스팅된 마켓플레이스 저장소를 설정하지 않고 작은 플러그인 세트를 인라인으로 선언합니다. 여기에 나열된 플러그인은 GitHub 또는 npm과 같은 외부 소스를 참조해야 합니다. 여전히 `enabledPlugins`에서 각 플러그인을 별도로 활성화해야 합니다.
```json theme={null}
{
"extraKnownMarketplaces": {
"team-tools": {
"source": {
"source": "settings",
"name": "team-tools",
"plugins": [
{
"name": "code-formatter",
"source": {
"source": "github",
"repo": "acme-corp/code-formatter"
}
}
]
}
}
}
}
```
#### `strictKnownMarketplaces`
**Managed 설정만**: 사용자가 추가할 수 있는 플러그인 마켓플레이스를 제어합니다. 이 설정은 [managed 설정](/ko/settings#settings-files)에서만 구성할 수 있으며 관리자에게 마켓플레이스 소스에 대한 엄격한 제어를 제공합니다.
**Managed 설정 파일 위치**:
* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`
* **Linux 및 WSL**: `/etc/claude-code/managed-settings.json`
* **Windows**: `C:\Program Files\ClaudeCode\managed-settings.json`
**주요 특성**:
* Managed 설정 (`managed-settings.json`)에서만 사용 가능
* 사용자 또는 프로젝트 설정으로 재정의할 수 없음 (최고 우선순위)
* 네트워크/파일 시스템 작업 전에 적용됨 (차단된 소스는 실행되지 않음)
* `hostPattern`을 제외한 소스 사양에 대해 정확한 일치를 사용합니다. `hostPattern`은 정규식 일치를 사용합니다
**허용 목록 동작**:
* `undefined` (기본값): 제한 없음 - 사용자는 모든 마켓플레이스를 추가할 수 있음
* 빈 배열 `[]`: 완전 잠금 - 사용자는 새 마켓플레이스를 추가할 수 없음
* 소스 목록: 사용자는 정확히 일치하는 마켓플레이스만 추가할 수 있음
**지원되는 모든 소스 유형**:
허용 목록은 여러 마켓플레이스 소스 유형을 지원합니다. 대부분의 소스는 정확한 일치를 사용하는 반면 `hostPattern`은 마켓플레이스 호스트에 대한 정규식 일치를 사용합니다.
1. **GitHub 저장소**:
```json theme={null}
{ "source": "github", "repo": "acme-corp/approved-plugins" }
{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }
```
필드: `repo` (필수), `ref` (선택: 분기/태그/SHA), `path` (선택: 하위 디렉토리)
2. **Git 저장소**:
```json theme={null}
{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }
```
필드: `url` (필수), `ref` (선택: 분기/태그/SHA), `path` (선택: 하위 디렉토리)
3. **URL 기반 마켓플레이스**:
```json theme={null}
{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }
```
필드: `url` (필수), `headers` (선택: 인증된 액세스를 위한 HTTP 헤더)
URL 기반 마켓플레이스는 `marketplace.json` 파일만 다운로드합니다. 서버에서 플러그인 파일을 다운로드하지 않습니다. URL 기반 마켓플레이스의 플러그인은 상대 경로가 아닌 외부 소스 (GitHub, npm 또는 git URL)를 사용해야 합니다. 상대 경로가 있는 플러그인의 경우 대신 Git 기반 마켓플레이스를 사용합니다. [문제 해결](/ko/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)을 참조하세요.
4. **NPM 패키지**:
```json theme={null}
{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }
```
필드: `package` (필수, 범위가 지정된 패키지 지원)
5. **파일 경로**:
```json theme={null}
{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }
```
필드: `path` (필수: marketplace.json 파일의 절대 경로)
6. **디렉토리 경로**:
```json theme={null}
{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }
```
필드: `path` (필수: `.claude-plugin/marketplace.json`을 포함하는 디렉토리의 절대 경로)
7. **호스트 패턴 일치**:
```json theme={null}
{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }
```
필드: `hostPattern` (필수: 마켓플레이스 호스트와 일치하는 정규식 패턴)
각 저장소를 열거하지 않고 특정 호스트의 모든 마켓플레이스를 허용하려면 호스트 패턴 일치를 사용합니다. 이는 개발자가 자신의 마켓플레이스를 만드는 내부 GitHub Enterprise 또는 GitLab 서버가 있는 조직에 유용합니다.
소스 유형별 호스트 추출:
* `github`: 항상 `github.com`에 대해 일치
* `git`: URL에서 호스트 이름 추출 (HTTPS 및 SSH 형식 지원)
* `url`: URL에서 호스트 이름 추출
* `npm`, `file`, `directory`: 호스트 패턴 일치에 지원되지 않음
**구성 예제**:
예제: 특정 마켓플레이스만 허용:
```json theme={null}
{
"strictKnownMarketplaces": [
{
"source": "github",
"repo": "acme-corp/approved-plugins"
},
{
"source": "github",
"repo": "acme-corp/security-tools",
"ref": "v2.0"
},
{
"source": "url",
"url": "https://plugins.example.com/marketplace.json"
},
{
"source": "npm",
"package": "@acme-corp/compliance-plugins"
}
]
}
```
예제 - 모든 마켓플레이스 추가 비활성화:
```json theme={null}
{
"strictKnownMarketplaces": []
}
```
예제: 내부 git 서버의 모든 마켓플레이스 허용:
```json theme={null}
{
"strictKnownMarketplaces": [
{
"source": "hostPattern",
"hostPattern": "^github\\.example\\.com$"
}
]
}
```
**정확한 일치 요구 사항**:
마켓플레이스 소스는 사용자의 추가가 허용되려면 **정확히** 일치해야 합니다. git 기반 소스 (`github` 및 `git`)의 경우 이는 모든 선택적 필드를 포함합니다:
* `repo` 또는 `url`이 정확히 일치해야 함
* `ref` 필드가 정확히 일치해야 함 (또는 둘 다 정의되지 않음)
* `path` 필드가 정확히 일치해야 함 (또는 둘 다 정의되지 않음)
일치하지 **않는** 소스의 예:
```json theme={null}
// 이들은 다른 소스입니다:
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }
// 이것도 다릅니다:
{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
{ "source": "github", "repo": "acme-corp/plugins" }
```
**`extraKnownMarketplaces`와의 비교**:
| 측면 | `strictKnownMarketplaces` | `extraKnownMarketplaces` |
| ---------- | ------------------------- | ------------------------ |
| **목적** | 조직 정책 적용 | 팀 편의 |
| **설정 파일** | `managed-settings.json`만 | 모든 설정 파일 |
| **동작** | 허용 목록에 없는 추가 차단 | 누락된 마켓플레이스 자동 설치 |
| **적용 시기** | 네트워크/파일 시스템 작업 전 | 사용자 신뢰 프롬프트 후 |
| **재정의 가능** | 아니오 (최고 우선순위) | 예 (높은 우선순위 설정으로) |
| **소스 형식** | 직접 소스 객체 | 중첩된 소스가 있는 명명된 마켓플레이스 |
| **사용 사례** | 규정 준수, 보안 제한 | 온보딩, 표준화 |
**형식 차이**:
`strictKnownMarketplaces`는 직접 소스 객체를 사용합니다:
```json theme={null}
{
"strictKnownMarketplaces": [
{ "source": "github", "repo": "acme-corp/plugins" }
]
}
```
`extraKnownMarketplaces`는 명명된 마켓플레이스가 필요합니다:
```json theme={null}
{
"extraKnownMarketplaces": {
"acme-tools": {
"source": { "source": "github", "repo": "acme-corp/plugins" }
}
}
}
```
**함께 사용**:
`strictKnownMarketplaces`는 정책 게이트입니다: 사용자가 추가할 수 있는 것을 제어하지만 마켓플레이스를 등록하지 않습니다. 모든 사용자를 위해 마켓플레이스를 제한하고 사전 등록하려면 `managed-settings.json`에서 둘 다 설정합니다:
```json theme={null}
{
"strictKnownMarketplaces": [
{ "source": "github", "repo": "acme-corp/plugins" }
],
"extraKnownMarketplaces": {
"acme-tools": {
"source": { "source": "github", "repo": "acme-corp/plugins" }
}
}
}
```
`strictKnownMarketplaces`만 설정되면 사용자는 여전히 `/plugin marketplace add`를 통해 허용된 마켓플레이스를 수동으로 추가할 수 있지만 자동으로 사용 가능하지 않습니다.
**중요 참고 사항**:
* 제한은 네트워크 요청 또는 파일 시스템 작업 전에 확인됨
* 차단되면 사용자는 소스가 managed 정책으로 차단되었음을 나타내는 명확한 오류 메시지를 봅니다
* 제한은 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용됩니다. 정책이 설정되기 전에 추가된 마켓플레이스는 해당 소스가 더 이상 허용 목록과 일치하지 않으면 플러그인을 설치하거나 업데이트하는 데 사용할 수 없습니다
* Managed 설정은 최고 우선순위를 가지며 재정의할 수 없습니다
사용자 대면 문서는 [Managed 마켓플레이스 제한](/ko/plugin-marketplaces#managed-marketplace-restrictions)을 참조하세요.
### 플러그인 관리
`/plugin` 명령을 사용하여 플러그인을 대화형으로 관리합니다:
* 마켓플레이스에서 사용 가능한 플러그인 찾아보기
* 플러그인 설치/제거
* 플러그인 활성화/비활성화
* 플러그인 세부 정보 보기 (제공되는 skills, agents, hooks)
* 마켓플레이스 추가/제거
[플러그인 문서](/ko/plugins)에서 플러그인 시스템에 대해 자세히 알아보세요.
## 환경 변수
환경 변수를 사용하면 설정 파일을 편집하지 않고 Claude Code 동작을 제어할 수 있습니다. 모든 변수는 [`settings.json`](#available-settings)의 `env` 키 아래에서 구성하여 모든 세션에 적용하거나 팀에 배포할 수 있습니다.
전체 목록은 [환경 변수 참조](/ko/env-vars)를 참조하세요.
## Claude가 사용할 수 있는 도구
Claude Code는 파일 읽기, 편집, 검색, 명령 실행 및 subagents 조율을 위한 도구 세트에 액세스할 수 있습니다. 도구 이름은 권한 규칙 및 hook 매처에서 사용하는 정확한 문자열입니다.
전체 목록 및 Bash 도구 동작 세부 사항은 [도구 참조](/ko/tools-reference)를 참조하세요.
## 참고 항목
* [권한](/ko/permissions): 권한 시스템, 규칙 구문, 도구 특정 패턴 및 관리형 정책
* [인증](/ko/authentication): Claude Code에 대한 사용자 액세스 설정
* [구성 디버깅](/ko/debug-your-config): 설정, 훅 또는 MCP 서버가 적용되지 않는 이유를 진단합니다
* [설치 및 로그인 문제 해결](/ko/troubleshoot-install): 설치, 인증 및 플랫폼 문제