Naar hoofdinhoud gaan

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

De Control UI is een kleine Vite + Lit single-page-app die door de Gateway wordt geserveerd:
  • standaard: http://<host>:18789/
  • optioneel voorvoegsel: stel gateway.controlUi.basePath in (bijv. /openclaw)
Deze communiceert rechtstreeks met de Gateway WebSocket op dezelfde poort.

​
Snel openen (lokaal)

Als de Gateway op dezelfde computer draait, open dan: Als de pagina niet laadt, start dan eerst de Gateway: openclaw gateway. Auth wordt tijdens de WebSocket-handshake geleverd via:
  • connect.params.auth.token
  • connect.params.auth.password
  • Tailscale Serve-identiteitsheaders wanneer gateway.auth.allowTailscale: true
  • vertrouwde-proxy-identiteitsheaders wanneer gateway.auth.mode: "trusted-proxy"
Het instellingenpaneel van het dashboard bewaart een token voor de huidige browsertabsessie en de geselecteerde Gateway-URL; wachtwoorden worden niet bewaard. Onboarding genereert meestal bij de eerste verbinding een Gateway-token voor auth met gedeeld geheim, maar wachtwoordauth werkt ook wanneer gateway.auth.mode "password" is.

​
Apparaatkoppeling (eerste verbinding)

Wanneer je vanaf een nieuwe browser of nieuw apparaat verbinding maakt met de Control UI, vereist de Gateway meestal een eenmalige koppelingsgoedkeuring. Dit is een beveiligingsmaatregel om ongeautoriseerde toegang te voorkomen. Wat je ziet: “verbinding verbroken (1008): koppeling vereist”
1

Openstaande verzoeken tonen

openclaw devices list
2

Goedkeuren op verzoek-ID

openclaw devices approve <requestId>
Als de browser opnieuw probeert te koppelen met gewijzigde auth-gegevens (rol/scopes/openbare sleutel), wordt het vorige openstaande verzoek vervangen en wordt een nieuwe requestId aangemaakt. Voer openclaw devices list opnieuw uit vóór goedkeuring. Als de browser al gekoppeld is en je deze wijzigt van leestoegang naar schrijf-/admintoegang, wordt dit behandeld als een goedkeuringsupgrade, niet als een stille herverbinding. OpenClaw houdt de oude goedkeuring actief, blokkeert de bredere herverbinding en vraagt je om de nieuwe set scopes expliciet goed te keuren. Na goedkeuring wordt het apparaat onthouden en is geen hernieuwde goedkeuring nodig, tenzij je het intrekt met openclaw devices revoke --device <id> --role <role>. Zie Apparaten-CLI voor tokenrotatie en intrekking.
  • Directe browserverbindingen via local loopback (127.0.0.1 / localhost) worden automatisch goedgekeurd.
  • Tailscale Serve kan de koppelingsronde overslaan voor Control UI-operatorsessies wanneer gateway.auth.allowTailscale: true, de Tailscale-identiteit is geverifieerd en de browser zijn apparaatidentiteit aanbiedt.
  • Directe Tailnet-binds, LAN-browserverbindingen en browserprofielen zonder apparaatidentiteit vereisen nog steeds expliciete goedkeuring.
  • Elk browserprofiel genereert een unieke apparaat-ID, dus wisselen van browser of het wissen van browsergegevens vereist opnieuw koppelen.

​
Persoonlijke identiteit (browserlokaal)

De Control UI ondersteunt een persoonlijke identiteit per browser (weergavenaam en avatar) die aan uitgaande berichten wordt gekoppeld voor attributie in gedeelde sessies. Deze staat in browseropslag, is beperkt tot het huidige browserprofiel en wordt niet gesynchroniseerd met andere apparaten of server-side bewaard buiten de normale transcript-auteurschapsmetadata op berichten die je daadwerkelijk verzendt. Het wissen van sitegegevens of wisselen van browser zet deze terug naar leeg. Hetzelfde browserlokale patroon geldt voor de override van de assistentavatar. Geüploade assistentavatars leggen de door de Gateway opgeloste identiteit alleen over de lokale browser heen en gaan nooit heen en weer via config.patch. Het gedeelde configuratieveld ui.assistant.avatar blijft beschikbaar voor niet-UI-clients die het veld rechtstreeks schrijven (zoals gescripte gateways of aangepaste dashboards).

