번역 자료 / / 2025. 5. 28. 19:44

[claude-code 번역] Claude Code 설정 (Claude Code settings)

출처: https://docs.anthropic.com/en/docs/claude-code/settings

Claude Code

Claude Code 설정

글로벌 및 프로젝트별 설정, 테마, 환경 변수 등 Claude Code의 다양한 설정 방법을 알아보세요.

Claude Code는 다양한 설정 옵션을 제공하여 사용자의 필요에 맞게 동작을 조정할 수 있습니다. 터미널에서 claude config를 실행하거나, 대화형 REPL에서는 /config 명령을 사용해 설정할 수 있습니다.

설정 계층 구조

새로운 settings.json 파일은 Claude Code의 계층적 설정을 위한 공식 메커니즘입니다:

  • 사용자 설정: ~/.claude/settings.json에 저장되며 모든 프로젝트에 적용됩니다.
  • 프로젝트 설정: 프로젝트 디렉터리 내 .claude/settings.json(공유 설정)과 .claude/settings.local.json(로컬 설정)에 저장됩니다. .claude/settings.local.json은 git에서 자동으로 무시됩니다.
  • 엔터프라이즈 관리 정책: 엔터프라이즈 배포 환경에서는 /Library/Application Support/ClaudeCode/policies.json(macOS) 또는 /etc/claude-code/policies.json(Linux/Windows/WSL)에 정책 파일을 배포할 수 있습니다. 이 정책은 사용자 및 프로젝트 설정보다 우선 적용됩니다.

settings.json 예시

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

사용 가능한 설정 옵션

settings.json에서 지원하는 주요 옵션:

키 설명 예시
apiKeyHelper Anthropic API 키를 생성하는 커스텀 스크립트 /bin/generate_temp_api_key.sh
cleanupPeriodDays 채팅 기록을 로컬에 보관하는 기간(기본값: 30일) 20
env 모든 세션에 적용할 환경 변수 {"FOO": "bar"}
includeCoAuthoredBy git 커밋/PR에 Claude 공동 작성자 표시 포함 여부(기본값: true) false

설정 우선순위

설정은 다음 순서로 적용됩니다:

  1. 엔터프라이즈 정책
  2. 커맨드라인 인자
  3. 로컬 프로젝트 설정
  4. 공유 프로젝트 설정
  5. 사용자 설정

설정 관리 명령어

Claude Code는 글로벌 및 프로젝트별 설정을 지원합니다.

  • 설정 목록 보기: 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>를 사용하세요:

키 설명 예시
autoUpdaterStatus 자동 업데이트 활성화/비활성화(기본값: 활성) disabled
preferredNotifChannel 알림 수신 채널(기본값: iterm2) iterm2, iterm2_with_bell, terminal_bell, notifications_disabled
theme 색상 테마 dark, light, light-daltonized, dark-daltonized
verbose 전체 bash/명령어 출력 표시 여부(기본값: false) true

글로벌 설정은 점진적으로 settings.json으로 이전되고 있습니다.

권한 관리

/allowed-tools 명령으로 Claude Code의 도구 권한을 관리할 수 있습니다. 이 UI에서는 모든 권한 규칙과 해당 규칙이 적용된 settings.json 파일을 확인할 수 있습니다.

  • Allow 규칙: 지정된 도구를 추가 승인 없이 사용할 수 있습니다.
  • Deny 규칙: 지정된 도구 사용을 차단합니다. Deny 규칙이 Allow보다 우선합니다.

권한 규칙은 Tool(옵션-지정자) 형식을 사용합니다.

예시: WebFetch를 allow 목록에 추가하면 웹 fetch 도구를 승인 없이 사용할 수 있습니다. 일부 도구는 세부 제어를 위한 옵션 지정자를 사용합니다. 예) WebFetch(domain:example.com)은 example.com에만 fetch를 허용합니다.

