레퍼런스
Claude Code 설정
레퍼런스
Claude Code 설정
전역 및 프로젝트 수준 설정과 환경 변수로 Claude Code를 구성합니다.
Claude Code는 귀하의 요구사항에 맞게 동작을 구성할 수 있는 다양한 설정을 제공합니다. 대화형 REPL을 사용할 때 /config 명령을 실행하여 Claude Code를 구성할 수 있습니다.
설정 파일
settings.json 파일은 계층적 설정을 통해 Claude Code를 구성하는 공식 메커니즘입니다:
- 사용자 설정은
~/.claude/settings.json에 정의되며 모든 프로젝트에 적용됩니다. - 프로젝트 설정은 프로젝트 디렉토리에 저장됩니다:
.claude/settings.json은 소스 제어에 체크인되어 팀과 공유되는 설정용입니다.claude/settings.local.json은 체크인되지 않는 설정으로, 개인 선호도와 실험에 유용합니다. Claude Code는 생성될 때.claude/settings.local.json을 무시하도록 git을 구성합니다.
- Claude Code의 엔터프라이즈 배포의 경우, 엔터프라이즈 관리 정책 설정도 지원합니다. 이는 사용자 및 프로젝트 설정보다 우선합니다. 시스템 관리자는 macOS의
/Library/Application Support/ClaudeCode/managed-settings.json과 Linux 및 WSL을 통한 Windows의/etc/claude-code/managed-settings.json에 정책을 배포할 수 있습니다.
Example settings.json
사용 가능한 설정
settings.json은 여러 옵션을 지원합니다:
| 키 | 설명 | 예시 |
|---|---|---|
apiKeyHelper | 인증 값을 생성하기 위해 /bin/sh에서 실행될 사용자 정의 스크립트입니다. 이 값은 일반적으로 모델 요청에 대해 X-Api-Key, Authorization: Bearer, Proxy-Authorization: Bearer 헤더로 전송됩니다 | /bin/generate_temp_api_key.sh |
cleanupPeriodDays | 채팅 기록을 로컬에 보관할 기간 (기본값: 30일) | 20 |
env | 모든 세션에 적용될 환경 변수 | {"FOO": "bar"} |
includeCoAuthoredBy | git 커밋과 풀 리퀘스트에 co-authored-by Claude 서명을 포함할지 여부 (기본값: true) | false |
permissions | 권한 구조는 아래 표를 참조하세요. |
권한 설정
| 키 | 설명 | 예시 |
|---|---|---|
allow | 도구 사용을 허용하는 권한 규칙 배열 | [ "Bash(git diff:*)" ] |
deny | 도구 사용을 거부하는 권한 규칙 배열 | [ "WebFetch", "Bash(curl:*)" ] |
additionalDirectories | Claude가 액세스할 수 있는 추가 작업 디렉토리 | [ "../docs/" ] |
defaultMode | Claude Code를 열 때의 기본 권한 모드 | "allowEdits" |
disableBypassPermissionsMode | bypassPermissions 모드가 활성화되지 않도록 하려면 "disable"로 설정합니다. 관리 정책 설정 참조 | "disable" |
설정 우선순위
설정은 우선순위 순서로 적용됩니다:
- 엔터프라이즈 정책 (IAM 문서 참조)
- 명령줄 인수
- 로컬 프로젝트 설정
- 공유 프로젝트 설정
- 사용자 설정
환경 변수
Claude Code는 동작을 제어하기 위해 다음 환경 변수를 지원합니다:
모든 환경 변수는 settings.json에서도 구성할 수 있습니다. 이는 각 세션에 대해 환경 변수를 자동으로 설정하거나 전체 팀이나 조직에 환경 변수 세트를 배포하는 유용한 방법입니다.
| 변수 | 목적 |
|---|---|
ANTHROPIC_API_KEY | X-Api-Key 헤더로 전송되는 API 키, 일반적으로 Claude SDK용 (대화형 사용의 경우 /login 실행) |
ANTHROPIC_AUTH_TOKEN | Authorization 및 Proxy-Authorization 헤더의 사용자 정의 값 (여기서 설정한 값 앞에 Bearer 가 붙습니다) |
ANTHROPIC_CUSTOM_HEADERS | 요청에 추가하려는 사용자 정의 헤더 (Name: Value 형식) |
ANTHROPIC_MODEL | 사용할 사용자 정의 모델 이름 (모델 구성 참조) |
ANTHROPIC_SMALL_FAST_MODEL | 백그라운드 작업용 Haiku급 모델 이름 |
BASH_DEFAULT_TIMEOUT_MS | 장시간 실행되는 bash 명령의 기본 타임아웃 |
BASH_MAX_TIMEOUT_MS | 모델이 장시간 실행되는 bash 명령에 설정할 수 있는 최대 타임아웃 |
BASH_MAX_OUTPUT_LENGTH | bash 출력이 중간 잘림되기 전의 최대 문자 수 |
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR | 각 Bash 명령 후 원래 작업 디렉토리로 돌아가기 |
CLAUDE_CODE_API_KEY_HELPER_TTL_MS | 자격 증명을 새로 고쳐야 하는 간격(밀리초) (apiKeyHelper 사용 시) |
CLAUDE_CODE_MAX_OUTPUT_TOKENS | 대부분의 요청에 대한 최대 출력 토큰 수 설정 |
CLAUDE_CODE_USE_BEDROCK | Bedrock 사용 (Bedrock & Vertex 참조) |
CLAUDE_CODE_USE_VERTEX | Vertex 사용 (Bedrock & Vertex 참조) |
CLAUDE_CODE_SKIP_BEDROCK_AUTH | Bedrock에 대한 AWS 인증 건너뛰기 (예: LLM 게이트웨이 사용 시) |
CLAUDE_CODE_SKIP_VERTEX_AUTH | Vertex에 대한 Google 인증 건너뛰기 (예: LLM 게이트웨이 사용 시) |
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | DISABLE_AUTOUPDATER, DISABLE_BUG_COMMAND, DISABLE_ERROR_REPORTING, DISABLE_TELEMETRY 설정과 동일 |
DISABLE_AUTOUPDATER | 자동 업데이터를 비활성화하려면 1로 설정 |
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_THINKING_TOKENS | 모델 예산에 대한 사고 강제 |
MCP_TIMEOUT | MCP 서버 시작에 대한 타임아웃(밀리초) |
MCP_TOOL_TIMEOUT | MCP 도구 실행에 대한 타임아웃(밀리초) |
MAX_MCP_OUTPUT_TOKENS | MCP 도구 응답에서 허용되는 최대 토큰 수 (기본값: 25000) |
구성 옵션
전역 구성을 settings.json으로 마이그레이션하는 과정에 있습니다.
claude config는 settings.json을 위해 더 이상 사용되지 않을 예정입니다
구성을 관리하려면 다음 명령을 사용하세요:
- 설정 목록:
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 | 자동 업데이트 활성화 여부 (기본값: true) | 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는 코드베이스를 이해하고 수정하는 데 도움이 되는 강력한 도구 세트에 액세스할 수 있습니다:
| 도구 | 설명 | 필요한 권한 |
|---|---|---|
| Agent | 복잡한 다단계 작업을 처리하기 위해 하위 에이전트를 실행 | 아니오 |
| Bash | 환경에서 셸 명령을 실행 | 예 |
| Edit | 특정 파일에 대상 편집을 수행 | 예 |
| Glob | 패턴 매칭을 기반으로 파일을 찾기 | 아니오 |
| Grep | 파일 내용에서 패턴 검색 | 아니오 |
| LS | 파일과 디렉토리 나열 | 아니오 |
| MultiEdit | 단일 파일에서 여러 편집을 원자적으로 수행 | 예 |
| NotebookEdit | Jupyter 노트북 셀 수정 | 예 |
| NotebookRead | Jupyter 노트북 내용 읽기 및 표시 | 아니오 |
| Read | 파일 내용 읽기 | 아니오 |
| TodoRead | 현재 세션의 작업 목록 읽기 | 아니오 |
| TodoWrite | 구조화된 작업 목록 생성 및 관리 | 아니오 |
| WebFetch | 지정된 URL에서 콘텐츠 가져오기 | 예 |
| WebSearch | 도메인 필터링으로 웹 검색 수행 | 예 |
| Write | 파일 생성 또는 덮어쓰기 | 예 |
권한 규칙은 /allowed-tools를 사용하거나 권한 설정에서 구성할 수 있습니다.
훅으로 도구 확장
Claude Code 훅을 사용하여 도구가 실행되기 전이나 후에 사용자 정의 명령을 실행할 수 있습니다.
예를 들어, Claude가 Python 파일을 수정한 후 자동으로 Python 포매터를 실행하거나, 특정 경로에 대한 Write 작업을 차단하여 프로덕션 구성 파일의 수정을 방지할 수 있습니다.
참고 항목
- 신원 및 액세스 관리 - Claude Code의 권한 시스템에 대해 알아보기
- IAM 및 액세스 제어 - 엔터프라이즈 정책 관리
- 문제 해결 - 일반적인 구성 문제에 대한 해결책