Hermes WebUI 主题与皮肤定制指南：12 种内置外观 + 3 条路径打造专属界面-创锋一号

Hermes WebUI 主题与皮肤定制指南：12 种内置外观 + 3 条路径打造专属界面

【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui

用 Hermes Agent 的时间越长，界面那点固定的强调色就越容易让你产生"这是模板"的感觉。Hermes WebUI 把外观拆成了主题（浅色 / 深色 / 系统跟随）和皮肤（强调色方案）两条互不干扰的轨道，再配上字体大小调节和一条不改源码的扩展通道，让"换一套顺眼的界面"从改 CSS 的工程活变成了点两下鼠标的事。无论你是想在深夜切到深色护眼、给团队统一一套品牌色，还是想造一个全项目独一份的配色，这篇都能照着做完。

这套外观系统到底能做什么

一张表说清楚 Hermes WebUI 外观能力的边界：

能力	说明	改动的范围
主题（Theme）	`System`/`Dark`/`Light`三档，控制背景、文字、面板底色	整体明暗模式
皮肤（Skin）	内置 12 种：`default`（默认金）、`ares`（红）、`mono`（灰）、`slate`（蓝灰）、`poseidon`（海洋蓝）、`sisyphus`（紫）、`charizard`（橙）、`sienna`（大地色）、`catppuccin`、`nous`（钢蓝）、`geist-contrast`（高对比）、`zeus`（OLED 黑）	仅`--accent`强调色族
字体大小	小 / 默认 / 大 / 超大四档	消息正文、侧边栏、输入框等关键文本
自定义皮肤	纯 CSS 即可，支持扩展注入或修改源码两种方式	强调色变量
自定义主题	重写整套基础色板变量	全局配色（工程量大，一般用不上）
设置持久化	本地`localStorage`+ 服务端`settings.json`（`theme`、`skin`键）	换设备、刷新均保留

主题管"明暗"，皮肤管"点缀"，两者自由组合：比如深色主题 + Ares 红、浅色主题 + Poseidon 蓝。全部是纯 CSS 实现，不涉及任何 Python 后端改动。

任务一：换外观，两分钟搞定

最日常的诉求无非是"换个顺眼的"，有两条路，按需选。

路径 A：设置面板点击切换

点击界面右上角的齿轮图标，进入外观设置区。
在主题卡片里点选"浅色""深色"或"系统"。
在皮肤网格里点你喜欢的色卡。

预览是即时的——点哪张卡，整个界面当场就变色，不用刷新，不用保存。字体大小选项就紧挨在主题/皮肤下方，四档里选一档即可，同样即时生效。

路径 B：斜杠命令一句话切换

在聊天输入框直接输入/theme加名称，主题名和皮肤名共用这一条命令：

/theme dark # 切到深色主题 /theme system # 跟随系统明暗 /theme ares # 切到 Ares 红色皮肤 /theme mono # 切到 Mono 灰色皮肤

规则很简单：命令只动你指定的那一轴。输入皮肤名不会碰主题，输入主题名不会碰皮肤。输错或只敲/theme不带参数时，界面会提示当前支持的全部取值，等于自带帮助文档。

提示：两套设置的最终效果完全一致，区别只是"手点"还是"键盘流"。重度用户基本会习惯命令方式，因为不打断聊天节奏。

任务二：自建配色，不动后端代码

内置 12 种里没有你想要的？皮肤本质就是一小段 CSS 变量覆写，理解两个前提就够了。

先看懂皮肤变量的分工

每种皮肤都要成对定义浅色和深色两个变体，各自覆写一组强调色变量：

变量	作用
`--accent`	主强调色：链接、激活态、主按钮
`--accent-hover`	鼠标悬停时的颜色
`--accent-bg`	浅色强调背景（选中行、标签底色）
`--accent-bg-strong`	更浓的强调背景（小徽章、chip 背后）
`--accent-text`	强调色背景上的文字颜色

最小完整示例（绿色系皮肤，注意成对写两个变体）：

