主题

theme 工具允许智能体列出、检查、选择和创建 OpenClaw 外观主题。设置界面和智能体使用同一个内置、插件和个人主题目录。主题描述说明了它们的调色板、排版和风格特征，以便智能体能够根据诸如“让它看起来像一艘外星飞船”这样的请求来选择主题。

该工具在编码（coding）和消息（messaging）配置文件中可用，也可在 group:ui 中使用。它不需要连接浏览器。个人更改需要受信任的参与者配置文件。

选择主题¶

让智能体列出可用主题或为你选择一个主题。list 会包含当前选择，因此选择主题通常需要两次调用：

{ "action": "list" }

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

使用 list 返回的 ID。插件 ID 限定为 <pluginId>/<themeId>；个人主题使用 user/<slug>。

操作¶

每个操作都接受可选的 user，即来自 Control UI 消息会话上下文中已验证的 requester_profile.id。当多个人主导了本轮对话时，必须提供 user；智能体会选择提出请求的人，如果不清楚则会询问他们。只能选择本轮对话的所有者或被接受的参与者。读取操作（包括 list 和 get 中的当前选择）使用该人的配置文件；更改仅保存到该配置文件。如果他们的访问权限已更改，则必须重新请求。

mode 只能是 system、light 或 dark。set 接受 id 或 mode 为 null，以清除该配置文件覆盖项并继承 Gateway 设置。仅设置一个字段会在兼容时保留另一个覆盖项。选择或应用单模式主题时，如果之前的显式模式无法渲染该主题，也会选择其支持的模式。明确请求的不兼容模式将被拒绝；system 遵循可用的调色板：

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

set 和 import 在持久化成功后返回 application: "saved"。响应已包含结果状态，无需再额外调用 get。保存操作并不断言某个浏览器已渲染该主题。

返回的 current.mode 是已保存的偏好。current.effectiveMode 在无需浏览器即可确定时报告渲染的变体；当存在两种调色板且处于 system 模式时，由设备决定。插件重载可以更改可用的变体，而无需重写任何人已保存的偏好。

创建并应用个人主题¶

import 接受最长 64 个字符的小写 slug，可使用字母、数字、连字符和下划线。重新导入相同的 slug 会更新该个人主题。apply 默认为 false。

一个定义需要名称、简短描述以及至少一个完整的 light 或 dark 调色板。每个调色板使用下面所示的语义化颜色，并且可以包含 font-sans 和 font-mono。使用 CSS 颜色值，如 hex、rgb()、hsl() 或 oklch()。字体族描述本地可用的字体；定义不能加载外部样式表或资源。

定义还可以提供以下可选的展示字段，这些字段由内置主题、插件主题和个人主题共享：

• mascot："claw"（默认值）或 "none"。"none" 会用中立的提示标记替换龙虾品牌形象，并隐藏常驻龙虾和到访的陌生龙虾。当启用 Lobster visits 时，普通小动物仍然可以穿过撰写器横栏；主题不会改变该开关。
• workingPhrases：最多 24 个字面状态短语，每个短语修剪后为 1–24 个字符，无控制字符或修剪后的重复项。这些作者定义的字符串不会被翻译。省略该字段可使用默认的俏皮词汇，或将其设置为 [] 以隐藏长时间等待的短语。
• critters：来自内置 "penguin" 和 "fedora" 目录的最多 8 个唯一 ID。在启用 Lobster visits 时，这些会为普通撰写器横栏的日常活动增添偶尔的访客。省略该字段或使用 [] 则不会添加；未知 ID 和重复项会被拒绝。
• avatarHat："fedora"、"crown"、"santa"、"party" 或 "pumpkin" 会为智能体头像偶尔添加装饰性帽子。省略该字段则不提供主题自带的头像帽子。

使用一致的 CSS 分隔符：rgb(20 30 40 / 50%) 或 rgba(20, 30, 40, 0.5)。诸如 oklch() 之类的现代函数在组件之间使用空格，并在透明度前使用 /。字体列表使用逗号分隔的字族名称；对包含标点或以数字开头的名称加引号，例如 "123 Font", monospace。对包含 CSS 关键字的名称也加引号，例如 "Foo serif"。格式错误的颜色和不配对的字体引号会在主题保存前被拒绝。

以下示例在一次调用中创建并激活了一个深色主题：

{
  "action": "import",
  "id": "xenovessel",
  "apply": true,
  "mode": "dark",
  "definition": {
    "name": "Xenovessel",
    "description": "Indigo spacecraft surfaces, lime controls, cyan highlights, and monospace typography.",
    "mascot": "none",
    "workingPhrases": ["Navigating", "Calibrating", "Scanning"],
    "critters": ["penguin", "fedora"],
    "avatarHat": "fedora",
    "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"
    }
  }
}

名称限制为 80 个字符，描述限制为 320 个字符，规范化定义限制为 4096 个 UTF-8 字节。Gateway 在保存前会验证定义。个人主题无需安装插件或将定义发布到其他位置。

插件主题与热重载¶

插件通过其清单以声明方式提供主题定义。个人主题仅使用内置的 hat 和 critter 目录 ID；插件主题还可以引用其在插件清单中声明的自有 SVG 美术资源 ID。定义从不包含美术资源标记或外部 URL。 当插件被启用、禁用或重新加载时，共享目录会更新；无需重启 Gateway。代理会继续使用相同的 theme 工具，而不是为每个插件接收一个新工具。

如果所选的插件主题不可用，结果将包含 current.requestedId，而 current.id 标识可渲染的回退主题。重新启用插件或选择其他主题。列出目录不会执行插件主题代码。

相关¶

• 插件主题声明
• 管理插件
• 控制 UI
• 屏幕工具