故障排查

针对常见的 Apothem 安装和运行时问题的解决方案。

安装问题Copy Anchor Link

未找到 Python 3.10+Copy Anchor Link

安装器会探测 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 或你的操作系统软件包仓库安装 CPython 3.10 或更新版本，确认 python3 --version（或 Windows 上的 py -3 --version）报告至少为 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（在 PowerShell 上为 -Yes）或设置 APOTHEM_AUTO_INSTALL_DEPS=1 以自动安装。如果你拒绝——或 pip 不可用，或你更倾向于使用操作系统的软件包管理器——请自行安装所列出的软件包（例如在 Debian 系主机上为 python3-click 和 python3-rich，或 pip install click rich），然后重新运行。

运行安装器后找不到 apothemCopy 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 秒后放弃。在较慢的磁盘上（例如 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 提供过期版本Copy Anchor Link

npx 会缓存已下载的软件包。当 npx @ahmed-g-gad/apothem --version 报告的版本比当前发布版本旧时，请清除缓存或锁定 dist-tag：

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 上，请按上文所示通过 Git 的 bash 导入：git verify-tag 读取的是随 Git for Windows 一同提供的 gpg 的密钥环。若主机没有 gpg，可使用 APOTHEM_VERIFY=checksum 安装，此时安装器会核对发布归档的摘要，而不是标签签名。

Windows 上 irm / iex 被阻止Copy 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 的行是项目作用域的工具，只有在传入 --project <path> 时 doctor 才会检查它。如果 doctor 报告 No harness is installed yet，请先确认你的工具已安装，然后运行 apothem install --harness <name>。

apothem verify 报告某个适配器失败Copy Anchor Link

重新运行 apothem install 以重新物化该适配器。如果问题仍然存在，请查看工具适配器下针对该适配器的专门页面。

Claude Code 中钩子未触发Copy Anchor Link

通过检查 ~/.claude/settings.json 中的钩子条目，确认 Apothem 已接入。如果该文件缺少这些钩子，请再次运行 apothem install。

获取帮助Copy Anchor Link

• GitHub Issues——错误报告
• GitHub Discussions——提问
• 常见问题——常见问题解答