乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > Hermes Agent 安装部署文档(亲测可用)

Hermes Agent 安装部署文档(亲测可用)

当前时间： 2026-05-14 12:47:38 更新时间： 2026-05-14 分类：软件教程 评论(0)

Hermes Agent 安装部署文档(亲测可用)

Hermes Agent 安装部署文档

前言：为什么选择原生开源而非套壳产品

如果你正在阅读这份文档，说明你已经意识到一个残酷的事实：市面上绝大多数所谓的”AI 智能体产品”，本质上就是套壳——在别人的模型 API 外面包一层简陋的 Web UI，加个花哨的定价页面，然后就敢自称”下一代 AI 平台”。他们做的最多的事情是在 GitHub 上 fork 开源项目改个 logo，唯一真正的”创新”是研究怎么把订阅费定得更高。

选择 Hermes Agent 这类原生开源项目的意义在于：

●你拥有你的数据。套壳产品的聊天记录存在别人的服务器上，你不知道它拿去训练了什么，也不知道什么时候会”因合规要求”被审查。Hermes 的所有会话、记忆、配置都在 ~/.hermes/ 下，是你的本地资产。

●你拥有你的模型选择权。套壳产品给你一张固定的模型列表，选什么由他们的商务合同决定。Hermes 支持 100+ 提供商，从 DeepSeek、OpenRouter 到你自己的本地 Ollama/VLLM 端点，切换模型只需 hermes model 一条命令。没有任何人替你”精选”。

●你拥有你的工具链。套壳产品给你几个预设工具就号称”生态”，而 Hermes 原生支持 Docker 沙箱终端、文件系统操作、网页搜索、代码执行、消息网关、定时任务、技能系统——这些不是”即将上线”的饼，是开箱即用的功能。

●你拥有扩展能力。套壳产品等你反馈需求然后排期到下个季度；开源项目你可以直接改源码，PR 可能 24 小时内就被合并。你的需求不需要经过产品经理的优先级评审。

●价格透明且可控。套壳产品的定价里，模型成本可能只占 30%，剩下的 70% 是他们的”平台溢价”和获客成本。自己对接 API，成本至少降低一个数量级。

当然，代价是你要亲手部署。这就是这份文档存在的意义——把安装过程从”劝退”变成”照做就行”。

概述

本文档记录了在 macOS (Apple Silicon) 上部署 Hermes Agent v0.13.0 的完整步骤，采用 本地运行 + Docker 终端沙箱 的安全隔离模式。

一、系统环境

项目

要求 / 已验证版本

操作系统

macOS (arm64) — 理论上 Intel Mac / Linux / WSL2 也可用

Shell

zsh（macOS 默认）

Git

2.50.1+

Docker

Orbstack 或 Docker Desktop（任选其一）

Python

3.11（通过 uv 自动管理，无需手动安装）

Node.js

22+（可选，浏览器工具需要）

⚠️ 避坑：不要试图在 Windows 原生环境安装，Hermes 官方明确不支持。请使用 WSL2。如果你正在用 Windows，建议立刻装 WSL2，不要在 PowerShell 上浪费时间。

二、准备工作

2.1 下载源码包

方式一（推荐）：从 GitHub 下载 release zip 包

# 如果遇到网络问题，浏览器下载后传到机器上也行

方式二：使用国内镜像克隆（如果 git clone 太慢）

mkdir -p ~/.hermesgit clone https://ghproxy.net/https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent

⚠️ 避坑：不要直接用 git clone git@github.com:NousResearch/hermes-agent.git——SSH 方式在国内网络环境下极易超时。也不要尝试 git clone –depth 1 来偷懒，因为 Hermes 的初始化脚本依赖完整的 git 历史来做版本检测。

⚠️ 避坑：安装脚本 curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash 在国内大概率跑不通——它会先尝试 SSH 克隆，失败后可能不会优雅回退，导致安装卡死。而且安装过程中需要从 PyPI 和 npm 下载大量依赖，直接跑脚本等于裸奔无代理，超时断连是家常便饭。手动安装是唯一可靠的路径。

