十分钟搞定 Hermes Agent：从安装到跑通的保姆级教程

别被「Agent 框架」这四个字吓到

很多人一听到「AI Agent 框架」就觉得安装过程肯定很复杂——要装一堆依赖、配一堆环境变量、折腾半天 Docker。

Hermes Agent 不是这样的。它的安装体验更接近装一个 CLI 工具：一条命令安装，一条命令启动，中间配个 API key 就完事了。

我在三台不同系统的机器上都装过，最慢的一次也没超过十分钟。这篇文章把整个过程拆碎了讲，跟着走就行。

环境要求

先确认你的机器满足这些条件：

操作系统（三选一）：

Linux（Ubuntu 20.04+ / Debian 11+ / CentOS 8+ / Arch）
macOS 12+（Intel 和 Apple Silicon 都行）
Windows 的 WSL2（原生 Windows 不行，必须走 WSL2）

基础依赖：

Python 3.10 或更高版本
pip 或 pipx
Git（用于从源码安装或更新）

硬件：

这东西真的不吃硬件。1 核 CPU、1GB 内存的 VPS 就跑得动
磁盘空间预留 500MB 左右，主要是依赖包

网络：

需要能访问你选择的 LLM API 提供商（OpenRouter、OpenAI 等）
安装过程需要访问 PyPI

大部分开发者的机器已经满足这些条件了。如果你用的是 Windows，先确保 WSL2 已经装好，后面所有操作都在 WSL2 里进行。

Linux / macOS 安装

方式一：一键安装脚本（推荐）

这是最简单的方式：

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

这个脚本做了几件事：

检测你的 Python 版本
创建虚拟环境（默认在 ~/.hermes/venv/）
安装 Hermes Agent 及所有依赖
把 hermes 命令链接到你的 PATH

安装完成后，终端里直接输入 hermes 应该能看到版本信息和帮助文档。

方式二：pip 安装

如果你习惯用 pip 管理 Python 包：

1	pip install hermes-agent

或者用 pipx（推荐，隔离性更好）：

1	pipx install hermes-agent

方式三：从源码安装

适合想看源码或者贡献代码的人：

1
2
3

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
pip install -e .

-e 参数表示可编辑模式安装，你改了源码后不用重新 install。

WSL2 安装

Windows 用户需要先确认 WSL2 环境：

1 2	# 在 PowerShell 中 wsl --version

如果没装 WSL2，先装：

1	wsl --install

装好之后，进入 WSL2 的 Ubuntu 环境：

wsl

然后就跟 Linux 一模一样了，用一键安装脚本或 pip 都行。

有一个注意点：WSL2 里的文件系统和 Windows 是两套。建议把项目文件放在 WSL2 的原生文件系统里（~/），不要放在 /mnt/c/ 下面，后者的 IO 性能差很多。

配置模型提供商

安装完 Hermes Agent 本身只是第一步，你还需要告诉它用哪个 LLM 来推理。

第一次运行 hermes 时，它会自动引导你完成配置。但你也可以手动创建配置文件：

1	mkdir -p ~/.hermes

编辑 ~/.hermes/config.yaml：

# 模型配置
default_model: openrouter/nous-hermes-3
model_providers:
  openrouter:
    api_key: "你的 OpenRouter API key"
  openai:
    api_key: "你的 OpenAI API key"
  nous:
    api_key: "你的 Nous Portal API key"

各平台 API key 获取方式

OpenRouter（推荐新手用这个，模型选择最多）：

访问 openrouter.ai{rel=”nofollow”} 注册账号
进入 Dashboard → API Keys → Create Key
充值几美元的 credits

Nous Portal（Nous 官方平台）：

访问 portal.nousresearch.com{rel=”nofollow”} 注册
生成 API key

OpenAI：

访问 platform.openai.com{rel=”nofollow”}
API keys 页面创建新 key

Kimi / MiniMax 等国内服务商：
各自官网注册获取。配置格式类似，在 model_providers 下加上对应的 provider 名称和 API key 即可。

怎么选模型？

如果你刚入门，用 OpenRouter 上的 nous-hermes-3 就行，性价比不错。

如果你需要更强的推理能力（比如复杂代码任务），可以切到 GPT-4 或 Claude 系列。配置多个 provider 后，在使用时通过参数指定即可：

1	hermes --model openai/gpt-4o "帮我分析这段代码的性能问题"

第一次对话

配置完成，来跑第一次对话试试：

1	hermes "你好，请介绍一下你自己"

如果一切配置正确，你应该在几秒内看到 Hermes Agent 的回复。

试一个稍微复杂点的：

1	hermes "查看当前系统的磁盘使用情况，找出占用空间最大的目录"

