1. Hermes 本地部署后为什么需要一个可视化运维入口Hermes Agent 跑起来之后很多人第一反应是把它接到微信、飞书或者企微里发一条消息等回复用起来确实顺手。但用了一段时间你会发现一个问题你只能看到输入和输出中间发生了什么完全是个黑盒。某次回复突然变慢你没法判断是模型接口延迟、网络抖动、工具调用卡住还是 Hermes 服务本身出了问题。想换个模型、检查一下 API 配置、看看频道状态、翻一下运行日志都得重新连回设备、翻配置文件、敲命令。对于已经长期运行、还接了多个消息平台的 Hermes 来说纯靠终端管理会越来越别扭。hermes-web-ui 就是补这一块的。它不替代 Hermes Agent而是给后台运行的 Hermes 加一个浏览器控制台把对话、模型、频道、任务、插件、记忆和日志集中展示出来。你可以把它理解成给 Hermes 装了一个仪表盘Agent 还在后台干活但你现在能看见它在干什么、干得怎么样。这篇文章面向的是已经把 Hermes 本地部署起来、但缺少可视化运维入口的开发者。我会从 hermes-web-ui 的 npm 安装与启动配置讲起然后给出 cpolar 内网穿透映射步骤最后逐个面板做验证动作帮你快速搭起一个可远程访问的 Hermes 管理界面。整个过程不需要你改 Hermes 的核心代码也不需要动现有的消息平台接入配置。先说清楚适用场景如果你只是偶尔跑一下 Hermes 做测试终端其实够用但如果你已经把 Hermes 接入微信、飞书、企微并且让它长期在线处理任务那 WebUI 带来的可见性和可管理性提升会非常明显。尤其是当你想排查“为什么这条消息回复这么慢”或者“这个定时任务到底跑没跑”的时候一个能直接打开的控制台比翻日志文件高效得多。我试过在只靠终端的情况下排查一次响应变慢的问题来回切窗口、翻配置、猜原因花了快二十分钟才定位到是某个模型端点的超时设置不合理。有了 WebUI 之后这类问题基本可以在一个页面里看完对话记录、模型配置和日志定位速度快很多。这也是我决定把 hermes-web-ui 的搭建过程完整写下来的原因——它解决的不是“能不能用”的问题而是“好不好管”的问题。2. TaoToken 前置准备模型接入与 API Key 配置在开始装 hermes-web-ui 之前有一个前置环节需要先处理好Hermes 背后的模型接入。因为 WebUI 的模型面板会直接读取 Hermes 当前的模型配置如果模型本身没接好WebUI 里看到的也是一堆报错。这里我推荐用 TaoToken 作为模型接入层它提供统一的 API 入口配置起来比较直接后面在 WebUI 里切换和查看模型也会更清晰。TaoToken 的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。你需要先注册账号然后在控制台里创建一个 API Key。这个 Key 就是后面 Hermes 调用模型时用的凭据也是 WebUI 模型面板里会显示的那条配置。具体操作路径是这样的打开官网后进入控制台找到 API Keys 页面点创建新的 Key。创建的时候建议给 Key 起一个能辨识的名字比如 hermes-local 或者 hermes-webui-test这样以后在 WebUI 里看到多条 Key 的时候不会搞混。创建完成后把 Key 复制出来注意这个 Key 只显示一次丢了就得重新建。拿到 Key 之后你需要把它配置到 Hermes 的模型设置里。Hermes 的模型配置通常在一个 JSON 或 TOML 文件里具体路径取决于你的部署方式。如果你是用 Hermes 的交互式配置可以直接在对话里让它帮你写入如果是手动改配置文件找到模型提供商那一节把 Base URL 填成 https://taotoken.net/api 把 API Key 填成你刚创建的那串Model ID 填你要用的模型名称。这里要强调一下三件套的完整性Base URL、API Key、Model ID 缺一不可。很多人配置失败就是因为只填了 Key 没改 Base URL或者 Model ID 写错了。WebUI 的模型面板会把这几个字段都展示出来所以配好之后你可以在 WebUI 里直接核对不用再去翻配置文件。如果你后面打算长期用 Hermes 做编码或者 Agent 类任务可以考虑 TaoToken 的 Coding Plan它在调用额度和稳定性上更适合持续运行场景。入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。不过这一步不是必须的先用按量计费的 API Key 把 WebUI 跑通也完全没问题。配置好模型之后建议先在终端里让 Hermes 做一次简单的对话测试确认模型能正常返回。这一步很关键因为如果模型本身不通后面 WebUI 里看到的对话面板也会是空的或者报错你会分不清是 WebUI 的问题还是模型的问题。测试通过之后再进入下一步安装 hermes-web-ui。3. hermes-web-ui 的 npm 安装与启动配置这一节是核心操作部分我会给出两种安装方式让 Hermes 自己装以及手动用 npm 装。两种方式最终效果一样你可以根据自己的习惯选。不管选哪种装完之后 hermes-web-ui 默认跑在 8648 端口登录需要一个 Token这个 Token 相当于密码后面会讲怎么改。先说推荐方式让 Hermes Agent 自己安装。既然你已经有了 Hermes最省事的做法就是直接把安装任务交给它。你可以把下面这段提示词发给 Hermes不管是在终端对话模式还是已经接入的飞书、微信里都可以请帮我在当前设备上安装 hermes-web-ui。先检查 Node.js 和 npm 是否可用如果环境正常就使用 npm 全局安装 hermes-web-ui。安装完成后启动 hermes-web-ui并告诉我本地和局域网访问地址还有登录的密码是什么并且告诉我如何修改密码。如果端口被占用请先提示我不要删除任何文件。发送之后Hermes 会先检查 Node.js 和 npm 环境然后执行全局安装、启动服务最后把本地地址、局域网地址和登录 Token 一起返回给你。输出大概长这样本地http://localhost:8648 局域网http://192.168.50.161:8648 登录 Tokend7f898d566ecbc437e4b9fe89bcaf1bf515b656834a3996304111716bcc7ba3d拿到局域网地址后在同一网络下的浏览器里打开输入 Token 就能进入控制台。这种方式适合已经跑通 Hermes 的用户不需要自己一步步敲命令。如果你不想让 Hermes 自动装或者想更清楚地控制每一步那就手动来。手动方式的思路很简单确认环境、安装、启动。先检查 Node.js 和 npmnode -v npm -vhermes-web-ui 对 Node.js 版本有要求建议用 Node.js 23 或更高。如果版本太低先升级再继续。然后全局安装npm install -g hermes-web-ui安装完成后启动hermes-web-ui start启动成功后终端会输出访问地址和登录 Token。如果你想修改密码也就是改 Token可以这样操作echo 你的新密码 ~/.hermes-web-ui/.token hermes-web-ui restart改完之后重启服务新 Token 就生效了。默认访问地址是 http://localhost:8648 局域网内其他设备用终端输出的局域网地址访问即可。这里给一个配置对照表方便你核对关键参数配置项值说明默认端口8648WebUI 监听端口本地地址http://localhost:8648本机访问局域网地址http://你的内网IP:8648同网络设备访问Token 文件~/.hermes-web-ui/.token登录凭据存储位置Node.js 要求 23低于此版本可能启动失败如果你在启动时遇到端口被占用可以先查一下 8648 被谁占了lsof -i :8648确认之后要么停掉占用进程要么给 hermes-web-ui 换一个端口启动。换端口的具体参数可以看 hermes-web-ui 的帮助输出。装好并成功进入控制台之后就可以开始验证各个面板了。4. 验证请求与成功结果对话、模型、任务、日志面板逐个测装好之后不要急着配 cpolar先在本地把各个面板验证一遍确认 WebUI 和 Hermes 之间的数据是通的。这一步能帮你提前发现模型配置或服务状态的问题避免远程访问时才发现打不开。第一个要验证的是对话面板。进入 WebUI 后找到对话入口发一条简单的测试消息比如“现在几点了”或者“帮我算一下 23 乘以 17”。正常情况下你会看到消息发出去之后页面上出现一个正在思考的动效然后返回结果。这个过程比在微信里等回复直观的地方在于你能看到请求从发出到返回的完整状态。如果这里一直转圈没有结果大概率是模型配置有问题回到上一节检查 Base URL、API Key 和 Model ID 三件套。第二个验证模型面板。进入模型页面你应该能看到当前已经添加的模型提供商列表包括 Base URL、Model ID 这些字段。核对一下这里的 Base URL 是不是 https://taotoken.net/api Model ID 是不是你实际在用的那个。如果这里显示为空或者报错说明 Hermes 的模型配置没有被正确读取需要回到配置文件检查。模型面板的价值在于以后切换模型、检查接口地址、调整默认模型都可以在这里直接看不用翻配置文件。第三个验证任务面板。这是我觉得最实用的一个面板。你可以创建一个最简单的定时任务来测试比如让 Hermes 每天早上 8 点推送当天天气。在左侧边栏进入任务面板点击创建任务按提示填写任务名称、执行时间、执行内容。创建完成后先点任务卡片上的“立即运行”按钮手动触发一次。稍等片刻你应该能在微信端收到一条天气提醒同时在任务面板的运行历史里看到这次执行记录。如果立即运行没有反应检查一下任务内容里调用的工具或模型是否可用。第四个验证日志面板。进入日志页面你应该能看到 Hermes 运行过程中的各类日志输出。这里可以配合前面的对话测试一起看发一条消息然后回到日志面板刷新看看有没有对应的请求记录。日志面板在排查“为什么回复慢”这类问题时特别有用你可以看到请求是在模型调用阶段耗时还是在工具调用阶段卡住。为了让你更清楚每个面板验证什么这里做一个对照面板验证动作成功标志失败时检查对话发一条测试消息收到模型回复模型三件套配置模型查看提供商列表显示 Base URL 和 Model IDHermes 模型配置文件任务创建并立即运行收到推送 运行历史有记录任务内容和工具可用性日志发消息后刷新日志出现对应请求记录Hermes 服务运行状态四个面板都验证通过之后说明 WebUI 和 Hermes 的对接是完整的。这时候再去做 cpolar 内网穿透远程访问时看到的才是一个真正可用的控制台而不是一个空壳页面。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth这一节把搭建过程中最容易遇到的几类报错集中讲一下都是真实会碰到的对照着排查能省不少时间。第一类是 401 未授权。这个通常出现在两个地方一是 WebUI 登录时 Token 输错二是 Hermes 调用模型时 API Key 无效。如果是 WebUI 登录报 401检查你输入的 Token 是否和终端输出的一致注意不要多复制空格。如果是模型调用报 401检查 TaoToken 的 API Key 是否复制完整、是否已经过期或被删除。可以在 TaoToken 控制台的 API Keys 页面确认 Key 状态必要时重新创建一个。第二类是 local proxy failed。这个报错一般和网络请求转发有关常见原因是 Base URL 配置不对或者本地网络无法访问目标地址。先确认 Base URL 是不是 https://taotoken.net/api 注意不要多加路径或者少写。然后确认你的设备能正常访问外网。如果是在公司内网或者有特殊网络策略的环境可能需要检查出口规则。这个报错在 WebUI 的日志面板里通常能看到更详细的上下文建议结合日志一起看。第三类是 reading choices 相关报错。这类报错一般出现在模型返回格式不符合预期的时候比如返回体里没有 choices 字段或者返回的是错误信息而不是正常响应。常见原因是 Model ID 填错了或者调用的模型不支持当前请求格式。解决办法是回到模型面板核对 Model ID确认它和 TaoToken 支持的模型名称一致。如果用的是兼容接口注意有些模型对请求参数有特殊要求。第四类是 OAuth 相关报错。如果你在配置某些频道或者插件时用到 OAuth 授权可能会遇到回调失败或者 token 过期的问题。这类问题通常和回调地址配置、授权范围有关。建议先确认你在对应平台配置的回调地址和实际访问地址一致然后重新走一遍授权流程。如果是在 cpolar 映射之后配置 OAuth注意公网地址变化可能导致回调地址失效这也是后面建议配置固定二级子域名的原因之一。为了更高效地排查建议养成一个习惯遇到报错先看 WebUI 的日志面板再去核对模型三件套配置最后检查网络和端口。大部分问题都出在这三个环节。如果日志面板本身打不开那说明 Hermes 服务可能没正常运行先在终端确认 hermes-web-ui 进程状态。另外提醒一点WebUI 的 Token 和模型 API Key 都是敏感信息不要截图发到公开群组也不要用过于简单的内容当密码。公网地址同样不要随意分享尤其是在还没配置访问控制的情况下。6. 用 cpolar 映射 8648 端口并配置固定域名远程访问本地验证通过之后接下来解决远程访问的问题。hermes-web-ui 默认只在本地和局域网可访问出门在外用手机流量或者在公司网络下就打不开了。cpolar 可以把本地的 8648 端口映射成一个公网地址让你在外面也能打开这个控制台。先安装 cpolar。以 macOS 为例用 Homebrew 安装最方便。先确认 Homebrew 可用brew -v如果没有安装 Homebrew可以用官方脚本安装。安装好之后执行brew tap probezy/core brew install cpolar然后安装并启动服务sudo cpolar service install sudo cpolar service start验证版本确认安装成功cpolar version出现版本信息就说明装好了。接着注册 cpolar 账号注册完成后在浏览器访问 http://127.0.0.1:9200 进入 Web UI 管理界面用刚注册的账号登录。登录后进入隧道管理创建或编辑一条隧道。关键配置是隧道名称填一个好辨识的比如 hermesweb协议选 http本地地址填 8648也就是 hermes-web-ui 的端口地区按需选择。保存之后到在线隧道列表你会看到一条 https 协议的公网地址。用这个地址访问应该能看到 hermes-web-ui 的登录页面输入 Token 就能进入控制台。不过随机公网地址适合临时测试长期用不方便因为地址可能会变。所以建议配置固定二级子域名。进入 cpolar 的预留页面选择保留二级子域名填写地区、名称、描述点击保留。列表中会出现一条记录比如二级域名是 hermes01。注意二级域名是唯一的以你自己保留的为准。然后回到隧道列表编辑 hermesweb 这条隧道把域名类型改成二级子域名在 Sub Domain 里填你保留的名称更新。再回到在线隧道列表公网地址就变成固定二级子域名形式了。用这个固定地址访问输入 Token 登录测试通过后就配置完成了。这里把 cpolar 的关键配置整理一下配置项值说明隧道名称hermesweb自定义便于辨识协议httpWebUI 是 HTTP 服务本地地址8648hermes-web-ui 默认端口域名类型二级子域名固定地址用Sub Domain你保留的名称如 hermes01配置完成后你在外面用手机或者其他电脑都可以通过这个固定地址打开 Hermes 的 Web 控制台查看对话、模型、任务和日志。对于长期运行的 Hermes 来说这个远程入口让管理变得方便很多。最后说一个实际使用中的小技巧如果你后面要调整 Hermes 的模型配置或者频道接入建议先在 WebUI 里改改完立即在对话面板发一条测试消息验证。这样配置和验证在同一个界面里完成不用来回切终端。另外固定二级子域名配好之后建议把它收藏到浏览器书签日常打开就是一步的事。整套搭下来Hermes 还是那个在后台干活的 Agent消息平台还是日常入口但你现在多了一个随时能打开、能看、能调的管理后台。