본문으로 건너뛰기

VS Code에서 Claude Code 설치 후 터미널 오류 해결 사례

둘둘

2026.01.17

VS Code에서 Claude Code 설치 후 터미널 오류 해결 사례 본문 이미지

소개

OT를 들으며 VS Code + Claude Code 환경을 처음으로 세팅해보았다.
VS Code 설치와 Claude 로그인까지는 비교적 순조로웠지만, 막상 터미널에서 claude 명령어를 실행하려고 하니 예상치 못한 오류를 마주했다.

문제 상황 한 줄 요약
👉 VS Code에서는 Claude가 잘 보이는데, 터미널에서는 claude를 찾을 수 없다고 나옴

이 글은 PATH 개념을 전혀 모르는 상태에서, 실제로 겪은 시행착오와 해결 과정을 정리한 기술 사례 기록이다.


진행 방법

1️⃣ 환경 세팅

  • VS Code 설치

  • Claude Code 설치 완료

  • VS Code 상에서는 로그인 상태 및 입력창 정상 확인

하지만 터미널에서 다음 명령어를 입력했을 때 문제가 발생했다.

claude

❌ 결과: command not found (경로를 찾을 수 없음)


2️⃣ Claude에게 직접 문의

Claude에게 그대로 상황을 설명했고, 아래와 같은 답변을 받았다.

📌 원인 설명

  • claude 명령어는 실제로 설치되어 있음

  • 설치 위치:

~/.local/bin/claude
  • 하지만 이 경로가 PATH 환경변수에 포함되어 있지 않아서

  • 터미널이 claude라는 명령어를 어디서 찾아야 할지 모르는 상태


3️⃣ 해결 방법 (zsh 기준)

Claude가 안내해준 해결 방법은 다음과 같았다.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

이 명령이 하는 일 (정리)

  • ~/.zshrc : 터미널(zsh)이 시작될 때 읽는 설정 파일

  • $HOME/.local/bin : claude가 설치된 실제 위치

  • PATH에 이 경로를 추가 → 터미널이 claude를 인식 가능

또는, 임시 테스트용 방법으로는 아래처럼 직접 경로를 지정해 실행할 수도 있었다.

~/.local/bin/claude

4️⃣ 너무 어려워서 다시 요청 (쉬운 설명)

위 설명이 잘 이해되지 않아, Claude에게 초보자 기준으로 다시 설명해달라고 요청했다.

Claude의 요약은 다음과 같았다.

  • Claude Code는 이미 설치되어 있음 ✅

  • 다만 터미널이 “어디 있는지” 몰라서 못 찾고 있는 상태 😅

  • 해결 방법은 주소를 터미널 주소록(PATH)에 추가하는 것

👉 그래서 아무 생각 말고 아래 두 줄을 순서대로 실행하라고 안내받았다.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

그리고 다시 터미널에서

claude

🎉 정상 실행 성공!


결과와 배운 점

✅ 배운 점

  • 프로그램이 설치되어 있어도 PATH에 없으면 실행할 수 없다

  • 터미널 명령어는 “이름”이 아니라 실제 위치를 기준으로 동작한다

  • ~/.zshrc는 zsh 환경에서 매우 중요한 설정 파일


🤔 여전히 남은 의문

  • ~/.local/bin이 정확히 어떤 기준으로 만들어지는지

  • 왜 자동으로 PATH에 안 들어가는 경우가 있는지

  • GUI(VS Code)와 터미널 환경이 왜 다르게 동작하는지

👉 지금은 “일단 되게 만들기”에는 성공했지만, 구조적인 이해는 아직 부족한 상태다.


추가 실습: 자동 생성된 Markdown 문서의 요일 오류

상황

  • Claude Code로 자동 생성된 Markdown 문서를 실습

  • 날짜는 맞았지만, 요일이 금요일로 표시됨

  • 실제 날짜: 1월 17일 (토요일)

