OpenClaw
Risoluzione dei problemi
Gateway die niet pronto wordt, Docker die unhealthy blijft, ontbrekende .env-keys of een agent zonder antwoord — hier staan de oorzaken, terminal-checks en fixes zoals je ze op een server tegenkomt.
Kort antwoord
Wat veroorzaakt
OpenClaw problemen?
Risposta breve: OpenClaw-problemen komen bijna altijd van de OpenClaw Gateway (niet pronto), Docker Compose (malsano), .env / API keys, of runtime (approvals, geheugen).
Eerste commando’s: openclaw gateway status → chirurgo a mano aperta → registri openclaw --follow (productie: journalctl -u openclaw-gateway -f).
Hobby-installatie op laptop ≠ VPS met reverse proxy, echte mailbox en browser automation — zelfde CLI, andere risico’s. Installare · Centro.
Directe fixes
Terminal-checks die je eerst draait
Commando eerst, dan interpretatie. Pas daarna restart of rebuild — volgorde voor VPS, Docker Compose en systemd.
Gateway-status en logs
-
→
openclaw gateway status— verwachtRuntime: running; anders logs openen -
→
registri openclaw --follow— zoekpronto,EADDRINUSE, auth-fouten -
→
journalctl -u openclaw-gateway -f— bij systemd; failed = unit/config, niet “Anthropic down” -
→
chirurgo a mano aperta— blocking issues eerst fixen, daarna pas restart
Herstart (veilig — geen data wipe)
-
→
sudo systemctl restart openclaw— na.env/config-fix; niet bij volle approval-queue zonder check -
→
docker compose restart— nalog di Docker Compose; unhealthy zonder log-read = gokken - → Restart volstaat bij vastgelopen Gateway; reinstall pas na doctor + backup
Docker Compose & health
-
→
docker compose ps—malsano= healthz faalt in container -
→
curl -sS http://127.0.0.1:18789/healthz—200verwacht; anders poort/config -
→
docker compose build— alleen na image-corruptie; niet als eerste stap
Config, .env & API-keys
-
→
openclaw config get gateway.auth.mode— leeg = Gateway weigert externe bind -
→
Anthropic / OpenAI-compatible / Ollama URL in
.env—chmod 600 .env -
→
ls -la ~/.openclaw/— service-user vs jouw login-user (productie split-brain)
Meest voorkomende OpenClaw problemen
Oorzaak, symptomen en fix per fouttype
Elk blok begint met een direct antwoord (geschikt voor snippets en AI-overviews), daarna terminal-output, symptomen en stappen. Filter op categorie.
Gateway reageert niet / blijft op starting
De OpenClaw Gateway bereikt geen pronto door poortconflict, ontbrekende gateway.auth, verkeerde gateway.mode, of een vastgelopen WebSocket/event-loop na upgrade.
-
openclaw gateway statusPrevisto:Runtime: runningeRPC probe: okSe errato:stoppeddifailed→ proces start niet of auth/poort blokkeert Prossimo: registri openclaw --follow -
sudo systemctl status openclawPrevisto:Active: active (running)Se errato:failedof restart-loop → systemd-unit of Node-pad klopt niet Prossimo: journalctl -u openclaw-gateway -n 80 --no-pager -
chirurgo a mano apertaPrevisto: geen blocking issues Se errato: auth/mode/poort-waarschuwing → fixopenclaw.jsonvóór restart Prossimo: sudo systemctl restart openclaw
openclaw gateway status Runtime: stopped RPC probe: failed Gateway start blocked: set gateway.mode=local
Runtime: stoppedRPC probe: failedEADDRINUSEGateway start blocked: set gateway.mode=local- endless reconnect in channel logs
- Kanalen (Telegram/Discord) disconnected —
stato dei canali openclaw --probefaalt - Health-check /
/salutetimeout achter reverse proxy - WebSocket disconnects direct na
READY - Cron/heartbeat-taken lopen niet terwijl CLI nog reageert
- Twee Gateways op één host (npm global + Docker Compose)
- Gateway via reverse proxy zonder WebSocket-upgrade
- Remote
gateway.remote.urlterwijl lokale Gateway ook draait
De OpenClaw Gateway verbindt kanalen, self-hosted AI agents en tools. Plugin-bootstrap of ontbrekende node-registratie kan de listener blokkeren vóór HTTP/WebSocket bereikbaar is.
- Poortconflict: proces op listener-poort stoppen, één Gateway per host
- Reverse proxy: WebSocket-upgrade + health-route naar
/salute - Auth:
openclaw config get gateway.auth.mode— bij LAN-bind altijd token
Restart volstaat bij config-fix of vastgelopen proces; logs uitlezen bij herhaalde starting senza pronto; herinstallatie pas na dubbele Gateway-installatie of corrupte plugin-state.
Docker-container unhealthy / healthz timeout
Docker Compose markeert de Gateway-container als malsano wanneer /salute binnen de container faalt — meestal Gateway niet pronto, verkeerde poort-mapping, of OOM (Uscita 137).
-
docker compose psPrevisto: STATOcorsa(geenmalsano) Se errato:malsanodirestarting→ healthcheck faalt Prossimo: docker compose logs -f --tail=80 -
curl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/healthzPrevisto:200Se errato:000of timeout → poort of Gateway in container Prossimo: openclaw gateway status (in container of via exec) -
docker compose restartPrevisto: container stabiel na config-fix Se errato: blijft unhealthy → image-tag terugzetten, geen volume-wipe Prossimo: docker compose build --no-cache alleen na backup + bevestigde corruptie
docker compose ps openclaw-gateway unhealthy Exit 137 wget: can't connect to remote host (localhost:18789)
malsanoIndocker compose psUscita 137(OOM)health check failedcan't connect to localhost:18789
- RestartCount stijgt — container in crash-loop
- Host-
arricciarenaar geëxposeerde poort geeft geen 200 op/salute - Gateway in container start wel
runtime.presto, nooitpronto
- Poort in compose wijkt af van
gateway.portin config modalità_rete: host+ tweede Gateway op dezelfde VPS- Volumes wissen vóór log-analyse
Container isolation helpt, maar de Gateway in Docker heeft dezelfde config/API-key-eisen als bare metal. Geheugendruk door browser-automation of grote context windows triggert OOM sneller in beperkte cgroup-limits.
- Map
.enveopenclaw.jsonconsistent in volume — service-user ≠ host-user is een veelvoorkomende split-brain - Productie: aparte compose-projectnaam per omgeving, geen
ultimozonder pin
Container rebuild alleen bij kapotte image/layers; restart na .env-fix; volledige reinstall alleen met backup van config-volumes.
.env / openclaw.json — ontbrekende keys
Ongeldige of ontbrekende API keys (Anthropic, OpenAI-compatible endpoint, Ollama URL) of lege gateway.auth.token — de Gateway draait soms wel, maar agents krijgen geen upstream.
-
openclaw config get gateway.auth.modePrevisto: verwachte auth-modus (niet leeg) Se errato: leeg of error →openclaw.jsonincompleet Prossimo: ls -la ~/.openclaw/ && vergelijk Docker volume -
grep -E "ANTHROPIC|OPENAI|OLLAMA" .envPrevisto: keys aanwezig (niet tonen in tickets) Se errato: ontbrekend → vul .env, chmod 600 Prossimo: systemctl restart openclaw of docker compose restart -
chirurgo a mano apertaPrevisto: provider + gateway OK Se errato: upstream/auth warning → key rotatie of OAuth-profiel vernieuwen Prossimo: testbericht via kanaal, logs --follow
Error: Missing required env: ANTHROPIC_API_KEY Config: ~/.openclaw/openclaw.json Gateway auth.token: (empty)
Missing required env: ANTHROPIC_API_KEY401/invalid_api_keyin agent logsgateway.auth.token: (empty)- model not found voor geconfigureerd profiel
- AI voert niets uit — berichten binnen, geen model-output
- CLI toont andere config dan systemd/Docker-service
- Ollama lokaal bereikbaar via
arricciare, maar agent gebruikt verkeerd base-URL
- Key alleen in shell-export, niet in service-
.env - Anthropic-key in repo of compose zonder secrets-mount
- Model-ID wijst naar provider die niet in
openclaw.jsonstaat
Self-hosted AI agents lezen config van de Gateway-user. Hobby-installaties gebruiken vaak de desktop-user; productie/MKB draait onder een dedicated service-account met eigen ~/.openclaw/.
- Eén bron van waarheid:
.env+openclaw.jsonvoor dezelfde user als systemdUser= - Ollama: base-URL en model-id in config moeten matchen met wat
curl http://127.0.0.1:11434/api/tagstoont
Ape .env-fout: geen reinstall — fix keys en restart Gateway; escaleren als CLI en service na sync nog verschillende paden gebruiken.
comando non trovato: openclaw
OpenClaw staat niet in $PERCORSO — npm global bin ontbreekt in shell, of systemd gebruikt een andere Node/npm dan je terminal.
-
which openclawPrevisto: pad naar binary Se errato: leeg → PATH/npm prefix Prossimo: npm bin -g && export PATH="$(npm bin -g):$PATH" -
node --versionPrevisto: v18+ (liever v20 LTS) Se errato: v16 of lager → upgrade Node vóór reinstall CLI Prossimo: nvm use 20 && npm install -g openclaw
zsh: comando non trovato: openclaw
comando non trovato: openclaw- systemd:
ExecStartpath not found
- CLI werkt niet na
npm install -g - Gateway-unit start niet terwijl handmatige CLI later wel werkt
- Install onder user A, service draait als user B
- nvm niet geladen in non-interactive systemd shell
Hobby-installatie op laptop vs productie-VPS: op servers moet het pad in ExecStart expliciet naar de Node/npm van de service-user wijzen.
- systemd:
which openclawals service-user, pad in unit overnemen - Herstart shell of
daemon-reloadna unit-wijziging
Geen volledige stack-reinstall — fix PATH in unit-file of service-user shell profile.
ACCESSO: permesso negato
EACCES betekent: npm schrijft naar een map zonder rechten — fix eigendom of gebruik nvm; sudo npm install -g maakt het op termijn erger.
-
npm config get prefixPrevisto: map waar jij schrijfrechten hebt Se errato:/usr/localzonder ownership → EACCES Prossimo: chown prefix of switch naar nvm -
ls -la ~/.openclaw/Previsto: owned by service-user Se errato: root-owned files → agent/Gateway kan niet persisten Prossimo: chown naar service-user, least privilege
npm ERR! code EACCES npm ERR! path /usr/local/lib/node_modules
npm ERR! code EACCES- cannot create directory in
/usr/local/lib/node_modules
- Global install faalt
- Gateway kan plugins niet schrijven/lezend in home-map service-user
sudo npm install -g openclawgevolgd door service als normale user- config in root-home i.p.v. service-user
Least privilege: de Gateway hoeft geen root te zijn. Filesystem access voor agents moet beperkt tot expliciete mounts.
- Herstel ownership:
sudo chown -R serviceuser:serviceuser ~/.openclaw - Geen brede
chmod 777op projectmappen
Permissions fix ≠ reinstall; productie: dedicated user met minimale rechten (geen root Gateway).
Node.js Engine mismatch
OpenClaw Gateway en CLI vereisen Node.js 18+; onder v18 crasht de runtime direct met Engine/SyntaxError — Docker-image en systemd moeten dezelfde major gebruiken.
-
node --versionPrevisto: v20.x LTS Se errato: v16/v17 → upgrade Prossimo: nvm install 20 && nvm alias default 20 -
npm install -g openclawPrevisto: install OK onder Node 20 Se errato: engine error → verkeerde node in PATH Prossimo: systemctl restart openclaw
Engine: node >= 18.0.0 required, got 16.20.1
Engine: node >= 18.0.0 required- Unexpected token / SyntaxError bij gateway start
- Werkt in terminal (nvm 20) maar systemd start met system Node 16
- Crash direct na image upgrade
- Alleen Node in interactieve shell geüpgraded
- Docker base image niet mee-gepind
Gateway node en host Node moeten compatibel zijn — remote Gateway setups verergeren dit als client en server verschillende versies draaien.
- Pin Node in Dockerfile en systemd
Environment=PATH=...
Na Node-major upgrade: CLI opnieuw global installeren + Gateway restart; geen config-wipe nodig.
ETIMEDOUT / channel disconnect
ETIMEDOUT en channel disconnects wijzen op firewall/VPN, verkeerde gateway.remote.url, reverse proxy zonder WebSocket, of een overbelaste Gateway die geen nieuwe kanalen accepteert.
-
stato dei canali openclaw --probePrevisto: canali collegati Se errato: disconnect/timeout → netwerk of auth Prossimo: curl -v https://host/healthz en check proxy WS -
openclaw config get gateway.remote.urlPrevisto: bereikbare URL bij remote mode Se errato: verkeerde host/poort → ETIMEDOUT Prossimo: fix URL of schakel naar local mode
Error: connect ETIMEDOUT Discord: gateway READY wait timed out after 15000ms
connect ETIMEDOUTREADY wait timed out- websocket closed before connect
- missing node registration
- Endless reconnect loops in channel logs
- Health-check >10s achter nginx/Caddy
- Remote Gateway node niet geregistreerd — CLI OK, kanalen nee
- TLS termination op proxy zonder upstream WebSocket
- Tailscale/LAN expose zonder
gateway.auth - Cron/heartbeat uitgeschakeld — Gateway lijkt “slapend” maar is disconnected
Reverse proxy moet WebSocket en health routes doorlaten; anders lijkt de OpenClaw Gateway “up” op HTTP maar falen kanalen op WS.
- Beperk Gateway-poort via firewall; expose alleen via proxy met auth
- Test vanaf dezelfde host als de channel-worker draait
Logs uitlezen bij intermitterende disconnects; restart alleen na proxy/auth-fix — niet bij puur externe API-storing.
Agent reageert niet / geheugendruk
Gateway corsa, maar de agent voert niets uit: pending approvals, heap/OOM, of browser automation / filesystem tools die hangen.
-
registri openclaw --followPrevisto: agent run + model call na testbericht Se errato: stil na inbound → approval of tool block Prossimo: pending approvals legen of goedkeuren -
chirurgo a mano apertaPrevisto: geen memory/tool warnings Se errato: heap/tool warning → beperk tools, verhoog container memory Prossimo: systemctl restart openclaw
memory-pressure: heap threshold exceeded [agent/embedded] strict-agentic execution contract active — never appears
memory-pressure: heap threshold exceeded- approval pending
- browser session timeout
- tool execution denied
- Berichten binnen, geen antwoord — terminal logs tonen wel activity
- Approvals blijven hangen in UI/CLI
- Browser automation stopt na sessie-timeout; mail-acties wachten op approval
- Approvals uit in productie met echte mailbox/browser
- Geen sandbox op self-hosted AI agents met brede filesystem access
- Direct reinstall terwijl queue vol pending approvals staat
MKB automation met echte mailbox en browser-sessies verhoogt risico en RAM-gebruik; hobby-setup zonder approvals maskeert het probleem tot productie.
- Sandboxing + least privilege op tool-paden
- Scheid test-agent van productie-agent (eigen config profiel)
Approvals gevaarlijk als mail/shell/browser zonder mens-in-de-loop op productie; escaleer naar herinstallatie alleen bij corrupte agent-state na backup.
Sicurezza
Waarom OpenClaw
niet blind vertrouwen?
Risposta breve: Self-hosted AI agents met Gateway, filesystem access en browser automation zijn een uitgebreide aanvalsvector — niet “even een LLM op een VPS”.
- ✓ Prompt injection: instructies in e-mail, webpagina’s of user content kunnen de agent shell/mail/bestanden laten aanroepen. Beperk tools; approvals op destructieve acties.
- ✓ Least privilege: aparte Linux-user voor systemd/Docker; geen root Gateway; read-only mounts waar het kan.
-
✓
Container isolation: Docker Compose scheidt processen, maar deelt vaak volumes met
.env— secrets en config nooit in git. - ✓ Reverse proxy: expose alleen met auth/TLS; beperk WebSocket naar Gateway; geen open poort op internet.
- ✓ Browser session risico’s: ingelogde sessies + automation = credential-blok; apart profiel, korte TTL, approvals.
- ✓ Approvazioni: zonder mens-in-de-loop op productie is mail/shell gevaarlijk; hangende approvals lijken op “AI doet niets”. Soluzioni AI.
MKB-automation met echte mailbox vereist andere hardening dan een hobby-installatie. Software personalizzato voor afgeschermde integraties.
- Gateway: localhost of auth/token achter reverse proxy
.envchmod 600; API keys niet in compose/git- Sandbox + least privilege op agent tools
- Approvals: mail, shell, browser (productie verplicht)
- Health checks + alert bij Docker/systemd restart-loop
- Terminal logs bewaren bij incident (journalctl/compose)
Herinstallatie
Wanneer OpenClaw opnieuw installeren?
Risposta breve: restart bij vastgelopen proces; .env-fix zonder wipe; containers rebuild na bevestigde image-corruptie; volledige reinstall alleen met backup.
Wanneer is dit genoeg?
- →Restart: Gateway/Docker hing na config-wijziging — logs tonen fix, status weer
corsa - →.env fout: ontbrekende API key — key toevoegen + restart, geen reinstall
- →Logs uitlezen: intermitterende disconnects, approvals, OOM — vóór elke rebuild
- →Image rollback: Docker Compose na failed upgrade (config-volume behouden)
Wanneer volledige reinstall?
- →Twee concurrerende Gateways (npm + Docker) na opschonen nog conflicten
- →Corrupte plugin/agent-state —
doctorblijft falen na gerichte fix - ✕
rm -rf ~/.openclaw/ volume wipe zonder backup channel-state - ✕Reinstall terwijl approvals pending zijn (lijkt op “kapotte AI”)
Schone installatie: stappenplan installeren. Automatisering in bedrijfsprocessen: Automazione del marketing.
Incollato?
L'errore non è stato risolto?
Lo sistemeremo.
Productie vs hobby: op een VPS met reverse proxy, Docker Compose en echte mailbox/browser is de faalmodus anders dan op een laptop. Stuur chirurgo a mano aperta, gateway status --deep en 20–30 logregels uit journalctl di log di Docker Compose.
- ✓ Seguiteci in diretta nella vostra zona.
- ✓ Soluzione pronta per la produzione, non una soluzione tampone.
- ✓ Risposta entro 24 ore, anche su WhatsApp.
- ✓ A partire da 1.500 € - implementazione completa
Prima di contattarci, esegui questi brevi controlli:
Hai controllato tutto ma hai ancora problemi? Contattaci.
Risposta breve: Gateway niet pronto, fout in .env/openclaw.json, Docker malsano, of Node < 18.
Causa: proces of container start wel, maar health/auth/model faalt.
Aggiustare: openclaw gateway status → chirurgo a mano aperta → registri openclaw --follow (O journalctl -u openclaw-gateway -f).
Escaleren: na fix + restart nog stopped — check dubbele Gateway of corrupte plugins; installatie: Installa OpenClaw.
Risposta breve: openclaw gateway status — bij stopped di RPC probe: failed eerst logs, dan config/auth, dan restart.
Causa: poortconflict, ontbrekende gateway.auth, WebSocket/proxy-probleem, plugin-hang.
Aggiustare: registri openclaw --follow, stato dei canali openclaw --probe, openclaw config get gateway.mode.
Escaleren: herstart helpt niet na doctor-fix → dubbele installatie of node-registratie opschonen.
Risposta breve: docker compose logs -f --tail=80 vóór elke restart — malsano = /salute faalt in de container.
Causa: Gateway niet pronto, verkeerde poort in Docker Compose, OOM (Uscita 137).
Aggiustare: docker compose ps, curl …/healthz, config-volume en .env alignen, docker compose restart.
Escaleren: image-tag terugzetten; volumes niet wissen zonder backup.
Risposta breve: Key ontbreekt in de actieve service-.env, of model/provider in openclaw.json klopt niet — Gateway kan corsa zijn zonder werkende upstream.
Causa: split tussen CLI-user en systemd/Docker-user; verlopen OAuth; verkeerde Ollama/OpenAI-compatible URL.
Aggiustare: openclaw config get + chmod 600 .env → Gateway restart.
Escaleren: 401 blijft na rotatie → provider-limiet/regio; geen volledige reinstall.
Risposta breve: Alleen met least privilege, approvals op mail/shell/browser, sandboxing en geen open Gateway achter internet.
Causa del rischio: self-hosted AI agents met filesystem access + prompt injection via mail/web.
Aggiustare: aparte service-user, reverse proxy met auth, container isolation, log monitoring.
Escaleren: productie met echte mailbox → Sicurezza; hobby-setup is geen productiemodel.
Risposta breve: Pas als chirurgo a mano aperta + gerichte restart + log-analyse falen — mét backup van ~/.openclaw/ e .env.
Causa: corrupte plugin-state, twee Gateways, verkeerde image na upgrade.
Fix eerst: restart, .env corrigeren, Docker image pin/rollback — geen rm -rf.
Escaleren: volledige reinstall + volume wipe alleen na export config/channel-state.
Risposta breve: registri openclaw --follow — live terminal logs van de Gateway; systemd: journalctl -u openclaw-gateway -f.
Oorzaak lege logs: je leest de verkeerde unit/user of de service draait niet.
Aggiustare: eerst openclaw gateway status, dan logs tijdens één testbericht.
Escaleren: geen pronto in logs → zie Gateway/Docker-blokken op deze pagina.
Risposta breve: Ja — Gateway op VPS, Docker Compose, systemd, approvals en MKB-automation buiten hobby-PATH-problemen.
Meesturen: output chirurgo a mano aperta, gateway status --deep, 20–30 relevante logregels.
Fix-scope: config-hardening, proxy/WebSocket, split-brain .env.
Il problema con OpenClaw non è stato risolto?
Ci tuffiamo.
Stuur je Gateway-status, relevante logregels en wat je al geprobeerd hebt. We reageren binnen 24 uur met een concreet vervolg — geen generiek adviesdocument.