适用范围与前置条件
部署目标
完成本文操作后,可达成以下结果:
- 在 Linux、macOS、Windows(WSL2 或原生 PowerShell)及容器环境中完成 Hermes Agent 部署
- 掌握依赖准备、配置写入、服务启动与自检的完整链路
- 能够定位并处理端口占用、权限不足、依赖缺失等常见安装异常
前置条件清单
| 项目 | 要求 | 检查命令 |
|---|---|---|
| 操作系统 | Linux 主流发行版 / macOS 12+ / Windows 10+(WSL2 或原生) | uname -a |
| 运行时 | Python 3.10+ 或 Go 1.21+(按发行包类型选择) | python3 --version / go version |
| 内存 | 建议可用内存 ≥ 2 GB | free -h |
| 网络 | 可访问依赖源与镜像仓库 | curl -I <源地址> |
| 权限 | 安装目录可写;注册系统服务需 sudo | id |
注意事项:生产环境建议为 Agent 分配独立系统用户运行,不建议以 root 身份直接启动。该做法属于最小权限原则的常规实践,可降低进程被利用后的影响范围。
分步安装流程
Windows 原生安装(无需 WSL)
支持 Win10/11 原生运行,CLI、网关、终端工具与浏览器相关功能均已适配。在 PowerShell 中执行:
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
脚本自动部署的组件
脚本会完成运行环境与工具链的配置,无需手动干预,包含:Python 3.11、uv 包管理器、Node.js 22、ripgrep 搜索工具、ffmpeg 多媒体工具、便携 Git 环境。
安装路径与隔离规则
- 安装目录:
%LOCALAPPDATA%\hermes\hermes-agent - 自动创建 Python 虚拟环境,与系统 Python 环境相互隔离,避免依赖冲突
- 自动将
hermes命令写入用户 PATH 环境变量
必要操作:安装完成后需重启终端,PATH 变更方可生效。未重启终端时出现
command not found属于预期现象,不视为安装失败。
Linux / macOS 通用安装
在终端执行一键安装脚本:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
可选参数(按需叠加)
--skip-setup:跳过初始化配置向导,适用于后续手动写入配置的场景--with-browser:安装浏览器工具依赖,适用于需要网页自动化能力的场景--full:安装全部扩展功能(WhatsApp 桥接、RL 训练、完整依赖),安装体积与耗时相应增加
适用边界:一键脚本默认在用户目录部署,不写入系统级路径。若企业环境限制外网访问,需先将脚本与依赖源地址替换为内网镜像,否则脚本会在下载阶段中断。
Android Termux 安装
适配手机端 Termux 终端环境。建议先更新系统组件,再执行安装脚本:
pkg update && pkg upgrade
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
注意事项:移动端内存与存储受限,运行长上下文任务时可能触发 OOM;建议仅用于轻量任务验证,不作为生产运行环境。
核心模型配置:Kimi 大模型
安装完成后需配置大模型 API 方可正常使用。Kimi 大模型的标准配置为:模型名 moonshot/k2.6,环境变量 MOONSHOT_API_KEY。两项参数与内置模板一致,通常不存在参数冲突。
Kimi API Key 获取步骤
- 注册并登录月之暗面开放平台
- 在左侧菜单栏进入「API Key 管理」
- 点击「新建 API Key」,自定义名称后确认
- 复制生成的密钥并妥善保存(密钥仅在创建时完整展示)
额度说明:新用户可获得平台提供的免费调用额度,无最低消费要求;额度用尽后按平台计费规则付费使用。具体额度与价格以平台当期公示为准。
交互式配置(推荐初次使用)
执行配置向导,全程可视化操作:
hermes setup
配置流程:
- LLM 服务商选择:Moonshot (Kimi, China)
- 粘贴 Moonshot API Key
- 默认模型选择:
moonshot/k2.6 - 按需勾选基础工具:网页检索、终端操作、文件处理
- 向导自动保存配置并完成初始化
手动命令配置(适用于自动化脚本)
可直接通过命令行写入配置,无需交互:
hermes config set model moonshot/k2.6
hermes config set MOONSHOT_API_KEY sk-你的API密钥
注意事项:手动写入时需确认模型名与密钥变量名的大小写和拼写完全一致;密钥中若含首尾空格或换行,会导致鉴权失败。
配置文件路径
- Windows:
%LOCALAPPDATA%\hermes\config.yaml、%LOCALAPPDATA%\hermes\.env - Linux / macOS / Termux:
~/.hermes/config.yaml、~/.hermes/.env
启动验证与基础使用
首次启动测试
终端输入以下命令启动交互界面:
hermes
出现 What can I do for you today? 提示即表示启动成功,可进行对话验证:
- 基础对话:你好,请介绍一下你自己
- 实操任务:统计当前目录下所有 Python 文件数量
判断条件:若提示符出现但对话返回鉴权错误,问题位于模型配置层而非安装层,应按下一节排查顺序处理。
两种运行模式
单次任务模式:适合一次性任务,执行完成后自动退出,不保留上下文。
hermes "帮我整理当前文件夹文件并统计大小"
交互多轮模式:保留上下文记忆,适合需要连续追问的复杂任务。
hermes
常用快捷命令
/help:查看全部指令/skill list:查看已加载技能/skill run 技能名:运行自定义技能/save 会话名:保存当前对话记忆(本地持久化)/exit或Ctrl+C:退出交互模式
记忆文件备份方法
跨会话记忆、自定义技能与配置文件均存储在本地对应目录中。直接复制该目录即可完成全量备份;重装系统或更换设备后,将备份目录还原至原路径即可恢复数据。
适用边界:该方式为文件级冷备份,不包含运行中进程的内存状态;备份前建议先退出 Agent,避免写入过程中复制产生不一致文件。
常见问题排查
安装失败
- 不建议使用 sudo 或管理员权限安装,框架默认在用户目录内部署,提权反而会引入属主混乱
- 检查网络连通性;若镜像访问异常,可切换网络环境重试
- Linux 极简系统可手动补齐基础依赖:
sudo apt install git curl build-essential
hermes: command not found
- 关闭当前终端并重新打开,使 PATH 变更生效
- Linux / macOS 可执行环境刷新:
source ~/.bashrc或source ~/.zshrc - Windows 可手动添加 PATH:将
%LOCALAPPDATA%\hermes\hermes-agent\venv\Scripts加入用户环境变量
大模型连接或调用失败
- 核对配置参数:模型名应为
moonshot/k2.6,密钥变量应为MOONSHOT_API_KEY - 检查 API Key 无多余空格与换行,确认账户余额或调用额度充足
- 国内网络环境通常无需配置代理;若开启全局代理,可能因出口 IP 变化引发鉴权或网络冲突,建议关闭后重试
部署方式选型
| 使用场景 | 推荐方式 | 说明 |
|---|---|---|
| 常规使用 | Windows 用 PowerShell 脚本,Linux / macOS 用 curl 脚本 | 部署链路最短,环境隔离由脚本保证 |
| 短期验证 | pip install hermes-agent | 依赖现有 Python 环境,需自行管理版本冲突 |
| 二次开发 | 源码编译安装 | 可修改项目代码,需自行维护依赖与构建流程 |
国内网络环境下,Hermes Agent 搭配 Kimi API 可减少跨境网络依赖,在长文本处理、自动化任务与代码生成场景中表现稳定。实际效果受任务类型、上下文长度与模型版本影响,建议以自有业务样本做小规模验证后再扩大使用范围。