​
Runtime-configuratie-eindpunt

De Control UI haalt zijn runtime-instellingen op uit /__openclaw/control-ui-config.json. Dat eindpunt wordt afgeschermd door dezelfde Gateway-auth als de rest van het HTTP-oppervlak: niet-geauthenticeerde browsers kunnen het niet ophalen, en een succesvolle fetch vereist een al geldig Gateway-token/wachtwoord, een Tailscale Serve-identiteit of een vertrouwde-proxy-identiteit.

​
Taalondersteuning

De Control UI kan zichzelf bij de eerste keer laden lokaliseren op basis van je browserlocale. Om dit later te overschrijven, open je Overzicht -> Gateway-toegang -> Taal. De locale-kiezer staat in de kaart Gateway-toegang, niet onder Weergave.
  • Ondersteunde locales: en, zh-CN, zh-TW, pt-BR, de, es, ja-JP, ko, fr, ar, it, tr, uk, id, pl, th, vi, nl, fa
  • Niet-Engelse vertalingen worden lazy-loaded in de browser.
  • De geselecteerde locale wordt opgeslagen in browseropslag en hergebruikt bij toekomstige bezoeken.
  • Ontbrekende vertaalsleutels vallen terug op Engels.
Documentatievertalingen worden gegenereerd voor dezelfde set niet-Engelse locales, maar de ingebouwde Mintlify-taalkiezer van de documentatiesite is beperkt tot de localecodes die Mintlify accepteert. Thaise (th) en Perzische (fa) documentatie wordt nog steeds gegenereerd in de publicatierepo; deze verschijnt mogelijk pas in die kiezer wanneer Mintlify die codes ondersteunt.

​
Weergavethema’s

Het paneel Weergave behoudt de ingebouwde thema’s Claw, Knot en Dash, plus één browserlokale tweakcn-importsleuf. Om een thema te importeren, open je tweakcn-thema’s, kies of maak je een thema, klik je op Delen en plak je de gekopieerde themalink in Weergave. De importeur accepteert ook https://tweakcn.com/r/themes/<id>-registry-URL’s, editor-URL’s zoals https://tweakcn.com/editor/theme?theme=amethyst-haze, relatieve /themes/<id>-paden, ruwe thema-ID’s en standaardthemanamen zoals amethyst-haze. Geïmporteerde thema’s worden alleen in het huidige browserprofiel opgeslagen. Ze worden niet naar de Gateway-configuratie geschreven en synchroniseren niet tussen apparaten. Het geïmporteerde thema vervangen werkt de ene lokale sleuf bij; het wissen ervan schakelt het actieve thema terug naar Claw als het geïmporteerde thema geselecteerd was.

