Claude Code가 실행되지 않을 때 보는 페이지 (Windows 트러블슈팅)

AgentKim·2026년 3월 31일

AI에이전트 claude code windows 윈도우 코딩에이전트 클로드코드

Claude Code 설치가이드 (Windows용)

목록 보기

3/6

용어 설명

이 페이지에서는 다소 생소한 용어가 등장하므로 미리 정리해둔다.

용어	설명
PATH (경로)	Windows가 명령어를 찾는 폴더 목록. "`claude`를 찾을 수 없다" 오류는 이 목록에 claude의 설치 위치가 빠져 있는 것이 원인
환경 변수	PC 전체에 적용되는 설정값. PATH도 환경 변수 중 하나
JSON	설정 파일에 자주 쓰이는 형식. `{ "key": "value" }` 형태로 작성
프로파일	PowerShell을 실행할 때마다 자동으로 읽히는 설정 파일. 여기에 PATH 등의 설정을 저장해두면 영구 적용됨
UTF-8	한국어를 포함한 대부분의 문자를 올바르게 표시하기 위한 국제 표준 인코딩 방식

💡 어려운 작업은 Claude Code에게 바로 부탁하자
아래 절차가 복잡하게 느껴진다면, Claude Code가 실행된 상태에서 자연어로 부탁하면 된다.

"PATH 설정을 해줘"

"한글 깨짐을 고쳐줘"

"PowerShell 프로파일에 UTF-8 설정을 추가해줘"

대부분의 경우 Claude가 명령어를 직접 실행해 자동으로 해결해준다.

❶ "claude를 찾을 수 없다"고 나올 때

증상

PowerShell에서 claude를 입력하면 아래 메시지가 표시된다:

claude: The term 'claude' is not recognized as a name of a cmdlet, function, script file, or executable program.

원인

설치 직후에는 PATH(명령어 검색 위치 목록)에 claude의 설치 경로가 반영되지 않은 상태다. PowerShell을 탭으로만 새로 열면 PATH가 갱신되지 않는다.

해결 방법

Step 1: PowerShell 창 전체를 닫고 다시 열기

반드시 탭이 아닌 창 전체를 ×버튼으로 닫는다. 새 탭을 여는 것으로는 PATH가 갱신되지 않는다.

그래도 해결되지 않으면 PC를 재시작한다.

Step 2: 그래도 안 되면 — claude.exe 파일 존재 확인

먼저 설치 파일 자체가 있는지 확인:

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

True → 파일은 있다. PATH에만 추가하면 된다
False → 설치가 실패한 것. 설치 가이드를 참고해 재설치

Step 3: PATH를 현재 세션에만 임시 추가

$env:PATH = "$env:USERPROFILE\.local\bin;$env:PATH"

이후 claude --version을 입력해서 버전 번호가 표시되면 성공.

Step 4: PATH를 영구적으로 저장

Step 3으로 동작이 확인됐다면 반드시 영구 저장한다. 그렇지 않으면 PowerShell을 닫을 때마다 같은 문제가 재발한다.

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

PowerShell을 재시작한 후 claude --version으로 최종 확인.

💡 실제로 막혔던 포인트
설치는 정상 완료되어 claude.exe 파일이 존재하는데도 PATH가 자동으로 등록되지 않는 케이스가 있었다. 위의 Step 3~4로 해결 가능하다.

❷ 한글·이모지가 깨질 때

증상

한글이 ????? 나 알 수 없는 문자로 표시됨
화면 레이아웃이 무너짐
이모지(🦙, ✓ 등)가 표시되지 않음

원인

Windows의 기본 콘솔 인코딩이 UTF-8이 아닌 경우 발생한다. 특히 한국어 Windows 환경에서는 기본값이 CP949(EUC-KR) 또는 CP932인 경우가 많다.

해결 방법

절차 1: PowerShell 프로파일 파일 열기

notepad $PROFILE

"파일이 없습니다. 만드시겠습니까?"라고 물으면 "예" 를 클릭한다.

절차 2: 아래 내용을 추가하고 저장

# UTF-8 강제 적용 (한글·이모지 깨짐 방지)
chcp 65001 > $null
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

절차 3: PowerShell 재시작

설정을 반영하려면 반드시 PowerShell을 완전히 닫고 다시 열어야 한다.

권장 터미널 환경

항목	권장값
터미널 앱	Windows Terminal (Microsoft Store, 무료)
폰트	Cascadia Code (Windows Terminal 기본 탑재)
인코딩	UTF-8 (위 설정으로 자동 적용)

