메인 콘텐츠로 건너뛰기
Claude Code는 사용자의 필요에 맞게 동작을 구성할 수 있는 다양한 설정을 제공합니다. 대화형 REPL을 사용할 때 /config 명령을 실행하여 Claude Code를 구성할 수 있으며, 이는 상태 정보를 보고 구성 옵션을 수정할 수 있는 탭 형식의 설정 인터페이스를 엽니다.

구성 범위

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

사용 가능한 범위

범위위치영향을 받는 대상팀과 공유?
Managed시스템 수준 managed-settings.json머신의 모든 사용자예 (IT에서 배포)
User~/.claude/ 디렉토리모든 프로젝트에서 사용자아니오
Project저장소의 .claude/이 저장소의 모든 협업자예 (git에 커밋됨)
Local.claude/*.local.* 파일이 저장소에서만 사용자아니오 (gitignored)

각 범위를 사용할 시기

Managed 범위는 다음을 위한 것입니다:
  • 조직 전체에서 적용해야 하는 보안 정책
  • 재정의할 수 없는 규정 준수 요구사항
  • IT/DevOps에서 배포한 표준화된 구성
User 범위는 다음에 가장 적합합니다:
  • 모든 곳에서 원하는 개인 설정 (테마, 편집기 설정)
  • 모든 프로젝트에서 사용하는 도구 및 플러그인
  • API 키 및 인증 (안전하게 저장됨)
Project 범위는 다음에 가장 적합합니다:
  • 팀 공유 설정 (권한, hooks, MCP servers)
  • 전체 팀이 가져야 할 플러그인
  • 협업자 간 도구 표준화
Local 범위는 다음에 가장 적합합니다:
  • 특정 프로젝트에 대한 개인 재정의
  • 팀과 공유하기 전에 구성 테스트
  • 다른 사용자에게는 작동하지 않을 머신 특정 설정

범위 상호작용

동일한 설정이 여러 범위에서 구성되면 더 구체적인 범위가 우선합니다:
  1. Managed (최상위) - 아무것도 재정의할 수 없음
  2. 명령줄 인수 - 임시 세션 재정의
  3. Local - 프로젝트 및 사용자 설정 재정의
  4. Project - 사용자 설정 재정의
  5. User (최하위) - 다른 것이 설정을 지정하지 않을 때 적용
예를 들어, 사용자 설정에서 권한이 허용되지만 프로젝트 설정에서 거부되면 프로젝트 설정이 우선하고 권한이 차단됩니다.

범위를 사용하는 것

범위는 많은 Claude Code 기능에 적용됩니다:
기능사용자 위치프로젝트 위치로컬 위치
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.mdCLAUDE.md 또는 .claude/CLAUDE.mdCLAUDE.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-settings.jsonmanaged-mcp.json 파일을 지원합니다:
    • macOS: /Library/Application Support/ClaudeCode/
    • Linux 및 WSL: /etc/claude-code/
    • Windows: C:\Program Files\ClaudeCode\
    이는 시스템 전체 경로입니다 (~/Library/...와 같은 사용자 홈 디렉토리가 아님). 관리자 권한이 필요합니다. IT 관리자가 배포하도록 설계되었습니다.
    자세한 내용은 Managed 설정Managed MCP 구성을 참조하세요.
    Managed 배포는 strictKnownMarketplaces를 사용하여 플러그인 마켓플레이스 추가를 제한할 수도 있습니다. 자세한 내용은 Managed 마켓플레이스 제한을 참조하세요.
  • 기타 구성~/.claude.json에 저장됩니다. 이 파일에는 사용자 설정 (테마, 알림 설정, 편집기 모드), OAuth 세션, 사용자 및 로컬 범위에 대한 MCP server 구성, 프로젝트별 상태 (허용된 도구, 신뢰 설정) 및 다양한 캐시가 포함됩니다. 프로젝트 범위 MCP 서버는 .mcp.json에 별도로 저장됩니다.
Claude Code는 자동으로 구성 파일의 타임스탬프가 지정된 백업을 생성하고 데이터 손실을 방지하기 위해 가장 최근의 5개 백업을 유지합니다.
예제 settings.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 스키마 검증을 지원하는 다른 편집기에서 자동 완성 및 인라인 검증이 활성화됩니다.

사용 가능한 설정

settings.json은 여러 옵션을 지원합니다:
설명예제
apiKeyHelper인증 값을 생성하기 위해 /bin/sh에서 실행할 사용자 정의 스크립트입니다. 이 값은 모델 요청에 대해 X-Api-KeyAuthorization: Bearer 헤더로 전송됩니다/bin/generate_temp_api_key.sh
cleanupPeriodDays이 기간보다 오래 비활성 상태인 세션은 시작 시 삭제됩니다. 0으로 설정하면 모든 세션이 즉시 삭제됩니다. (기본값: 30일)20
companyAnnouncements시작 시 사용자에게 표시할 공지사항입니다. 여러 공지사항이 제공되면 무작위로 순환됩니다.["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]
env모든 세션에 적용될 환경 변수{"FOO": "bar"}
attributiongit 커밋 및 풀 요청에 대한 속성을 사용자 정의합니다. 속성 설정을 참조하세요{"commit": "🤖 Generated with Claude Code", "pr": ""}
includeCoAuthoredBy더 이상 사용되지 않음: 대신 attribution을 사용하세요. git 커밋 및 풀 요청에 co-authored-by Claude 바이라인을 포함할지 여부 (기본값: true)false
permissions권한 구조는 아래 표를 참조하세요.
hooks라이프사이클 이벤트에서 실행할 사용자 정의 명령을 구성합니다. 형식은 hooks 문서를 참조하세요hooks 참조
disableAllHooks모든 hooks 비활성화true
allowManagedHooksOnly(Managed 설정만 해당) 사용자, 프로젝트 및 플러그인 hooks 로드 방지. Managed hooks 및 SDK hooks만 허용합니다. Hook 구성 참조true
allowManagedPermissionRulesOnly(Managed 설정만 해당) 사용자 및 프로젝트 설정이 allow, ask 또는 deny 권한 규칙을 정의하는 것을 방지합니다. Managed 설정의 규칙만 적용됩니다. Managed 전용 설정 참조true
modelClaude Code에 사용할 기본 모델을 재정의합니다"claude-sonnet-4-5-20250929"
otelHeadersHelper동적 OpenTelemetry 헤더를 생성하는 스크립트입니다. 시작 시 및 주기적으로 실행됩니다 (동적 헤더 참조)/bin/generate_otel_headers.sh
statusLine컨텍스트를 표시하기 위한 사용자 정의 상태 줄을 구성합니다. statusLine 문서 참조{"type": "command", "command": "~/.claude/statusline.sh"}
fileSuggestion@ 파일 자동 완성을 위한 사용자 정의 스크립트를 구성합니다. 파일 제안 설정 참조{"type": "command", "command": "~/.claude/file-suggestion.sh"}
respectGitignore@ 파일 선택기가 .gitignore 패턴을 준수하는지 여부를 제어합니다. true (기본값)일 때 .gitignore 패턴과 일치하는 파일은 제안에서 제외됩니다false
outputStyle시스템 프롬프트를 조정하기 위한 출력 스타일을 구성합니다. 출력 스타일 문서 참조"Explanatory"
forceLoginMethodclaudeai를 사용하여 Claude.ai 계정으로만 로그인 제한, console을 사용하여 Claude Console (API 사용 청구) 계정으로만 로그인 제한claudeai
forceLoginOrgUUID로그인 중에 자동으로 선택할 조직의 UUID를 지정하여 조직 선택 단계를 건너뜁니다. forceLoginMethod를 설정해야 합니다"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
enableAllProjectMcpServers프로젝트 .mcp.json 파일에 정의된 모든 MCP 서버를 자동으로 승인합니다true
enabledMcpjsonServers승인할 .mcp.json 파일의 특정 MCP 서버 목록["memory", "github"]
disabledMcpjsonServers거부할 .mcp.json 파일의 특정 MCP 서버 목록["filesystem"]
allowedMcpServersmanaged-settings.json에 설정되면 사용자가 구성할 수 있는 MCP 서버의 허용 목록입니다. 정의되지 않음 = 제한 없음, 빈 배열 = 잠금. 모든 범위에 적용됩니다. 거부 목록이 우선합니다. Managed MCP 구성 참조[{ "serverName": "github" }]
deniedMcpServersmanaged-settings.json에 설정되면 명시적으로 차단된 MCP 서버의 거부 목록입니다. 모든 범위 (Managed 서버 포함)에 적용됩니다. 거부 목록이 허용 목록보다 우선합니다. Managed MCP 구성 참조[{ "serverName": "filesystem" }]
strictKnownMarketplacesmanaged-settings.json에 설정되면 사용자가 추가할 수 있는 플러그인 마켓플레이스의 허용 목록입니다. 정의되지 않음 = 제한 없음, 빈 배열 = 잠금. 마켓플레이스 추가에만 적용됩니다. Managed 마켓플레이스 제한 참조[{ "source": "github", "repo": "acme-corp/plugins" }]
awsAuthRefresh.aws 디렉토리를 수정하는 사용자 정의 스크립트 (고급 자격증명 구성 참조)aws sso login --profile myprofile
awsCredentialExportAWS 자격증명이 포함된 JSON을 출력하는 사용자 정의 스크립트 (고급 자격증명 구성 참조)/bin/generate_aws_grant.sh
alwaysThinkingEnabled모든 세션에 대해 기본적으로 확장 사고를 활성화합니다. 일반적으로 직접 편집하기보다는 /config 명령을 통해 구성됩니다true
plansDirectory계획 파일이 저장되는 위치를 사용자 정의합니다. 경로는 프로젝트 루트에 상대적입니다. 기본값: ~/.claude/plans"./plans"
showTurnDuration응답 후 턴 지속 시간 메시지를 표시합니다 (예: “Cooked for 1m 6s”). 이 메시지를 숨기려면 false로 설정합니다true
spinnerVerbs스피너 및 턴 지속 시간 메시지에 표시되는 작업 동사를 사용자 정의합니다. mode"replace"로 설정하여 사용자 정의 동사만 사용하거나 "append"로 설정하여 기본값에 추가합니다{"mode": "append", "verbs": ["Pondering", "Crafting"]}
languageClaude의 선호 응답 언어를 구성합니다 (예: "japanese", "spanish", "french"). Claude는 기본적으로 이 언어로 응답합니다"japanese"
autoUpdatesChannel업데이트를 따를 릴리스 채널입니다. 일반적으로 약 1주일 된 버전이고 주요 회귀가 있는 버전을 건너뛰는 "stable"을 사용하거나 가장 최근 릴리스인 "latest" (기본값)을 사용합니다"stable"
spinnerTipsEnabledClaude가 작업 중일 때 스피너에 팁을 표시합니다. 팁을 비활성화하려면 false로 설정합니다 (기본값: true)false
terminalProgressBarEnabledWindows Terminal 및 iTerm2와 같은 지원되는 터미널에서 진행률을 표시하는 터미널 진행률 표시줄을 활성화합니다 (기본값: true)false
prefersReducedMotion접근성을 위해 UI 애니메이션 (스피너, 반짝임, 플래시 효과)을 줄이거나 비활성화합니다true
teammateMode에이전트 팀 팀원이 표시되는 방식: auto (tmux 또는 iTerm2에서 분할 창 선택, 그 외에는 in-process), in-process 또는 tmux. 에이전트 팀 설정 참조"in-process"

권한 설정

설명예제
allow도구 사용을 허용하는 권한 규칙의 배열입니다. 패턴 매칭 세부사항은 아래의 권한 규칙 구문을 참조하세요[ "Bash(git diff *)" ]
ask도구 사용 시 확인을 요청하는 권한 규칙의 배열입니다. 패턴 매칭 세부사항은 아래의 권한 규칙 구문을 참조하세요[ "Bash(git push *)" ]
deny도구 사용을 거부하는 권한 규칙의 배열입니다. 이를 사용하여 Claude Code 액세스에서 민감한 파일을 제외합니다. 권한 규칙 구문Bash 권한 제한 참조[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]
additionalDirectoriesClaude가 액세스할 수 있는 추가 작업 디렉토리[ "../docs/" ]
defaultModeClaude Code를 열 때 기본 권한 모드"acceptEdits"
disableBypassPermissionsModebypassPermissions 모드가 활성화되는 것을 방지하려면 "disable"로 설정합니다. 이는 --dangerously-skip-permissions 명령줄 플래그를 비활성화합니다. Managed 설정 참조"disable"

권한 규칙 구문

권한 규칙은 Tool 또는 Tool(specifier) 형식을 따릅니다. 규칙은 순서대로 평가됩니다: 먼저 거부 규칙, 그 다음 요청, 그 다음 허용. 첫 번째 일치 규칙이 우선합니다. 빠른 예제:
규칙효과
Bash모든 Bash 명령과 일치
Bash(npm run *)npm run으로 시작하는 명령과 일치
Read(./.env).env 파일 읽기와 일치
WebFetch(domain:example.com)example.com에 대한 가져오기 요청과 일치
와일드카드 동작, Read, Edit, WebFetch, MCP 및 Task 규칙에 대한 도구별 패턴, Bash 패턴의 보안 제한을 포함한 완전한 규칙 구문 참조는 권한 규칙 구문을 참조하세요.

샌드박스 설정

고급 샌드박싱 동작을 구성합니다. 샌드박싱은 bash 명령을 파일 시스템 및 네트워크에서 격리합니다. 자세한 내용은 샌드박싱을 참조하세요. 파일 시스템 및 네트워크 제한은 이 샌드박스 설정이 아닌 Read, Edit 및 WebFetch 권한 규칙을 통해 구성됩니다.
설명예제
enabledbash 샌드박싱 활성화 (macOS, Linux 및 WSL2). 기본값: falsetrue
autoAllowBashIfSandboxed샌드박싱되면 bash 명령 자동 승인. 기본값: truetrue
excludedCommands샌드박스 외부에서 실행해야 할 명령["git", "docker"]
allowUnsandboxedCommandsdangerouslyDisableSandbox 매개변수를 통해 샌드박스 외부에서 명령을 실행하도록 허용합니다. false로 설정하면 dangerouslyDisableSandbox 이스케이프 해치가 완전히 비활성화되고 모든 명령은 샌드박싱되거나 excludedCommands에 있어야 합니다. 엄격한 샌드박싱이 필요한 엔터프라이즈 정책에 유용합니다. 기본값: truefalse
network.allowUnixSockets샌드박스에서 액세스 가능한 Unix 소켓 경로 (SSH 에이전트 등)["~/.ssh/agent-socket"]
network.allowAllUnixSockets샌드박스에서 모든 Unix 소켓 연결을 허용합니다. 기본값: falsetrue
network.allowLocalBindinglocalhost 포트에 바인딩 허용 (macOS만 해당). 기본값: falsetrue
network.allowedDomains아웃바운드 네트워크 트래픽을 허용할 도메인의 배열입니다. 와일드카드를 지원합니다 (예: *.example.com).["github.com", "*.npmjs.org"]
network.httpProxyPort자신의 프록시를 가져오려는 경우 사용되는 HTTP 프록시 포트입니다. 지정하지 않으면 Claude가 자신의 프록시를 실행합니다.8080
network.socksProxyPort자신의 프록시를 가져오려는 경우 사용되는 SOCKS5 프록시 포트입니다. 지정하지 않으면 Claude가 자신의 프록시를 실행합니다.8081
enableWeakerNestedSandbox권한이 없는 Docker 환경에서 더 약한 샌드박스를 활성화합니다 (Linux 및 WSL2만 해당). 보안이 감소합니다. 기본값: falsetrue
구성 예제:
{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)"
    ]
  }
}
파일 시스템 및 네트워크 제한은 표준 권한 규칙을 사용합니다:
  • Read 거부 규칙을 사용하여 Claude가 특정 파일 또는 디렉토리를 읽는 것을 차단합니다
  • Edit 허용 규칙을 사용하여 Claude가 현재 작업 디렉토리 이상의 디렉토리에 쓸 수 있도록 합니다
  • Edit 거부 규칙을 사용하여 특정 경로에 대한 쓰기를 차단합니다
  • WebFetch 허용/거부 규칙을 사용하여 Claude가 액세스할 수 있는 네트워크 도메인을 제어합니다

속성 설정

Claude Code는 git 커밋 및 풀 요청에 속성을 추가합니다. 이는 별도로 구성됩니다:
  • 커밋은 기본적으로 git trailers (예: Co-Authored-By)를 사용하며, 사용자 정의하거나 비활성화할 수 있습니다
  • 풀 요청 설명은 일반 텍스트입니다
설명
commitgit 커밋에 대한 속성 (모든 trailers 포함). 빈 문자열은 커밋 속성을 숨깁니다
pr풀 요청 설명에 대한 속성. 빈 문자열은 풀 요청 속성을 숨깁니다
기본 커밋 속성:
🤖 Generated with [Claude Code](https://claude.com/claude-code)

   Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
기본 풀 요청 속성:
🤖 Generated with [Claude Code](https://claude.com/claude-code)
예제:
{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <[email protected]>",
    "pr": ""
  }
}
attribution 설정은 더 이상 사용되지 않는 includeCoAuthoredBy 설정보다 우선합니다. 모든 속성을 숨기려면 commitpr을 빈 문자열로 설정합니다.

파일 제안 설정

@ 파일 경로 자동 완성을 위한 사용자 정의 명령을 구성합니다. 기본 제공 파일 제안은 빠른 파일 시스템 순회를 사용하지만 대규모 모노레포는 사전 구축된 파일 인덱스 또는 사용자 정의 도구와 같은 프로젝트별 인덱싱의 이점을 얻을 수 있습니다.
{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}
명령은 hooks와 동일한 환경 변수로 실행되며 CLAUDE_PROJECT_DIR을 포함합니다. 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 --query "$query" | head -20

Hook 구성

Managed 설정만 해당: 실행할 수 있는 hooks를 제어합니다. 이 설정은 Managed 설정에서만 구성할 수 있으며 관리자에게 hook 실행에 대한 엄격한 제어를 제공합니다. allowManagedHooksOnlytrue일 때의 동작:
  • Managed hooks 및 SDK hooks가 로드됩니다
  • 사용자 hooks, 프로젝트 hooks 및 플러그인 hooks가 차단됩니다
구성:
{
  "allowManagedHooksOnly": true
}

설정 우선순위

설정은 우선순위 순서로 적용됩니다. 최상위에서 최하위로:
  1. Managed 설정 (managed-settings.json)
    • IT/DevOps에서 시스템 디렉토리에 배포한 정책
    • 사용자 또는 프로젝트 설정으로 재정의할 수 없음
  2. 명령줄 인수
    • 특정 세션에 대한 임시 재정의
  3. 로컬 프로젝트 설정 (.claude/settings.local.json)
    • 개인 프로젝트별 설정
  4. 공유 프로젝트 설정 (.claude/settings.json)
    • 소스 제어의 팀 공유 프로젝트 설정
  5. 사용자 설정 (~/.claude/settings.json)
    • 개인 전역 설정
이 계층 구조는 조직 정책이 항상 적용되면서도 팀과 개인이 자신의 경험을 사용자 정의할 수 있도록 보장합니다. 예를 들어, 사용자 설정에서 Bash(npm run *)을 허용하지만 프로젝트의 공유 설정에서 거부하면 프로젝트 설정이 우선하고 명령이 차단됩니다.

구성 시스템의 핵심 사항

  • 메모리 파일 (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 설정을 사용합니다:
{
  "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": "github",
      "repo": "acme-corp/claude-plugins"
    }
  }
}

enabledPlugins

활성화된 플러그인을 제어합니다. 형식: "plugin-name@marketplace-name": true/false 범위:
  • 사용자 설정 (~/.claude/settings.json): 개인 플러그인 설정
  • 프로젝트 설정 (.claude/settings.json): 팀과 공유되는 프로젝트별 플러그인
  • 로컬 설정 (.claude/settings.local.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 사용)

strictKnownMarketplaces

Managed 설정만 해당: 사용자가 추가할 수 있는 플러그인 마켓플레이스를 제어합니다. 이 설정은 managed-settings.json에서만 구성할 수 있으며 관리자에게 마켓플레이스 소스에 대한 엄격한 제어를 제공합니다. 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을 제외한 소스 사양에 대해 정확한 일치를 사용합니다 (정규식 일치 사용)
허용 목록 동작:
  • undefined (기본값): 제한 없음 - 사용자가 모든 마켓플레이스를 추가할 수 있음
  • 빈 배열 []: 완전 잠금 - 사용자가 새 마켓플레이스를 추가할 수 없음
  • 소스 목록: 사용자는 정확히 일치하는 마켓플레이스만 추가할 수 있음
지원되는 모든 소스 유형: 허용 목록은 7가지 마켓플레이스 소스 유형을 지원합니다. 대부분의 소스는 정확한 일치를 사용하지만 hostPattern은 마켓플레이스 호스트에 대해 정규식 일치를 사용합니다.
  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 (선택사항: 하위 디렉토리)
  1. 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://[email protected]/plugins.git", "ref": "v3.1", "path": "approved" }
필드: url (필수), ref (선택사항: 분기/태그/SHA), path (선택사항: 하위 디렉토리)
  1. 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 헤더)
URL 기반 마켓플레이스는 marketplace.json 파일만 다운로드합니다. 서버에서 플러그인 파일을 다운로드하지 않습니다. URL 기반 마켓플레이스의 플러그인은 상대 경로가 아닌 외부 소스 (GitHub, npm 또는 git URL)를 사용해야 합니다. 상대 경로가 있는 플러그인의 경우 Git 기반 마켓플레이스를 대신 사용합니다. 자세한 내용은 문제 해결을 참조하세요.
  1. NPM 패키지:
{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }
필드: package (필수, 범위가 지정된 패키지 지원)
  1. 파일 경로:
{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }
필드: path (필수: marketplace.json 파일의 절대 경로)
  1. 디렉토리 경로:
{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }
필드: path (필수: .claude-plugin/marketplace.json을 포함하는 디렉토리의 절대 경로)
  1. 호스트 패턴 일치:
{ "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: 호스트 패턴 일치에 지원되지 않음
구성 예제: 예제: 특정 마켓플레이스만 허용:
{
  "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 기반 소스 (githubgit)의 경우 모든 선택사항 필드를 포함합니다:
  • 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와의 비교:
측면strictKnownMarketplacesextraKnownMarketplaces
목적조직 정책 적용팀 편의
설정 파일managed-settings.json모든 설정 파일
동작허용 목록에 없는 추가 차단누락된 마켓플레이스 자동 설치
적용 시기네트워크/파일 시스템 작업 전사용자 신뢰 프롬프트 후
재정의 가능아니오 (최상위 우선순위)예 (더 높은 우선순위 설정)
소스 형식직접 소스 객체중첩된 소스가 있는 명명된 마켓플레이스
사용 사례규정 준수, 보안 제한온보딩, 표준화
형식 차이: strictKnownMarketplaces는 직접 소스 객체를 사용합니다:
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ]
}
extraKnownMarketplaces는 명명된 마켓플레이스가 필요합니다:
{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}
중요 참고사항:
  • 제한은 네트워크 요청 또는 파일 시스템 작업 전에 확인됩니다
  • 차단되면 사용자는 소스가 Managed 정책에 의해 차단되었음을 나타내는 명확한 오류 메시지를 봅니다
  • 제한은 새 마켓플레이스 추가에만 적용됩니다. 이전에 설치된 마켓플레이스는 계속 액세스 가능합니다
  • Managed 설정은 최상위 우선순위를 가지며 재정의할 수 없습니다
사용자 대면 문서는 Managed 마켓플레이스 제한을 참조하세요.

플러그인 관리

/plugin 명령을 사용하여 플러그인을 대화형으로 관리합니다:
  • 마켓플레이스에서 사용 가능한 플러그인 찾아보기
  • 플러그인 설치/제거
  • 플러그인 활성화/비활성화
  • 플러그인 세부사항 보기 (제공되는 명령, 에이전트, hooks)
  • 마켓플레이스 추가/제거
플러그인 문서에서 플러그인 시스템에 대해 자세히 알아보세요.

환경 변수

Claude Code는 다음 환경 변수를 지원하여 동작을 제어합니다:
모든 환경 변수는 settings.json에서도 구성할 수 있습니다. 이는 각 세션에 대해 환경 변수를 자동으로 설정하거나 전체 팀 또는 조직에 대해 환경 변수 집합을 배포하는 방법으로 유용합니다.
변수목적
ANTHROPIC_API_KEYX-Api-Key 헤더로 전송되는 API 키, 일반적으로 Claude SDK용 (대화형 사용의 경우 /login 실행)
ANTHROPIC_AUTH_TOKENAuthorization 헤더의 사용자 정의 값 (여기서 설정한 값에 Bearer 접두사가 붙음)
ANTHROPIC_CUSTOM_HEADERS요청에 추가할 사용자 정의 헤더 (Name: Value 형식, 여러 헤더의 경우 줄 바꿈으로 구분)
ANTHROPIC_DEFAULT_HAIKU_MODEL모델 구성 참조
ANTHROPIC_DEFAULT_OPUS_MODEL모델 구성 참조
ANTHROPIC_DEFAULT_SONNET_MODEL모델 구성 참조
ANTHROPIC_FOUNDRY_API_KEYMicrosoft Foundry 인증을 위한 API 키 (Microsoft Foundry 참조)
ANTHROPIC_FOUNDRY_BASE_URLFoundry 리소스의 전체 기본 URL (예: https://my-resource.services.ai.azure.com/anthropic). ANTHROPIC_FOUNDRY_RESOURCE의 대안 (Microsoft Foundry 참조)
ANTHROPIC_FOUNDRY_RESOURCEFoundry 리소스 이름 (예: my-resource). ANTHROPIC_FOUNDRY_BASE_URL이 설정되지 않은 경우 필수 (Microsoft Foundry 참조)
ANTHROPIC_MODEL사용할 모델 설정의 이름 (모델 구성 참조)
ANTHROPIC_SMALL_FAST_MODEL[더 이상 사용되지 않음] 배경 작업용 Haiku 클래스 모델의 이름
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGIONBedrock을 사용할 때 Haiku 클래스 모델의 AWS 지역 재정의
AWS_BEARER_TOKEN_BEDROCK인증을 위한 Bedrock API 키 (Bedrock API 키 참조)
BASH_DEFAULT_TIMEOUT_MS장시간 실행되는 bash 명령의 기본 시간 초과
BASH_MAX_OUTPUT_LENGTH중간 잘림 전 bash 출력의 최대 문자 수
BASH_MAX_TIMEOUT_MS모델이 장시간 실행되는 bash 명령에 대해 설정할 수 있는 최대 시간 초과
CLAUDE_AUTOCOMPACT_PCT_OVERRIDEauto-compaction이 트리거되는 컨텍스트 용량의 백분율 (1-100)을 설정합니다. 기본적으로 auto-compaction은 약 95% 용량에서 트리거됩니다. 50과 같은 낮은 값을 사용하여 더 일찍 압축합니다. 기본 임계값 이상의 값은 효과가 없습니다. 주 대화 및 subagents 모두에 적용됩니다. 이 백분율은 상태 줄에서 사용 가능한 context_window.used_percentage 필드와 일치합니다
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR각 Bash 명령 후 원래 작업 디렉토리로 돌아갑니다
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD--add-dir으로 지정된 디렉토리에서 CLAUDE.md 파일을 로드하려면 1로 설정합니다. 기본적으로 추가 디렉토리는 메모리 파일을 로드하지 않습니다1
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS에이전트 팀을 활성화하려면 1로 설정합니다. 에이전트 팀은 실험적이며 기본적으로 비활성화됩니다
CLAUDE_CODE_API_KEY_HELPER_TTL_MS자격증명을 새로 고쳐야 하는 간격 (밀리초) (apiKeyHelper 사용 시)
CLAUDE_CODE_CLIENT_CERTmTLS 인증을 위한 클라이언트 인증서 파일의 경로
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE암호화된 CLAUDE_CODE_CLIENT_KEY의 암호 (선택사항)
CLAUDE_CODE_CLIENT_KEYmTLS 인증을 위한 클라이언트 개인 키 파일의 경로
CLAUDE_CODE_EFFORT_LEVEL지원되는 모델에 대한 노력 수준을 설정합니다. 값: low, medium, high (기본값). 낮은 노력은 더 빠르고 저렴하며, 높은 노력은 더 깊은 추론을 제공합니다. 현재 Opus 4.6에서만 지원됩니다. 노력 수준 조정 참조
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASAnthropic API 특정 anthropic-beta 헤더를 비활성화하려면 1로 설정합니다. 타사 공급자가 있는 LLM 게이트웨이를 사용할 때 “Unexpected value(s) for the anthropic-beta header”와 같은 문제가 발생하는 경우 사용합니다
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS모든 배경 작업 기능을 비활성화하려면 1로 설정합니다. Bash 및 subagent 도구의 run_in_background 매개변수, auto-backgrounding 및 Ctrl+B 단축키 포함
CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY”Claude는 어떻게 하고 있나요?” 세션 품질 설문조사를 비활성화하려면 1로 설정합니다. 타사 공급자를 사용하거나 원격 측정이 비활성화되면 비활성화됩니다. 세션 품질 설문조사 참조
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY쿼리 루프가 유휴 상태가 된 후 자동으로 종료되기 전에 대기할 시간 (밀리초). SDK 모드를 사용하는 자동화된 워크플로우 및 스크립트에 유용합니다
CLAUDE_CODE_PROXY_RESOLVES_HOSTS프록시가 호출자 대신 DNS 해석을 수행하도록 허용하려면 true로 설정합니다. 프록시가 호스트명 해석을 처리해야 하는 환경에 대해 옵트인합니다
CLAUDE_CODE_TASK_LIST_ID세션 간에 작업 목록을 공유합니다. 여러 Claude Code 인스턴스에서 동일한 ID를 설정하여 공유 작업 목록에서 조정합니다. 작업 목록 참조
CLAUDE_CODE_TEAM_NAME이 팀원이 속한 에이전트 팀의 이름입니다. 에이전트 팀 멤버에서 자동으로 설정됩니다
CLAUDE_CODE_TMPDIR내부 임시 파일에 사용되는 임시 디렉토리를 재정의합니다. Claude Code는 이 경로에 /claude/를 추가합니다. 기본값: Unix/macOS에서 /tmp, Windows에서 os.tmpdir()
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICDISABLE_AUTOUPDATER, DISABLE_BUG_COMMAND, DISABLE_ERROR_REPORTINGDISABLE_TELEMETRY 설정과 동일
CLAUDE_CODE_DISABLE_TERMINAL_TITLE대화 컨텍스트를 기반으로 자동 터미널 제목 업데이트를 비활성화하려면 1로 설정합니다
CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION프롬프트 제안을 비활성화하려면 false로 설정합니다 (/config의 “프롬프트 제안” 토글). 이는 Claude가 응답한 후 프롬프트 입력에 나타나는 회색으로 표시된 예측입니다. 프롬프트 제안 참조
CLAUDE_CODE_ENABLE_TASKS이전 TODO 목록으로 임시로 되돌리려면 false로 설정합니다. 기본값: true. 작업 목록 참조
CLAUDE_CODE_ENABLE_TELEMETRYOpenTelemetry 데이터 수집을 활성화하려면 1로 설정합니다. OTel 내보내기를 구성하기 전에 필요합니다. 모니터링 참조
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS파일 읽기의 기본 토큰 제한을 재정의합니다. 전체 파일을 읽어야 할 때 유용합니다
CLAUDE_CODE_HIDE_ACCOUNT_INFOClaude Code UI에서 이메일 주소 및 조직 이름을 숨기려면 1로 설정합니다. 스트리밍 또는 녹화할 때 유용합니다
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALLIDE 확장 자동 설치 건너뛰기
CLAUDE_CODE_MAX_OUTPUT_TOKENS대부분의 요청에 대한 최대 출력 토큰 수를 설정합니다. 기본값: 32,000. 최대값: 64,000. 이 값을 증가시키면 auto-compaction이 트리거되기 전에 사용 가능한 효과적인 컨텍스트 윈도우가 감소합니다.
CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS동적 OpenTelemetry 헤더를 새로 고치는 간격 (밀리초) (기본값: 1740000 / 29분). 동적 헤더 참조
CLAUDE_CODE_PLAN_MODE_REQUIRED에이전트 팀 팀원이 계획 승인이 필요한 경우 자동으로 true로 설정됩니다. 읽기 전용: Claude Code가 팀원을 생성할 때 설정됩니다. 팀원에 대한 계획 승인 필요 참조
CLAUDE_CODE_SHELL자동 셸 감지를 재정의합니다. 로그인 셸이 선호하는 작업 셸과 다를 때 유용합니다 (예: bash vs zsh)
CLAUDE_CODE_SHELL_PREFIX모든 bash 명령을 래핑할 명령 접두사 (예: 로깅 또는 감사). 예: /path/to/logger.sh/path/to/logger.sh <command>를 실행합니다
CLAUDE_CODE_SKIP_BEDROCK_AUTHBedrock에 대한 AWS 인증을 건너뜁니다 (예: LLM 게이트웨이를 사용할 때)
CLAUDE_CODE_SKIP_FOUNDRY_AUTHMicrosoft Foundry에 대한 Azure 인증을 건너뜁니다 (예: LLM 게이트웨이를 사용할 때)
CLAUDE_CODE_SKIP_VERTEX_AUTHVertex에 대한 Google 인증을 건너뜁니다 (예: LLM 게이트웨이를 사용할 때)
CLAUDE_CODE_SUBAGENT_MODEL모델 구성 참조
CLAUDE_CODE_USE_BEDROCKBedrock 사용
CLAUDE_CODE_USE_FOUNDRYMicrosoft Foundry 사용
CLAUDE_CODE_USE_VERTEXVertex 사용
CLAUDE_CONFIG_DIRClaude Code가 구성 및 데이터 파일을 저장하는 위치를 사용자 정의합니다
DISABLE_AUTOUPDATER자동 업데이트를 비활성화하려면 1로 설정합니다.
DISABLE_BUG_COMMAND/bug 명령을 비활성화하려면 1로 설정합니다
DISABLE_COST_WARNINGS비용 경고 메시지를 비활성화하려면 1로 설정합니다
DISABLE_ERROR_REPORTINGSentry 오류 보고를 거부하려면 1로 설정합니다
DISABLE_INSTALLATION_CHECKS설치 경고를 비활성화하려면 1로 설정합니다. 설치 위치를 수동으로 관리할 때만 사용하세요. 표준 설치의 문제를 숨길 수 있습니다
DISABLE_NON_ESSENTIAL_MODEL_CALLS맛 텍스트와 같은 중요하지 않은 경로에 대한 모델 호출을 비활성화하려면 1로 설정합니다
DISABLE_PROMPT_CACHING모든 모델에 대해 prompt caching을 비활성화하려면 1로 설정합니다 (모델별 설정보다 우선)
DISABLE_PROMPT_CACHING_HAIKUHaiku 모델에 대해 prompt caching을 비활성화하려면 1로 설정합니다
DISABLE_PROMPT_CACHING_OPUSOpus 모델에 대해 prompt caching을 비활성화하려면 1로 설정합니다
DISABLE_PROMPT_CACHING_SONNETSonnet 모델에 대해 prompt caching을 비활성화하려면 1로 설정합니다
DISABLE_TELEMETRYStatsig 원격 측정을 거부하려면 1로 설정합니다 (Statsig 이벤트는 코드, 파일 경로 또는 bash 명령과 같은 사용자 데이터를 포함하지 않음)
ENABLE_TOOL_SEARCHMCP 도구 검색을 제어합니다. 값: auto (기본값, 10% 컨텍스트에서 활성화), auto:N (사용자 정의 임계값, 예: 5%의 경우 auto:5), true (항상 켜짐), false (비활성화)
FORCE_AUTOUPDATE_PLUGINS주 auto-updater가 DISABLE_AUTOUPDATER를 통해 비활성화된 경우에도 플러그인 auto-updates를 강제하려면 true로 설정합니다
HTTP_PROXY네트워크 연결을 위한 HTTP 프록시 서버를 지정합니다
HTTPS_PROXY네트워크 연결을 위한 HTTPS 프록시 서버를 지정합니다
IS_DEMO데모 모드를 활성화하려면 true로 설정합니다: UI에서 이메일 및 조직을 숨기고, 온보딩을 건너뛰고, 내부 명령을 숨깁니다. 스트리밍 또는 녹화 세션에 유용합니다
MAX_MCP_OUTPUT_TOKENSMCP 도구 응답에서 허용되는 최대 토큰 수입니다. Claude Code는 출력이 10,000 토큰을 초과할 때 경고를 표시합니다 (기본값: 25000)
MAX_THINKING_TOKENS확장 사고 토큰 예산을 재정의합니다. 사고는 기본적으로 최대 예산 (31,999 토큰)에서 활성화됩니다. 예산을 제한하려면 이를 사용합니다 (예: MAX_THINKING_TOKENS=10000) 또는 사고를 완전히 비활성화합니다 (MAX_THINKING_TOKENS=0). Opus 4.6의 경우 사고 깊이는 대신 노력 수준으로 제어되며 0으로 설정하여 사고를 비활성화하지 않는 한 이 변수는 무시됩니다.
MCP_CLIENT_SECRET사전 구성된 자격증명이 필요한 MCP 서버에 대한 OAuth 클라이언트 비밀입니다. --client-secret으로 서버를 추가할 때 대화형 프롬프트를 피합니다
MCP_OAUTH_CALLBACK_PORT사전 구성된 자격증명으로 MCP 서버를 추가할 때 --callback-port의 대안으로 OAuth 리디렉션 콜백의 고정 포트
MCP_TIMEOUTMCP 서버 시작의 시간 초과 (밀리초)
MCP_TOOL_TIMEOUTMCP 도구 실행의 시간 초과 (밀리초)
NO_PROXY프록시를 우회하여 직접 요청이 발급될 도메인 및 IP 목록
SLASH_COMMAND_TOOL_CHAR_BUDGETSkill 도구에 표시되는 skill 메타데이터의 최대 문자 수 (기본값: 15000). 하위 호환성을 위해 레거시 이름 유지됨.
USE_BUILTIN_RIPGREPClaude Code에 포함된 rg 대신 시스템 설치 rg를 사용하려면 0으로 설정합니다
VERTEX_REGION_CLAUDE_3_5_HAIKUVertex AI를 사용할 때 Claude 3.5 Haiku의 지역 재정의
VERTEX_REGION_CLAUDE_3_7_SONNETVertex AI를 사용할 때 Claude 3.7 Sonnet의 지역 재정의
VERTEX_REGION_CLAUDE_4_0_OPUSVertex AI를 사용할 때 Claude 4.0 Opus의 지역 재정의
VERTEX_REGION_CLAUDE_4_0_SONNETVertex AI를 사용할 때 Claude 4.0 Sonnet의 지역 재정의
VERTEX_REGION_CLAUDE_4_1_OPUSVertex AI를 사용할 때 Claude 4.1 Opus의 지역 재정의

Claude가 사용할 수 있는 도구

Claude Code는 코드베이스를 이해하고 수정하는 데 도움이 되는 강력한 도구 집합에 액세스할 수 있습니다:
도구설명권한 필요
AskUserQuestion요구사항을 수집하거나 모호함을 명확히 하기 위해 객관식 질문을 합니다아니오
Bash환경에서 셸 명령을 실행합니다 (아래의 Bash 도구 동작 참조)
TaskOutput배경 작업 (bash 셸 또는 subagent)의 출력을 검색합니다아니오
Edit특정 파일에 대한 대상 편집을 수행합니다
ExitPlanMode사용자에게 계획 모드를 종료하고 코딩을 시작하도록 프롬프트합니다
Glob패턴 매칭을 기반으로 파일을 찾습니다아니오
Grep파일 내용에서 패턴을 검색합니다아니오
KillShellID로 실행 중인 배경 bash 셸을 종료합니다아니오
MCPSearch도구 검색이 활성화되면 MCP 도구를 검색하고 로드합니다아니오
NotebookEditJupyter 노트북 셀을 수정합니다
Read파일의 내용을 읽습니다아니오
Skill주 대화 내에서 skill을 실행합니다
Task복잡한 다단계 작업을 처리하기 위해 sub-agent를 실행합니다아니오
TaskCreate작업 목록에 새 작업을 만듭니다아니오
TaskGet특정 작업에 대한 전체 세부사항을 검색합니다아니오
TaskList현재 상태와 함께 모든 작업을 나열합니다아니오
TaskUpdate작업 상태, 종속성, 세부사항을 업데이트하거나 작업을 삭제합니다아니오
WebFetch지정된 URL에서 콘텐츠를 가져옵니다
WebSearch도메인 필터링을 사용하여 웹 검색을 수행합니다
Write파일을 만들거나 덮어씁니다
LSP언어 서버를 통한 코드 인텔리전스입니다. 파일 편집 후 유형 오류 및 경고를 자동으로 보고합니다. 또한 탐색 작업을 지원합니다: 정의로 이동, 참조 찾기, 유형 정보 가져오기, 기호 나열, 구현 찾기, 호출 계층 추적. 코드 인텔리전스 플러그인과 해당 언어 서버 바이너리가 필요합니다아니오
권한 규칙은 /allowed-tools를 사용하거나 권한 설정에서 구성할 수 있습니다. 도구별 권한 규칙도 참조하세요.

Bash 도구 동작

Bash 도구는 다음 지속성 동작으로 셸 명령을 실행합니다:
  • 작업 디렉토리 지속: Claude가 작업 디렉토리를 변경하면 (예: cd /path/to/dir), 후속 Bash 명령은 해당 디렉토리에서 실행됩니다. CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1을 사용하여 각 명령 후 프로젝트 디렉토리로 재설정할 수 있습니다.
  • 환경 변수는 지속되지 않음: 한 Bash 명령에서 설정된 환경 변수 (예: export MY_VAR=value)는 후속 Bash 명령에서 사용할 수 없습니다. 각 Bash 명령은 새로운 셸 환경에서 실행됩니다.
Bash 명령에서 환경 변수를 사용 가능하게 하려면 3가지 옵션이 있습니다: 옵션 1: Claude Code를 시작하기 전에 환경 활성화 (가장 간단한 방법) Claude Code를 시작하기 전에 터미널에서 가상 환경을 활성화합니다:
conda activate myenv
# 또는: source /path/to/venv/bin/activate
claude
이는 셸 환경에서 작동하지만 Claude의 Bash 명령 내에서 설정된 환경 변수는 명령 간에 지속되지 않습니다. 옵션 2: Claude Code를 시작하기 전에 CLAUDE_ENV_FILE 설정 (지속적인 환경 설정) 환경 설정을 포함하는 셸 스크립트의 경로를 내보냅니다:
export CLAUDE_ENV_FILE=/path/to/env-setup.sh
claude
여기서 /path/to/env-setup.sh에는:
conda activate myenv
# 또는: source /path/to/venv/bin/activate
# 또는: export MY_VAR=value
Claude Code는 각 Bash 명령 전에 이 파일을 소싱하여 모든 명령에서 환경을 지속적으로 사용할 수 있게 합니다. 옵션 3: SessionStart hook 사용 (프로젝트별 구성) .claude/settings.json에서 구성합니다:
{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""
      }]
    }]
  }
}
hook은 $CLAUDE_ENV_FILE에 쓰며, 이는 각 Bash 명령 전에 소싱됩니다. 이는 팀 공유 프로젝트 구성에 이상적입니다. 옵션 3에 대한 자세한 내용은 SessionStart hooks를 참조하세요.

hooks로 도구 확장

Claude Code hooks를 사용하여 도구가 실행되기 전이나 후에 사용자 정의 명령을 실행할 수 있습니다. 예를 들어 Claude가 Python 파일을 수정한 후 Python 포매터를 자동으로 실행하거나 특정 경로에 대한 Write 작업을 차단하여 프로덕션 구성 파일 수정을 방지할 수 있습니다.

참고 항목

  • 권한: 권한 시스템, 규칙 구문, 도구별 패턴 및 Managed 정책
  • 인증: Claude Code에 대한 사용자 액세스 설정
  • 문제 해결: 일반적인 구성 문제에 대한 해결책