​
Wat het kan doen (vandaag)

  • Chat met het model via Gateway WS (chat.history, chat.send, chat.abort, chat.inject).
  • Spreek via realtime browsersessies. OpenAI gebruikt directe WebRTC, Google Live gebruikt een beperkt browser-token voor eenmalig gebruik via WebSocket, en backend-only realtime spraak-plugins gebruiken het relaytransport van de Gateway. De relay houdt providerreferenties op de Gateway terwijl de browser microfoon-PCM streamt via talk.realtime.relay*-RPC’s en openclaw_agent_consult-toolcalls terugstuurt via chat.send voor het grotere geconfigureerde OpenClaw-model.
  • Stream toolcalls + live tooluitvoerkaarten in Chat (agent-events).
  • Kanalen: status van ingebouwde plus gebundelde/externe plugin-kanalen, QR-login en configuratie per kanaal (channels.status, web.login.*, config.patch).
  • Instanties: aanwezigheidslijst + vernieuwen (system-presence).
  • Sessies: lijst + model-/thinking-/fast-/verbose-/trace-/reasoning-overrides per sessie (sessions.list, sessions.patch).
  • Dromen: Dreaming-status, in-/uitschakelaar en Droomdagboek-lezer (doctor.memory.status, doctor.memory.dreamDiary, config.patch).
  • Cron-taken: tonen/toevoegen/bewerken/uitvoeren/inschakelen/uitschakelen + uitvoeringsgeschiedenis (cron.*).
  • Skills: status, inschakelen/uitschakelen, installeren, API-sleutelupdates (skills.*).
  • Nodes: lijst + capaciteiten (node.list).
  • Exec-goedkeuringen: Gateway- of Node-allowlists bewerken + vraagbeleid voor exec host=gateway/node (exec.approvals.*).
  • Bekijk/bewerk ~/.openclaw/openclaw.json (config.get, config.set).
  • Pas toe + herstart met validatie (config.apply) en wek de laatst actieve sessie.
  • Schrijfacties bevatten een base-hash-bescherming om te voorkomen dat gelijktijdige bewerkingen worden overschreven.
  • Schrijfacties (config.set/config.apply/config.patch) voeren vooraf SecretRef-resolutie uit voor actieve refs in de ingediende configuratiepayload; niet-opgeloste actieve ingediende refs worden geweigerd vóór het schrijven.
  • Schema + formulierweergave (config.schema / config.schema.lookup, inclusief veld title / description, overeenkomende UI-hints, samenvattingen van directe kinderen, docs-metadata op geneste object-/wildcard-/array-/compositienodes, plus Plugin- + kanaalschema’s wanneer beschikbaar); Raw JSON-editor is alleen beschikbaar wanneer de snapshot een veilige ruwe round-trip heeft.
  • Als een snapshot niet veilig ruwe tekst heen en terug kan verwerken, dwingt Control UI de formuliermodus af en schakelt Raw-modus uit voor die snapshot.
  • Raw JSON-editor “Terugzetten naar opgeslagen” behoudt de ruw geschreven vorm (opmaak, opmerkingen, $include-layout) in plaats van een afgevlakte snapshot opnieuw te renderen, zodat externe bewerkingen een reset overleven wanneer de snapshot veilig heen en terug kan worden verwerkt.
  • Gestructureerde SecretRef-objectwaarden worden alleen-lezen weergegeven in tekstinvoer van formulieren om onbedoelde corruptie van object naar string te voorkomen.
  • Debug: snapshots van status/gezondheid/modellen + eventlog + handmatige RPC-calls (status, health, models.list).
  • Logs: live tail van Gateway-bestandslogs met filter/export (logs.tail).
  • Update: voer een pakket-/git-update + herstart uit (update.run) met een herstartrapport, en poll daarna update.status na herverbinding om de draaiende Gateway-versie te verifiëren.
  • Voor geïsoleerde taken is levering standaard ingesteld op samenvatting aankondigen. Je kunt overschakelen naar geen als je alleen interne runs wilt.
  • Kanaal-/doelvelden verschijnen wanneer aankondigen is geselecteerd.
  • Webhook-modus gebruikt delivery.mode = "webhook" met delivery.to ingesteld op een geldige HTTP(S)-Webhook-URL.
  • Voor hoofdsessietaken zijn Webhook- en geen-leveringsmodi beschikbaar.
  • Geavanceerde bewerkingsknoppen omvatten verwijderen-na-uitvoering, agent-override wissen, exacte/gespreide Cron-opties, agentmodel-/thinking-overrides en best-effort-leveringsschakelaars.
  • Formuliervalidatie is inline met fouten op veldniveau; ongeldige waarden schakelen de opslagknop uit totdat ze zijn opgelost.
  • Stel cron.webhookToken in om een speciale bearer-token te verzenden; indien weggelaten wordt de Webhook zonder auth-header verzonden.
  • Verouderde fallback: opgeslagen legacy-taken met notify: true kunnen nog steeds cron.webhook gebruiken totdat ze zijn gemigreerd.

