Hermes Agent 部署及初始配置指南

1. 环境准备

  • 操作系统要求:
    • 推荐使用 Ubuntu Server 24.04 LTS 版本，后期可更换为 26.04 LTS。
    • 硬件配置为 2 核心、2GB 内存、20GB 存储。
  • 必要的软件依赖:
    使用官方一键脚本进行部署，不修改原位置，使用默认国际源。
  • 初始配置:
    执行以下命令以更新系统并清理缓存： 
    sudo apt update && sudo apt -y --auto-remove --purge full-upgrade && sudo apt -y --purge autoremove && sudo apt clean -y
  • 网络配置:
    • 不开放外部访问，维护使用 Web 页面 SSH 进行。
    • 交互使用聊天工具。
    • 配置允许访问互联网。

2. 安装步骤

系统安装推荐在普通用户身份下进行。

  • 下载安装包:
    使用以下命令下载并执行安装脚本： 
    curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装用户需具备 sudo 权限，因为在一键安装脚本中还需要进行部分系统环境变量和工具的配置。

注：Hermes Agent 自身是不需要 root 权限的。也不建议 root 用户安装。

3. 启动与验证

  • 配置前准备:
    • 刷新一下系统环境变量。
      如果使用 Bash: source ~/.bashrc
      如果使用 Zsh: source ~/.zshrc
  • 安装二维码显示工具: 
    ~/.hermes/hermes-agent/venv/bin/python -m ensurepip
~/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade pip qrcode aiohttp cryptography
  • 将 Gateway 配置为系统级自动运行: 
    sudo /home/alan/.hermes/hermes-agent/venv/bin/hermes gateway install --system
  • 初始配置 Agent 服务:
    • 常见配置与命令如上图。

4. 配置 Hermes Agent

以配置飞书为例

  • 执行 hermes setup 命令进行配置。
    选择接入配置，按照需要进行选择。
    • image.png
      选择默认的在本地运行。
      选择配置接入的消息工具:
      image.png
      按空格选择需要的工具，回车键继续:
      image.png
      选择二维码接入，因为之前已经配置了二维码插件。
      image.png
      SSH终端显示二维码，并等待客户端配置。
      image.png
      客户端飞书扫描二维码，创建完成后会弹出下一步菜单。选择使用设备码进行安全验证。
      image.png
      选择群聊中智能体如何响应消息：只有 @ 智能体才会获得回复。
      image.png
      设置本地频道：默认保持为空，回车后会弹出完成设置的界面。
      image.png

5. 客户端验证配置

  • 确保网关服务已启动:
    执行 hermes profile list 检查。
    image.png
  • 重启 Gateway 服务:
    使用以下命令： 
    sudo /home/alan/.hermes/hermes-agent/venv/bin/hermes gateway restart
    或者： 
    sudo systemctl restart hermes-gateway
    image.png
  • 检查客户端接收列表:
    执行 hermes pairing list，发现列表为空。
    image.png
  • 等待客户端发送消息，然后再次刷新命令。
    执行 hermes pairing list。
    image.png
  • 客户端准入方式:
    • a. 使用客户端收到的验证码进行批准（无需重启服务）。
      客户端收到一个设备验证码，执行命令批准： 
      hermes pairing approve feishu 客户端收到的验证码
    • b. 直接修改配置文件，填写用户ID。
      如果已经获取到用户ID，直接在 .hermes/.env 中填写对应的字段。 
      tail .hermes/.env
      image.png
      重启服务后客户端正常访问。
      image.png
      清除待验证列表:
      执行 hermes pairing clear-pending。
      image.png

6. 常见问题与解决方案

  • 安装失败处理:
    • 检查网络连接是否正常。
    • 确保脚本具有可执行权限。
  • 服务启动异常处理:
    • 检查服务状态并查看日志。
    • 如果服务未启动，尝试重新安装或检查依赖项。
顺序命令说明命令
1更新系统并清理缓存sudo apt update && sudo apt -y --auto-remove --purge full-upgrade && sudo apt -y --purge autoremove && sudo apt clean -y
2安装 Hermes Agent`curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh
3刷新系统环境变量source ~/.bashrc 或 source ~/.zshrc
4安装二维码显示工具~/.hermes/hermes-agent/venv/bin/python -m ensurepip ~/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade pip qrcode aiohttp cryptography
5配置 Gateway 为系统自动运行sudo /home/alan/.hermes/hermes-agent/venv/bin/hermes gateway install --system
6配置 Hermes Agent 服务hermes setup
7重启 Gateway 服务sudo .hermes/hermes-agent/venv/bin/hermes gateway restart  sudo systemctl restart hermes-gateway
8客户端验证hermes pairing list
9客户端准入hermes pairing approve feishu 客户端收到的验证码
10清除待验证列表hermes pairing clear-pending
11检查日志文件tail /var/log/hermes-agent/agent.log
12查看 Hermes Agent 状态hermes gateway status
13查看 Hermes Agent 配置hermes config list
14重新配置 Hermes Agenthermes setup
15查看 Hermes Agent 配置文件tail .hermes/.env
16检查 Hermes Agent 系统配置hermes profile list