Claude Code가 갑자기 실행되지 않을 때 — 설정 파일로 인한 '차단' 원인을 분리하여 복구하기

Claude Code는 설정 파일에 아주 작은 실수 하나만 있어도, 에러 이유를 알려주지 않은 채 완전히 실행되지 않는 경우가 있습니다. 게다가 메시지가 "설정이 원인이다"라고 알려주지 않기 때문에, 네트워크나 설치 문제를 의심하며 시간을 허비하기 쉽습니다.

이 기사에서는 실제로 보고된 "삭제한 폴더에 대한 참조가 남아 실행할 수 없게 되는" 사례를 시작으로, 원인의 층을 하나씩 분리하여 30초~수 분 내에 복구하는 절차와 재발을 방지하는 습관을 정리합니다. 절차에 포함된 스크립트는 직접 실행하여, 망가뜨리지 않고 고쳐지는 것을 확인했습니다.

~/.claude/settings.local.json

의 permissions.additionalDirectories

에, 이미 존재하지 않는 경로가 하나라도 남아 있으면 Claude Code는 실행 도중에 멈추며, 도구를 전혀 사용할 수 없게 됩니다 (2026-06-16에 보고 · macOS에서 확인, 해당 Issue #68844).

{
"permissions": {
"additionalDirectories": ["/some/path/that/does/not/exist"]
...

본래라면 "이 디렉토리를 찾을 수 없으므로 건너뜁니다"라는 경고만 내보내고 실행되어야 하지만, 현재는 경고가 아니라 실행 자체가 실패합니다.

대부분의 경우 직접 작성한 기억이 없습니다. 흔한 경로는 다음과 같습니다.

• 어떤 세션에서 작업 편의를 위해 임시 폴더를 additionalDirectories에 추가한다 (자동으로 추가되는 경우도 있음)
• 작업이 끝나고 해당 폴더를 삭제한다
• 다음에 실행했을 때, 설정은 여전히 삭제된 폴더를 가리키고 있어 실행에 실패한다

즉, "폴더를 삭제했더니 다음 날부터 실행되지 않는다"와 같이 원인과 결과가 시간적으로 떨어져 있는 까다로운 방식으로 고장 납니다.

additionalDirectories를 포함하는 설정은 여러 파일이 합성되어 사용됩니다. 주로 다음 4곳입니다.

• ~/.claude/settings.json (사용자 전체)
• ~/.claude/settings.local.json (사용자 전체 · 로컬)
• 프로젝트의 .claude/settings.json (리포지토리에 포함)
• 프로젝트의 .claude/settings.local.json (프로젝트 · 로컬)

어디에 문제의 경로가 적혀 있는지 모를 때는 한꺼번에 찾습니다.

grep -rl additionalDirectories ~/.claude .claude 2>/dev/null

찾은 파일을 수동으로 편집해도 되지만, 유효한 경로는 남겨둔 채 존재하지 않는 것만 지우고 싶으므로 다음 처리를 사용하는 것이 안전합니다. 백업(.bak)을 남기며, 다른 설정 항목에는 일절 손대지 않습니다. 인자로 대상 파일을 전달합니다.

python3 - "$HOME/.claude/settings.local.json" <<'PY'
import json, os, sys, shutil
p = sys.argv[1]
...

직접 테스트한 결과, 존재하는 경로는 그대로 남기고 존재하지 않는 경로만 제거하며, 무관한 키도 망가뜨리지 않았습니다. 절차 1에서 여러 파일이 나왔다면 각각에 대해 실행합니다.

설정이 원인인 실행 불능의 경우, **오타(끝부분의 콤마, 닫히지 않은 괄호, 주석 혼입)**도 제2의 용의자입니다. 각 층이 올바른 형식인지 기계에게 확인시키세요.

for f in ~/.claude/settings.json ~/.claude/settings.local.json .claude/settings.json .claude/settings.local.json; do
[ -f "$f" ] && { python3 -m json.tool "$f" >/dev/null 2>&1 && echo "OK $f" || echo "고장남 $f"; }
done

이번에는 additionalDirectories였지만, 설정이나 환경 변수의 작은 실수로 실행이 멈추는 사례는 다른 것도 있습니다. 이유를 알 수 없을 때의 정석은 동일합니다.

• 먼저 의심스러운 층을 격리한다. settings.local.json

을(를) 일시적으로 이름을 변경하여, 빈 상태에서 실행할 수 있는지 시도한다 (실행된다면 원인은 해당 층 안에 있다).

• 층을 하나씩 되돌린다. 어떤 설정을 되돌린 순간에 고장 나는지를 통해 범인을 알 수 있다.
• 수정하기 전에 반드시 백업. cp file file.bak 명령어를 사용하면, 실수하더라도 되돌릴 수 있다.

"설정을 모두 삭제"하는 것이 아니라 "층을 하나씩 무효화하여 분리"하는 것이, 유효한 설정을 잃지 않고 최단 시간에 복구하는 요령입니다.

폴더를 삭제하거나 이동하기 전에, 그것이 additionalDirectories에 등록되어 있지 않은지 확인하고 먼저 설정에서 제외한다. 이전 세션이 자동으로 추가한 경로는 어느샌가 오래되었을 가능성이 높다. 정기적으로 단계 2를 실행하여 정리해 두면, 어느 날 갑자기 접근이 차단되는 것을 방지할 수 있다.

근본적으로는 실행 시 "찾을 수 없는 경로는 경고를 띄우고 건너뛰는" 설계가 바람직하며, 해당 내용에 대한 요구는 Issue에서도 나오고 있다. 제공 측의 수정이 이루어지기 전까지는 위의 단계로 자가 방어가 가능하다.

이러한 종류의 "설정이나 운용의 작은 함정으로 인한 사고"를 줄이기 위해, 위험한 조작을 실행하기 전에 멈추는 후크(Hook)나 모든 조작을 기록하는 메커니즘을 정리한 무료 툴킷을 공개하고 있다.

• 무료 안전 기반: cc-safe-setup (MIT 라이선스 · 위험한 조작의 가드 및 감사 로그)

또한, 이번과 같은 "그달에 새로 발견된 운용의 함정과 대처법"을 매달 정리하여 전달하는 뉴스레터도 시작했다 (첫 달 무료). 일상적인 Issue나 장시간의 자율 운용 중에 빠진 함정을 증상 → 확인 → 대응 순으로 정리하고 있다.

• 매월 운용 뉴스레터: Claude Code 안전 운용 편

곤란을 겪는 분들에게 도움이 되기를 바랍니다. 설정이 원인인 실행 불능 상태는, 침착하게 층을 분리하면 반드시 해결됩니다.