​
Chatgedrag

  • chat.send is niet-blokkerend: het bevestigt onmiddellijk met { runId, status: "started" } en de respons streamt via chat-events.
  • Chat-uploads accepteren afbeeldingen plus niet-videobestanden. Afbeeldingen behouden het native afbeeldingspad; andere bestanden worden opgeslagen als beheerde media en in de geschiedenis getoond als bijlagelinks.
  • Opnieuw verzenden met dezelfde idempotencyKey retourneert { status: "in_flight" } terwijl de uitvoering loopt, en { status: "ok" } na voltooiing.
  • chat.history-responsen zijn in omvang begrensd voor UI-veiligheid. Wanneer transcriptitems te groot zijn, kan Gateway lange tekstvelden inkorten, zware metadatablokken weglaten en te grote berichten vervangen door een placeholder ([chat.history omitted: message too large]).
  • Door de assistent/gegenereerde afbeeldingen worden opgeslagen als beheerde mediareferenties en teruggeleverd via geauthenticeerde Gateway-media-URL’s, zodat opnieuw laden niet afhankelijk is van onbewerkte base64-afbeeldingspayloads die in de chatgeschiedenisrespons blijven staan.
  • chat.history verwijdert ook display-only inline richtlijntags uit zichtbare assistenttekst (bijvoorbeeld [[reply_to_*]] en [[audio_as_voice]]), platte-tekst tool-call XML-payloads (waaronder <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> en ingekorte tool-call-blokken), en gelekte ASCII-/full-width modelbesturingstokens, en laat assistentitems weg waarvan de volledige zichtbare tekst alleen het exacte stille token NO_REPLY / no_reply is.
  • Tijdens een actieve verzending en de uiteindelijke geschiedenisverversing houdt de chatweergave lokale optimistische gebruikers-/assistentberichten zichtbaar als chat.history kort een oudere momentopname retourneert; het canonieke transcript vervangt die lokale berichten zodra de Gateway-geschiedenis is bijgewerkt.
  • chat.inject voegt een assistentnotitie toe aan het sessietranscript en zendt een chat-event uit voor alleen-UI-updates (geen agentuitvoering, geen kanaallevering).
  • De model- en denkkeuzes in de chatkop patchen de actieve sessie onmiddellijk via sessions.patch; het zijn permanente sessie-overschrijvingen, geen verzendopties voor slechts één beurt.
  • De chatmodelkiezer vraagt de geconfigureerde modelweergave van de Gateway op. Als agents.defaults.models aanwezig is, stuurt die allowlist de kiezer aan. Anders toont de kiezer expliciete models.providers.*.models-items plus providers met bruikbare authenticatie. De volledige catalogus blijft beschikbaar via de debug-models.list-RPC met view: "all".
  • Wanneer recente gebruiksrapporten van Gateway-sessies hoge contextdruk tonen, laat het chatopstelgebied een contextmelding zien en, bij aanbevolen Compaction-niveaus, een compacte knop die het normale sessie-Compaction-pad uitvoert. Verouderde tokenmomentopnamen worden verborgen totdat de Gateway opnieuw recent gebruik rapporteert.
De praatmodus gebruikt een geregistreerde realtime spraakprovider. Configureer OpenAI met talk.provider: "openai" plus talk.providers.openai.apiKey, of configureer Google met talk.provider: "google" plus talk.providers.google.apiKey; de realtime providerconfiguratie voor Voice Call kan nog steeds als fallback worden hergebruikt. De browser ontvangt nooit een standaard provider-API-sleutel. OpenAI ontvangt een tijdelijke Realtime-clientsecret voor WebRTC. Google Live ontvangt een eenmalig beperkt Live API-authenticatietoken voor een browser-WebSocket-sessie, waarbij instructies en tooldeclaraties door de Gateway in het token zijn vergrendeld. Providers die alleen een backend realtime bridge aanbieden, lopen via het Gateway-relaytransport, zodat referenties en vendor-sockets server-side blijven terwijl browseraudio via geauthenticeerde Gateway-RPC’s beweegt. De Realtime-sessieprompt wordt samengesteld door de Gateway; talk.realtime.session accepteert geen door de aanroeper aangeleverde instructie-overschrijvingen.In de Chat-composer is de Talk-bediening de golfknop naast de microfoondictatieknop. Wanneer Talk start, toont de statusrij van de composer Connecting Talk..., daarna Talk live terwijl audio is verbonden, of Asking OpenClaw... terwijl een realtime tool-call het geconfigureerde grotere model raadpleegt via chat.send.Maintainer live smoke: OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts verifieert de OpenAI browser-WebRTC-SDP-uitwisseling, de Google Live browser-WebSocket-installatie met beperkt token, en de Gateway-relaybrowseradapter met nep-microfoonmedia. De opdracht print alleen providerstatus en logt geen secrets.
  • Klik op Stop (roept chat.abort aan).
  • Terwijl een uitvoering actief is, worden normale vervolgberichten in de wachtrij geplaatst. Klik op Sturen bij een bericht in de wachtrij om dat vervolgbericht in de lopende beurt te injecteren.
  • Typ /stop (of losse afbreekzinnen zoals stop, stop action, stop run, stop openclaw, please stop) om buiten de normale stroom af te breken.
  • chat.abort ondersteunt { sessionKey } (geen runId) om alle actieve uitvoeringen voor die sessie af te breken.
  • Wanneer een uitvoering wordt afgebroken, kan gedeeltelijke assistenttekst nog steeds in de UI worden getoond.
  • Gateway bewaart afgebroken gedeeltelijke assistenttekst in de transcriptgeschiedenis wanneer gebufferde output bestaat.
  • Bewaarde items bevatten afbreekmetadata zodat transcriptconsumenten gedeeltelijke afbreekoutput kunnen onderscheiden van normale voltooiingsoutput.

