문제 해결

Claude Code 설치 및 사용 시 발생하는 일반적인 문제에 대한 해결 방법을 안내합니다.

설치 문제 해결

팁:

터미널을 완전히 건너뛰고 싶다면, Claude Code Desktop 앱을 사용하여 그래픽 인터페이스로 Claude Code를 설치하고 사용할 수 있습니다. macOS 또는 Windows용으로 다운로드하여 명령줄 설정 없이 코딩을 시작하세요.

표시되는 오류 메시지나 증상을 찾아보세요:

표시되는 내용	해결 방법
`command not found: claude` 또는 `'claude' is not recognized`	PATH 수정
`syntax error near unexpected token '<'`	설치 스크립트가 HTML을 반환함
`curl: (56) Failure writing output to destination`	스크립트를 먼저 다운로드한 후 실행
`Killed` (Linux 설치 중)	저메모리 서버에 swap 공간 추가
`TLS connect error` 또는 `SSL/TLS secure channel`	CA 인증서 업데이트
`Failed to fetch version` 또는 다운로드 서버 접속 불가	네트워크 및 프록시 설정 확인
`irm is not recognized` 또는 `&& is not valid`	올바른 셸 명령어 사용
`Claude Code on Windows requires git-bash`	Git Bash 설치 또는 설정
`Error loading shared library`	시스템에 맞지 않는 바이너리 변형 설치됨
`Illegal instruction` (Linux)	아키텍처 불일치
`dyld: cannot load` 또는 `Abort trap` (macOS)	바이너리 비호환
`Invoke-Expression: Missing argument in parameter list`	설치 스크립트가 HTML을 반환함
`App unavailable in region`	해당 국가에서 Claude Code를 사용할 수 없습니다. 지원 국가를 확인하세요.
`unable to get local issuer certificate`	기업 CA 인증서 설정
`OAuth error` 또는 `403 Forbidden`	인증 문제 해결

목록에 해당하는 문제가 없다면 아래 진단 단계를 따라가세요.

설치 문제 디버그

네트워크 연결 확인

설치 프로그램은 storage.googleapis.com에서 다운로드합니다. 접속 가능 여부를 확인하세요:

curl -sI https://storage.googleapis.com

실패하면 네트워크가 연결을 차단하고 있을 수 있습니다. 일반적인 원인:

기업 방화벽 또는 프록시가 Google Cloud Storage를 차단
지역 네트워크 제한: VPN 또는 다른 네트워크를 시도하세요
TLS/SSL 문제: 시스템의 CA 인증서를 업데이트하거나 HTTPS_PROXY가 설정되어 있는지 확인하세요

기업 프록시 뒤에 있다면 설치 전에 HTTPS_PROXY와 HTTP_PROXY를 프록시 주소로 설정하세요. 프록시 URL을 모른다면 IT 팀에 문의하거나 브라우저의 프록시 설정을 확인하세요.

다음 예시는 두 프록시 변수를 설정한 후 프록시를 통해 설치 프로그램을 실행합니다:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

PATH 확인

설치는 성공했지만 claude 실행 시 command not found 또는 not recognized 오류가 발생하면 설치 디렉토리가 PATH에 포함되어 있지 않은 것입니다. 셸은 PATH에 나열된 디렉토리에서 프로그램을 검색하며, 설치 프로그램은 macOS/Linux에서 ~/.local/bin/claude, Windows에서 %USERPROFILE%\.local\bin\claude.exe에 claude를 설치합니다.

PATH 항목을 나열하고 local/bin을 필터링하여 설치 디렉토리가 PATH에 있는지 확인하세요:

macOS/Linux

echo $PATH | tr ':' '\n' | grep local/bin

출력이 없으면 디렉토리가 누락된 것입니다. 셸 설정에 추가하세요:

# Zsh (macOS 기본)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Bash (Linux 기본)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

또는 터미널을 닫고 다시 여세요.

수정이 적용되었는지 확인하세요:

claude --version

Windows PowerShell

$env:PATH -split ';' | Select-String 'local\\bin'

출력이 없으면 설치 디렉토리를 사용자 PATH에 추가하세요:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

변경 사항이 적용되도록 터미널을 재시작하세요.

수정이 적용되었는지 확인하세요:

claude --version

Windows CMD

echo %PATH% | findstr /i "local\bin"

출력이 없으면 시스템 설정을 열고 환경 변수로 이동하여 사용자 PATH 변수에 %USERPROFILE%\.local\bin을 추가하세요. 터미널을 재시작하세요.

수정이 적용되었는지 확인하세요:

claude --version

충돌하는 설치 확인

여러 Claude Code 설치가 있으면 버전 불일치나 예기치 않은 동작이 발생할 수 있습니다. 설치된 항목을 확인하세요:

macOS/Linux

PATH에서 발견된 모든 claude 바이너리를 나열하세요:

which -a claude

네이티브 설치 프로그램과 npm 버전이 있는지 확인하세요:

ls -la ~/.local/bin/claude

ls -la ~/.claude/local/

npm -g ls @anthropic-ai/claude-code 2>/dev/null

Windows PowerShell

where.exe claude
Test-Path "$env:LOCALAPPDATA\Claude Code\claude.exe"

여러 설치가 발견되면 하나만 유지하세요. ~/.local/bin/claude의 네이티브 설치를 권장합니다. 추가 설치를 제거하세요:

npm 글로벌 설치 제거:

npm uninstall -g @anthropic-ai/claude-code

macOS에서 Homebrew 설치 제거:

brew uninstall --cask claude-code

디렉토리 권한 확인

설치 프로그램은 ~/.local/bin/과 ~/.claude/에 대한 쓰기 권한이 필요합니다. 권한 오류로 설치가 실패하면 이 디렉토리가 쓰기 가능한지 확인하세요:

test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

어느 디렉토리든 쓰기 불가능하면 설치 디렉토리를 만들고 사용자를 소유자로 설정하세요:

sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

바이너리 작동 확인

claude가 설치되었지만 시작 시 충돌하거나 멈추면 원인을 좁히기 위해 다음 검사를 실행하세요.

바이너리가 존재하고 실행 가능한지 확인하세요:

ls -la $(which claude)

Linux에서 누락된 공유 라이브러리를 확인하세요. ldd에서 누락된 라이브러리가 표시되면 시스템 패키지를 설치해야 할 수 있습니다. Alpine Linux 및 기타 musl 기반 배포판은 Alpine Linux 설정을 참고하세요.

ldd $(which claude) | grep "not found"

바이너리가 실행 가능한지 빠르게 확인하세요:

claude --version

일반적인 설치 문제

가장 자주 발생하는 설치 문제와 해결 방법입니다.

설치 스크립트가 셸 스크립트 대신 HTML을 반환함

설치 명령 실행 시 다음과 같은 오류가 발생할 수 있습니다:

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

PowerShell에서는 동일한 문제가 다음과 같이 나타납니다:

Invoke-Expression: Missing argument in parameter list.

이는 설치 URL이 설치 스크립트 대신 HTML 페이지를 반환했음을 의미합니다. HTML 페이지에 "App unavailable in region"이라고 표시되면 해당 국가에서 Claude Code를 사용할 수 없습니다. 지원 국가를 확인하세요.

그렇지 않으면 네트워크 문제, 지역 라우팅 또는 일시적인 서비스 장애로 인해 발생할 수 있습니다.

해결 방법:

대안 설치 방법 사용:

macOS 또는 Linux에서 Homebrew로 설치:
```
brew install --cask claude-code
```
Windows에서 WinGet으로 설치:
```
winget install Anthropic.ClaudeCode
```
몇 분 후 재시도: 이 문제는 일시적인 경우가 많습니다. 잠시 기다린 후 원래 명령을 다시 시도하세요.

설치 후 `command not found: claude`

설치는 완료되었지만 claude가 작동하지 않습니다. 정확한 오류는 플랫폼에 따라 다릅니다:

플랫폼	오류 메시지
macOS	`zsh: command not found: claude`
Linux	`bash: claude: command not found`
Windows CMD	`'claude' is not recognized as an internal or external command`
PowerShell	`claude : The term 'claude' is not recognized as the name of a cmdlet`

