VS Code Claude 연동 오류 (2026) — 증상별 해결 순서

 

VS Code Claude 연동이 안 될 때 가장 흔한 실수는 재설치부터 하는 것이다.

 

증상마다 고쳐야 할 곳이 다르다.

확장이 안 보이는 것과 응답이 없는 것, 파일을 못 찾는 것은 원인이 아예 다른 층에 있다.

공식 문서도 증상을 6가지 갈래로 나눠 각각 다른 문서로 보낸다.

재설치는 그중 하나에만 듣는다.

VS Code 1.94.0 미만이면 아예 동작하지 않는다는 것도 확인 대상이다.

 

설치와 초기 세팅은 Claude Code VS Code 연동 - 개발환경 세팅 가이드에 정리해뒀다.

이 글은 이미 설치한 뒤에 생기는 문제만 다룬다.

 

먼저 이것부터

 

• /doctor를 실행한다. 설치·설정·확장·컨텍스트 사용량을 자동 점검하고, 고칠 수 있는 항목은 확인 후 적용까지 해준다.
• claude가 아예 안 뜨면 셸에서 claude doctor를 실행한다.
• MCP 서버가 의심되면 /mcp로 상태를 본다.
• VS Code는 1.94.0 이상이어야 확장이 동작한다.
• 제한 모드(Restricted Mode)에서는 확장이 동작하지 않는다. 워크스페이스 신뢰부터 확인한다.

 

증상별로 어디를 먼저 봐야 할까요

 

증상원인이 있는 곳

command not found, 설치 실패, PATH, EACCES	설치·로그인 문제
로그인 루프, OAuth 오류, 403 Forbidden	인증 문제
설정이 안 먹음, 훅이 안 돌음, MCP 미로딩	설정 디버깅
확장이 Claude를 못 잡음	VS Code 통합
CPU·메모리 과다, 응답 지연, 멈춤	성능·안정성
검색이 파일을 못 찾음	ripgrep

 

같은 "연동이 안 된다"로 묶이지만 조치는 이렇게 갈린다.

어느 칸인지부터 정하면 헤매는 시간이 크게 준다.

 

개인적으로는 이 표를 먼저 보는 습관이 재설치보다 훨씬 값이 크다고 본다.

재설치는 첫 줄(설치·PATH) 하나에만 듣는데, 실제로 자주 걸리는 건 아래 다섯 줄이다.

 

 

확장이 안 보일 때

 

Spark 아이콘은 파일을 열어야 편집기 툴바 오른쪽 위에 나타난다.

폴더만 열어둔 상태로는 안 보인다.

이걸 모르고 재설치를 반복하는 경우가 많다.

 

순서대로 확인한다.

 

1. 파일을 하나 연다
2. VS Code 버전이 1.94.0 이상인지 본다(도움말 → 정보)
3. 명령 팔레트에서 "Developer: Reload Window"를 실행한다
4. 다른 AI 확장(Cline, Continue 등)을 잠시 비활성화한다
5. 워크스페이스 신뢰를 확인한다. 제한 모드에서는 동작하지 않는다

 

아이콘이 끝내 안 보이면 우회로가 있다.

화면 오른쪽 아래 상태 표시줄의 ✱ Claude Code를 누르면 파일을 열지 않아도 실행된다.

명령 팔레트에서 "Claude Code"를 쳐도 된다.

 

맥에서 단축키가 안 먹을 때

 

macOS Tahoe 이상에서 Cmd+Esc가 먹히지 않는 일이 있다.

시스템의 게임 오버레이 단축키가 같은 키에 기본 할당돼 있어서, VS Code까지 키 입력이 도달하지 않는다.

 

시스템 설정 → 키보드 → 키보드 단축키 → 게임 컨트롤러에서 게임 오버레이 체크를 해제하면 풀린다.

바꾸고 싶지 않다면 VS Code 단축키 편집기에서 Claude Code: Focus input을 다른 키에 재할당하는 방법도 있다.

 

이건 확장의 버그가 아니라 OS 쪽 충돌이라, 재설치로는 절대 해결되지 않는다.

 

응답이 없거나 느릴 때

 

응답이 안 오면 인터넷 연결과 새 대화부터 확인하고, 그래도 이상하면 터미널에서 claude를 직접 실행해본다.

확장 화면보다 터미널 쪽에 더 자세한 오류 메시지가 찍힌다.

 

CPU나 메모리를 심하게 쓰는 경우는 대개 컨텍스트가 커진 상태다.

 

