Claude Code 설정

Claude Code는 귀하의 요구사항에 맞게 동작을 구성할 수 있는 다양한 설정을 제공합니다. 대화형 REPL을 사용할 때 /config 명령을 실행하여 Claude Code를 구성할 수 있습니다.

설정 파일

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

사용자 설정은 ~/.claude/settings.json에 정의되며 모든 프로젝트에 적용됩니다.
프로젝트 설정은 프로젝트 디렉토리에 저장됩니다:
- .claude/settings.json은 소스 제어에 체크인되어 팀과 공유되는 설정용
- .claude/settings.local.json은 체크인되지 않는 설정으로, 개인 선호도와 실험에 유용합니다. Claude Code는 생성될 때 git이 .claude/settings.local.json을 무시하도록 구성합니다.
Claude Code의 엔터프라이즈 배포의 경우, 엔터프라이즈 관리 정책 설정도 지원합니다. 이는 사용자 및 프로젝트 설정보다 우선합니다. 시스템 관리자는 다음 위치에 정책을 배포할 수 있습니다:
- macOS: /Library/Application Support/ClaudeCode/managed-settings.json
- Linux 및 WSL: /etc/claude-code/managed-settings.json
- Windows: C:\ProgramData\ClaudeCode\managed-settings.json

예시 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"
  }
}

사용 가능한 설정

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

키	설명	예시
`apiKeyHelper`	인증 값을 생성하기 위해 `/bin/sh`에서 실행될 사용자 정의 스크립트. 이 값은 모델 요청에 대해 `X-Api-Key` 및 `Authorization: Bearer` 헤더로 전송됩니다	`/bin/generate_temp_api_key.sh`
`cleanupPeriodDays`	마지막 활동 날짜를 기준으로 채팅 기록을 로컬에 보관할 기간 (기본값: 30일)	`20`
`env`	모든 세션에 적용될 환경 변수	`{"FOO": "bar"}`
`includeCoAuthoredBy`	git 커밋과 풀 리퀘스트에 `co-authored-by Claude` 서명을 포함할지 여부 (기본값: `true`)	`false`
`permissions`	권한 구조는 아래 표를 참조하세요.
`hooks`	도구 실행 전후에 실행할 사용자 정의 명령을 구성합니다. hooks 문서 참조	`{"PreToolUse": {"Bash": "echo 'Running command...'"}}`
`disableAllHooks`	모든 hooks 비활성화	`true`
`model`	Claude Code에 사용할 기본 모델 재정의	`"claude-3-5-sonnet-20241022"`
`statusLine`	컨텍스트를 표시할 사용자 정의 상태 라인 구성. statusLine 문서 참조	`{"type": "command", "command": "~/.claude/statusline.sh"}`
`outputStyle`	시스템 프롬프트를 조정할 출력 스타일 구성. 출력 스타일 문서 참조	`"Explanatory"`
`forceLoginMethod`	Claude.ai 계정으로 로그인을 제한하려면 `claudeai`, Anthropic Console (API 사용량 청구) 계정으로 제한하려면 `console` 사용	`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"]`
`awsAuthRefresh`	`.aws` 디렉토리를 수정하는 사용자 정의 스크립트 (고급 자격 증명 구성 참조)	`aws sso login --profile myprofile`
`awsCredentialExport`	AWS 자격 증명이 포함된 JSON을 출력하는 사용자 정의 스크립트 (고급 자격 증명 구성 참조)	`/bin/generate_aws_grant.sh`

권한 설정

키	설명	예시
`allow`	도구 사용을 허용할 권한 규칙 배열. 참고: Bash 규칙은 정규식이 아닌 접두사 매칭을 사용합니다	`[ "Bash(git diff:*)" ]`
`ask`	도구 사용 시 확인을 요청할 권한 규칙 배열.	`[ "Bash(git push:*)" ]`
`deny`	도구 사용을 거부할 권한 규칙 배열. Claude Code 액세스에서 민감한 파일을 제외하는 데도 사용합니다. 참고: Bash 패턴은 접두사 매치이며 우회될 수 있습니다 (Bash 권한 제한사항 참조)	`[ "WebFetch", "Bash(curl:)", "Read(./.env)", "Read(./secrets/*)" ]`
`additionalDirectories`	Claude가 액세스할 수 있는 추가 작업 디렉토리	`[ "../docs/" ]`
`defaultMode`	Claude Code를 열 때의 기본 권한 모드	`"acceptEdits"`
`disableBypassPermissionsMode`	`bypassPermissions` 모드가 활성화되지 않도록 하려면 `"disable"`로 설정. 관리 정책 설정 참조	`"disable"`

