本页内容
本页内容
工具
主题
theme 工具可让代理列出、检查、选择和创建 OpenClaw 外观主题。设置和代理使用相同的内置、插件和个人主题目录。主题描述解释了它们的调色板、排版和特征，以便代理可以从请求中选择主题，例如“使其看起来像外星飞船”
主题品牌是装饰性的，适用于 Control UI，而不是 CLI 或本机应用程序。它不会重写技术命令文本、包路径、身份验证协议或法律和版权声明。在加载个人资料和主题目录之前，匿名冷登录无法使用经过身份验证的人员的主题；在此之前，只有现有的本地记住的吉祥物后备可用。这些字段不添加网关配置选项或配置迁移。
该工具可在编码和消息传递配置文件以及 group:ui 中使用。它不需要连接的浏览器。个人变更需要可信的参与者资料。
CRT和Phosphor使用中性端子标记、点工作指示器，并且没有Lobsterdex。它们保留 OpenClaw 名称和帮助链接。其他内置主题，包括 Claw，保留了现有的吉祥物和品牌。隐藏 Lobsterdex 不会删除浏览器的集合或保存的图标首选项。
选择主题
请代理列出可用的主题或为您选择一个。 list 包括当前选择，因此选择主题通常需要两次调用：
使用 list 返回的 ID。插件 ID 为 <pluginId>/<themeId>；个人主题使用user/<slug>。
操作
| 操作 | 输入 | 结果 |
|---|---|---|
list |
无 | 可用的主题、描述、支持的模式、来源和当前选择。 |
get |
可选id |
当前选择和请求的主题，包括其可编辑定义（如果可用）。如果没有 id，则检查当前主题。 |
set |
id and/or mode |
保存配置文件覆盖并返回结果选择。 |
import |
id、definition；可选 apply、mode |
保存个人主题。 apply: true 在同一调用中选择它。 |
每个操作都接受可选的 user，即来自 Control UI 消息对话上下文的人员验证的 requester_profile.id。当多人转向时，需要user；智能体选择询问的人或不清楚的情况询问他们。只能选择回合的所有者或接受的参与者。读取，包括list和get中的当前选择，使用该人的个人资料；更改仅保存到该配置文件。如果他们的访问权限发生了变化，他们必须再次询问。
mode 是 system、light 或 dark。 set 接受 id 或 mode 的 null，以清除该配置文件覆盖并继承网关设置。仅设置一个字段会在兼容时保留其他覆盖。如果先前的显式模式无法呈现它，则选择或应用单模式主题也会选择其支持的模式。明确请求的不兼容模式被拒绝； system 遵循可用调色板：
set和import持久化成功后返回application: "saved"。响应已经包含结果状态；不需要额外的 get。保存并不断言特定浏览器已呈现主题。
返回的current.mode是保存的首选项。 current.effectiveMode 在无需浏览器即可确定时报告呈现的变体；有两个调色板和 system 模式，由设备决定。插件重新加载可以更改可用的变体，而无需重写任何人保存的首选项。
创建并应用个人主题
import 接受最多 64 个字符的小写段，使用字母、数字、连字符和下划线。重新导入相同的 slug 会更新该个人主题。 apply 默认为 false。
定义需要名称、简短描述和至少一个完整的 light 或 dark 调色板。每个调色板使用如下所示的语义颜色，并且可能包括 font-sans 和 font-mono。使用 CSS 颜色值，例如十六进制、rgb()、hsl() 或 oklch()。字体系列描述本地可用的字体；定义无法加载外部样式表或资源。
定义还可以提供这些可选的表示字段，由内置、插件和个人主题共享：
mascot："claw"（默认）或"none"。"none"默认为中性提示标记，并隐藏常驻龙虾和来访龙虾陌生人。当 Lobster 访问启用时，普通生物仍然可以跨越作曲家壁架；主题不会改变该切换。brandName：1-80 个可打印字符的显示名称，在保存前进行修剪。省略它以保留“OpenClaw”。这是外观文本，而不是对代理身份或产品配置的更改。brandIcon："claw"或中性"mark"。省略如下mascot：爪为"claw"，标记为"none"。插件主题还可以选择声明的图标艺术品 ID。workingIndicator："claw"、"dots"、"brand"（所选品牌图标）或"none"。省略使用爪作为爪吉祥物，点作为没有吉祥物。此选择与长期等待短语无关。lobsterdex和communityLinks：控制各自导航条目的布尔值。两者都默认为true，独立于mascot。隐藏条目不会删除发现或更改访问权限。workingPhrases：最多 24 个文字状态短语，每个被修剪为 1-24 个字符，修剪后没有控制字符或重复。这些创作的字符串不会被翻译。省略该字段以使用默认的异想天开的词汇，或将其设置为[]以隐藏长时间等待的短语。critters：内置"penguin"和"fedora"目录中最多 8 个唯一 ID。当启用 Lobster 访问时，这些会将偶尔的访问者添加到普通作曲家壁架流量中。省略该字段或使用[]不添加；未知 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"。在保存主题之前，格式错误的颜色和不平衡的字体引号将被拒绝。
此示例在一次调用中创建并激活深色主题：
名称限制为 80 个字符，描述限制为 320 个字符，规范化定义限制为 4096 UTF-8 字节。网关在保存定义之前验证定义。个人主题不需要安装插件或在其他地方发布定义。
插件主题和热重载
插件通过其清单以声明方式贡献主题定义。个人主题仅使用内置品牌图标、帽子和小动物目录 ID；插件主题还可以引用在 插件清单 中声明的自己的 SVG 艺术品 ID，并且它们的清单可以声明浅色和深色画布背景。定义从不包含图稿标记或外部 URL。当插件启用、禁用或重新加载时，共享目录会更新；不需要重新启动网关。代理继续使用相同的 theme 工具，而不是为每个插件接收新工具。
如果选定的插件主题不可用，结果将包括 current.requestedId，而 current.id 标识可以呈现的后备。重新启用插件或选择其他主题。列出目录不执行插件主题代码。