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 为什么先配 TaoTokenHermes Agent 的模型调用、工具执行都依赖 API 通道。如果每个模型提供商单独配一套 Key后续在 WebUI 里切换模型、排查调用异常会很乱。TaoToken 提供统一的 Key 和 API 通道把模型接入收敛到一个入口WebUI 的模型页面里只需要维护一套配置。TaoToken 的 API 地址是https://taotoken.net/api官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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.jsonWebUI 行为配置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才生效。模型调用 401TaoToken 的 Key 填错或过期去控制台重新创建一把同步更新 config.toml 和 settings.json 两处。模型调用 404base_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/consoleAPI Keys 管理在https://taotoken.net/api-keys。想直接在网页里试模型对话可以用https://taotoken.net/model-chat如果打算长期跑编码类 Agent 任务Coding Plan 页面在https://taotoken.net/coding-plan。最后提醒一句WebUI 能碰模型、频道、任务和日志权限比普通聊天入口高得多。公网访问时 Token 要妥善保管别把管理地址和凭证直接发到公开场合。固定二级子域名配好之后建议把 cpolar 的隧道访问也加上一层自己的认证习惯比如定期换 Token。