판단 & 대응

  • 요일 계산이 한국 시간 기준이 아닌 것 같다고 추측

  • Claude에게 “한국 시간 기준이 맞는지” 질문

결과

  • 즉시 인식

  • 요일 수정 성공

한국어 텍스트가 있는 화면의 스크린샷

그 외 정리한 생각들

  • AI 관련 지식과 경험이 너무 빨리 휘발됨 → Notion에 전용 페이지 생성 // 옵시디언은 아직 어려워..

  • 지금까지 사용해본 AI 툴 목록 정리

  • Google의 Antigravity 설치 시도

  • 스터디 전에 목표를 정리할 필요성 인식

앞으로 해보고 싶은 것

  • 이번 스터디를 통해 내가 만들고 싶은 결과물 명확히 정의하기

  • 예전에 만들었던 단계표처럼 AI 학습 단계 로드맵 만들기

  • 모르는 용어가 급격히 늘어남 → AI 용어 단어장 새로 만들기


도움 받고 싶은 글 (보류 중)

  • 참고하고 싶은 글은 찾았지만,

  • 현재 수준에서는 이해가 거의 불가능 😅

👉 일단 홀드, 다음 스터디에서 질문 예정

https://www.gpters.org/nocode/post/koding-1do-molrado-ok-antigeuraebitiro-3bun-mane-gokweolriti-gangyi-wiki-3IJJsPboytKJo9H


마무리

새로운 배움은 언제나 즐겁다! 다음 사례에서는 단순 해결이 아니라, 구조까지 이해한 기록을 남겨보고 싶다 💪
초반 강한 호기심일 때 부지런히 익혀둬야겠다!

5

함께 이야기해요 5

로그인하고 댓글을 남겨 주세요

진여진 프로필 이미지
진여진2026.01.18

와~~ 사례글 재미있게 잘 읽었습니다

저도 경험상, 처음 셋팅이 가장 어려웠고, 이거만 해내면

나머지 시행착오들은 처음 겪은 문제들보단 쉽게 해낼거에요

앞으로의 여정도 응원드립니다 ㅎㅎ

안
안상영2026.01.18

"아무 생각 말고 아래 두 줄을 순서대로 실행하라고 안내받았다."
이거 너무 웃기네요~
저도 처음 AI와 대화한 시절이 생각납니다 ㅋㅋㅋ

윈도우는 사용자 권한, 시스템 권한, 띄어쓰기 오인식 등
별거 아닌 별거 같은 문제로 개발환경에서 path문제가 자주 발생합니다.

그런데...
zsh를 안내하다니... 이미 단순 윈도우 환경이 아닌가봐요?
그래도 벌써 문제를 몇개나 해결하셨다니
너무 잘 하시는데용!!

정혜지 프로필 이미지
정혜지2026.01.21

와!! 둘둘님 PATH 오류 해결 사례 너무 꼼꼼하게 정리해주셨네요! "아무 생각 말고" 두 줄 실행하라는건 ㅋㅋㅋ 저도 웃음이 났어요 ㅋㅋ

특히 PATH 개념 전혀 모르는 상태에서 시작하셨다고 말씀해주신 게 다른 분들께 큰 용기가 될 것 같아요. 초반 설치 과정에서 이런 환경 문제가 가장 많이 발생하더라고요.

요일 오류까지 발견하고 수정하신 것도 대단해요! 작은 것도 놓치지 않는 꼼꼼함이 앞으로 큰 힘이 될 거예요. 다음에 만나는 문제는 더 쉽게 해결하실 거예요!

oneshot 프로필 이미지
oneshot2026.01.21

클로드와 함께 작업하시는 모습이 돋보입니다.

정옥선 프로필 이미지
정옥선2026.01.21

오~ 꼼꼼한 정리!! 저는 이틀전 클로드코드 따라하며 설치하기 바빠 어떻게 했는지 잊어버렸는데 다시 공부할수 있어서 좋아요!! 앞으로도 홧팅!!

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기