문제 해결
플러그인, npx, 설치 프로그램 경로 전반에 걸친 일반적인 Apothem 설치 실패 및 런타임 문제에 대한 해결책.
일반적인 Apothem 설치 및 런타임 문제에 대한 해결책입니다.
설치 문제
Python 3.10+를 찾을 수 없음
설치 프로그램은 python3, python, 그리고 버전이 지정된 이름(python3.14부터 python3.10까지)을 탐색하며 — Microsoft Store 런처 심은 거부합니다 — 3.10 하한선을 충족하는 후보가 없으면 No Python >= 3.10 found in PATH라는 메시지와 함께 중단합니다. npx 심은 APOTHEM_PYTHON이 설정되어 있으면 이를 먼저 탐색하고, 그다음 python3, python, py -3을 탐색하며, 조건을 충족하는 후보가 없으면 자체 메시지를 출력하고 종료 코드 1로 종료합니다. python.org 또는 OS 패키지 저장소에서 CPython 3.10 이상을 설치하고, python3 --version(또는 Windows에서 py -3 --version)이 최소 3.10을 보고하는지 확인한 다음, 다시 실행하세요.
런타임 종속성 누락: click, rich
엔진은 대부분의 서드파티 종속성을 소스 트리 내부에 벤더링하지만, click과 rich는 설치 프로그램이 선택한 인터프리터에서 임포트 가능해야 합니다. 둘 중 하나가 누락되면 설치 프로그램은 그것의 이름을 알려 주고 사용자를 대신해 설치하겠다고 제안합니다.
! Missing Python prerequisites under <python>: click rich
Install click rich under <python> now? [y/N]프롬프트를 수락하면 설치 프로그램이 해당 인터프리터에서 pip install을 실행합니다. 프롬프트를 건너뛰려면 --yes(PowerShell에서는 -Yes)를 전달하거나 APOTHEM_AUTO_INSTALL_DEPS=1을 설정하여 자동으로 설치하세요. 거부하거나 — pip을 사용할 수 없거나, OS 패키지 관리자를 선호하는 경우 — 명명된 패키지를 직접 설치한 다음(예: Debian 계열 호스트에서 python3-click 및 python3-rich, 또는 pip install click rich) 다시 실행하세요.
설치 프로그램 실행 후 apothem을 찾을 수 없음
설치 프로그램은 소스 트리를 ~/.apothem에 배치하고, 기본적으로 apothem 심을 ~/.local/bin(POSIX) 또는 %LOCALAPPDATA%\Microsoft\WindowsApps(Windows)에 씁니다. PATH는 수정하지 않습니다. apothem을 찾을 수 없다면 그 디렉터리가 PATH에 없는 것입니다. 디렉터리를 추가하거나, 그렇게 할 때까지 아래의 PYTHONPATH 형식을 사용하세요. 설치 프로그램이 완료될 때 출력하는 호출 방식으로 엔진을 실행하세요.
PYTHONPATH="$HOME/.apothem/src" python -m apothem <command>또는 PATH 항목이 필요 없는 npx 형식(npx @ahmed-g-gad/apothem <command>)을 사용하세요.
/plugin marketplace add가 실패함
/plugin marketplace add ahmed-g-gad/apothem은 GitHub에서 마켓플레이스 목록을 가져옵니다. 실패하는 경우, 머신이 https://github.com/ahmed-g-gad/apothem에 도달할 수 있는지(네트워크, 프록시, 또는 방화벽 규칙) 확인한 다음 다시 시도하세요. 부분 가져오기 상태에서 마켓플레이스가 이전에 추가된 경우, /plugin install apothem@apothem을 실행하기 전에 제거하고 다시 추가하세요.
플러그인 호스트의 마켓플레이스 추가가 시간 초과됨
마켓플레이스를 추가하는 플러그인 호스트의 명령은 해당 저장소를 클론하며 30초가 지나면 포기합니다. 이 저장소의 전체 클론은 WSL 아래의 Windows 드라이브처럼 느린 디스크에서 그보다 오래 걸릴 수 있으며, 이전에 받은 전체 클론 때문에 이후의 새로 고침이 시간 초과될 때 플러그인이 오래된 버전에 머물 수도 있습니다. 플러그인에 필요한 두 폴더만 가져오세요:
codex plugin marketplace remove apothem
codex plugin marketplace add ahmed-g-gad/apothem --sparse .agents/plugins --sparse plugins/apothem
codex plugin add apothem@apothem그러면 호스트의 플러그인 목록에 apothem@apothem의 현재 버전이 표시됩니다.
npx가 오래된 버전을 제공함
npx는 다운로드된 패키지를 캐시합니다. npx @ahmed-g-gad/apothem --version이 현재 릴리스보다 이전 버전을 보고하는 경우, 캐시를 지우거나 dist-tag를 고정하세요.
npx clear-npx-cache
npx @ahmed-g-gad/apothem@latest --version설치 프로그램 중단: 메인테이너 공개 키가 로컬 키링에 없습니다
설치 프로그램은 서명된 릴리스 태그를 검증하며, 서명 키가 키링에 없으면 중단합니다. 키를 한 번 가져오고, 지문이 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163인지 확인한 다음, 설치 프로그램을 다시 실행하세요:
curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import
gpg --fingerprint 70396FED9C634163& "$env:ProgramFiles\Git\bin\bash.exe" -c 'curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import && gpg --fingerprint 70396FED9C634163'Windows에서는 위와 같이 Git의 bash를 통해 가져오세요. git verify-tag는 Git for Windows에 포함된 gpg의 키링을 읽습니다. gpg가 없는 호스트는 APOTHEM_VERIFY=checksum을 설정하여 설치할 수 있으며, 이 설정은 태그 서명 대신 릴리스 아카이브의 다이제스트를 검사합니다.
Windows에서 irm / iex가 차단됨
PowerShell 실행 정책이 설치 프로그램을 차단하는 경우:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm https://apothem.ahmedgad.com/install.ps1 | iex런타임 문제
apothem install이 하니스를 찾지 못함
apothem doctor를 실행하여 하니스마다 한 행씩 있는 Harness Status 표를 확인하세요. not installed로 표시된 행은 Apothem이 해당 하니스의 설치를 찾지 못했다는 뜻입니다. needs --project로 표시된 행은 프로젝트 범위 하니스이며, doctor는 --project <path>를 전달할 때만 이를 검사합니다. doctor가 No harness is installed yet을 보고하면 하니스가 설치되어 있는지 확인한 다음 apothem install --harness <name>을 실행하세요.
apothem verify가 실패한 어댑터를 보고함
apothem install을 다시 실행하여 어댑터를 다시 머티리얼라이즈하세요. 문제가 지속되면 하니스 어댑터 아래의 어댑터별 페이지를 확인하세요.
Claude Code에서 훅이 실행되지 않음
~/.claude/settings.json에서 훅 항목을 확인하여 Apothem이 연결되어 있는지 확인하세요. 파일에 훅이 누락된 경우, apothem install을 다시 실행하세요.
도움 받기
- GitHub Issues -- 버그 신고
- GitHub Discussions -- 질문
- FAQ -- 자주 묻는 질문