Claude Code 설정

전역 및 프로젝트 수준 설정과 환경 변수로 Claude Code를 구성합니다.

Claude Code는 사용자의 필요에 맞게 동작을 구성할 수 있는 다양한 설정을 제공합니다. /config 명령을 실행하여 Claude Code를 구성할 수 있으며, 이는 상태 정보를 보고 구성 옵션을 수정할 수 있는 탭 형식의 설정 인터페이스를 엽니다. {/* min-version: 2.1.181 */}v2.1.181부터는 인터페이스를 열지 않고 /config에 key=value를 전달하여 단일 옵션을 변경할 수 있습니다. 예를 들어 /config verbose=true입니다.

구성 범위

Claude Code는 범위 시스템을 사용하여 구성이 어디에 적용되고 누가 공유하는지 결정합니다. 범위를 이해하면 개인 사용, 팀 협업 또는 엔터프라이즈 배포를 위해 Claude Code를 구성하는 방법을 결정하는 데 도움이 됩니다.

사용 가능한 범위

각 범위를 사용할 때

Managed 범위는 다음을 위한 것입니다:

• 조직 전체에서 적용해야 하는 보안 정책
• 재정의할 수 없는 규정 준수 요구 사항
• IT/DevOps에서 배포한 표준화된 구성

User 범위는 다음에 가장 적합합니다:

• 모든 곳에서 원하는 개인 설정 (테마, 편집기 설정)
• 모든 프로젝트에서 사용하는 도구 및 플러그인
• API 키 및 인증 (안전하게 저장됨)

Project 범위는 다음에 가장 적합합니다:

• 팀 공유 설정 (권한, hooks, MCP servers)
• 전체 팀이 가져야 할 플러그인
• 협업자 간 도구 표준화

Local 범위는 다음에 가장 적합합니다:

• 특정 프로젝트에 대한 개인 재정의
• 팀과 공유하기 전에 구성 테스트
• 다른 사용자에게는 작동하지 않을 머신 특정 설정

범위가 상호 작용하는 방식

동일한 설정이 여러 범위에서 구성되면 Claude Code는 우선순위 순서대로 적용합니다:

1. Managed (최고) - 아무것도 재정의할 수 없음
2. 명령줄 인수 - 임시 세션 재정의
3. Local - 프로젝트 및 사용자 설정 재정의
4. Project - 사용자 설정 재정의
5. User (최저) - 다른 것이 설정을 지정하지 않을 때 적용

예를 들어, 사용자 설정에서 spinnerTipsEnabled를 true로 설정하고 프로젝트 설정에서 false로 설정하면 프로젝트 값이 적용됩니다. 권한 규칙은 재정의하지 않고 범위 전체에서 병합되기 때문에 다르게 작동합니다. 설정 우선순위를 참조하십시오.

범위를 사용하는 것

범위는 많은 Claude Code 기능에 적용됩니다:

Windows에서 ~/.claude로 표시된 경로는 %USERPROFILE%\.claude로 확인됩니다.

설정 파일

settings.json 파일은 계층적 설정을 통해 Claude Code를 구성하기 위한 공식 메커니즘입니다:

• 사용자 설정은 ~/.claude/settings.json에 정의되며 모든 프로젝트에 적용됩니다.

• 프로젝트 설정은 프로젝트 디렉토리에 저장됩니다:

  • 소스 제어에 체크인되고 팀과 공유되는 설정을 위한 .claude/settings.json
  • 체크인되지 않은 설정을 위한 .claude/settings.local.json으로, 개인 설정 및 실험에 유용합니다. Claude Code는 .claude/settings.local.json이 생성될 때 git을 구성하여 이를 무시하도록 합니다. 파일을 직접 생성하는 경우 gitignore에 수동으로 추가합니다.

