Encuentra tu problema
Empieza por el mensaje que ves en Panolayer. Usa la tabla para ir a la solución correspondiente y, después, comprueba el resultado antes de probar el paso siguiente.
| ¿Qué va mal? | Empieza aquí |
|---|---|
| La instalación o la comprobación del sistema no termina | Instalación y comprobación del sistema |
| El navegador inicia sesión, pero la app sigue esperando | Terminar el inicio de sesión |
| El repository no se abre o parece incompleto | Abrir el repository correcto |
| Falta un agent, no se inicia o informa de un error del motor | Iniciar un agent |
| Un agent no puede leer o modificar un archivo | Comprobar el acceso a archivos |
| La verificación se interrumpe, no está disponible o queda sin decidir | Recuperar la verificación |
| Una regla describe el comportamiento incorrecto | Inspeccionar la regla y su evidencia |
| Un agent se detiene o no encuentras sus cambios | Inspeccionar el trabajo del agent |
| Un grafo falla o devuelve una respuesta incompleta | Comprobar el paso del grafo |
| Un merge entra en conflicto o falla un push | Resolver problemas de merge y push |
| Aún necesitas ayuda | Informar de un bug reproducible |
Conserva el error y el trabajo. Anota el mensaje exacto y dónde apareció. Inspecciona la ejecución o el worktree existentes antes de iniciar otra tarea. No necesitas eliminar el repository, el worktree del agent ni los ajustes para seguir esta guía.
Ayuda de configuración
¿Sigues esperando el inicio de sesión en el navegador?
Elige Abrir el navegador de nuevo en Panolayer y termina de aprobar el inicio de sesión. Si la solicitud ha caducado, elige Reintentar para iniciar una nueva.
¿El navegador está usando la cuenta equivocada?
Elige Cambiar de cuenta en la página de aprobación del navegador y, después, inicia sesión con la cuenta que quieras.
¿El instalador del sistema ya no está abierto?
Elige Volver a abrir el instalador en la pantalla de comprobación del sistema de Panolayer y termina de instalar Apple Command Line Tools. Panolayer comprueba automáticamente mientras se ejecuta el instalador.
Para problemas de instalación, verificación o agent, consulta Solución de problemas.
La instalación o la comprobación del sistema no termina
Comprueba tu Mac primero. La app de escritorio de Panolayer requiere un Mac con Apple silicon que ejecute macOS 15 Sequoia o posterior. Consulta menú Apple → Acerca de este Mac para ver tu chip y la versión de macOS. Los Mac con Intel no son compatibles.
Si has descargado Panolayer pero no está instalado: abre el .dmg, arrastra Panolayer a Aplicaciones y, después, ábrelo desde Aplicaciones. Sigue Instalar y configurar Panolayer para ver la secuencia completa.
Si te quedas atascado en Una comprobación rápida del sistema:
- Elige Instalar junto a Git — Apple Command Line Tools y termina el instalador de Apple.
- Si has cerrado el instalador, elige Volver a abrir el instalador en Panolayer.
- Vuelve a Panolayer después de la instalación. Detecta las herramientas automáticamente; elige Elegir un proyecto cuando la comprobación esté lista.
Estás listo para continuar cuando Panolayer te permita elegir un proyecto. Si el instalador de Apple informa de un error, incluye ese error exacto cuando pidas ayuda.
El inicio de sesión no se completa
Iniciar sesión tiene dos partes: autentícate en tu navegador y luego aprueba ese Mac para la app Panolayer. Tener la sesión iniciada solo en el sitio web no completa la aprobación de la app.
| Lo que ves | Qué hacer |
|---|---|
| La app está esperando y no hay ninguna página del navegador abierta | Elige Abrir el navegador de nuevo en Panolayer. |
| El navegador muestra otra cuenta | Elige Cambiar de cuenta y luego inicia sesión con la cuenta que quieras usar en la app. |
| El navegador te pide que apruebes este ordenador | Compara su código con Tu código en la app. Cuando coincidan, elige Sí, iniciar sesión en este ordenador. |
| La solicitud ha caducado | Elige Reintentar en Panolayer y completa la nueva solicitud del navegador. |
| El navegador confirma la aprobación | Vuelve a Panolayer para continuar con la configuración. |
Usa la misma cuenta en la app y en el sitio web. Consulta Iniciar sesión para ver el recorrido completo.
¿Un agent de terceros te pide que inicies sesión por separado? Ese es el inicio de sesión del proveedor del agent. Tu cuenta de Panolayer no lo sustituye. Sigue las instrucciones de ese agent y consulta agents compatibles.
Tu repository no se abre o parece incompleto
¿Tu proyecto no se abre?
Comprueba que has seleccionado la carpeta raíz de un repositorio Git local. Si tu repositorio está alojado en línea, clónalo primero en tu Mac y luego abre esa carpeta en Panolayer.
Elige Abrir proyecto… en la pantalla de inicio de Panolayer y, después, selecciona la carpeta raíz de tu repositorio Git local. Una URL de GitHub no es una carpeta local; clona primero el repositorio en tu Mac con tus herramientas Git habituales.
Si el mapa parece incompleto:
- Comprueba que has abierto la raíz del repositorio que querías, y no un archivo individual o una subcarpeta incorrecta.
- Comprueba si Panolayer sigue analizando el código o informa de un error de indexación. Consulta Recuperar la verificación.
- Consulta Lenguajes compatibles para tu base de código. Inspecciona las aplicaciones y relaciones que se muestran en Arquitectura, especialmente en un monorepo.
Que se detecte un framework o que un archivo sea visible no significa que se pueda resolver toda relación dinámica. Consulta Explorar la arquitectura y las dependencias.
Usa el ejemplo para comparar el flujo de trabajo. La documentación usa Twitter Clone, que se abre como twitter-starter. Tu propio repositorio tendrá archivos, recuentos de incidencias y dependencias distintos. No necesitas cambiar al ejemplo para usar Panolayer.
Un agent no se inicia
Panolayer Agent está integrado. Abre Mis agents, elige el botón + que hay junto a Agents de monitorización y luego selecciona Panolayer Agent. No necesita un inicio de sesión independiente del proveedor. Consulta Ejecutar un agent en tu repository.
Para otro agent: instálalo desde Marketplace, vuelve a Mis agents y elígelo en el mismo menú. Completa el inicio de sesión del proveedor cuando se te solicite. Su acceso a modelos y su facturación corresponden a ese proveedor; consulta Agents compatibles para la configuración correspondiente.
Si ves una tarjeta de error de un agent:
- Abre Detalles técnicos y lee el error de inicio.
- Si el motor de contenedores no ha podido iniciarse, comprueba los requisitos de Mac indicados arriba y usa Reintentar en la tarjeta de error.
- Si el mensaje indica credenciales que faltan o un problema de cuenta, termina el inicio de sesión de ese agent antes de reintentar.
- Si vuelve a fallar con el mismo mensaje, elige Informar de un error en la tarjeta de error. Esa vía incluye los diagnósticos del agent. Revisa el informe antes de enviarlo.
Un inicio correcto abre la conversación del agent para que puedas enviar una solicitud. Iniciar sesiones nuevas repetidamente no resuelve un error de instalación o de cuenta que no haya cambiado.
Se rechaza una solicitud o se agota tu uso
Si Panolayer muestra Has agotado el uso de este mes, abre Ajustes → Plan y uso para comprobar el uso y la fecha de restablecimiento de la cuenta. Reintentar la misma solicitud no restaura el uso agotado.
Para un agent de terceros, comprueba la cuenta del proveedor que se indica en su error. Iniciar sesión en Panolayer no cambia la cuota ni la facturación de ese proveedor. Resuelve el problema de cuenta indicado antes de reintentar.
Un agent no puede leer ni modificar un archivo
Comprueba los controles del archivo en Arquitectura. Abre el código fuente del archivo y desplázate hacia abajo en su panel de detalles.
| Control | Qué modifica |
|---|---|
| Bloquear archivo, en Bloqueo de implementación | Impide que los agents de IA modifiquen el archivo. |
| Ocultar a los agents, en Acceso de agents de contenedor | Impide que los nuevos agents de contenedor lean el archivo. Las sesiones de agent existentes no cambian. |
Si la restricción es intencionada, mantenla y pide al agent que trabaje dentro de ella. Si quieres que el agent acceda a este archivo, cambia el control correspondiente de forma deliberada. Un cambio de visibilidad se aplica a las nuevas sesiones de agents de contenedor; el acceso de una sesión existente no cambia.
Si ninguno de los dos controles explica el problema, revisa el error del agent y el espacio de trabajo que está usando. Consulta Inspeccionar el trabajo del agent.
La verificación no tiene un resultado utilizable
Abre Problemas y lee el estado de la verificación antes de decidir qué hacer. Una comprobación que no ha podido finalizar no es un resultado aprobado y es distinta de una regla que ha fallado en tu código.
| Estado o mensaje | Qué hacer a continuación |
|---|---|
| Analizando código o Comprobando reglas | Sigue la etapa actual. Espera a que termine antes de interpretar el resultado. |
| Aún no indexado o No se ha podido indexar este proyecto | Usa la acción de la tarjeta para iniciar la indexación o Reintentar. Panolayer necesita leer las fuentes antes de poder verificarlas. |
| La verificación se interrumpió o La verificación requiere atención | Lee el error que la acompaña, soluciona su causa y elige Reintentar en la tarjeta de estado. |
| No se ha podido leer el estado de la verificación | Elige Reintentar para volver a leer el estado. El mensaje no determina si el código ha pasado o ha fallado. |
| Resultados sin determinar | Abre el motivo registrado de cada elemento. Estas comprobaciones no se consideran ni superadas ni fallidas. |
| Entrada demasiado grande | Reintentar con las mismas entradas no servirá de nada. Incluye el archivo afectado y el mensaje visible en un informe para que el equipo pueda investigarlo. |
| La evaluación no ha podido finalizar | Soluciona la causa registrada y usa Reintentar comprobación donde se ofrezca. |
| Nada que verificar — aún no hay cambios | El agent no tiene cambios que comprobar. Revisa su tarea y su espacio de trabajo antes de esperar un resultado de fusión. |
Si la aplicación indica que se ha eliminado un espacio de trabajo de agent o que ya no se está siguiendo, elige Volver al principal para seguir trabajando en el espacio de trabajo principal. Un resultado antiguo no determina el estado de los archivos que ya no se están comprobando.
Después de reintentar, lee el nuevo estado. No interpretes un error que ha desaparecido, una lista de problemas vacía o una comprobación sin finalizar como prueba de que el código ha pasado. Consulta Entender un resultado de verificación.
Una regla parece incorrecta
Abre Detalles junto a la incidencia y compara la expectativa, la explicación y el código fuente. En el ejemplo de Twitter, se espera que clearSaved termine solo después de que se completen las eliminaciones de marcadores; los detalles muestran por qué su código actual devuelve demasiado pronto.
- La expectativa es correcta y el código la incumple: elige Corregir y selecciona Panolayer Agent u otro agent instalado. Sigue Corrige tu primer bug.
- La expectativa describe el comportamiento incorrecto: corrige la regla para que coincida con lo que debería hacer la función, después vuelve a ejecutar la verificación e inspecciona el nuevo resultado.
- La expectativa es correcta, pero el fallo notificado parece incorrecto: informa de la regla, la explicación visible y un ejemplo mínimo que lo reproduzca.
Cambiar una expectativa es distinto de corregir el código. No debilites una regla precisa solo para convertir un fallo en un aprobado.
Un agent se detiene o no encuentras sus cambios
Abre My Agents y vuelve a la conversación de esa tarea. Elige Open en su tarjeta de ejecución. En Stream, selecciona la actividad relevante para inspeccionar el comando y su salida en el panel derecho. Lee el error antes de enviar otra tarea.
¿Ha fallado un comando o una prueba? Comprueba lo que dice realmente la salida. Una dependencia que falta, una credencial rechazada y una prueba de la aplicación que falla necesitan soluciones distintas. Indica al agent el comando que falla y el resultado que esperas, manteniendo el seguimiento vinculado a la misma tarea. Si la aplicación muestra una tarjeta de fallo, usa sus controles Technical details, Retry o Report a bug.
¿El agent ha terminado, pero tu checkout no ha cambiado? El trabajo de programación se realiza en el worktree del agent, separado de tu espacio de trabajo principal. Abre Changes y selecciona el worktree de ese agent en el lado derecho para ver su código sin commit. Puedes revisar worktrees, inspeccionar cambios por riesgo y hacer commit desde Changes.
¿La ejecución indica Done, pero el trabajo no está fusionado? La finalización y la aprobación de la fusión son independientes. Revisa el resumen de verificación y los archivos modificados, y luego decide si fusionar. Una fusión en tu rama registra el cambio localmente; hacer push a tu remoto es un paso aparte.
Consulta Sigue el trabajo del agent y Revisa los cambios y haz commit.
Un paso del grafo falla o la respuesta está incompleta
Inspecciona el paso que ha fallado y su salida antes de cambiar todo el grafo.
| Lo que ves | Qué comprobar |
|---|---|
| El grafo es de solo lectura | Duplica el grafo integrado para editar tu propia copia. |
| Un paso del agent necesita una clasificación | Selecciona el paso y elige su clasificación de agent en el panel derecho. |
| Un script falla de inmediato | Comprueba Program, un argumento por línea, y Success exit code. El programa debe estar disponible donde se ejecuta el paso. |
| El agent no usa la pregunta de esta ejecución | Comprueba que Custom instructions incluye la variable Goal insertada con @. |
| Un fallo no tiene adónde ir | Inspecciona la ruta de fallo roja y conecta un controlador explícito o un destino Failed. |
| El grafo se completa correctamente, pero la respuesta está incompleta | Lee la salida del paso del agent, aclara sus instrucciones y prueba el mismo objetivo de nuevo. |
Un paso de script correcto significa que cumplió su código de salida de éxito configurado. Comprueba también la salida real y el resultado que pretendías. Después de editar una ruta de fallo, prueba esa ruta a propósito.
Consulta Crea tu primer grafo de agent de IA para ver el ejemplo funcional y las capturas de pantalla de la configuración.
Un merge entra en conflicto o falla un push
Empieza en Cambios. Selecciona el worktree correspondiente y revisa qué está pendiente de commit o de fusión. Si ya aprobaste una fusión de un agent, busca su commit en Historial antes de intentar hacer commit del mismo trabajo otra vez.
Si la fusión informa de conflictos:
- Lee el diálogo de conflictos. El trabajo del agent aún no se ha fusionado y su worktree sigue disponible.
- Resuelve cada archivo en conflicto en el worktree del agent, guárdalo y prepara esa resolución con
git adden ese worktree. También puedes usar la acción del diálogo para pedir al agent que resuelva los conflictos y, después, revisar sus ediciones. - Elige Actualizar estado. Si el rebase está en pausa y los conflictos están preparados, elige Continuar rebase.
- Revisa los cambios resultantes y usa Revisar y reintentar fusión cuando se ofrezca.
No resuelvas un conflicto en otro checkout y esperes que el worktree del agent cambie con él.
Si falla un push: lee el error de Git y comprueba el remoto configurado y tus permisos de escritura en él. Si la rama remota ha avanzado, reconcilia los cambios con tu flujo de trabajo habitual de Git antes de reintentarlo. Una fusión o un commit local siguen siendo locales hasta que un push se complete correctamente. Puede que el ejemplo de Twitter no tenga ningún remoto configurado; basta con un commit local para completar su recorrido.
Consulta Revisar cambios y hacer commit para los controles de commit, Historial y push.
Informar de un error
Si el problema persiste, elige Informar de un error en Panolayer o contacta con el equipo. Cuando falle un agent, usa Informar de un error en su tarjeta de fallo para que el informe incluya los diagnósticos de ese agent.
Puedes usar esta plantilla:
Qué intentaba hacer:
Pasos para reproducirlo:
1.
2.
3.
Resultado esperado:
Resultado real:
Error o estado exacto:
Versión de Panolayer:
Chip del Mac y versión de macOS:
Nombre del agent, si es relevante:
¿Ocurre también en el ejemplo Twitter Clone?
Incluye el nombre del archivo o de la función cuando ayude a localizar el problema e indica si ocurrió en el espacio de trabajo principal o en el worktree de un agent. Un ejemplo pequeño que puedas compartir es más útil que un repository privado entero. No hace falta que pruebes el ejemplo si eso va a interrumpir tu trabajo actual.
El diálogo de informe incluye diagnósticos y registros, y puede adjuntar la pantalla actual. Revisa el control Captura adjunta y los archivos que añadas antes de enviarlo. Omite credenciales, claves de API y código fuente privado que no tengas intención de compartir.
Después de enviarlo, guarda la referencia de seguimiento que aparece en la confirmación para poder consultar el mismo informe cuando hagas seguimiento.