摘要

这篇文章记录如何在 macOS 和 Ubuntu Desktop 24.04 LTS 上安装 Hermes Agent，并给出一套更适合个人使用和长期运行的配置建议。

Hermes Agent 是 Nous Research 开源的 AI Agent。它不是单纯的聊天机器人，也不是绑定在 IDE 里的代码助手，而是一个可以长期运行在你自己电脑、服务器、VPS 或容器环境里的自治 Agent。它支持：

• CLI 对话
• 长期记忆
• 自动生成和复用技能
• 定时任务
• Telegram、Discord、Slack、飞书、企业微信、微信、钉钉、Email 等消息入口
• Web 搜索、浏览器自动化、语音、图片等工具
• local、Docker、SSH、Singularity、Modal、Daytona 等执行后端

如果你只是想在自己电脑上试用，Mac 是最方便的入口。如果你希望 Agent 长期在线、能跑定时任务、能接消息机器人、能作为个人自动化服务器使用，Ubuntu 24.04 LTS 更适合作为生产环境。

1 - Hermes Agent 适合解决什么问题

现在的 AI 工具大致可以分成三类：

1. 网页聊天工具，比如 ChatGPT、Claude、Gemini。
2. IDE 编程助手，比如 Cursor、GitHub Copilot。
3. 常驻型 Agent，比如 Hermes Agent。

前两类工具更像“你打开它，它帮你处理当前问题”。Hermes Agent 的定位更偏向“你把它部署在自己的环境里，它逐渐记住你的项目、偏好、流程，并通过 CLI、消息平台或定时任务持续工作”。

举几个更适合 Hermes Agent 的场景：

• 每天早上定时汇总新闻、项目状态或服务器状态
• 通过 Telegram 给家里的 Ubuntu 服务器发送任务
• 让 Agent 记住某个项目的构建、测试、部署流程
• 在 Docker 沙箱里分析陌生代码仓库
• 用 SSH 后端连接远程机器执行任务
• 把常用的多步操作沉淀成 skill，下次直接复用

所以，它不是替代 Cursor 的工具，而是补上了“长期运行、跨平台入口、自动化、记忆和定时任务”这一块。

2 - Mac 和 Ubuntu 应该怎么选

2.1 Mac：适合个人试用和日常助手

如果你平时主要在 Mac 上工作，先在 Mac 上安装 Hermes Agent 是最省事的。它适合：

• 本地 CLI 对话
• 研究文档
• 管理本机项目
• 轻量脚本自动化
• 体验 memory、skills、tools 等功能

Mac 的优势是日常使用方便，终端、浏览器、剪贴板、开发工具都在同一台机器上。但它的缺点也很明显：电脑合上、关机、断网之后，Agent 就无法长期在线。

2.2 Ubuntu 24.04 LTS：适合常驻 AI Agent 服务器

如果你已经有一台旧笔记本、迷你主机、NAS、VPS 或云服务器，Ubuntu 24.04 LTS 更适合跑 Hermes Agent。

Ubuntu 的优势是：

• 可以 7x24 小时运行
• 适合配合 SSH、Tailscale、Docker 使用
• 适合挂定时任务和消息网关
• 环境更接近服务器和容器生态
• 后续迁移到更强的机器也更自然

如果你之前已经像我一样把旧笔记本改造成 Ubuntu AI 自动化服务器，那么 Hermes Agent 就是很自然的下一步：系统负责常驻，Docker 负责隔离，Hermes Agent 负责把 AI 能力接到自动化工作流里。

若系统盘较小、另有挂载在 /data 的数据盘，安装时建议直接把 HERMES_HOME 指到数据盘（详见 6.1 节），避免 venv、会话和日志占满根分区。

3 - 官方安装方式

Hermes Agent 官方文档给出的 Linux / macOS / WSL2 安装方式是一行命令：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后，重新加载 shell 配置，然后进入初始化向导：

source ~/.bashrc
hermes setup

如果你使用的是 zsh，则执行：

source ~/.zshrc
hermes setup

官方安装器会自动处理大部分依赖，包括：

• uv
• Python 3.11
• Node.js 22
• ripgrep
• ffmpeg
• Hermes Agent 仓库
• Python 虚拟环境
• 全局 hermes 命令
• LLM Provider 初始化配置

官方文档也说明，唯一需要提前确认的是 Git 可用：

git --version

如果这个命令能正常输出版本号，通常就可以开始安装。

4 - macOS 安装 Hermes Agent

4.1 安装前准备

Mac 上建议先准备好 Xcode Command Line Tools：