• Managed 설정: 중앙 집중식 제어가 필요한 조직의 경우 Claude Code는 managed 설정을 위한 여러 전달 메커니즘을 지원합니다. 모두 동일한 JSON 형식을 사용하며 사용자 또는 프로젝트 설정으로 재정의할 수 없습니다:

  • 서버 관리 설정: Anthropic의 서버에서 Claude.ai 관리 콘솔을 통해 전달됩니다. 서버 관리 설정을 참조하세요.

  • MDM/OS 수준 정책: macOS 및 Windows의 기본 장치 관리를 통해 전달됩니다:

    • macOS: com.anthropic.claudecode managed preferences domain. plist의 최상위 키는 managed-settings.json을 반영하며, 중첩된 설정은 딕셔너리이고 배열은 plist 배열입니다. Jamf, Iru (Kandji) 또는 유사한 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\

    파일 기반 managed 설정은 managed-settings.json과 동일한 시스템 디렉토리에 managed-settings.d/ 드롭인 디렉토리도 지원합니다. 이를 통해 별도의 팀이 단일 파일 편집을 조정하지 않고 독립적인 정책 조각을 배포할 수 있습니다.

    systemd 규칙을 따르면 managed-settings.json이 먼저 기본으로 병합되고, 드롭인 디렉토리의 모든 *.json 파일이 알파벳순으로 정렬되어 위에 병합됩니다. 스칼라 값의 경우 나중 파일이 이전 파일을 재정의합니다. 배열은 연결되고 중복 제거됩니다. 객체는 깊게 병합됩니다. .로 시작하는 숨겨진 파일은 무시됩니다.

    병합 순서를 제어하려면 숫자 접두사를 사용합니다 (예: 10-telemetry.json 및 20-security.json).

  managed 설정 및 Managed MCP 구성을 참조하세요.

  이 저장소에는 Jamf, Iru (Kandji), Intune 및 그룹 정책에 대한 시작 배포 템플릿이 포함되어 있습니다. 이를 시작점으로 사용하고 필요에 맞게 조정합니다.

• 기타 구성은 ~/.claude.json에 저장됩니다. 이 파일에는 OAuth 세션, MCP server 구성 (사용자 및 local 범위), 프로젝트별 상태 (허용된 도구, 신뢰 설정) 및 다양한 캐시가 포함됩니다. 프로젝트 범위 MCP 서버는 .mcp.json에 별도로 저장됩니다.

