Gateway

Risoluzione dei problemi

Questa pagina è il runbook approfondito. Inizia da /help/troubleshooting se vuoi prima il flusso di triage rapido.

Sequenza di comandi

Esegui prima questi, in questo ordine:

bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Segnali attesi di stato corretto:

  • 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.

Dopo un aggiornamento

Usalo quando un aggiornamento termina ma il Gateway è inattivo, i canali sono vuoti oppure le chiamate al modello iniziano a fallire con 401.

bash
openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

Cerca:

  • Update restart in openclaw status / openclaw status --all. Gli handoff in sospeso o non riusciti includono il comando successivo da eseguire.
  • plugin load failed: dependency tree corrupted; run openclaw doctor --fix sotto Channels. Significa che la configurazione del canale esiste ancora, ma la registrazione del plugin è fallita prima che il canale potesse caricarsi.
  • 401 del provider dopo la riautenticazione. openclaw doctor --fix controlla la presenza di shadow OAuth obsolete per agente e rimuove le vecchie copie in modo che tutti gli agenti risolvano il profilo condiviso corrente.

Installazioni split-brain e protezione per configurazioni più recenti

Usalo quando un servizio gateway si arresta inaspettatamente dopo un aggiornamento, oppure i log mostrano che un binario openclaw è più vecchio della versione che ha scritto per ultima openclaw.json.