2.2 检查必备工具

# Git（必备）git --version# uv（Python 包管理器，如未安装会自动安装）curl -LsSf https://astral.sh/uv/install.sh | sh# Docker / Orbstack（可选，用于终端沙箱）docker --version# Node.js（可选，用于浏览器工具）node --version# ffmpeg（可选，用于语音功能）ffmpeg --version

⚠️ 避坑：uv 安装后不会自动添加到 PATH，需要手动执行 source ~/.zshrc 或将 ~/.local/bin 加入 PATH。如果你运行 uv –version 报错，不要慌，这是正常现象。

三、安装步骤

3.1 解压 / 放置代码

# 如果是从 zip 解压unzip hermes-agent-main.zip -d /tmp/cp -r /tmp/hermes-agent-main ~/.hermes/hermes-agent# 验证ls ~/.hermes/hermes-agent/ | head -10

⚠️ 避坑：不要用 mv 替代 cp -r——某些文件系统跨分区 mv 会导致文件权限错乱。更不要尝试 unzip -d ~/.hermes/hermes-agent，zip 内层还有一个 hermes-agent-main/ 目录，直接解压会多一层嵌套。

3.2 创建虚拟环境并安装依赖

cd ~/.hermes/hermes-agent# 创建虚拟环境（使用 uv）uv venv .venv --python 3.11# 激活虚拟环境source .venv/bin/activate# ---------- 关键步骤：安装锁定依赖 ----------# uv sync --frozen 会按照 uv.lock 文件精确安装每个依赖的指定版本# 这比 pip install -e ".[all]" 快得多，且版本完全可控# 如果这里报错，90% 是网络问题uv sync --frozen# 安装本项目（editable 模式，不重复装依赖）uv pip install --quiet --no-deps -e .

⚠️ 避坑：不要执行 pip install -e “.[all]”——[all] 会安装所有可选依赖（包括 Telegram bot、Discord bot、语音、浏览器等），数量巨大且很多在国内网络下无法下载。uv sync –frozen 只安装核心依赖，后续按需补充即可。

⚠️ 避坑：如果 uv sync –frozen 因为网络超时失败，可以尝试设置代理：

export HTTP_PROXY=http://127.0.0.1:7890export HTTPS_PROXY=http://127.0.0.1:7890uv sync --frozen

或者指定国内镜像源（但 uv.lock 锁定依赖，改源可能版本不匹配）：

uv sync --frozen --index-url https://pypi.tuna.tsinghua.edu.cn/simple

⚠️ 避坑：确保当前目录是 ~/.hermes/hermes-agent/，且 uv.lock 文件存在。如果从 zip 解压时漏了 uv.lock，uv sync –frozen 会报错——因为 frozen 模式要求 lock 文件存在且与 pyproject.toml 一致。

3.3 注册 hermes 命令

⚠️ 此步骤极其容易踩坑，请仔细阅读

mkdir -p ~/.local/bin# ✅ 正确方式：链接到 venv 下的 entry point（推荐）ln -sf ~/.hermes/hermes-agent/.venv/bin/hermes ~/.local/bin/hermes# ❌ 错误方式：链接到项目根目录的 hermes（脚本）# ln -sf ~/.hermes/hermes-agent/hermes ~/.local/bin/hermes# 这个 hermes 脚本的 shebang 可能指向系统 Python，导致找不到虚拟环境中的依赖

⚠️ 避坑：项目根目录下有两个 hermes：

●~/.hermes/hermes-agent/hermes → 一个 Python 脚本，shebang 写的是 #!/usr/bin/env python3，运行时用的是系统 Python，而不是虚拟环境里的 Python。如果直接链这个，你会遇到 ModuleNotFoundError: No module named ‘dotenv’。

