1. 为什么 Hermes Agent 需要一个 WebUI 管理后台
Hermes Agent 接入微信、飞书或企微之后，日常用起来就像一个聊天机器人：发一句话，等一会儿收到回复。但 Agent 和普通聊天机器人不一样，它背后涉及模型调用、工具执行、频道配置、定时任务、插件和日志。服务长期运行以后，只看聊天窗口里的最终回复，很难判断当前配置是什么、任务有没有正常执行、异常出在哪一步。
hermes-web-ui 补的就是这一层。它不替代 Hermes Agent，而是给后台运行的 Agent 加一个浏览器控制台，把对话测试、模型、频道、TTS、任务、插件和日志集中展示出来。你可以把它理解成给一台常年开着的服务器装了一块仪表盘：Agent 负责干活，WebUI 负责让你看见它怎么干、干得怎么样。
这篇面向的是已经把 Hermes Agent 跑起来、想再加一个可视化管理入口的人。我会覆盖 hermes-web-ui 的 npm 安装、本地启动、cpolar 内网穿透远程访问，以及用 TaoToken 统一 Key/API 通道接入模型配置的完整流程。全程给可复制的 config.toml 与 settings.json 骨架，最后做一次连通性验证，确保远程环境下管理后台能稳定打开。
2. 前置准备：Node 环境与 TaoToken 统一通道
2.1 确认 Node.js 与 npm 版本
hermes-web-ui 对 Node.js 版本有要求，建议 Node.js 23 或更高。先在终端确认环境：
node -v npm -v如果版本太低，先升级 Node.js 再继续。版本不够时 npm 全局安装可能报引擎不兼容的错，这一步别跳过。
2.2 为什么先配 TaoToken
Hermes Agent 的模型调用、工具执行都依赖 API 通道。如果每个模型提供商单独配一套 Key，后续在 WebUI 里切换模型、排查调用异常会很乱。TaoToken 提供统一的 Key 和 API 通道，把模型接入收敛到一个入口，WebUI 的模型页面里只需要维护一套配置。
TaoToken 的 API 地址是https://taotoken.net/api，官网入口在https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=。先去控制台创建一个 API Key，后面写进配置文件。
创建 Key 的入口在控制台，拿到 Key 之后先别急着填，等 WebUI 起来后一起验证。
3. 安装 hermes-web-ui 并启动 8648 端口
3.1 让 Hermes Agent 自己装（推荐）
如果 Hermes Agent 已经能正常运行，最省事的方式是直接让它自己完成安装。把下面这段提示词发给它：
请帮我在当前设备上安装 hermes-web-ui。先检查 Node.js 和 npm 是否可用， 如果环境正常，就使用 npm 全局安装 hermes-web-ui。安装完成后启动 hermes-web-ui， 并告诉我本地和局域网访问地址、登录密码是什么，以及如何修改密码。 如果端口被占用，请先提示我，不要删除任何文件。发送后它会先检查环境，再执行安装、启动，并返回访问地址和登录 Token。这种方式适合已经跑通 Agent 的用户，相当于让 AI 助手自己给自己装上控制台。
3.2 手动 npm 安装
不想自动安装就手动来。全局安装：
npm install -g hermes-web-ui安装完成后启动：
hermes-web-ui start启动成功后终端会输出本地地址、局域网地址和登录 Token。默认本地访问地址是：
http://localhost:8648同一局域网内的其他设备可以用终端输出的局域网地址访问。打开页面后输入 Token 进入控制台。
3.3 修改登录密码
Token 就是登录密码。想改密码，写入新的 token 文件后重启：
echo "你的新密码" > ~/.hermes-web-ui/.token hermes-web-ui restart重启后旧 Token 失效，用新密码登录。这一步在把 WebUI 暴露到公网之前一定要做，别用默认生成的弱口令。
4. 可复制的 config.toml 与 settings.json 骨架
4.1 config.toml：模型与 API 通道
Hermes Agent 的模型配置走 config.toml。下面是一份可直接改的骨架，把 TaoToken 作为统一 API 通道：
# ~/.hermes/config.toml [model] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key = "sk-你的TaoToken密钥" default_model = "claude-sonnet-4-20250514" timeout = 60 [model.fallback] enabled = true model = "gpt-4o-mini" [webui] enabled = true port = 8648 host = "0.0.0.0"几个关键点：base_url填 TaoToken 的 API 地址，不要带多余路径；api_key换成你在控制台创建的那把；host设成0.0.0.0是为了让局域网和穿透工具都能访问，只绑127.0.0.1的话 cpolar 映射不到。
4.2 settings.json：WebUI 行为配置
WebUI 自身的设置走 settings.json，控制界面行为、TTS 和任务面板：
{ "webui": { "port": 8648, "token_file": "~/.hermes-web-ui/.token", "theme": "auto", "language": "zh-CN" }, "tts": { "enabled": false, "provider": "webspeech", "voice": "zh-CN" }, "tasks": { "history_limit": 100, "timezone": "Asia/Shanghai" }, "model": { "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoToken密钥" } }TTS 先关着，等基础对话跑通再开。timezone设成Asia/Shanghai，定时任务的执行时间才符合预期，不然天气推送可能半夜发。
4.3 配置生效与重启
改完两个文件后重启服务：
hermes-web-ui restart重启后进 WebUI 的模型页面，应该能看到 TaoToken 通道下的模型列表。如果列表为空，先看第 6 节的排查。
5. 验证请求：从 WebUI 对话到定时任务
5.1 连通性验证
进 WebUI 后先在对话页发一条测试消息，比如「现在几点」。能正常回复说明模型通道通了。如果报错，重点看返回的错误码：401 是 Key 问题，404 是 base_url 路径问题，超时是网络或 timeout 设置问题。
更直接的验证方式是用 curl 打一次 TaoToken 的接口：
curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的TaoToken密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "ping"}] }'返回正常 JSON 就说明 Key 和通道都没问题，问题在 Hermes 配置侧。
5.2 创建一个定时任务验证
在 WebUI 左侧进入任务面板，创建一个「每天早上 8 点推送当天天气」的任务。创建后点「立即运行」手动触发一次，稍等片刻微信端会收到天气提醒，任务面板里也能看到本次运行历史。
这一步同时验证了三件事：模型通道正常、任务调度正常、频道推送正常。三个都过，说明整套链路是通的。
6. cpolar 内网穿透与常见错排查
6.1 用 cpolar 暴露 8648 端口
WebUI 默认只能在本地网络访问，出门在外就打不开。用 cpolar 把 8648 端口映射成公网地址。macOS 下用 Homebrew 安装：
brew tap probezy/core && brew install cpolar sudo cpolar service install sudo cpolar service start cpolar version装好后访问http://127.0.0.1:9200登录 cpolar 后台，在隧道列表里编辑一条隧道：协议选 http，本地地址填8648，地区选 China Top，保存后在线隧道列表会生成公网地址。用 https 地址访问，能打开 WebUI 登录页就说明穿透成功。
想要固定地址，去 cpolar 预留页面保留一个二级子域名，再把隧道的域名类型改成「二级子域名」，填入预留名称，更新后公网地址就固定了。
6.2 常见错排查
WebUI 打不开、连接被拒：先确认hermes-web-ui start是否真的在跑，再看 config.toml 里host是不是0.0.0.0。绑了127.0.0.1的话 cpolar 映射不到。
登录一直提示 Token 错误：检查~/.hermes-web-ui/.token文件内容，注意别带多余换行。改完密码必须hermes-web-ui restart才生效。
模型调用 401：TaoToken 的 Key 填错或过期，去控制台重新创建一把，同步更新 config.toml 和 settings.json 两处。
模型调用 404：base_url写成了https://taotoken.net/api/v1之类带多余路径的形式。正确写法是https://taotoken.net/api，路径由客户端自己拼。
cpolar 隧道连上但页面空白：多半是 WebUI 只监听了本地回环。改host后重启，再重新访问公网地址。
定时任务不按点执行：检查 settings.json 里的timezone，没设成Asia/Shanghai的话执行时间会偏。
7. 接入文档与后续管理入口
WebUI 跑起来之后，日常管理就集中在这个控制台里了。模型配置、频道接入、任务历史、日志查看都在一个页面完成，不用再翻配置文件和终端输出。
如果你还在调模型接入和 API 通道，建议先把 TaoToken 的接入文档过一遍，确认 base_url 和 Key 的用法，再回 WebUI 验证。文档入口在https://taotoken.net/api，控制台里创建和管理 Key 的页面在https://taotoken.net/console，API Keys 管理在https://taotoken.net/api-keys。想直接在网页里试模型对话，可以用https://taotoken.net/model-chat；如果打算长期跑编码类 Agent 任务，Coding Plan 页面在https://taotoken.net/coding-plan。
最后提醒一句：WebUI 能碰模型、频道、任务和日志，权限比普通聊天入口高得多。公网访问时 Token 要妥善保管，别把管理地址和凭证直接发到公开场合。固定二级子域名配好之后，建议把 cpolar 的隧道访问也加上一层自己的认证习惯，比如定期换 Token。