{
  "$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 스키마를 가리킵니다. 이를 settings.json에 추가하면 VS Code, Cursor 및 JSON 스키마 검증을 지원하는 다른 편집기에서 자동 완성 및 인라인 검증이 활성화됩니다.

게시된 스키마는 주기적으로 업데이트되며 가장 최근 CLI 릴리스에서 추가된 설정을 포함하지 않을 수 있으므로, 최근에 문서화된 필드에 대한 검증 경고가 반드시 구성이 유효하지 않음을 의미하지는 않습니다.

편집이 적용되는 시기

Claude Code는 설정 파일을 감시하고 변경될 때 다시 로드하므로 대부분의 키에 대한 편집은 재시작 없이 실행 중인 세션에 적용됩니다. 여기에는 permissions, hooks 및 apiKeyHelper와 같은 자격 증명 도우미가 포함됩니다. 다시 로드는 사용자, 프로젝트, local 및 managed 설정을 포함하며, 감지된 각 변경에 대해 ConfigChange hook이 실행됩니다.

몇 가지 키는 세션 시작 시 한 번 읽혀지고 대신 다음 재시작에 적용됩니다:

• model: 세션 중에 전환하려면 /model을 사용합니다
• outputStyle: 시스템 프롬프트의 일부로, /clear 또는 재시작 시 다시 빌드됩니다

Managed 설정의 유효하지 않은 항목

Managed 설정은 관대하게 파싱됩니다. Managed 구성에 스키마 검증에 실패하는 항목이 포함되어 있으면 Claude Code는 해당 항목을 제거하고 경고를 기록하며 남은 모든 유효한 정책을 적용합니다. 단일 오타가 조직의 나머지 정책을 비활성화할 수 없습니다. 이 동작은 세 가지 전달 메커니즘 모두에서 일관됩니다: 서버 관리 설정, MDM을 통해 배포된 plist 및 레지스트리 정책, 그리고 managed-settings.json 파일. Claude Code v2.1.169 이상이 필요합니다.

보안 적용 필드는 전체적으로 제거되는 대신 필드별로 처리됩니다:

requiredMinimumVersion 및 requiredMaximumVersion은 설계상 실패하도록 열려 있습니다: 유효하지 않은 값은 적용되지 않고 제거되므로 잘못된 정책 푸시가 Claude Code 시작을 방지할 수 없습니다.

검증 오류는 세 곳에 표시됩니다:

• 대화형 세션은 시작 시 유효하지 않은 항목을 나열하는 대화를 표시합니다.
• -p를 사용한 헤드리스 실행은 stderr에 요약을 인쇄합니다.
• claude doctor는 각 유효하지 않은 항목을 소스 및 필드와 함께 나열합니다.

정책 변경을 검증하려면 전사 배포 전에 테스트 머신에서 claude doctor를 실행합니다.

이 관대함은 managed 설정에만 적용됩니다. 사용자, 프로젝트 및 local 설정 파일은 엄격합니다: 검증에 실패하는 파일은 전체적으로 거부되고 보고됩니다.

사용 가능한 설정

settings.json은 여러 옵션을 지원합니다:

전역 구성 설정

이러한 설정은 settings.json이 아닌 ~/.claude.json에 저장됩니다. 이들을 settings.json에 추가하면 스키마 검증 오류가 발생합니다.

Worktree 설정

--worktree가 git worktrees를 생성하고 관리하는 방식을 구성합니다.

worktrees에 .env와 같은 gitignored 파일을 복사하려면 설정 대신 프로젝트 루트의 .worktreeinclude 파일을 사용합니다.

권한 설정

권한 규칙 구문

권한 규칙은 Tool 또는 Tool(specifier) 형식을 따릅니다. 규칙은 순서대로 평가됩니다: 먼저 거부 규칙, 그 다음 요청, 그 다음 허용. 첫 번째 일치 규칙이 우승합니다. 규칙 특이성과 관계없이 결과를 결정합니다. 권한 규칙 평가 순서를 참조하세요.

빠른 예제:

Read, Edit, WebFetch, MCP 및 Agent 규칙에 대한 와일드카드 동작, 도구 특정 패턴 및 Bash 패턴의 보안 제한을 포함한 완전한 규칙 구문 참조는 권한 규칙 구문을 참조하세요.

Sandbox 설정

고급 샌드박싱 동작을 구성합니다. 샌드박싱은 bash 명령을 파일 시스템 및 네트워크에서 격리합니다. 자세한 내용은 Sandboxing을 참조하세요.

Sandbox 경로 접두사

filesystem.allowWrite, filesystem.denyWrite, filesystem.denyRead, filesystem.allowRead 및 credentials.files의 경로는 다음 접두사를 지원합니다:

이전 //path 접두사는 절대 경로에 대해 여전히 작동합니다. 이전에 프로젝트 상대 해결을 기대하면서 단일 슬래시 /path를 사용한 경우 ./path로 전환합니다. 이 구문은 /path를 프로젝트 상대로 사용하는 Read 및 Edit 권한 규칙과 다릅니다. Sandbox 파일 시스템 경로는 표준 규칙을 사용합니다: /tmp/build는 절대 경로입니다.

구성 예제:

{
  "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 (예: Co-Authored-By)를 사용하며 사용자 정의하거나 비활성화할 수 있습니다
• Pull request 설명은 일반 텍스트입니다

기본 커밋 attribution:

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

세션의 활성 모델을 반영하는 trailer의 모델 이름입니다.

기본 pull request attribution:

🤖 Generated with [Claude Code](https://claude.com/claude-code)

예제:

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": ""
  }
}

파일 제안 설정

@ 파일 경로 자동 완성을 위한 사용자 정의 명령을 구성합니다. 기본 제공 파일 제안은 빠른 파일 시스템 순회를 사용하지만 대규모 monorepos는 사전 구축된 파일 인덱스 또는 사용자 정의 도구와 같은 프로젝트 특정 인덱싱의 이점을 얻을 수 있습니다.

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

명령은 CLAUDE_PROJECT_DIR을 포함한 hooks와 동일한 환경 변수로 실행됩니다. stdin을 통해 query 필드가 있는 JSON을 받습니다:

{"query": "src/comp"}

stdout에 줄 바꿈으로 구분된 파일 경로를 출력합니다 (현재 15개로 제한됨):

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

예제:

#!/bin/bash
query=$(cat | jq -r '.query')
# your-repo-file-index를 자신의 파일 검색 명령으로 바꿉니다
your-repo-file-index --query "$query" | head -20

바닥글 링크 배지

footerLinksRegexes 설정은 입력 상자 아래 바닥글에 클릭 가능한 배지를 렌더링합니다. 이를 사용하여 검토 도구 및 이슈 추적기와 같은 프로젝트 CLI에서 인쇄한 ID를 세션 링크로 변환합니다.

각 항목의 pattern 정규식은 턴 출력과 일치합니다: 도구 결과 (파일 내용 및 가져온 페이지 포함) 및 Claude의 자체 응답. url 및 label의 {name} 자리 표시자는 패턴의 명명된 캡처 그룹에서 채워집니다.

다음 예제는 PROJ-1234와 같은 이슈 키가 턴 출력에 나타날 때마다 배지를 렌더링합니다. (?<key>...) 명명된 그룹이 키를 캡처하고 {key}가 URL 및 레이블로 대체됩니다:

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

이렇게 구성하면 PROJ-1234가 도구 결과 또는 Claude의 응답에 나타날 때 PROJ-1234 칩이 바닥글에 나타나 https://issues.example.com/browse/PROJ-1234로 연결됩니다.

다음 제약이 각 항목에 적용됩니다:

턴이 완료되면 Claude Code는 메인 스레드에서 각 항목의 pattern 정규식을 턴 출력과 일치시키므로 느린 정규식은 완료될 때까지 UI를 차단합니다. (a+)+$와 같은 중첩된 수량자는 특정 입력에 대해 지수적으로 오래 걸릴 수 있고 세션을 고정시킬 수 있으므로 각 pattern을 선형으로 유지하고 + 또는 * 중첩을 피합니다.

바닥글 배지는 구성된 사용자 정의 상태 줄과 함께 렌더링됩니다. 어느 것도 다른 것을 대체하지 않습니다. 세션 데이터에서 자신의 콘텐츠를 계산하는 스크립트 기반 행에 상태 줄을 사용하고 스크립트 없이 대화에서 ID를 링크로 변환하려면 바닥글 배지를 사용합니다.

Hook 구성

이러한 설정은 어떤 hooks가 실행될 수 있는지와 HTTP hooks가 액세스할 수 있는 것을 제어합니다. allowManagedHooksOnly 설정은 managed 설정에서만 구성할 수 있습니다. 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는 자동으로 차단됩니다. 호스트명 일치는 대소문자를 구분하지 않으며 후행 FQDN 점을 무시하여 DNS 의미론과 일치합니다.

{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

HTTP hook 환경 변수 제한:

HTTP hooks가 헤더 값에 보간할 수 있는 환경 변수 이름을 제한합니다. 각 hook의 유효한 allowedEnvVars는 이 설정과의 교집합입니다.

{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}

정책 도우미로 managed 설정 계산

policyHelper 설정은 시작 시 managed 설정을 동적으로 계산하는 실행 파일을 가리키므로 관리자는 장치 상태, ID 또는 원격 서비스에서 정책을 파생시킬 수 있습니다. MDM 또는 시스템 managed-settings.json 파일에서 구성합니다. Claude Code는 사용자 설정, 프로젝트 설정, HKCU 레지스트리 하이브 및 서버 관리 설정을 포함한 다른 범위에 나타나는 policyHelper를 무시합니다.

설정은 다음 키를 허용합니다:

도우미는 stdout에 JSON 봉투를 작성합니다. 설정을 최상위 수준이 아닌 managedSettings 키 아래에 배치합니다. 왜냐하면 베어 설정 객체는 managedSettings undefined로 파싱되고 아무것도 적용하지 않기 때문입니다:

{
  "managedSettings": {
    "permissions": { "deny": ["Read(//etc/secrets/**)"] }
  },
  "claudeMd": "# Organization context\n...",
  "appendSystemPrompt": "Always cite the internal style guide."
}

도우미가 managedSettings를 내보낼 때 해당 객체는 실행을 위해 파일 기반 managed 설정을 대체합니다. 도우미가 시작 시 0이 아닌 값으로 종료되면 Claude Code는 오류를 인쇄하고 시작을 거부하므로 중단 복원력이 필요한 도우미는 자신의 캐시에서 제공하고 0으로 종료해야 합니다.

설정 우선순위

설정은 우선순위 순서대로 적용됩니다. 가장 높음에서 가장 낮음:

1. Managed 설정 (서버 관리, MDM/OS 수준 정책 또는 managed 설정)

   • IT에서 서버 전달, MDM 구성 프로필, 레지스트리 정책 또는 managed 설정 파일을 통해 배포한 정책
   • 명령줄 인수를 포함한 다른 수준으로 재정의할 수 없음
   • Managed 계층 내에서 우선순위는: 서버 관리 > MDM/OS 수준 정책 > 파일 기반 (managed-settings.d/*.json + managed-settings.json) > HKCU 레지스트리 (Windows만). 하나의 managed 소스만 사용되며 소스는 병합되지 않습니다. 파일 기반 계층 내에서 드롭인 파일과 기본 파일이 함께 병합됩니다.
   • Agent SDK 또는 IDE 확장과 같은 embedding host는 SDK managedSettings 옵션을 통해 정책을 제공할 수 있습니다. 기본적으로 이는 관리자 배포 managed 계층이 있을 때 무시됩니다. 관리자는 parentSettingsBehavior를 "merge"로 설정하여 옵트인할 수 있습니다. embedder의 값은 필터링되므로 managed 정책을 강화할 수 있지만 완화할 수 없습니다.

2. 명령줄 인수

   • 특정 세션에 대한 임시 재정의. --settings <file-or-json>을 통해 전달된 JSON은 파일 기반 설정과 동일한 규칙을 사용하여 병합됩니다: 여기에 설정된 키는 local, project 또는 user 설정의 동일한 키를 재정의하고, 키를 생략하면 낮은 계층 값이 유지됩니다

3. Local 프로젝트 설정 (.claude/settings.local.json)

   • 개인 프로젝트 특정 설정

4. 공유 프로젝트 설정 (.claude/settings.json)

   • 소스 제어의 팀 공유 프로젝트 설정

5. 사용자 설정 (~/.claude/settings.json)

   • 개인 전역 설정

이 계층 구조는 조직 정책이 항상 적용되면서도 팀과 개인이 자신의 경험을 사용자 정의할 수 있도록 보장합니다. CLI, VS Code 확장 또는 JetBrains IDE에서 Claude Code를 실행하든 동일한 우선순위가 적용됩니다.

예를 들어 사용자 설정이 permissions.defaultMode를 acceptEdits로 설정하지만 프로젝트의 공유 설정이 이를 default로 설정하면 프로젝트 값이 적용됩니다. 아래 예제는 배열 값 설정 (예: 권한 규칙)이 대신 어떻게 결합되는지를 다룹니다.

활성 설정 확인

Claude Code 내에서 /status를 실행하여 활성 설정 소스를 확인합니다. 메뉴 내에서 Status 탭에는 이 세션에 대해 Claude Code가 로드한 각 계층을 나열하는 Setting sources 줄이 포함됩니다 (예: User settings 또는 Project local settings). managed 설정이 적용되면 항목은 전달 채널을 괄호로 표시합니다 (예: Enterprise managed settings (remote), (plist), (HKLM), (HKCU) 또는 (file)). 계층은 해당 소스가 최소 하나의 키로 로드될 때만 목록에 나타나므로 빈 목록은 설정 소스를 찾을 수 없음을 의미합니다.

Setting sources 줄은 어떤 소스가 읽혀지는지 확인합니다. 각 개별 키를 제공한 계층을 표시하지는 않습니다. Config 탭은 동일한 대화에서 테마 및 verbose 출력과 같은 고정된 토글 집합의 편집기입니다. settings.json 내용의 보기가 아닙니다.

설정 파일에 유효하지 않은 JSON 또는 검증에 실패한 값이 포함되어 있으면 Claude Code는 시작 시 설정 문제 알림을 표시하고 /status는 영향을 받는 파일을 나열합니다. 각 오류의 세부 사항을 보려면 /doctor를 실행합니다.

구성 시스템의 핵심 포인트

• 메모리 파일 (CLAUDE.md): Claude가 시작 시 로드하는 지침 및 컨텍스트를 포함합니다
• 설정 파일 (JSON): 권한, 환경 변수 및 도구 동작을 구성합니다
• Skills: /skill-name으로 호출하거나 Claude가 자동으로 로드할 수 있는 사용자 정의 프롬프트
• MCP servers: 추가 도구 및 통합으로 Claude Code를 확장합니다
• 우선순위: 높은 수준 구성 (Managed)이 낮은 수준 (User/Project)을 재정의합니다
• 상속: 설정은 범위 전체에서 병합됩니다. 스칼라 값은 높은 우선순위 범위에서 재정의되고, 배열은 연결됩니다 (예외: fallbackModel은 최고 우선순위 범위가 전체 체인을 제공합니다. v2.1.175부터 availableModels도 managed 또는 정책 값이 낮은 우선순위 항목을 완전히 대체합니다)

시스템 프롬프트

Claude Code의 내부 시스템 프롬프트는 게시되지 않습니다. 사용자 정의 지침을 추가하려면 CLAUDE.md 파일 또는 --append-system-prompt 플래그를 사용합니다.

민감한 파일 제외

API 키, 비밀 및 환경 파일과 같은 민감한 정보가 포함된 파일에서 Claude Code가 액세스하는 것을 방지하려면 .claude/settings.json 파일에서 permissions.deny 설정을 사용합니다:

{
  "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 문서에서 subagents 생성 및 사용에 대해 자세히 알아보세요.

플러그인 구성

Claude Code는 skills, agents, hooks 및 MCP servers로 기능을 확장할 수 있는 플러그인 시스템을 지원합니다. 플러그인은 마켓플레이스를 통해 배포되며 사용자 및 저장소 수준 모두에서 구성할 수 있습니다.

플러그인 설정

settings.json의 플러그인 관련 설정:

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

`enabledPlugins`

어떤 플러그인이 활성화되는지 제어합니다. 형식: "plugin-name@marketplace-name": true/false. 어떤 범위에서도 항목이 없는 플러그인은 해당 defaultEnabled 값으로 폴백됩니다.

범위:

• 사용자 설정 (~/.claude/settings.json): 개인 플러그인 설정
• 프로젝트 설정 (.claude/settings.json): 팀과 공유되는 프로젝트 특정 플러그인
• Local 설정 (.claude/settings.local.json): 머신별 재정의, Claude Code가 생성할 때 gitignored됨
• Managed 설정 (managed-settings.json): 모든 범위에서 설치를 차단하고 마켓플레이스에서 플러그인을 숨기는 조직 전체 정책 재정의

예제:

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}

`extraKnownMarketplaces`

저장소에서 사용 가능하게 해야 할 추가 마켓플레이스를 정의합니다. 일반적으로 팀 멤버가 필요한 플러그인 소스에 액세스할 수 있도록 저장소 수준 설정에서 사용됩니다.

저장소에 extraKnownMarketplaces가 포함되면:

1. 팀 멤버는 폴더를 신뢰할 때 마켓플레이스를 설치하라는 메시지를 받습니다
2. 그 다음 팀 멤버는 해당 마켓플레이스에서 플러그인을 설치하라는 메시지를 받습니다
3. 사용자는 원하지 않는 마켓플레이스 또는 플러그인을 건너뛸 수 있습니다 (사용자 설정에 저장됨)
4. 설치는 신뢰 경계를 존중하고 명시적 동의가 필요합니다

예제:

{
  "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 사용)

git 소스 유형은 자체 호스팅 GitLab 및 Bitbucket을 포함한 모든 git 호스팅 서비스에서 작동합니다. Claude Code는 해당 머신에서 git clone이 사용할 것과 동일한 인증으로 저장소를 복제합니다: 구성된 credential helpers, SSH 키 또는 호스트별 토큰 환경 변수. 설정 세부 정보는 Private repositories를 참조하세요.

github 및 git 소스의 경우 source 객체 내부 (repo 또는 url과 함께)에 "skipLfs": true를 설정하여 Claude Code가 마켓플레이스 저장소를 복제하거나 업데이트할 때 Git LFS 다운로드를 건너뜁니다. LFS 포인터 파일은 해당 콘텐츠를 다운로드하는 대신 포인터로 유지됩니다. 저장소에 플러그인 콘텐츠와 무관한 대용량 LFS 객체가 포함되어 있을 때 이를 사용합니다. {/* min-version: 2.1.153 */}Claude Code v2.1.153 이상이 필요합니다.

각 마켓플레이스 항목은 선택적 autoUpdate Boolean도 허용합니다. source와 함께 "autoUpdate": true를 설정하여 Claude Code가 해당 마켓플레이스를 새로고침하고 시작 시 설치된 플러그인을 업데이트하도록 합니다. 생략하면 공식 Anthropic 마켓플레이스는 기본값이 true이고 다른 모든 마켓플레이스는 기본값이 false입니다. 자동 업데이트 구성을 참조하세요.

source: 'settings'를 사용하여 호스팅된 마켓플레이스 저장소를 설정하지 않고 작은 플러그인 세트를 인라인으로 선언합니다. 여기에 나열된 플러그인은 GitHub 또는 npm과 같은 외부 소스를 참조해야 합니다. 여전히 enabledPlugins에서 각 플러그인을 별도로 활성화해야 합니다.

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "settings",
        "name": "team-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": {
              "source": "github",
              "repo": "acme-corp/code-formatter"
            }
          }
        ]
      }
    }
  }
}