●~/.hermes/hermes-agent/.venv/bin/hermes → pip 安装时自动生成的 entry point，其 Python 解释器路径指向虚拟环境内部，所有依赖都能正确找到。必须链这个。

如果已经链错了，请先删除再重建：

rm -f ~/.local/bin/hermesln -sf ~/.hermes/hermes-agent/.venv/bin/hermes ~/.local/bin/hermes

3.4 加入 PATH

# 检查是否已存在grep '\.local/bin' ~/.zshrc || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc# 立即生效source ~/.zshrc

⚠️ 避坑：如果你用的是 bash 而不是 zsh（macOS 从 Catalina 起默认 zsh，但如果升级过系统可能残留），请改为编辑 ~/.bash_profile 或 ~/.bashrc。不确定？执行 echo $SHELL 确认。

3.5 验证安装

hermes --version

⚠️ 预期输出：Hermes Agent v0.13.0 (2026.5.7)。如果没有这个输出：

●command not found → PATH 没生效，执行 source ~/.zshrc 或直接 export PATH=”$HOME/.local/bin:$PATH”

●ModuleNotFoundError → 链错了文件，参考 3.3 的避坑说明重新链

●Segmentation fault → Python 版本冲突，执行 uv python install 3.11 强制使用 3.11

四、配置 LLM 模型提供商

4.1 配置 API Key

编辑 ~/.hermes/.env，添加对应 API Key：

# DeepSeek（推荐入门，性价比高）echo 'DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.hermes/.env# OpenRouter（200+ 模型，一个 Key 通吃）echo 'OPENROUTER_API_KEY="sk-or-xxxxxxxxxxxxxxxx"' >> ~/.hermes/.env# OpenAIecho 'OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"' >> ~/.hermes/.env

⚠️ 避坑：~/.hermes/.env 文件不是标准的 shell 环境文件——Hermes 用自己的 dotenv 加载器解析它。这意味着：

●引号写不写都行（KEY=value 和 KEY=”value” 等价）

●但不要在值里加多余的空格：KEY = value 会报错

●不要用 export 前缀：export KEY=value 会被 Hermes 忽略

●不要把 Key 写进 ~/.zshrc——那是 shell 的配置，Hermes 不读

修改 .env 后不需要重启——Hermes 每次启动都会重新加载。但是如果正在运行中的会话已经读取了旧值，你需要 /reset 或重启会话。

4.2 配置默认模型

# 方法一：使用交互式配置（推荐，会列出所有可用模型）hermes model# 方法二：直接写入配置（如果已经知道模型名）hermes config set provider deepseekhermes config set model deepseek/deepseek-v4-flash

⚠️ 避坑：模型名格式是 provider/model-name，中间是斜杠不是空格。常见的错误：

●deepseek-chat → ❌ 缺少 provider 前缀

●deepseek deepseek-chat → ❌ 空格分隔，config 会解析为两个参数

●deepseek/deepseek-chat → ⚠️ 旧模型名，DeepSeek 已升级到 v4 系列

执行 hermes model 交互式选择是最保险的方式，它会自动帮你拼接正确的格式。

4.3 验证 API 连通性

hermes doctor | grep "API Connectivity"# 成功输出: ✓ DeepSeek

或者直接 curl 测试（不依赖 Hermes）——当不知道怎么排查问题时可以回到这个命令：

curl -s https://api.deepseek.com/v1/models \  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"

⚠️ 避坑：hermes doctor 报告 DeepSeek 连通性为 ✓ 只代表 API Key 有效，不代表模型一定能用。如果启动聊天后报错，可能是模型名不对或上下文窗口不足。Hermes 要求模型至少 64K tokens，DeepSeek v4 系列满足这个要求，但如果切到其他模型务必确认这一点。

五、配置 Docker 终端沙箱（可选但强烈推荐）

5.1 检查 / 启动 Docker

docker info

⚠️ 避坑：macOS 上的 Docker 有两种主流方案：

●Docker Desktop：官方方案，但内存占用高（常驻 2-3GB），商业使用需要付费许可证