Bash 규칙은 Bash(npm run build)처럼 정확히 일치하거나, Bash(npm run test:*)처럼 접두사 일치(와일드카드)도 지원합니다.

Read()와 Edit() 규칙은 gitignore 규칙을 따릅니다. 패턴은 .claude/settings.json이 위치한 디렉터리를 기준으로 해석됩니다. 절대 경로는 //, 홈 디렉터리 기준은 ~/를 사용하세요. 예) Read(//tmp/build_cache), Edit(~/.zshrc) 등.

MCP 도구 이름은 mcp__서버명__도구명 형식을 따릅니다.

규칙 설명
Bash(npm run build) 정확히 일치하는 Bash 명령어 허용
Bash(npm run test:*) npm run test로 시작하는 Bash 명령어 허용
Edit(~/.zshrc) ~/.zshrc 파일 편집 허용
Read(node_modules/**) node_modules 디렉터리 내 모든 파일 읽기 허용
mcp__puppeteer__puppeteer_navigate puppeteer MCP 서버의 puppeteer_navigate 도구 허용
WebFetch(domain:example.com) example.com 도메인에 대한 fetch 허용

Claude Code는 명령어 구분자(예: &&)를 인식하므로, 접두사 일치 규칙이 의도치 않은 명령어 실행을 허용하지 않습니다.

자동 업데이트 권한 옵션

글로벌 npm prefix 디렉터리에 쓸 권한이 부족할 경우, 자동 업데이트 관련 경고가 표시됩니다. 자세한 해결 방법은 문제 해결 가이드를 참고하세요.

권장: 사용자 쓰기 권한이 있는 npm prefix 생성

# 기존 글로벌 패키지 목록 저장
npm list -g --depth=0 > ~/npm-global-packages.txt

# 글로벌 패키지용 디렉터리 생성
mkdir -p ~/.npm-global

# npm에 새 경로 지정
npm config set prefix ~/.npm-global

# 환경 변수 적용 (셸에 따라 파일명 변경)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Claude Code 재설치
npm install -g @anthropic-ai/claude-code

# 필요시 기존 패키지 재설치
# npm install -g package1 package2 package3...

이 방법을 권장하는 이유:

  • 시스템 디렉터리 권한 변경 없이 사용 가능
  • 글로벌 npm 패키지 전용 디렉터리로 관리 용이
  • 보안 모범 사례 준수

Claude Code는 활발히 개발 중이므로, 위 방법으로 자동 업데이트를 설정하는 것을 권장합니다.

자동 업데이트 비활성화

권한 문제를 해결하지 않고 자동 업데이트를 끄려면:

claude config set -g autoUpdaterStatus disabled

터미널 환경 최적화

Claude Code는 터미널이 적절히 설정되어 있을 때 최상의 성능을 발휘합니다. 아래 가이드라인을 참고하세요.

지원 셸:

  • Bash
  • Zsh
  • Fish

테마 및 외관

Claude는 터미널 테마를 제어하지 않습니다. 터미널 앱에서 테마를 설정하세요. Claude Code의 테마는 온보딩 또는 /config 명령으로 변경할 수 있습니다.

줄바꿈 입력

여러 줄 입력 방법:

  • 빠른 이스케이프: \ 입력 후 Enter
  • 키보드 단축키: Option+Enter(Meta+Enter) (터미널 설정 필요)

Mac Terminal.app:

  1. 설정 → 프로필 → 키보드 → "Option을 Meta 키로 사용" 체크

iTerm2/VSCode 터미널:

  1. 설정 → 프로필 → 키
  2. General에서 Option 키를 "Esc+"로 설정

팁(iTerm2/VSCode): /terminal-setup 명령으로 Shift+Enter를 줄바꿈 단축키로 자동 설정할 수 있습니다.

알림 설정

작업 완료 시 알림을 받으려면 아래 설정을 참고하세요.

터미널 벨 알림

claude config set --global preferredNotifChannel terminal_bell

macOS: 시스템 설정 → 알림 → 터미널 앱에서 알림 권한을 활성화하세요.

iTerm2 시스템 알림

  1. iTerm2 환경설정 → 프로필 → 터미널
  2. "벨 무음" 활성화 및 알림 필터 설정
  3. 원하는 알림 지연 시간 설정

(iTerm2 전용, 기본 macOS 터미널에서는 지원되지 않음)

대용량 입력 처리

  • 직접 붙여넣기 지양: 매우 긴 내용은 Claude Code가 처리하지 못할 수 있음
  • 파일 기반 워크플로우 권장: 파일로 저장 후 Claude에 읽도록 요청
  • VS Code 터미널 한계 주의: VS Code 터미널은 긴 입력을 잘라낼 수 있음

Vim 모드

Claude Code는 /vim 또는 /config로 Vim 키 바인딩 일부를 지원합니다.

  • 모드 전환: Esc(NORMAL), i/I, a/A, o/O(INSERT)
  • 이동: h/j/k/l, w/e/b, 0/$/^, gg/G
  • 편집: x, dw/de/db/dd/D, cw/ce/cb/cc/C, .(반복)

환경 변수

Claude Code는 다양한 환경 변수로 동작을 제어할 수 있습니다. 모든 환경 변수는 settings.json에서도 설정할 수 있습니다.

변수 목적
ANTHROPIC_AUTH_TOKEN Authorization 및 Proxy-Authorization 헤더에 사용할 값(Bearer 접두사 자동 추가)
ANTHROPIC_CUSTOM_HEADERS 요청에 추가할 커스텀 헤더(Name: Value 형식)
ANTHROPIC_MODEL 사용할 커스텀 모델 이름
ANTHROPIC_SMALL_FAST_MODEL 백그라운드 작업용 Haiku-class 모델 이름
BASH_DEFAULT_TIMEOUT_MS Bash 명령어 기본 타임아웃(ms)
BASH_MAX_TIMEOUT_MS Bash 명령어 최대 타임아웃(ms)
BASH_MAX_OUTPUT_LENGTH Bash 출력 최대 글자 수(중간 생략)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS apiKeyHelper 사용 시 자격 증명 갱신 주기(ms)
CLAUDE_CODE_USE_BEDROCK Bedrock 사용 여부
CLAUDE_CODE_USE_VERTEX Vertex 사용 여부
CLAUDE_CODE_SKIP_VERTEX_AUTH Vertex용 Google 인증 건너뛰기(프록시 사용 시)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC DISABLE_AUTOUPDATER, DISABLE_BUG_COMMAND, DISABLE_ERROR_REPORTING, DISABLE_TELEMETRY와 동일
DISABLE_AUTOUPDATER 1로 설정 시 자동 업데이트 비활성화
DISABLE_BUG_COMMAND 1로 설정 시 /bug 명령 비활성화
DISABLE_COST_WARNINGS 1로 설정 시 비용 경고 메시지 비활성화
DISABLE_ERROR_REPORTING 1로 설정 시 Sentry 오류 보고 비활성화
DISABLE_TELEMETRY 1로 설정 시 Statsig 텔레메트리 비활성화
HTTP_PROXY 네트워크 연결용 HTTP 프록시 서버 지정
HTTPS_PROXY 네트워크 연결용 HTTPS 프록시 서버 지정
MAX_THINKING_TOKENS 모델의 thinking 토큰 예산 강제 설정
MCP_TIMEOUT MCP 서버 시작 타임아웃(ms)
MCP_TOOL_TIMEOUT MCP 도구 실행 타임아웃(ms)
반응형
저작자표시 (새창열림)
  • 네이버 블로그 공유
  • 네이버 밴드 공유
  • 페이스북 공유
  • 카카오스토리 공유
번역 자료 관련 글
글 더보기

티스토리툴바