이 글을 검색해서 들어왔다면 이미 알고 있을 것이다. Claude Code 터미널 어딘가에서 한 줄짜리 메시지가 떠올랐다. “Claude 작업 공간을 시작하지 못했습니다.” 어제까지 멀쩡히 돌아가던 도구가 갑자기 열리지 않는다. 메시지가 짧아서 어디부터 손대야 할지 막막하다. 결론부터 말하면 — 대부분의 경우 5분 안에 해결된다. 원인이 보통 셋 중 하나로 좁혀지기 때문이다.
왜 이 오류가 나는가
Claude Code의 “작업 공간을 시작하지 못했습니다” 오류는 거의 다음 세 가지 중 하나로 귀결된다.
- 인증 만료 — OAuth 토큰이 만료됐거나 계정 상태에 변화가 생긴 경우
- IDE 연결 실패 — VS Code, JetBrains 같은 IDE와 Claude Code 사이의 연결이 끊어진 경우
- 실행 환경 문제 — WSL 설정, PATH 누락, Node.js 버전 충돌
중요한 사실 한 가지. 이 오류는 거의 Claude Code 자체의 버그가 아니다. 대부분 환경 설정 차원의 문제이고, 그래서 짧은 조치 몇 가지로 해결된다. 아래 순서대로 시도해 보면 90% 이상의 케이스가 잡힌다.
해결법 1 — 가장 먼저 시도할 것: 로그아웃 후 재로그인
인증 토큰이 만료된 경우가 가장 흔한 원인이다. Claude Code 터미널에서 다음을 입력한다.
/logout
로그아웃이 끝나면 Claude Code를 완전히 종료한다. 터미널을 새로 열고 다시 실행한다.
claude
로그인 화면이 나타나면 안내에 따라 브라우저 인증을 완료한다. 브라우저가 자동으로 안 열리는 경우가 있는데, 이때는 c 키를 눌러 URL을 클립보드에 복사한 다음 직접 브라우저에 붙여 넣으면 된다. 이 단계만으로 해결되는 비율이 가장 높다.
해결법 2 — PATH 문제 (command not found 포함)
설치는 됐는데 실행이 안 되는 경우다. 터미널에서 다음을 입력해 PATH를 점검한다.
echo $PATH | tr ':' '\n' | grep local/bin
아무것도 출력되지 않는다면 PATH에 설치 경로가 빠져 있는 것이다. 사용 중인 셸에 맞춰 추가한다.
macOS (zsh)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Linux (bash)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
이후 claude --version으로 정상 실행 여부를 확인한다.
해결법 3 — WSL 환경에서의 추가 조치
Windows에서 WSL로 Claude Code를 쓰는 경우 별도 설정이 필요하다. 자주 부딪히는 세 가지 케이스가 있다.
브라우저 로그인이 안 되는 경우. WSL이 Windows 브라우저를 못 띄우는 상황이다. BROWSER 환경 변수를 직접 지정한다.
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude
Node를 못 찾는 경우. WSL이 Windows 경로의 Node.js를 잘못 참조하는 게 원인이다. which node를 입력했을 때 /mnt/c/로 시작하면 이 문제가 맞다. nvm으로 Linux용 Node를 별도로 설치한다.
source ~/.nvm/nvm.sh
nvm install --lts
JetBrains IDE가 감지 안 되는 경우. WSL2 방화벽이 IDE 연결을 차단하는 케이스다. PowerShell을 관리자 권한으로 열고 다음을 실행한다(WSL2 IP는 wsl hostname -I로 확인).
New-NetFirewallRule -DisplayName "Allow WSL2" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
해결법 4 — 마지막 수단: 구성 파일 초기화
위 세 가지로 안 잡힌다면 Claude Code 설정 파일을 통째로 초기화한다. 세션 기록은 사라지지만 기능은 그대로 복구된다.
rm ~/.claude.json
rm -rf ~/.claude/
이후 claude를 다시 실행하면 초기 상태로 돌아간다. 처음 설치한 것과 같은 상태에서 다시 로그인하면 된다.
그래서
Claude Code는 업데이트 속도가 빠른 도구다. 그만큼 간헐적인 환경 충돌이 생긴다. 다만 거의 모든 경우 재로그인 → PATH 확인 → 구성 초기화 순서로 풀린다. 이 흐름을 머리에 넣어 두면 다음 번에는 5분 안에 끝낼 수 있다.
지금 할 일
가장 먼저 할 일은 Claude Code 터미널에서 /doctor를 실행하는 것이다. Anthropic 공식 문서가 권장하는 1차 진단 도구다. 결과가 어디에 문제가 있는지 직접 알려 준다. 진단 결과에 따라 위 4가지 해결법 중 해당하는 것부터 시도한다. 같은 오류가 반복적으로 발생한다면 운영 환경(WSL 사용 여부, Node 버전, 셸 종류) 정보를 메모해 두자. 다음 번 troubleshooting이 훨씬 빨라진다.
관련 글
- Claude Code 처음 시작하는 법: 설치부터 실전까지 2026 완전 가이드
- Claude Opus 4.6 완전 분석 / Cowork 출시
- Claude Code가 복잡한 작업에서 망가졌다: 2월 업데이트 이후 무슨 일이