이는 설치 디렉토리가 셸의 검색 경로에 포함되어 있지 않음을 의미합니다. 각 플랫폼별 수정 방법은 PATH 확인을 참고하세요.

`curl: (56) Failure writing output to destination`

curl ... | bash 명령은 스크립트를 다운로드하고 파이프(|)를 사용하여 Bash로 직접 전달하여 실행합니다. 이 오류는 스크립트 다운로드가 완료되기 전에 연결이 끊어졌음을 의미합니다. 일반적인 원인으로는 네트워크 중단, 다운로드 차단 또는 시스템 리소스 제한이 있습니다.

해결 방법:

네트워크 안정성 확인: Claude Code 바이너리는 Google Cloud Storage에 호스팅됩니다. 접속 가능한지 테스트하세요:
```
curl -fsSL https://storage.googleapis.com -o /dev/null
```
명령이 조용히 완료되면 연결이 정상이며 문제가 간헐적일 가능성이 높습니다. 설치 명령을 재시도하세요. 오류가 발생하면 네트워크가 다운로드를 차단하고 있을 수 있습니다.

대안 설치 방법 사용:

macOS 또는 Linux:

brew install --cask claude-code

Windows:

winget install Anthropic.ClaudeCode

TLS 또는 SSL 연결 오류

curl: (35) TLS connect error, schannel: next InitializeSecurityContext failed 또는 PowerShell의 Could not establish trust relationship for the SSL/TLS secure channel과 같은 오류는 TLS 핸드셰이크 실패를 나타냅니다.

해결 방법:

시스템 CA 인증서 업데이트:

Ubuntu/Debian:

sudo apt-get update && sudo apt-get install ca-certificates

macOS (Homebrew):

brew install ca-certificates

Windows에서 TLS 1.2 활성화 - 설치 프로그램 실행 전 PowerShell에서:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

프록시 또는 방화벽 간섭 확인: TLS 검사를 수행하는 기업 프록시는 unable to get local issuer certificate를 포함한 이러한 오류를 유발할 수 있습니다. NODE_EXTRA_CA_CERTS를 기업 CA 인증서 번들로 설정하세요:
```
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
```
인증서 파일이 없다면 IT 팀에 문의하세요. 직접 연결로 시도하여 프록시가 원인인지 확인할 수도 있습니다.

`Failed to fetch version from storage.googleapis.com`

설치 프로그램이 다운로드 서버에 접속할 수 없습니다. 이는 일반적으로 네트워크에서 storage.googleapis.com이 차단되어 있음을 의미합니다.

해결 방법:

직접 연결 테스트:

curl -sI https://storage.googleapis.com

프록시 뒤에 있다면 HTTPS_PROXY를 설정하여 설치 프로그램이 프록시를 통해 라우팅되도록 하세요. 자세한 내용은 프록시 설정을 참고하세요.
```
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash
```
제한된 네트워크에서는 다른 네트워크 또는 VPN을 사용하거나 대안 설치 방법을 시도하세요:

macOS 또는 Linux:
```
brew install --cask claude-code
```
Windows:
```
winget install Anthropic.ClaudeCode
```

Windows: `irm` 또는 `&&` 인식 불가

'irm' is not recognized 또는 The token '&&' is not valid 오류가 발생하면 현재 셸에 맞지 않는 명령을 실행하고 있는 것입니다.

irm 인식 불가: PowerShell이 아닌 CMD에서 실행 중입니다. 두 가지 옵션이 있습니다:

시작 메뉴에서 "PowerShell"을 검색하여 PowerShell을 열고 원래 설치 명령을 실행하세요:
```
irm https://claude.ai/install.ps1 | iex
```
또는 CMD에서 CMD 설치 프로그램을 사용하세요:
```
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```
&& 유효하지 않음: PowerShell에서 CMD 설치 명령을 실행한 것입니다. PowerShell 설치 프로그램을 사용하세요:
```
irm https://claude.ai/install.ps1 | iex
```

저메모리 Linux 서버에서 설치 중 종료됨

VPS 또는 클라우드 인스턴스에서 설치 중 Killed가 표시되는 경우:

Setting up Claude Code...
Installing Claude Code native build latest...
bash: line 142: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}

시스템 메모리가 부족하여 Linux OOM killer가 프로세스를 종료한 것입니다. Claude Code는 최소 4 GB의 가용 RAM이 필요합니다.

해결 방법:

swap 공간 추가 - 서버의 RAM이 제한적인 경우. swap은 디스크 공간을 오버플로 메모리로 사용하여 물리적 RAM이 부족해도 설치를 완료할 수 있게 합니다.

2 GB swap 파일을 생성하고 활성화하세요:
```
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
```
그런 다음 설치를 재시도하세요:
```
curl -fsSL https://claude.ai/install.sh | bash
```
다른 프로세스 종료 - 설치 전에 메모리를 확보하세요.
더 큰 인스턴스 사용 - 가능하다면. Claude Code는 최소 4 GB RAM이 필요합니다.

Docker에서 설치 멈춤

Docker 컨테이너에서 Claude Code를 설치할 때 root로 /에 설치하면 멈출 수 있습니다.

해결 방법:

설치 프로그램 실행 전 작업 디렉토리 설정. /에서 실행하면 설치 프로그램이 전체 파일시스템을 스캔하여 과도한 메모리 사용을 유발합니다. WORKDIR를 설정하면 스캔을 작은 디렉토리로 제한합니다:
```
WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash
```
Docker 메모리 제한 증가 - Docker Desktop을 사용하는 경우:
```
docker build --memory=4g .
```

Windows: Claude Desktop이 `claude` CLI 명령을 덮어씀

이전 버전의 Claude Desktop을 설치한 경우, WindowsApps 디렉토리에 Claude.exe가 등록되어 Claude Code CLI보다 PATH 우선순위가 높을 수 있습니다. claude를 실행하면 CLI 대신 Desktop 앱이 열립니다.

이 문제를 해결하려면 Claude Desktop을 최신 버전으로 업데이트하세요.

Windows: "Claude Code on Windows requires git-bash"

네이티브 Windows에서 Claude Code를 사용하려면 Git Bash가 포함된 Git for Windows가 필요합니다.

Git이 설치되지 않은 경우 git-scm.com/downloads/win에서 다운로드하여 설치하세요. 설정 중 "Add to PATH"를 선택하세요. 설치 후 터미널을 재시작하세요.

Git이 이미 설치되어 있지만 Claude Code가 여전히 찾지 못하는 경우, settings.json 파일에서 경로를 설정하세요:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Git이 다른 곳에 설치되어 있다면 PowerShell에서 where.exe git을 실행하여 경로를 찾고 해당 디렉토리의 bin\bash.exe 경로를 사용하세요.

Linux: 잘못된 바이너리 변형 설치됨 (musl/glibc 불일치)

설치 후 libstdc++.so.6 또는 libgcc_s.so.1과 같은 공유 라이브러리 누락 오류가 발생하면 설치 프로그램이 시스템에 맞지 않는 바이너리 변형을 다운로드했을 수 있습니다.

Error loading shared library libstdc++.so.6: No such file or directory

musl 크로스 컴파일 패키지가 설치된 glibc 기반 시스템에서 설치 프로그램이 시스템을 musl로 잘못 감지하는 경우 발생할 수 있습니다.

해결 방법:

시스템이 사용하는 libc 확인:
```
ldd /bin/ls | head -1
```
linux-vdso.so 또는 /lib/x86_64-linux-gnu/에 대한 참조가 표시되면 glibc입니다. musl이 표시되면 musl입니다.
glibc인데 musl 바이너리를 받은 경우, 설치를 제거하고 재설치하세요. https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json의 GCS 버킷에서 올바른 바이너리를 수동으로 다운로드할 수도 있습니다. ldd /bin/ls와 ls /lib/libc.musl*의 출력과 함께 GitHub 이슈를 제출하세요.
실제로 musl인 경우 (Alpine Linux), 필요한 패키지를 설치하세요:
```
apk add libgcc libstdc++ ripgrep
```

Linux에서 `Illegal instruction`

설치 프로그램이 OOM Killed 메시지 대신 Illegal instruction을 출력하면 다운로드된 바이너리가 CPU 아키텍처와 일치하지 않는 것입니다. 이는 x86 바이너리를 받은 ARM 서버나 필요한 명령어 세트가 없는 구형 CPU에서 흔히 발생합니다.