●Orbstack：社区推荐，轻量（~200MB），免费，兼容 docker CLI

如果你用 orb 命令而非 docker 命令，检查是否有 Orbstack：

ls ~/.orbstack/ 2>/dev/null && echo "Orbstack installed" || echo "Not Orbstack"

如果你看到错误 “dial unix /Users/xxx/.orbstack/run/docker.sock”，说明你的机器装的是 Orbstack 但没有启动。执行 open -a Orbstack 启动即可。

5.2 配置终端后端

hermes config set terminal.backend docker

查看最终配置：

cat ~/.hermes/config.yaml# 应该看到:# terminal:#   backend: docker# model: deepseek/deepseek-v4-flash# provider: deepseek

⚠️ 避坑：配置 Docker 后端后，Hermes 执行的每条终端命令都会在 Docker 容器中运行。好处是：

●隔离了主机环境——Agent 不能 rm -rf / 你的电脑

●一致的运行时环境——不管在 macOS 还是 Linux 上，容器内都是 Debian

坏处是：

●每条命令都要等容器启动（首次启动约 3-5 秒，后续复用）

●容器内没有你的环境变量、别名、工具链——Agent 可能需要 apt install

●如果 Docker 没运行，所有终端工具都会静默失败，Agent 不会给你报错提示

5.3 临时切换回本地终端

hermes config set terminal.backend local

⚠️ 避坑：切回本地终端后，Agent 的终端命令将直接在你的 shell 中执行。这意味着：

●Agent 可以看到你的环境变量（包括 API Key）

●Agent 可以访问你电脑上的所有文件

●Agent 可以执行破坏性操作（rm -rf、sudo 等）

Docker 不是性能优化，是安全隔离。 如果只是为了跑得快而切 local，请意识到你在用安全性换便利性。

六、启动与使用

6.1 启动方式

# 经典 CLI 模式（最稳定，ssh 远程也能用）hermes# 现代 TUI 模式（推荐，支持鼠标操作、分屏视图）hermes --tui# 恢复上次会话hermes -c# 带初始提示词启动hermes -z "你好，请先扫描我的项目结构并做自我介绍"

⚠️ 避坑：第一次启动需要下载一些运行时依赖（如 TUI 的 Node.js 组件），启动可能较慢。以后启动会快很多。如果你看到 Installing TUI dependencies… 卡了很久，检查网络环境——它在 npm install。

⚠️ 避坑：在 Trae、Cursor、VS Code 的内置终端中运行 TUI 可能出问题（例如 –expose-gc is not allowed in NODE_OPTIONS），这是 IDE 环境变量注入导致的。在系统原生终端（Terminal.app、iTerm2）中运行即可。

6.2 常用命令

# 诊断检查（排查问题的第一站）hermes doctor# 交互式配置向导hermes setup# 查看所有配置hermes config list# 查看配置中的特定项hermes config get model# 查看会话列表hermes sessions list# 查看可用模型列表hermes model# 更新版本hermes update

⚠️ 避坑：hermes config set 只能设置已知的配置键。如果你打错了键名（比如 terminal.backendd），不会报错，但配置不会生效。之后 hermes doctor 也不会告诉你配置错了。检查配置请用 hermes config list 或直接 cat ~/.hermes/config.yaml。

七、目录结构

~/.hermes/├── .env                    # API Key 等敏感配置（不要提交到 git）├── config.yaml             # 非敏感配置（模型、提供商、终端后端等）├── SOUL.md                 # Agent 个性设定文件├── hermes-agent/           # 代码仓库（~500MB，含依赖）│   ├── .venv/              # Python 虚拟环境│   ├── hermes              # CLI 入口脚本（勿直接链接此文件）│   ├── hermes_cli/         # CLI 主模块│   ├── agent/              # Agent 核心逻辑│   ├── tools/              # 工具集（终端、文件、浏览器等）│   ├── providers/          # LLM 提供商适配│   ├── gateway/            # 消息网关（Telegram/Discord 等）│   └── uv.lock             # 依赖锁定文件（切勿手动修改）├── sessions/               # 对话历史├── memories/               # 持久记忆存储├── cron/                   # 定时任务├── logs/                   # 运行日志└── skills/                 # 安装的技能（首次安装无此目录）

