명령을 찾는 길(PATH)과 절대 경로
클로드 코드 설치 오류를 겪고 다시 깔아야 하나 고민했는데, 알고 보니 설치는 멀쩡했습니다. 설치 성공 문구까지 본 직후 새 터미널이 클로드 명령을 찾지 못했던 일을 빈 폴더에서 처음부터 직접 다시 따라가 봤습니다.
1. 클로드 코드 설치 오류, 무슨 일이 있었나요?
2026-09-29 맥에서 빈 폴더를 홈 폴더 삼아 공식 설치 스크립트로 클로드 코드 2.1.284 를 깔았습니다. 설치는 성공 문구와 종료 코드(프로그램이 끝나며 남기는 성공, 실패 숫자) 0 으로 끝났습니다.
그런데 새 터미널에서 클로드를 부르자 명령을 찾을 수 없다는 오류와 함께 127 이 나왔습니다. 원래 쓰던 홈 폴더는 건드리지 않았고 로그인 화면 앞에서 멈췄기 때문에, 이 글은 설치와 진단까지만 다룹니다.
2. 무슨 문제가 생겼나요?
설치 전과 설치 후의 오류 문구가 한 글자도 다르지 않았습니다. 그래서 그 한 줄만으로는 설치가 안 된 것인지, 깔렸는데 못 찾는 것인지 가릴 수 없었습니다.
원인은 깔린 폴더 ~/.local/bin 이 셸의 PATH 에 없다는 것이었습니다. 설치 스크립트는 성공 문구 위와 맨 끝에 같은 경고를 두 번 찍었지만, 설치 뒤 ls ~/.zshrc 는 No such file or directory 였습니다. 이번 실행에서 스크립트는 셸 설정 파일을 대신 고치지 않았습니다.
.zshrc 에 한 줄을 넣어도 끝이 아니었습니다. 스크립트나 cron 처럼 사람이 열지 않는 비대화형 셸은 .zshrc 를 읽지 않아 같은 127 이 다시 나왔습니다.
3. 클로드 코드 설치 오류, 어떻게 풀었나요?
다시 설치하지 않고 아래 순서로 확인했습니다.
- 설치 출력의
Setup notes를 끝까지 읽습니다. PATH 경고가 있으면 설치 실패가 아니라 PATH 문제입니다 - 절대 경로로 설치부터 가립니다.
~/.local/bin/claude --version은2.1.284 (Claude Code)와 종료 코드 0 을 냈습니다 - 사람이 여는 터미널은
.zshrc한 줄로 고칩니다. 안내문의 PATH 한 줄을 넣자 새 대화형 셸에서command -v claude가~/.local/bin/claude를 돌려줬습니다.>>는 덧붙이기라 두 번 돌리면 줄이 두 번 들어가고, 열어 둔 터미널은source ~/.zshrc를 쳐야 바뀝니다 - 스크립트와 cron 에는 절대 경로를 적습니다.
~를 풀어 쓴 전체 경로로 적었습니다 - 종료 코드로 남은 일을 가릅니다. 127 이면 PATH, 1 이면서
Not logged in이면 설치는 끝났고 로그인만 남았습니다.claude doctor는 로그인 전에도Running: native (2.1.284)를 보여 주고 0 으로 끝났습니다
| 부르는 방식 | .zshrc 필요 |
이번 결과 | 어울리는 곳 |
|---|---|---|---|
claude (PATH 로 찾기) |
필요 | 대화형 0, 비대화형 127 | 사람이 여는 터미널 |
~/.local/bin/claude (절대 경로) |
필요 없음 | 0 | 스크립트, cron, 다른 프로그램 |
zsh -i -c "claude ..." |
필요 | 0 | 대화형 설정을 꼭 써야 할 때 |
설치 방법은 공식 설치 문서를 함께 보시고, zsh 설정이 처음이라면 zsh 설치 방법에서 .zshrc 가 쌓이는 모양을 먼저 보셔도 좋습니다.
4. 누구에게 도움이 되나요?
새 맥에 클로드 코드를 막 깔았는데 명령을 못 찾는 분, 깐 클로드 코드를 스크립트나 cron 에서 부르려는 분이라면 읽어 보세요. 다시 설치하기 전에 절대 경로 한 번이면 원인이 갈립니다.
bash, .zprofile 과 .zshenv, 실제 cron 이 주는 PATH, npm 과 Homebrew 설치, Linux 와 Windows, 로그인 뒤 오류는 이번에 돌려 보지 않았습니다. 이런 환경이라면 이 글의 결론을 그대로 옮기지 않는 편이 맞습니다.
5. 한 줄 정리
필자의 결론
클로드 코드 설치 오류의 대부분은 다시 설치할 문제가 아니라 PATH 문제였고, 필자는 사람이 쓰는 터미널에는 .zshrc 한 줄을, 스크립트와 cron 에는 ~/.local/bin/claude 절대 경로를 쓰기로 정했습니다. 성공 신호와 실제 결과를 따로 봐야 한다는 교훈은 테스트는 통과했는데 261편 중 6편만 맞았다에서도 다뤘습니다.
그래서 당신은 이것만 하면 됩니다. 새 터미널에서
~/.local/bin/claude --version과claude --version을 차례로 쳐서 어느 쪽이 도는지부터 확인해 보세요.
설치 뒤 무엇을 할지는 서평 클로드 코드 에이전틱 코딩이, 규칙 파일이 안 읽힐 때는 AGENTS.md 안 읽힐 때 해결 방법 총정리가 이어 읽기 좋습니다.
부록: 재현 명령과 출력
2026-09-29 19:27~19:35 KST, macOS 27.0 arm64 에서 /tmp/cc-fresh/home 을 HOME 으로 삼아 돌렸습니다. 이 글의 ~ 는 전부 이 빈 HOME 입니다.
| 순서 | 한 일 | 원문 결과(일부) | 종료 코드 |
|---|---|---|---|
| 1 | 설치 전 새 셸에서 claude --version |
zsh:1: command not found: claude |
127 |
| 2 | 공식 설치 스크립트 실행 | Claude Code successfully installed! 와 PATH 경고 2회 |
0 |
| 3 | 설치 직후 새 셸에서 claude --version |
zsh:1: command not found: claude, ~/.zshrc 없음 |
127 |
| 4 | .zshrc 에 PATH 한 줄 넣고 대화형 셸 |
2.1.284 (Claude Code) |
0 |
| 5 | 절대 경로 ~/.local/bin/claude --version |
2.1.284 (Claude Code) |
0 |
| 6 | 로그인 전 claude -p |
Not logged in 문구 |
1 |
| 7 | .zshrc 를 넣은 뒤 비대화형 셸(zsh -c) |
zsh:1: command not found: claude |
127 |
| 8 | claude doctor |
Running: native (2.1.284) |
0 |
설치와 설치 직후 확인(설치 출력은 발췌)입니다. 안내문의 한 줄은 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc 였습니다.
$ curl -fsSL https://claude.ai/install.sh | bash
● Native installation exists but ~/.local/bin is not in your PATH. Run:
✔ Claude Code successfully installed!
$ env -i HOME=/tmp/cc-fresh/home PATH=/usr/bin:/bin /bin/zsh -f -c "claude --version"
zsh:1: command not found: claude.zshrc 를 넣은 뒤 대화형과 비대화형의 차이입니다.
$ zsh -i -c "claude --version"
2.1.284 (Claude Code)
$ env -i HOME=/tmp/cc-fresh/home PATH=/usr/bin:/bin /bin/zsh -c "claude --version"
zsh:1: command not found: claude로그인 전 claude -p 입니다.
$ claude -p "ok 라고만 답해" < /dev/null
Not logged in · Please run /login
rc=1doctor 출력의 Path: ~/.local/share/claude/versions/2.1.284 줄로 본체 위치도 확인했습니다. doctor 출력에 있던 경고 한 건은 가짜 HOME 이라 키체인 파일이 없어서 생긴 격리 시험의 부산물이라 다루지 않았고, 계정 쪽 줄도 뺐습니다.
새 글이 올라오면 Threads @wonizz.ai 에도 올립니다. 팔로우해 두면 피드에서 바로 볼 수 있습니다.