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.

✓ Gateway, Docker & config
✓ macOS, Windows e Linux
✓ Soluzioni Node.js v18+
✓ È disponibile assistenza professionale.

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.

1e
Gateway check
v20
Node LTS
docker
+ systemd
E-E-A-T
Server-debug

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 — verwacht Runtime: running; anders logs openen
  • → registri openclaw --follow — zoek pronto, 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 — na log 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 — 200 verwacht; 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

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.

  1. openclaw gateway status Previsto: Runtime: running e RPC probe: ok Se errato: stopped di failed → proces start niet of auth/poort blokkeert Prossimo: registri openclaw --follow
  2. sudo systemctl status openclaw Previsto: Active: active (running) Se errato: failed of restart-loop → systemd-unit of Node-pad klopt niet Prossimo: journalctl -u openclaw-gateway -n 80 --no-pager
  3. chirurgo a mano aperta Previsto: geen blocking issues Se errato: auth/mode/poort-waarschuwing → fix openclaw.json vóór restart Prossimo: sudo systemctl restart openclaw
terminale
openclaw gateway status
Runtime: stopped
RPC probe: failed
Gateway start blocked: set gateway.mode=local
  • Runtime: stopped
  • RPC probe: failed
  • EADDRINUSE
  • Gateway start blocked: set gateway.mode=local
  • endless reconnect in channel logs
  • Kanalen (Telegram/Discord) disconnected — stato dei canali openclaw --probe faalt
  • Health-check / /salute timeout 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.url terwijl 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.

  1. Poortconflict: proces op listener-poort stoppen, één Gateway per host
  2. Reverse proxy: WebSocket-upgrade + health-route naar /salute
  3. 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

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

  1. docker compose ps Previsto: STATO corsa (geen malsano) Se errato: malsano di restarting → healthcheck faalt Prossimo: docker compose logs -f --tail=80
  2. curl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/healthz Previsto: 200 Se errato: 000 of timeout → poort of Gateway in container Prossimo: openclaw gateway status (in container of via exec)
  3. docker compose restart Previsto: 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
terminale
docker compose ps
openclaw-gateway   unhealthy   Exit 137
wget: can't connect to remote host (localhost:18789)
  • malsano In docker compose ps
  • Uscita 137 (OOM)
  • health check failed
  • can't connect to localhost:18789
  • RestartCount stijgt — container in crash-loop
  • Host-arricciare naar geëxposeerde poort geeft geen 200 op /salute
  • Gateway in container start wel runtime.presto, nooit pronto
  • Poort in compose wijkt af van gateway.port in 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.

  1. Map .env e openclaw.json consistent in volume — service-user ≠ host-user is een veelvoorkomende split-brain
  2. Productie: aparte compose-projectnaam per omgeving, geen ultimo zonder pin

Container rebuild alleen bij kapotte image/layers; restart na .env-fix; volledige reinstall alleen met backup van config-volumes.

Configurazione

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

  1. openclaw config get gateway.auth.mode Previsto: verwachte auth-modus (niet leeg) Se errato: leeg of error → openclaw.json incompleet Prossimo: ls -la ~/.openclaw/ && vergelijk Docker volume
  2. grep -E "ANTHROPIC|OPENAI|OLLAMA" .env Previsto: keys aanwezig (niet tonen in tickets) Se errato: ontbrekend → vul .env, chmod 600 Prossimo: systemctl restart openclaw of docker compose restart
  3. chirurgo a mano aperta Previsto: provider + gateway OK Se errato: upstream/auth warning → key rotatie of OAuth-profiel vernieuwen Prossimo: testbericht via kanaal, logs --follow
terminale
Error: Missing required env: ANTHROPIC_API_KEY
Config: ~/.openclaw/openclaw.json
Gateway auth.token: (empty)
  • Missing required env: ANTHROPIC_API_KEY
  • 401 / invalid_api_key in agent logs
  • gateway.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.json staat

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

  1. Eén bron van waarheid: .env + openclaw.json voor dezelfde user als systemd User=
  2. Ollama: base-URL en model-id in config moeten matchen met wat curl http://127.0.0.1:11434/api/tags toont