bash: line 142: 2238232 Illegal instruction    "$binary_path" install ${TARGET:+"$TARGET"}

해결 방법:

아키텍처 확인:
```
uname -m
```
x86_64는 64비트 Intel/AMD, aarch64는 ARM64를 의미합니다. 바이너리가 일치하지 않으면 출력과 함께 GitHub 이슈를 제출하세요.
아키텍처 문제가 해결되는 동안 대안 설치 방법 시도:
```
brew install --cask claude-code
```

macOS에서 `dyld: cannot load`

설치 중 dyld: cannot load 또는 Abort trap: 6이 표시되면 바이너리가 macOS 버전 또는 하드웨어와 호환되지 않는 것입니다.

dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
Abort trap: 6

해결 방법:

macOS 버전 확인: Claude Code는 macOS 13.0 이상이 필요합니다. Apple 메뉴를 열고 "이 Mac에 관하여"를 선택하여 버전을 확인하세요.
macOS 업데이트 - 이전 버전을 사용하고 있다면. 바이너리가 이전 macOS 버전에서 지원하지 않는 로드 명령을 사용합니다.
대안 설치 방법으로 Homebrew 시도:
```
brew install --cask claude-code
```

Windows 설치 문제: WSL 오류

WSL에서 다음과 같은 문제가 발생할 수 있습니다:

OS/플랫폼 감지 문제: 설치 중 오류가 발생하면 WSL이 Windows npm을 사용하고 있을 수 있습니다. 다음을 시도하세요:

설치 전에 npm config set os linux 실행
npm install -g @anthropic-ai/claude-code --force --no-os-check로 설치. sudo를 사용하지 마세요.

Node를 찾을 수 없는 오류: claude 실행 시 exec: node: not found가 표시되면 WSL 환경이 Windows에 설치된 Node.js를 사용하고 있을 수 있습니다. which npm과 which node로 확인할 수 있으며, /mnt/c/가 아닌 /usr/로 시작하는 Linux 경로를 가리켜야 합니다. 이를 해결하려면 Linux 배포판의 패키지 관리자 또는 nvm을 통해 Node를 설치해 보세요.

nvm 버전 충돌: WSL과 Windows 모두에 nvm이 설치되어 있으면 WSL에서 Node 버전을 전환할 때 버전 충돌이 발생할 수 있습니다. 이는 WSL이 기본적으로 Windows PATH를 가져오기 때문에 Windows nvm/npm이 WSL 설치보다 우선순위가 높아지기 때문입니다.

이 문제를 식별하는 방법:

which npm과 which node 실행 - Windows 경로(/mnt/c/로 시작)를 가리키면 Windows 버전이 사용되고 있는 것입니다
WSL에서 nvm으로 Node 버전 전환 후 기능이 비정상적으로 작동

이 문제를 해결하려면 Linux node/npm 버전이 우선순위를 갖도록 Linux PATH를 수정하세요:

주요 해결 방법: nvm이 셸에 올바르게 로드되었는지 확인

가장 흔한 원인은 비대화형 셸에서 nvm이 로드되지 않는 것입니다. 셸 설정 파일(~/.bashrc, ~/.zshrc 등)에 다음을 추가하세요:

# nvm이 존재하면 로드
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

또는 현재 세션에서 직접 실행하세요:

source ~/.nvm/nvm.sh

대안: PATH 순서 조정

nvm이 올바르게 로드되었지만 Windows 경로가 여전히 우선순위를 가지면 셸 설정에서 Linux 경로를 PATH 앞에 명시적으로 추가할 수 있습니다:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

주의:

appendWindowsPath = false를 통해 Windows PATH 가져오기를 비활성화하면 WSL에서 Windows 실행 파일을 호출하는 기능이 손상되므로 피하세요. 마찬가지로 Windows 개발에 Node.js를 사용하는 경우 Windows에서 Node.js를 제거하지 마세요.

WSL2 샌드박스 설정

샌드박싱은 WSL2에서 지원되지만 추가 패키지 설치가 필요합니다. /sandbox 실행 시 "Sandbox requires socat and bubblewrap" 오류가 표시되면 의존성을 설치하세요:

Ubuntu/Debian

sudo apt-get install bubblewrap socat

Fedora

sudo dnf install bubblewrap socat

WSL1은 샌드박싱을 지원하지 않습니다. "Sandboxing requires WSL2"가 표시되면 WSL2로 업그레이드하거나 샌드박싱 없이 Claude Code를 실행해야 합니다.

설치 중 권한 오류

네이티브 설치 프로그램이 권한 오류로 실패하면 대상 디렉토리가 쓰기 불가능할 수 있습니다. 디렉토리 권한 확인을 참고하세요.

이전에 npm으로 설치하고 npm 관련 권한 오류가 발생하는 경우 네이티브 설치 프로그램으로 전환하세요:

curl -fsSL https://claude.ai/install.sh | bash

권한 및 인증

로그인 실패, 토큰 문제, 권한 프롬프트 동작에 대한 내용을 다룹니다.

반복되는 권한 프롬프트

동일한 명령을 반복적으로 승인하고 있다면 /permissions 명령을 사용하여 특정 도구가 승인 없이 실행되도록 허용할 수 있습니다. 권한 문서를 참고하세요.

인증 문제

인증 문제가 발생하는 경우:

/logout을 실행하여 완전히 로그아웃하세요
Claude Code를 종료하세요
claude로 재시작하고 인증 과정을 다시 완료하세요

로그인 중 브라우저가 자동으로 열리지 않으면 c를 눌러 OAuth URL을 클립보드에 복사한 후 브라우저에 수동으로 붙여넣으세요.

OAuth 오류: Invalid code

OAuth error: Invalid code. Please make sure the full code was copied가 표시되면 로그인 코드가 만료되었거나 복사-붙여넣기 중 잘렸습니다.

해결 방법:

Enter를 눌러 재시도하고 브라우저가 열린 후 빠르게 로그인을 완료하세요
브라우저가 자동으로 열리지 않으면 c를 입력하여 전체 URL을 복사하세요
원격/SSH 세션을 사용하는 경우 브라우저가 잘못된 머신에서 열릴 수 있습니다. 터미널에 표시된 URL을 복사하여 로컬 브라우저에서 대신 여세요.

로그인 후 403 Forbidden

로그인 후 API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}가 표시되는 경우:

Claude Pro/Max 사용자: claude.ai/settings에서 구독이 활성 상태인지 확인하세요
Console 사용자: 관리자가 계정에 "Claude Code" 또는 "Developer" 역할을 할당했는지 확인하세요
프록시 뒤에 있는 경우: 기업 프록시가 API 요청을 방해할 수 있습니다. 프록시 설정은 네트워크 설정을 참고하세요.

WSL2에서 OAuth 로그인 실패

WSL2에서 브라우저 기반 로그인은 WSL이 Windows 브라우저를 열 수 없는 경우 실패할 수 있습니다. BROWSER 환경 변수를 설정하세요:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

또는 URL을 수동으로 복사하세요: 로그인 프롬프트가 나타나면 c를 눌러 OAuth URL을 복사한 후 Windows 브라우저에 붙여넣으세요.

"Not logged in" 또는 토큰 만료

세션 후 Claude Code가 다시 로그인하라고 요청하면 OAuth 토큰이 만료되었을 수 있습니다.

/login을 실행하여 재인증하세요. 이 문제가 자주 발생하면 시스템 시계가 정확한지 확인하세요. 토큰 검증은 올바른 타임스탬프에 의존합니다.

설정 파일 위치

Claude Code는 여러 위치에 설정을 저장합니다:

파일	용도
`~/.claude/settings.json`	사용자 설정 (권한, 후크, 모델 오버라이드)
`.claude/settings.json`	프로젝트 설정 (소스 컨트롤에 커밋)
`.claude/settings.local.json`	로컬 프로젝트 설정 (커밋하지 않음)
`~/.claude.json`	글로벌 상태 (테마, OAuth, MCP 서버)
`.mcp.json`	프로젝트 MCP 서버 (소스 컨트롤에 커밋)
`managed-mcp.json`	관리형 MCP 서버
관리형 설정	관리형 설정 (서버 관리, MDM/OS 수준 정책 또는 파일 기반)

