Chat UI plugins
A chat UI plugin ships one browser ES module. After the operator allowlists the plugin, the web client imports the module, calls itsactivate(host), and the plugin mounts its own DOM into
the right-panel slot shared with Canvas and Inbox. A panel registered for the memory slot
enables the Sidebar’s Memory entry (the calendar slot enables Calendar the same way);
other panels list under an Extensions sidebar group. The Add extension entry stays
disabled: installing new plugins from the client is not part of this tier (ADR 0634, amending
ADR 0113).
The contract is deliberately small, like plugin-sdk/control-ui for the operator console, and
the two are not compatible: chat panels are single-slot and scoped to the signed-in end user,
not the operator.
Declare the entry in the manifest
Add an optionalchatUi object to openclaw.plugin.json:
entryfollows thecontrolUirules: a relative.jsor.mjspath in a subdirectory of the plugin root. 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-chat-ui/<plugin-id>/<path>, so put only browser assets there — use a dedicated output directory such asdist/chat-ui/.methodslists the plugin gateway methods the browser side may call. Each name must be non-empty and start with your own plugin id followed by a dot, for examplememory-extension.notes.list. A method without the prefix is rejected at manifest load, so a chat panel can never proxy another plugin’s methods. A method the browser calls but that is not inmethodsfails with “method not exposed to chat UI”.
Allowlist the plugin
Chat UI is opt-in per plugin. The operator lists trusted plugin ids:chatUi.entry but no allow entry contributes
nothing (no sidebar entries, no panels, and its assets answer 404). This allowlist is separate
from gateway.controlUiV2.pluginUi.allow on purpose: letting a plugin run in the operator
console and letting it run for every chat user are different trust decisions.
Install the SDK import
The contract
A plugin module default-exportsdefineChatUiPlugin({ 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. Failures are isolated per plugin: one broken plugin never breaks the web client, and other plugins still load.mount(container, { host, signal })builds DOM inside the given element and returns an optionaldispose(). The host abortssignaland calls the disposer when the panel closes or the connection resets. Ifmountthrows, the host abortssignaland empties the container at once, then shows the failure note. This is framework-free: bundle your own framework inside the module.- Registration inputs are validated: panel
idmatches/^[a-z0-9][a-z0-9._-]{0,63}$/,labelis 1 to 48 characters,slotis one ofmemory,calendar,extension, and panel ids are unique per plugin. Only one panel across all plugins may claim a givenmemoryorcalendarslot: the first registration wins (plugins activate in listed order) and the loser fails with “chat UI slot already registered”.
The host
ChatUiHost (from the same subpath) carries:
There is no
onEvent and no navigation in apiVersion 1: gateway events are not filtered per
user, so a chat panel must re-query through request when it needs fresh data.
Slots and the sidebar
All panels render in the right-panel slot shared with Canvas and Inbox; opening a chat panel
closes Canvas or Inbox and vice versa.
The chatUser handler contract
The browser never reaches your gateway method directly. Everyhost.request goes through the
plugins.chatUi.request dispatcher, which resolves the caller’s device to a person (the same
resolution as identity.self) and injects it into your handler options:
opts.chatUser.person and reject
when it is absent (for example when a gateway admin calls the method directly):
UNAVAILABLE with details.code: "identity_unlinked" before your handler runs — the browser
side sees a rejected request, not your data. Scoping data to chatUser.person is your
responsibility: the gateway injects identity, it does not sandbox your Node side.
Same-origin only
Chat plugin modules load only when the web client is served by the gateway (the gateway’s web client hosting, or a reverse proxy in front of it). The client authenticates to the gateway over its WebSocket connection andimport() cannot attach that authentication, so asset
requests are unauthenticated but confined to allowlisted plugins’ UI directories and carry
Cross-Origin-Resource-Policy: same-origin. When the gateway origin differs from
window.location.origin, the client does not import anything and reports the feature as
cross-origin. Support for cross-origin plugin UI is tracked separately (#1310).
Keeping the entry small
The entry module is fetched after the client connects, before first use of a slot. Keep it small: register panels and lazy-load heavy code (framework runtimes, charts) insidemount.
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 takes effect when the gateway applies the new config, plus a tab reload. The client also resets and re-activates every chat module whenever the gateway connection drops and reconnects, so never rely on module state kept across activations.Troubleshooting
The Memory entry stays disabled. No plugin registered amemory panel: the gateway does not
advertise plugins.chatUi.list (older gateway), no plugin is allowlisted under
gateway.webClient.pluginUi.allow, or the plugin’s activation failed.
request rejects with identity_unlinked. The signed-in device has no linked person. Link
the device identity (the same identity flow the client uses for identity.self), then retry.
Nothing loads and the client says the gateway is cross-origin. The web client is served from
a different origin than the gateway. Serve the client from the gateway origin (or a reverse
proxy in front of it).
The panel shows “This extension failed to load.” The module import failed, the default
export is missing or its id does not match the manifest id, activation threw or timed out, or
mount threw. Check the manifest chatUi.entry path, the allowlist, and that the built module
default-exports defineChatUiPlugin({ id: "<manifest-id>", ... }).
Assets answer 404. The plugin is not in gateway.webClient.pluginUi.allow (default none), or
the request is outside the plugin’s declared UI directory (node_modules, dot-prefixed segments
and paths resolving outside the plugin root are refused).