--- read_when: - L'hub per la risoluzione dei problemi ti ha indirizzato qui per una diagnosi più approfondita - Servono sezioni di runbook stabili basate sui sintomi con comandi esatti sidebarTitle: Troubleshooting summary: Runbook approfondito per la risoluzione dei problemi di Gateway, canali, automazione, nodi e browser title: Risoluzione dei problemi x-i18n: generated_at: "2026-05-11T20:30:00Z" model: gpt-5.5 provider: openai source_hash: 146a593493ce265da9a24660e8a9fc2effa25cae16cf00bf77cc1f2fec84275d source_path: gateway/troubleshooting.md workflow: 16 --- Questa pagina è il runbook approfondito. Inizia da [/help/troubleshooting](/it/help/troubleshooting) se vuoi prima il flusso di triage rapido. ## Scala dei comandi Esegui prima questi, in questo ordine: ```bash openclaw status openclaw gateway status openclaw logs --follow openclaw doctor openclaw channels status --probe ``` Segnali attesi di stato sano: - `openclaw gateway status` mostra `Runtime: running`, `Connectivity probe: ok` e una riga `Capability: ...`. - `openclaw doctor` non segnala problemi bloccanti di configurazione/servizio. - `openclaw channels status --probe` mostra lo stato live del trasporto per account e, dove supportato, risultati di probe/audit come `works` o `audit ok`. ## Installazioni split brain e guardia per configurazioni più nuove Usa questa se un servizio Gateway si arresta inaspettatamente dopo un aggiornamento, oppure se i log mostrano che un binario `openclaw` è più vecchio della versione che ha scritto per ultima `openclaw.json`. OpenClaw contrassegna le scritture di configurazione con `meta.lastTouchedVersion`. I comandi in sola lettura possono ancora ispezionare una configurazione scritta da un OpenClaw più nuovo, ma le mutazioni di processo e servizio rifiutano di continuare da un binario più vecchio. Le azioni bloccate includono avvio, arresto, riavvio e disinstallazione del servizio Gateway, reinstallazione forzata del servizio, avvio del Gateway in modalità servizio e pulizia della porta con `gateway --force`. ```bash which openclaw openclaw --version openclaw gateway status --deep openclaw config get meta.lastTouchedVersion ``` Correggi `PATH` in modo che `openclaw` punti all'installazione più nuova, poi riesegui l'azione. Reinstalla il servizio Gateway previsto dall'installazione più nuova: ```bash openclaw gateway install --force openclaw gateway restart ``` Rimuovi il pacchetto di sistema obsoleto o le vecchie voci wrapper che puntano ancora a un vecchio binario `openclaw`. Solo per downgrade intenzionale o ripristino di emergenza, imposta `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` per il singolo comando. Lascialo non impostato per il funzionamento normale. ## Symlink Skills ignorato come escape di percorso Usa questa quando i log includono: ```text Skipping escaped skill path outside its configured root: ... reason=symlink-escape ``` OpenClaw tratta ogni radice di Skills come un perimetro di contenimento. Un symlink sotto `~/.agents/skills`, `/.agents/skills`, `/skills` o `~/.openclaw/skills` viene ignorato quando il suo target reale si risolve fuori da quella radice, a meno che il target non sia esplicitamente considerato attendibile. Ispeziona il link: ```bash ls -l ~/.agents/skills/ realpath ~/.agents/skills/ openclaw config get skills.load ``` Se il target è intenzionale, configura sia la radice Skills diretta sia il target symlink consentito: ```json5 { skills: { load: { extraDirs: ["~/Projects/manager/skills"], allowSymlinkTargets: ["~/Projects/manager/skills"], }, }, } ``` Poi avvia una nuova sessione o attendi che il watcher delle Skills si aggiorni. Riavvia il Gateway se il processo in esecuzione precede la modifica della configurazione. Non usare target ampi come `~`, `/` o un'intera cartella di progetto sincronizzata. Mantieni `allowSymlinkTargets` limitato alla radice Skills reale che contiene directory `SKILL.md` attendibili. Correlati: - [Configurazione Skills](/it/tools/skills-config#symlinked-sibling-repos) - [Esempi di configurazione](/it/gateway/configuration-examples#symlinked-sibling-skill-repo) ## Anthropic 429: utilizzo extra richiesto per contesto lungo Usa questa quando log/errori includono: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. ```bash openclaw logs --follow openclaw models status openclaw config get agents.defaults.models ``` Cerca: - Il modello Anthropic Opus/Sonnet selezionato ha `params.context1m: true`. - La credenziale Anthropic corrente non è idonea all'uso del contesto lungo. - Le richieste falliscono solo su sessioni/esecuzioni di modelli lunghe che richiedono il percorso beta 1M. Opzioni di correzione: Disabilita `context1m` per quel modello per tornare alla finestra di contesto normale. Usa una credenziale Anthropic idonea alle richieste con contesto lungo, oppure passa a una chiave API Anthropic. Configura modelli di fallback in modo che le esecuzioni continuino quando le richieste Anthropic con contesto lungo vengono rifiutate. Correlati: - [Anthropic](/it/providers/anthropic) - [Uso dei token e costi](/it/reference/token-use) - [Perché vedo HTTP 429 da Anthropic?](/it/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) ## Il backend locale compatibile con OpenAI supera i probe diretti ma le esecuzioni agent falliscono Usa questa quando: - `curl ... /v1/models` funziona - le piccole chiamate dirette a `/v1/chat/completions` funzionano - le esecuzioni di modelli OpenClaw falliscono solo nei turni agent normali ```bash curl http://127.0.0.1:1234/v1/models curl http://127.0.0.1:1234/v1/chat/completions \ -H 'content-type: application/json' \ -d '{"model":"","messages":[{"role":"user","content":"hi"}],"stream":false}' openclaw infer model run --model --prompt "hi" --json openclaw logs --follow ``` Cerca: - le piccole chiamate dirette riescono, ma le esecuzioni OpenClaw falliscono solo con prompt più grandi - errori `model_not_found` o 404 anche se `/v1/chat/completions` diretto funziona con lo stesso id modello semplice - errori del backend su `messages[].content` che si aspetta una stringa - avvisi intermittenti `incomplete turn detected ... stopReason=stop payloads=0` con un backend locale compatibile con OpenAI - crash del backend che compaiono solo con conteggi di prompt-token più grandi o prompt completi del runtime agent - `model_not_found` con un server locale in stile MLX/vLLM → verifica che `baseUrl` includa `/v1`, che `api` sia `"openai-completions"` per backend `/v1/chat/completions` e che `models.providers..models[].id` sia l'id semplice locale del provider. Selezionalo una volta con il prefisso del provider, ad esempio `mlx/mlx-community/Qwen3-30B-A3B-6bit`; mantieni la voce di catalogo come `mlx-community/Qwen3-30B-A3B-6bit`. - `messages[...].content: invalid type: sequence, expected a string` → il backend rifiuta parti di contenuto strutturato di Chat Completions. Correzione: imposta `models.providers..models[].compat.requiresStringContent: true`. - `validation.keys` o chiavi di messaggio consentite come `["role","content"]` → il backend rifiuta metadati di replay in stile OpenAI sui messaggi Chat Completions. Correzione: imposta `models.providers..models[].compat.strictMessageKeys: true`. - `incomplete turn detected ... stopReason=stop payloads=0` → il backend ha completato la richiesta Chat Completions ma non ha restituito testo dell'assistente visibile all'utente per quel turno. OpenClaw ritenta una volta i turni vuoti compatibili con OpenAI e sicuri per il replay; i fallimenti persistenti di solito indicano che il backend sta emettendo contenuto vuoto/non testuale o sopprimendo il testo della risposta finale. - le piccole richieste dirette riescono, ma le esecuzioni agent OpenClaw falliscono con crash del backend/modello (per esempio Gemma su alcune build `inferrs`) → il trasporto OpenClaw è probabilmente già corretto; il backend sta fallendo sulla forma più grande del prompt di runtime agent. - i fallimenti si riducono dopo aver disabilitato gli strumenti ma non scompaiono → gli schemi degli strumenti erano parte della pressione, ma il problema restante è ancora la capacità del modello/server a monte o un bug del backend. 1. Imposta `compat.requiresStringContent: true` per backend Chat Completions che accettano solo stringhe. 2. Imposta `compat.strictMessageKeys: true` per backend Chat Completions rigorosi che accettano solo `role` e `content` in ogni messaggio. 3. Imposta `compat.supportsTools: false` per modelli/backend che non riescono a gestire in modo affidabile la superficie degli schemi strumenti di OpenClaw. 4. Riduci la pressione del prompt dove possibile: bootstrap del workspace più piccolo, cronologia sessione più breve, modello locale più leggero o un backend con supporto più robusto per contesti lunghi. 5. Se le piccole richieste dirette continuano a riuscire mentre i turni agent OpenClaw continuano a crashare dentro il backend, trattalo come una limitazione del server/modello a monte e apri lì una riproduzione con la forma del payload accettato. Correlati: - [Configurazione](/it/gateway/configuration) - [Modelli locali](/it/gateway/local-models) - [Endpoint compatibili con OpenAI](/it/gateway/configuration-reference#openai-compatible-endpoints) ## Nessuna risposta Se i canali sono attivi ma nulla risponde, controlla routing e policy prima di riconnettere qualsiasi cosa. ```bash openclaw status openclaw channels status --probe openclaw pairing list --channel [--account ] openclaw config get channels openclaw logs --follow ``` Cerca: - Pairing in sospeso per i mittenti DM. - Gating delle menzioni nei gruppi (`requireMention`, `mentionPatterns`). - Disallineamenti dell'allowlist di canale/gruppo. Firme comuni: - `drop guild message (mention required` → messaggio di gruppo ignorato fino alla menzione. - `pairing request` → il mittente richiede approvazione. - `blocked` / `allowlist` → il mittente/canale è stato filtrato dalla policy. Correlati: - [Risoluzione dei problemi dei canali](/it/channels/troubleshooting) - [Gruppi](/it/channels/groups) - [Pairing](/it/channels/pairing) ## Connettività dell'UI di controllo della dashboard Quando la dashboard/UI di controllo non si connette, valida URL, modalità di autenticazione e presupposti di contesto sicuro. ```bash openclaw gateway status openclaw status openclaw logs --follow openclaw doctor openclaw gateway status --json ``` Cerca: - URL di probe e URL della dashboard corretti. - Disallineamento modalità/token di autenticazione tra client e Gateway. - Uso di HTTP dove è richiesta l'identità del dispositivo. - `device identity required` → contesto non sicuro o autenticazione dispositivo mancante. - `origin not allowed` → l'`Origin` del browser non è in `gateway.controlUi.allowedOrigins` (oppure ti stai connettendo da un'origine browser non loopback senza un'allowlist esplicita). - `device nonce required` / `device nonce mismatch` → il client non completa il flusso di autenticazione dispositivo basato su challenge (`connect.challenge` + `device.nonce`). - `device signature invalid` / `device signature expired` → il client ha firmato il payload sbagliato (o un timestamp obsoleto) per l'handshake corrente. - `AUTH_TOKEN_MISMATCH` con `canRetryWithDeviceToken=true` → il client può eseguire un solo tentativo attendibile con token dispositivo in cache. - Quel ritentativo con token in cache riutilizza l'insieme di ambiti in cache memorizzato con il token dispositivo associato. I chiamanti con `deviceToken` esplicito / `scopes` espliciti mantengono invece il proprio insieme di ambiti richiesto. - `AUTH_SCOPE_MISMATCH` → il token dispositivo è stato riconosciuto, ma i suoi ambiti approvati non coprono questa richiesta di connessione; riassocia o approva il contratto di ambiti richiesto invece di ruotare un token Gateway condiviso. - Fuori da quel percorso di ritentativo, la precedenza dell'autenticazione di connessione è prima token/password condivisi espliciti, poi `deviceToken` esplicito, poi token dispositivo memorizzato, poi token bootstrap. - Nel percorso async della UI di controllo Tailscale Serve, i tentativi falliti per lo stesso `{scope, ip}` vengono serializzati prima che il limiter registri il fallimento. Due ritentativi concorrenti errati dallo stesso client possono quindi mostrare `retry later` al secondo tentativo invece di due semplici mismatch. - `too many failed authentication attempts (retry later)` da un client loopback con origine browser → fallimenti ripetuti dalla stessa `Origin` normalizzata vengono bloccati temporaneamente; un'altra origine localhost usa un bucket separato. - `unauthorized` ripetuto dopo quel ritentativo → deriva tra token condiviso/token dispositivo; aggiorna la configurazione del token e riapprova/ruota il token dispositivo se necessario. - `gateway connect failed:` → target host/porta/url errato. ### Mappa rapida dei codici di dettaglio autenticazione Usa `error.details.code` dalla risposta `connect` fallita per scegliere l'azione successiva: | Codice dettaglio | Significato | Azione consigliata | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AUTH_TOKEN_MISSING` | Il client non ha inviato un token condiviso richiesto. | Incolla/imposta il token nel client e riprova. Per i percorsi della dashboard: `openclaw config get gateway.auth.token`, quindi incollalo nelle impostazioni della Control UI. | | `AUTH_TOKEN_MISMATCH` | Il token condiviso non corrispondeva al token di autenticazione del gateway. | Se `canRetryWithDeviceToken=true`, consenti un solo nuovo tentativo attendibile. I tentativi con token in cache riutilizzano gli ambiti approvati memorizzati; i chiamanti espliciti `deviceToken` / `scopes` mantengono gli ambiti richiesti. Se l'errore persiste, esegui la [checklist di recupero della deriva del token](/it/cli/devices#token-drift-recovery-checklist). | | `AUTH_DEVICE_TOKEN_MISMATCH` | Il token per dispositivo memorizzato nella cache è obsoleto o revocato. | Ruota/riapprova il token del dispositivo usando la [CLI dei dispositivi](/it/cli/devices), quindi riconnettiti. | | `AUTH_SCOPE_MISMATCH` | Il token del dispositivo è valido, ma il suo ruolo/i suoi ambiti approvati non coprono questa richiesta di connessione. | Associa nuovamente il dispositivo o approva il contratto di ambito richiesto; non trattarlo come deriva del token condiviso. | | `PAIRING_REQUIRED` | L'identità del dispositivo richiede approvazione. Controlla `error.details.reason` per `not-paired`, `scope-upgrade`, `role-upgrade` o `metadata-upgrade`, e usa `requestId` / `remediationHint` quando presenti. | Approva la richiesta in sospeso: `openclaw devices list`, quindi `openclaw devices approve `. Gli upgrade di ambito/ruolo usano lo stesso flusso dopo aver esaminato l'accesso richiesto. | Gli RPC backend loopback diretti autenticati con il token/password condiviso del gateway non dovrebbero dipendere dalla baseline degli ambiti dei dispositivi associati della CLI. Se subagent o altre chiamate interne continuano a fallire con `scope-upgrade`, verifica che il chiamante usi `client.id: "gateway-client"` e `client.mode: "backend"` e che non forzi un `deviceIdentity` esplicito o un token dispositivo. Controllo della migrazione dell'autenticazione dispositivo v2: ```bash openclaw --version openclaw doctor openclaw gateway status ``` Se i log mostrano errori di nonce/firma, aggiorna il client di connessione e verificalo: Il client attende il `connect.challenge` emesso dal gateway. Il client firma il payload vincolato alla challenge. Il client invia `connect.params.device.nonce` con lo stesso nonce della challenge. Se `openclaw devices rotate` / `revoke` / `remove` viene negato inaspettatamente: - le sessioni con token di dispositivo associato possono gestire solo il **proprio** dispositivo, a meno che il chiamante non abbia anche `operator.admin` - `openclaw devices rotate --scope ...` può richiedere solo ambiti operatore già posseduti dalla sessione chiamante Correlati: - [Configurazione](/it/gateway/configuration) (modalità di autenticazione del gateway) - [Control UI](/it/web/control-ui) - [Dispositivi](/it/cli/devices) - [Accesso remoto](/it/gateway/remote) - [Autenticazione proxy attendibile](/it/gateway/trusted-proxy-auth) ## Servizio Gateway non in esecuzione Usa questa se il servizio è installato ma il processo non rimane attivo. ```bash openclaw gateway status openclaw status openclaw logs --follow openclaw doctor openclaw gateway status --deep # also scan system-level services ``` Cerca: - `Runtime: stopped` con suggerimenti di uscita. - Mancata corrispondenza della configurazione del servizio (`Config (cli)` rispetto a `Config (service)`). - Conflitti di porta/listener. - Installazioni launchd/systemd/schtasks extra quando viene usato `--deep`. - Suggerimenti di pulizia `Other gateway-like services detected (best effort)`. - `Gateway start blocked: set gateway.mode=local` o `existing config is missing gateway.mode` → la modalità gateway locale non è abilitata, oppure il file di configurazione è stato sovrascritto e ha perso `gateway.mode`. Correzione: imposta `gateway.mode="local"` nella configurazione, oppure riesegui `openclaw onboard --mode local` / `openclaw setup` per ristampare la configurazione prevista in modalità locale. Se esegui OpenClaw tramite Podman, il percorso di configurazione predefinito è `~/.openclaw/openclaw.json`. - `refusing to bind gateway ... without auth` → bind non-loopback senza un percorso di autenticazione gateway valido (token/password, oppure trusted-proxy dove configurato). - `another gateway instance is already listening` / `EADDRINUSE` → conflitto di porta. - `Other gateway-like services detected (best effort)` → esistono unità launchd/systemd/schtasks obsolete o parallele. La maggior parte delle configurazioni dovrebbe mantenere un solo gateway per macchina; se ne serve più di uno, isola porte + configurazione/stato/workspace. Vedi [/gateway#multiple-gateways-same-host](/it/gateway#multiple-gateways-same-host). - `System-level OpenClaw gateway service detected` da doctor → esiste un'unità systemd di sistema mentre il servizio a livello utente manca. Rimuovi o disabilita il duplicato prima di consentire a doctor di installare un servizio utente, oppure imposta `OPENCLAW_SERVICE_REPAIR_POLICY=external` se l'unità di sistema è il supervisore previsto. - `Gateway service port does not match current gateway config` → il supervisore installato impone ancora il vecchio `--port`. Esegui `openclaw doctor --fix` o `openclaw gateway install --force`, quindi riavvia il servizio gateway. Correlati: - [Exec in background e strumento di processo](/it/gateway/background-process) - [Configurazione](/it/gateway/configuration) - [Doctor](/it/gateway/doctor) ## Gateway ha rifiutato una configurazione non valida Usa questa se l'avvio del Gateway fallisce con `Invalid config` o i log del ricaricamento a caldo indicano che ha ignorato una modifica non valida. ```bash openclaw logs --follow openclaw config file openclaw config validate openclaw doctor ``` Cerca: - `Invalid config at ...` - `config reload skipped (invalid config): ...` - `Config write rejected: ...` - Un file `openclaw.json.rejected.*` con timestamp accanto alla configurazione attiva - Un file `openclaw.json.clobbered.*` con timestamp se `doctor --fix` ha riparato una modifica diretta non valida - La configurazione non è stata convalidata durante l'avvio, il ricaricamento a caldo o una scrittura di proprietà di OpenClaw. - L'avvio del Gateway fallisce in modo chiuso invece di riscrivere `openclaw.json`. - Il ricaricamento a caldo ignora le modifiche esterne non valide e mantiene attiva la configurazione runtime corrente. - Le scritture di proprietà di OpenClaw rifiutano payload non validi/distruttivi prima del commit e salvano `.rejected.*`. - `openclaw doctor --fix` è responsabile della riparazione. Può rimuovere prefissi non JSON o ripristinare l'ultima copia valida nota, preservando il payload rifiutato come `.clobbered.*`. ```bash CONFIG="$(openclaw config file)" ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)" openclaw config validate openclaw doctor ``` - `.clobbered.*` esiste → doctor ha preservato una modifica esterna non valida mentre riparava la configurazione attiva. - `.rejected.*` esiste → una scrittura di configurazione di proprietà di OpenClaw ha fallito i controlli di schema o clobber prima del commit. - `Config write rejected:` → la scrittura ha tentato di rimuovere la forma richiesta, ridurre drasticamente il file o persistere una configurazione non valida. - `config reload skipped (invalid config):` → una modifica diretta ha fallito la validazione ed è stata ignorata dal Gateway in esecuzione. - `Invalid config at ...` → l'avvio è fallito prima che i servizi Gateway si avviassero. - `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` o `size-drop-vs-last-good:*` → una scrittura di proprietà di OpenClaw è stata rifiutata perché ha perso campi o dimensione rispetto al backup dell'ultima versione valida nota. - `Config last-known-good promotion skipped` → il candidato conteneva segnaposto di segreti redatti, come `***`. 1. Esegui `openclaw doctor --fix` per lasciare che doctor ripari una configurazione con prefissi/clobbered o ripristini l'ultima versione valida nota. 2. Copia solo le chiavi previste da `.clobbered.*` o `.rejected.*`, quindi applicale con `openclaw config set` o `config.patch`. 3. Esegui `openclaw config validate` prima di riavviare. 4. Se modifichi a mano, mantieni l'intera configurazione JSON5, non solo l'oggetto parziale che volevi cambiare. Correlati: - [Config](/it/cli/config) - [Configurazione: ricaricamento a caldo](/it/gateway/configuration#config-hot-reload) - [Configurazione: validazione rigorosa](/it/gateway/configuration#strict-validation) - [Doctor](/it/gateway/doctor) ## Avvisi del probe Gateway Usa questa se `openclaw gateway probe` raggiunge qualcosa, ma stampa comunque un blocco di avviso. ```bash openclaw gateway probe openclaw gateway probe --json openclaw gateway probe --ssh user@gateway-host ``` Cerca: - `warnings[].code` e `primaryTargetId` nell'output JSON. - Se l'avviso riguarda fallback SSH, gateway multipli, ambiti mancanti o riferimenti di autenticazione non risolti. Firme comuni: - `SSH tunnel failed to start; falling back to direct probes.` → configurazione SSH non riuscita, ma il comando ha comunque provato i target diretti configurati/loopback. - `multiple reachable gateways detected` → ha risposto più di un target. Di solito significa una configurazione multi-gateway intenzionale o listener obsoleti/duplicati. - `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → la connessione ha funzionato, ma l'RPC di dettaglio è limitato dagli ambiti; associa l'identità del dispositivo o usa credenziali con `operator.read`. - `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → la connessione ha funzionato, ma l'intero set di RPC diagnostici è scaduto o non è riuscito. Trattalo come un Gateway raggiungibile con diagnostica degradata; confronta `connect.ok` e `connect.rpcOk` nell'output `--json`. - `Capability: pairing-pending` o `gateway closed (1008): pairing required` → il gateway ha risposto, ma questo client richiede ancora associazione/approvazione prima del normale accesso operatore. - testo di avviso SecretRef `gateway.auth.*` / `gateway.remote.*` non risolto → il materiale di autenticazione non era disponibile in questo percorso di comando per il target non riuscito. Correlati: - [Gateway](/it/cli/gateway) - [Più Gateway sullo stesso host](/it/gateway#multiple-gateways-same-host) - [Accesso remoto](/it/gateway/remote) ## Canale connesso, messaggi non in transito Se lo stato del canale è connesso ma il flusso dei messaggi è fermo, concentrati su criteri, autorizzazioni e regole di recapito specifiche del canale. ```bash openclaw channels status --probe openclaw pairing list --channel [--account ] openclaw status --deep openclaw logs --follow openclaw config get channels ``` Verifica: - Criterio DM (`pairing`, `allowlist`, `open`, `disabled`). - Allowlist dei gruppi e requisiti di menzione. - Autorizzazioni/scope API del canale mancanti. Indicatori comuni: - `mention required` → messaggio ignorato dal criterio di menzione del gruppo. - `pairing` / tracce di approvazione in sospeso → il mittente non è approvato. - `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → problema di autenticazione/autorizzazioni del canale. Correlati: - [Risoluzione dei problemi dei canali](/it/channels/troubleshooting) - [Discord](/it/channels/discord) - [Telegram](/it/channels/telegram) - [WhatsApp](/it/channels/whatsapp) ## Recapito di Cron e Heartbeat Se Cron o Heartbeat non è stato eseguito o non ha recapitato, verifica prima lo stato dello scheduler, poi la destinazione di recapito. ```bash openclaw cron status openclaw cron list openclaw cron runs --id --limit 20 openclaw system heartbeat last openclaw logs --follow ``` Verifica: - Cron abilitato e prossima riattivazione presente. - Stato della cronologia di esecuzione del job (`ok`, `skipped`, `error`). - Motivi di salto di Heartbeat (`quiet-hours`, `requests-in-flight`, `cron-in-progress`, `lanes-busy`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). - `cron: scheduler disabled; jobs will not run automatically` → Cron disabilitato. - `cron: timer tick failed` → tick dello scheduler non riuscito; controlla errori di file/log/runtime. - `heartbeat skipped` con `reason=quiet-hours` → fuori dalla finestra di ore attive. - `heartbeat skipped` con `reason=empty-heartbeat-file` → `HEARTBEAT.md` esiste ma contiene solo righe vuote / intestazioni markdown, quindi OpenClaw salta la chiamata al modello. - `heartbeat skipped` con `reason=no-tasks-due` → `HEARTBEAT.md` contiene un blocco `tasks:`, ma nessuna attività è in scadenza in questo tick. - `heartbeat: unknown accountId` → ID account non valido per la destinazione di recapito di Heartbeat. - `heartbeat skipped` con `reason=dm-blocked` → la destinazione Heartbeat risolta è di tipo DM mentre `agents.defaults.heartbeat.directPolicy` (o l’override per agente) è impostato su `block`. Correlati: - [Heartbeat](/it/gateway/heartbeat) - [Attività pianificate](/it/automation/cron-jobs) - [Attività pianificate: risoluzione dei problemi](/it/automation/cron-jobs#troubleshooting) ## Node associato, strumento non riuscito Se un Node è associato ma gli strumenti non funzionano, isola foreground, autorizzazioni e stato di approvazione. ```bash openclaw nodes status openclaw nodes describe --node openclaw approvals get --node openclaw logs --follow openclaw status ``` Verifica: - Node online con le capacità previste. - Concessioni di autorizzazioni del sistema operativo per fotocamera/microfono/posizione/schermo. - Approvazioni exec e stato dell’allowlist. Indicatori comuni: - `NODE_BACKGROUND_UNAVAILABLE` → l’app del Node deve essere in foreground. - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → autorizzazione del sistema operativo mancante. - `SYSTEM_RUN_DENIED: approval required` → approvazione exec in sospeso. - `SYSTEM_RUN_DENIED: allowlist miss` → comando bloccato dall’allowlist. Correlati: - [Approvazioni exec](/it/tools/exec-approvals) - [Risoluzione dei problemi dei Node](/it/nodes/troubleshooting) - [Node](/it/nodes/index) ## Strumento browser non riuscito Usa questa se le azioni dello strumento browser falliscono anche se il Gateway stesso è integro. ```bash openclaw browser status openclaw browser start --browser-profile openclaw openclaw browser profiles openclaw logs --follow openclaw doctor ``` Verifica: - Se `plugins.allow` è impostato e include `browser`. - Percorso valido dell’eseguibile del browser. - Raggiungibilità del profilo CDP. - Disponibilità di Chrome locale per i profili `existing-session` / `user`. - `unknown command "browser"` o `unknown command 'browser'` → il Plugin browser incluso è escluso da `plugins.allow`. - strumento browser mancante / non disponibile mentre `browser.enabled=true` → `plugins.allow` esclude `browser`, quindi il Plugin non è mai stato caricato. - `Failed to start Chrome CDP on port` → avvio del processo browser non riuscito. - `browser.executablePath not found` → il percorso configurato non è valido. - `browser.cdpUrl must be http(s) or ws(s)` → l’URL CDP configurato usa uno schema non supportato come `file:` o `ftp:`. - `browser.cdpUrl has invalid port` → l’URL CDP configurato ha una porta errata o fuori intervallo. - `Playwright is not available in this gateway build; '' is unsupported.` → l’installazione corrente del Gateway non include la dipendenza runtime core del browser; reinstalla o aggiorna OpenClaw, quindi riavvia il Gateway. Gli snapshot ARIA e gli screenshot base delle pagine possono comunque funzionare, ma navigazione, snapshot AI, screenshot di elementi con selettore CSS ed esportazione PDF restano non disponibili. - `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session non è ancora riuscito ad agganciarsi alla directory dati del browser selezionata. Apri la pagina di ispezione del browser, abilita il debug remoto, mantieni il browser aperto, approva il primo prompt di aggancio, quindi riprova. Se lo stato di accesso non è richiesto, preferisci il profilo gestito `openclaw`. - `No Chrome tabs found for profile="user"` → il profilo di aggancio Chrome MCP non ha schede Chrome locali aperte. - `Remote CDP for profile "" is not reachable` → l’endpoint CDP remoto configurato non è raggiungibile dall’host del Gateway. - `Browser attachOnly is enabled ... not reachable` o `Browser attachOnly is enabled and CDP websocket ... is not reachable` → il profilo solo aggancio non ha target raggiungibili, oppure l’endpoint HTTP ha risposto ma il WebSocket CDP non ha comunque potuto essere aperto. - `fullPage is not supported for element screenshots` → la richiesta di screenshot ha combinato `--full-page` con `--ref` o `--element`. - `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → le chiamate screenshot Chrome MCP / `existing-session` devono usare la cattura della pagina o un `--ref` da snapshot, non CSS `--element`. - `existing-session file uploads do not support element selectors; use ref/inputRef.` → gli hook di upload Chrome MCP richiedono riferimenti snapshot, non selettori CSS. - `existing-session file uploads currently support one file at a time.` → invia un upload per chiamata sui profili Chrome MCP. - `existing-session dialog handling does not support timeoutMs.` → gli hook dialog sui profili Chrome MCP non supportano override del timeout. - `existing-session type does not support timeoutMs overrides.` → ometti `timeoutMs` per `act:type` su `profile="user"` / profili Chrome MCP existing-session, oppure usa un profilo browser gestito/CDP quando è richiesto un timeout personalizzato. - `existing-session evaluate does not support timeoutMs overrides.` → ometti `timeoutMs` per `act:evaluate` su `profile="user"` / profili Chrome MCP existing-session, oppure usa un profilo browser gestito/CDP quando è richiesto un timeout personalizzato. - `response body is not supported for existing-session profiles yet.` → `responsebody` richiede ancora un browser gestito o un profilo CDP raw. - override obsoleti di viewport / modalità scura / locale / offline sui profili solo aggancio o CDP remoto → esegui `openclaw browser stop --browser-profile ` per chiudere la sessione di controllo attiva e rilasciare lo stato di emulazione Playwright/CDP senza riavviare l’intero Gateway. Correlati: - [Browser (gestito da OpenClaw)](/it/tools/browser) - [Risoluzione dei problemi del browser su Linux](/it/tools/browser-linux-troubleshooting) ## Se hai aggiornato e qualcosa si è rotto all’improvviso La maggior parte dei guasti successivi a un aggiornamento è dovuta a deriva della configurazione o a default più rigorosi ora applicati. ```bash openclaw gateway status openclaw config get gateway.mode openclaw config get gateway.remote.url openclaw config get gateway.auth.mode ``` Cosa controllare: - Se `gateway.mode=remote`, le chiamate CLI potrebbero puntare al remoto mentre il servizio locale è a posto. - Le chiamate esplicite `--url` non ricadono sulle credenziali memorizzate. Indicatori comuni: - `gateway connect failed:` → destinazione URL errata. - `unauthorized` → endpoint raggiungibile ma autenticazione errata. ```bash openclaw config get gateway.bind openclaw config get gateway.auth.mode openclaw config get gateway.auth.token openclaw gateway status openclaw logs --follow ``` Cosa controllare: - I bind non-loopback (`lan`, `tailnet`, `custom`) richiedono un percorso di autenticazione Gateway valido: autenticazione con token/password condivisi, oppure una distribuzione `trusted-proxy` non-loopback configurata correttamente. - Vecchie chiavi come `gateway.token` non sostituiscono `gateway.auth.token`. Indicatori comuni: - `refusing to bind gateway ... without auth` → bind non-loopback senza un percorso di autenticazione Gateway valido. - `Connectivity probe: failed` mentre il runtime è in esecuzione → Gateway attivo ma inaccessibile con autenticazione/URL correnti. ```bash openclaw devices list openclaw pairing list --channel [--account ] openclaw logs --follow openclaw doctor ``` Cosa controllare: - Approvazioni dispositivo in sospeso per dashboard/Node. - Approvazioni di associazione DM in sospeso dopo modifiche di criterio o identità. Indicatori comuni: - `device identity required` → autenticazione dispositivo non soddisfatta. - `pairing required` → mittente/dispositivo deve essere approvato. Se la configurazione del servizio e il runtime sono ancora in disaccordo dopo i controlli, reinstalla i metadati del servizio dalla stessa directory di profilo/stato: ```bash openclaw gateway install --force openclaw gateway restart ``` Correlati: - [Autenticazione](/it/gateway/authentication) - [Exec in background e strumento di processo](/it/gateway/background-process) - [Associazione gestita dal Gateway](/it/gateway/pairing) ## Correlati - [Doctor](/it/gateway/doctor) - [FAQ](/it/help/faq) - [Runbook del Gateway](/it/gateway)