Windows에서 ~는 C:\Users\YourName과 같은 사용자 홈 디렉토리를 의미합니다.

이 파일들의 설정에 대한 자세한 내용은 Settings와 MCP를 참고하세요.

설정 초기화

Claude Code를 기본 설정으로 초기화하려면 설정 파일을 제거하세요:

# 모든 사용자 설정 및 상태 초기화
rm ~/.claude.json
rm -rf ~/.claude/

# 프로젝트별 설정 초기화
rm -rf .claude/
rm .mcp.json

주의:

이렇게 하면 모든 설정, MCP 서버 구성 및 세션 기록이 제거됩니다.

성능 및 안정성

리소스 사용량, 응답성 및 검색 동작과 관련된 문제를 다룹니다.

높은 CPU 또는 메모리 사용량

Claude Code는 대부분의 개발 환경에서 작동하도록 설계되었지만, 대규모 코드베이스를 처리할 때 상당한 리소스를 소비할 수 있습니다. 성능 문제가 발생하는 경우:

/compact를 정기적으로 사용하여 컨텍스트 크기를 줄이세요
주요 작업 사이에 Claude Code를 종료하고 재시작하세요
대규모 빌드 디렉토리를 .gitignore 파일에 추가하는 것을 고려하세요

명령 멈춤 또는 프리즈

Claude Code가 응답하지 않는 경우:

Ctrl+C를 눌러 현재 작업 취소를 시도하세요
응답이 없으면 터미널을 닫고 재시작해야 할 수 있습니다

검색 및 탐색 문제

Search 도구, @file 멘션, 커스텀 에이전트 및 커스텀 스킬이 작동하지 않으면 시스템 ripgrep을 설치하세요:

# macOS (Homebrew)
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep

그런 다음 환경 변수에서 USE_BUILTIN_RIPGREP=0을 설정하세요.

WSL에서 느리거나 불완전한 검색 결과

WSL의 파일 시스템 간 작업 시 디스크 읽기 성능 저하로 인해 WSL에서 Claude Code를 사용할 때 예상보다 적은 일치 결과가 나올 수 있습니다. 검색은 작동하지만 네이티브 파일시스템보다 적은 결과를 반환합니다.

참고:

이 경우 /doctor는 Search를 OK로 표시합니다.

해결 방법:

더 구체적인 검색 제출: 디렉토리나 파일 유형을 지정하여 검색 대상 파일 수를 줄이세요: "auth-service 패키지에서 JWT 검증 로직 검색" 또는 "JS 파일에서 md5 해시 사용 찾기".
프로젝트를 Linux 파일시스템으로 이동: 가능하다면 프로젝트가 Windows 파일시스템(/mnt/c/)이 아닌 Linux 파일시스템(/home/)에 위치하도록 하세요.
네이티브 Windows 사용: 더 나은 파일 시스템 성능을 위해 WSL 대신 네이티브 Windows에서 Claude Code를 실행하는 것을 고려하세요.

IDE 통합 문제

Claude Code가 IDE에 연결되지 않거나 IDE 터미널에서 예기치 않게 동작하면 아래 해결 방법을 시도하세요.

WSL2에서 JetBrains IDE 감지 불가

WSL2에서 JetBrains IDE와 함께 Claude Code를 사용하는데 "No available IDEs detected" 오류가 발생하면 WSL2의 네트워킹 설정 또는 Windows 방화벽이 연결을 차단하고 있을 가능성이 높습니다.

WSL2 네트워킹 모드

WSL2는 기본적으로 NAT 네트워킹을 사용하며, 이로 인해 IDE 감지가 방해될 수 있습니다. 두 가지 옵션이 있습니다:

옵션 1: Windows 방화벽 설정 (권장)

WSL2 IP 주소를 확인하세요:

wsl hostname -I
# 출력 예시: 172.21.123.45

관리자 권한으로 PowerShell을 열고 방화벽 규칙을 만드세요:

New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

1단계의 WSL2 서브넷에 따라 IP 범위를 조정하세요.

IDE와 Claude Code를 모두 재시작하세요

옵션 2: 미러 네트워킹으로 전환

Windows 사용자 디렉토리의 .wslconfig에 추가하세요:

[wsl2]
networkingMode=mirrored

그런 다음 PowerShell에서 wsl --shutdown으로 WSL을 재시작하세요.

참고:

이 네트워킹 문제는 WSL2에서만 발생합니다. WSL1은 호스트의 네트워크를 직접 사용하며 이러한 설정이 필요하지 않습니다.

추가적인 JetBrains 설정 팁은 JetBrains IDE 가이드를 참고하세요.

Windows IDE 통합 문제 보고

Windows에서 IDE 통합 문제가 발생하면 다음 정보와 함께 이슈를 생성하세요:

환경 유형: 네이티브 Windows (Git Bash) 또는 WSL1/WSL2
WSL 네트워킹 모드 (해당되는 경우): NAT 또는 mirrored
IDE 이름 및 버전
Claude Code 확장/플러그인 버전
셸 유형: Bash, Zsh, PowerShell 등

JetBrains IDE 터미널에서 Escape 키가 작동하지 않음

JetBrains 터미널에서 Claude Code를 사용하는데 Esc 키가 예상대로 에이전트를 중단하지 않으면 JetBrains의 기본 단축키와 충돌하고 있을 가능성이 높습니다.

이 문제를 해결하려면:

Settings → Tools → Terminal로 이동하세요
다음 중 하나를 수행하세요:
- "Move focus to the editor with Escape" 체크 해제, 또는
- "Configure terminal keybindings"를 클릭하고 "Switch focus to Editor" 단축키를 삭제
변경 사항을 적용하세요

이렇게 하면 Esc 키가 Claude Code 작업을 올바르게 중단할 수 있습니다.

Markdown 서식 문제

Claude Code는 때때로 코드 펜스에 언어 태그가 누락된 markdown 파일을 생성하여 GitHub, 편집기 및 문서 도구에서 구문 강조와 가독성에 영향을 줄 수 있습니다.

코드 블록에서 누락된 언어 태그

생성된 markdown에서 다음과 같은 코드 블록이 보이는 경우:

```
function example() {
  return "hello";
}
```text

올바르게 태그된 블록 대신:

```javascript
function example() {
  return "hello";
}
```text

해결 방법:

Claude에게 언어 태그 추가 요청: "이 markdown 파일의 모든 코드 블록에 적절한 언어 태그를 추가해 주세요"라고 요청하세요.
후처리 후크 사용: 누락된 언어 태그를 감지하고 추가하는 자동 서식 후크를 설정하세요. PostToolUse 서식 후크의 예시는 편집 후 코드 자동 서식 지정을 참고하세요.
수동 확인: markdown 파일을 생성한 후 올바른 코드 블록 서식을 검토하고 필요한 경우 수정을 요청하세요.

일관되지 않은 간격 및 서식

생성된 markdown에 과도한 빈 줄이나 일관되지 않은 간격이 있는 경우:

해결 방법:

서식 수정 요청: Claude에게 "이 markdown 파일의 간격 및 서식 문제를 수정해 주세요"라고 요청하세요.
서식 도구 사용: prettier 또는 사용자 정의 서식 스크립트와 같은 markdown 포매터를 생성된 markdown 파일에 실행하는 후크를 설정하세요.
서식 선호도 지정: 프롬프트 또는 프로젝트 메모리 파일에 서식 요구 사항을 포함하세요.

Markdown 서식 문제 줄이기

서식 문제를 최소화하려면:

요청에서 명확히 하세요: "언어 태그가 지정된 코드 블록이 포함된 올바르게 서식된 markdown"을 요청하세요
프로젝트 규칙 사용: 선호하는 markdown 스타일을 CLAUDE.md에 문서화하세요
검증 후크 설정: 후처리 후크를 사용하여 일반적인 서식 문제를 자동으로 확인하고 수정하세요

추가 도움 받기

여기에서 다루지 않은 문제가 발생하는 경우:

