Resolução de problemas

Soluções para problemas comuns de instalação e de tempo de execução do Apothem.

Problemas de instalaçãoCopy Anchor Link

Nenhum Python 3.10+ encontradoCopy Anchor Link

Os instaladores sondam python3, python e os nomes versionados (python3.14 até python3.10) — rejeitando os shims do lançador da Microsoft Store — e param com No Python >= 3.10 found in PATH quando nenhum candidato atinge o piso 3.10. O shim do npx sonda APOTHEM_PYTHON quando essa variável está definida, depois python3, python e py -3, e termina com o código 1 e uma mensagem própria quando nenhum candidato se qualifica. Instale o CPython 3.10 ou mais recente a partir do python.org ou do repositório de pacotes do seu SO, confirme que python3 --version (ou py -3 --version no Windows) reporta pelo menos 3.10 e então execute novamente.

Dependências de tempo de execução ausentes: click, richCopy Anchor Link

O motor incorpora a maior parte de suas dependências de terceiros dentro da árvore de código-fonte, mas click e rich precisam ser importáveis pelo interpretador que o instalador seleciona. Quando qualquer um deles está ausente, o instalador o nomeia e se oferece para instalá-lo para você:

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

Aceite o prompt para que o instalador execute pip install sob esse interpretador. Para pular o prompt, passe --yes (-Yes no PowerShell) ou defina APOTHEM_AUTO_INSTALL_DEPS=1 para instalar automaticamente. Se você recusar — ou se o pip não estiver disponível, ou se você preferir o gerenciador de pacotes do seu SO — instale você mesmo os pacotes indicados (por exemplo, python3-click e python3-rich em hosts da família Debian, ou pip install click rich) e então execute novamente.

apothem não encontrado após executar o instaladorCopy Anchor Link

O instalador coloca a árvore de código-fonte em ~/.apothem e grava um shim apothem em ~/.local/bin por padrão (POSIX) ou em %LOCALAPPDATA%\Microsoft\WindowsApps (Windows). Ele não altera o seu PATH. Se apothem não for encontrado, esse diretório não está no PATH; adicione-o ou use a forma PYTHONPATH abaixo até fazê-lo. Execute o motor pela invocação que o instalador imprime ao concluir:

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

ou use a forma npx (npx @ahmed-g-gad/apothem <command>), que não precisa de uma entrada no PATH.

/plugin marketplace add falhaCopy Anchor Link

/plugin marketplace add ahmed-g-gad/apothem busca a listagem do marketplace no GitHub. Quando falha, confirme que a máquina consegue alcançar https://github.com/ahmed-g-gad/apothem (regras de rede, proxy ou firewall) e tente novamente. Se o marketplace foi adicionado anteriormente com uma busca parcial, remova-o e adicione-o novamente antes de executar /plugin install apothem@apothem.

Adicionar o marketplace do host de plugin expiraCopy Anchor Link

O comando do host de plugin que adiciona um marketplace clona o repositório dele e desiste após 30 segundos. Um clone completo deste repositório pode demorar mais em um disco lento, como uma unidade do Windows sob o WSL, e um clone completo anterior também pode deixar o plugin preso em uma versão antiga quando uma atualização posterior expira. Busque apenas as duas pastas de que o plugin precisa:

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

Listar os plugins do host passa então a mostrar a versão atual de apothem@apothem.

O npx serve uma versão desatualizadaCopy Anchor Link

O npx armazena em cache os pacotes baixados. Quando npx @ahmed-g-gad/apothem --version reporta uma versão mais antiga que o lançamento atual, limpe o cache ou fixe a dist-tag:

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

O instalador é interrompido: a chave pública do mantenedor não está no chaveiro localCopy Anchor Link

O instalador verifica a tag de lançamento assinada e para quando a chave de assinatura não está no seu chaveiro. Importe-a uma vez, confira se a impressão digital é 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163 e execute o instalador novamente:

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'

No Windows, importe pelo bash do Git, como mostrado: o git verify-tag lê o chaveiro do gpg que vem com o Git for Windows. Um host sem gpg pode instalar com APOTHEM_VERIFY=checksum, que confere o digest do arquivo do lançamento em vez da assinatura da tag.

irm / iex bloqueado no WindowsCopy Anchor Link

Se a política de execução do PowerShell bloquear o instalador:

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

Problemas de tempo de execuçãoCopy Anchor Link

apothem install não encontra harnessesCopy Anchor Link

Execute apothem doctor para ler a tabela Harness Status, que tem uma linha por harness. Uma linha marcada como not installed significa que o Apothem não encontrou nenhuma instalação para aquele harness. Uma linha marcada como needs --project é um harness de escopo de projeto, que o doctor verifica somente quando você passa --project <path>. Se o doctor relatar No harness is installed yet, garanta que o seu harness esteja instalado e então execute apothem install --harness <name>.

apothem verify reporta um adaptador com falhaCopy Anchor Link

Execute apothem install novamente para rematerializar o adaptador. Se o problema persistir, verifique a página específica do adaptador em Adaptadores de harness.

Hooks não disparam no Claude CodeCopy Anchor Link

Confirme que o Apothem está conectado verificando se ~/.claude/settings.json contém as entradas de hook. Se o arquivo não tiver os hooks, execute apothem install novamente.

Obter ajudaCopy Anchor Link

• GitHub Issues -- relatórios de bugs
• GitHub Discussions -- perguntas
• Perguntas frequentes -- perguntas frequentes