腾讯云 Ubuntu 搭建 Hermes Agent 并接入硅基流动 API 全流程实战
在腾讯云 Ubuntu 服务器上部署 Hermes Agent（Nous Research 开源 AI 智能体框架），并通过硅基流动（SiliconFlow）平台调用 DeepSeek 等大模型。本文记录完整操作流程、遇到的问题与解决方案。
⚠️ 隐私提醒： 文中所有涉及 API 密钥、密码、Token 的位置均用
<占位符>代替，请勿在真实文档中明文展示。
目录
- 环境概览
- 第一步：安装 Hermes Agent
- 第二步：接入硅基流动（SiliconFlow）API
- 第三步：配置模型与验证
- 第四步：搭建 Web UI（hermes-web-ui）
- 常见问题与解决方案（重点）
- 安全注意事项
- 最终成果与常用命令
1. 环境概览
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 24.04.4 LTS |
| 云服务商 | 腾讯云 |
| Hermes 框架 | Hermes Agent（Nous Research） |
| LLM 平台 | 硅基流动 SiliconFlow |
| 模型 | deepseek-ai/DeepSeek-V4-Flash |
| Web UI | hermes-web-ui（npm 全局安装） |
| Node.js | v23（从 v22 升级） |
架构说明：Hermes Agent 是同一套智能体核心，可同时运行在终端、Web UI、聊天网关（微信/Telegram 等）多种入口，通过工具调用与系统交互。
2. 第一步：安装 Hermes Agent
Hermes Agent 提供 Shell 一键安装脚本，会自动配置 uv、Python、虚拟环境和启动器：
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash安装完成后，核心命令入口是 hermes。
验证安装：
hermes --version
hermes doctor # 检查依赖和配置
hermes status # 查看组件状态3. 第二步：接入硅基流动（SiliconFlow）API
3.1 获取 API 密钥
登录硅基流动平台 → 控制台 → API 密钥 → 创建密钥，得到形如 sk-xxxxxxxx 的密钥。
3.2 配置 Hermes 使用该密钥
在 .env 文件中配置密钥（.env 只存放密钥等敏感信息）：
# 路径：~/.hermes/.env（或 $HERMES_HOME/.env）
SILICONFLOW_API_KEY=<你的硅基流动API密钥，勿明文展示>隐私要点：API 密钥只写入 ~/.hermes/.env，绝不写进任何文档、脚本或聊天记录。3.3 配置 Provider 指向硅基流动
通过 hermes config 将默认模型与 Provider 指向硅基流动：
hermes model # 交互式选择模型与 Provider
hermes config set <provider配置项> <值>配置完成后，.env 里应能看到硅基流动相关的密钥项，hermes status 中 Provider 显示为 custom_siliconflow。
4. 第三步：配置模型与验证
4.1 确认模型
hermes status | grep -E "Model|Provider"
# Model: deepseek-ai/DeepSeek-V4-Flash
# Provider: custom_siliconflow4.2 试跑一个查询验证连通
hermes chat -q "用一句话介绍你自己"如果正常返回内容，说明 Hermes ↔ 硅基流动 ↔ DeepSeek 整条链路已打通。
4.3 启动聊天网关（可选）
Hermes 支持接入多种聊天平台（微信、Telegram、Discord 等）：
hermes gateway run # 前台运行
hermes gateway status # 查看网关状态5. 第四步：搭建 Web UI（hermes-web-ui）
5.1 全局安装
npm install -g hermes-web-ui⚠️ 遇到的问题：
npm error EACCES: permission denied, mkdir '/usr/lib/node_modules/hermes-web-ui'原因：npm 全局安装写入系统目录 /usr/lib/node_modules，当前普通用户无写权限。
✅ 解决：用 sudo 安装：
sudo npm install -g hermes-web-ui5.2 启动
hermes-web-ui start默认监听 8648 端口：
✓ hermes-web-ui started
http://localhost:8648初次启动会返回一个带 Token 的访问地址，形如 http://localhost:8648/#/?token=<一串字符>，该 Token 是访问凭证，请勿公开。5.3 公网访问与安全
服务默认监听 0.0.0.0:8648（公网可达）。若需公网访问，需在腾讯云安全组放行 8648 端口。强烈建议：
- 仅使用时开放，用完即关
- 使用强密码或 Token 保护
- 不要长期暴露管理界面
6. 常见问题与解决方案（核心章节）
6.1 安装后 Web UI 启动失败：spawn hermes ENOENT
现象：
FATAL: Uncaught exception
Error: spawn hermes ENOENT原因：hermes-web-ui 启动时需自动拉起 hermes gateway run，但用 sudo（root）启动时，root 的 PATH 里没有 hermes 命令路径（hermes 安装在 /home/ubuntu/.local/bin/，不在 root 的 PATH 中）。
✅ 解决：启动时显式带上完整 PATH：
sudo bash -c 'export PATH="$PATH:/home/ubuntu/.local/bin"; nohup hermes-web-ui start >/tmp/hwui.log 2>&1 &'6.2 页面提示 Node.js 版本过低
现象：
检测到 Node.js v22.23.2，请升级到 23 以上版本
原因：hermes-web-ui 要求 Node.js 23+，而服务器的 Node 是 22.x（通过 nodesource 的 node_22.x 源安装）。
✅ 解决：把 nodesource 源从 node_22.x 换成 node_23.x 后升级：
# 修改 /etc/apt/sources.list.d/nodesource.sources 中的源
sudo sed -i 's|deb.nodesource.com/node_22.x|deb.nodesource.com/node_23.x|' /etc/apt/sources.list.d/nodesource.sources
sudo apt-get update
sudo apt-get install -y --only-upgrade nodejs
node --version # v23.11.1升级后重启 hermes-web-ui：
sudo bash -c 'export PATH="$PATH:/home/ubuntu/.local/bin"; nohup hermes-web-ui restart >/tmp/hwui.log 2>&1 &'6.3 Web UI 重启后 8648 端口无监听
现象：curl localhost:8648 连接失败（状态码 000），ss -tlnp 无 8648 监听。
原因：服务进程因 PATH 问题或后台会话结束而退出。
✅ 解决：用带完整 PATH 的 nohup 方式重新启动（见 6.1），并用端口检查确认：
sudo ss -tlnp | grep 8648 # 确认监听
curl -s -o /dev/null -w "%{http_code}" http://localhost:8648/ # 确认响应6.4 npm 全局安装无权限
现象：EACCES 权限拒绝（见 5.1）。
原因：npm 全局目录在 /usr/lib/node_modules（系统目录）。
✅ 解决：sudo npm install -g <包名>，或用 nvm 将 npm 全局目录改到用户目录下。
6.5 公网端口不通（安全组）
现象：本机能访问，但从公网 IP 访问超时/拒绝。
原因：腾讯云安全组在云控制台过滤入站流量，未放行目标端口。
✅ 解决：腾讯云控制台 → 安全组 → 添加入站规则（TCP + 端口 + 0.0.0.0/0）。开通后从公网 IP 测试：
curl -s -o /dev/null -w "%{http_code}" http://<服务器公网IP>:<端口>/7. 安全注意事项（重要）
- API 密钥只进
.env—— 密钥绝不写进文章、脚本、截图、聊天记录。 - Token / 密码绝不公开 —— Web UI 的访问 Token、登录密码都是敏感凭据。
- 管理界面不要长期暴露公网 —— 用完即关，或改用强认证（基本认证/ OAuth）。
- 只开放需要的端口 —— 在腾讯云安全组按需放行，最小化暴露面。
- 日志也可能含敏感信息 —— 分享日志前先排查密钥与 Token。
8. 最终成果与常用命令
8.1 常用命令速查
hermes # 进入交互式聊天（CLI 终端界面）
hermes chat -q "..." # 单次查询
hermes status # 查看组件状态
hermes model # 切换模型/Provider
hermes gateway run|status # 聊天网关运行/状态
hermes-web-ui start|stop|restart # Web UI 管理
hermes-web-ui status # 查看状态
hermes dashboard --status|--stop # Hermes 内置 Web 面板8.2 关键路径与配置
~/.hermes/.env # API 密钥（敏感，勿泄露）
~/.hermes/config.yaml # 配置（模型、Provider、工具等）
~/.hermes/skills/ # 安装的技能
~/.hermes/logs/ # 运行日志结语
Hermes Agent 的能力很强，但第一次部署最容易在权限、PATH、和云服务商安全组这三个地方卡住。这篇实战记录了最常见的几个坑及解法，希望帮你顺利跑通 腾讯云 + Hermes + 硅基流动 这套组合。
再次提醒： 分享这类文档时，务必确认文中没有泄露任何 API 密钥、密码或 Token。