# Hermes Agent 完全配置教程：在 Windows WSL、macOS 与 Linux 下从安装到 Telegram 完美集成
**作者**: Mulight 沐光
**日期**: 2026-04-21T07:08:04.000Z
**来源**: [https://x.com/0xMulight/status/2046486105739161887](https://x.com/0xMulight/status/2046486105739161887)
---
## 概述
本教程将详细介绍如何在 Windows 系统 基于 WSL、macOS 以及原生Linux 环境下从零开始配置强大的 Hermes Agent，并配合 Web UI 将其集成到Telegram，实现通过手机随时随地访问您的私有 AI 助手。教程基于真实的排坑过程，包含所有核心步骤、常见问题和解决方案。
## 目录
环境准备
Hermes Agent 安装
基础配置
Telegram Bot 创建
启动服务与 Web UI
Telegram 集成配置
用户配令人与授权
常见问题解决
高级配置
测试与验证
维护与更新
总结与后续建议
## 一 环境准备
系统要求 全平台支持
Hermes 强依赖 Linux 架构的底层进程管理，原生支持 macOS 和各大主流 Linux 发行版 Ubuntu、CentOS 等。Windows 用户必须使用 WSL2 环境。
Windows 用户：在 Windows 搜索“启用或关闭 Windows 功能”，务必勾选 虚拟机平台 和 适用于 Linux 的 Windows 子系统。重启电脑后，在命令提示符执行 wsl --install，或直接在 Microsoft Store 安装 Ubuntu。
macOS 用户：请打开系统自带的Terminal 终端，建议提前安装好 Homebrew包管理器，并在终端执行 xcode-select --install 安装必要的开发者工具。
Linux 用户：直接打开你熟悉的终端即可。
环境验证 打开你系统对应的终端执行：
# 检查Python 环境 通常系统自带
python3 --version
# 检查网络连接 确保你的终端可以科学上网
curl -s https://api.telegram.org
## 二 Hermes Agent 安装
注：不推荐使用旧版的 pip 手动安装，容易产生依赖冲突。
推荐安装方法：官方一键脚本 这是最稳妥的安装方式，会自动配置Python 虚拟环境和必要的底层构建工具，全平台通用。
curl -fsSL https://hermes-agent.nousresearch.com/install.sh| bash
提示：安装过程中如果询问是否安装 ripgrep 和 build tools，请务必输入 Y 确认，否则后续跑 AI 策略时可能会报错。
验证安装：
hermes --version
## 三 基础配置
1. 初始化向导配置
安装完成后，直接运行官方配置向导 比手动写 yaml 配置文件更安全：
hermes setup
按照屏幕提示操作：
- 选择你喜欢的大模型提供商 强烈推荐选择 DeepSeek，速度快且跑代码/策略性价比极高，选 deepseek-chat 模型。
- 输入对应的 API Key。
- 当系统询问是否现在配置 Messaging Platform 如Telegram时，选择 Skip 跳过，我们稍后在更方便的 Web UI 中配置。
DeepSeek链接：https://platform.deepseek.com/api_keys
2. 配置文件位置
向导跑完后，你的配置会自动保存在：~/.hermes/config.yaml。
## 四 Telegram Bot 创建
创建 Bot
- 在 Telegram 中搜索 @BotFather
- 发送 /newbot 命令
- 设置 Bot 名称和用户名 必须以 bot 结尾
- 复制生成的 Bot Token 格式：1234567890:ABCdef...
获取你的用户 ID
- 在 Telegram 中搜索 @userinfobot
- 发送 /start，复制显示的纯数字 User ID。
## 五 启动服务与Web UI 核心推荐
注：原文通过命令行手动改配置的方式极易出错。强烈建议使用官方 Web UI 面板来统一管理底层的 Gateway 服务和渠道连接。
一键安装环境自适应的 Web UI： 此脚本会自动检测你的系统是 macOS、Linux 还是 WSL，并智能配置后台挂机模式。
推荐EKKOLearnAI/hermes-web-ui
GIT仓库地址：https://github.com/EKKOLearnAI/hermes-web-ui/tree/main
输入命令：
bash <(curl -fsSL https://cdn.jsdelivr.net/gh/EKKOLearnAI/hermes-web-ui@main/scripts/setup.sh)
如果提示找不到 hermes 命令，请先执行 source ~/.bashrc 或者source ~/.zshrc 刷新环境变量，再跑一遍上面的安装脚本
启动面板：
hermes-web-ui start
打开浏览器访问：http://localhost:8648，您将看到精美的可视化管理界面。
## 六 Telegram 集成配置 通过面板
在浏览器打开的 Web UI 中，进入 Gateway / 通讯设置 页面。
找到 Telegram 选项卡并开启。
填入刚才从 BotFather 获取的 Bot Token。
保存并重启 Gateway：面板会在后台自动应用配置并拉起服务。
## 七 用户配对与授权 重点排坑
很多人在 Web UI 设置完 Telegram 后发现机器人依然无响应，这是因为底层 Gateway 网关引擎因为配置文件冲突崩溃了！必须清理旧配置并设置权限。
第一步：清理底层过期的致命配置
新版 Hermes 已经废弃了部分变量，底层一看到旧变量就会触发安全机制中断退出。在终端执行以下命令直接拔除病根：
WSL：sed -i '/TERMINAL_CWD/d' ~/.hermes/.env
MacOS: grep -v "TERMINAL_CWD" ~/.hermes/.env > ~/.hermes/.env.tmp && mv ~/.hermes/.env.tmp ~/.hermes/.env
第二步：直接设置白名单 最稳妥方案
在终端执行以下命令，直接将你的 TG 账号设为全局允许：
echo "GATEWAY_ALLOW_ALL_USERS=true" >> ~/.hermes/.env
# 或者精确限制你的 TG ID：
# echo "TELEGRAM_ALLOWED_USERS=你的TG用户ID" >> ~/.hermes/.env
第三步：彻底重启底层网关
清理并授权后，强杀旧进程并让新网关在后台运行：
pkill -f "hermes gateway" && hermes gateway run --replace &
## 八 常见问题解决
问题1：Web UI 安装后提示 command not found
解决方案：环境变量未刷新。执行 source ~/.bashrc mac 用户执行source ~/.zshrc。如果依然不行，执行绝对路径启动： /home/你的用户名/.hermes/node/bin/hermes-web-ui start
问题2：Telegram 连接超时或无响应 解决方案：确保系统的网络终端开启了代理的 TUN 模式。可以在终端里测试：curl -s https://api.telegram.org，如果不通则说明网络被墙。
问题3：终端关闭后，Telegram 机器人掉线
解决方案：如果你使用的是 Windows WSL，WSL 相当于一个虚拟机，如果您的 Windows 关机或彻底杀死了 WSL 进程，服务就会停止，请保持终端在后台运行。如果你使用的是 macOS 或 Linux，由于安装脚本自动配置了系统级守护进程，通常关闭终端也会保持长期在线。
## 九 高级配置 选修
如果你喜欢极客操作，可以直接编辑 ~/.hermes/config.yaml：
技能与内存持久化配置：
YAML
skills:
enabled: true
auto_load: true
memory:
enabled: true
storage: "sqlite"
path: "~/.hermes/memory.db"
## 十 测试与验证
验证 Web UI：访问 http://localhost:8648 确保正常运行。
测试 Telegram：打开 Telegram，向你的 Bot 发送 hello。如果 AI 能快速回复你，并且能在 Web UI 的聊天记录中看到交互，说明大功告成！
## 十一 维护与更新
# 更新底层Hermes Agent
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
# 刷新环境变量
source ~/.bashrc
## 十二 故障恢复
如果遇到严重卡死或配置错乱问题：
# 1. 强行停止所有服务
pkill -f "hermes"
# 2. 重新通过Web UI 启动服务
WSL：hermes-web-ui start
MacOs: grep -v "TERMINAL_CWD" ~/.hermes/.env > ~/.hermes/.env.tmp && mv ~/.hermes/.env.tmp ~/.hermes/.env
## 总结
通过本教程，你已经成功：
✅ 完美配置了全平台的底层环境
✅ 避开了命令行配置的坑，部署了图形化 Web UI
✅ 成功创建并授权了 Telegram专属机器人
✅ 为后续跑策略和日常助理需求打好了坚实基础
获取帮助
- 官方文档： https://hermes.help
- 恭喜！你的私有化 Hermes Agent 现已完全配置完毕，开始享受跨平台的 AI 助理体验吧！
## 相关链接
- [Mulight 沐光](https://x.com/0xMulight)
- [@0xMulight](https://x.com/0xMulight)
- [2.3K](https://x.com/0xMulight/status/2046486105739161887/analytics)
- [https://api.telegram.org](https://api.telegram.org/)
- [https://hermes-agent.nousresearch.com/install.sh](https://hermes-agent.nousresearch.com/install.sh)
- [https://platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys)
- [@BotFather](https://x.com/@BotFather)
- [@userinfobot](https://x.com/@userinfobot)
- [https://github.com/EKKOLearnAI/hermes-web-ui/tree/main](https://github.com/EKKOLearnAI/hermes-web-ui/tree/main)
- [https://cdn.jsdelivr.net/gh/EKKOLearnAI/hermes-web-ui@main/scripts/setup.sh](https://cdn.jsdelivr.net/gh/EKKOLearnAI/hermes-web-ui@main/scripts/setup.sh)
- [https://api.telegram.org，如果不通则说明网络被墙](https://api.telegram.xn--org,-jb5fk8s2umgxb947cwidzw8fdfbiz6ekvjdup/)
- [http://localhost:8648](http://localhost:8648/)
- [https://hermes-agent.nousresearch.com/install.sh](https://hermes-agent.nousresearch.com/install.sh)
- [https://hermes.help](https://hermes.help/)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [3:08 PM · Apr 21, 2026](https://x.com/0xMulight/status/2046486105739161887)
- [2,399 Views](https://x.com/0xMulight/status/2046486105739161887/analytics)
---
*导出时间: 2026/4/21 19:26:55*