PSA: Claude Code의 'Bash 도구'가 macOS에서 /bin/zsh를 실행함 — 문서화되지 않은 환경 변수로 해결 가능 (토큰 절약은 덤)

만약 macOS를 사용 중이고 기본값이 아닌 로그인 셸(homebrew bash, fish, 그 외 시스템 /bin/zsh가 아닌 모든 것)을 사용한다면, Claude Code의 Bash 도구는 이를 조용히 무시해 왔습니다. 사용자의 $SHELL이 무엇이든 상관없이 /bin/zsh를 실행하기 때문에, .bash_profile(또는 fish 설정 등)이 전혀 로드되지 않습니다. 커스텀 PATH도, direnv도, starship도, 별칭(alias)도, 자동 완성도 작동하지 않는 거죠.

왜 어떤 세션은 제대로 작동하지 않는지 디버깅하는 데 시간을 좀 썼습니다. 분명 설치되어 있는데도 명령어를 "찾을 수 없다"고 하거나, 터미널에서는 잘 되던 게 Claude 안에서는 실패하는 경우들이었죠. 알고 보니 밑바닥에서 돌아가는 셸이… 제 셸이 아니었던 겁니다. 다른 분들께 도움이 될까 싶어 해결책을 공유합니다.

확인 방법

Claude에게 다음 명령어를 실행해달라고 하거나, 직접 세션에서 실행해보세요:

ps -p $$ -o comm=
echo "SHELL=$SHELL  BASH_VERSION=$BASH_VERSION  ZSH_VERSION=$ZSH_VERSION"

만약 표시되는 프로세스가 /bin/zsh인데 실제 사용하는 셸은 다른 것이라면, 이 문제가 있는 겁니다.

해결책 (설정 한 줄 추가)

~/.claude/settings.json을 열고 env 블록에 다음을 추가하세요:

{
 "env": {
   "CLAUDE_CODE_SHELL": "/opt/homebrew/bin/bash",
   "BASH_SILENCE_DEPRECATION_WARNING": "1"
  }
}

경로는 본인의 셸에 맞게 수정하세요(which bash, which fish, which nu 등). 그 후 Claude Code를 완전히 종료하고 다시 실행하세요.

같은 확인 과정을 다시 거쳐보세요. 이제 실제 셸, 실제 BASH_VERSION(또는 fish 버전), 그리고 올바르게 설정된 $SHELL을 볼 수 있을 겁니다. 터미널에서와 마찬가지로 일반적인 시작 파일들이 로드될 거예요.

왜 이게 단순히 편의성 이상의 문제라고 생각하는지

Bash 도구가 PATH나 별칭이 없는 셸에서 실행되면, Claude는 결국 명령어를 재시도하거나, 절대 경로로 돌아가거나, bash -c '...'로 감싸거나, 첫 번째 시도가 실패하면 다른 방식을 시도하게 됩니다. 모든 재시도는 토큰을 소모하죠. 제 경우, 이 수정 이후 세션이 확실히 더 깔끔해졌습니다. "다른 방법을 시도해볼게" 같은 우회 경로가 줄어들었거든요.

Apple 실리콘에서 homebrew bash를 사용 중이라면, /bin/zsh 구문 불일치에 갇히는 대신 Claude 안에서 bash 5.3 기능(연관 배열, mapfile, globstar, ${var,,}/^^ 등)을 사용할 수 있다는 장점도 있습니다. 꽤 괜찮은 보너스죠.

궁금해할 분들을 위한 배경

CLAUDE_CODE_SHELL은 제가 찾을 수 있는 그 어디에도 문서화되어 있지 않습니다. 2026년 3월에 u/antonibertel이라는 사용자가 issue #7490에서 지나가듯 언급한 적이 있을 뿐입니다. Claude Code 2.1.119 버전 기준으로 작동하며, 향후 버전에서는 바뀔 수 있으니 테스트한 버전을 기록해두는 것이 좋습니다.

누군가의 디버깅 시간을 아껴줄 수 있기를 바랍니다.