トラブルシューティング
プラグイン、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 ドライブのような低速なディスクではそれより長くかかることがあり、また以前の完全なクローンが原因で、後の更新がタイムアウトしたときにプラグインが古いバージョンのまま止まることもあります。 プラグインが必要とする 2 つのフォルダーだけを取得してください。
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 を実行して、ハーネスごとに 1 行ずつある 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 -- よくある質問