最新 Hermes Agent 安装教程:全环境部署指南

AI知识库3天前发布 ai131
147 00

适用范围与前置条件

部署目标

完成本文操作后,可达成以下结果:

  • 在 Linux、macOS、Windows(WSL2 或原生 PowerShell)及容器环境中完成 Hermes Agent 部署
  • 掌握依赖准备、配置写入、服务启动与自检的完整链路
  • 能够定位并处理端口占用、权限不足、依赖缺失等常见安装异常

1794821122 Hermes Agent %E C E B Hermes Agent E Ae E A E E A Befbc Ae A E Eafe A E A E Bd

前置条件清单

项目要求检查命令
操作系统Linux 主流发行版 / macOS 12+ / Windows 10+(WSL2 或原生)uname -a
运行时Python 3.10+ 或 Go 1.21+(按发行包类型选择)python3 --version / go version
内存建议可用内存 ≥ 2 GBfree -h
网络可访问依赖源与镜像仓库curl -I <源地址>
权限安装目录可写;注册系统服务需 sudoid

注意事项:生产环境建议为 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 获取步骤

  1. 注册并登录月之暗面开放平台
  2. 在左侧菜单栏进入「API Key 管理」
  3. 点击「新建 API Key」,自定义名称后确认
  4. 复制生成的密钥并妥善保存(密钥仅在创建时完整展示)

额度说明:新用户可获得平台提供的免费调用额度,无最低消费要求;额度用尽后按平台计费规则付费使用。具体额度与价格以平台当期公示为准。

交互式配置(推荐初次使用)

执行配置向导,全程可视化操作:

hermes setup

配置流程:

  1. LLM 服务商选择:Moonshot (Kimi, China)
  2. 粘贴 Moonshot API Key
  3. 默认模型选择:moonshot/k2.6
  4. 按需勾选基础工具:网页检索、终端操作、文件处理
  5. 向导自动保存配置并完成初始化

手动命令配置(适用于自动化脚本)

可直接通过命令行写入配置,无需交互:

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 可减少跨境网络依赖,在长文本处理、自动化任务与代码生成场景中表现稳定。实际效果受任务类型、上下文长度与模型版本影响,建议以自有业务样本做小规模验证后再扩大使用范围。

© 版权声明

相关文章