Solución de problemas comunes de Pi Agent
A continuación se presentan los problemas comunes y sus soluciones durante el uso de Pi Agent.
Problemas de instalación
Esta sección cubre los errores típicos y las rutas de solución en la etapa de instalación.
Error en npm install
Síntoma: tras ejecutar el comando de instalación, se produce un error y el proceso se interrumpe. Los errores comunes se concentran en tres categorías: versión, red y permisos.
| Causas posibles | Método de diagnóstico | Solución |
|---|---|---|
| La versión de Node.js es demasiado baja; Pi Agent requiere Node.js 22.19.0 o superior. | Ejecutenode --versionpara ver la versión actual. | Use nvm para instalar y cambiar a 22 LTS o una versión superior. |
| Problema de red: acceder al registro oficial de npm desde China continental suele provocar tiempos de espera. | Observe si en el mensaje de error aparecen datos de tiempo de espera de red como ETIMEDOUT. | Ejecutenpm config set registry https://registry.npmmirror.comReinstale después de cambiar al registro espejo. |
| Problema de permisos: el directorio de instalación global en macOS/Linux no es escribible para el usuario actual. | Observe si en el mensaje de error aparece un error de permisos EACCES. | Use nvm para gestionar Node.js, o configure el prefijo de npm en el directorio del usuario; evite usar sudo. |
El comando 'pi' no se encuentra después de la instalación
Síntoma: la instalación indica que se completó, pero al escribir 'pi' aparece 'command not found'.
Primero revise el prefijo de instalación global de npm:
$ npm prefix -g /usr/local
Luego confirme si el directorio bin bajo ese prefijo está en PATH:
$ echo $PATH | grep "$(npm prefix -g)/bin" /usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin
Cuando el directorio no está en PATH, este comando no produce ninguna salida:
$ echo $PATH | grep "$(npm prefix -g)/bin"
Si no hay salida, significa que el directorio global bin no está en PATH; esa es la razón por la que no se encuentra el comando 'pi'.
| Causas posibles | Método de diagnóstico | Solución |
|---|---|---|
| El directorio global bin no se ha añadido a PATH. | Use el comando grep anterior para confirmar si hay salida. | tomar$(npm prefix -g)/binAgréguelo a~/.zshrco~/.bashrcla variable PATH; reinicie la terminal para que surta efecto. |
| Se cambió la versión de Node y el enlace simbólico anterior ya no es válido. | Ejecutels $(npm prefix -g)/binpara ver si 'pi' sigue presente. | Vuelva a realizar una instalación global con la versión actual de Node. |
Problemas de autenticación
Esta sección cubre las rutas de solución para el inicio de sesión con /login y los fallos de autenticación de API Key.
Error al iniciar sesión con /login
Síntoma: después de escribir /login, el navegador no puede completar la redirección, o la interfaz permanece esperando la autorización.
| Causas posibles | Método de diagnóstico | Solución |
|---|---|---|
| La suscripción no está en estado válido. | Inicie sesión en el sitio oficial del proveedor para confirmar si la suscripción ha caducado. | Renueve la suscripción o use otro proveedor para iniciar sesión. |
| No se puede acceder al servidor de autenticación del proveedor. | Abra el sitio del proveedor en el navegador para confirmar que la red es accesible. | Reintente después de configurar el proxy; consulte la sección de configuración del proxy más abajo. |
| Usar /login en una conexión remota SSH. | No hay navegador en la máquina remota, por lo que el callback de OAuth no puede llegar. | Copie la URL de autorización, ábrala en el navegador local y luego pegue manualmente la URL de callback para completar el inicio de sesión. |
La API Key no surte efecto
Síntoma: ya se ha exportado la variable de entorno, pero al iniciar sigue indicando que no está autenticado, o continúa usando las credenciales antiguas.
Verifique en el siguiente orden:
| Causas posibles | Método de diagnóstico | Solución |
|---|---|---|
| La variable de entorno no se ha configurado correctamente. | Ejecuteecho $ANTHROPIC_API_KEYpara ver la salida. | Si la salida está vacía, añada el export en el archivo de configuración del shell y vuelva a ejecutar source. |
| auth.jsonYa contiene credenciales con el mismo nombre, que tienen prioridad sobre la variable de entorno. | Revise~/.pi/agent/auth.jsonsi ya existe una entrada para ese proveedor. | Ejecute/logoutElimine las credenciales antiguas o edite directamente auth.json para actualizar la Key. |
| El formato de la API Key es incorrecto. | Compruebe si el contenido copiado incluye espacios o comillas adicionales. | Copie la Key de nuevo por completo y vuelva a configurarla. |
auth.jsonLas credenciales guardadas en el archivo tienen prioridad sobre la variable de entorno.
Cuando la API Key no funcione, revise primero~/.pi/agent/auth.jsonno se fije únicamente en la variable de entorno.
Modelo no disponible
Síntoma: no se encuentra el modelo esperado en la lista de modelos, o se indica falta de permisos al invocarlo.
| Causas posibles | Método de diagnóstico | Solución |
|---|---|---|
| El directorio local de modelos está desactualizado. | Ejecutepi update --modelspara actualizar el directorio de modelos. | Una vez actualizado, vuelva a abrir el selector de modelos. |
| No se sabe qué modelos están disponibles actualmente. | Ejecutepi --list-modelspara ver la lista de modelos disponibles. | Seleccione de la lista un modelo disponible para la cuenta actual. |
| La API Key no tiene permiso de acceso para el modelo correspondiente. | Confirme en la consola del proveedor el alcance de autorización de modelos de esa Key. | Actualice el plan o cambie a un modelo ya autorizado. |
| El modelo de GitHub Copilot muestra 'not supported'. | Confirme si el modelo ya está habilitado en VS Code. | Primero habilite el modelo en VS Code Copilot Chat y luego vuelva a Pi Agent para usarlo. |
Problemas de interfaz
Esta sección cubre tres tipos de anomalías de interfaz: renderizado en terminal, visualización de imágenes y atajos de teclado.
Visualización anómala de la interfaz (colores incorrectos, alineación desordenada)
Síntoma: los colores se ven apagados o distorsionados, y los bordes de las tablas y los cuadros de texto están desalineados.
| Causas posibles | Método de diagnóstico | Solución |
|---|---|---|
| La terminal no es compatible con True Color. | Ejecuteecho $COLORTERMSi la salida indica truecolor o 24bit, es compatible. | Cambie a una terminal compatible con True Color (iTerm2, Windows Terminal, etc.). |
| VS Code ha ajustado automáticamente el contraste de la terminal. | Revise la opción de configuraciónterminal.integrated.minimumContrastRatio | Establezca esa opción en 1. |
| La compatibilidad de renderizado de la terminal actual es deficiente. | Pruebe en otra terminal para confirmar si el problema se reproduce. | Cambie de terminal; se recomienda iTerm2 o Windows Terminal. |
No se pueden mostrar las imágenes
Síntoma: después de enviar o pegar una imagen, solo se ve un marcador de posición o un espacio en blanco en la terminal.
| Causas posibles | Método de diagnóstico | Solución |
|---|---|---|
| La terminal no es compatible con el protocolo de visualización de imágenes. | Confirme si la terminal es compatible con imgcat de iTerm2 o icat de Kitty. | Cambie a una terminal que admita el protocolo de imágenes. |
| La visualización de imágenes se ha desactivado en la configuración. | Reviseterminal.showImagessi es 'true'. | Después de cambiarlo a 'true', ejecute/reloadpara que la configuración surta efecto. |
Los atajos de teclado no funcionan
Síntoma: al pulsar el atajo descrito en la documentación no hay ninguna respuesta, o se activa la función propia de la terminal.
| Causas posibles | Método de diagnóstico | Solución |
|---|---|---|
| La terminal ha interceptado ese atajo de teclado. | Revise la lista de asignaciones de atajos en la configuración de la terminal. | Modifique o libere las asignaciones en conflicto en la terminal. |
| Se ha recordado mal el atajo actual. | Ejecute/hotkeyspara ver todas las asignaciones de atajos actuales. | Opere según las asignaciones reales que aparecen en la lista. |
| Es necesario ajustarlo según las preferencias personales. | Confirme si el archivo de configuración~/.pi/agent/keybindings.jsonexiste. | Edite este archivo para personalizar los atajos de teclado |
Problemas de sesión
Esta sección cubre dos tipos de problemas: archivos de sesión inflados y no encontrar sesiones históricas.
El archivo de sesión es demasiado grande
Síntoma: el uso del contexto sigue aumentando, la respuesta se vuelve lenta o se activa la compresión anticipadamente.
| Posibles causas | Método de diagnóstico | Solución |
|---|---|---|
| El historial de conversación es demasiado largo | Ejecute/sessionVer el número de mensajes y el uso de tokens | Ejecute/compactComprimir el historial de conversación |
| La compresión automática no está habilitada | Verifiquecompaction.enabledsi es true | Después de establecerlo en true, reinicie pi para que surta efecto. |
| El tiempo acumulado de una sola sesión es demasiado largo | usar/sessionObserve el crecimiento del tamaño del archivo de sesión | Periódicamente, utilice/newInicie una nueva sesión y divida las sesiones por tareas. |
No se encuentra la sesión anterior
Síntoma: en la lista de pi -r no se ven los registros de trabajo anteriores.
| Posibles causas | Método de diagnóstico | Solución |
|---|---|---|
| No se utiliza la entrada de restauración | Ejecutepi -rO en el modo interactivo, ingrese /resume para explorar la lista de sesiones | Seleccione la sesión deseada en la lista para restaurarla. |
| sessionDirLa configuración ha sido modificada | Verifique en settings.jsonsessionDirel valor actual de | Vuelva a cambiar al directorio original, o migre los archivos del directorio original al nuevo directorio. |
| Permisos de directorio de sesión anómalos | Ejecutels ~/.pi/agent/sessions/Confirme que se puede leer y escribir. | Ejecutechmod -R u+rw ~/.pi/agent/sessionsRepare los permisos |
Problemas de rendimiento
Esta sección cubre dos tipos de problemas de rendimiento: respuestas lentas y degradación del rendimiento en contextos largos.
La respuesta de la IA es muy lenta
Síntoma: después de enviar una solicitud, no hay salida del primer carácter durante mucho tiempo, o el tiempo total es claramente mayor de lo habitual.
| Posibles causas | Método de diagnóstico | Solución |
|---|---|---|
| Alta latencia de red o enlace no disponible | Ejecuteping api.anthropic.comVer la latencia y la pérdida de paquetes | Cambie de red o configure un proxy según la configuración de proxy a continuación. |
| El nivel de razonamiento es demasiado alto y el tiempo de pensamiento se alarga. | Observe el nivel de razonamiento actual en la barra de estado. | Presione Shift+Tab para reducir el nivel de razonamiento. |
| El mensaje del sistema o el contenido de los archivos de contexto es demasiado extenso. | Verifique el tamaño de los archivos de contexto como AGENTS.md. | Acorte el mensaje del sistema y simplifique el contenido de AGENTS.md. |
| El consumo de tokens en una sola solicitud es demasiado grande. | Ejecute/sessionVer el uso de tokens y la distribución del tiempo de espera. | Ejecute/compacto/newAcorte el contexto y vuelva a intentarlo. |
Si se encuentra en un entorno de proxy, utilicecurl -x $HTTP_PROXY https://api.anthropic.compara probar.
En un entorno de proxy, que ping no responda no significa que la API no esté disponible.
ping utiliza ICMP, la API utiliza HTTPS; en este caso, debe usar curl para verificar el enlace real.
El rendimiento de la IA disminuye después de un contexto extenso
Síntoma: después de que aumentan las rondas de conversación, AI comienza a olvidar los acuerdos anteriores o da respuestas repetidas.
| Posibles causas | Método de diagnóstico | Solución |
|---|---|---|
| El contexto se acerca al límite de la ventana y el contenido temprano se comprime. | Ejecute/sessionVer el uso actual de tokens. | Ejecute manualmente/compactComprimir el contexto |
| Se han mezclado muchos intentos no válidos en los mensajes históricos. | usar/treeVer ramas y conversaciones no válidas | usar/newInicie una nueva sesión y escriba las conclusiones en AGENTS.md. |
| El contenido de los archivos citados no está relacionado con la tarea actual. | Verifique si las referencias @ y los archivos de contexto contienen contenido irrelevante. | Reduzca el contenido innecesario de los archivos de contexto y conserve solo lo que necesita la tarea actual. |
Configuración del proxy
Esta sección explica cómo permitir que Pi Agent acceda normalmente a la API en entornos de red restringidos.
Acceso a la API desde China continental
Configure el proxy HTTP en settings.json:
{
"httpProxy": "http://127.0.0.1:7890"
}
O inicie después de establecer las variables de entorno:
$ export HTTP_PROXY=http://127.0.0.1:7890 $ export HTTPS_PROXY=http://127.0.0.1:7890 $ piOtras extensiones