OpenClaw marca le scritture di configurazione con meta.lastTouchedVersion. I comandi di sola lettura possono ancora ispezionare una configurazione scritta da un OpenClaw più recente, 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 openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion
  • Fix PATH

    Correggi PATH in modo che openclaw risolva all'installazione più recente, quindi riesegui l'azione.

  • Reinstall the gateway service

    Reinstalla il servizio gateway previsto dall'installazione più recente:

    bash
    openclaw gateway install --forceopenclaw gateway restart
  • Remove stale wrappers

    Rimuovi il pacchetto di sistema obsoleto o le vecchie voci wrapper che puntano ancora a un vecchio binario openclaw.

  • Mancata corrispondenza del protocollo dopo il rollback

    Usalo quando i log continuano a stampare protocol mismatch dopo il downgrade o il rollback di OpenClaw. Significa che è in esecuzione un Gateway più vecchio, ma un processo client locale più recente sta ancora tentando di riconnettersi con un intervallo di protocollo che il Gateway più vecchio non può parlare.

    bash
    openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

    Cerca:

    • protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> nei log del Gateway.
    • Established clients: in openclaw gateway status --deep oppure Gateway clients in openclaw doctor --deep. Elenca i client TCP attivi connessi alla porta del Gateway, inclusi PID e righe di comando quando il sistema operativo lo consente.
    • Un processo client la cui riga di comando punta all'installazione o al wrapper OpenClaw più recente da cui hai eseguito il rollback.

    Correzione:

    1. Arresta o riavvia il processo client OpenClaw obsoleto mostrato da gateway status --deep.
    2. Riavvia le app o i wrapper che incorporano OpenClaw, come dashboard locali, editor, helper di app-server o shell openclaw logs --follow a lunga esecuzione.
    3. Riesegui openclaw gateway status --deep oppure openclaw doctor --deep e conferma che il PID del client obsoleto non sia più presente.

    Non fare in modo che un Gateway più vecchio accetti un protocollo più recente incompatibile. Gli incrementi di protocollo proteggono il contratto wire; il ripristino da rollback è un problema di pulizia di processi/versioni.

    Usalo quando i log includono:

    text
    Skipping escaped skill path outside its configured root: ... reason=symlink-escape

    OpenClaw tratta ogni radice skill come un confine di contenimento. Un symlink sotto ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills o ~/.openclaw/skills viene ignorato quando la sua destinazione reale si risolve fuori da quella radice a meno che la destinazione non sia esplicitamente attendibile.

    Ispeziona il link:

    bash
    ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

    Se la destinazione è intenzionale, configura sia la radice skill diretta sia la destinazione symlink consentita:

    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 destinazioni ampie come ~, / o un'intera cartella di progetto sincronizzata. Mantieni allowSymlinkTargets limitato alla radice skill reale che contiene directory SKILL.md attendibili.

    Se anche l'applicazione da Skill Workshop deve scrivere attraverso quei percorsi skill del workspace symlinkati e attendibili, abilita skills.workshop.allowSymlinkTargetWrites. Tienilo disabilitato per radici skill condivise di sola lettura.

    Correlati:

    Anthropic 429: uso extra richiesto per contesto lungo

    Usalo quando log/errori includono: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

    bash
    openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

    Cerca:

    • Il modello Anthropic selezionato è un modello Claude 4.x da 1M con capacità GA, oppure il modello ha il parametro legacy params.context1m: true.
    • La credenziale Anthropic corrente non è idonea per l'uso con contesto lungo.
    • Le richieste falliscono solo su sessioni lunghe/esecuzioni modello che richiedono il percorso di contesto 1M.

    Opzioni di correzione:

  • Use a standard context window

    Passa a un modello con finestra standard, oppure rimuovi context1m legacy dalla configurazione di modelli più vecchi che non sono GA-capable per contesto 1M.

  • Use an eligible credential

    Usa una credenziale Anthropic idonea per richieste con contesto lungo, oppure passa a una chiave API Anthropic.

  • Configure fallback models

    Configura modelli di fallback in modo che le esecuzioni continuino quando le richieste Anthropic con contesto lungo vengono rifiutate.

  • Correlati:

    Risposte upstream 403 bloccate

    Usalo quando un provider LLM upstream restituisce un 403 generico come Your request was blocked.

    Non presumere che sia sempre un problema di configurazione OpenClaw. La risposta può provenire da un livello di sicurezza upstream come CDN, WAF, regola di gestione bot o reverse proxy davanti a un endpoint compatibile con OpenAI.

    bash
    openclaw statusopenclaw gateway statusopenclaw logs --follow

    Cerca:

    • più modelli sotto lo stesso provider che falliscono nello stesso modo
    • HTML o testo di sicurezza generico invece di un normale errore API del provider
    • eventi di sicurezza lato provider per lo stesso orario della richiesta
    • un minuscolo probe diretto curl che riesce mentre le normali richieste in forma SDK falliscono

    Correggi prima il filtro lato provider quando le prove indicano un blocco WAF/CDN. Preferisci una regola allow o skip con ambito ristretto per il percorso API usato da OpenClaw ed evita di disabilitare la protezione per l'intero sito.

    Correlati:

    Il backend locale compatibile con OpenAI supera i probe diretti ma le esecuzioni agente falliscono

    Usalo quando:

    • curl ... /v1/models funziona
    • chiamate dirette minuscole a /v1/chat/completions funzionano
    • le esecuzioni modello OpenClaw falliscono solo nei normali turni agente
    bash
    curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "hi" --jsonopenclaw logs --follow

    Cerca:

    • le chiamate dirette minuscole 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 prompt-token maggiori o prompt completi del runtime agente
    Common signatures
    • 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.<provider>.models[].id sia l'id provider-locale semplice. Selezionalo una volta con il prefisso del provider, per 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 Chat Completions strutturate. Correzione: imposta models.providers.<provider>.models[].compat.requiresStringContent: true.
    • validation.keys o chiavi messaggio consentite come ["role","content"] → il backend rifiuta metadati di replay in stile OpenAI sui messaggi Chat Completions. Correzione: imposta models.providers.<provider>.models[].compat.strictMessageKeys: true.
    • incomplete turn detected ... stopReason=stop payloads=0 → il backend ha completato la richiesta Chat Completions ma non ha restituito testo 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 emette contenuto vuoto/non testuale o sopprime il testo della risposta finale.
    • le richieste dirette minuscole riescono, ma le esecuzioni agente OpenClaw falliscono con crash backend/modello (per esempio Gemma su alcune build inferrs) → il trasporto OpenClaw è probabilmente già corretto; il backend sta fallendo sulla forma di prompt più grande del runtime agente.
    • i fallimenti si riducono dopo aver disabilitato gli strumenti ma non scompaiono → gli schemi degli strumenti erano parte della pressione, ma il problema residuo è ancora capacità del modello/server upstream o un bug del backend.
    Fix options
    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 su 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ù forte per contesti lunghi.
    5. Se le richieste dirette minuscole continuano a riuscire mentre i turni agente OpenClaw continuano a causare crash dentro il backend, trattalo come una limitazione upstream del server/modello e apri lì una riproduzione con la forma di payload accettata.

    Correlati:

    Nessuna risposta

    Se i canali sono attivi ma nulla risponde, controlla routing e policy prima di riconnettere qualsiasi cosa.

    bash
    openclaw statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw config get channelsopenclaw logs --follow

    Cerca:

    • Pairing in sospeso per mittenti DM.
    • Gate sulle menzioni nei gruppi (requireMention, mentionPatterns).
    • Disallineamenti nell'allowlist di canale/gruppo.

    Firme comuni:

    • drop guild message (mention required → messaggio di gruppo ignorato finché non viene menzionato.
    • pairing request → il mittente necessita di approvazione.
    • blocked / allowlist → mittente/canale filtrato dalla policy.

    Correlati:

    Connettività dell'interfaccia di controllo del dashboard

    Quando l'interfaccia utente dashboard/di controllo non si connette, verifica URL, modalità di autenticazione e assunzioni sul contesto sicuro.

    bash
    openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

    Cerca:

    • URL di probe e URL del dashboard corretti.
    • Disallineamento modalità/token di autenticazione tra client e Gateway.
    • Uso di HTTP dove è richiesta l'identità del dispositivo.

    Se un browser locale non riesce a connettersi a 127.0.0.1:18789 dopo un aggiornamento, prima ripristina il servizio Gateway locale e conferma che stia servendo il dashboard:

    bash
    openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

    Se curl restituisce HTML di OpenClaw, il Gateway funziona e il problema residuo è probabilmente la cache del browser, un vecchio deep link o uno stato di scheda obsoleto. Apri http://127.0.0.1:18789 direttamente e naviga dal dashboard. Se il riavvio non lascia il servizio in esecuzione, esegui openclaw gateway start e ricontrolla openclaw gateway status.

    Firme di connessione/autenticazione
    • device identity required → contesto non sicuro o autenticazione del 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 del dispositivo basato su challenge (connect.challenge + device.nonce).
    • device signature invalid / device signature expired → il client ha firmato il payload sbagliato (o con timestamp obsoleto) per l'handshake corrente.
    • AUTH_TOKEN_MISMATCH con canRetryWithDeviceToken=true → il client può eseguire un solo tentativo affidabile con il token dispositivo in cache.
    • Quel nuovo tentativo con token in cache riusa l'insieme di scope in cache memorizzato con il token dispositivo associato. I chiamanti con deviceToken esplicito / scopes espliciti mantengono invece l'insieme di scope richiesto.
    • AUTH_SCOPE_MISMATCH → il token dispositivo è stato riconosciuto, ma i suoi scope approvati non coprono questa richiesta di connessione; riassocia o approva il contratto di scope richiesto invece di ruotare un token Gateway condiviso.
    • Al di fuori di quel percorso di nuovo tentativo, la precedenza dell'autenticazione di connessione è prima token/password condivisi espliciti, poi deviceToken esplicito, poi token dispositivo memorizzato, poi token di bootstrap.
    • Nel percorso asincrono dell'interfaccia di controllo Tailscale Serve, i tentativi falliti per la stessa {scope, ip} vengono serializzati prima che il limitatore registri il fallimento. Due nuovi tentativi errati concorrenti 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 nuovo tentativo → deriva tra token condiviso/token dispositivo; aggiorna la configurazione del token e riapprova/ruota il token dispositivo se necessario.
    • gateway connect failed: → host/porta/URL di destinazione errati.

    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 del dashboard: openclaw config get gateway.auth.token, poi incollalo nelle impostazioni dell'interfaccia di controllo.
    AUTH_TOKEN_MISMATCH Il token condiviso non corrispondeva al token di autenticazione del Gateway. Se canRetryWithDeviceToken=true, consenti un solo tentativo affidabile. I tentativi con token in cache riusano gli scope approvati memorizzati; i chiamanti con deviceToken / scopes espliciti mantengono gli scope richiesti. Se continua a fallire, esegui la checklist di ripristino dalla deriva del token.
    AUTH_DEVICE_TOKEN_MISMATCH Il token per dispositivo in cache è obsoleto o revocato. Ruota/riapprova il token dispositivo usando la CLI dei dispositivi, quindi riconnettiti.
    AUTH_SCOPE_MISMATCH Il token dispositivo è valido, ma il suo ruolo/i suoi scope approvati non coprono questa richiesta di connessione. Riassocia il dispositivo o approva il contratto di scope 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, poi openclaw devices approve <requestId>. Gli upgrade di scope/ruolo usano lo stesso flusso dopo aver esaminato l'accesso richiesto.

    Controllo migrazione autenticazione dispositivo v2:

    bash
    openclaw --versionopenclaw doctoropenclaw gateway status

    Se i log mostrano errori di nonce/firma, aggiorna il client che si connette e verificalo:

  • Attendi connect.challenge

    Il client attende il connect.challenge emesso dal Gateway.

  • Firma il payload

    Il client firma il payload vincolato alla challenge.

  • Invia il nonce del dispositivo

    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 abbia anche operator.admin
    • openclaw devices rotate --scope ... può richiedere solo scope operatore che la sessione del chiamante possiede già

    Correlati:

    Servizio Gateway non in esecuzione

    Usalo quando il servizio è installato ma il processo non resta attivo.

    bash
    openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # analizza anche i servizi a livello di sistema

    Cerca:

    • Runtime: stopped con suggerimenti di uscita.
    • Disallineamento della configurazione del servizio (Config (cli) vs 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).
    Firme comuni
    • 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 tua 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, o proxy attendibile 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 Gateway per macchina; se ne serve più di uno, isola porte + configurazione/stato/workspace. Consulta /gateway#multiple-gateways-same-host.
    • System-level OpenClaw gateway service detected da doctor → esiste un'unità di sistema systemd mentre manca il servizio a livello utente. 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 fissa ancora il vecchio --port. Esegui openclaw doctor --fix o openclaw gateway install --force, quindi riavvia il servizio Gateway.

    Correlati:

    Il Gateway macOS smette silenziosamente di rispondere, poi riprende quando tocchi il dashboard

    Usalo quando i canali (Telegram, WhatsApp, ecc.) su un host macOS restano silenziosi per minuti o ore alla volta, e il Gateway sembra tornare non appena apri l'interfaccia di controllo, accedi via SSH o interagisci in altro modo con l'host. Di solito non c'è alcun sintomo evidente in openclaw status perché quando controlli il Gateway è già di nuovo attivo.

    bash
    ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

    Cerca:

    • Uno o più bundle *-uncaught_exception.json in ~/.openclaw/logs/stability/ con error.code impostato su un codice di rete transitorio come ENETDOWN, ENETUNREACH, EHOSTUNREACH o ECONNREFUSED.
    • Righe di pmset -g log come Entering Sleep state due to 'Maintenance Sleep' o en0 driver is slow (msg: WillChangeState to 0) allineate ai timestamp del crash. Power Nap / Maintenance Sleep porta brevemente il driver Wi-Fi nello stato 0; qualsiasi connect() in uscita che cade in quella finestra può fallire con ENETDOWN anche su un host che altrimenti ha connettività di rete completa.
    • Output di launchctl print che mostra state = not running con più runs recenti e un codice di uscita, soprattutto quando l'intervallo tra il crash e l'avvio successivo è dell'ordine di un'ora anziché di secondi. Su macOS, launchd applica una protezione di respawn non documentata dopo una raffica di crash che può smettere di rispettare KeepAlive=true finché un trigger esterno, come login interattivo, connessione alla dashboard o launchctl kickstart, non lo riattiva.

    Firme comuni:

    • Un bundle di stabilità il cui error.code è ENETDOWN o un codice simile, con lo stack di chiamate che punta a lookupAndConnect / Socket.connect di net in Node. OpenClaw 2026.5.26 e versioni successive classificano questi errori come errori di rete transitori benigni, quindi non si propagano più all'handler uncaught di primo livello; se usi una release precedente, esegui prima l'aggiornamento.
    • Lunghi periodi di silenzio che terminano nell'istante in cui ti connetti alla Control UI o accedi all'host via SSH: l'attività visibile all'utente è ciò che riattiva la protezione di respawn di launchd, non qualcosa che la dashboard fa al gateway.
    • Conteggio runs che aumenta durante la giornata senza una riga corrispondente received SIG*; shutting down in ~/Library/Logs/openclaw/gateway.log: gli arresti puliti registrano un segnale; i crash transitori no.

    Cosa fare:

    1. Aggiorna il gateway se stai eseguendo una release precedente a 2026.5.26. Dopo l'aggiornamento, i futuri errori ENETDOWN vengono registrati come avvisi invece di terminare il processo.

    2. Riduci l'attività di sospensione per manutenzione sugli host Mac mini / desktop pensati per funzionare come server sempre attivi:

      bash
      sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

      Questo riduce in modo significativo, ma non elimina del tutto, il flap del driver sottostante. Il sistema può comunque eseguire alcune sospensioni di manutenzione per TCP keepalive e manutenzione mDNS indipendentemente da questi flag.

    3. Aggiungi un watchdog di liveness in modo che una futura raffica di crash parcheggiata da launchd venga rilevata rapidamente:

      bash
      # Example launchd-aware liveness check, suitable for a 5-minute cron or LaunchAgentstate=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

      L'obiettivo è riattivare esternamente la protezione di respawn; KeepAlive=true da solo non è sufficiente su macOS dopo una raffica di crash.

    Correlato:

    Il Gateway esce durante un uso elevato della memoria

    Usa questa se il Gateway scompare sotto carico, il supervisore segnala un riavvio in stile OOM o i log menzionano critical memory pressure bundle written.

    bash
    openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

    Cerca:

    • Reason: diagnostic.memory.pressure.critical nel bundle di stabilità più recente.
    • Memory pressure: con critical/rss_threshold, critical/heap_threshold o critical/rss_growth.
    • Valori V8 heap: vicini al limite dello heap.
    • Voci Largest session files: come agents/<agent>/sessions/<session>.jsonl o sessions/<session>.jsonl.
    • Contatori di memoria cgroup Linux quando il gateway viene eseguito dentro un container o un servizio con memoria limitata.

    Firme comuni:

    • critical memory pressure bundle written appare poco prima del riavvio → OpenClaw ha acquisito un bundle di stabilità pre-OOM. Ispezionalo con openclaw gateway stability --bundle latest.
    • memory pressure: level=critical ... memoryPressureSnapshot=disabled appare nei log del gateway → OpenClaw ha rilevato pressione di memoria critica, ma lo snapshot di stabilità pre-OOM è disattivato.
    • Largest session files: punta a un percorso di trascrizione redatto molto grande → riduci la cronologia delle sessioni conservata, ispeziona la crescita della sessione o sposta le vecchie trascrizioni fuori dallo store attivo prima di riavviare.
    • I byte usati in V8 heap: sono vicini al limite dello heap → riduci la pressione di prompt/sessione, riduci il lavoro concorrente o aumenta il limite dello heap di Node solo dopo aver confermato che il carico di lavoro è previsto.
    • Memory pressure: critical/rss_growth → la memoria è cresciuta rapidamente in una finestra di campionamento. Controlla i log più recenti per un import grande, output di tool fuori controllo, retry ripetuti o un batch di lavoro agente in coda.
    • La pressione di memoria critica appare nei log ma non esiste alcun bundle → questo è il comportamento predefinito. Imposta diagnostics.memoryPressureSnapshot: true per acquisire il bundle di stabilità pre-OOM nei futuri eventi di pressione di memoria critica.

    Il bundle di stabilità non contiene payload. Include prove operative sulla memoria e percorsi di file relativi redatti, non testo dei messaggi, corpi webhook, credenziali, token, cookie o ID sessione grezzi. Allega l'export diagnostico alle segnalazioni di bug invece di copiare log grezzi.

    Correlato:

    Il Gateway ha rifiutato una configurazione non valida

    Usa questa quando l'avvio del Gateway fallisce con Invalid config o i log di hot reload dicono che ha saltato una modifica non valida.

    bash
    openclaw logs --followopenclaw config fileopenclaw config validateopenclaw 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 rotta
    • OpenClaw conserva gli ultimi 32 file .clobbered.* per ciascun percorso di configurazione e ruota quelli più vecchi
    Cosa è successo
    • La configurazione non è stata validata durante l'avvio, l'hot reload o una scrittura di proprietà di OpenClaw.
    • L'avvio del Gateway fallisce in modo chiuso invece di riscrivere openclaw.json.
    • L'hot reload salta 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 possiede la riparazione. Può rimuovere prefissi non JSON o ripristinare l'ultima copia valida nota preservando il payload rifiutato come .clobbered.*.
    • Quando avvengono molte riparazioni per un percorso di configurazione, OpenClaw ruota i file .clobbered.* più vecchi in modo che il payload riparato più recente sia ancora disponibile.
    Ispeziona e ripara
    bash
    CONFIG="$(openclaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor
    Firme comuni
    • .clobbered.* esiste → doctor ha preservato una modifica esterna rotta 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 eliminare la struttura 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 del Gateway venissero avviati.
    • 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 last-known-good.
    • Config last-known-good promotion skipped → il candidato conteneva placeholder di segreti redatti come ***.
    Opzioni di correzione
    1. Esegui openclaw doctor --fix per lasciare che doctor ripari la configurazione prefissata/clobbered o ripristini last-known-good.
    2. Copia solo le chiavi desiderate da .clobbered.* o .rejected.*, poi applicale con openclaw config set o config.patch.
    3. Esegui openclaw config validate prima di riavviare.
    4. Se modifichi a mano, mantieni la configurazione JSON5 completa, non solo l'oggetto parziale che volevi cambiare.

    Correlato:

    Avvisi dei probe del Gateway

    Usa questa quando openclaw gateway probe raggiunge qualcosa, ma stampa comunque un blocco di avviso.

    bash
    openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

    Cerca:

    • warnings[].code e primaryTargetId nell'output JSON.
    • Se l'avviso riguarda fallback SSH, più gateway, ambiti mancanti o riferimenti auth non risolti.

    Firme comuni:

    • SSH tunnel failed to start; falling back to direct probes. → la configurazione SSH è fallita, ma il comando ha comunque provato target diretti configurati/loopback.
    • multiple reachable gateway identities detected → gateway distinti hanno risposto, oppure OpenClaw non ha potuto provare che i target raggiungibili siano lo stesso gateway. Un tunnel SSH, URL proxy o URL remoto configurato verso lo stesso gateway viene trattato come un solo gateway con più trasporti, anche quando le porte di trasporto differiscono.
    • Read-probe diagnostics are limited by gateway scopes (missing operator.read) → la connessione ha funzionato, ma l'RPC di dettaglio è limitato dagli ambiti; abbina 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 il set completo di RPC diagnostici è andato in timeout o è fallito. 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 necessita ancora di pairing/approvazione prima del normale accesso operatore.
    • testo di avviso SecretRef gateway.auth.* / gateway.remote.* non risolto → il materiale auth non era disponibile in questo percorso di comando per il target fallito.

    Correlato:

    Canale connesso, messaggi non in transito

    Se lo stato del canale è connesso ma il flusso dei messaggi è interrotto, concentrati su policy, autorizzazioni e regole di consegna specifiche del canale.

    bash
    openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

    Cerca:

    • Policy DM (pairing, allowlist, open, disabled).
    • Allowlist dei gruppi e requisiti di menzione.
    • Autorizzazioni/ambiti API del canale mancanti.

    Firme comuni:

    • mention required → messaggio ignorato dalla policy di menzione del gruppo.
    • tracce pairing / approvazione in sospeso → il mittente non è approvato.
    • missing_scope, not_in_channel, Forbidden, 401/403 → problema di auth/autorizzazioni del canale.

    Correlato:

    Consegna di Cron e Heartbeat

    Se Cron o Heartbeat non è stato eseguito o non ha consegnato, verifica prima lo stato dello scheduler, poi il target di consegna.

    bash
    openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

    Cerca:

    • Cron abilitato e prossimo risveglio presente.
    • Stato della cronologia delle esecuzioni del job (ok, skipped, error).
    • Motivi di salto dell'Heartbeat (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due).
    Firme comuni
    • 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 degli orari attivi.
    • heartbeat skipped con reason=empty-heartbeat-fileHEARTBEAT.md esiste ma contiene solo righe vuote, commenti, intestazioni, fence o scaffolding di checklist vuote, quindi OpenClaw salta la chiamata al modello.
    • heartbeat skipped con reason=no-tasks-dueHEARTBEAT.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 dell'Heartbeat.
    • heartbeat skipped con reason=dm-blocked → la destinazione dell'Heartbeat è stata risolta in una destinazione in stile DM mentre agents.defaults.heartbeat.directPolicy (o l'override per agente) è impostato su block.

    Correlati:

    Node associato, strumento non riuscito

    Se un nodo è associato ma gli strumenti non riescono, isola stato di foreground, autorizzazioni e approvazioni.

    bash
    openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw status

    Cerca:

    • Nodo online con le capacità previste.
    • Concessioni di autorizzazioni del sistema operativo per fotocamera/microfono/posizione/schermo.
    • Stato delle approvazioni exec e dell'allowlist.

    Firme comuni:

    • NODE_BACKGROUND_UNAVAILABLE → l'app del nodo 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:

    Strumento browser non riuscito

    Usalo quando le azioni dello strumento browser non riescono anche se il Gateway stesso è integro.

    bash
    openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

    Cerca:

    • 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.
    Firme Plugin / eseguibile
    • unknown command "browser" o unknown command 'browser' → il Plugin browser in bundle è escluso da plugins.allow.
    • strumento browser mancante / non disponibile mentre browser.enabled=trueplugins.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; '<feature>' 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 di base delle pagine possono ancora funzionare, ma navigazione, snapshot AI, screenshot di elementi con selettore CSS ed esportazione PDF restano non disponibili.
    Firme Chrome MCP / existing-session
    • 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, tieni aperto il browser, approva la prima richiesta 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 "<name>" 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 destinazioni raggiungibili, oppure l'endpoint HTTP ha risposto ma il WebSocket CDP non ha comunque potuto essere aperto.
    Firme elemento / screenshot / caricamento
    • 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 --element CSS.
    • existing-session file uploads do not support element selectors; use ref/inputRef. → gli hook di caricamento Chrome MCP richiedono riferimenti snapshot, non selettori CSS.
    • existing-session file uploads currently support one file at a time. → invia un caricamento per chiamata sui profili Chrome MCP.
    • existing-session dialog handling does not support timeoutMs. → gli hook di dialogo 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 grezzo.
    • override obsoleti di viewport / modalità scura / locale / offline su profili solo aggancio o CDP remoto → esegui openclaw browser stop --browser-profile <name> per chiudere la sessione di controllo attiva e rilasciare lo stato di emulazione Playwright/CDP senza riavviare l'intero Gateway.

    Correlati:

    Se hai aggiornato e qualcosa si è rotto improvvisamente

    La maggior parte delle rotture post-aggiornamento è dovuta a deriva della configurazione o a default più rigorosi ora applicati.

    1. Il comportamento di override di autenticazione e URL è cambiato
    bash
    openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

    Cosa controllare:

    • Se gateway.mode=remote, le chiamate CLI potrebbero puntare al remoto mentre il servizio locale funziona correttamente.
    • Le chiamate esplicite con --url non fanno fallback alle credenziali memorizzate.

    Firme comuni:

    • gateway connect failed: → destinazione URL errata.
    • unauthorized → endpoint raggiungibile ma autenticazione errata.
    2. I guardrail di bind e autenticazione sono più rigorosi
    bash
    openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw 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.
    • Le vecchie chiavi come gateway.token non sostituiscono gateway.auth.token.

    Firme 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.
    3. Lo stato di associazione e identità del dispositivo è cambiato
    bash
    openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctor

    Cosa controllare:

    • Approvazioni dispositivo in sospeso per dashboard/nodi.
    • Approvazioni di associazione DM in sospeso dopo modifiche a policy o identità.

    Firme comuni:

    • device identity required → autenticazione dispositivo non soddisfatta.
    • pairing required → mittente/dispositivo deve essere approvato.

    Se la configurazione del servizio e il runtime continuano a non concordare dopo i controlli, reinstalla i metadati del servizio dalla stessa directory profilo/stato:

    bash
    openclaw gateway install --forceopenclaw gateway restart

    Correlati:

    Correlati

    Was this useful?
    On this page

    On this page