OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Tools

Theme

The theme tool lets an agent list, inspect, select, and create OpenClaw appearance themes. Settings and the agent use the same catalog of built-in, plugin, and personal themes. Theme descriptions explain their palette, typography, and character so the agent can choose a theme from a request such as "make this look like an alien spacecraft."

The tool is available in the coding and messaging profiles and group:ui. It does not require a connected browser. Personal changes require a trusted requesting profile; the agent cannot supply another person's profile ID.

Select a theme

Ask the agent to list available themes or choose one for you. list includes the current selection, so selecting a theme usually takes two calls:

json
{ "action": "list" }
json
{ "action": "set", "id": "space-pack/xenovessel", "mode": "dark" }

Use an ID returned by list. Plugin IDs are qualified as <pluginId>/<themeId>; personal themes use user/<slug>.

Actions

Action Inputs Result
list None Available themes, descriptions, supported modes, sources, and the current selection.
get Optional id Current selection and the requested theme, including its editable definition when available. Without id, inspects the current theme.
set id and/or mode Saves profile overrides and returns the resulting selection.
import id, definition; optional apply, mode Saves a personal theme. apply: true selects it in the same call.

mode is system, light, or dark. set accepts null for either id or mode to clear that profile override and inherit the Gateway setting. Setting only one field preserves the other override when it is compatible. Selecting or applying a single-mode theme also selects its supported mode if the previous explicit mode cannot render it. An explicitly requested incompatible mode is rejected; system follows the available palette:

json
{ "action": "set", "id": null, "mode": null }

set and import return application: "saved" after persistence succeeds. The response already includes the resulting state; an extra get is not necessary. Saving does not assert that a particular browser has rendered the theme.

The returned current.mode is the saved preference. current.effectiveMode reports the rendered variant when it can be determined without a browser; with two palettes and system mode, the device determines it. A plugin reload can change available variants without rewriting anyone's saved preferences.

Create and apply a personal theme

import accepts a lowercase slug of up to 64 characters using letters, numbers, hyphens, and underscores. Reimporting the same slug updates that personal theme. apply defaults to false.

A definition requires a name, a short description, and at least one complete light or dark palette. Each palette uses the semantic colors shown below and may include font-sans and font-mono. Use CSS color values such as hex, rgb(), hsl(), or oklch(). Font families describe locally available fonts; definitions cannot load external stylesheets or resources.

This example creates and activates a dark theme in one call:

json
{  "action": "import",  "id": "xenovessel",  "apply": true,  "mode": "dark",  "definition": {    "name": "Xenovessel",    "description": "Indigo spacecraft surfaces, lime controls, cyan highlights, and monospace typography.",    "dark": {      "background": "#090818",      "foreground": "#e8f2ff",      "card": "#12112b",      "card-foreground": "#e8f2ff",      "popover": "#171533",      "popover-foreground": "#e8f2ff",      "primary": "#c7ff3d",      "primary-foreground": "#172300",      "secondary": "#28234a",      "secondary-foreground": "#e8f2ff",      "muted": "#211e39",      "muted-foreground": "#aca6cc",      "accent": "#4ce9ef",      "accent-foreground": "#042b30",      "destructive": "#ff698b",      "destructive-foreground": "#290711",      "border": "#40385e",      "input": "#40385e",      "ring": "#c7ff3d",      "font-sans": "ui-monospace, monospace",      "font-mono": "ui-monospace, monospace"    }  }}

Names are limited to 80 characters, descriptions to 320 characters, and the normalized definition to 4096 UTF-8 bytes. The Gateway validates definitions before saving them. A personal theme does not require installing a plugin or publishing the definition elsewhere.

Plugin themes and hot reload

Plugins contribute theme definitions declaratively through their manifest. The shared catalog updates when the plugin is enabled, disabled, or reloaded; a Gateway restart is not required. The agent continues using the same theme tool rather than receiving a new tool for each plugin.

If a selected plugin theme becomes unavailable, the result includes current.requestedId while current.id identifies the fallback that can be rendered. Re-enable the plugin or choose another theme. Listing the catalog does not execute plugin theme code.

Was this useful?
On this page

On this page