xcode-select --install

如果你还没有安装 Homebrew，建议先安装。Hermes Agent 官方安装器不一定强依赖 Homebrew，但对于长期使用 Mac 开发环境来说，Homebrew 基本是必备工具。

确认 Git 可用：

git --version

如果 Git 不存在，通常安装 Xcode Command Line Tools 后就会有。

4.2 Apple Silicon 和 Intel Mac 的 PATH 差异

Apple Silicon Mac 上，Homebrew 默认路径通常是：

/opt/homebrew/bin

Intel Mac 上，Homebrew 默认路径通常是：

/usr/local/bin

安装完成后如果遇到 hermes: command not found，优先检查 shell 配置是否加载了 ~/.local/bin，以及当前终端是否重新打开过。

可以执行：

echo $PATH
ls -l ~/.local/bin/hermes

如果 ~/.local/bin/hermes 存在，但命令找不到，通常就是 PATH 没刷新。

4.3 执行安装

运行官方安装命令：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后，如果你使用 zsh：

source ~/.zshrc

然后运行：

hermes setup

初始化时重点关注：

• 选择 LLM Provider
• 配置 API Key
• 选择默认模型
• 配置启用的工具
• 是否启用消息网关

第一次安装后建议立刻跑一次诊断：

hermes doctor

如果缺少依赖、PATH 未生效或配置不完整，hermes doctor 会给出更明确的提示。

4.4 Mac 上的使用建议

Mac 上建议把 Hermes Agent 当作“个人本机助手”使用：

hermes

常用命令包括：

hermes model          # 重新选择模型
hermes tools          # 配置启用哪些工具
hermes config         # 查看配置
hermes config edit    # 编辑配置
hermes doctor         # 检查环境

如果只是本机日常使用，默认 local backend 就够了。但要注意：local backend 代表 Agent 执行命令时拥有和你当前用户一样的文件权限。因此，不要随便让它在本机跑陌生项目里的危险命令。

5 - Ubuntu 24.04 LTS 安装 Hermes Agent

5.1 安装前准备

Ubuntu 24.04 LTS 上建议先更新系统：

sudo apt update
sudo apt upgrade -y

安装基础依赖：

sudo apt install -y curl git build-essential ca-certificates

确认 Git 可用：

git --version

如果这台机器是长期运行的个人服务器，我还建议提前准备：

• SSH
• Tailscale
• Docker
• 独立的普通用户账户
• 稳定的网络和电源
• 定期备份目录
• 若系统盘偏小：提前挂载数据盘（如 /data），安装时设置 HERMES_HOME=/data/hermes

Hermes Agent 不要求这些全部存在，但对于常驻 AI Agent 服务器来说，它们会显著提升可维护性。

5.2 不建议一开始用 root 安装

官方安装文档提到，Hermes Agent 支持普通用户安装和 root-mode 安装。

普通用户安装时：

代码目录：~/.hermes/hermes-agent/
命令位置：~/.local/bin/hermes
数据目录：~/.hermes/

root-mode 安装时：

代码目录：/usr/local/lib/hermes-agent/
命令位置：/usr/local/bin/hermes
数据目录：/root/.hermes/

我更推荐个人用户先用 普通用户安装。原因很简单：

• 权限边界更清晰
• 不容易污染系统目录
• 配置、日志、记忆、会话都在当前用户的 ~/.hermes/
• 后续迁移和备份更方便

除非你明确需要给多用户共享一套系统级 Hermes Agent，否则不要一上来就：

sudo curl ... | sudo bash

更稳妥的做法是新建一个普通用户，例如：

sudo adduser hermes
sudo usermod -aG sudo hermes

然后切换到这个用户下安装：

su - hermes
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

5.3 执行安装和初始化

在 Ubuntu 上运行：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后加载 shell 配置：

source ~/.bashrc

进入初始化向导：

hermes setup

然后执行诊断：

hermes doctor

如果要重新选择模型：

hermes model

如果要配置工具：

hermes tools

如果要配置消息平台：

hermes gateway setup

6 - 配置文件和数据目录

Hermes Agent 的主要数据都在：

~/.hermes/

官方配置文档列出的典型结构如下：

