Individua il problema
Parti dal messaggio visualizzato in Panolayer. Usa la tabella per passare alla soluzione pertinente, quindi controlla il risultato prima di provare il passaggio successivo.
| Cosa non funziona? | Inizia da qui |
|---|---|
| L’installazione o il controllo del sistema non si completa | Installazione e controllo del sistema |
| Il browser esegue l’accesso, ma l’app è ancora in attesa | Completa l’accesso |
| Il tuo repository non si apre o sembra incompleto | Apri il repository corretto |
| Un agent manca, non si avvia o segnala un errore del motore | Avvia un agent |
| Un agent non riesce a leggere o modificare un file | Controlla l’accesso ai file |
| La verifica è interrotta, non disponibile o non conclusa | Ripristina la verifica |
| Una regola descrive il comportamento errato | Esamina la regola e le relative evidenze |
| Un agent si arresta o non riesci a trovare le sue modifiche | Esamina il lavoro dell’agent |
| Un grafo fallisce o restituisce una risposta incompleta | Controlla il passaggio del grafo |
| Un merge va in conflitto o un push non riesce | Risolvi i problemi di merge e push |
| Hai ancora bisogno di aiuto | Segnala un bug riproducibile |
Conserva l’errore e il lavoro. Annota il messaggio esatto e il punto in cui è apparso. Esamina l’esecuzione o il worktree esistente prima di avviare un’altra attività. Non devi eliminare il tuo repository, il worktree dell’agent o le impostazioni per seguire questa guida.
Aiuto per la configurazione
Aspetti ancora l’accesso dal browser?
Scegli Apri di nuovo il browser in Panolayer e completa l’approvazione dell’accesso. Se la richiesta è scaduta, scegli Riprova per avviarne una nuova.
Il browser sta usando l’account sbagliato?
Scegli Cambia account nella pagina di approvazione del browser, quindi accedi con l’account desiderato.
Il programma di installazione del sistema non è più aperto?
Scegli Riapri programma di installazione nella schermata di controllo del sistema di Panolayer, quindi completa l’installazione di Apple Command Line Tools. Panolayer esegue il controllo automaticamente mentre il programma di installazione è in esecuzione.
Per problemi di installazione, verifica o agent, consulta Risoluzione dei problemi.
L’installazione o il controllo del sistema non si completa
Controlla prima il tuo Mac. L’app desktop Panolayer richiede un Mac con Apple silicon con macOS 15 Sequoia o versione successiva. Controlla menu Apple → Informazioni su questo Mac per il chip e la versione di macOS. I Mac Intel non sono supportati.
Se hai scaricato Panolayer ma non è installato: apri il file .dmg, trascina Panolayer in Applicazioni, quindi aprilo da Applicazioni. Segui Installa e configura Panolayer per la sequenza completa.
Se sei bloccato su Un rapido controllo del sistema:
- Scegli Installa accanto a Git — Apple Command Line Tools e completa il programma di installazione di Apple.
- Se hai chiuso il programma di installazione, scegli Riapri programma di installazione in Panolayer.
- Torna a Panolayer dopo l’installazione. Rileva automaticamente gli strumenti; scegli Scegli un progetto quando il controllo è pronto.
Sei pronto a continuare quando Panolayer ti consente di scegliere un progetto. Se il programma di installazione di Apple segnala un errore, includi quell’errore esatto quando chiedi assistenza.
L'accesso non si completa
L'accesso prevede due passaggi: autenticati nel browser, quindi approva quel Mac per l'app Panolayer. Il solo accesso al sito web non completa l'approvazione dell'app.
| Cosa vedi | Cosa fare |
|---|---|
| L'app è in attesa e nessuna pagina del browser è aperta | Seleziona Apri di nuovo il browser in Panolayer. |
| Il browser mostra un account diverso | Seleziona Cambia account, quindi accedi con l'account che vuoi usare nell'app. |
| Il browser ti chiede di approvare questo computer | Confronta il suo codice con Il tuo codice nell'app. Se corrispondono, seleziona Sì, accedi su questo computer. |
| La richiesta è scaduta | Seleziona Riprova in Panolayer e completa la nuova richiesta del browser. |
| Il browser conferma l'approvazione | Torna a Panolayer per continuare la configurazione. |
Usa lo stesso account nell'app e sul sito web. Consulta Accedi per la procedura completa.
Un agent di terze parti ti chiede di accedere separatamente? È l'accesso del fornitore dell'agent. Il tuo account Panolayer non lo sostituisce. Segui le istruzioni di quell'agent e Agent supportati.
Il tuo repository non si apre o sembra incompleto
Il tuo progetto non si apre?
Controlla di aver selezionato la cartella radice di un repository Git locale. Se il tuo repository è ospitato online, clonalo prima sul tuo Mac, poi apri quella cartella in Panolayer.
Scegli Apri progetto… nella schermata iniziale di Panolayer, poi seleziona la cartella radice del tuo repository Git locale. Un URL GitHub non è una cartella locale; clona prima il repository sul tuo Mac usando i tuoi soliti strumenti Git.
Se la mappa sembra incompleta:
- Controlla di aver aperto la radice del repository prevista, non un singolo file o la sottocartella sbagliata.
- Controlla se Panolayer sta ancora analizzando il codice o segnala un errore di indicizzazione. Vedi Recupera verifica.
- Controlla Linguaggi supportati per la tua codebase. Esamina le app e le relazioni mostrate in Architettura, soprattutto in un monorepo.
Un framework rilevato o un file visibile non significa che ogni relazione dinamica possa essere risolta. Vedi Esplora architettura e dipendenze.
Usa l’esempio per confrontare il flusso di lavoro. La documentazione usa Twitter Clone, che si apre come twitter-starter. Il tuo repository avrà file, numero di issue e dipendenze diversi. Non devi passare all’esempio per usare Panolayer.
Un agent non si avvia
Panolayer Agent è integrato. Apri I miei agent, scegli il pulsante + accanto a Monitora agent, quindi seleziona Panolayer Agent. Non richiede un accesso separato al fornitore. Vedi Esegui un agent sul tuo repository.
Per un altro agent: installalo da Marketplace, torna a I miei agent e sceglilo dallo stesso menu. Completa l’accesso al fornitore quando richiesto. L’accesso ai modelli e la fatturazione fanno capo a quel fornitore; consulta Agent supportati per la configurazione pertinente.
Se vedi una scheda di errore dell’agent:
- Apri Dettagli tecnici e leggi l’errore di avvio.
- Se il motore del container non è riuscito ad avviarsi, controlla i requisiti Mac sopra, quindi usa Riprova sulla scheda di errore.
- Se il messaggio indica credenziali mancanti o un problema dell’account, completa l’accesso di quell’agent prima di riprovare.
- Se fallisce di nuovo con lo stesso messaggio, scegli Segnala un bug sulla scheda di errore. Quel percorso include la diagnostica dell’agent. Controlla il report prima di inviarlo.
Un avvio riuscito apre la conversazione dell’agent, così puoi inviare una richiesta. Avviare ripetutamente nuove sessioni non risolve un errore di installazione o dell’account rimasto invariato.
Una richiesta viene rifiutata o l’utilizzo è esaurito
Se Panolayer segnala Hai esaurito l’utilizzo per questo mese, apri Impostazioni → Piano e utilizzo per controllare l’utilizzo e la data di reset dell’account. Ripetere la stessa richiesta non ripristina l’utilizzo esaurito.
Per un agent di terze parti, controlla l’account del fornitore indicato nel relativo errore. Accedere a Panolayer non modifica la quota o la fatturazione di quel fornitore. Risolvi il problema dell’account segnalato prima di riprovare.
Un agent non può leggere o modificare un file
Controlla le impostazioni del file in Architettura. Apri il sorgente del file e scorri verso il basso nel relativo pannello dei dettagli.
| Controllo | Cosa modifica |
|---|---|
| Blocca file, in Blocco implementazione | Impedisce agli agent AI di modificare il file. |
| Nascondi agli agent, in Accesso agent container | Impedisce ai nuovi agent container di leggere il file. Le sessioni agent esistenti non cambiano. |
Se la restrizione è intenzionale, mantienila e chiedi all'agent di lavorare entro i suoi limiti. Se vuoi che l'agent acceda a questo file, modifica deliberatamente il controllo pertinente. Una modifica di visibilità si applica alle nuove sessioni agent container; l'accesso di una sessione esistente non cambia.
Se nessuno dei due controlli spiega il problema, esamina l'errore dell'agent e il workspace che sta usando. Vedi Esamina il lavoro dell'agent.
La verifica non ha un risultato utilizzabile
Apri Problemi e leggi lo stato della verifica prima di decidere cosa fare. Un controllo che non è riuscito a terminare non è un risultato positivo ed è diverso da una regola che ha fallito sul tuo codice.
| Stato o messaggio | Cosa fare dopo |
|---|---|
| Analisi del codice o Verifica delle regole | Segui la fase corrente. Attendi che termini prima di interpretare il risultato. |
| Non ancora indicizzato o Impossibile indicizzare questo progetto | Segui l'azione della scheda per avviare l'indicizzazione o Riprova. Panolayer deve leggere i sorgenti prima di poterli verificare. |
| La verifica è stata interrotta o La verifica richiede attenzione | Leggi l'errore associato, risolvine la causa, quindi scegli Riprova sulla scheda di stato. |
| Impossibile leggere lo stato della verifica | Scegli Riprova per leggere di nuovo lo stato. Il messaggio non stabilisce se il codice ha superato o meno la verifica. |
| Risultati indeterminati | Apri il motivo registrato per ogni elemento. Questi controlli non sono né superati né falliti. |
| Input troppo grande | Riprovare con input invariati non aiuterà. Includi il file interessato e il messaggio visibile in una segnalazione, così il team può indagare. |
| Impossibile completare la valutazione | Risolvi la causa registrata, quindi usa Riprova verifica dove disponibile. |
| Niente da verificare — nessuna modifica per ora | L'agent non ha modifiche da controllare. Esamina la sua attività e il workspace prima di aspettarti un risultato di merge. |
Se l'app segnala che un workspace dell'agent è stato rimosso o non è più monitorato, scegli Torna alla main per continuare a lavorare nel workspace principale. Un risultato precedente non stabilisce lo stato dei file che non vengono più controllati.
Dopo un nuovo tentativo, leggi il nuovo stato. Non considerare un errore scomparso, un elenco di problemi vuoto o un controllo non terminato come prova che il codice sia stato superato. Vedi Comprendere un risultato di verifica.
Una regola sembra errata
Apri Dettagli accanto al problema e confronta l'aspettativa, la spiegazione e il sorgente. Nell'esempio Twitter, clearSaved deve terminare solo dopo il completamento delle rimozioni dei segnalibri; i dettagli mostrano perché il suo codice attuale restituisce troppo presto.
- L'aspettativa è corretta e il codice la viola: scegli Correggi e seleziona Panolayer Agent o un altro agent installato. Segui Correggi il tuo primo bug.
- L'aspettativa descrive il comportamento sbagliato: correggi la regola in modo che corrisponda a ciò che la funzione dovrebbe fare, quindi esegui di nuovo la verifica ed esamina il nuovo risultato.
- L'aspettativa è corretta ma il fallimento segnalato sembra errato: segnala la regola, la spiegazione visibile e un esempio minimo che lo riproduce.
Modificare un'aspettativa è diverso dal correggere il codice. Non indebolire una regola accurata solo per trasformare un fallimento in un esito positivo.
Un agent si arresta o non riesci a trovare le sue modifiche
Open My Agents and return to the conversation for that task. Choose Open on its run card. In Stream, select the relevant activity to inspect the command and its output in the right-hand panel. Read the error before sending another task.
A command or test failed? Check what the output actually says. A missing dependency, a rejected credential, and a failing application test need different fixes. Give the agent the failing command and the result you expect, keeping the follow-up tied to the same task. If the app shows a failure card, use its Technical details, Retry, or Report a bug controls.
The agent finished, but your checkout looks unchanged? Coding work happens in the agent’s worktree, separate from your main workspace. Open Changes and select that agent’s worktree on the right-hand side to see its uncommitted code. You can review worktrees, inspect changes by risk, and commit from Changes.
The run says Done, but the work is not merged? Completion and merge approval are separate. Review the verification summary and changed files, then decide whether to merge. A merge into your branch records the change locally; pushing to your remote is a separate step.
See Follow the agent’s work and Review changes and commit.
A graph step fails or the answer is incomplete
Inspect the step that failed and its output before changing the whole graph.
| What you see | What to check |
|---|---|
| The graph is read-only | Duplicate the built-in graph to edit your own copy. |
| An agent step needs a classification | Select the step and choose its agent classification in the right-hand panel. |
| A script fails immediately | Check Program, one argument per line, and Success exit code. The program must be available where the step runs. |
| The agent doesn’t use the question from this run | Check that Custom instructions includes the Goal variable inserted with @. |
| A failure has nowhere to go | Inspect the red failure route and connect an explicit handler or Failed destination. |
| The graph succeeds but the answer is incomplete | Read the agent step’s output, clarify its instructions, and test the same goal again. |
A successful script step means it met its configured success exit code. Check the actual output and the result you intended, too. After editing a failure route, test that path deliberately.
Follow Build your first AI agent graph for the working example and configuration screenshots.
A merge conflicts, or a push fails
Start in Changes. Select the relevant worktree and inspect what is waiting to be committed or merged. If you already approved an agent merge, find its commit in History before trying to commit the same work again.
If the merge reports conflicts:
- Read the conflict dialog. The agent’s work has not been merged yet, and its worktree remains available.
- Resolve each conflicted file in the agent’s worktree, save it, and stage that resolution with
git addin that worktree. You can also use the dialog’s action to ask the agent to resolve the conflicts, then review its edits. - Choose Refresh status. If the rebase is paused and the conflicts are staged, choose Continue rebase.
- Review the resulting changes, then use Review & retry merge when offered.
Do not resolve a conflict in a different checkout and expect the agent’s worktree to change with it.
If a push fails: read the Git error and check the configured remote and your permission to write to it. If the remote branch has moved on, reconcile the changes using your normal Git workflow before retrying. A local merge or commit remains local until a push succeeds. The Twitter sample may have no remote configured; a local commit is enough to complete its walkthrough.
See Review changes and commit for commit, History, and push controls.
Report a bug
If the problem persists, choose Report a bug in Panolayer, or contact the team. When an agent fails, use Report a bug on its failure card so the report includes that agent’s diagnostics.
You can use this template:
What I was trying to do:
Steps to reproduce:
1.
2.
3.
Expected result:
Actual result:
Exact error or status:
Panolayer version:
Mac chip and macOS version:
Agent name, if relevant:
Does it also happen in the Twitter Clone sample?
Include the file or function name when it helps locate the problem, and note whether it happened in the main workspace or an agent worktree. A small example you can share is more useful than an entire private repository. You don’t need to test the sample if it would interrupt your current work.
The report dialog includes diagnostics and logs, and can attach the current screen. Review the Screenshot attached control and any files you add before sending. Leave out credentials, API keys, and private source code you do not intend to share.
After sending, keep the tracking reference shown in the confirmation so you can refer to the same report when following up.