Hermes Agent 部署安装与常见问题完全指南

Hermes Agent 是由 Nous Research 开发的开源自改进 AI Agent 项目，在 GitHub 上拥有超过 12 万星标。与传统的 IDE 编程助手或单一 API 聊天机器人不同，Hermes Agent 是一个可以运行在你自己服务器上的自主 Agent，能够记住它学到的东西，并随着运行时间的增长变得越来越强大。本文详细介绍 Hermes Agent 的安装部署方式以及常见问题的解决方法。

什么是 Hermes Agent

Hermes Agent 是一个开源的个人 AI Agent，具有以下核心特性：

持久化记忆与自学习能力：Agent 会在使用过程中自动创建技能（Skills），记住解决过的问题，构建关于用户的深度模型，越用越聪明。

多平台消息通道：支持 Telegram、Discord、Slack、WhatsApp、Signal、邮件、CLI 等多种平台，在一个平台开始对话，可以在另一个平台无缝继续。

灵活的模型支持：可以使用 Nous Portal、OpenRouter（200+ 模型）、OpenAI、Anthropic、Local Ollama、本地 VLLM/SGLang 等任何你想要的模型。

计划任务自动化：内置 Cron 调度器，支持自然语言配置日程报告、备份、定时提醒等任务。

沙箱隔离执行：支持 Docker、SSH、Singularity、Modal、Daytona 等多种终端后端，确保执行环境安全隔离。

完整浏览器控制：内置网页搜索、浏览器自动化、视觉分析、图片生成、语音合成、多模型推理等功能。

系统要求

项目	最低要求	推荐配置
操作系统	Linux / macOS / WSL2 / Android (Termux)	Ubuntu 22.04+ / macOS 13+
Git	必须安装	最新版
Python	自动安装（通过 uv）	Python 3.11
Node.js	自动安装（v22）	v22 最新版
内存	1 GB	2 GB 及以上
磁盘	3 GB 可用空间	10 GB 及以上
模型上下文	最少 64K tokens	128K tokens 或更大

注意：Hermes Agent 要求模型至少具备 64,000 token 的上下文窗口。上下文小于 64K 的模型无法维持多步骤工具调用工作流，会在启动时被拒绝。大多数托管模型（Claude、GPT、Gemini、Qwen、DeepSeek）都可以满足此要求。

安装部署

方法一：官方安装脚本（推荐，最快）

一行命令自动安装，自动检测平台并配置所有依赖：

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

安装脚本会自动完成以下工作：

安装 uv（快速的 Python 包管理器）

安装 Python 3.11（通过 uv，无需 sudo）

安装 Node.js v22（用于浏览器自动化和 WhatsApp 桥接）

安装 ripgrep（快速文件搜索）

安装 ffmpeg（语音格式转换）

克隆代码仓库并配置虚拟环境

安装完成后，重新加载 Shell 并启动：

source ~/.bashrc  # 或 source ~/.zshrc
hermes  # 开始对话！

方法二：Android / Termux 安装

Hermes Agent 支持在手机上的 Termux 中运行。官方安装脚本可以自动检测 Termux 并切换到测试过的 Android 流程：

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

Termux 安装会自动使用 Termux pkg 安装系统依赖（git、python、nodejs、ripgrep、ffmpeg、build-essential），并创建一个专为 Android 优化的虚拟环境。

详细的 Termux 安装说明请参考官方指南。

方法三：Nix / NixOS 安装

如果你使用 Nix（Linux、macOS 或 NixOS），官方提供了专门的安装路径：

Nix flake 方式

声明式 NixOS 模块

可选的容器模式

详见官方 Nix 和 NixOS 安装指南。

方法四：从源码手动安装（开发者模式）

如果你想为 Hermes Agent 做贡献，或者想从特定分支安装：

# 克隆仓库
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 运行官方安装脚本
./setup-hermes.sh

# 或者手动安装
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"

# 运行测试
./scripts/run_tests.sh

初始配置

选择 AI 模型提供商

安装完成后，第一件事是选择并配置 AI 模型提供商：

hermes model

推荐的常用提供商：

提供商	类型	特点
Nous Portal	订阅制	零配置 OAuth 登录（推荐新手）
OpenRouter	多模型路由	200+ 模型可选，灵活路由
Anthropic Claude	API	强大的推理能力
OpenAI Codex	OAuth/API	ChatGPT / Codex 模型
OpenAI	API	GPT-4o / o1 / o3 系列
Local Ollama / VLLM	本地部署	完全私有，零 API 费用
DeepSeek	API	高性价比国产模型
NVIDIA NIM	API	Nemotron 系列模型

设置 API Key 环境变量示例：

