Fehlerbehebung

Lösungen für häufige Apothem-Installations- und Laufzeitprobleme.

InstallationsproblemeCopy Anchor Link

Kein Python 3.10+ gefundenCopy Anchor Link

Die Installer prüfen python3, python und die versionierten Namen (python3.14 bis python3.10) — wobei sie Launcher-Shims des Microsoft Store zurückweisen — und brechen mit No Python >= 3.10 found in PATH ab, wenn kein Kandidat die Untergrenze von 3.10 erfüllt. Der npx-Shim prüft APOTHEM_PYTHON, wenn es gesetzt ist, danach python3, python und py -3 und endet mit Exit-Code 1 und einer eigenen Meldung, wenn keiner die Anforderung erfüllt. Installieren Sie CPython 3.10 oder neuer von python.org oder aus dem Paket-Repository Ihres Betriebssystems, bestätigen Sie, dass python3 --version (oder py -3 --version unter Windows) mindestens 3.10 meldet, und führen Sie den Vorgang dann erneut aus.

Fehlende Laufzeitabhängigkeiten: click, richCopy Anchor Link

Die Engine bündelt die meisten ihrer Drittanbieter-Abhängigkeiten innerhalb des Quellbaums, aber click und rich müssen unter dem vom Installer ausgewählten Interpreter importierbar sein. Fehlt eines davon, benennt der Installer es und bietet an, es für Sie zu installieren:

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

Bestätigen Sie die Abfrage, damit der Installer pip install unter diesem Interpreter ausführt. Um die Abfrage zu überspringen, übergeben Sie --yes (-Yes unter PowerShell) oder setzen Sie APOTHEM_AUTO_INSTALL_DEPS=1, um automatisch zu installieren. Wenn Sie ablehnen — oder pip nicht verfügbar ist oder Sie Ihren OS-Paketmanager bevorzugen — installieren Sie die genannten Pakete selbst (zum Beispiel python3-click und python3-rich auf Hosts der Debian-Familie oder pip install click rich) und führen Sie den Vorgang dann erneut aus.

apothem nach Ausführung des Installers nicht gefundenCopy Anchor Link

Der Installer legt den Quellbaum unter ~/.apothem ab und schreibt standardmäßig einen apothem-Shim nach ~/.local/bin (POSIX) bzw. nach %LOCALAPPDATA%\Microsoft\WindowsApps (Windows). Er ändert Ihren PATH nicht. Wird apothem nicht gefunden, ist dieses Verzeichnis nicht im PATH enthalten; nehmen Sie es auf oder verwenden Sie bis dahin die PYTHONPATH-Form weiter unten. Führen Sie die Engine über den Aufruf aus, den der Installer am Ende ausgibt:

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

oder verwenden Sie die npx-Form (npx @ahmed-g-gad/apothem <command>), die keinen PATH-Eintrag benötigt.

/plugin marketplace add schlägt fehlCopy Anchor Link

/plugin marketplace add ahmed-g-gad/apothem ruft den Marketplace-Eintrag von GitHub ab. Wenn dies fehlschlägt, vergewissern Sie sich, dass der Rechner https://github.com/ahmed-g-gad/apothem erreichen kann (Netzwerk-, Proxy- oder Firewall-Regeln), und versuchen Sie es erneut. Wenn der Marketplace zuvor unter einem unvollständigen Abruf hinzugefügt wurde, entfernen Sie ihn und fügen Sie ihn erneut hinzu, bevor Sie /plugin install apothem@apothem ausführen.

Das Hinzufügen des Marketplace des Plugin-Hosts läuft in eine ZeitüberschreitungCopy Anchor Link

Der Befehl des Plugin-Hosts, der einen Marketplace hinzufügt, klont dessen Repository und gibt nach 30 Sekunden auf. Ein vollständiger Klon dieses Repositorys kann auf einem langsamen Datenträger, etwa einem Windows-Laufwerk unter WSL, länger dauern, und ein früherer vollständiger Klon kann das Plugin außerdem auf einer alten Version festhalten, wenn eine spätere Aktualisierung in eine Zeitüberschreitung läuft. Laden Sie nur die beiden Ordner, die das Plugin benötigt:

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

Die Liste der Plugins des Hosts zeigt danach die aktuelle Version von apothem@apothem.

npx liefert eine veraltete VersionCopy Anchor Link

npx speichert heruntergeladene Pakete zwischen. Wenn npx @ahmed-g-gad/apothem --version eine ältere Version als das aktuelle Release meldet, leeren Sie den Cache oder fixieren Sie den dist-Tag:

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

Der Installer bricht ab: Der öffentliche Maintainer-Schlüssel fehlt im lokalen SchlüsselbundCopy Anchor Link

Der Installer prüft das signierte Release-Tag und bricht ab, wenn der Maintainer-Signaturschlüssel nicht in Ihrem Schlüsselbund liegt. Importieren Sie ihn einmalig, prüfen Sie, dass der Fingerabdruck 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163 lautet, und führen Sie anschließend den Installer erneut aus:

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'

Importieren Sie unter Windows über Gits bash, wie gezeigt: git verify-tag liest den Schlüsselbund des gpg, der mit Git for Windows ausgeliefert wird. Ein Host ohne gpg kann mit APOTHEM_VERIFY=checksum installieren; dann prüft der Installer die Prüfsumme des Release-Archivs statt der Tag-Signatur.

irm / iex unter Windows blockiertCopy Anchor Link

Wenn die PowerShell-Ausführungsrichtlinie den Installer blockiert:

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

LaufzeitproblemeCopy Anchor Link

apothem install findet keine HarnessesCopy Anchor Link

Führen Sie apothem doctor aus, um dessen Tabelle Harness Status zu lesen, die eine Zeile pro Harness enthält. Eine Zeile mit der Markierung not installed bedeutet, dass Apothem für diesen Harness keine Installation gefunden hat. Eine Zeile mit der Markierung needs --project gehört zu einem Harness mit Projekt-Geltungsbereich, den doctor nur prüft, wenn Sie --project <path> angeben. Meldet doctor No harness is installed yet, stellen Sie sicher, dass Ihr Harness installiert ist, und führen Sie anschließend apothem install --harness <name> aus.

apothem verify meldet einen fehlerhaften AdapterCopy Anchor Link

Führen Sie apothem install erneut aus, um den Adapter neu zu materialisieren. Wenn das Problem weiterhin besteht, prüfen Sie die adapterspezifische Seite unter Harness-Adapter.

Hooks werden in Claude Code nicht ausgelöstCopy Anchor Link

Vergewissern Sie sich, dass Apothem eingebunden ist, indem Sie ~/.claude/settings.json auf die Hook-Einträge prüfen. Fehlen die Hooks in der Datei, führen Sie apothem install erneut aus.

Hilfe erhaltenCopy Anchor Link

• GitHub Issues -- Fehlerberichte
• GitHub Discussions -- Fragen
• FAQ -- häufig gestellte Fragen