• /compact로 대화 컨텍스트를 줄인다
• 큰 작업 사이사이에 Claude Code를 껐다 켠다
• 빌드 산출물 같은 대용량 디렉터리를 .gitignore에 넣는다
• claude --safe-mode로 다시 띄워 본다. 플러그인·MCP 서버·훅을 전부 끄고 시작하므로, 이때 사용량이 떨어지면 커스터마이징 중 하나가 원인이다

 

멈춘 것 같으면 Ctrl+C로 현재 작업을 취소하고, 그래도 안 되면 터미널을 닫는다.

대화는 사라지지 않는다.

같은 디렉터리에서 claude --resume으로 이어서 쓸 수 있다.

 

글자가 깨지거나 검색이 안 될 때

 

편집기 내장 터미널에서 글자가 네모나 이상한 기호로 보이면 터미널의 GPU 렌더러가 원인일 가능성이 크다.

/terminal-setup을 실행하면 terminal.integrated.gpuAcceleration을 끄도록 설정을 잡아준다.

 

검색이 파일을 못 찾는 문제는 다른 층이다.

@파일 언급이나 검색이 동작하지 않으면 번들된 ripgrep이 그 시스템에서 실행되지 않는 경우다.

플랫폼 패키지로 ripgrep을 설치한 뒤 환경변수 USE_BUILTIN_RIPGREP을 0으로 두면 시스템 ripgrep을 쓴다.

적용됐는지는 claude doctor의 Search 항목이 시스템 경로를 가리키는지로 확인한다.

 

WSL에서 검색 결과가 적게 나오는 건 또 다른 사정이다.

파일 시스템을 넘나드는 구조라 읽기 성능이 떨어지는 것이라, 프로젝트를 /home/ 아래로 옮기거나 검색 범위를 좁혀서 쓰는 편이 낫다.

 

자동 압축이 반복될 때

 

Autocompact is thrashing 메시지는 압축은 성공했는데 큰 파일이나 도구 출력이 곧바로 컨텍스트를 다시 채웠다는 뜻이다.

같은 일이 반복되자 Claude Code가 재시도를 멈춘 상태다.

 

큰 파일을 통째로 읽히지 말고 함수나 줄 범위를 지정해 나눠 읽히면 풀린다.

/compact 뒤에 남길 내용을 지정하거나, 큰 파일 작업만 서브에이전트로 넘겨 별도 컨텍스트에서 처리하는 방법도 있다.

 

자주 묻는 질문 (FAQ)

 

뭘 봐야 할지 모르겠으면요?

/doctor를 먼저 실행한다.

설치·설정·확장·컨텍스트를 한 번에 점검하고 고칠 항목을 제안한다.

 

확장을 지웠는데 자꾸 다시 설치됩니다.

VS Code 내장 터미널에서 claude를 실행하면 확장이 자동으로 다시 설치된다.

/config에서 IDE 확장 자동 설치를 끄면 멈춘다.

 

API 키가 꼭 필요한가요?

아니다.

유료 Claude 구독이나 Console 계정으로 로그인하면 되고, 별도 API 키는 필요하지 않다.

 

설정을 완전히 초기화하려면요?

확장을 제거한 뒤 확장 저장소 디렉터리를 삭제한다.

맥은 ~/Library/Application Support/Code/User/globalStorage/anthropic.claude-code 경로다.

 

터미널에서 쓰던 대화를 확장에서 이어갈 수 있나요?

대화 기록에서 이전 대화를 다시 열 수 있다.

확장과 CLI는 설정을 공유한다.

 

오늘 바로 할 것

 

1. /doctor 먼저. 증상 추측보다 자동 점검이 빠르다.
2. 확장이 안 보이면 파일을 열고 워크스페이스 신뢰를 확인한다. 재설치는 그다음이다.
3. 느려졌으면 /compact와 --safe-mode로 원인을 컨텍스트와 커스터마이징으로 갈라본다.
4. 검색이 안 되면 claude doctor의 Search 항목을 본다. ripgrep 문제일 수 있다.
5. 설치 자체가 안 됐다면 세팅 가이드로 돌아간다.

 

---

 

출처

• Claude Code 공식 문서 — Troubleshooting — 증상별 분기표, 성능·안정성, ripgrep, 자동 압축 thrashing
• Claude Code 공식 문서 — Use Claude Code in VS Code — VS Code 1.94.0 요건, Spark 아이콘·제한 모드, Cmd+Esc 충돌, 확장 제거
• 버전 업데이트로 메뉴와 명령이 바뀔 수 있다. 오류 메시지가 새로 보이면 메시지 전문으로 검색하는 편이 빠르다.