export OPENROUTER_API_KEY=sk-or-v1-xxxx
# 或
hermes config set OPENROUTER_API_KEY your_key_here

配置消息平台（可选）

如果你想让 Hermes Agent 在 Telegram、Discord 等平台上运行，需要配置消息网关：

# 交互式配置所有消息平台
hermes gateway setup

# 启动网关服务
hermes gateway start

# 安装为系统服务（Linux）
sudo hermes gateway install --system

# 查看网关状态
hermes gateway status

支持的平台包括：Telegram、Discord、Slack、WhatsApp、Signal、邮件、Home Assistant、Mattermost、Matrix、飞书、钉钉、企业微信、微信、BlueBubbles (iMessage)、QQ、Yuanbao 等。

配置工具集

你可以根据需要启用或禁用特定的工具集：

# 查看所有可用工具
hermes tools

# 启用特定工具集
hermes chat --toolsets "web,terminal,browser,vision"

# 常用工具集说明
# web        - 网页搜索和内容提取
# terminal  - 命令行执行和文件操作
# browser   - 浏览器自动化
# vision    - 图片分析和视觉识别
# image_gen - AI 图片生成
# memory    - 持久化记忆
# cronjob   - 计划任务调度
# skills    - 技能系统

完整配置向导

如果你想一次性完成所有配置（模型、工具、消息平台等），直接运行：

hermes setup  # 完整的交互式配置向导

常见问题与解决方法

问题一：hermes: command not found

症状：安装完成后运行 hermes 提示命令找不到。

解决方法：

# 方法一：重新加载 Shell
source ~/.bashrc
# 或
source ~/.zshrc

# 方法二：检查 PATH
which hermes
ls ~/.local/bin/hermes

# 方法三：手动添加到 PATH（如果 ~/.local/bin 不在 PATH 中）
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

问题二：API Key 未设置

症状：启动时报错 API key not set 或类似错误。

解决方法：

# 使用 hermes model 交互式配置
hermes model

# 或者直接设置环境变量
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
hermes config set OPENROUTER_API_KEY your_key_here

问题三：模型上下文窗口不足（64K 要求）

症状：启动时报错 context window too small 或 Minimum context: 64K tokens。

Hermes Agent 要求模型至少 64K token 上下文。解决方法：

# 切换到支持更大上下文的模型
hermes model

# 如果使用本地模型（如 Ollama）
# 确保设置足够的上下文大小
OLLAMA_CONTEXT_SIZE=65536 ollama serve

# 或在 Ollama 启动时指定
ollama run qwen2.5:72b-instruct-q4_K_M -c 65536

问题四：更新后配置丢失或损坏

症状：更新 Hermes 后出现配置错误或缺少配置项。

# 检查配置问题
hermes config check

# 迁移配置
hermes config migrate

# 查看详细诊断
hermes doctor

问题五：hermes doctor 诊断命令

这是最常用的排障命令，可以诊断几乎所有常见问题：

# 运行完整诊断
hermes doctor

# 它会检查：
# - 配置文件是否完整
# - 依赖是否正确安装
# - 服务是否正常运行
# - API Key 是否有效
# - 网络连接是否正常

问题六：Docker 沙箱无法启动

症状：终端工具使用 Docker 后端时报错或无法执行。

解决方法：

# 确认 Docker 已安装并正在运行
docker --version
docker ps

# 如果使用非标准 Docker socket
hermes config set DOCKER_SOCKET /path/to/docker.sock

# 或者切换到本地终端后端
hermes config set TERMINAL_BACKEND local

问题七：消息网关（Gateway）无法连接

症状：配置了 Telegram/Discord 但 Bot 没有响应消息。

# 1. 检查网关是否在运行
hermes gateway status

# 2. 查看网关日志
hermes gateway logs

# 3. 重新启动网关
hermes gateway stop
hermes gateway start

# 4. 检查 Bot Token 是否正确
hermes gateway setup

# 5. 确认平台允许的用户/频道配置正确

问题八：升级过程中终端断开连接

症状：运行 hermes update 时 SSH 断开了。

不用担心，hermes update 有防断连保护：

# 重新连接后，检查更新是否完成
hermes --version  # 确认版本已更新
hermes doctor       # 验证配置完整性

# 如果更新未完成，手动重试
hermes update

# 查看更新日志
cat ~/.hermes/logs/update.log

问题九：危险的命令行未授权被拦截

症状：执行 rm -rf 等危险命令时被拦截，提示需要 approval。

Hermes Agent 有内置的安全命令审批机制。如果确定命令是安全的：

# 方法一：交互式审批（推荐）
/hermes approve   # 在对话中批准
/hermes deny       # 拒绝命令