Claude Code 내에서 /bug 명령을 사용하여 Anthropic에 직접 문제를 보고하세요
GitHub 저장소에서 알려진 문제를 확인하세요
/doctor를 실행하여 문제를 진단하세요. 다음을 확인합니다:
- 설치 유형, 버전 및 검색 기능
- 자동 업데이트 상태 및 사용 가능한 버전
- 잘못된 설정 파일 (잘못된 형식의 JSON, 잘못된 유형)
- MCP 서버 설정 오류
- 키 바인딩 설정 문제
- 컨텍스트 사용량 경고 (대용량 CLAUDE.md 파일, 높은 MCP 토큰 사용량, 접근 불가능한 권한 규칙)
- 플러그인 및 에이전트 로딩 오류
Claude에게 직접 기능과 특징에 대해 질문하세요 - Claude는 자체 문서에 대한 내장 접근 권한이 있습니다

문제 해결

Claude Code 설치 및 사용 시 발생하는 일반적인 문제에 대한 해결 방법을 안내합니다.

설치 문제 해결

팁:

터미널을 완전히 건너뛰고 싶다면, Claude Code Desktop 앱을 사용하여 그래픽 인터페이스로 Claude Code를 설치하고 사용할 수 있습니다. macOS 또는 Windows용으로 다운로드하여 명령줄 설정 없이 코딩을 시작하세요.

표시되는 오류 메시지나 증상을 찾아보세요:

표시되는 내용	해결 방법
`command not found: claude` 또는 `'claude' is not recognized`	PATH 수정
`syntax error near unexpected token '<'`	설치 스크립트가 HTML을 반환함
`curl: (56) Failure writing output to destination`	스크립트를 먼저 다운로드한 후 실행
`Killed` (Linux 설치 중)	저메모리 서버에 swap 공간 추가
`TLS connect error` 또는 `SSL/TLS secure channel`	CA 인증서 업데이트
`Failed to fetch version` 또는 다운로드 서버 접속 불가	네트워크 및 프록시 설정 확인
`irm is not recognized` 또는 `&& is not valid`	올바른 셸 명령어 사용
`Claude Code on Windows requires git-bash`	Git Bash 설치 또는 설정
`Error loading shared library`	시스템에 맞지 않는 바이너리 변형 설치됨
`Illegal instruction` (Linux)	아키텍처 불일치
`dyld: cannot load` 또는 `Abort trap` (macOS)	바이너리 비호환
`Invoke-Expression: Missing argument in parameter list`	설치 스크립트가 HTML을 반환함
`App unavailable in region`	해당 국가에서 Claude Code를 사용할 수 없습니다. 지원 국가를 확인하세요.
`unable to get local issuer certificate`	기업 CA 인증서 설정
`OAuth error` 또는 `403 Forbidden`	인증 문제 해결

목록에 해당하는 문제가 없다면 아래 진단 단계를 따라가세요.

설치 문제 디버그

네트워크 연결 확인

설치 프로그램은 storage.googleapis.com에서 다운로드합니다. 접속 가능 여부를 확인하세요:

curl -sI https://storage.googleapis.com

실패하면 네트워크가 연결을 차단하고 있을 수 있습니다. 일반적인 원인:

기업 방화벽 또는 프록시가 Google Cloud Storage를 차단
지역 네트워크 제한: VPN 또는 다른 네트워크를 시도하세요
TLS/SSL 문제: 시스템의 CA 인증서를 업데이트하거나 HTTPS_PROXY가 설정되어 있는지 확인하세요

다음 예시는 두 프록시 변수를 설정한 후 프록시를 통해 설치 프로그램을 실행합니다:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

PATH 확인

PATH 항목을 나열하고 local/bin을 필터링하여 설치 디렉토리가 PATH에 있는지 확인하세요:

macOS/Linux

echo $PATH | tr ':' '\n' | grep local/bin

출력이 없으면 디렉토리가 누락된 것입니다. 셸 설정에 추가하세요:

# Zsh (macOS 기본)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Bash (Linux 기본)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

또는 터미널을 닫고 다시 여세요.

수정이 적용되었는지 확인하세요:

claude --version

Windows PowerShell

$env:PATH -split ';' | Select-String 'local\\bin'

출력이 없으면 설치 디렉토리를 사용자 PATH에 추가하세요:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

변경 사항이 적용되도록 터미널을 재시작하세요.

수정이 적용되었는지 확인하세요:

claude --version

Windows CMD

echo %PATH% | findstr /i "local\bin"

출력이 없으면 시스템 설정을 열고 환경 변수로 이동하여 사용자 PATH 변수에 %USERPROFILE%\.local\bin을 추가하세요. 터미널을 재시작하세요.

수정이 적용되었는지 확인하세요:

claude --version

충돌하는 설치 확인

여러 Claude Code 설치가 있으면 버전 불일치나 예기치 않은 동작이 발생할 수 있습니다. 설치된 항목을 확인하세요:

macOS/Linux

PATH에서 발견된 모든 claude 바이너리를 나열하세요:

which -a claude

네이티브 설치 프로그램과 npm 버전이 있는지 확인하세요:

ls -la ~/.local/bin/claude

ls -la ~/.claude/local/

npm -g ls @anthropic-ai/claude-code 2>/dev/null

Windows PowerShell

where.exe claude
Test-Path "$env:LOCALAPPDATA\Claude Code\claude.exe"

여러 설치가 발견되면 하나만 유지하세요. ~/.local/bin/claude의 네이티브 설치를 권장합니다. 추가 설치를 제거하세요:

npm 글로벌 설치 제거:

npm uninstall -g @anthropic-ai/claude-code

macOS에서 Homebrew 설치 제거:

brew uninstall --cask claude-code

디렉토리 권한 확인

설치 프로그램은 ~/.local/bin/과 ~/.claude/에 대한 쓰기 권한이 필요합니다. 권한 오류로 설치가 실패하면 이 디렉토리가 쓰기 가능한지 확인하세요:

test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

어느 디렉토리든 쓰기 불가능하면 설치 디렉토리를 만들고 사용자를 소유자로 설정하세요:

sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

바이너리 작동 확인

claude가 설치되었지만 시작 시 충돌하거나 멈추면 원인을 좁히기 위해 다음 검사를 실행하세요.

바이너리가 존재하고 실행 가능한지 확인하세요:

ls -la $(which claude)

ldd $(which claude) | grep "not found"

바이너리가 실행 가능한지 빠르게 확인하세요:

claude --version

일반적인 설치 문제

가장 자주 발생하는 설치 문제와 해결 방법입니다.

설치 스크립트가 셸 스크립트 대신 HTML을 반환함

설치 명령 실행 시 다음과 같은 오류가 발생할 수 있습니다:

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

PowerShell에서는 동일한 문제가 다음과 같이 나타납니다:

Invoke-Expression: Missing argument in parameter list.

그렇지 않으면 네트워크 문제, 지역 라우팅 또는 일시적인 서비스 장애로 인해 발생할 수 있습니다.

해결 방법:

대안 설치 방법 사용:

macOS 또는 Linux에서 Homebrew로 설치:
```
brew install --cask claude-code
```
Windows에서 WinGet으로 설치:
```
winget install Anthropic.ClaudeCode
```
몇 분 후 재시도: 이 문제는 일시적인 경우가 많습니다. 잠시 기다린 후 원래 명령을 다시 시도하세요.

설치 후 `command not found: claude`

설치는 완료되었지만 claude가 작동하지 않습니다. 정확한 오류는 플랫폼에 따라 다릅니다:

플랫폼	오류 메시지
macOS	`zsh: command not found: claude`
Linux	`bash: claude: command not found`
Windows CMD	`'claude' is not recognized as an internal or external command`
PowerShell	`claude : The term 'claude' is not recognized as the name of a cmdlet`

이는 설치 디렉토리가 셸의 검색 경로에 포함되어 있지 않음을 의미합니다. 각 플랫폼별 수정 방법은 PATH 확인을 참고하세요.

`curl: (56) Failure writing output to destination`

해결 방법:

네트워크 안정성 확인: Claude Code 바이너리는 Google Cloud Storage에 호스팅됩니다. 접속 가능한지 테스트하세요:
```
curl -fsSL https://storage.googleapis.com -o /dev/null
```
명령이 조용히 완료되면 연결이 정상이며 문제가 간헐적일 가능성이 높습니다. 설치 명령을 재시도하세요. 오류가 발생하면 네트워크가 다운로드를 차단하고 있을 수 있습니다.