💡 Windows Terminal은 기본 PowerShell보다 한글 처리가 훨씬 안정적이다. 아직 설치하지 않았다면 이참에 전환을 추천한다.

❸ MCP 서버 연결 오류

증상

MCP(외부 도구 연동)를 설정했는데 동작하지 않고 아래 오류가 표시된다:

[Warning] mcpServers.github: Windows requires 'cmd /c' wrapper to execute npx

원인

Windows 환경에서는 npx 명령어를 Claude Code가 직접 실행할 수 없는 경우가 있다. cmd /c를 통해 Windows 명령 프롬프트를 거쳐 실행해야 한다.

해결 방법

설정 파일의 command 값을 수정한다.

❌ 잘못된 설정 (오류 발생)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

✅ 올바른 설정

{
  "mcpServers": {
    "github": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "여기에 토큰을 입력"
      }
    }
  }
}

변경 포인트 2가지:

"command": "npx" → "command": "cmd" 로 변경
"args" 배열 첫 번째 항목에 "/c" 추가

설정 파일 위치

적용 범위	경로
전역 (모든 프로젝트 공통)	`%APPDATA%\Claude\claude_desktop_config.json`
프로젝트별	`.mcp.json` (프로젝트 폴더 최상위)

💡 %APPDATA% 폴더 여는 방법

Windows 키 + R 을 누른다

%APPDATA%\Claude 를 입력하고 Enter

claude_desktop_config.json 을 메모장으로 열어 편집

❹ "Posix shell environment required" 오류

증상

Claude CLI requires a Posix shell environment.
Please ensure you have a valid shell installed and the SHELL environment variable set.

원인

Git for Windows가 설치되어 있지 않거나, 설치는 됐지만 경로(PATH)가 제대로 연결되지 않은 상태다.

해결 방법

방법 1: Git for Windows 설치 (미설치 시)

git-scm.com/download/win에서 다운로드해 설치한다.
설치 중 모든 선택지는 기본값 그대로 진행하면 된다.

방법 2: 경로 수동 지정 (이미 설치된 경우)

이미 Git이 설치되어 있는데도 오류가 발생한다면:

$env:CLAUDE_CODE_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe"

매번 입력하기 번거롭다면 PowerShell 프로파일에 이 줄을 추가해두면 자동으로 적용된다.

notepad $PROFILE

파일을 열고 위 줄을 추가한 뒤 저장 → PowerShell 재시작.

❺ 응답이 느리다·반응이 없다

원인

대화(컨텍스트)가 너무 길어지면 매 요청마다 전체 대화 이력을 처리하게 되어 응답이 현저히 느려진다.

해결 방법

/clear

대화 이력을 초기화해 빠른 응답 속도를 회복한다.

이전 대화 내용을 모두 지우고 싶지 않은 경우:

/compact

대화를 자동 요약해서 컨텍스트 크기를 줄인다. 중요한 맥락은 유지하면서 속도를 개선한다.

❻ 코드가 이상하게 바뀌었다·되돌리고 싶다

해결 방법

/rewind

또는 Esc 키를 2번 연속 으로 누른다.

되돌리기 메뉴가 열리면 복구할 시점을 선택한다.

선택지:

옵션	동작
대화만 되돌리기	코드 변경은 유지하고 대화 이력만 이전 상태로
코드만 되돌리기	대화는 유지하고 파일 변경만 취소
둘 다 되돌리기	대화와 코드 변경을 모두 이전 상태로 복구

💡 Git을 사용 중이라면 더 안전하다
Claude Code 사용 중에는 작업 단위로 git commit을 해두면 /rewind보다 더 세밀하게 특정 시점으로 돌아갈 수 있다.

❼ 파일의 한글이 깨질 때

증상

Claude Code가 생성하거나 편집한 파일을 열었을 때 한글이 ??? 나 이상한 기호로 표시된다.

원인

Claude Code는 내부적으로 UTF-8을 기준으로 파일을 처리한다. 기존 파일이 EUC-KR(CP949) 등 다른 인코딩으로 저장되어 있으면 깨질 수 있다.

해결 방법

프로젝트 내 모든 파일을 UTF-8로 통일한다
기존 파일이 EUC-KR로 저장되어 있다면, VS Code에서 오른쪽 하단의 인코딩 표시를 클릭 → "UTF-8로 다시 저장"으로 변환한다
Claude Code에 직접 부탁할 수도 있다:

