Control UI plugins
A Control UI v2 plugin ships one browser ES module. After the operator allows the plugin, the console imports the module, calls itsactivate(host), and the plugin mounts its own DOM into
host-owned slots: pages in a Plugins sidebar group, panels in the Session inspector, and
panels in the Run inspector. The contract is a strict subset of upstream OpenClaw
plugin-sdk/control-ui apiVersion 1 plus one field (ControlUiPanel.placement); it is not
drop-in compatible with upstream plugins (ADR 0113).
Everything below applies to Control UI v2 (the operator console). The web client loads plugin UI
through a separate, parallel tier: see Chat UI plugins.
Declare the entry in the manifest
Add an optionalcontrolUi object to openclaw.plugin.json:
entryis a relative.jsor.mjspath in a subdirectory of the plugin root, for exampledist/control-ui/index.js. Root-level entries, absolute paths,..segments, intermediate.segments, and.tssources are rejected when the manifest loads.- The gateway serves the entry’s directory and everything under it at
/__openclaw__/plugin-ui/<plugin-id>/<path>on the gateway origin, without authentication. Put only browser assets there: use a dedicated output directory such asdist/control-ui/, never a directory that also holds server code. Paths throughnode_modulesor dot-prefixed segments, files resolving outside the plugin root (symlinks included), and extensions other than.js,.mjs,.css,.svg,.png,.jpg,.jpeg,.webp,.woffand.woff2answer 404. No plugin HTTP route can shadow the reserved prefix.
Install the SDK import
The browser contract is a dedicated subpath, so the gateway side and the browser side share the types without pulling in Node-only SDK code:openclaw/plugin-sdk/control-ui is the legacy alias for the same subpath.)
The contract
A plugin module default-exportsdefineControlUiPlugin({ id, activate }):
idmust equal the plugin manifest id; activation fails otherwise.activate(host)may be async and may return a disposer. It must finish within 10 seconds; a slower activation is aborted and reported as a failure. All failures are isolated: one broken plugin never breaks the console, and the reason is listed in the console Debug view.mount(container, { host, signal, props })builds DOM inside the given element and returns an optionaldispose(). The host remounts the view when props change and never calls an update hook;signalis aborted when the host unmounts the view. This is deliberately framework-free: bundle your own framework (React, Vue, Lit) inside the module. Native look comes from the brand tokens, not from host internals.- Registration inputs are validated: page and panel
idmatch/^[a-z0-9][a-z0-9._-]{0,63}$/,labelis 1 to 48 characters after trim, and a duplicate id is rejected — page ids are unique per plugin, panel ids are unique per(plugin, placement), so the same panel id may be used once for asessionpanel and once for arunpanel.
The host
ControlUiHost (from the same subpath) carries:
Placements and props
Pages render as their own route (
?plugin=<id>&page=<pageId> plus your params) under the
Plugins sidebar group and the command palette. Session panels render inside the Session
inspector; run panels render at the end of the Run inspector after the timeline.
The operator allowlist
Plugin UI is opt-in per plugin. The operator lists trusted plugin ids:controlUi.entry but no allow entry contributes
nothing (no nav entries, no panels, and its UI assets answer 404). The allowlist gate re-reads
when gateway config changes; see
Configuration reference under gateway.controlUiV2.pluginUi.allow.
Trust model: plugin browser code runs with the signed-in operator’s console authority, the same
trust class as the plugin’s in-process gateway code. Only allow plugins you trust.
Same-origin only
Plugin modules load only when the console is served by the gateway (gateway.controlUiV2 or a
reverse proxy in front of it). The console authenticates to the gateway over its WebSocket
connection, and import() cannot attach that authentication, so asset requests are
unauthenticated, which is acceptable because they are as public as the console bundle itself and
limited to allowlisted plugins’ UI directories; the responses carry
Cross-Origin-Resource-Policy: same-origin. On a cross-origin console (standalone server or CDN,
different origin from the gateway) plugin UI does not load at all; the console reports the gateway
origin it would need. Support for cross-origin plugin UI is tracked separately.
Styling
Style your DOM with the documented brand-token CSS custom properties, which the console defines globally:--bg, --card, --border, --text, --muted, --accent, --ok, --warn,
--danger, and the --radius-* radii. They flip automatically with the light and dark themes.
The console’s internal ct- class names are not a contract. Do not depend on them; a console
update may rename them at any time.
Keep the entry small
The entry module is fetched after the console connects, before first use of any slot, but it blocks your first panel render. Keep it small: register pages, panels and listeners, and lazy-load heavy code (framework runtimes, charts) insidemount with a dynamic import() of
your own module chunks.
Bundle your own framework. For React, build the entry as a library with Vite:
ui/index.js). Import defineControlUiPlugin as a value
(it is a one-line identity helper, so bundling it costs nothing) and the contract types with
import type.
Fetch data through your own methods
Do not reach around the gateway. Register your own gateway methods from the plugin’s Node side and call them from the browser side withhost.request:
operator.admin; see the
scope note above.
Updating a plugin
The browser caches loaded plugin modules. After you change or redeploy a plugin’s UI, reload the browser tab; there is no live hot-reload. Changing the allowlist config takes effect when the gateway applies the new config, plus a tab reload. The console also resets and re-activates plugin modules whenever the gateway connection drops and reconnects (not only on sign-out): the activation disposer runs,host.signal aborts, and
activate runs again on a fresh host. Register all pages, panels and event listeners from
activate (or in response to its signal), and never rely on module state kept across
activations.
Troubleshooting
The Plugins group is missing. The gateway does not advertiseplugins.controlUi.list (older
gateway), no plugin is allowlisted under gateway.controlUiV2.pluginUi.allow, or the console is
not served by the gateway origin.
The plugin page shows “This plugin page is not available.” Activation failed or the page id
is wrong. Open Debug and check the plugin UI status panel: it lists each plugin as loaded or
with its failure message (import error, missing or mismatched default export, activation throw,
or activation timeout).
A panel is blank. The mount call may have thrown after registering; the console replaces a
throwing mount with an error state, but an async failure after the first paint is your plugin’s
error handling to surface. Wrap mount work in try/catch and render the error into the container.