⚠️ 避坑：~/.hermes/ 目录应该是你的定期备份对象。它包含了所有对话历史、记忆、配置和 API Key。一句话：丢了代码可以重新 clone，丢了 ~/.hermes/ 你失去的是 Agent 对你的全部认知积累。

快速备份：

tar czf hermes-backup-$(date +%Y%m%d).tar.gz -C ~ .hermes

八、常见问题

8.1 hermes: command not found

# 立即修复（临时）export PATH="$HOME/.local/bin:$PATH"# 永久修复echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrcsource ~/.zshrc

8.2 No module named ‘dotenv’

原因：hermes 命令使用的 Python 解释器不是虚拟环境中的那个。

修复：

# 检查当前指向ls -la ~/.local/bin/hermes# 应输出: ~/.local/bin/hermes -> ~/.hermes/hermes-agent/.venv/bin/hermes# 如果指向了错误的文件，重新链接rm -f ~/.local/bin/hermesln -sf ~/.hermes/hermes-agent/.venv/bin/hermes ~/.local/bin/hermes

8.3 –expose-gc is not allowed in NODE_OPTIONS

原因：Trae/VSCode 等 IDE 会设置 NODE_OPTIONS=–expose-gc 环境变量，但这个选项在新版 Node.js 中被禁止。

修复：

# 在 IDE 终端中运行前清理unset NODE_OPTIONS && hermes --tui# 或直接在系统原生终端中运行（推荐）

8.4 Docker daemon not running

原因：配置了 terminal.backend=docker，但 Docker 服务未启动。

修复：

# macOS Docker Desktopopen -a Docker# macOS Orbstackopen -a Orbstack# 验证docker info# 如果只是想快速用起来，临时切回本地终端hermes config set terminal.backend local

8.5 安装依赖时网络超时

原因：PyPI / npm 在国内网络不稳定。

修复：

# 方案一：设置代理export HTTP_PROXY=http://127.0.0.1:7890export HTTPS_PROXY=http://127.0.0.1:7890uv sync --frozen# 方案二：使用国内镜像（仅适用于 pip，uv sync --frozen 不推荐改源）pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e .# 方案三：换个时间段再试（工作日晚间比白天快）

8.6 模型返回空响应或乱码

原因：API Key 过期、模型名错误、或自定义端点的 URL 配置有误。

修复：

# 1. 先验证 API Key 本身是否有效curl -s https://api.deepseek.com/v1/models \  -H "Authorization: Bearer $DEEPSEEK_API_KEY"# 2. 重新运行 hermes model 交互式选择hermes model# 3. 检查自定义端点配置（如果用本地模型）hermes config get base_url

8.7 会话无法恢复

原因：切换了配置文件或数据目录。

修复：

# 查看现有会话列表hermes sessions list# 用名称恢复特定会话hermes --continue 会话名称# 或用序号恢复hermes --resume 3

九、更新与卸载

更新

hermes update

⚠️ 避坑：hermes update 会从 GitHub 拉取最新代码然后重新安装依赖。如果你的网络环境慢，这个命令可能会超时。更新前建议先备份 ~/.hermes/。

如果 hermes update 不可用（比如网络问题），手动更新：

cd ~/.hermes/hermes-agentgit pull origin mainsource .venv/bin/activateuv sync --frozenuv pip install --quiet --no-deps -e .

卸载

rm -rf ~/.hermesrm -f ~/.local/bin/hermes

⚠️ 避坑：卸载会永久删除所有对话历史和记忆。执行前务必确认不需要这些数据了。建议先备份：

tar czf hermes-backup-before-uninstall.tar.gz -C ~ .hermes