> 이 프로젝트의 모든 파일을 UTF-8 인코딩으로 변환해줘

❽ GitHub 인증 오류

증상

GitHub 관련 작업 시 아래 오류가 발생한다:

Error: connect ECONNREFUSED 127.0.0.1:xxxx

또는

ERR_CONNECTION_REFUSED

원인

gh CLI(GitHub CLI)의 인증 설정이 올바르지 않거나, 방화벽·보안 소프트웨어가 연결을 차단하는 경우에 발생한다.

해결 방법

방법 1: Personal Access Token (PAT) 사용 (권장)

GitHub → 우측 상단 프로필 → Settings → Developer settings → Personal access tokens → Tokens (classic)
"Generate new token (classic)" 클릭
필요한 권한 범위(repo, workflow 등) 선택 후 생성
생성된 토큰을 복사
Claude Code에서 사용:

> GitHub에 푸시해줘. 인증에는 Personal Access Token을 사용해: ghp_xxxx...

방법 2: gh CLI 재인증

gh auth login

대화형 메뉴를 따라 GitHub.com 또는 GitHub Enterprise에 로그인한다.

💡 방화벽 문제인 경우
회사 PC나 보안 소프트웨어(V3, 알약 등)가 설치된 환경에서는 포트가 차단되어 있을 수 있다. IT 담당자에게 문의하거나, PAT 방식으로 우회하자.

❾ 빌드·컴파일 오류가 발생했을 때

증상

코드를 작성해준 후 빌드(컴파일)를 실행하면 오류가 발생한다:

error: 'username' is declared but never used
  --> src/main.rs:15:9

해결 방법

오류 메시지를 그대로 Claude Code에 붙여넣기만 하면 된다. 이것이 가장 빠르고 정확한 방법이다.

> 아래 오류가 발생했어. 고쳐줘:

error: 'username' is declared but never used
  --> src/main.rs:15:9

Claude Code가 오류를 분석해 해당 파일을 자동으로 수정해준다.

💡 핵심 팁
"○번째 줄의 이걸 △으로 바꿔줘" 같은 세세한 지시는 오히려 역효과가 날 수 있다.
오류 메시지를 가공 없이 그대로 전달하는 것이 Claude Code가 가장 정확하게 수정할 수 있는 방법이다.

🔧 디버그용 명령어

문제 원인을 직접 조사하고 싶을 때 사용하는 명령어 모음.

명령어	설명
`claude doctor`	현재 환경 전반을 진단 (PATH, 버전, 의존성 등)
`claude --verbose`	상세 로그를 출력하면서 실행 (오류 원인 추적에 유용)
`claude --mcp-debug`	MCP 서버 연결 디버그 정보 표시

💡 오류 보고 시 유용한 활용법
claude --verbose로 실행한 후 출력된 로그를 그대로 Claude Code에 붙여넣으면 문제를 더 빠르게 진단할 수 있다.

AI강의/개발/기술자문, Claude Code 전문강의, AI 업무 자동화 컨설팅 문의: https://talk.naver.com/ct/w5umt5

AI 업무 자동화/에이전트/워크플로우설계 컨설팅/AI교육: https://mdrules.dev

AgentKim

이전 포스트

Claude Code 편의 기능 모음

다음 포스트

Claude Code가 실행되지 않을 때 보는 페이지 (Windows 트러블슈팅)

Claude Code 설치가이드 (Windows용)

용어 설명

❶ "claude를 찾을 수 없다"고 나올 때

증상

원인

해결 방법

❷ 한글·이모지가 깨질 때

증상

원인

해결 방법

권장 터미널 환경

❸ MCP 서버 연결 오류

증상

원인

해결 방법

설정 파일 위치

❹ "Posix shell environment required" 오류

증상

원인

해결 방법

❺ 응답이 느리다·반응이 없다

원인

해결 방법

❻ 코드가 이상하게 바뀌었다·되돌리고 싶다

해결 방법

❼ 파일의 한글이 깨질 때

증상

원인

해결 방법

❽ GitHub 인증 오류

증상

원인

해결 방법

❾ 빌드·컴파일 오류가 발생했을 때

증상

해결 방법

🔧 디버그용 명령어

Claude Code 편의 기능 모음

Claude Code로 AI가 코드를 짜고 AI가 리뷰하는 개발 워크플로 구축하기

0개의 댓글