🚀 Hermes Agent 小白安装教程｜一键部署，轻松接入飞书

一行命令安装，两分钟启动你的专属 AI 智能体

🔍 一句话认识 Hermes Agent

Hermes Agent 是由 Nous Research 开发的开源自主学习 AI 智能体框架。它不是一个简单的聊天机器人，而是一个具备跨会话持久记忆和自学习技能生成能力的长期运行 AI 助理——用得越久，它越懂你。

📦 前置准备

在开始之前，请确认你已准备好以下三项：

项目	要求
操作系统	Linux / macOS / Windows WSL2（原生 Windows 不支持）
Git	已安装（安装脚本会自动检测）
LLM API Key	至少一个可用 Provider 的 API Key（如 OpenAI、Kimi、阿里云 DashScope、OpenRouter 等）

Windows 用户必看：如果你用的是 Windows，请先按微软官方教程安装 WSL2 并配置 Ubuntu 22.04 LTS 子系统，然后在 WSL2 终端中执行下方的安装命令。

⚡ 第一步：一键安装（推荐）

在终端中执行以下命令，安装脚本会自动处理 Python、Node.js、Git、ripgrep 等所有依赖：

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

安装脚本会自动完成以下工作：检测并安装 Python 3.11、Node.js v22、ripgrep、ffmpeg 等依赖；克隆项目仓库；创建虚拟环境；安装所有 Python 依赖；配置全局 hermes 命令。

🔁 重新加载 Shell 配置

安装完成后，执行以下命令使环境变量生效：

source ~/.bashrc      # 如果你使用 bash
# 或
source ~/.zshrc       # 如果你使用 zsh

✅ 验证安装

运行以下命令检查安装是否成功：

hermes version       # 应返回版本号，如 v0.8.3
hermes doctor        # 进行环境诊断

hermes doctor 会检查所有依赖和配置项，输出类似：

✓ Python 3.11.9
✓ Node.js v22.4.0
✓ uv 0.4.1
✓ ripgrep 14.1.0
✓ ffmpeg 6.1.1
⚠ 未检测到 API Key，请运行 hermes setup

⚙️ 第二步：初始配置

运行配置向导，进行初步设置：

hermes setup

在向导中，新手建议直接选择 Quick setup，然后选择你的大模型供应商（如 OpenAI、Kimi、OpenRouter、阿里云 DashScope 等）并配置相应的 API Key。

配置目录说明：Hermes Agent 的配置目录位于 ~/.hermes/，其中包含以下子目录：
目录
用途
~/.hermes/skills/
存放自动生成和手动创建的技能文件
~/.hermes/memory/
持久记忆数据库
~/.hermes/personas/
人格/角色配置文件
~/.hermes/logs/
运行日志

目录	用途
`~/.hermes/skills/`	存放自动生成和手动创建的技能文件
`~/.hermes/memory/`	持久记忆数据库
`~/.hermes/personas/`	人格/角色配置文件
`~/.hermes/logs/`	运行日志

💬 第三步：开始对话

安装并配置完成后，在终端中输入以下命令即可开始与 AI 智能体对话：

hermes

首次启动时会显示 Hermes 横幅、配置的模型信息，然后出现 > 提示符，输入你的消息即可实时获得回复。

🔌 第四步：接入飞书（可选）

如果你希望 Hermes 能像客服机器人一样在飞书群聊中与你交互，可以配置“消息网关”。

1️⃣ 飞书开放平台侧配置

注意：飞书侧配置是让 Hermes 能够收到消息的前提。

第一步：访问飞书开放平台，登录后进入开发者后台。
第二步：点击「创建企业自建应用」，输入应用名称和描述。
第三步：在应用详情页，点击「添加应用能力」，选择「机器人」。
第四步：在左侧「权限管理」中，至少添加 im:message（获取与发送消息的核心权限）和 im:resource（获取消息中的资源文件）。建议补充 im:chat:readonly 和 admin:app.info:readonly。
第五步：在左侧「凭证与基础信息」中，记录下 App ID 和 App Secret。
第六步：在左侧「事件与回调」中，订阅方式选择「长连接」，添加事件 im.message.receive_v1。
第七步：在「版本管理与发布」中，创建版本并提交发布。

2️⃣ Hermes Agent 侧配置

飞书侧配置完成后，回到终端进行 Hermes 侧的 Gateway 配置：

hermes gateway setup

在渠道列表中选择 Feishu（飞书）。
按提示依次填写 App ID、App Secret。
Domain 国内版填 feishu，Connection mode 默认为 websocket。
在鉴权中选择「1」（不限制对话人），这样群里所有人都可以与机器人交互。
确认无误后选择「Done」保存。

3️⃣ 启动网关服务

hermes gateway start

Gateway 启动成功后，在飞书中找到你的机器人，发送消息测试（如「你好」），首次对话需根据终端提示运行配对命令进行授权确认。

🔧 常见问题与排错

问题	解决方法
安装后 hermes 命令找不到	重新执行 `source ~/.bashrc` 或 `source ~/.zshrc`
模型未被识别	在聊天窗口中输入 `/model` 命令手动指定模型，或检查 `~/.hermes/config.yaml` 中配置是否正确
飞书网关启动失败，提示 lark-oapi 缺失	在 Windows/WSL2 环境下，进入 Hermes 内置 venv 手动安装：`.\\pip.exe install lark-oapi==2.19.0`
飞书机器人能收到消息但不回复	检查 `~/.hermes/.env` 文件中的 API Key 是否正确，以及 `config.yaml` 中的模型配置是否指向了正确的供应商
API 返回 401 错误	API Key 无效或模型配置有误，请重新运行 `hermes setup` 配置正确的 Provider 和 API Key
安装脚本卡住或超时	检查网络能否访问 GitHub，必要时切换 DNS 或配置代理