설정 우선순위

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

엔터프라이즈 관리 정책 (managed-settings.json)
- IT/DevOps에서 배포
- 재정의할 수 없음
명령줄 인수
- 특정 세션에 대한 임시 재정의
로컬 프로젝트 설정 (.claude/settings.local.json)
- 개인 프로젝트별 설정
공유 프로젝트 설정 (.claude/settings.json)
- 소스 제어에서 팀이 공유하는 프로젝트 설정
사용자 설정 (~/.claude/settings.json)
- 개인 전역 설정

이 계층 구조는 엔터프라이즈 보안 정책이 항상 적용되도록 보장하면서도 팀과 개인이 경험을 사용자 정의할 수 있도록 합니다.

구성 시스템의 주요 사항

메모리 파일 (CLAUDE.md): Claude가 시작 시 로드하는 지침과 컨텍스트를 포함
설정 파일 (JSON): 권한, 환경 변수 및 도구 동작을 구성
슬래시 명령: /command-name으로 세션 중에 호출할 수 있는 사용자 정의 명령
MCP 서버: 추가 도구와 통합으로 Claude Code 확장
우선순위: 상위 수준 구성 (엔터프라이즈)이 하위 수준 구성 (사용자/프로젝트)을 재정의
상속: 설정이 병합되며, 더 구체적인 설정이 더 광범위한 설정에 추가되거나 재정의

시스템 프롬프트 가용성

claude.ai와 달리, 이 웹사이트에는 Claude Code의 내부 시스템 프롬프트를 게시하지 않습니다. CLAUDE.md 파일이나 --append-system-prompt를 사용하여 Claude Code의 동작에 사용자 정의 지침을 추가하세요.

민감한 파일 제외

Claude Code가 민감한 정보 (예: API 키, 비밀, 환경 파일)가 포함된 파일에 액세스하지 못하도록 하려면 .claude/settings.json 파일의 permissions.deny 설정을 사용하세요:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

이는 더 이상 사용되지 않는 ignorePatterns 구성을 대체합니다. 이러한 패턴과 일치하는 파일은 Claude Code에서 완전히 보이지 않게 되어 민감한 데이터의 우발적 노출을 방지합니다.

서브에이전트 구성

Claude Code는 사용자 및 프로젝트 수준에서 구성할 수 있는 사용자 정의 AI 서브에이전트를 지원합니다. 이러한 서브에이전트는 YAML 프론트매터가 있는 Markdown 파일로 저장됩니다:

사용자 서브에이전트: ~/.claude/agents/ - 모든 프로젝트에서 사용 가능
프로젝트 서브에이전트: .claude/agents/ - 프로젝트별로 특정하며 팀과 공유 가능

서브에이전트 파일은 사용자 정의 프롬프트와 도구 권한을 가진 전문 AI 어시스턴트를 정의합니다. 서브에이전트 생성 및 사용에 대한 자세한 내용은 서브에이전트 문서를 참조하세요.

환경 변수

Claude Code는 동작을 제어하기 위해 다음 환경 변수를 지원합니다:

모든 환경 변수는 settings.json에서도 구성할 수 있습니다. 이는 각 세션에 대해 환경 변수를 자동으로 설정하거나 전체 팀이나 조직에 환경 변수 세트를 배포하는 유용한 방법입니다.