这次你会看到 Hermes Agent 的 ReAct 循环在工作：

观察：它先分析你的请求
推理：决定需要使用 shell_exec 工具
行动：执行 df -h 和 du -sh /* | sort -rh | head -20 这类命令
观察：读取命令输出
推理：整理分析结果
输出：给你一个格式化的报告

关于这个推理循环的详细工作原理，可以看 ReAct 循环架构拆解。

交互模式 vs 单次模式

上面演示的是单次模式——给一条指令，拿到结果。适合简单的一次性任务。

如果你要做多轮对话，用交互模式：

hermes -i

进入交互模式后，你可以连续提问，Hermes Agent 会保持上下文。比如：

你: 帮我看看 /etc/nginx/nginx.conf 的内容
Hermes: [显示文件内容]
你: 把 worker_processes 改成 auto
Hermes: [修改文件]
你: 测试一下配置有没有语法错误
Hermes: [执行 nginx -t]

交互模式下的对话会被记录到会话存档中，后续可以被记忆系统检索到。

常见问题排查

Python 版本不对

1	Error: Python 3.10+ required, found 3.8.10

解决方案：

# Ubuntu/Debian
sudo apt update && sudo apt install python3.11 python3.11-venv

# macOS
brew install python@3.11

API key 无效

1	Error: Authentication failed for provider 'openrouter'

检查几个点：

API key 有没有多余的空格或换行
账户里有没有余额
key 是不是被禁用了

网络超时

1	Error: Connection timed out

如果你在国内环境，部分 API 服务商可能需要代理。在配置文件中添加：

1
2
3

proxy:
  http: "http://127.0.0.1:7890"
  https: "http://127.0.0.1:7890"

权限问题

1	Permission denied: ~/.hermes/

一键安装脚本通常会处理权限。手动安装遇到这个问题，执行：

1	chmod -R 755 ~/.hermes/

安装后的第一件事

装好之后，我建议你立刻做一件事：设置持久记忆。

1	hermes "请记住：我的主力编程语言是 Python，我偏好使用 Docker 部署服务，回复请用中文"

Hermes Agent 会把这些偏好写入持久记忆文件。之后每次对话，它都会带着这些上下文，让回复更贴合你的习惯。

你也可以直接编辑 ~/.hermes/memory/prompt.md 文件，手动写入你的偏好信息。记住这个文件有 3575 字符的限制，言简意赅就好。

关于记忆系统更多的配置和用法，参考四层记忆体系详解。

进阶配置

配置终端后端

默认情况下，Hermes Agent 使用本地终端执行命令。如果你想让它在 Docker 容器里执行（更安全），可以配置：

# ~/.hermes/config.yaml
backend:
  type: docker
  image: "hermes-sandbox:latest"
  auto_remove: true

六种终端后端各有适用场景，详见六大执行后端解析。

配置消息平台

如果你想通过 Telegram 或 Discord 跟 Hermes Agent 交互：

platforms:
  telegram:
    bot_token: "你的 Telegram bot token"
    allowed_users:
      - "你的 Telegram user ID"

配置完后，启动平台网关：

1	hermes serve --platform telegram

这块内容比较多，后续有专文介绍。

配置 cron 调度

想让 Hermes Agent 定期自动执行某些任务：

1	hermes cron add "每天早上9点检查服务器状态并发送到 Telegram"

对，用自然语言就能定义定时任务，不用写 cron 表达式。

版本更新

Hermes Agent 更新挺频繁的，社区很活跃。更新方式取决于你的安装方式：

# pip 安装
pip install --upgrade hermes-agent

# pipx 安装
pipx upgrade hermes-agent

# 源码安装
cd hermes-agent && git pull && pip install -e .

# 一键脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/install.sh | bash

更新后，你的记忆、技能文件、配置都不会丢失——它们都存在 ~/.hermes/ 下面，和程序本体是分开的。

安装完了，然后呢

到这里，你应该已经有一个能正常工作的 Hermes Agent 了。下一步我建议：

让它帮你做几个你熟悉的任务，观察它的执行过程
去 ~/.hermes/skills/ 目录看看它自动生成的技能文件
到 cocoloop 社区翻翻别人分享的技能文件和配置方案
如果感兴趣的话，看看它的架构设计，理解它为什么这么做

折腾过程中遇到问题，GitHub Issues 和社区讨论区都是好去处。这个项目的 maintainer 响应挺快的。

延伸阅读：OpenClaw 社区资源

本文由 CocoLoop 中文社区出品。如果你在研究 AI Agent 与主流模型的工程化落地，姊妹站 OpenClaw 中文社区 也许会有帮助：

目录