대안 설치 방법 사용:

macOS 또는 Linux:

brew install --cask claude-code

Windows:

winget install Anthropic.ClaudeCode

TLS 또는 SSL 연결 오류

해결 방법:

시스템 CA 인증서 업데이트:

Ubuntu/Debian:

sudo apt-get update && sudo apt-get install ca-certificates

macOS (Homebrew):

brew install ca-certificates

Windows에서 TLS 1.2 활성화 - 설치 프로그램 실행 전 PowerShell에서:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

프록시 또는 방화벽 간섭 확인: TLS 검사를 수행하는 기업 프록시는 unable to get local issuer certificate를 포함한 이러한 오류를 유발할 수 있습니다. NODE_EXTRA_CA_CERTS를 기업 CA 인증서 번들로 설정하세요:
```
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
```
인증서 파일이 없다면 IT 팀에 문의하세요. 직접 연결로 시도하여 프록시가 원인인지 확인할 수도 있습니다.

`Failed to fetch version from storage.googleapis.com`

설치 프로그램이 다운로드 서버에 접속할 수 없습니다. 이는 일반적으로 네트워크에서 storage.googleapis.com이 차단되어 있음을 의미합니다.

해결 방법:

직접 연결 테스트:

curl -sI https://storage.googleapis.com

프록시 뒤에 있다면 HTTPS_PROXY를 설정하여 설치 프로그램이 프록시를 통해 라우팅되도록 하세요. 자세한 내용은 프록시 설정을 참고하세요.
```
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash
```
제한된 네트워크에서는 다른 네트워크 또는 VPN을 사용하거나 대안 설치 방법을 시도하세요:

macOS 또는 Linux:
```
brew install --cask claude-code
```
Windows:
```
winget install Anthropic.ClaudeCode
```

Windows: `irm` 또는 `&&` 인식 불가

'irm' is not recognized 또는 The token '&&' is not valid 오류가 발생하면 현재 셸에 맞지 않는 명령을 실행하고 있는 것입니다.

irm 인식 불가: PowerShell이 아닌 CMD에서 실행 중입니다. 두 가지 옵션이 있습니다:

시작 메뉴에서 "PowerShell"을 검색하여 PowerShell을 열고 원래 설치 명령을 실행하세요:
```
irm https://claude.ai/install.ps1 | iex
```
또는 CMD에서 CMD 설치 프로그램을 사용하세요:
```
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```
&& 유효하지 않음: PowerShell에서 CMD 설치 명령을 실행한 것입니다. PowerShell 설치 프로그램을 사용하세요:
```
irm https://claude.ai/install.ps1 | iex
```

저메모리 Linux 서버에서 설치 중 종료됨

VPS 또는 클라우드 인스턴스에서 설치 중 Killed가 표시되는 경우:

Setting up Claude Code...
Installing Claude Code native build latest...
bash: line 142: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}

시스템 메모리가 부족하여 Linux OOM killer가 프로세스를 종료한 것입니다. Claude Code는 최소 4 GB의 가용 RAM이 필요합니다.

해결 방법:

swap 공간 추가 - 서버의 RAM이 제한적인 경우. swap은 디스크 공간을 오버플로 메모리로 사용하여 물리적 RAM이 부족해도 설치를 완료할 수 있게 합니다.

2 GB swap 파일을 생성하고 활성화하세요:
```
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
```
그런 다음 설치를 재시도하세요:
```
curl -fsSL https://claude.ai/install.sh | bash
```
다른 프로세스 종료 - 설치 전에 메모리를 확보하세요.
더 큰 인스턴스 사용 - 가능하다면. Claude Code는 최소 4 GB RAM이 필요합니다.

Docker에서 설치 멈춤

Docker 컨테이너에서 Claude Code를 설치할 때 root로 /에 설치하면 멈출 수 있습니다.

해결 방법:

설치 프로그램 실행 전 작업 디렉토리 설정. /에서 실행하면 설치 프로그램이 전체 파일시스템을 스캔하여 과도한 메모리 사용을 유발합니다. WORKDIR를 설정하면 스캔을 작은 디렉토리로 제한합니다:
```
WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash
```
Docker 메모리 제한 증가 - Docker Desktop을 사용하는 경우:
```
docker build --memory=4g .
```

Windows: Claude Desktop이 `claude` CLI 명령을 덮어씀

이 문제를 해결하려면 Claude Desktop을 최신 버전으로 업데이트하세요.

Windows: "Claude Code on Windows requires git-bash"

네이티브 Windows에서 Claude Code를 사용하려면 Git Bash가 포함된 Git for Windows가 필요합니다.

Git이 설치되지 않은 경우 git-scm.com/downloads/win에서 다운로드하여 설치하세요. 설정 중 "Add to PATH"를 선택하세요. 설치 후 터미널을 재시작하세요.

Git이 이미 설치되어 있지만 Claude Code가 여전히 찾지 못하는 경우, settings.json 파일에서 경로를 설정하세요:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Git이 다른 곳에 설치되어 있다면 PowerShell에서 where.exe git을 실행하여 경로를 찾고 해당 디렉토리의 bin\bash.exe 경로를 사용하세요.

Linux: 잘못된 바이너리 변형 설치됨 (musl/glibc 불일치)

Error loading shared library libstdc++.so.6: No such file or directory

musl 크로스 컴파일 패키지가 설치된 glibc 기반 시스템에서 설치 프로그램이 시스템을 musl로 잘못 감지하는 경우 발생할 수 있습니다.

해결 방법:

시스템이 사용하는 libc 확인:
```
ldd /bin/ls | head -1
```
linux-vdso.so 또는 /lib/x86_64-linux-gnu/에 대한 참조가 표시되면 glibc입니다. musl이 표시되면 musl입니다.
glibc인데 musl 바이너리를 받은 경우, 설치를 제거하고 재설치하세요. https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json의 GCS 버킷에서 올바른 바이너리를 수동으로 다운로드할 수도 있습니다. ldd /bin/ls와 ls /lib/libc.musl*의 출력과 함께 GitHub 이슈를 제출하세요.
실제로 musl인 경우 (Alpine Linux), 필요한 패키지를 설치하세요:
```
apk add libgcc libstdc++ ripgrep
```

Linux에서 `Illegal instruction`

bash: line 142: 2238232 Illegal instruction    "$binary_path" install ${TARGET:+"$TARGET"}

해결 방법:

아키텍처 확인:
```
uname -m
```
x86_64는 64비트 Intel/AMD, aarch64는 ARM64를 의미합니다. 바이너리가 일치하지 않으면 출력과 함께 GitHub 이슈를 제출하세요.
아키텍처 문제가 해결되는 동안 대안 설치 방법 시도:
```
brew install --cask claude-code
```

macOS에서 `dyld: cannot load`

설치 중 dyld: cannot load 또는 Abort trap: 6이 표시되면 바이너리가 macOS 버전 또는 하드웨어와 호환되지 않는 것입니다.

dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
Abort trap: 6

해결 방법:

macOS 버전 확인: Claude Code는 macOS 13.0 이상이 필요합니다. Apple 메뉴를 열고 "이 Mac에 관하여"를 선택하여 버전을 확인하세요.
macOS 업데이트 - 이전 버전을 사용하고 있다면. 바이너리가 이전 macOS 버전에서 지원하지 않는 로드 명령을 사용합니다.
대안 설치 방법으로 Homebrew 시도:
```
brew install --cask claude-code
```

Windows 설치 문제: WSL 오류

WSL에서 다음과 같은 문제가 발생할 수 있습니다:

OS/플랫폼 감지 문제: 설치 중 오류가 발생하면 WSL이 Windows npm을 사용하고 있을 수 있습니다. 다음을 시도하세요:

설치 전에 npm config set os linux 실행
npm install -g @anthropic-ai/claude-code --force --no-os-check로 설치. sudo를 사용하지 마세요.

이 문제를 식별하는 방법:

which npm과 which node 실행 - Windows 경로(/mnt/c/로 시작)를 가리키면 Windows 버전이 사용되고 있는 것입니다
WSL에서 nvm으로 Node 버전 전환 후 기능이 비정상적으로 작동

이 문제를 해결하려면 Linux node/npm 버전이 우선순위를 갖도록 Linux PATH를 수정하세요:

