Resolución de problemas

Soluciones para los problemas habituales de instalación y de tiempo de ejecución de Apothem.

Problemas de instalaciónCopy Anchor Link

No se encuentra Python 3.10+Copy Anchor Link

Los instaladores prueban python3, python y los nombres versionados (python3.14 a python3.10) —rechazando los shims del lanzador de Microsoft Store— y se detienen con No Python >= 3.10 found in PATH cuando ningún candidato cumple el mínimo de 3.10. El shim de npx prueba APOTHEM_PYTHON cuando está definida, después python3, python y py -3, y termina con código 1 y con su propio mensaje cuando ninguno cumple. Instala CPython 3.10 o más reciente desde python.org o el repositorio de paquetes de tu sistema operativo, confirma que python3 --version (o py -3 --version en Windows) informa de al menos la versión 3.10 y vuelve a ejecutar.

Faltan dependencias en tiempo de ejecución: click, richCopy Anchor Link

El motor incorpora la mayoría de sus dependencias de terceros dentro del árbol de código, pero click y rich deben poder importarse bajo el intérprete que el instalador selecciona. Cuando falta alguno de ellos, el instalador lo nombra y se ofrece a instalarlo por ti:

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

Acepta la solicitud para que el instalador ejecute pip install bajo ese intérprete. Para omitir la solicitud, pasa --yes (-Yes en PowerShell) o define APOTHEM_AUTO_INSTALL_DEPS=1 para instalar automáticamente. Si la rechazas —o pip no está disponible, o prefieres el gestor de paquetes de tu sistema operativo— instala tú mismo los paquetes indicados (por ejemplo python3-click y python3-rich en sistemas de la familia Debian, o pip install click rich) y vuelve a ejecutar.

No se encuentra apothem tras ejecutar el instaladorCopy Anchor Link

El instalador coloca el árbol de código fuente en ~/.apothem y escribe un shim apothem en ~/.local/bin por defecto (POSIX) o en %LOCALAPPDATA%\Microsoft\WindowsApps (Windows). No modifica tu PATH. Si apothem no se encuentra, ese directorio no está en PATH: añádelo, o usa la forma con PYTHONPATH que aparece más abajo hasta que lo hagas. Ejecuta el motor mediante la invocación que el instalador imprime al terminar:

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

o usa la forma npx (npx @ahmed-g-gad/apothem <command>), que no necesita ninguna entrada en PATH.

/plugin marketplace add fallaCopy Anchor Link

/plugin marketplace add ahmed-g-gad/apothem obtiene la entrada del marketplace desde GitHub. Cuando falla, confirma que la máquina puede alcanzar https://github.com/ahmed-g-gad/apothem (reglas de red, proxy o cortafuegos) y vuelve a intentarlo. Si el marketplace se añadió antes con una descarga parcial, elimínalo y vuelve a añadirlo antes de ejecutar /plugin install apothem@apothem.

Añadir el marketplace del host de plugin agota el tiempo de esperaCopy Anchor Link

El comando del host de plugin que añade un marketplace clona su repositorio y se rinde al cabo de 30 segundos. Un clon completo de este repositorio puede tardar más en un disco lento, como una unidad de Windows bajo WSL, y un clon completo anterior también puede dejar el plugin atascado en una versión antigua cuando una actualización posterior agota el tiempo de espera. Obtén solo las dos carpetas que necesita el plugin:

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

Al listar los plugins del host se muestra entonces la versión actual de apothem@apothem.

npx sirve una versión obsoletaCopy Anchor Link

npx almacena en caché los paquetes descargados. Cuando npx @ahmed-g-gad/apothem --version informa de una versión más antigua que la versión actual, limpia la caché o fija la dist-tag:

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

El instalador se detiene: la clave pública del mantenedor no está en el llavero localCopy Anchor Link

El instalador verifica la etiqueta de lanzamiento firmada y se detiene cuando la clave de firma no está en tu llavero. Impórtala una vez, comprueba que la huella digital es 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163 y luego vuelve a ejecutar el instalador:

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'

En Windows, importa a través del bash de Git, como se muestra: git verify-tag lee el llavero del gpg que incluye Git for Windows. Un equipo sin gpg puede instalar con APOTHEM_VERIFY=checksum, que comprueba el resumen (digest) del archivo de lanzamiento en lugar de la firma de la etiqueta.

irm / iex bloqueado en WindowsCopy Anchor Link

Si la política de ejecución de PowerShell bloquea el instalador:

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

Problemas en tiempo de ejecuciónCopy Anchor Link

apothem install no encuentra ningún entornoCopy Anchor Link

Ejecuta apothem doctor para leer su tabla Harness Status, que tiene una fila por entorno. Una fila marcada como not installed indica que Apothem no encontró ninguna instalación para ese entorno. Una fila marcada como needs --project corresponde a un entorno de alcance de proyecto, que doctor comprueba solo cuando pasas --project <path>. Si doctor informa No harness is installed yet, asegúrate de que tu entorno esté instalado y, después, ejecuta apothem install --harness <name>.

apothem verify informa de un adaptador que fallaCopy Anchor Link

Vuelve a ejecutar apothem install para volver a materializar el adaptador. Si el problema persiste, consulta la página específica del adaptador en Adaptadores de entorno.

Los hooks no se disparan en Claude CodeCopy Anchor Link

Confirma que Apothem está conectado comprobando que ~/.claude/settings.json contiene las entradas de los hooks. Si al archivo le faltan los hooks, vuelve a ejecutar apothem install.

Cómo obtener ayudaCopy Anchor Link

• GitHub Issues -- informes de errores
• GitHub Discussions -- preguntas
• Preguntas frecuentes -- preguntas frecuentes