# Hermes Web Chat 安装指南 > 让 Hermes Agent 支持浏览器对话的网页界面 > **📌 当前版本：v1.2.2.1（2026-06-22）** > > **v1.2.2.1 补丁修复**： > - 🐛 修复 `except Future.timeout:` 导致 Python 3.11 抛 AttributeError、返回 500 HTML 错误页的问题（浏览器看到 "Unexpected token '<', ""..." 错误） > - ✅ 改用 `concurrent.futures.TimeoutError`，超时正常返回中文提示 > - ✅ 统一 `future.result(timeout=...)` 使用 `HERMES_TIMEOUT` 常量（之前是硬编码 150） > - ✅ `/chat` 路由加防堆积逻辑：同一 tab 上一个请求未完成时，返回 429 + "请稍后再发" > - ✅ 慢响应警告日志（>HERMES_TIMEOUT 时记录到 Flask logger） > > **v1.2.2 重大变更**： > - ❌ 移除 WebSocket → OpenClaw Gateway（11626）连接路径，避免 2026-06 OpenClaw 升级后的鉴权兼容问题 > - ✅ 新增 `hermes chat -Q` CLI 子进程路径（通过 systemd 环境变量 `HERMES_CMD` / `HERMES_USE_CLI=1` 控制） > - ✅ 新增多 tab 上下文隔离（按 `tab_id` 维护 `session_id` 映射表，自动 `--resume` 续接） > - ✅ systemd service 文件预填三个环境变量（`HERMES_CMD` / `HERMES_USE_CLI` / `HERMES_TIMEOUT`） > - 升级后需要 `systemctl daemon-reload && systemctl restart hermes-chat` --- ## 📋 开始之前 — 你需要准备什么 ### 必选项 | 内容 | 说明 | |------|------| | **Hermes Agent** | 已安装并能正常对话 | | **Python 3** | 服务器/电脑上已安装 | | **一个可用的 MiniMax API Key** | Hermes 对话必须用到 | ### 可选项（决定你用哪种模式） | 你的情况 | 选择哪种模式 | |----------|-------------| | 有域名 + 网站 + nginx | **模式 A**（推荐） | | 只有云服务器公网 IP | **模式 B** | | 本地 Mac/Linux 开发测试 | **模式 C** | --- ## Step 1 — 确认 Hermes 能正常对话 打开终端，运行： ```bash hermes --version ``` 能看到版本号（v0.10.x）就说明 Hermes 已安装。 **如果提示 command not found**，先安装 Hermes： ```bash # 方式一：pip 安装 pip install hermes-agent # 方式二：官方脚本（去 https://hermesagent.dev 看最新方法） ``` --- ## Step 2 — 确认 Python 环境 ```bash python3 --version ``` 要求 **Python 3.8 或更高版本**。 --- ## Step 3 — 确定部署模式 ### 你是哪种情况，对号入座： **情况 A：你有域名 + 网站 + nginx**（推荐 ✅） ``` 你的网站：https://example.com 安装后访问：https://example.com/hermes-chat/ ``` **情况 B：你只有云服务器公网 IP**（比如腾讯云/阿里云） ``` 你的IP：1.2.3.4 安装后访问：http://1.2.3.4:8081/ 额外操作：需要在云控制台开放 8081 端口 ``` **情况 C：本地 Mac/Linux 开发测试** ``` 安装后访问：http://localhost:8081/ ``` --- ## Step 4 — 执行安装 ### 情况 A（有域名 + nginx） 用 SSH 登录你的服务器，执行： ```bash # 一行命令，替换成你的域名 curl -sL https://raw.githubusercontent.com/YOUR_REPO/install.sh | bash -s -- \ --mode a \ --domain example.com \ --subdir /hermes-chat ``` > 把 `example.com` 换成你的真实域名 --- ### 情况 B（只有 IP） ```bash # 一行命令 curl -sL https://raw.githubusercontent.com/YOUR_REPO/install.sh | bash -s -- \ --mode b \ --port 8081 ``` 安装完成后会显示类似这样的提示： ``` 访问地址: http://1.2.3.4:8081/ ⚠️ 如果无法访问，请在云控制台安全组中放行 TCP 端口 8081 ``` **开放端口步骤（腾讯云示例）：** 1. 登录 [腾讯云控制台](https://console.cloud.tencent.com/) 2. 进入「云服务器」→「安全组」 3. 找到绑定你服务器的安全组 4. 入站规则添加： - 协议：`TCP` - 端口：`8081` - 来源：`0.0.0.0/0` 5. 保存 --- ### 情况 C（本地开发） ```bash # 下载脚本到本地 curl -sL https://raw.githubusercontent.com/YOUR_REPO/install.sh -o install.sh chmod +x install.sh # 运行 ./install.sh --mode c --port 8081 ``` --- ## Step 5 — 验证是否成功 安装脚本运行完毕后，浏览器打开： - **情况 A**：https://你的域名/hermes-chat/ - **情况 B**：http://你的IP:8081/ - **情况 C**：http://localhost:8081/ **看到输入框就说明成功了！** 输入一条消息测试： ``` 你好 ``` --- ## Step 6 — 如果遇到报错 ### 报错 1：401 Authentication Error **表现：** 对话界面提示认证错误，Hermes 无法回复 **原因：** API Key 没有配置好 **解决：** SSH 登录服务器，运行： ```bash # 查看当前的 key 状态 env | grep API_KEY # 如果显示 MINIMAX_API_KEY 但没有 ANTHROPIC_API_KEY，同步一下 export ANTHROPIC_API_KEY="$MINIMAX_API_KEY" # 重启服务 systemctl restart hermes-chat ``` --- ### 报错 2：无法访问此网站（连接超时） **原因：** 防火墙/安全组没有开放端口 **解决：** - **腾讯云**：控制台 → 安全组 → 入站规则 → 放行对应端口 - **阿里云**：ECS → 安全组 → 规则 → 入方向 → 添加记录 - **AWS**：EC2 → Security Groups → Inbound → 添加入口 --- ### 报错 3：502 Bad Gateway **原因：** Flask 服务没有启动 **解决：** ```bash # Linux 查看状态 systemctl status hermes-chat # 重启 systemctl restart hermes-chat ``` --- ## 常用命令 ### Linux 服务器 | 操作 | 命令 | |------|------| | 查看服务状态 | `systemctl status hermes-chat` | | 查看实时日志 | `journalctl -u hermes-chat -f` | | 重启服务 | `systemctl restart hermes-chat` | | 停止服务 | `systemctl stop hermes-chat` | | 卸载（停止+删除） | `systemctl stop hermes-chat && systemctl disable hermes-chat && rm /etc/systemd/system/hermes-chat.service` | ### Mac | 操作 | 命令 | |------|------| | 查看日志 | `tail -f ~/logs/hermes_chat.log` | | 停止服务 | `launchctl unload ~/Library/LaunchAgents/com.hermes.webchat.plist` | | 重新加载 | `launchctl load ~/Library/LaunchAgents/com.hermes.webchat.plist` | --- ## 更换端口 如果 8081 端口被占用，换一个： ```bash # 安装时指定端口 ./install.sh --mode a --domain example.com --port 9090 # 已有服务，改端口： # 1. 修改 /etc/systemd/system/hermes-chat.service 中的端口号 # 2. systemctl daemon-reload && systemctl restart hermes-chat # 3. 更新 nginx 配置中的端口 ``` --- ## 修改子目录路径 默认子目录是 `/hermes-chat`，想换成别的比如 `/chat`： ```bash ./install.sh --mode a --domain example.com --subdir /chat ``` --- ## 安全提醒 ⚠️ **Web 界面没有密码保护**，建议： - **情况 A**（有 nginx）：通过子目录访问，已受 HTTPS 保护，短期公网使用没问题 - **情况 B**（IP 直连）：建议用完即关，或加 nginx 密码认证 - **情况 C**（本地）：无风险 --- ## 界面体验优化 ✅ **回复干净整洁** — 自动过滤 Hermes CLI 的工具列表、Banner、Session 信息，只显示对话文字： ``` 你：你好 → 你好 Jeff！有什么可以帮你的？ ``` **输入不被遮挡** — 发送消息后界面自动滚动，始终露出你刚输入的内容和"正在思考"状态提示。 --- ## 多轮对话支持 ✅ ``` 你：我叫Jeff → 你好 Jeff！有什么可以帮你的？ 你：我几岁？ → 我没有你的年龄信息，如果你愿意告诉我... 你：刚才我叫什么？ → 你叫 Jeff ✅（正确记住） ``` - 每个浏览器标签页有独立的会话（基于 `localStorage`） - 关闭标签页或新标签页 = 新会话 - 超过 1 小时无活动自动清理 - **注意**：会话上下文存在服务器内存中，服务重启后丢失（关闭标签页不影响） --- ## 技术架构说明 ``` [你的浏览器] ↓ https://example.com/hermes-chat/ [nginx 反向代理]（可选） ↓ [Flask Web 服务 :8081] ↓ 调用 [Hermes Agent CLI] ↓ 请求 [MiniMax API]（对话） ``` **包含组件：** - `hermes_chat_app.py` — Flask 网页应用 - `install.sh` — 一键安装脚本 - systemd / launchd — 开机自启服务 --- ## 获取帮助 遇到问题先看日志： ```bash # Linux journalctl -u hermes-chat -n 50 # Mac tail -50 ~/logs/hermes_chat.log ``` --- ## 更新历史 ### v1.2.0（2026-05-02） **多页签支持** — 新增标签页功能，每个浏览器标签页独立一个 Hermes 会话，通过 --resume 保持上下文： - 点击左上角 + 新建标签页，开启独立任务 - 切换标签页自动加载该任务的历史对话 - 同一标签页内多轮对话上下文自动保持 - 关闭标签页后，新标签页不会影响其他任务 **界面滚动优化** — 发送消息后、显示思考状态时、回复到达后，三处都加了自动滚动，输入内容不会被遮挡 **回复过滤** — 只提取对话文字，过滤 Hermes CLI 的工具列表/Banner/Session 信息 ### v1.1.0（2026-05-02） - 回复过滤：新增 extract_hermes_response() 解析函数 - 界面滚动：发送后/思考时/回复后三处都加 scrollTop - 版本号从 v1.0.0（2026-04-24）升级到 v1.1.0（2026-05-02） ### v1.0.0（2026-04-24） - 初始版本，支持与 Hermes 对话的 Web 界面