# 方法二：YOLO 模式（信任所有命令，仅测试环境使用）
hermes --yolo
# 或在会话中输入 /yolo

# 方法三：关闭审批（不推荐，仅 CI/CD 等可信环境）
# 在配置中设置
hermes config set approvals.mode off

警告：关闭 approvals.mode 会禁用所有危险命令安全检查。仅在你完全信任生成命令的来源时使用。

问题十：内存（Memory）文件已满

Hermes Agent 的记忆系统有字符限制（MEMORY.md 约 2200 字符，USER.md 约 1375 字符）。当记忆满了之后：

Agent 会自动整合或替换旧条目来为新信息腾出空间。

你可以通过 memory 工具手动管理记忆条目：

# Agent 会在需要时自动调用 memory 工具
# 支持的操作：
# add     - 添加新的记忆条目
# replace - 替换已有的记忆条目（通过 old_text 匹配）
# remove  - 删除不再需要的记忆条目

# 记忆文件位置
ls ~/.hermes/memories/
# MEMORY.md   - Agent 的个人笔记
# USER.md     - 用户画像和偏好

问题十一：从 OpenClaw 迁移

如果你之前使用 OpenClaw，Hermes Agent 可以自动导入所有数据：

# 交互式迁移（完整迁移）
hermes claw migrate

# 预览迁移内容（不实际执行）
hermes claw migrate --dry-run

# 仅迁移用户数据（不含密钥）
hermes claw migrate --preset user-data

# 覆盖已有冲突
hermes claw migrate --overwrite

会导入的内容：SOUL.md 人格文件、记忆条目、创建的技能、命令白名单配置、消息平台设置、API 密钥（可选择）、TTS 资源文件、工作区指令等。

问题十二：多平台同时使用的会话管理

在多个平台上使用 Hermes Agent 时，会话管理很重要：

场景	命令	说明
开始新对话	/new 或 /reset	在当前平台开始一个全新的对话
切换平台继续	/resume [name]	恢复之前保存的会话
设置主平台	/sethome	将当前聊天设为主通道
查看会话信息	/status	查看当前会话状态和历史
压缩上下文	/compress	手动压缩对话历史以节省 token
中断当前任务	/stop	停止正在运行的 Agent 任务

安全建议

Hermes Agent 内置了多层安全机制，但仍需要注意以下几点：

默认拒绝未知用户：消息网关默认拒绝所有不在白名单或未完成配对的用户。这是防止陌生人滥用 Agent 的安全默认设置。

危险命令审批：不要在不可信的环境中关闭 approvals.mode。rm -rf、chmod 777、dd 等危险命令默认需要手动审批。

YOLO 模式仅限测试环境：hermes –yolo 会跳过所有安全检查，只应在确定命令安全的情况下使用。

API 密钥保护：不要将包含真实 API Key 的配置提交到 Git。Hermes 会将密钥存储在环境变量或单独的密钥存储中。

定期更新：使用 hermes update 保持最新版本，获取最新安全修复和功能更新。

更新与维护

保持 Hermes Agent 更新非常简单：

# 一键更新
hermes update

# 更新后验证
hermes --version   # 确认版本
hermes doctor       # 检查配置完整性
hermes gateway status  # 如果使用了网关

卸载 Hermes Agent：

# 卸载（删除所有数据和配置）
hermes uninstall

# 或手动卸载
rm -rf ~/.hermes
rm -f ~/.local/bin/hermes
rm -f /usr/local/bin/hermes  # 如果用了 --system 安装

什么是 Hermes Agent

系统要求

安装部署

方法一：官方安装脚本（推荐，最快）

方法二：Android / Termux 安装

方法三：Nix / NixOS 安装

方法四：从源码手动安装（开发者模式）

初始配置

选择 AI 模型提供商

配置消息平台（可选）

配置工具集

完整配置向导

常见问题与解决方法

问题一：hermes: command not found

问题二：API Key 未设置

问题三：模型上下文窗口不足（64K 要求）

问题四：更新后配置丢失或损坏

问题五：hermes doctor 诊断命令

问题六：Docker 沙箱无法启动

问题七：消息网关（Gateway）无法连接

问题八：升级过程中终端断开连接

问题九：危险的命令行未授权被拦截

问题十：内存（Memory）文件已满

问题十一：从 OpenClaw 迁移

问题十二：多平台同时使用的会话管理

安全建议

更新与维护

相关资源

相关推荐

Ollama 加载 GGUF 模型 400 错误：huggingface.co 镜像踩坑记

WSL2 完全指南：从零搭建 Windows 最强 Linux 子系统（安装、配置、常见问题）

Docker 容器化技术完全指南：从零掌握安装部署与常见问题解决