Ape .env-fout: geen reinstall — fix keys en restart Gateway; escaleren als CLI en service na sync nog verschillende paden gebruiken.

Installazione

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.

  1. which openclaw Previsto: pad naar binary Se errato: leeg → PATH/npm prefix Prossimo: npm bin -g && export PATH="$(npm bin -g):$PATH"
  2. node --version Previsto: v18+ (liever v20 LTS) Se errato: v16 of lager → upgrade Node vóór reinstall CLI Prossimo: nvm use 20 && npm install -g openclaw
terminale
zsh: comando non trovato: openclaw
  • comando non trovato: openclaw
  • systemd: ExecStart path 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.

  1. systemd: which openclaw als service-user, pad in unit overnemen
  2. Herstart shell of daemon-reload na unit-wijziging

Geen volledige stack-reinstall — fix PATH in unit-file of service-user shell profile.

Autorizzazioni

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.

  1. npm config get prefix Previsto: map waar jij schrijfrechten hebt Se errato: /usr/local zonder ownership → EACCES Prossimo: chown prefix of switch naar nvm
  2. 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
terminale
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 openclaw gevolgd 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.

  1. Herstel ownership: sudo chown -R serviceuser:serviceuser ~/.openclaw
  2. Geen brede chmod 777 op projectmappen

Permissions fix ≠ reinstall; productie: dedicated user met minimale rechten (geen root Gateway).

Versione Node.js

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.

  1. node --version Previsto: v20.x LTS Se errato: v16/v17 → upgrade Prossimo: nvm install 20 && nvm alias default 20
  2. npm install -g openclaw Previsto: install OK onder Node 20 Se errato: engine error → verkeerde node in PATH Prossimo: systemctl restart openclaw
terminale
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.

  1. Pin Node in Dockerfile en systemd Environment=PATH=...

Na Node-major upgrade: CLI opnieuw global installeren + Gateway restart; geen config-wipe nodig.

Rete

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.

  1. stato dei canali openclaw --probe Previsto: canali collegati Se errato: disconnect/timeout → netwerk of auth Prossimo: curl -v https://host/healthz en check proxy WS
  2. openclaw config get gateway.remote.url Previsto: bereikbare URL bij remote mode Se errato: verkeerde host/poort → ETIMEDOUT Prossimo: fix URL of schakel naar local mode
terminale
Error: connect ETIMEDOUT
Discord: gateway READY wait timed out after 15000ms
  • connect ETIMEDOUT
  • READY 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.

  1. Beperk Gateway-poort via firewall; expose alleen via proxy met auth
  2. 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.

Tempo di esecuzione

Agent reageert niet / geheugendruk

Gateway corsa, maar de agent voert niets uit: pending approvals, heap/OOM, of browser automation / filesystem tools die hangen.

  1. registri openclaw --follow Previsto: agent run + model call na testbericht Se errato: stil na inbound → approval of tool block Prossimo: pending approvals legen of goedkeuren
  2. chirurgo a mano aperta Previsto: geen memory/tool warnings Se errato: heap/tool warning → beperk tools, verhoog container memory Prossimo: systemctl restart openclaw
terminale
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.

  1. Sandboxing + least privilege op tool-paden
  2. 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.

🛡 Minimale hardening-checklist
  • Gateway: localhost of auth/token achter reverse proxy
  • .env chmod 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 — doctor blijft 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
🔍 Lista di controllo: fai questo per primo

Prima di contattarci, esegui questi brevi controlli:

Hai controllato tutto ma hai ancora problemi? Contattaci.

FAQ

FAQ — direct
antwoord eerst

Elke vraag begint met een korte regel die ook losstaand klopt (snippets, AI-overviews). Daarna pas detail en commando’s.

Poni la tua domanda →

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.

Contatto · OpenClaw overzicht

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.

✓ Conversazione libera
✓ Risposta entro 24 ore
✓ Soluzione pronta per la produzione
✓ Hosting olandese ed europeo