주요 해결 방법: nvm이 셸에 올바르게 로드되었는지 확인

가장 흔한 원인은 비대화형 셸에서 nvm이 로드되지 않는 것입니다. 셸 설정 파일(~/.bashrc, ~/.zshrc 등)에 다음을 추가하세요:

# nvm이 존재하면 로드
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

또는 현재 세션에서 직접 실행하세요:

source ~/.nvm/nvm.sh

대안: PATH 순서 조정

nvm이 올바르게 로드되었지만 Windows 경로가 여전히 우선순위를 가지면 셸 설정에서 Linux 경로를 PATH 앞에 명시적으로 추가할 수 있습니다:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

주의:

appendWindowsPath = false를 통해 Windows PATH 가져오기를 비활성화하면 WSL에서 Windows 실행 파일을 호출하는 기능이 손상되므로 피하세요. 마찬가지로 Windows 개발에 Node.js를 사용하는 경우 Windows에서 Node.js를 제거하지 마세요.

WSL2 샌드박스 설정

샌드박싱은 WSL2에서 지원되지만 추가 패키지 설치가 필요합니다. /sandbox 실행 시 "Sandbox requires socat and bubblewrap" 오류가 표시되면 의존성을 설치하세요:

Ubuntu/Debian

sudo apt-get install bubblewrap socat

Fedora

sudo dnf install bubblewrap socat

WSL1은 샌드박싱을 지원하지 않습니다. "Sandboxing requires WSL2"가 표시되면 WSL2로 업그레이드하거나 샌드박싱 없이 Claude Code를 실행해야 합니다.

설치 중 권한 오류

네이티브 설치 프로그램이 권한 오류로 실패하면 대상 디렉토리가 쓰기 불가능할 수 있습니다. 디렉토리 권한 확인을 참고하세요.

이전에 npm으로 설치하고 npm 관련 권한 오류가 발생하는 경우 네이티브 설치 프로그램으로 전환하세요:

curl -fsSL https://claude.ai/install.sh | bash

권한 및 인증

로그인 실패, 토큰 문제, 권한 프롬프트 동작에 대한 내용을 다룹니다.

반복되는 권한 프롬프트

인증 문제

인증 문제가 발생하는 경우:

/logout을 실행하여 완전히 로그아웃하세요
Claude Code를 종료하세요
claude로 재시작하고 인증 과정을 다시 완료하세요

로그인 중 브라우저가 자동으로 열리지 않으면 c를 눌러 OAuth URL을 클립보드에 복사한 후 브라우저에 수동으로 붙여넣으세요.

OAuth 오류: Invalid code

OAuth error: Invalid code. Please make sure the full code was copied가 표시되면 로그인 코드가 만료되었거나 복사-붙여넣기 중 잘렸습니다.

해결 방법:

Enter를 눌러 재시도하고 브라우저가 열린 후 빠르게 로그인을 완료하세요
브라우저가 자동으로 열리지 않으면 c를 입력하여 전체 URL을 복사하세요
원격/SSH 세션을 사용하는 경우 브라우저가 잘못된 머신에서 열릴 수 있습니다. 터미널에 표시된 URL을 복사하여 로컬 브라우저에서 대신 여세요.

로그인 후 403 Forbidden

로그인 후 API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}가 표시되는 경우:

Claude Pro/Max 사용자: claude.ai/settings에서 구독이 활성 상태인지 확인하세요
Console 사용자: 관리자가 계정에 "Claude Code" 또는 "Developer" 역할을 할당했는지 확인하세요
프록시 뒤에 있는 경우: 기업 프록시가 API 요청을 방해할 수 있습니다. 프록시 설정은 네트워크 설정을 참고하세요.

WSL2에서 OAuth 로그인 실패

WSL2에서 브라우저 기반 로그인은 WSL이 Windows 브라우저를 열 수 없는 경우 실패할 수 있습니다. BROWSER 환경 변수를 설정하세요:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

또는 URL을 수동으로 복사하세요: 로그인 프롬프트가 나타나면 c를 눌러 OAuth URL을 복사한 후 Windows 브라우저에 붙여넣으세요.

"Not logged in" 또는 토큰 만료

세션 후 Claude Code가 다시 로그인하라고 요청하면 OAuth 토큰이 만료되었을 수 있습니다.

/login을 실행하여 재인증하세요. 이 문제가 자주 발생하면 시스템 시계가 정확한지 확인하세요. 토큰 검증은 올바른 타임스탬프에 의존합니다.

설정 파일 위치

Claude Code는 여러 위치에 설정을 저장합니다:

파일	용도
`~/.claude/settings.json`	사용자 설정 (권한, 후크, 모델 오버라이드)
`.claude/settings.json`	프로젝트 설정 (소스 컨트롤에 커밋)
`.claude/settings.local.json`	로컬 프로젝트 설정 (커밋하지 않음)
`~/.claude.json`	글로벌 상태 (테마, OAuth, MCP 서버)
`.mcp.json`	프로젝트 MCP 서버 (소스 컨트롤에 커밋)
`managed-mcp.json`	관리형 MCP 서버
관리형 설정	관리형 설정 (서버 관리, MDM/OS 수준 정책 또는 파일 기반)

Windows에서 ~는 C:\Users\YourName과 같은 사용자 홈 디렉토리를 의미합니다.

이 파일들의 설정에 대한 자세한 내용은 Settings와 MCP를 참고하세요.

설정 초기화

Claude Code를 기본 설정으로 초기화하려면 설정 파일을 제거하세요:

# 모든 사용자 설정 및 상태 초기화
rm ~/.claude.json
rm -rf ~/.claude/

# 프로젝트별 설정 초기화
rm -rf .claude/
rm .mcp.json

주의:

이렇게 하면 모든 설정, MCP 서버 구성 및 세션 기록이 제거됩니다.

성능 및 안정성

리소스 사용량, 응답성 및 검색 동작과 관련된 문제를 다룹니다.

높은 CPU 또는 메모리 사용량

/compact를 정기적으로 사용하여 컨텍스트 크기를 줄이세요
주요 작업 사이에 Claude Code를 종료하고 재시작하세요
대규모 빌드 디렉토리를 .gitignore 파일에 추가하는 것을 고려하세요

명령 멈춤 또는 프리즈

Claude Code가 응답하지 않는 경우:

Ctrl+C를 눌러 현재 작업 취소를 시도하세요
응답이 없으면 터미널을 닫고 재시작해야 할 수 있습니다

검색 및 탐색 문제

Search 도구, @file 멘션, 커스텀 에이전트 및 커스텀 스킬이 작동하지 않으면 시스템 ripgrep을 설치하세요:

# macOS (Homebrew)
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep

그런 다음 환경 변수에서 USE_BUILTIN_RIPGREP=0을 설정하세요.

WSL에서 느리거나 불완전한 검색 결과

참고:

이 경우 /doctor는 Search를 OK로 표시합니다.

해결 방법:

더 구체적인 검색 제출: 디렉토리나 파일 유형을 지정하여 검색 대상 파일 수를 줄이세요: "auth-service 패키지에서 JWT 검증 로직 검색" 또는 "JS 파일에서 md5 해시 사용 찾기".
프로젝트를 Linux 파일시스템으로 이동: 가능하다면 프로젝트가 Windows 파일시스템(/mnt/c/)이 아닌 Linux 파일시스템(/home/)에 위치하도록 하세요.
네이티브 Windows 사용: 더 나은 파일 시스템 성능을 위해 WSL 대신 네이티브 Windows에서 Claude Code를 실행하는 것을 고려하세요.

IDE 통합 문제

Claude Code가 IDE에 연결되지 않거나 IDE 터미널에서 예기치 않게 동작하면 아래 해결 방법을 시도하세요.

WSL2에서 JetBrains IDE 감지 불가

WSL2 네트워킹 모드

WSL2는 기본적으로 NAT 네트워킹을 사용하며, 이로 인해 IDE 감지가 방해될 수 있습니다. 두 가지 옵션이 있습니다:

옵션 1: Windows 방화벽 설정 (권장)

WSL2 IP 주소를 확인하세요:

wsl hostname -I
# 출력 예시: 172.21.123.45