​
PWA-installatie en webpush

De Control UI levert een manifest.webmanifest en een serviceworker mee, zodat moderne browsers deze als zelfstandige PWA kunnen installeren. Web Push laat de Gateway de geïnstalleerde PWA wekken met meldingen, zelfs wanneer het tabblad of browservenster niet open is.
OppervlakWat het doet
ui/public/manifest.webmanifestPWA-manifest. Browsers bieden “App installeren” aan zodra het bereikbaar is.
ui/public/sw.jsServiceworker die push-events en meldingsklikken afhandelt.
push/vapid-keys.json (onder de OpenClaw-statusmap)Automatisch gegenereerd VAPID-sleutelpaar dat wordt gebruikt om Web Push-payloads te ondertekenen.
push/web-push-subscriptions.jsonOpgeslagen browsersubscriptie-endpoints.
Overschrijf het VAPID-sleutelpaar via omgevingsvariabelen op het Gateway-proces wanneer je sleutels wilt vastzetten (voor multi-host-deployments, secretrotatie of tests):
  • OPENCLAW_VAPID_PUBLIC_KEY
  • OPENCLAW_VAPID_PRIVATE_KEY
  • OPENCLAW_VAPID_SUBJECT (standaard mailto:openclaw@localhost)
De Control UI gebruikt deze scope-gated Gateway-methoden om browsersubscripties te registreren en te testen:
  • push.web.vapidPublicKey — haalt de actieve openbare VAPID-sleutel op.
  • push.web.subscribe — registreert een endpoint plus keys.p256dh/keys.auth.
  • push.web.unsubscribe — verwijdert een geregistreerd endpoint.
  • push.web.test — verzendt een testmelding naar de subscriptie van de aanroeper.
Web Push staat los van het iOS APNS-relaypad (zie Configuratie voor relay-ondersteunde push) en de bestaande push.test-methode, die gericht zijn op native mobiele koppeling.

​
Gehoste embeds

Assistentberichten kunnen gehoste webcontent inline renderen met de [embed ...]-shortcode. Het iframe-sandboxbeleid wordt beheerd door gateway.controlUi.embedSandbox:
Schakelt scriptuitvoering binnen gehoste embeds uit.
Voorbeeld: 
{
  gateway: {
    controlUi: {
      embedSandbox: "scripts",
    },
  },
}
Gebruik trusted alleen wanneer het ingesloten document echt same-origin-gedrag nodig heeft. Voor de meeste door agents gegenereerde games en interactieve canvassen is scripts de veiligere keuze.
Absolute externe http(s)-embed-URL’s blijven standaard geblokkeerd. Als je bewust wilt dat [embed url="https://..."] pagina’s van derden laadt, stel dan gateway.controlUi.allowExternalEmbedUrls: true in.

​
Tailnet-toegang (aanbevolen)

Houd de Gateway op local loopback en laat Tailscale Serve deze met HTTPS proxyen:
openclaw gateway --tailscale serve
Open:
  • https://<magicdns>/ (of je geconfigureerde gateway.controlUi.basePath)