~/.hermes/
├── config.yaml          # 模型、终端后端、TTS、压缩等普通配置
├── .env                 # API Key、Bot Token 等敏感信息
├── auth.json            # OAuth 凭据
├── SOUL.md              # Agent 的默认身份和表达风格
├── hermes-agent/        # 源码 + Python 虚拟环境（venv，体积最大）
├── node/                # 安装器自带的 Node.js 运行时
├── node_modules/        # 浏览器自动化等 npm 依赖
├── memories/            # 长期记忆
├── skills/              # Agent 创建和复用的技能
├── cron/                # 定时任务
├── sessions/            # 消息网关会话（含 state.db，会持续增长）
├── logs/                # 日志
├── image_cache/         # 图片缓存
└── audio_cache/         # 音频缓存

此外，安装器还会在用户主目录下占用一些不在 ~/.hermes/ 内的空间，例如：

~/.cache/ms-playwright/   # Chromium（浏览器工具，约 200–400 MB）
~/.cache/uv/              # uv 包下载缓存
~/.local/share/uv/python/ # uv 管理的 Python 解释器

若启用 Docker backend，镜像与容器数据通常在 /var/lib/docker，也不计入 ~/.hermes/。

这里有一个很重要的原则：

API Key、Bot Token、密码等敏感信息放进 ~/.hermes/.env；模型、终端后端、工具开关等普通配置放进 ~/.hermes/config.yaml。

可以用命令修改配置：

hermes config
hermes config edit
hermes config set KEY VALUE
hermes config check
hermes config migrate

其中 hermes config set 会尽量把配置写到正确的位置：敏感信息写入 .env，普通配置写入 config.yaml。

6.1 将数据目录迁移到大容量磁盘（/data）

个人服务器常见布局是：系统盘较小（几十 GB），数据盘挂载在 /data。Hermes Agent 安装后很容易占满系统盘——尤其是 hermes-agent/venv、Playwright 的 Chromium、以及长期运行的 sessions/ 和 logs/。

官方支持通过环境变量 HERMES_HOME 指定数据根目录；安装脚本也支持 --hermes-home。推荐把整个 Hermes 数据目录迁到 /data，而不是只拆某几个子目录。

哪些占用空间大

config.yaml、.env、memories/、skills/ 等配置文件和文本数据一般不大，随 HERMES_HOME 一起迁移即可。

推荐做法：整包迁到 /data

新安装（尚未执行过安装脚本）：

sudo mkdir -p /data/hermes
sudo chown "$USER:$USER" /data/hermes

export HERMES_HOME=/data/hermes
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --hermes-home /data/hermes

安装完成后，在 ~/.bashrc（若用 zsh 则 ~/.zshrc）中固定：

export HERMES_HOME=/data/hermes

已安装（从默认的 ~/.hermes 迁出）：

# 1. 先停止网关（若在运行）
hermes gateway stop

# 2. 迁移目录（将 hermes 换成你的实际用户名）
mv ~/.hermes /data/hermes

# 3. 建立软链接，兼容少数仍写死 ~/.hermes 的代码路径
ln -s /data/hermes ~/.hermes

# 4. 写入环境变量
echo 'export HERMES_HOME=/data/hermes' >> ~/.bashrc
source ~/.bashrc

# 5. 若 gateway 以 systemd 运行，需确保服务也带上 HERMES_HOME
#    可重新执行 hermes gateway install，或手动编辑 unit 后 daemon-reload
hermes gateway install
hermes gateway start
hermes doctor

~/.local/bin/hermes 只是启动器，体积很小，可继续留在系统盘。

可单独迁到 /data 的相关缓存

若系统盘仍紧张，下列目录不在 HERMES_HOME 内，可额外指向 /data（写入 shell 配置，并确保 gateway 的 systemd 服务同样继承这些变量）：

# uv 缓存
export UV_CACHE_DIR=/data/cache/uv

# Playwright Chromium
export PLAYWRIGHT_BROWSERS_PATH=/data/playwright
# 迁移后在新路径执行一次：npx playwright install chromium

# Docker（若大量使用 docker backend）
# 在 /etc/docker/daemon.json 中设置 "data-root": "/data/docker"

不需要浏览器工具时可省空间

若不需要浏览器自动化，安装时可跳过 Chromium：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-browser --hermes-home /data/hermes

迁移前检查占用