관리자 권한으로 PowerShell을 열고 방화벽 규칙을 만드세요:

New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

1단계의 WSL2 서브넷에 따라 IP 범위를 조정하세요.

IDE와 Claude Code를 모두 재시작하세요

옵션 2: 미러 네트워킹으로 전환

Windows 사용자 디렉토리의 .wslconfig에 추가하세요:

[wsl2]
networkingMode=mirrored

그런 다음 PowerShell에서 wsl --shutdown으로 WSL을 재시작하세요.

참고:

이 네트워킹 문제는 WSL2에서만 발생합니다. WSL1은 호스트의 네트워크를 직접 사용하며 이러한 설정이 필요하지 않습니다.

추가적인 JetBrains 설정 팁은 JetBrains IDE 가이드를 참고하세요.

Windows IDE 통합 문제 보고

Windows에서 IDE 통합 문제가 발생하면 다음 정보와 함께 이슈를 생성하세요:

환경 유형: 네이티브 Windows (Git Bash) 또는 WSL1/WSL2
WSL 네트워킹 모드 (해당되는 경우): NAT 또는 mirrored
IDE 이름 및 버전
Claude Code 확장/플러그인 버전
셸 유형: Bash, Zsh, PowerShell 등

JetBrains IDE 터미널에서 Escape 키가 작동하지 않음

이 문제를 해결하려면:

Settings → Tools → Terminal로 이동하세요
다음 중 하나를 수행하세요:
- "Move focus to the editor with Escape" 체크 해제, 또는
- "Configure terminal keybindings"를 클릭하고 "Switch focus to Editor" 단축키를 삭제
변경 사항을 적용하세요

이렇게 하면 Esc 키가 Claude Code 작업을 올바르게 중단할 수 있습니다.

Markdown 서식 문제

코드 블록에서 누락된 언어 태그

생성된 markdown에서 다음과 같은 코드 블록이 보이는 경우:

```
function example() {
  return "hello";
}
```text

올바르게 태그된 블록 대신:

```javascript
function example() {
  return "hello";
}
```text

해결 방법:

Claude에게 언어 태그 추가 요청: "이 markdown 파일의 모든 코드 블록에 적절한 언어 태그를 추가해 주세요"라고 요청하세요.
후처리 후크 사용: 누락된 언어 태그를 감지하고 추가하는 자동 서식 후크를 설정하세요. PostToolUse 서식 후크의 예시는 편집 후 코드 자동 서식 지정을 참고하세요.
수동 확인: markdown 파일을 생성한 후 올바른 코드 블록 서식을 검토하고 필요한 경우 수정을 요청하세요.

일관되지 않은 간격 및 서식

생성된 markdown에 과도한 빈 줄이나 일관되지 않은 간격이 있는 경우:

해결 방법:

서식 수정 요청: Claude에게 "이 markdown 파일의 간격 및 서식 문제를 수정해 주세요"라고 요청하세요.
서식 도구 사용: prettier 또는 사용자 정의 서식 스크립트와 같은 markdown 포매터를 생성된 markdown 파일에 실행하는 후크를 설정하세요.
서식 선호도 지정: 프롬프트 또는 프로젝트 메모리 파일에 서식 요구 사항을 포함하세요.

Markdown 서식 문제 줄이기

서식 문제를 최소화하려면:

요청에서 명확히 하세요: "언어 태그가 지정된 코드 블록이 포함된 올바르게 서식된 markdown"을 요청하세요
프로젝트 규칙 사용: 선호하는 markdown 스타일을 CLAUDE.md에 문서화하세요
검증 후크 설정: 후처리 후크를 사용하여 일반적인 서식 문제를 자동으로 확인하고 수정하세요

추가 도움 받기

여기에서 다루지 않은 문제가 발생하는 경우:

Claude Code 내에서 /bug 명령을 사용하여 Anthropic에 직접 문제를 보고하세요
GitHub 저장소에서 알려진 문제를 확인하세요
/doctor를 실행하여 문제를 진단하세요. 다음을 확인합니다:
- 설치 유형, 버전 및 검색 기능
- 자동 업데이트 상태 및 사용 가능한 버전
- 잘못된 설정 파일 (잘못된 형식의 JSON, 잘못된 유형)
- MCP 서버 설정 오류
- 키 바인딩 설정 문제
- 컨텍스트 사용량 경고 (대용량 CLAUDE.md 파일, 높은 MCP 토큰 사용량, 접근 불가능한 권한 규칙)
- 플러그인 및 에이전트 로딩 오류
Claude에게 직접 기능과 특징에 대해 질문하세요 - Claude는 자체 문서에 대한 내장 접근 권한이 있습니다

51. 문제 해결

문제 해결

설치 문제 해결

설치 문제 디버그

네트워크 연결 확인

PATH 확인

충돌하는 설치 확인

디렉토리 권한 확인

바이너리 작동 확인

일반적인 설치 문제

설치 스크립트가 셸 스크립트 대신 HTML을 반환함

설치 후 command not found: claude

curl: (56) Failure writing output to destination

TLS 또는 SSL 연결 오류

Failed to fetch version from storage.googleapis.com

Windows: irm 또는 && 인식 불가

저메모리 Linux 서버에서 설치 중 종료됨

Docker에서 설치 멈춤

Windows: Claude Desktop이 claude CLI 명령을 덮어씀

Windows: "Claude Code on Windows requires git-bash"

Linux: 잘못된 바이너리 변형 설치됨 (musl/glibc 불일치)

Linux에서 Illegal instruction

macOS에서 dyld: cannot load

Windows 설치 문제: WSL 오류

WSL2 샌드박스 설정

설치 중 권한 오류

권한 및 인증

반복되는 권한 프롬프트

인증 문제

OAuth 오류: Invalid code

로그인 후 403 Forbidden

WSL2에서 OAuth 로그인 실패

"Not logged in" 또는 토큰 만료

설정 파일 위치

설정 초기화

성능 및 안정성

높은 CPU 또는 메모리 사용량

명령 멈춤 또는 프리즈

검색 및 탐색 문제

WSL에서 느리거나 불완전한 검색 결과

IDE 통합 문제

WSL2에서 JetBrains IDE 감지 불가

WSL2 네트워킹 모드

Windows IDE 통합 문제 보고

JetBrains IDE 터미널에서 Escape 키가 작동하지 않음

Markdown 서식 문제

코드 블록에서 누락된 언어 태그

일관되지 않은 간격 및 서식

Markdown 서식 문제 줄이기

추가 도움 받기

51. 문제 해결

문제 해결

설치 문제 해결

설치 문제 디버그

네트워크 연결 확인

PATH 확인

충돌하는 설치 확인

디렉토리 권한 확인

바이너리 작동 확인

일반적인 설치 문제

설치 스크립트가 셸 스크립트 대신 HTML을 반환함

설치 후 command not found: claude

curl: (56) Failure writing output to destination

TLS 또는 SSL 연결 오류

Failed to fetch version from storage.googleapis.com

Windows: irm 또는 && 인식 불가

저메모리 Linux 서버에서 설치 중 종료됨

Docker에서 설치 멈춤

Windows: Claude Desktop이 claude CLI 명령을 덮어씀

Windows: "Claude Code on Windows requires git-bash"

Linux: 잘못된 바이너리 변형 설치됨 (musl/glibc 불일치)

Linux에서 Illegal instruction

macOS에서 dyld: cannot load

Windows 설치 문제: WSL 오류

WSL2 샌드박스 설정

설치 중 권한 오류

권한 및 인증

반복되는 권한 프롬프트

인증 문제

OAuth 오류: Invalid code

설치 후 `command not found: claude`

`curl: (56) Failure writing output to destination`

`Failed to fetch version from storage.googleapis.com`

Windows: `irm` 또는 `&&` 인식 불가

Windows: Claude Desktop이 `claude` CLI 명령을 덮어씀

Linux에서 `Illegal instruction`

macOS에서 `dyld: cannot load`

설치 후 `command not found: claude`

`curl: (56) Failure writing output to destination`

`Failed to fetch version from storage.googleapis.com`

Windows: `irm` 또는 `&&` 인식 불가

Windows: Claude Desktop이 `claude` CLI 명령을 덮어씀

Linux에서 `Illegal instruction`

macOS에서 `dyld: cannot load`