Устранение неполадок

Решения для распространённых проблем установки и времени выполнения Apothem.

Проблемы установкиCopy Anchor Link

Не найден Python 3.10+Copy Anchor Link

Установщики проверяют python3, python и версионированные имена (от python3.14 до python3.10) — отклоняя шимы-лаунчеры Microsoft Store — и останавливаются с сообщением No Python >= 3.10 found in PATH, когда ни один кандидат не соответствует порогу 3.10. Шим npx проверяет APOTHEM_PYTHON, если он задан, затем python3, python и py -3, и завершается с кодом 1 и собственным сообщением, когда ни один не подходит. Установите CPython 3.10 или новее с python.org или из репозитория пакетов вашей ОС, убедитесь, что python3 --version (или py -3 --version в Windows) сообщает как минимум 3.10, затем запустите заново.

Отсутствуют зависимости времени выполнения: click, richCopy Anchor Link

Движок вендорит большинство своих сторонних зависимостей внутри дерева исходного кода, но click и rich должны быть импортируемы под интерпретатором, который выбирает установщик. Если какой-либо из них отсутствует, установщик называет его и предлагает установить за вас:

! Missing Python prerequisites under <python>: click rich
  Install click rich under <python> now? [y/N]

Примите запрос, чтобы установщик выполнил pip install под этим интерпретатором. Чтобы пропустить запрос, передайте --yes (-Yes в PowerShell) или задайте APOTHEM_AUTO_INSTALL_DEPS=1 для автоматической установки. Если вы откажетесь — или pip недоступен, или вы предпочитаете менеджер пакетов вашей ОС — установите названные пакеты сами (например, python3-click и python3-rich на хостах семейства Debian, или pip install click rich) и затем запустите заново.

apothem не найден после запуска установщикаCopy Anchor Link

Установщик размещает дерево исходного кода в ~/.apothem и по умолчанию записывает шим apothem в ~/.local/bin (POSIX) или %LOCALAPPDATA%\Microsoft\WindowsApps (Windows). Он не редактирует ваш PATH. Если apothem не найден, значит, этот каталог не входит в PATH: добавьте его или используйте форму с PYTHONPATH ниже, пока не сделаете этого. Запускайте движок через вызов, который установщик выводит по завершении:

PYTHONPATH="$HOME/.apothem/src" python -m apothem <command>

или используйте форму npx (npx @ahmed-g-gad/apothem <command>), которой не нужна запись в PATH.

/plugin marketplace add завершается с ошибкойCopy Anchor Link

/plugin marketplace add ahmed-g-gad/apothem загружает запись маркетплейса с GitHub. Если это не удаётся, убедитесь, что машина может достичь https://github.com/ahmed-g-gad/apothem (правила сети, прокси или брандмауэра), затем повторите. Если маркетплейс был добавлен ранее при частичной загрузке, удалите и добавьте его заново перед запуском /plugin install apothem@apothem.

Добавление маркетплейса хоста плагинов завершается по тайм-аутуCopy Anchor Link

Команда хоста плагинов, добавляющая маркетплейс, клонирует его репозиторий и прекращает попытку через 30 секунд. Полное клонирование этого репозитория может занять больше времени на медленном диске, например на диске Windows под WSL, а ранее выполненное полное клонирование также может оставить плагин на старой версии, когда последующее обновление завершается по тайм-ауту. Загрузите только две папки, которые нужны плагину:

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 выдаёт устаревшую версиюCopy Anchor Link

npx кэширует загруженные пакеты. Если npx @ahmed-g-gad/apothem --version сообщает версию старее текущего релиза, очистите кэш или закрепите dist-тег:

npx clear-npx-cache
npx @ahmed-g-gad/apothem@latest --version

Установщик останавливается: открытого ключа сопровождающего нет в локальной связке ключейCopy Anchor Link

Установщик проверяет подписанный тег релиза и останавливается, если ключа подписи нет в вашей связке ключей. Импортируйте его один раз, проверьте, что отпечаток равен 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 импортируйте ключ через bash Git, как показано выше: git verify-tag читает связку ключей gpg, которая поставляется с Git for Windows. Хост без gpg может выполнить установку с APOTHEM_VERIFY=checksum: тогда вместо подписи тега проверяется контрольная сумма архива релиза.

irm / iex заблокированы в WindowsCopy Anchor Link

Если политика выполнения PowerShell блокирует установщик:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm https://apothem.ahmedgad.com/install.ps1 | iex

Проблемы времени выполненияCopy Anchor Link

apothem install не находит окруженийCopy Anchor Link

Запустите apothem doctor, чтобы прочитать его таблицу Harness Status, в которой одна строка на каждое окружение. Строка с пометкой not installed означает, что Apothem не нашёл установки для этого окружения. Строка с пометкой needs --project относится к окружению с областью проекта, которое doctor проверяет только при передаче --project <path>. Если doctor сообщает No harness is installed yet, убедитесь, что нужное окружение установлено, затем выполните apothem install --harness <name>.

apothem verify сообщает о неисправном адаптереCopy Anchor Link

Повторно запустите apothem install, чтобы заново материализовать адаптер. Если проблема сохраняется, проверьте страницу конкретного адаптера в разделе Адаптеры окружений.

Хуки не срабатывают в Claude CodeCopy Anchor Link

Убедитесь, что Apothem подключён, проверив наличие записей хуков в ~/.claude/settings.json. Если в файле отсутствуют хуки, запустите apothem install снова.

Получение помощиCopy Anchor Link

• GitHub Issues -- отчёты об ошибках
• GitHub Discussions -- вопросы
• ЧаВо -- часто задаваемые вопросы