最新Hermes Agent 安装部署完整文档

Hermes Agent 部署完整文档

文档信息

• 适配版本：Hermes Agent 最新稳定版
• 适用系统：Ubuntu / Debian / macOS / WSL2 / Docker
• 核心定位：开源自主智能体，支持任务规划、长期记忆、工具调用、多渠道接入
• 默认端口：8642
  

一、环境前置要求

1. 基础依赖

• Python ≥ 3.11
• Git、curl
• Node.js ≥ 22（部分网关组件依赖）
• 包管理器：uv/ pip 二选一

2. 系统防火墙放行

如需外网访问，服务器放行端口：8642

二、部署方式（四种可选）

方式1：一键脚本快速部署（新手推荐）

Linux / macOS / WSL

国内加速脚本（解决GitHub访问慢）

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

官方原版脚本（海外网络使用）

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

执行完成后刷新环境变量

# bash 用户source~/.bashrc# zsh 用户（macOS默认）source~/.zshrc

验证安装

hermes--version# 环境自动自检hermes doctor

方式2：PIP 包安装（已有Python环境）

pipinstallhermes-agent# 安装浏览器、系统工具依赖hermes postinstall

方式3：源码手动部署（开发二次修改首选）

# 1. 安装 uv 高速包管理器curl-LsSfhttps://astral.sh/uv/install.sh|shsource~/.bashrc# 2. 拉取源码gitclone https://github.com/NousResearch/hermes-agent.gitcdhermes-agent# 3. 创建虚拟环境uv venv venv--python3.11sourcevenv/bin/activate# 4. 安装全量依赖uv pipinstall-e".[all]"# 5. 全局注册 hermes 命令ln-sf$(pwd)/venv/bin/hermes ~/.local/bin/ hermes--version

方式4：Docker 容器部署（服务端常驻运行）

# 1. 创建持久化配置目录mkdir-p~/.hermes# 2. 初始化配置向导dockerrun-it--rm\-v~/.hermes:/opt/data\nousresearch/hermes-agent setup# 3. 后台启动网关服务dockerrun-d\--namehermes-agent\--restartunless-stopped\-p8642:8642\-v~/.hermes:/opt/data\nousresearch/hermes-agent gateway run

Docker 常用管理命令

# 实时日志查看dockerlogs-fhermes-agent# 重启dockerrestart hermes-agent# 停止dockerstop hermes-agent

三、初始化核心配置

1. 配置大模型接口

交互式配置模型服务商与 API Key

hermes model

支持接入类型：

• Nous Portal（官方渠道，入门测试首选）
• OpenRouter（聚合多模型）
• Ollama（本地私有化模型）
• OpenAI 兼容接口（通义、Kimi、自定义中转地址）

配置完成测试对话

hermes chat-q"部署测试，正常回复即配置成功"

2. 网关多机器人渠道配置（Telegram/Discord等）

# 进入渠道配置向导hermes gateway setup# 查看网关运行状态hermes gateway status# 启停网关hermes gateway start hermes gateway restart hermes gateway stop

关键：配置allowed_user_ids用户白名单，防止外人调用智能体

四、Web 管理面板访问

网关启动后浏览器打开地址：

• 本地访问：http://localhost:8642
• 服务器公网访问：http://服务器IP:8642

功能：会话记忆管理、技能查看、任务日志、渠道配置可视化管理

五、常用运维命令汇总

基础对话

hermes# 交互式终端对话hermes--continue# 接续上一轮会话hermes chat-q"单次指令"

配置管理

hermes config show# 查看全部配置hermes config edit# 手动编辑配置文件hermes update# 一键升级新版本

智能体技能管理（核心自主进化能力）

hermes skills list# 查看已加载技能hermes skills browse# 浏览社区公共技能库hermes skills reload# 重载生效新安装技能

日志排查

hermes logs--followcat~/.hermes/logs/main.log

六、卸载步骤

PIP / 脚本安装卸载

pip uninstall-yhermes-agent# 删除全部配置、记忆、日志数据rm-rf~/.hermes# 删除全局命令rm~/.local/bin/hermes

Docker 卸载

dockerrm-fhermes-agentdockerrmi nousresearch/hermes-agentrm-rf~/.hermes

七、常见问题排错

1. hermes: command not found
   刷新环境变量source ~/.bashrc，重启终端重试

2. Python 版本过低
   使用 pyenv / uv 指定 Python3.11 虚拟环境运行

3. API 调用报错 401 / 超时
   执行hermes model重新填写有效密钥；配置代理环境变量排查网络问题

4. 端口 8642 被占用

# Linux/macOSlsof-i:8642kill对应PID# 自定义端口启动hermes gateway run--port8643

5. 网关机器人无响应
   检查网关状态、确认白名单ID配置，通过实时日志定位异常

八、官方地址

• 开源仓库：https://github.com/NousResearch/hermes-agent
• 官方文档：https://hermes-agent.nousresearch.com/docs/zh-Hans
• 国内社区：https://hermesagent.org.cn