Dépannage

Solutions aux problèmes d'installation et d'exécution courants d'Apothem.

Problèmes d'installationCopy Anchor Link

Aucun Python 3.10+ trouvéCopy Anchor Link

Les installateurs sondent python3, python et les noms versionnés (python3.14 jusqu'à python3.10) — en rejetant les shims du lanceur du Microsoft Store — et s'arrêtent avec No Python >= 3.10 found in PATH lorsqu'aucun candidat ne satisfait le seuil de 3.10. Le shim npx sonde APOTHEM_PYTHON lorsque cette variable est définie, puis python3, python et py -3, et se termine avec le code 1 en affichant son propre message lorsqu'aucun candidat ne convient. Installez CPython 3.10 ou une version plus récente depuis python.org ou le dépôt de paquets de votre OS, confirmez que python3 --version (ou py -3 --version sous Windows) signale au moins 3.10, puis réexécutez.

Dépendances d'exécution manquantes : click, richCopy Anchor Link

Le moteur intègre la plupart de ses dépendances tierces dans l'arborescence source, mais click et rich doivent être importables sous l'interpréteur que l'installateur sélectionne. Lorsque l'un ou l'autre manque, l'installateur le nomme et propose de l'installer pour vous :

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

Acceptez l'invite pour que l'installateur exécute pip install sous cet interpréteur. Pour ignorer l'invite, passez --yes (-Yes sous PowerShell) ou définissez APOTHEM_AUTO_INSTALL_DEPS=1 pour installer automatiquement. Si vous refusez — ou si pip est indisponible, ou si vous préférez le gestionnaire de paquets de votre OS — installez vous-même les paquets nommés (par exemple python3-click et python3-rich sur les hôtes de la famille Debian, ou pip install click rich) puis réexécutez.

apothem introuvable après l'exécution de l'installateurCopy Anchor Link

L'installateur place l'arborescence source dans ~/.apothem et écrit un shim apothem dans ~/.local/bin par défaut (POSIX), ou dans %LOCALAPPDATA%\Microsoft\WindowsApps (Windows). Il ne modifie pas votre PATH. Si apothem est introuvable, ce répertoire ne figure pas dans PATH : ajoutez-le, ou utilisez la forme PYTHONPATH ci-dessous jusqu'à ce que vous le fassiez. Exécutez le moteur avec l'invocation qu'affiche l'installateur à la fin :

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

ou utilisez la forme npx (npx @ahmed-g-gad/apothem <command>), qui ne nécessite aucune entrée dans PATH.

/plugin marketplace add échoueCopy Anchor Link

/plugin marketplace add ahmed-g-gad/apothem récupère la liste du marketplace depuis GitHub. En cas d'échec, confirmez que la machine peut atteindre https://github.com/ahmed-g-gad/apothem (règles de réseau, de proxy ou de pare-feu), puis réessayez. Si le marketplace a été ajouté précédemment lors d'une récupération partielle, supprimez-le et rajoutez-le avant d'exécuter /plugin install apothem@apothem.

L'ajout du marketplace de l'hôte à plugins expireCopy Anchor Link

La commande de l'hôte à plugins qui ajoute un marketplace clone son dépôt et abandonne au bout de 30 secondes. Un clone complet de ce dépôt peut prendre plus de temps sur un disque lent, tel qu'un lecteur Windows sous WSL, et un clone complet antérieur peut aussi laisser le plugin bloqué à une ancienne version lorsqu'une actualisation ultérieure expire. Ne récupérez que les deux dossiers dont le plugin a besoin :

codex plugin marketplace remove apothem
codex plugin marketplace add ahmed-g-gad/apothem --sparse .agents/plugins --sparse plugins/apothem
codex plugin add apothem@apothem

La liste des plugins de l'hôte affiche alors la version actuelle de apothem@apothem.

npx sert une version obsolèteCopy Anchor Link

npx met en cache les paquets téléchargés. Lorsque npx @ahmed-g-gad/apothem --version signale une version plus ancienne que la version actuelle, videz le cache ou épinglez la dist-tag :

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

L'installateur s'arrête : la clé publique du mainteneur n'est pas dans le trousseau localCopy Anchor Link

L'installateur vérifie l'étiquette de publication signée et s'arrête lorsque la clé de signature n'est pas dans votre trousseau. Importez-la une seule fois, vérifiez que l'empreinte affiche 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163, puis relancez l'installateur :

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'

Sous Windows, importez par le bash de Git comme indiqué : git verify-tag lit le trousseau du gpg fourni avec Git for Windows. Un hôte sans gpg peut installer avec APOTHEM_VERIFY=checksum, qui vérifie le condensat de l'archive de publication au lieu de la signature de l'étiquette.

irm / iex bloqués sous WindowsCopy Anchor Link

Si la politique d'exécution de PowerShell bloque l'installateur :

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

Problèmes d'exécutionCopy Anchor Link

apothem install ne trouve aucun environnementCopy Anchor Link

Exécutez apothem doctor pour lire son tableau Harness Status, qui compte une ligne par environnement. Une ligne marquée not installed signifie qu'Apothem n'a trouvé aucune installation pour cet environnement. Une ligne marquée needs --project correspond à un environnement à portée de projet, que doctor ne vérifie que si vous passez --project <path>. Si doctor affiche No harness is installed yet, vérifiez que votre environnement est installé, puis exécutez apothem install --harness <name>.

apothem verify signale un adaptateur défaillantCopy Anchor Link

Réexécutez apothem install pour re-matérialiser l'adaptateur. Si le problème persiste, consultez la page spécifique à l'adaptateur sous Adaptateurs d'environnement.

Les hooks ne se déclenchent pas dans Claude CodeCopy Anchor Link

Confirmez qu'Apothem est bien câblé en vérifiant la présence des entrées de hook dans ~/.claude/settings.json. Si le fichier ne contient pas les hooks, réexécutez apothem install.

Obtenir de l'aideCopy Anchor Link

• GitHub Issues -- signalements de bugs
• GitHub Discussions -- questions
• FAQ -- foire aux questions