OpenClaw met Service Unavailable duidt niet op één specifieke fout. In de IceWhale Community-thread uit februari 2026 kwamen tijdens het oplossen achtereenvolgens drie verschillende lagen aan het licht: een vereist gatewaytoken, onvoldoende rechten om Docker vanaf het ZimaOS-hostaccount te inspecteren en ten slotte een OpenClaw-container die de initiële configuratie nooit had voltooid.
De thread is vooral nuttig omdat enkele tussentijdse suggesties onjuist bleken voor de door Big-Bear verpakte image. Het toevoegen van een verzonnen GATEWAY_MODE het omgevingsvariabele loste de herstartlus niet op, en het toevoegen van --gateway.mode=local het verkeerde commando resulteerde in een onbekende optie fout. De huidige OpenClaw-documentatie bevestigt dat gateway.mode=local hoort thuis in de permanente configuratie van OpenClaw en Docker-implementaties de onboarding of installatie moeten uitvoeren om die configuratie aan te maken.
Controleer eerst of de OpenClaw-container daadwerkelijk actief is
In het oorspronkelijke bericht meldde de OpenClaw-app dat de toepassing niet goed werkte en toonde deze een tip over OPENCLAW_GATEWAY_TOKEN.
Controleer de containerstatus op de ZimaOS- of CasaOS-host voordat u de applicatie-instellingen wijzigt:
docker ps -a | grep openclawAls de container opnieuw wordt gestart of is afgesloten, lees dan de logs:
docker logs big-bear-openclaw --tail 100De exacte containernaam kan verschillen. Gebruik docker ps -a om de werkelijke naam te achterhalen in plaats van aan te nemen dat deze altijd big-bear-openclaw.
OPENCLAW_GATEWAY_TOKEN genereren en opslaan
De eerste suggestie uit de community was om een sterk willekeurig gatewaytoken te genereren:
openssl rand -hex 32Als OpenSSL niet beschikbaar is, bood de thread een lokaal alternatief voor willekeurige bytes:
head -c 32 /dev/urandom | xxd -p -c 32De huidige officiële Docker-documentatie van OpenClaw gebruikt ook OPENCLAW_GATEWAY_TOKEN voor gatewayauthenticatie. Het standaardinstallatiescript genereert een token en schrijft dit naar het .env bestand automatisch. Voer in een handmatig verpakte CasaOS-toepassing de gegenereerde waarde in het omgevingsvariabeleveld in dat door die image wordt verwacht.
Behandel dit token als een geheim. Plaats het niet op een openbaar forum, in een schermafbeelding, supportticket of repository.
Een Docker-machtigingsfout is geen OpenClaw-machtigingsfout
Nadat er een token was toegevoegd, kreeg de oorspronkelijke auteur deze fout:
toestemming geweigerd bij het verbinden met de Docker-daemonsocket
/var/run/docker.sock: verbinden: toestemming geweigerd
The community recommendation was to elevate temporarily before running administrative Docker commands:
De aanbeveling van de community was om tijdelijk verhoogde rechten te gebruiken voordat administratieve Docker-opdrachten werden uitgevoerd:
sudo -idocker ps Gebruik alleen rootrechten voor opdrachten die deze daadwerkelijk vereisen. Verzwak machtigingen aan te passen of de Docker-socket wereldschrijfbaar te maken alleen om de fout te verwijderen. Toegang tot Docker geeft feitelijk beheerderscontrole over de host.
De echte OpenClaw-fout was “Missing config”
Zodra de Docker-logs toegankelijk waren, verscheen de belangrijke melding:
Missing config. Run `openclaw setup` or set gateway.mode=local
Dit was bruikbaarder dan de algemene pagina over de servicestoring. De huidige gatewaydocumentatie van OpenClaw bevestigt dat de gateway normaal gesproken niet start tenzij de configuratie het volgende bevat:
gateway.mode = localDe huidige versie van OpenClaw vermeldt ook dat OpenClaw instellen of openclaw onboard --mode local schrijft de lokale gatewaymodus naar de persistente configuratie.
Waarom GATEWAY_MODE=local deze image niet repareerde
Een tussentijdse reactie van de community stelde voor om het volgende toe te voegen:
Vertrouw niet opDe gebruiker probeerde dit en de herstartlus ging door. Dat is een belangrijke correctie om te behouden: de huidige officiële OpenClaw-documentatie definieert geen generieke GATEWAY_MODE omgevingsvariabele als vervanging voor de persistente gateway.mode instelling die in deze workflow wordt gebruikt.
Zet niet elke OpenClaw-configuratiesleutel met punten om in een zelfbedachte hoofdletterige omgevingsvariabele. Gebruik de configuratiemethode die wordt beschreven voor de exacte OpenClaw-image of de exacte implementatietemplate.
Waarom --gateway.mode=local “Unknown option” opleverde
Een latere poging van de community voegde het volgende toe:
--gateway.mode=localaan de containeropdracht van CasaOS. De image gaf vervolgens het volgende terug:
unknown option '--gateway.mode'De thread identificeerde correct waarom: CasaOS voegde de optie toe aan een commandolaag die deze niet accepteerde. De huidige CLI van OpenClaw gebruikt opdrachten zoals openclaw gateway, OpenClaw instellen, openclaw onboarden openclaw config set; gateway.mode is een configuratiesleutel, geen universele runtime-optie op topniveau die overal in een containeropdracht kan worden geplaatst.
De Big-Bear-image had een persistente, geïnitialiseerde configuratiemap nodig
De uiteindelijke diagnose van de community richtte zich op deze koppeling:
/DATA/AppData/big-bear-openclaw
→ /home/node/.openclawDe container verwachtte de configuratie onder /home/node/.openclaw, maar de gekoppelde map was nog niet geïnitialiseerd. Dit komt overeen met de huidige OpenClaw-documentatie voor Docker: de gekoppelde configuratiemap bevat de persistente openclaw.json, authenticatieprofielgegevens en omgevingsvariabelegebaseerde geheimen.
De laatste suggestie in de thread was om de configuratie in de container uit te voeren, zodat de gekoppelde map een daadwerkelijke OpenClaw-configuratie zou ontvangen. De oorspronkelijke poster kwam na die laatste reactie echter niet terug met een definitieve bevestiging. Beschouw dit daarom als de sterkste diagnose in de thread, niet als een geverifieerde definitieve oplossing.
Geef bij een nieuwe installatie de voorkeur aan de huidige OpenClaw Docker-onboarding
Volg voor een actuele implementatie de officiële OpenClaw Docker-installatiehandleiding in plaats van de probleemoplossingsreeks uit 2026 fout voor fout opnieuw op te bouwen.
OpenClaw biedt momenteel een Docker-installatiescript dat:
- bouwt de gateway-image of haalt deze op;
- voert onboarding uit;
- genereert een gatewaytoken;
- schrijft persistente configuratie;
- maakt de vereiste geheime mappen aan;
- start de gateway via Docker Compose.
Voor headless Docker-implementaties documenteert OpenClaw momenteel ook niet-interactieve onboarding met lokale gatewaymodus en tokenauthenticatie. Dat verdient de voorkeur boven het zelf bedenken van omgevingsvariabelen of het toevoegen van niet-ondersteunde flags.
Huidig patroon voor handmatige configuratie
De huidige Docker-handleiding van OpenClaw documenteert een handmatig patroon dat hiermee overeenkomt:
openclaw onboard --mode local --no-install-daemon
openclaw config set gateway.mode local
openclaw config set gateway.bind lanIn Docker Compose worden deze opdrachten normaal uitgevoerd via de speciale CLI- of onboardingcontainer die door het project is gedefinieerd. Plak opdrachten die op de host zijn bedoeld niet zomaar in een verpakte CasaOS-image zonder eerst de entrypoint en mounts ervan te controleren.
De huidige documentatie over de OpenClaw Gateway CLI bevestigt dat openclaw setup en openclaw onboard --mode local de vereiste lokale gatewayconfiguratie aanmaken.
Gebruik dezelfde gatewaytoken in de Control UI
De huidige OpenClaw-documentatie voor Docker stelt de Control UI beschikbaar op poort 18789 in de standaard-Compose-configuratie en instrueert gebruikers om de gatewaytoken uit de implementatieomgeving in de UI-instellingen te plakken.
Een tokenmismatch kan authenticatiefouten veroorzaken nadat de gateway gezond is, maar verschilt van een container die herhaaldelijk afsluit omdat er geen configuratie bestaat. Diagnoseer eerst het opstartprobleem en daarna de UI-authenticatie.
Maak van --allow-unconfigured niet de permanente oplossing
OpenClaw biedt --allow-unconfigured voor ad-hoc- of ontwikkelopstart. In de huidige documentatie staat expliciet dat hiermee de bewaking van de lokale modus wordt omzeild, zonder configuratie te schrijven of te herstellen. Dit is nuttig voor tests, maar vervangt geen correcte onboarding van een persistente server.
Checklist voor het oplossen van problemen met de OpenClaw-service die niet beschikbaar is
- Controleer of de OpenClaw-container actief is, is afgesloten of steeds opnieuw wordt gestart.
- Lees de huidige containerlogs voordat je instellingen wijzigt.
- Controleer
OPENCLAW_GATEWAY_TOKENbestaat en als geheim wordt behandeld. - Als Docker-opdrachten mislukken met ‘permission denied’ voor de socket, gebruik dan een geautoriseerde beheerdersshell in plaats van de rechten van de Docker-socket te versoepelen.
- Zoek specifiek naar
Ontbrekende configuratieofgateway.mode=localfouten. - Controleer of het AppData-pad op de host is gekoppeld aan de OpenClaw-configuratiemap die de image verwacht.
- Voer de ondersteunde installatie- of onboardingprocedure van OpenClaw uit, zodat
openclaw.jsonis aangemaakt in persistente opslag. - GATEWAY_MODE=local
Vertrouw niet opniet toe, tenzij de documentatie van de exacte image dit expliciet definieert. - Voeg
--gateway.mode=localaan een willekeurige CasaOS-containeropdracht. - Start de container opnieuw en controleer de logs opnieuw nadat de configuratie is opgeslagen.
- Pas nadat de gateway actief blijft, moet je problemen met tokenauthenticatie in de Control UI of met de configuratie van modelproviders oplossen.
Veelgestelde vragen over OpenClaw Service Unavailable
Heeft OpenClaw OPENCLAW_GATEWAY_TOKEN nodig?
Huidige OpenClaw-Dockerimplementaties ondersteunen en gebruiken doorgaans OPENCLAW_GATEWAY_TOKEN voor gatewayauthenticatie. Het officiële installatiescript kan er automatisch een genereren. Pakketten en images van derden kunnen deze waarde op een andere manier beschikbaar maken; volg daarom het daadwerkelijke omgevingsschema van de image.
Wat betekent “permission denied /var/run/docker.sock”?
Dit betekent dat de huidige hostgebruiker geen toegang heeft tot de Docker-daemon. Het betekent op zichzelf niet dat de interne gegevensmap van OpenClaw niet schrijfbaar is. Gebruik voor Docker-diagnostiek een geautoriseerd beheerdersaccount.
Hoe stel ik gateway.mode=local in?
Gebruik de ondersteunde installatie-, onboarding- of configuratieopdracht van OpenClaw, zodat de waarde wordt opgeslagen in de persistente openclaw.json. In de huidige documentatie staat OpenClaw instellen of openclaw onboard --mode local maakt deze instelling aan.
Moet ik GATEWAY_MODE=local toevoegen?
Niet op basis van deze thread. Die suggestie loste de restartlus van de verpakte image van de gebruiker niet op, en de huidige upstreamdocumentatie behandelt gateway.mode als configuratie in plaats van een generieke omgevingsvariabele met de naam GATEWAY_MODE.
Waarom geeft --gateway.mode=local de melding ‘onbekende optie’?
Omdat de optie aan de verkeerde opdrachtlaag in het CasaOS-pakket was toegevoegd. Een configuratiesleutel met punten is niet automatisch een geldige opdrachtregeloptie voor elke OpenClaw-binary of elk entrypoint.
Is de communitythread definitief opgelost?
De thread kwam uit bij een sterke einddiagnose—een niet-geïnitialiseerde persistente configuratiemap—en adviseerde om OpenClaw instellen in de container. De oorspronkelijke poster heeft na die laatste instructie geen definitieve bevestiging geplaatst. De pagina mag daarom geen geverifieerde oplossing claimen die niet in de bron staat.
