Auto-Claude macOS 설치 트러블슈팅 가이드

Auto-Claude는 자율적으로 코딩을 수행하는 멀티 에이전트 프레임워크입니다. macOS에서 DMG 파일로 설치한 후 발생할 수 있는 문제들과 해결 방법을 정리했습니다.

환경

• macOS (Apple Silicon / Intel)
• Python 3.12+ (Homebrew로 설치)
• Auto-Claude 2.7.x (DMG 설치)

---

문제 1: spawn python ENOENT

증상

Context 메뉴에서 프로젝트 분석 시 다음 에러 발생:

Failed to load project index
spawn python ENOENT

원인

macOS에서 Homebrew로 Python을 설치하면 python3 명령어만 생성되고, python 명령어는 생성되지 않습니다. Auto-Claude는 python 명령어를 사용하기 때문에 이 문제가 발생합니다.

해결 방법

1단계: Python 설치 확인

python3 --version  # Python 3.x.x 출력되면 설치됨
python --version   # command not found 발생

2단계: 심볼릭 링크 생성

sudo ln -s $(which python3) /usr/local/bin/python

3단계: 링크 확인

which python
# 출력: /usr/local/bin/python

python --version
# 출력: Python 3.x.x

---

문제 2: 심볼릭 링크 생성 후에도 동일한 에러 발생

증상

python 명령어가 터미널에서는 정상 동작하지만, Auto-Claude 앱에서는 여전히 spawn python ENOENT 에러 발생.

원인

macOS GUI 앱은 터미널과 다른 환경에서 실행되어 /usr/local/bin PATH를 인식하지 못합니다.

해결 방법

방법 A: 터미널에서 앱 실행 (권장)

open -a "Auto-Claude"

참고: 앱 이름에 하이픈이 포함되어 있습니다. Auto Claude가 아닌 Auto-Claude입니다.

방법 B: 시스템 PATH 영구 등록 후 재부팅

sudo launchctl config user path "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"

이후 Mac을 재부팅하면 Dock에서 직접 실행해도 정상 동작합니다.

---

문제 3: ModuleNotFoundError - dotenv

증상

태스크 실행 시 다음 에러 발생:

Traceback (most recent call last):
  File ".../spec_runner.py", line 85, in <module>
    from dotenv import load_dotenv
ModuleNotFoundError: No module named 'dotenv'

원인

Auto-Claude 실행에 필요한 Python 패키지가 설치되지 않았습니다.

해결 방법

pip3 install python-dotenv --break-system-packages

--break-system-packages 플래그는 macOS의 Python 환경 보호 기능(PEP 668)을 우회합니다.

---

문제 4: externally-managed-environment 에러

증상

pip 설치 시 다음 에러 발생:

error: externally-managed-environment
× This environment is externally managed

원인

macOS Sonoma부터 시스템 Python 환경을 보호하기 위해 PEP 668이 적용되었습니다.

해결 방법

모든 pip 설치 명령에 --break-system-packages 플래그를 추가합니다:

pip3 install <패키지명> --break-system-packages

---

문제 5: ModuleNotFoundError - claudeagentsdk

증상

dotenv 설치 후에도 추가 모듈 에러 발생:

ModuleNotFoundError: No module named 'claude_agent_sdk'

원인

Auto-Claude 실행에 필요한 의존성 패키지들이 추가로 필요합니다.

해결 방법

방법 A: requirements.txt로 일괄 설치 (권장)

pip3 install -r /Applications/Auto-Claude.app/Contents/Resources/auto-claude/requirements.txt --break-system-packages

방법 B: 개별 설치

pip3 install python-dotenv claude-agent-sdk --break-system-packages

---

최종 체크리스트

Auto-Claude를 정상적으로 실행하기 위한 체크리스트입니다:

• [ ] Python 3.12+ 설치 확인
• [ ] python 심볼릭 링크 생성
• [ ] 필요한 Python 패키지 설치
• [ ] 터미널에서 앱 실행 또는 시스템 PATH 등록

한번에 설정하기

# 1. python 심볼릭 링크 생성
sudo ln -s $(which python3) /usr/local/bin/python

# 2. 필수 패키지 설치
pip3 install -r /Applications/Auto-Claude.app/Contents/Resources/auto-claude/requirements.txt --break-system-packages

# 3. 앱 실행
open -a "Auto-Claude"

---

참고

• Auto-Claude GitHub Repository
• PEP 668 - Externally Managed Environments
• Auto-Claude는 Claude Pro/Max 구독이 필요합니다.