Standaard kunnen Control UI-/WebSocket Serve-verzoeken authenticeren via Tailscale-identiteitsheaders (tailscale-user-login) wanneer gateway.auth.allowTailscale true is. OpenClaw verifieert de identiteit door het x-forwarded-for-adres op te lossen met tailscale whois en dit te matchen met de header, en accepteert deze alleen wanneer het verzoek loopback raakt met Tailscale’s x-forwarded-*-headers. Voor Control UI-operatorsessies met browserapparaatidentiteit slaat dit geverifieerde Serve-pad ook de retourronde voor apparaatkoppeling over; browsers zonder apparaat en node-rolverbindingen volgen nog steeds de normale apparaatcontroles. Stel gateway.auth.allowTailscale: false in als je expliciete shared-secret-referenties wilt vereisen, zelfs voor Serve-verkeer. Gebruik daarna gateway.auth.mode: "token" of "password".Voor dat async Serve-identiteitspad worden mislukte authpogingen voor hetzelfde client-IP en dezelfde authscope geserialiseerd voordat rate-limit-writes plaatsvinden. Gelijktijdige slechte nieuwe pogingen vanaf dezelfde browser kunnen daarom retry later op het tweede verzoek tonen in plaats van twee gewone mismatches die parallel racen.
Tokenloze Serve-authenticatie veronderstelt dat de gatewayhost vertrouwd is. Als niet-vertrouwde lokale code op die host kan draaien, vereis dan token-/wachtwoordauthenticatie.

​
Onveilige HTTP