변수	목적
`ANTHROPIC_API_KEY`	`X-Api-Key` 헤더로 전송되는 API 키, 일반적으로 Claude SDK용 (대화형 사용의 경우 `/login` 실행)
`ANTHROPIC_AUTH_TOKEN`	`Authorization` 헤더의 사용자 정의 값 (여기서 설정한 값은 `Bearer` 접두사가 붙습니다)
`ANTHROPIC_CUSTOM_HEADERS`	요청에 추가하려는 사용자 정의 헤더 (`Name: Value` 형식)
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	모델 구성 참조
`ANTHROPIC_DEFAULT_OPUS_MODEL`	모델 구성 참조
`ANTHROPIC_DEFAULT_SONNET_MODEL`	모델 구성 참조
`ANTHROPIC_MODEL`	사용할 모델 설정 이름 (모델 구성 참조)
`ANTHROPIC_SMALL_FAST_MODEL`	[더 이상 사용되지 않음] 백그라운드 작업용 Haiku급 모델 이름
`ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION`	Bedrock 사용 시 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_BASH_MAINTAIN_PROJECT_WORKING_DIR`	각 Bash 명령 후 원래 작업 디렉토리로 돌아가기
`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`	자격 증명을 새로 고쳐야 하는 간격(밀리초) (`apiKeyHelper` 사용 시)
`CLAUDE_CODE_CLIENT_CERT`	mTLS 인증용 클라이언트 인증서 파일 경로
`CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`	암호화된 CLAUDE_CODE_CLIENT_KEY의 암호 (선택사항)
`CLAUDE_CODE_CLIENT_KEY`	mTLS 인증용 클라이언트 개인 키 파일 경로
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	`DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, `DISABLE_TELEMETRY` 설정과 동일
`CLAUDE_CODE_DISABLE_TERMINAL_TITLE`	대화 컨텍스트를 기반으로 한 자동 터미널 제목 업데이트를 비활성화하려면 `1`로 설정
`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`	IDE 확장의 자동 설치 건너뛰기
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	대부분의 요청에 대한 최대 출력 토큰 수 설정
`CLAUDE_CODE_SKIP_BEDROCK_AUTH`	Bedrock에 대한 AWS 인증 건너뛰기 (예: LLM 게이트웨이 사용 시)
`CLAUDE_CODE_SKIP_VERTEX_AUTH`	Vertex에 대한 Google 인증 건너뛰기 (예: LLM 게이트웨이 사용 시)
`CLAUDE_CODE_SUBAGENT_MODEL`	모델 구성 참조
`CLAUDE_CODE_USE_BEDROCK`	Bedrock 사용
`CLAUDE_CODE_USE_VERTEX`	Vertex 사용
`DISABLE_AUTOUPDATER`	자동 업데이트를 비활성화하려면 `1`로 설정. 이는 `autoUpdates` 구성 설정보다 우선합니다.
`DISABLE_BUG_COMMAND`	`/bug` 명령을 비활성화하려면 `1`로 설정
`DISABLE_COST_WARNINGS`	비용 경고 메시지를 비활성화하려면 `1`로 설정
`DISABLE_ERROR_REPORTING`	Sentry 오류 보고를 거부하려면 `1`로 설정
`DISABLE_NON_ESSENTIAL_MODEL_CALLS`	플레이버 텍스트와 같은 중요하지 않은 경로에 대한 모델 호출을 비활성화하려면 `1`로 설정
`DISABLE_TELEMETRY`	Statsig 텔레메트리를 거부하려면 `1`로 설정 (Statsig 이벤트에는 코드, 파일 경로 또는 bash 명령과 같은 사용자 데이터가 포함되지 않음)
`HTTP_PROXY`	네트워크 연결용 HTTP 프록시 서버 지정
`HTTPS_PROXY`	네트워크 연결용 HTTPS 프록시 서버 지정
`MAX_MCP_OUTPUT_TOKENS`	MCP 도구 응답에서 허용되는 최대 토큰 수. Claude Code는 출력이 10,000 토큰을 초과할 때 경고를 표시합니다 (기본값: 25000)
`MAX_THINKING_TOKENS`	모델 예산에 대한 사고 강제
`MCP_TIMEOUT`	MCP 서버 시작에 대한 타임아웃(밀리초)
`MCP_TOOL_TIMEOUT`	MCP 도구 실행에 대한 타임아웃(밀리초)
`NO_PROXY`	프록시를 우회하여 직접 요청을 발행할 도메인 및 IP 목록
`USE_BUILTIN_RIP GREP`	Claude Code에 포함된 `rg` 대신 시스템에 설치된 `rg`를 사용하려면 `0`으로 설정
`VERTEX_REGION_CLAUDE_3_5_HAIKU`	Vertex AI 사용 시 Claude 3.5 Haiku의 리전 재정의
`VERTEX_REGION_CLAUDE_3_5_SONNET`	Vertex AI 사용 시 Claude Sonnet 3.5의 리전 재정의
`VERTEX_REGION_CLAUDE_3_7_SONNET`	Vertex AI 사용 시 Claude 3.7 Sonnet의 리전 재정의
`VERTEX_REGION_CLAUDE_4_0_OPUS`	Vertex AI 사용 시 Claude 4.0 Opus의 리전 재정의
`VERTEX_REGION_CLAUDE_4_0_SONNET`	Vertex AI 사용 시 Claude 4.0 Sonnet의 리전 재정의
`VERTEX_REGION_CLAUDE_4_1_OPUS`	Vertex AI 사용 시 Claude 4.1 Opus의 리전 재정의

