Hermes Agent 全平台安装配置指南：国内镜像一键部署，支持飞书接入

“

Hermes Agent 是开源 AI 智能体框架，可对接飞书/钉钉等平台，支持自定义工具链。国内用户必须用镜像源，本文全程采用中文社区国内镜像（res1.hermesagent.org.cn），适配 Windows、Linux、macOS，含完整安装、模型配置、飞书接入、常见问题排查。

一、系统要求与准备

1. 支持系统

Linux：Ubuntu 20.04+/Debian 11+/CentOS 8+（推荐）
macOS：12 Monterey+（Intel/Apple Silicon 均可）
Windows：10+/11（优先 WSL2 Ubuntu，原生 PowerShell 为 Beta 版）

2. 硬件最低配置

接入外部 API（如 Kimi）：1核CPU、1GB内存、100MB磁盘
本地运行模型：16GB+内存/显存
浏览器自动化：2GB+可用内存

3. 必备准备

大模型 API Key（国内推荐 Kimi（Moonshot），中文强、免特殊网络）
Windows 用户：开启 WSL2（管理员权限）
网络：国内镜像已优化，无需代理

二、分平台安装

Linux / macOS / WSL2（最稳定，推荐）

第一步：一键安装（国内镜像，3–5分钟）

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

脚本自动做：安装 Python 3.11、Node.js 22、uv 包管理器、克隆源码、创建虚拟环境、配置 hermes 命令。

第二步：重载环境变量（必做）

# Bash 用户（Linux 默认） source ~/.bashrc # Zsh 用户（macOS 默认） source ~/.zshrc

第三步：验证安装

# 查版本（显示 v0.14.0+ 即成功） hermes --version # 健康检查 hermes doctor

Windows 安装（两种方案）

方案1：WSL2 Ubuntu（强烈推荐）

管理员身份打开 PowerShell，安装 WSL2：wsl --install -d Ubuntu
重启电脑，设置 Ubuntu 用户名/密码
打开 Ubuntu 终端，执行 Linux 一键安装命令

方案2：原生 PowerShell（Beta，仅临时体验）

irm https://res1.hermesagent.org.cn/install.ps1 | iex hermes --version

三、核心配置

初始化模型配置

hermes setup

按提示选择模型（推荐 Kimi），输入 API Key，配置自动保存到 ~/.hermes/config.yaml。

飞书机器人接入

一键配置（扫码，推荐）：

hermes gateway setup

选择 Feishu / Lark → 扫码新建机器人（自动）→ 飞书手机扫码 → 自动创建应用、配置权限、发布版本。

启动飞书网关：

# 前台启动（测试用） hermes gateway # 后台安装服务（生产用） hermes gateway install # 查看状态 hermes gateway status

配对授权（解决”不认识你”）：

飞书私聊机器人时提示”配对码”，在终端执行：

hermes pairing approve feishu ABC123

四、常用命令速查

命令	作用
`hermes`	开始聊天
`hermes setup`	重新配置模型 API Key
`hermes config`	查看/编辑配置文件
`hermes gateway setup`	重新配置飞书/钉钉
`hermes gateway install`	安装后台服务（开机自启）
`hermes pairing approve feishu 码`	授权飞书用户
`hermes doctor`	健康检查

五、常见问题与避坑

安装超时/依赖拉取失败 → 必须用国内镜像脚本（res1.hermesagent.org.cn），不要用官方 GitHub 源

Windows 提示”命令未找到” → 重启 PowerShell，或执行 $env:PATH += ";$env:LOCALAPPDATA\hermes\bin"

飞书收不到消息 → 检查网关已启动、应用已发布、配对授权已完成

提示”lark-oapi 缺失”

~/.hermes/venv/bin/python -m pip install lark-oapi

六、总结

安装：优先 Linux/macOS/WSL2，用国内镜像一键脚本
配置：hermes setup 绑模型，hermes gateway setup 接飞书
运行：hermes gateway install 后台自启，记得授权配对码
国内优化：镜像源 + 补装依赖，解决网络问题