`strictKnownMarketplaces`

Managed 설정만: 사용자가 추가할 수 있는 플러그인 마켓플레이스를 제어합니다. 이 설정은 managed 설정에서만 구성할 수 있으며 관리자에게 마켓플레이스 소스에 대한 엄격한 제어를 제공합니다.

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 및 pathPattern을 제외한 소스 사양에 대해 정확한 일치를 사용합니다. hostPattern 및 pathPattern은 정규식 일치를 사용합니다

허용 목록 동작:

• undefined (기본값): 제한 없음 - 사용자는 모든 마켓플레이스를 추가할 수 있습니다
• 빈 배열 []: 완전 잠금 - 사용자는 새 마켓플레이스를 추가할 수 없습니다
• 소스 목록: 사용자는 정확히 일치하는 마켓플레이스만 추가할 수 있습니다

지원되는 모든 소스 유형:

허용 목록은 여러 마켓플레이스 소스 유형을 지원합니다. 대부분의 소스는 정확한 일치를 사용하는 반면 hostPattern 및 pathPattern은 마켓플레이스 호스트 및 파일 시스템 경로에 대한 정규식 일치를 각각 사용합니다.

1. GitHub 저장소:

{ "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 저장소:

{ "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 기반 마켓플레이스:

{ "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 헤더)

4. NPM 패키지:

{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }

필드: package (필수, 범위가 지정된 패키지 지원)

5. 파일 경로:

{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

필드: path (필수: marketplace.json 파일의 절대 경로)

6. 디렉토리 경로:

{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

필드: path (필수: .claude-plugin/marketplace.json을 포함하는 디렉토리의 절대 경로)

7. 호스트 패턴 일치:

{ "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: 호스트 패턴 일치에 지원되지 않음

8. 경로 패턴 일치:

{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
{ "source": "pathPattern", "pathPattern": ".*" }

필드: pathPattern (필수: file 및 directory 소스의 path 필드와 일치하는 정규식 패턴)

네트워크 소스에 대한 hostPattern 제한과 함께 파일 시스템 기반 마켓플레이스를 허용하려면 경로 패턴 일치를 사용합니다. 모든 로컬 경로를 허용하려면 ".*"를 설정하거나 특정 디렉토리로 제한하려면 더 좁은 패턴을 설정합니다.

구성 예제:

예제: 특정 마켓플레이스만 허용:

{
  "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"
    }
  ]
}

예제 - 모든 마켓플레이스 추가 비활성화:

{
  "strictKnownMarketplaces": []
}

예제: 내부 git 서버의 모든 마켓플레이스 허용:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

정확한 일치 요구 사항:

마켓플레이스 소스는 사용자의 추가가 허용되려면 정확히 일치해야 합니다. git 기반 소스 (github 및 git)의 경우 이는 모든 선택적 필드를 포함합니다:

• repo 또는 url이 정확히 일치해야 합니다
• ref 필드가 정확히 일치해야 합니다 (또는 둘 다 정의되지 않음)
• path 필드가 정확히 일치해야 합니다 (또는 둘 다 정의되지 않음)

일치하지 않는 소스의 예:

// 이들은 다른 소스입니다:
{ "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는 직접 소스 객체를 사용합니다:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ]
}

extraKnownMarketplaces는 명명된 마켓플레이스가 필요합니다:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

함께 사용:

strictKnownMarketplaces는 정책 게이트입니다: 사용자가 추가할 수 있는 것을 제어하지만 마켓플레이스를 등록하지 않습니다. 모든 사용자를 위해 마켓플레이스를 제한하고 사전 등록하려면 managed-settings.json에서 둘 다 설정합니다:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ],
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

strictKnownMarketplaces만 설정되면 사용자는 여전히 /plugin marketplace add를 통해 허용된 마켓플레이스를 수동으로 추가할 수 있지만 자동으로 사용 가능하지 않습니다.

중요 참고 사항:

• 제한은 네트워크 요청 또는 파일 시스템 작업 전에 확인됩니다
• 차단되면 사용자는 소스가 managed 정책으로 차단되었음을 나타내는 명확한 오류 메시지를 봅니다
• 제한은 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용됩니다. 정책이 설정되기 전에 추가된 마켓플레이스는 해당 소스가 더 이상 허용 목록과 일치하지 않으면 플러그인을 설치하거나 업데이트하는 데 사용할 수 없습니다
• Managed 설정은 최고 우선순위를 가지며 재정의할 수 없습니다

사용자 대면 문서는 Managed 마켓플레이스 제한을 참조하세요.

`strictPluginOnlyCustomization`

Managed 설정만: skills, agents, hooks 및 MCP servers가 사용자 및 프로젝트 소스에서 로드되는 것을 차단하므로 플러그인 또는 managed 설정에서만 가져올 수 있습니다. strictKnownMarketplaces와 결합하여 전체 사용자 정의 공급 체인을 제어합니다: 마켓플레이스 허용 목록은 사용자가 설치할 수 있는 플러그인을 제어하고 이 설정은 플러그인 또는 managed 설정에서 오지 않는 모든 것을 차단합니다.

값은 모든 4개 표면을 잠그려면 true이거나 잠글 표면을 명명하는 배열입니다:

{
  "strictPluginOnlyCustomization": ["skills", "hooks"]
}

각 잠긴 표면에 대해 Claude Code는 사용자 수준 및 프로젝트 수준 소스를 건너뛰고 플러그인 제공 및 managed 소스만 로드합니다:

Claude Code 버전이 인식하지 못하는 표면 이름은 설정 파일을 실패시키지 않고 무시되므로 모든 클라이언트가 업데이트되기 전에 새 표면 이름을 추가할 수 있습니다.

플러그인 관리

/plugin 명령을 사용하여 플러그인을 대화형으로 관리합니다:

• 마켓플레이스에서 사용 가능한 플러그인 찾아보기
• 플러그인 설치/제거
• 플러그인 활성화/비활성화
• 플러그인 세부 정보 보기 (제공되는 skills, agents, hooks)
• 마켓플레이스 추가/제거

플러그인 문서에서 플러그인 시스템에 대해 자세히 알아보세요.

환경 변수

환경 변수를 사용하면 설정 파일을 편집하지 않고 Claude Code 동작을 제어할 수 있습니다. 모든 변수는 settings.json의 env 키 아래에서 구성하여 모든 세션에 적용하거나 팀에 배포할 수 있습니다.

전체 목록은 환경 변수 참조를 참조하세요.

Claude가 사용할 수 있는 도구

Claude Code는 파일 읽기, 편집, 검색, 명령 실행 및 subagents 조율을 위한 도구 세트에 액세스할 수 있습니다. 도구 이름은 권한 규칙 및 hook 매처에서 사용하는 정확한 문자열입니다.

전체 목록 및 Bash 도구 동작 세부 사항은 도구 참조를 참조하세요.

참고 항목

• 권한: 권한 시스템, 규칙 구문, 도구 특정 패턴 및 관리형 정책
• 인증: Claude Code에 대한 사용자 액세스 설정
• 구성 디버깅: 설정, 훅 또는 MCP 서버가 적용되지 않는 이유를 진단합니다
• 설치 및 로그인 문제 해결: 설치, 인증 및 플랫폼 문제