증상 → 원인 → 조치
교육 현장에서 자주 나오는 문제를 빠르게 해결하기 위한 강사용 참고표입니다. 설치 명령·요구사항은 공식 문서(code.claude.com/docs, 2026-07-07 확인) 기준입니다.
| 증상 | 원인 | 조치 |
|---|---|---|
| "claude를 인식할 수 없습니다" | 설치 후 터미널 미재시작 / PATH 미반영 | PowerShell을 닫고 다시 열기 → 그래도 안 되면 %USERPROFILE%\.local\bin을 사용자 PATH에 추가 |
| PowerShell 명령이 오류가 남 | CMD에 붙여넣음(셸 혼동) | PS C:\(PowerShell)에서 실행. irm … | iex는 PowerShell 전용 |
| npm 설치가 실패/경고 | Node.js 22 미만 | Node.js 22+(LTS) 설치, 또는 네이티브 설치 irm https://claude.ai/install.ps1 | iex 사용 |
winget이 없음 | App Installer 부재 / 구형 Windows | Microsoft Store에서 "App Installer" 설치, 또는 네이티브 설치 사용 |
| "32-bit Windows" 오류 | Windows Terminal의 x86 항목 실행 | 일반 PowerShell(64비트)로 실행 |
| 설치가 계속 실패 | 사내망 프록시/방화벽 | claude doctor로 진단, 사외망에서 재시도, 프록시 설정 확인 |
| 증상 | 원인 | 조치 |
|---|---|---|
| 브라우저가 자동으로 안 열림 | 원격/제한 환경 | 터미널에서 c를 눌러 로그인 URL 복사 → 브라우저에 붙여넣기 |
| 로그인했는데 진행이 안 됨 | 인증 콜백 미완료 | 브라우저에서 "허용/완료"까지 누른 뒤 터미널로 복귀 |
| "구독이 필요" 안내 | Pro/Max 미구독 | Claude Pro/Max 구독, 또는 Anthropic Console API 키 사용 |
| 증상 | 원인 | 조치 |
|---|---|---|
| "파일을 못 찾음" / 엉뚱한 파일을 봄 | 작업 폴더 밖에서 실행 | 대상 폴더에서 실행 — 탐색기 주소창에 powershell → claude |
| 결과가 요청과 다름 | 요청이 모호 / AI 한계 | 무엇이 다른지 구체적으로 알려주고 재요청. 숫자·사실은 사람이 검증 |
| 사용량 한도 도달 | 요청 과다 / 긴 대화 누적 | 새 대화로 정리, 요청을 더 간결하게, 잠시 후 재시도 |
| 응답이 느리거나 멈춤 | 큰 작업 / 일시 네트워크 | 작업을 작게 나눠 요청, 재시도 |
| 증상 | 원인 | 조치 |
|---|---|---|
| 스킬 설치가 안 됨 | 마켓 미등록 / 네트워크 | /plugin으로 설치 상태 확인, 저장소명·최신 정보 재확인 |
| claude-video가 동작 안 함(Windows) | ffmpeg·yt-dlp 미설치 | winget/pip로 수동 설치 후 PATH 등록(자동 설치는 macOS 중심) |
| agentmemory 설치·연결 실패 | Node.js/엔진 요건, Windows 네이티브 제약 | Node.js 설치, Windows는 WSL2 권장 |
당일 15분 버퍼 확보. 네이티브 설치 한 줄(irm https://claude.ai/install.ps1 | iex)로 즉시 따라오게.
오류 화면을 캡처해 원문 그대로 보여주게 유도 — 진단이 가장 빠릅니다.
① 작업 폴더 밖에서 실행 ② PowerShell↔CMD 혼동 ③ 설치 후 터미널 미재시작.
실습엔 실제 개인정보·기밀 금지. 연습은 가짜 데이터로.