Could not locate the Claude CLI on PATH 오류 해결 (VS Code)

VS Code에서 Claude Code를 열었더니 이런 문구가 뜨고 아무것도 시작되지 않는 경우가 있습니다.

Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH. Launching by name in a PowerShell terminal would run a 'claude' from the open folder instead of the installed CLI, so the launch was blocked. Make sure the Claude CLI's install directory is on your system PATH (not only your PowerShell profile), then restart VS Code and try again. VS Code reads PATH when it starts, so PATH changes take effect only after a restart.

길어서 대충 “PATH 문제네” 하고 넘기기 쉬운데, 끝까지 읽어 보면 괄호 하나가 눈에 걸립니다. not only your PowerShell profile.

터미널에 claude를 치면 잘 실행되는데 확장만 못 찾는다면 이 괄호부터 의심해 보세요. PATH를 PowerShell 프로필에서 넣어 두면 내가 여는 터미널에는 보이지만 확장에는 보이지 않거든요.

순서는 이렇습니다. VS Code 밖에서 새 PowerShell 창을 열어 where.exe claude로 설치본이 잡히는지 보고, PATH를 프로필이 아니라 사용자 환경 변수에 넣고, VS Code를 완전히 껐다가 다시 엽니다.

2026년 10월 8일 기준 공식 문서와 공개 이슈 한 건을 바탕으로 썼습니다. 10월 13일에는 Windows 11 · PowerShell 5.1에서 where.exe 출력을 확인하고, 설치된 VS Code 확장 2.1.296의 코드에서 이 오류를 내는 조건을 직접 찾아봤습니다.

이 오류가 뜨는 조건

이 오류는 네 가지가 겹칠 때 뜹니다.

1. 운영체제가 Windows이고
2. 확장이 Claude Code를 VS Code 통합 터미널에서 열려고 하고
3. 그 터미널의 셸이 PowerShell이고
4. 확장이 설치된 claude 실행 파일을 PATH에서 찾지 못했을 때

조건에 들어가는 운영체제는 Windows뿐이고, 그중에서도 통합 터미널의 셸이 PowerShell일 때입니다. 확장이 Claude Code를 터미널에서 띄우게 하는 설정으로는 Use Terminal(claudeCode.useTerminal)이 있어요. 켜면 그래픽 패널 대신 터미널 모드로 열리고, 기본값은 꺼져 있습니다.

확장 2.1.296의 코드를 열어 보니 판정이 문서 그대로였습니다. 설치된 claude의 경로를 찾으면 PowerShell에서는 & '<경로>'처럼 그 경로로 실행하고, 못 찾았을 때만 갈립니다.

통합 터미널 셸	경로를 못 찾았을 때
PowerShell	이 오류로 실행을 막음
명령 프롬프트, Git Bash	이름 그대로 claude 실행

통합 터미널의 기본 프로필을 따로 정하지 않았다면 PowerShell로 봅니다. 그래서 Use Terminal을 켰고 기본 셸을 바꾸지 않았다면 이 오류 쪽으로 갑니다.

여기서 하나 갈라 둘 게 있습니다. 확장에는 채팅 패널용 CLI 사본이 따로 들어 있지만, 확장을 깔았다고 해서 claude가 PATH에 생기지는 않습니다. 통합 터미널에서 claude를 쓰려면 독립 설치(CLI 설치)를 따로 해야 해요.

확장 패널은 쓰던 대로 되는데 터미널 쪽만 막힌다면 이 차이부터 떠올려 보세요. 독립 설치 순서와 PATH 등록은 Windows에서 Claude Code를 설치하고 확인하는 순서에 정리해 뒀어요.

왜 그냥 실행하지 않고 막을까

오류 문구의 가운데 문장이 그 이유입니다. PowerShell 터미널에서 이름만으로 claude를 실행하면, 설치된 CLI 대신 지금 열린 폴더에 있는 claude 파일이 실행될 수 있다고 해요. 그래서 확장은 설치된 claude를 PATH에서 확인할 때까지 실행 자체를 막습니다.

남의 저장소를 받아 VS Code로 여는 장면을 떠올려 보면 왜 막는지 납득이 갑니다. 그 저장소에 누가 claude라는 실행 파일을 넣어 뒀다면, 확장 버튼 한 번에 그 파일이 돌 수 있는 거니까요.