/* 浅色主题下的变体 */ :root[data-skin="my-skin"] { --accent: #2E7D32; --accent-hover: #1B5E20; --accent-bg: rgba(46,125,50,0.08); --accent-bg-strong: rgba(46,125,50,0.15); --accent-text: #1B5E20; } /* 深色主题下的变体，通常调亮或提高饱和度 */ :root.dark[data-skin="my-skin"] { --accent: #66BB6A; --accent-hover: #43A047; --accent-bg: rgba(102,187,106,0.08); --accent-bg-strong: rgba(102,187,106,0.15); --accent-text: #66BB6A; }

注意：漏写深色变体是最常见的翻车点。只写浅色变体的皮肤，一到深色主题下就会退回默认金，看起来像"皮肤没生效"。

应用方式一：扩展注入（推荐，不碰源码）

Hermes WebUI 提供了扩展机制，把自写 CSS 作为外部样式表注入<head>，仓库一个字都不用改。

准备一个扩展目录，把my-skin.css放进去。
启动时通过环境变量声明它：

export HERMES_WEBUI_EXTENSION_DIR=~/.hermes/webui-extension export HERMES_WEBUI_EXTENSION_STYLESHEET_URLS=/extensions/my-skin.css

之后按 docs/EXTENSIONS.md 里的流程启动 WebUI，样式即生效。更完整的方式是调用window.registerHermesSkin(descriptor)把皮肤正式注册进去——注册后它会出现在设置 → 外观的原生皮肤网格里，和内置皮肤享有同等待遇；还可以用scheme声明"仅限浅色"或"仅限深色"的皮肤，避免两种基础模式下的变量互相串味。

提示：skin设置在服务端接受任意字符串，所以你的自定义皮肤名在 CSS 加载后能直接持久化，不需要任何代码适配。

应用方式二：修改源码（想贡献给上游才用）

适合打算把皮肤做成内置选项的用户，三处都要动，缺一不可：

把两段:root[data-skin="..."]变体追加到 static/style.css 的现有皮肤区块里；
在 static/index.html 的设置皮肤选择器中注册；
在 static/commands.js 的cmdTheme()皮肤列表中加入名字，否则/theme命令不认识它。

顺手的进阶项：换字体

如果不满意的不是颜色而是"字太小/太大"，外观区下方的字体大小就是全部解法：小（12px 基准）、默认（14px）、大（16px）、超大（18px）。它以data-font-size属性挂在<html>上，同步作用于消息正文、侧边栏会话列表、输入框和文件树，跟主题、皮肤一并持久化。

想要更彻底的改造（比如整体换一套色板情绪），那是自定义主题的活：要重定义--bg、--surface、--text、--border、--code-bg等基础变量，契约定义在 static/style.css 顶部的:root与:root.dark块。变量多、牵动的选择器也多，除非确有高对比无障碍或 OLED 纯黑这类刚需，优先做皮肤。

效果不满意时，按这个顺序排查

大多数"皮肤不对劲"都能在三步内定位：

先切主题验证。浅色下好看、深色下糊掉（或反之），九成是漏写了某一侧变体。把:root[data-skin]和:root.dark[data-skin]两个选择器都过一遍。
查对比度重点位。最容易被忽略的是--accent-text叠在--accent-bg-strong上的小标签和徽章——对比度不够时表现为"发灰发糊"。建议按 WCAG 2.1 AA 的对比度标准校验，浅色深色各测一轮。
确认设置真的落地了。主题、皮肤、字号都走双通道持久化：浏览器localStorage负责加载时零闪烁（<head>里的内联脚本在样式表之前就读好），POST /api/settings负责把theme、skin写进服务端settings.json，启动时再经GET /api/settings回灌。如果刷新后设置丢了，多半是这一侧断链，而不是 CSS 没生效。

另有两条省心的事实，做皮肤前知道可以少走弯路：logo 渐变直接引用--accent，换皮肤后它自动跟着变，无需单独处理；扩展注册皮肤时若声明了scheme，WebUI 会自动替你选对基础明暗类，不会出现"深色皮肤 + 浅色表格令牌"的混搭。

动手清单与延伸阅读

现在就打开设置面板，挑一张内置皮肤点击试试即时预览的效果；想要专属配色，把上面 15 行 CSS 抄下来改成你的主色，走扩展注入这条路，全程不碰源码。

资源	位置
主题与皮肤完整文档	THEMES.md
扩展机制说明（样式注入、皮肤注册）	docs/EXTENSIONS.md
全部皮肤与主题的 CSS 定义	static/style.css
外观设置界面实现	static/index.html
`/theme`命令实现	static/commands.js

需要克隆仓库体验的话，使用：git clone https://gitcode.com/GitHub_Trending/he/hermes-webui

【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析