Als je het dashboard opent via gewone HTTP (http://<lan-ip> of http://<tailscale-ip>), draait de browser in een niet-veilige context en blokkeert WebCrypto. Standaard blokkeert OpenClaw Control UI-verbindingen zonder apparaatidentiteit. Gedocumenteerde uitzonderingen:
  • localhost-only compatibiliteit met onveilige HTTP via gateway.controlUi.allowInsecureAuth=true
  • succesvolle operator-Control UI-authenticatie via gateway.auth.mode: "trusted-proxy"
  • break-glass gateway.controlUi.dangerouslyDisableDeviceAuth=true
Aanbevolen oplossing: gebruik HTTPS (Tailscale Serve) of open de UI lokaal:
  • https://<magicdns>/ (Serve)
  • http://127.0.0.1:18789/ (op de gatewayhost)
{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}
allowInsecureAuth is alleen een lokale compatibiliteitsschakelaar:
  • Hiermee kunnen localhost-Control UI-sessies doorgaan zonder apparaatidentiteit in niet-veilige HTTP-contexten.
  • Dit omzeilt koppelingcontroles niet.
  • Dit versoepelt apparaatidentiteitsvereisten op afstand (niet-localhost) niet.
{
  gateway: {
    controlUi: { dangerouslyDisableDeviceAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}
dangerouslyDisableDeviceAuth schakelt identiteitscontroles voor Control UI-apparaten uit en is een ernstige beveiligingsverlaging. Draai dit snel terug na noodgebruik.
  • Geslaagde authenticatie via vertrouwde proxy kan operator Control UI-sessies toelaten zonder apparaatidentiteit.
  • Dit geldt niet voor Control UI-sessies met node-rol.
  • Reverseproxy’s op dezelfde host via loopback voldoen nog steeds niet aan authenticatie via vertrouwde proxy; zie Authenticatie via vertrouwde proxy.
Zie Tailscale voor richtlijnen voor HTTPS-configuratie.

​
Contentbeveiligingsbeleid

De Control UI wordt geleverd met een strikt img-src-beleid: alleen assets van dezelfde origin, data:-URL’s en lokaal gegenereerde blob:-URL’s zijn toegestaan. Externe http(s)- en protocolrelatieve afbeeldings-URL’s worden door de browser geweigerd en veroorzaken geen netwerkverzoeken. Wat dit in de praktijk betekent:
  • Avatars en afbeeldingen die via relatieve paden worden geleverd (bijvoorbeeld /avatars/<id>) worden nog steeds weergegeven, inclusief geauthenticeerde avatarroutes die de UI ophaalt en omzet in lokale blob:-URL’s.
  • Inline data:image/...-URL’s worden nog steeds weergegeven (handig voor payloads binnen het protocol).
  • Lokale blob:-URL’s die door de Control UI zijn gemaakt, worden nog steeds weergegeven.
  • Externe avatar-URL’s die door kanaalmetadata worden uitgegeven, worden verwijderd door de avatarhelpers van de Control UI en vervangen door het ingebouwde logo/badge, zodat een gecompromitteerd of kwaadwillig kanaal geen willekeurige externe afbeeldingsverzoeken vanuit een operatorbrowser kan afdwingen.
Je hoeft niets te wijzigen om dit gedrag te krijgen — het staat altijd aan en is niet configureerbaar.

​
Authenticatie voor avatarroute

Wanneer Gateway-authenticatie is geconfigureerd, vereist het avatarendpoint van de Control UI hetzelfde Gateway-token als de rest van de API:
  • GET /avatar/<agentId> retourneert de avatarafbeelding alleen aan geauthenticeerde aanroepers. GET /avatar/<agentId>?meta=1 retourneert de avatarmetadata volgens dezelfde regel.
  • Niet-geauthenticeerde verzoeken naar beide routes worden geweigerd (overeenkomstig de naastgelegen assistant-media-route). Dit voorkomt dat de avatarroute agentidentiteit lekt op hosts die anders beschermd zijn.
  • De Control UI zelf stuurt het Gateway-token door als bearer-header bij het ophalen van avatars en gebruikt geauthenticeerde blob-URL’s, zodat de afbeelding nog steeds in dashboards wordt weergegeven.
Als je Gateway-authenticatie uitschakelt (niet aanbevolen op gedeelde hosts), wordt de avatarroute ook niet-geauthenticeerd, in lijn met de rest van de Gateway.

​
De UI bouwen

De Gateway serveert statische bestanden vanuit dist/control-ui. Bouw ze met: 
pnpm ui:build
Optionele absolute basis (wanneer je vaste asset-URL’s wilt): 
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
Voor lokale ontwikkeling (aparte dev-server): 
pnpm ui:dev
Richt de UI vervolgens op je Gateway WS-URL (bijv. ws://127.0.0.1:18789).

​
Debuggen/testen: dev-server + externe Gateway

De Control UI bestaat uit statische bestanden; het WebSocket-doel is configureerbaar en kan verschillen van de HTTP-origin. Dit is handig wanneer je de Vite-dev-server lokaal wilt gebruiken, maar de Gateway elders draait.
1

Start de UI-dev-server

pnpm ui:dev
2

Openen met gatewayUrl

http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
Optionele eenmalige authenticatie (indien nodig):
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
  • gatewayUrl wordt na het laden opgeslagen in localStorage en uit de URL verwijderd.
  • Als je een volledig ws://- of wss://-endpoint via gatewayUrl doorgeeft, URL-codeer dan de gatewayUrl-waarde zodat de browser de querystring correct parseert.
  • token moet waar mogelijk via het URL-fragment (#token=...) worden doorgegeven. Fragmenten worden niet naar de server verzonden, wat lekkage via aanvraaglogs en Referer voorkomt. Verouderde ?token=-queryparameters worden nog steeds één keer geïmporteerd voor compatibiliteit, maar alleen als fallback, en worden direct na bootstrap verwijderd.
  • password wordt alleen in het geheugen bewaard.
  • Wanneer gatewayUrl is ingesteld, valt de UI niet terug op configuratie- of omgevingsreferenties. Geef token (of password) expliciet op. Ontbrekende expliciete referenties zijn een fout.
  • Gebruik wss:// wanneer de Gateway achter TLS staat (Tailscale Serve, HTTPS-proxy, enz.).
  • gatewayUrl wordt alleen geaccepteerd in een venster op topniveau (niet ingesloten) om clickjacking te voorkomen.
  • Niet-loopback Control UI-deployments moeten gateway.controlUi.allowedOrigins expliciet instellen (volledige origins). Dit omvat externe dev-opstellingen.
  • Het opstarten van de Gateway kan lokale origins zoals http://localhost:<port> en http://127.0.0.1:<port> vullen op basis van de effectieve runtime-bind en -poort, maar externe browser-origins hebben nog steeds expliciete vermeldingen nodig.
  • Gebruik gateway.controlUi.allowedOrigins: ["*"] niet, behalve voor strikt gecontroleerde lokale tests. Het betekent dat elke browser-origin is toegestaan, niet “match welke host ik ook gebruik.”
  • gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true schakelt de fallbackmodus voor Host-header-origin in, maar dit is een gevaarlijke beveiligingsmodus.
Voorbeeld: 
{
  gateway: {
    controlUi: {
      allowedOrigins: ["http://localhost:5173"],
    },
  },
}
Details voor externe toegang instellen: Externe toegang.

​
Gerelateerd