구성 옵션

구성을 관리하려면 다음 명령을 사용하세요:

설정 목록: claude config list
설정 보기: claude config get <key>
설정 변경: claude config set <key> <value>
설정에 추가 (목록용): claude config add <key> <value>
설정에서 제거 (목록용): claude config remove <key> <value>

기본적으로 config는 프로젝트 구성을 변경합니다. 전역 구성을 관리하려면 --global (또는 -g) 플래그를 사용하세요.

전역 구성

전역 구성을 설정하려면 claude config set -g <key> <value>를 사용하세요:

키	설명	예시
`autoUpdates`	더 이상 사용되지 않음. 대신 `DISABLE_AUTOUPDATER` 환경 변수를 사용하세요.	`false`
`preferredNotifChannel`	알림을 받고 싶은 위치 (기본값: `iterm2`)	`iterm2`, `iterm2_with_bell`, `terminal_bell`, 또는 `notifications_disabled`
`theme`	색상 테마	`dark`, `light`, `light-daltonized`, 또는 `dark-daltonized`
`verbose`	전체 bash 및 명령 출력을 표시할지 여부 (기본값: `false`)	`true`

Claude가 사용할 수 있는 도구

Claude Code는 코드베이스를 이해하고 수정하는 데 도움이 되는 강력한 도구 세트에 액세스할 수 있습니다:

도구	설명	권한 필요
Bash	환경에서 셸 명령을 실행합니다	예
Edit	특정 파일에 대상 편집을 수행합니다	예
Glob	패턴 매칭을 기반으로 파일을 찾습니다	아니오
Grep	파일 내용에서 패턴을 검색합니다	아니오
MultiEdit	단일 파일에서 여러 편집을 원자적으로 수행합니다	예
NotebookEdit	Jupyter 노트북 셀을 수정합니다	예
NotebookRead	Jupyter 노트북 내용을 읽고 표시합니다	아니오
Read	파일의 내용을 읽습니다	아니오
Task	복잡한 다단계 작업을 처리하기 위해 서브에이전트를 실행합니다	아니오
TodoWrite	구조화된 작업 목록을 생성하고 관리합니다	아니오
WebFetch	지정된 URL에서 콘텐츠를 가져옵니다	예
WebSearch	도메인 필터링으로 웹 검색을 수행합니다	예
Write	파일을 생성하거나 덮어씁니다	예

권한 규칙은 /allowed-tools를 사용하거나 권한 설정에서 구성할 수 있습니다. 도구별 권한 규칙도 참조하세요.

hooks로 도구 확장

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

참고 항목

신원 및 액세스 관리 - Claude Code의 권한 시스템에 대해 알아보기
IAM 및 액세스 제어 - 엔터프라이즈 정책 관리
문제 해결 - 일반적인 구성 문제에 대한 해결책

시작하기

Claude Code로 구축하기

Claude Code SDK

배포

관리

구성

참조

리소스

Claude Code 설정

설정 파일

사용 가능한 설정

권한 설정

설정 우선순위

구성 시스템의 주요 사항

시스템 프롬프트 가용성

민감한 파일 제외

서브에이전트 구성

환경 변수

구성 옵션

전역 구성

Claude가 사용할 수 있는 도구

hooks로 도구 확장

참고 항목

시작하기

Claude Code로 구축하기

Claude Code SDK

배포

관리

구성

참조

리소스

​설정 파일

​사용 가능한 설정

​권한 설정

​설정 우선순위

​구성 시스템의 주요 사항

​시스템 프롬프트 가용성

​민감한 파일 제외

​서브에이전트 구성

​환경 변수

​구성 옵션

​전역 구성

​Claude가 사용할 수 있는 도구

​hooks로 도구 확장

​참고 항목

설정 파일

사용 가능한 설정

권한 설정

설정 우선순위

구성 시스템의 주요 사항

시스템 프롬프트 가용성

민감한 파일 제외

서브에이전트 구성

환경 변수

구성 옵션

전역 구성

Claude가 사용할 수 있는 도구

hooks로 도구 확장

참고 항목