du -sh ~/.hermes ~/.hermes/*/ ~/.cache/ms-playwright ~/.cache/uv ~/.local/share/uv 2>/dev/null
docker system df   # 若使用 docker backend

Ubuntu 常驻服务器推荐布局：

系统盘：Ubuntu + ~/.local/bin/hermes
数据盘 /data/hermes：HERMES_HOME（配置、记忆、venv、会话、日志）
数据盘 /data/docker：Docker 镜像与容器（可选）

7 - 选择合适的 Terminal Backend

Hermes Agent 执行命令时，需要选择命令到底在哪里运行。官方文档把这个能力称为 terminal backend。

常见选择如下：

7.1 本机开发：local

默认就是 local。

terminal:
  backend: local

这最方便，但也最需要谨慎。因为 Agent 拥有当前用户的文件访问权限。

7.2 陌生项目：Docker

如果你经常让 Agent 分析未知仓库、执行依赖安装、跑脚本，建议优先使用 Docker backend。

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: false
  docker_run_as_host_user: false
  container_cpu: 1
  container_memory: 5120
  container_persistent: true

Docker backend 的好处是隔离更强。官方文档提到，它会使用容器 namespace、cap-drop、no-new-privileges、PID 限制、tmpfs 限制等安全加固。对于个人服务器来说，这是非常值得开启的能力。

需要注意的是：Docker backend 默认会复用一个长生命周期容器。同一个 Hermes 进程里的多个会话或子任务可能共享容器状态，所以并行任务写同一路径时仍然可能互相影响。

7.3 远程机器：SSH

如果你的 Hermes Agent 跑在 Mac 上，但希望命令实际在 Ubuntu 服务器上执行，可以考虑 SSH backend。

典型配置需要设置远程主机和用户：

TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu

这适合把 Mac 当入口，把 Ubuntu 当执行环境。

不过如果你的目标是长期自动化，我更建议直接把 Hermes Agent 安装在 Ubuntu 服务器上，减少中间层。

8 - 安全最佳实践

Hermes Agent 很强，但越强的 Agent 越需要边界。尤其是它能执行命令、访问文件、连接消息平台、运行定时任务时，安全配置不能省。

8.1 不要轻易开启 YOLO 模式

Hermes Agent 有危险命令审批机制。遇到递归删除、格式化磁盘、危险 SQL、写系统目录等操作时，会要求用户确认。

官方也支持 --yolo 或 /yolo 这类跳过审批的模式，但我不建议在个人主机或服务器上长期使用。

只有在下面两种情况下才考虑：

• 一次性、可丢弃的 Docker 容器
• 非常可信、经过测试的自动化环境

8.2 陌生代码优先放进 Docker

如果 Agent 要处理陌生仓库，不要直接在宿主机 local backend 下运行：

npm install
python setup.py
bash install.sh

这些命令都有供应链风险。更好的做法是切到 Docker backend，让破坏范围限制在容器内。

8.3 消息机器人必须配置 allowlist

Hermes Agent 支持 Telegram、Discord、Slack、飞书、企业微信、微信、钉钉等消息网关。这个能力很实用，但也很危险：如果别人能给你的 bot 发消息，就可能间接控制你的 Agent。

所以不要设置：

GATEWAY_ALLOW_ALL_USERS=true

更推荐配置明确的用户 allowlist：

TELEGRAM_ALLOWED_USERS=123456789
DISCORD_ALLOWED_USERS=123456789012345678
FEISHU_ALLOWED_USERS=ou_xxxxxxxx
WECOM_ALLOWED_USERS=user-id-1,user-id-2
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2
GATEWAY_ALLOWED_USERS=123456789

如果你要给家人、朋友或团队成员使用，可以考虑官方提供的 DM pairing 机制，由你手动批准。

8.4 API Key 不要写进项目目录

API Key 应放在：

~/.hermes/.env

不要写进项目里的 .env、README 或脚本，也不要提交到 Git。

8.5 定期检查配置

升级后建议执行：

hermes config check
hermes config migrate
hermes doctor

这可以检查配置缺失、迁移旧配置，并排查环境问题。

9 - 中国大陆地区消息入口怎么选

Hermes Agent 的消息网关支持很多平台。对中国大陆用户来说，最常见的选择不是 Telegram 或 Discord，而是 飞书、企业微信、微信、钉钉。

我的建议是：

个人或小团队优先：飞书
企业办公环境优先：企业微信
只想接入个人微信：可以尝试 Weixin，但不要依赖微信群
已有钉钉组织：再考虑钉钉

如果只能选一个，我更推荐 飞书。它的机器人能力更完整，官方文档里 Feishu/Lark 支持语音、图片、文件、线程、reaction、typing indicator 和 streaming；连接方式也推荐 WebSocket，不需要你准备公网域名或反向代理。

9.1 飞书：大陆地区最推荐

飞书适合个人、家庭小团队、创业团队和知识管理场景。它的优势是：

• 国内访问稳定
• Bot 能力比较完整
• 支持私聊和群聊
• 群聊里默认需要 @ 机器人，误触发少
• WebSocket 模式不需要公网回调地址
• 可以作为 cron 定时任务的 home chat

最简单的配置方式是：

hermes gateway setup

然后选择 Feishu / Lark，按提示用飞书手机端扫码或手动填写应用信息。

如果手动配置，核心变量大致是：

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx

这里有几个关键点：

• FEISHU_DOMAIN=feishu 表示使用中国大陆飞书；国际版 Lark 才用 lark。
• FEISHU_CONNECTION_MODE=websocket 是更推荐的方式，不需要公网 URL。
• FEISHU_ALLOWED_USERS 建议一定配置，避免任何能接触到 bot 的人都能使用 Agent。
• 群聊中默认只有 @ 到机器人时才会触发，适合放在日常群里。

添加其他飞书用户

Hermes 默认不会对所有人开放，需要把对方的 飞书 open_id（形如 ou_xxx）加入白名单。

方式一：编辑 allowlist（最常用）

在 ~/.hermes/.env（若设置了 HERMES_HOME 则在其下的 .env）中追加，多个 ID 用英文逗号分隔：

FEISHU_ALLOWED_USERS=ou_你的id,ou_同事A,ou_同事B

或用命令写入（会自动落到 .env）：

hermes config set FEISHU_ALLOWED_USERS ou_xxx,ou_yyy,ou_zzz

修改后需重启 gateway。若使用系统级 systemd 服务：

sudo hermes gateway restart --system

如何获取对方的 open_id

• 让对方先给机器人发私聊；在网关日志 ~/.hermes/logs/ 或 journalctl -u hermes-gateway -f 中查看 sender 信息。
• 在已授权的会话里发送 /whoami，Hermes 会返回当前用户标识。

群聊说明

• 私聊：发送者须在 FEISHU_ALLOWED_USERS 中。
• 群聊：一般需 @ 机器人；且当 FEISHU_GROUP_POLICY=allowlist（默认）时，发送者也须在白名单内。

更细的「按群、按人」规则可在 config.yaml 的 platforms.feishu.extra.group_rules 中配置，参见官方 Feishu / Lark 文档。

方式二：DM Pairing（免手填 ID）

适合家人或小团队：对方私聊机器人会收到配对码，你在服务器上批准：

hermes pairing list
hermes pairing approve feishu XKGH5N7P   # 以实际显示的配对码为准

详见 Messaging Gateway - DM Pairing。若 approve feishu 报错，可执行 hermes pairing --help 查看当前版本支持的平台名。

修改飞书应用与机器人显示名称

这不在 Hermes 里配置，需在 飞书开放平台 修改：

1. 打开 飞书开放平台（国际版用 Lark）。
2. 进入对应应用 → 凭证与基础信息 / 应用信息 → 修改应用名称。
3. 用户侧看到的机器人名称、头像、描述等，在 应用能力 → 机器人 相关页面中设置（以控制台当前菜单为准）。

环境变量 FEISHU_BOT_NAME 仅用于 Hermes 在自动识别失败时辅助 @ 提及检测，不会改变飞书客户端里显示的机器人名称。

配置完成后启动网关：

hermes gateway

若希望网关在 Ubuntu 上开机自启、SSH 断开后仍运行，不要只用默认的 hermes gateway install（用户级服务），而应使用 10.3 节 的 system 级安装。macOS 仍用 launchd：

hermes gateway install
hermes gateway start
hermes gateway status

9.2 企业微信：适合公司和正式团队

企业微信适合已经在企业微信里办公的团队，尤其是需要组织架构、成员权限和企业内部群的场景。

Hermes Agent 的 WeCom adapter 使用企业微信 AI Bot WebSocket 网关，优点是：

• 不需要公网 webhook
• 支持私聊和群聊
• 支持图片、文件、语音、视频等媒体
• 可以配置 DM 和群聊访问策略
• 可以做更细的 per-group sender allowlist

推荐配置方式仍然是：

hermes gateway setup

选择 WeCom 后，可以扫码创建 Bot，或者手动在企业微信管理后台创建 AI Bot。

手动配置时核心变量是：

WECOM_BOT_ID=your-bot-id
WECOM_SECRET=your-secret
WECOM_ALLOWED_USERS=user_id_1,user_id_2
WECOM_HOME_CHANNEL=chat_id

如果要限制群聊：

WECOM_DM_POLICY=allowlist
WECOM_GROUP_POLICY=allowlist

企业微信更适合“正式组织内的 AI 助手”，而不是个人随手用。它的权限体系更重，但长期运行会更可控。

9.3 个人微信：能用，但不建议作为主入口

Hermes Agent 也支持 Weixin，也就是个人微信。它通过腾讯 iLink Bot API 接入，使用二维码登录，消息通过 long-polling 获取，所以不需要公网 webhook。

配置方式：

hermes gateway setup

选择 Weixin，然后用微信扫码登录。

初始化后，通常会在 ~/.hermes/.env 里保存或需要配置类似变量：

WEIXIN_ACCOUNT_ID=your-account-id
WEIXIN_DM_POLICY=allowlist
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2
WEIXIN_HOME_CHANNEL=chat_id

个人微信接入最大的优点是：微信是国内最常用的 IM，手机上随时可用。

但它的问题也很明确：官方文档说明 QR 登录连接的是 iLink bot identity，不是一个完全可脚本化的普通个人微信号。因此：

• 多数情况下私聊 DM 更可靠
• 普通微信群不一定能正常收到事件
• @ 扫码登录的个人微信号，不等于 @ iLink bot
• 群消息是否能到达 Hermes，取决于 iLink 是否返回事件

所以我不建议把个人微信作为主要生产入口。它适合作为“给自己发消息”的轻量入口，不适合作为团队群机器人。

9.4 钉钉：已有钉钉组织时再选

Hermes Agent 也支持 DingTalk。钉钉在企业和学校里仍然常见，但如果你没有现成钉钉组织，我不建议为了 Hermes Agent 专门迁移过去。

选择钉钉的理由通常是：

• 公司或学校已经用钉钉
• 组织权限和通知都在钉钉里
• 你希望 Hermes Agent 进入现有办公群

如果是从零开始搭个人 AI 助手，飞书通常更顺手。

9.5 我的最终建议

如果你的目标是“中国大陆地区可长期使用的个人 AI Agent”，我建议这样选：

我的实际部署会选：

Ubuntu 24.04 LTS 常驻服务器
+ Hermes Agent
+ Docker backend
+ 飞书 WebSocket Gateway
+ FEISHU_ALLOWED_USERS allowlist
+ /sethome 接收定时任务结果
+ Tailscale / SSH 远程维护

这样既符合国内网络环境，又不用暴露公网 webhook，也方便以后把日报、监控、备份、提醒等任务都交给 Agent。

10 - 我的推荐部署方式

10.1 Mac 推荐方案

Mac 上推荐：

普通用户安装
+ local backend
+ CLI 使用为主
+ 少量本机自动化
+ 需要处理陌生代码时临时切 Docker backend

适合的使用方式：

hermes
hermes -c
hermes model
hermes tools

Mac 上不要追求 7x24 小时运行，把它当作日常工作台即可。

10.2 Ubuntu 24.04 LTS 推荐方案

Ubuntu 服务器上推荐：

普通用户 hermes 安装
+ HERMES_HOME=/data/hermes（系统盘小时；否则默认 ~/.hermes）
+ Docker backend 处理陌生代码（Docker data-root 也可放 /data）
+ Tailscale / SSH 远程维护
+ gateway 接飞书 / 企业微信 / Telegram / Discord
+ sudo hermes gateway install --system --run-as-user <用户>（开机自启）
+ allowlist 限制用户
+ cron 做定时任务
+ 定期备份 $HERMES_HOME（或 ~/.hermes）

如果这台机器是家里的旧笔记本或迷你主机，可以把它定位成：

个人 AI 自动化服务器
= Ubuntu 24.04 LTS
+ Docker
+ SSH
+ Tailscale
+ Hermes Agent
+ n8n / 其他自动化工具

Hermes Agent 负责自然语言入口、记忆、工具调用和任务拆解；Docker 负责隔离执行；Tailscale 负责安全远程访问；n8n 负责传统工作流编排。这样比把所有事情都堆给一个工具更稳定。

10.3 Ubuntu 上 Gateway 的 systemd 服务

在 Ubuntu 常驻服务器上，消息网关需要 7×24 运行。Hermes 支持两种 Linux systemd 安装方式：

个人 VPS / 无头服务器推荐系统级，仍以普通用户身份跑进程（配置、.env 仍在该用户的 ~/.hermes 或 HERMES_HOME 下）：

sudo /home/terry/.local/bin/hermes gateway install --system --run-as-user terry
sudo hermes gateway start --system
sudo hermes gateway status --system
# install 通常已执行 systemctl enable；若需手动：sudo systemctl enable hermes-gateway

说明：

• --run-as-user terry 表示 systemd 以用户 terry 运行 gateway，不是以 root 跑 Agent；FEISHU_* 等配置仍读取 /home/terry/.hermes/（或该用户的 HERMES_HOME）。
• 系统级服务一般不需要 sudo loginctl enable-linger（那是用户级服务在 SSH 断开后可能退出时才需要）。
• 日常 start / stop / restart / status 须带 sudo 与 --system，否则会操作到用户级服务或报未安装。

重启后是否自动运行

install --system 会 enable 单元并设置 WantedBy=multi-user.target，重启后 systemd 应自动拉起 gateway。验证：

systemctl is-enabled hermes-gateway
sudo hermes gateway status --system
sudo journalctl -u hermes-gateway -f

若数据目录已迁到 /data/hermes，须先为 terry 配置好 HERMES_HOME，再重新执行一次 gateway install --system --run-as-user terry，否则 unit 里可能仍指向旧的 ~/.hermes（见 6.1 节）。

不要同时保留两套服务

若既装过 hermes gateway install（无 --system），又装了 --system，两个 unit 可能同时存在，会导致 start/stop 行为混乱，甚至争抢同一飞书 app_id。判断与清理见 11.10 节。

11 - 常见问题

11.1 hermes: command not found

先重新打开终端，或者执行：

source ~/.bashrc

zsh 用户执行：

source ~/.zshrc

再检查：

ls -l ~/.local/bin/hermes
echo $PATH

如果 ~/.local/bin/hermes 存在但命令不可用，基本就是 PATH 没包含 ~/.local/bin。

11.2 API key not set

执行：

hermes model

或者通过配置命令写入：

hermes config set OPENROUTER_API_KEY your_key

也可以重新运行完整向导：

hermes setup

若使用 DeepSeek 且 hermes doctor 仍提示 Check DEEPSEEK_API_KEY in .env，见 11.11 节。

11.3 Ubuntu 缺少 Git

执行：

sudo apt update
sudo apt install -y git
git --version

11.4 安装脚本执行很慢

安装器需要下载依赖、克隆仓库、安装 Python 和 Node.js 相关组件。国内网络环境下可能会慢。

建议：

• 确认 GitHub 访问稳定
• 不要中途关闭终端
• 如果失败，先看报错，不要反复盲目重跑
• 安装完成后用 hermes doctor 定位问题

11.5 Mac 上 Docker backend 找不到 docker

先确认 Docker Desktop 已安装并正在运行：

docker version

Apple Silicon Mac 上如果 PATH 没包含 Docker 命令路径，也可能导致 Hermes Agent 找不到 Docker。先在普通终端里确认 docker version 正常，再回到 Hermes Agent 配置。

11.6 消息网关无法使用

先执行：

hermes gateway setup

然后检查：

• Bot Token 是否正确
• allowlist 是否配置
• 当前用户 ID 是否在 allowlist 内
• 服务器是否能访问对应平台
• ~/.hermes/logs/ 下是否有错误日志

11.7 飞书机器人不响应

先确认网关在运行（若用系统级服务须加 --system）：

hermes gateway status
# 或
sudo hermes gateway status --system

如果是前台运行，则看当前终端日志：

hermes gateway

然后检查：

• FEISHU_DOMAIN 是否设置为 feishu
• FEISHU_CONNECTION_MODE 是否为 websocket
• FEISHU_APP_ID 和 FEISHU_APP_SECRET 是否正确
• 当前发送者的 open_id 是否在 FEISHU_ALLOWED_USERS
• 群聊里是否 @ 了机器人

11.8 微信群里 @ 机器人没反应

这不一定是 Hermes Agent 配置问题。个人微信适配器使用 iLink bot identity，官方文档说明普通微信群事件经常不会投递给这个 bot identity。

如果私聊可用、群聊不可用，优先判断为 iLink 侧限制。更稳定的方案是改用飞书或企业微信。

11.9 系统盘空间不足 / Hermes 占满磁盘

先用 du 确认占用（见 6.1 节），再按是否已安装选择：

• 未安装：--hermes-home /data/hermes 安装，并 export HERMES_HOME=/data/hermes
• 已安装：停 gateway → mv ~/.hermes /data/hermes → ln -s /data/hermes ~/.hermes → 写入 shell 与 systemd 的 HERMES_HOME

Playwright、uv 缓存、Docker 镜像可额外迁到 /data（见 6.1 节「可单独迁到 /data 的相关缓存」）。不需要浏览器工具时，重装可加 --skip-browser。

11.10 如何判断是否装过用户级 gateway

若曾执行过 hermes gateway install（无 --system），会在用户目录留下 systemd 单元；与 install --system 并存时可能冲突。

检查单元文件是否存在

# 用户级（无 --system 时生成）
ls -l ~/.config/systemd/user/hermes-gateway*.service 2>/dev/null

# 系统级（--system 时生成）
sudo ls -l /etc/systemd/system/hermes-gateway*.service 2>/dev/null

用 Hermes / systemctl 辅助判断

hermes gateway status
sudo hermes gateway status --system
systemctl --user list-unit-files 'hermes-gateway*' 2>/dev/null
systemctl list-unit-files 'hermes-gateway*' 2>/dev/null

若同时存在 user 与 system 单元，hermes gateway status 可能提示 Both user and system gateway services are installed。

只保留系统级时的清理（在对应 Linux 用户下）

hermes gateway stop
hermes gateway uninstall

系统级服务继续用 sudo hermes gateway … --system 管理，勿卸载 system 单元。

11.11 hermes doctor 与 DeepSeek 配置

按 DeepSeek 官方 Hermes 接入说明 完成 hermes setup 后，若 hermes doctor 摘要仍出现例如：

1. Check DEEPSEEK_API_KEY in .env
2. Run 'hermes setup' to configure missing API keys for full tool access

两条提示含义不同：

核对 DeepSeek 密钥

• 必须写在 ~/.hermes/.env（或 HERMES_HOME 对应目录），变量名 exactly：DEEPSEEK_API_KEY=sk-...
• 勿只写在项目目录 .env；注意值两侧不要多余引号或空格
• 推荐：hermes config set DEEPSEEK_API_KEY sk-你的密钥

独立验证密钥（与 doctor 相同接口）

curl -sS -o /tmp/ds_models.json -w "%{http_code}\n" \
  -H "Authorization: Bearer 你的KEY" \
  "https://api.deepseek.com/v1/models"

返回 200 表示密钥有效；401 请到 DeepSeek API Keys 重新创建。

看完整 doctor 输出

hermes doctor

在 ◆ API Connectivity 中查看 DeepSeek 一行（invalid API key / HTTP 状态）；在 ◆ Tool Availability 中查看带 missing XXX_API_KEY 的工具，对应第二条摘要。

12 - 参考命令速查

安装：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装到数据盘 /data（Ubuntu 常驻服务器推荐）：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --hermes-home /data/hermes

初始化：

hermes setup

启动聊天：

hermes

继续上次会话：

hermes -c

选择模型：

hermes model

配置工具：

hermes tools

配置消息平台：

hermes gateway setup

Gateway 系统级服务（Ubuntu 常驻，用户 terry 示例）：

sudo hermes gateway install --system --run-as-user terry
sudo hermes gateway start --system
sudo hermes gateway status --system
sudo journalctl -u hermes-gateway -f

飞书用户白名单：

hermes config set FEISHU_ALLOWED_USERS ou_xxx,ou_yyy

查看配置：

hermes config

编辑配置：

hermes config edit

检查环境：

hermes doctor

检查配置：

hermes config check

迁移配置：

hermes config migrate

13 - 总结

如果你只是想快速体验 Hermes Agent，Mac 上一行命令安装，然后 hermes setup 就能开始。

如果你希望把它变成真正可用的个人 AI 自动化服务器，我更推荐 Ubuntu 24.04 LTS：

Ubuntu 24.04 LTS
+ 普通用户安装 Hermes Agent
+ HERMES_HOME 放 /data（系统盘较小时）
+ Docker backend 做隔离
+ Tailscale / SSH 做远程访问
+ Gateway 接飞书 / 企业微信
+ sudo hermes gateway install --system --run-as-user <用户>（开机自启）
+ Allowlist 控制访问权限
+ 定期备份 $HERMES_HOME

Hermes Agent 最值得关注的地方，不是“又多了一个 AI 聊天工具”，而是它把 长期记忆、技能沉淀、工具调用、消息入口、定时任务和沙箱执行 放到了一套系统里。

对个人来说，这更像是一个可以长期培养的 AI 助手；对服务器来说，它则是一个自然语言驱动的自动化入口。

参考资料

• Hermes Agent 官网
• Hermes Agent Documentation
• Installation Guide
• Configuration
• Security
• Messaging Gateway
• Feishu / Lark
• DeepSeek 接入 Hermes
• Tips & Best Practices
• NousResearch/Hermes-Agent GitHub 仓库

最后修改于 2026-05-12