OpenClaw
troubleshooting
Gateway die niet ready 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?
Short answer: OpenClaw-problemen komen bijna altijd van de OpenClaw Gateway (niet ready), Docker Compose (unhealthy), .env / API keys, of runtime (approvals, geheugen).
Eerste commando’s: openclaw gateway status → open claw doctor → openclaw logs --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. Install · Hub.
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 -
→
openclaw logs --follow— zoekready,EADDRINUSE, auth-fouten -
→
journalctl -u openclaw-gateway -f— bij systemd; failed = unit/config, niet “Anthropic down” -
→
open claw doctor— 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— naDocker compose logs; unhealthy zonder log-read = gokken - → Restart volstaat bij vastgelopen Gateway; reinstall pas na doctor + backup
Docker Compose & health
-
→
docker compose ps—unhealthy= 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 ready door poortconflict, ontbrekende gateway.auth, verkeerde gateway.mode, of een vastgelopen WebSocket/event-loop na upgrade.
-
openclaw gateway statusExpected:Runtime: runningandRPC probe: okIf incorrect:stoppedorfailed→ proces start niet of auth/poort blokkeert Next: openclaw logs --follow -
sudo systemctl status openclawExpected:Active: active (running)If incorrect:failedof restart-loop → systemd-unit of Node-pad klopt niet Next: journalctl -u openclaw-gateway -n 80 --no-pager -
open claw doctorExpected: geen blocking issues If incorrect: auth/mode/poort-waarschuwing → fixopenclaw.jsonvóór restart Next: 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 —
openclaw channels status --probefaalt - Health-check /
/healthztimeout 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
/healthz - 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 without ready; herinstallatie pas na dubbele Gateway-installatie of corrupte plugin-state.
Docker-container unhealthy / healthz timeout
Docker Compose markeert de Gateway-container als unhealthy wanneer /healthz binnen de container faalt — meestal Gateway niet ready, verkeerde poort-mapping, of OOM (Exit 137).
-
docker compose psExpected: STATUSrunning(geenunhealthy) If incorrect:unhealthyorrestarting→ healthcheck faalt Next: docker compose logs -f --tail=80 -
curl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/healthzExpected:200If incorrect:000of timeout → poort of Gateway in container Next: openclaw gateway status (in container of via exec) -
docker compose restartExpected: container stabiel na config-fix If incorrect: blijft unhealthy → image-tag terugzetten, geen volume-wipe Next: 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)
unhealthyindocker compose psExit 137(OOM)health check failedcan't connect to localhost:18789
- RestartCount stijgt — container in crash-loop
- Host-
curlnaar geëxposeerde poort geeft geen 200 op/healthz - Gateway in container start wel
runtime.early, nooitready
- Poort in compose wijkt af van
gateway.portin config network_mode: 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
.envandopenclaw.jsonconsistent in volume — service-user ≠ host-user is een veelvoorkomende split-brain - Productie: aparte compose-projectnaam per omgeving, geen
latestzonder 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.modeExpected: verwachte auth-modus (niet leeg) If incorrect: leeg of error →openclaw.jsonincompleet Next: ls -la ~/.openclaw/ && vergelijk Docker volume -
grep -E "ANTHROPIC|OPENAI|OLLAMA" .envExpected: keys aanwezig (niet tonen in tickets) If incorrect: ontbrekend → vul .env, chmod 600 Next: systemctl restart openclaw of docker compose restart -
open claw doctorExpected: provider + gateway OK If incorrect: upstream/auth warning → key rotatie of OAuth-profiel vernieuwen Next: 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
curl, 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
Bee .env-fout: geen reinstall — fix keys en restart Gateway; escaleren als CLI en service na sync nog verschillende paden gebruiken.
command not found: openclaw
OpenClaw staat niet in $PATH — npm global bin ontbreekt in shell, of systemd gebruikt een andere Node/npm dan je terminal.
-
which openclawExpected: pad naar binary If incorrect: leeg → PATH/npm prefix Next: npm bin -g && export PATH="$(npm bin -g):$PATH" -
node --versionExpected: v18+ (liever v20 LTS) If incorrect: v16 of lager → upgrade Node vóór reinstall CLI Next: nvm use 20 && npm install -g openclaw
zsh: command not found: openclaw
command not found: 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.
ACCESS: permission denied
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 prefixExpected: map waar jij schrijfrechten hebt If incorrect:/usr/localzonder ownership → EACCES Next: chown prefix of switch naar nvm -
ls -la ~/.openclaw/Expected: owned by service-user If incorrect: root-owned files → agent/Gateway kan niet persisten Next: 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 --versionExpected: v20.x LTS If incorrect: v16/v17 → upgrade Next: nvm install 20 && nvm alias default 20 -
npm install -g openclawExpected: install OK onder Node 20 If incorrect: engine error → verkeerde node in PATH Next: 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.
-
openclaw channels status --probeExpected: channels connected If incorrect: disconnect/timeout → netwerk of auth Next: curl -v https://host/healthz en check proxy WS -
openclaw config get gateway.remote.urlExpected: bereikbare URL bij remote mode If incorrect: verkeerde host/poort → ETIMEDOUT Next: 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 running, maar de agent voert niets uit: pending approvals, heap/OOM, of browser automation / filesystem tools die hangen.
-
openclaw logs --followExpected: agent run + model call na testbericht If incorrect: stil na inbound → approval of tool block Next: pending approvals legen of goedkeuren -
open claw doctorExpected: geen memory/tool warnings If incorrect: heap/tool warning → beperk tools, verhoog container memory Next: 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.
safety
Waarom OpenClaw
niet blind vertrouwen?
Short answer: 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.
- ✓ Approvals: zonder mens-in-de-loop op productie is mail/shell gevaarlijk; hangende approvals lijken op “AI doet niets”. AI solutions.
MKB-automation met echte mailbox vereist andere hardening dan een hobby-installatie. Custom software 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?
Short answer: 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
running - →.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: marketing automation.
Stuck?
Error not resolved?
We will fix it.
Productie vs hobby: op een VPS met reverse proxy, Docker Compose en echte mailbox/browser is de faalmodus anders dan op een laptop. Stuur open claw doctor, gateway status --deep en 20–30 logregels uit journalctl or Docker compose logs.
- ✓ Watch along directly in your area
- ✓ Production-ready solution, not a quick fix
- ✓ Response within 24 hours — also on WhatsApp
- ✓ From €1,500— full implementation
Before you get in touch, go through these quick checks:
All boxes checked but still stuck? Contact us.
Short answer: Gateway niet ready, fout in .env/openclaw.json, Docker unhealthy, of Node < 18.
Cause: proces of container start wel, maar health/auth/model faalt.
Fix: openclaw gateway status → open claw doctor → openclaw logs --follow (or journalctl -u openclaw-gateway -f).
Escaleren: na fix + restart nog stopped — check dubbele Gateway of corrupte plugins; installatie: Install OpenClaw.
Short answer: openclaw gateway status — bij stopped or RPC probe: failed eerst logs, dan config/auth, dan restart.
Cause: poortconflict, ontbrekende gateway.auth, WebSocket/proxy-probleem, plugin-hang.
Fix: openclaw logs --follow, openclaw channels status --probe, openclaw config get gateway.mode.
Escaleren: herstart helpt niet na doctor-fix → dubbele installatie of node-registratie opschonen.
Short answer: docker compose logs -f --tail=80 vóór elke restart — unhealthy = /healthz faalt in de container.
Cause: Gateway niet ready, verkeerde poort in Docker Compose, OOM (Exit 137).
Fix: docker compose ps, curl …/healthz, config-volume en .env alignen, docker compose restart.
Escaleren: image-tag terugzetten; volumes niet wissen zonder backup.
Short answer: Key ontbreekt in de actieve service-.env, of model/provider in openclaw.json klopt niet — Gateway kan running zijn zonder werkende upstream.
Cause: split tussen CLI-user en systemd/Docker-user; verlopen OAuth; verkeerde Ollama/OpenAI-compatible URL.
Fix: openclaw config get + chmod 600 .env → Gateway restart.
Escaleren: 401 blijft na rotatie → provider-limiet/regio; geen volledige reinstall.
Short answer: Alleen met least privilege, approvals op mail/shell/browser, sandboxing en geen open Gateway achter internet.
Cause of risk: self-hosted AI agents met filesystem access + prompt injection via mail/web.
Fix: aparte service-user, reverse proxy met auth, container isolation, log monitoring.
Escaleren: productie met echte mailbox → safety; hobby-setup is geen productiemodel.
Short answer: Pas als open claw doctor + gerichte restart + log-analyse falen — mét backup van ~/.openclaw/ and .env.
Cause: 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.
Short answer: openclaw logs --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.
Fix: eerst openclaw gateway status, dan logs tijdens één testbericht.
Escaleren: geen ready in logs → zie Gateway/Docker-blokken op deze pagina.
Short answer: Ja — Gateway op VPS, Docker Compose, systemd, approvals en MKB-automation buiten hobby-PATH-problemen.
Meesturen: output open claw doctor, gateway status --deep, 20–30 relevante logregels.
Fix-scope: config-hardening, proxy/WebSocket, split-brain .env.
OpenClaw problem not solved?
We're diving in.
Stuur je Gateway-status, relevante logregels en wat je al geprobeerd hebt. We reageren binnen 24 uur met een concreet vervolg — geen generiek adviesdocument.