Claude Code가 Windows에서 Git Bash를 찾을 때 실행한 폴더 안의 git을 건너뛰는 것도 같은 생각에서 나온 장치입니다. 그 이야기는 Windows에서 Git Bash 경로를 찾는 순서에 있어요.

열린 폴더에 claude라는 이름의 파일이나 폴더를 직접 두지 않았는지도 한 번 보세요. 확장이 막으려는 게 바로 그런 파일이라, 있다면 무엇인지부터 확인하는 게 좋습니다.

where.exe에 경로가 찍혀도 안심하면 안 되는 이유

첫 확인은 VS Code 밖에서 새 PowerShell 창을 열고 이걸 치는 겁니다.

where.exe claude

독립 설치를 기본 위치에 했다면 이런 줄이 나옵니다(출력 예).

C:\Users\YourName\.local\bin\claude.exe

npm으로 설치했다면 출력이 다릅니다. npm으로 깐 테스트 환경에서는 두 줄이 나왔어요.

C:\Users\YourName\AppData\Roaming\npm\claude
C:\Users\YourName\AppData\Roaming\npm\claude.cmd

첫 줄은 확장자가 없는 파일이라 걱정될 수 있는데, 괜찮습니다. 확장은 where.exe 결과 중 .exe·.cmd·.bat·.com으로 끝나는 첫 경로만 쓰거든요. 그래서 npm 설치본은 claude.cmd가 잡힙니다.

헷갈리는 건 경로가 나왔을 때입니다. “나왔으니 PATH는 정상”이라고 넘기기 쉬운데, 실은 반대예요. 경로가 나오는데도 오류가 뜬다면, 그 PATH가 PowerShell 프로필에서 들어온 것이거나 VS Code가 아직 반영하지 못한 PATH 변경이라는 거예요.

새로 연 PowerShell 창은 프로필을 실행하니 프로필이 넣은 PATH가 보이지만, 확장은 프로필을 실행하지 않습니다. 같은 이유로 통합 터미널에 직접 claude를 치면 잘 되는데 확장은 못 찾는 일이 생길 수 있어요.

1. 경로가 안 나오면: 설치 폴더부터

먼저 독립 설치를 했는지부터 봅니다. 확장만 깔았다면 %USERPROFILE%\.local\bin\claude.exe 자체가 없어요. 독립 설치를 했다면 사용자 PATH에 그 폴더를 넣습니다.

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

공식 설치 문서의 명령 그대로이고, 출력은 없습니다. 이 명령은 PowerShell 프로필이 아니라 사용자 환경 변수에 적기 때문에 확장에도 닿습니다.

설치도 했고 PATH도 맞는데 업데이트 직후부터 안 된다면 하나 더 볼 곳이 있습니다. Windows에서 업데이트는 기존 claude.exe를 claude.exe.old.<숫자> 백업으로 옮겨 두고 새 파일을 그 자리에 넣는데, 이 과정이 실패하면 폴더에 백업만 남고 claude.exe가 없을 수 있어요. 복원 명령은 이렇습니다.

Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

복원한 뒤 claude --version이 버전을 찍으면 된 겁니다. 백업 파일이 없으면 설치 명령(irm https://claude.ai/install.ps1 | iex)을 다시 실행하세요. v2.1.281 전에는 claude.exe가 없는 상태에서 백업까지 지워질 수 있었다고 합니다.

2. 경로가 나오면: PATH가 어디서 왔는지

이때는 프로필을 거치지 않은 값, 즉 사용자 환경 변수에 실제로 들어 있는지를 보세요. 설치 문서의 PATH 확인 명령은 $env:PATH를 읽는데, 그건 지금 창의 값이라 프로필이 더한 것까지 섞여 있어요. 아래는 그 명령을 저장된 사용자 PATH만 읽도록 바꾼 겁니다.

[Environment]::GetEnvironmentVariable('PATH', 'User') -split ';' | Select-String '\.local\\bin'

등록돼 있으면 이런 줄이 나옵니다(출력 예).

C:\Users\YourName\.local\bin

아무것도 안 나오면 'User' 자리를 'Machine'으로 바꿔 시스템 PATH도 한 번 보세요. 시스템 PATH에 있다면 등록은 된 것이니 3번의 재시작으로 넘어가면 됩니다.

둘 다 비어 있으면 그 PATH는 프로필이나 다른 스크립트가 넣고 있는 거예요. 1번의 등록 명령으로 사용자 환경 변수에 넣고, 프로필에 있던 PATH 줄은 지워도 됩니다.

3. 마지막은 늘 VS Code 재시작

확장은 VS Code가 시작할 때 잡아 둔 PATH로 확인합니다. 그래서 PATH를 바꾼 뒤에는 VS Code를 다시 시작해야 반영돼요. 창이 여러 개 열려 있으면 하나만 닫아서는 VS Code가 꺼지지 않으니, 저는 창을 모두 닫고 새로 여는 쪽을 권합니다.

급할 때는 패널로

이 오류는 통합 터미널에서 열 때의 이야기입니다. 그래서 지금 당장 작업을 이어 가야 한다면 Use Terminal을 끄고 기본 그래픽 패널로 쓰는 것도 방법이에요. 패널은 확장에 들어 있는 CLI 사본을 쓰니까요.

확장 코드에서도 이 오류는 터미널을 여는 함수 한 곳에서만 나옵니다. 패널로 여는 길에는 이 검사가 없어요.

패널과 CLI는 할 수 있는 일이 조금 다릅니다. 명령과 스킬은 패널에서 일부만 보이니, CLI에만 있는 기능이 필요하면 결국 PATH를 고쳐 터미널에서 써야 합니다.

다른 사람들이 겪은 문제

아래는 GitHub 이슈에 올라온 사례입니다.

PATH가 맞는데도 확장 2.1.214부터 오류가 뜬다는 보고

nishidate는 2026년 7월 22일 이슈 #80087에서, Windows 11 사용자 이름에 일본어가 들어간 환경에서 이 오류가 잘못 뜬다고 보고했습니다.

확장 2.1.212까지는 됐고 2.1.214부터 2.1.217까지는 같은 오류가 났다고 해요. 확장을 2.1.212로 고정해 둔 동안에도 CLI 자체는 2.1.217로 잘 돌았다고 하니, 확장 쪽 확인 과정의 문제로 본 겁니다.

보고자는 이 글이 권하는 확인을 대부분 이미 해 봤습니다. 사용자 PATH에 .local\bin이 저장돼 있었고, where.exe claude와 통합 터미널의 Get-Command claude 모두 설치본을 정확히 가리켰어요.

열린 폴더에 claude로 시작하는 파일도 없었고, 확장을 지우고 다시 깔아도 같았다고 합니다. ASCII로만 된 경로(C:\ClaudeCLI)에 연결 폴더를 만들어 PATH에 넣어 봤지만 그래도 오류가 났다고 하고요.

보고자가 찾은 우회법은 확장의 Install Another Version으로 2.1.212에 고정하는 것이었습니다. where.exe 출력의 인코딩을 확장이 잘못 읽는다는 추정도 적었지만 보고자 본인의 추정이고, 원인은 확정되지 않았습니다. 이슈는 stale 표시와 함께 not planned로 닫혀 있어서, 고쳐졌다는 기록은 이슈 페이지에서 찾지 못했어요.

한글 사용자 이름에서도 같은 일이 생기는지는 이 보고만으로는 알 수 없습니다. 위 순서대로 다 맞췄는데도 오류가 남는다면, 사용자 이름에 비ASCII 문자가 있는지 확인하고 확장 버전을 함께 기록해 두세요. 옛 확장에 고정하는 방법은 그 사이 고쳐진 다른 문제까지 되돌리는 셈이라 마지막 수단으로 남겨 두는 게 좋겠습니다.

마치며

이 오류는 문구가 길어서 원인을 다 말해 주는데도 읽히지 않는 쪽에 가깝습니다. 저는 괄호 안의 “프로필만으로는 안 된다”와 마지막 문장의 “재시작해야 반영된다”, 이 두 군데를 먼저 보시길 권해요. 터미널에서 되는 것과 확장이 찾는 것은 다른 일이라는 것, 문서와 확장 코드를 보면서 가장 크게 남은 부분입니다.

VS Code 밖 새 PowerShell 창에서 where.exe claude 한 줄로 시작해 보세요. 경로가 안 나오면 설치와 PATH 등록부터, 나오면 프로필 대신 사용자 환경 변수로 옮기고 VS Code를 다시 여는 순서입니다. 설치 단계에서 다른 오류가 함께 보인다면 Claude Code 설치·로그인 오류를 단계별로 가르는 법도 같이 보시면 좋습니다.