Hermes-Agent 全平台部署运维中文安装配置手册

转载请注明 来源:https://www.cnblogs.com/eword/
Author：eword
Email:eword@139.com

文档说明

本文档覆盖 Docker容器部署 / 原生非Docker部署 两大架构；支持 macOS / Windows / Linux / 银河麒麟 / 统信UOS；统一使用mirror-switcher 做全链路镜像源切换；Anaconda 管控Python虚拟环境、nrm/nvm 管理Node.js版本与源；包含企业微信机器人接入、MCP双向系统集成、安全加固、配置详解、智谱GLM大模型接入全套流程。

前置工具仓库：mirror-switcher
官方地址：https://gitee.com/eword/mirror-switcher/blob/main/README.md

目录

1. 前置公共环境准备（全系统通用镜像源管控）
2. 分架构部署：非Docker原生部署、Docker容器部署
   　2.1 macOS 非Docker（Anaconda+nvm+nrm+mirror-switcher）
   　2.2 Windows 非Docker（Anaconda+nvm+nrm+mirror-switcher）
   　2.3 Linux x86_64 非Docker
   　2.4 银河麒麟V10 非Docker
   　2.5 统信UOS 非Docker
   　2.6 全平台 Docker 一键部署方案
3. Hermes 初始化向导分步配置（避坑版）
4. 大模型接入教程：智谱GLM API + Ollama本地离线双方案
5. 企业微信客户端插件安装 + CLI调用对接
6. 系统双向集成：外部系统调用Hermes | 第三方系统暴露MCP给Hermes
7. 安全策略配置与权限加固
8. 核心配置文件目录清单 & 关键配置项详解
9. 常用运维命令、日志排查、备份与卸载
10. 信创环境补充说明（麒麟/统信）
11. 常见故障排查

一、公共前置：安装 mirror-switcher 镜像源管理工具

mirror-switcher 是全平台统一镜像源切换工具集，覆盖 pip/conda/npm/brew/docker/git/yum/apt 等 20 种包管理器与开发环境，命令格式与 nrm 完全一致，支持一键测速、配置备份还原、国产系统自动适配。部署 Hermes 前必须先完成本工具安装，统一切换国内源避免外网下载超时。

工具官方仓库：https://gitee.com/eword/mirror-switcher
核心特性：零第三方 Python 依赖、自动注入系统 PATH、原生支持银河麒麟/统信UOS等信创系统、配置修改前自动备份。

1.1 方式A：远程一键安装（官方推荐，全自动）

无需手动 git clone，一行命令完成全量工具安装、软链接注册、PATH 环境变量自动写入，全程免手动配置。

macOS / Linux / 银河麒麟 / 统信UOS（bash/zsh）

# 国内优先 Gitee 源，自动识别系统发行版与架构
bash <(curl -fsSL https://gitee.com/eword/mirror-switcher/raw/main/bootstrap.sh)

• 可选：仅安装指定工具（逗号分隔，按需精简）

  bash <(curl -fsSL https://gitee.com/eword/mirror-switcher/raw/main/bootstrap.sh) --tools=pip,conda,npm,brew,git,docker
  

• 安装完成后执行以下命令，让当前终端立即生效：

  source ~/.zshrc   # zsh 用户
  source ~/.bashrc  # bash 用户
  

Windows PowerShell（管理员身份运行）

iwr -useb https://gitee.com/eword/mirror-switcher/raw/main/bootstrap.ps1 | iex

安装完成后新开 PowerShell 窗口，即可全局调用所有 switch-* 命令。

自动安装机制说明：

1. 优先通过 git clone 拉取源码，支持后续增量更新；无 git 环境自动回退到压缩包安装
2. 自动注册全部 20 个 switch-* 命令到系统全局
3. 命令目录幂等写入系统 PATH，重复安装不会重复污染配置文件
4. 自动识别国产系统（麒麟/统信/openEuler 等），匹配对应系统源管理工具

1.2 方式B：源码本地手动安装（备选，可定制）

适合离线部署、需修改源码的场景，通过官方安装脚本完成标准化注册。

# Gitee 免登录克隆源码
git clone https://gitee.com/eword/mirror-switcher.git
cd mirror-switcher

# 一键安装全部工具（自动创建软链接 + 自动写入系统 PATH）
./install.sh

# 可选：仅安装指定工具
./install.sh --tools=pip,conda,npm

安装完成后重载 shell 配置即可全局使用。

1.3 一键切换国内源（部署 Hermes 前必执行）

所有工具命令格式统一，与 nrm 用法完全一致：

# Python pip 切换清华源
switch-pip use tsinghua

# Conda 切换清华源
switch-conda use tsinghua

# NPM 切换淘宝源
switch-npm use taobao

# Git 全局配置 GitHub 加速代理
switch-git use ghproxy

# macOS Homebrew 切换清华源
switch-brew use tsinghua

# Docker 镜像加速器配置
switch-docker use ustc

通用辅助命令（所有 switch-* 工具通用）：

• switch-xxx ls：列出所有预设源，* 标记当前生效源
• switch-xxx test：批量测速并按延迟排序
• switch-xxx backup：备份原始配置文件
• switch-xxx restore：从最新备份还原配置

1.4 Node.js 环境管控：nvm + nrm（兼容方案）

mirror-switcher 自带 switch-node 可替代 nvm 实现多版本管理；如需沿用传统 nvm 方案，可按以下步骤部署：

安装 nvm（版本管理器）

macOS/Linux/麒麟/UOS：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc
# 安装 LTS 稳定版 Node
nvm install --lts
nvm use lts

Windows：使用 nvm-windows，执行 nvm install lts

nrm 管理 npm 镜像源

npm install -g nrm
# 列出所有可用源
nrm ls
# 切换淘宝源
nrm use taobao

二、方案A：非Docker原生部署（推荐，宿主机直接运行）

通用源码拉取（Gitee免登录，无账号校验）

# 国内镜像克隆Hermes-Agent源码
git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git hermes-agent
cd hermes-agent

目录分离说明：此处克隆的 hermes-agent 为程序源码目录，所有用户配置、会话记录、密钥、记忆数据均独立存放在 ~/.hermes/ 目录下，删除源码文件夹不会丢失任何个人配置与数据。

2.1 macOS 详细部署（Anaconda）

步骤1 安装Xcode命令行工具

xcode-select --install

步骤2 安装Homebrew并换源

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
switch-brew tsinghua
brew install git ffmpeg ripgrep cmake

步骤3 安装Anaconda并创建独立Python环境

1. 官网下载Anaconda macOS安装包；
2. 初始化conda：

# 换conda国内源
switch-conda tsinghua
# 创建Hermes专属虚拟环境，锁定Python3.11
conda create -n hermes python=3.11
conda activate hermes
# pip换源
switch-pip tsinghua

步骤4 项目本地可编辑安装

执行前请确认终端前缀显示 (hermes)，即已成功激活专属虚拟环境。-e 为可编辑模式，修改源码即时生效；[all] 表示安装全量依赖，包含桌面GUI、工具链、浏览器自动化、多媒体处理等所有组件。

pip install --upgrade pip
pip install -e ".[all]"

步骤5 全局注册hermes命令

mkdir -p ~/.local/bin
ln -sf $(conda env list | grep hermes | awk '{print $2"/bin/hermes"}') ~/.local/bin/hermes
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# 验证
hermes --version

2.2 Windows 非Docker Anaconda部署

1. 安装Anaconda，启动Anaconda Prompt；
2. 创建环境：

conda create -n hermes python=3.11
conda activate hermes
switch-pip tsinghua

1. 进入源码目录执行：

pip install -e ".[all]"

1. 全局注册hermes命令（生产环境推荐）：
   • 找到Anaconda环境路径，默认位于 C:\ProgramData\anaconda3\envs\hermes\Scripts\hermes.exe
   • 右键「此电脑」→ 属性 → 高级系统设置 → 环境变量 → 系统变量Path → 编辑 → 新建，填入上述Scripts目录路径
   • 重启PowerShell或终端，执行 hermes --version 验证

2.3 Linux x86_64（Ubuntu/Debian/CentOS）

前置：安装Anaconda

# 下载对应架构安装包，以x86_64为例
wget https://mirrors.tuna.tsinghua.edu.cn/anaconda/archive/Anaconda3-2024.02-1-Linux-x86_64.sh
bash Anaconda3-2024.02-1-Linux-x86_64.sh
# 按提示完成安装，执行初始化
source ~/.bashrc

部署Hermes

# 系统依赖
sudo apt update && sudo apt install git ffmpeg build-essential
# 创建虚拟环境
conda create -n hermes python=3.11
conda activate hermes
switch-pip tsinghua
cd hermes-agent
pip install -e ".[all]"
# 软链接全局命令
sudo ln -s $(which hermes) /usr/local/bin/hermes

2.4 银河麒麟V10 信创环境部署

系统适配说明

麒麟基于Linux内核，使用yum/dnf包管理器，先用mirror-switcher切换yum源：

switch-yum 163
sudo yum install git ffmpeg gcc gcc-c++

后续Anaconda环境创建、源码安装步骤同标准Linux一致；
如为ARM飞腾架构，下载ARM版Anaconda，其余流程完全相同。

2.5 统信UOS 非Docker部署

switch-apt tsinghua
sudo apt install git ffmpeg make gcc

Anaconda选用对应CPU架构版本，创建hermes虚拟环境，pip install -e ".[all]"即可，流程无差异。

2.6 方案B：Docker容器化一键部署

前置说明

全程国内可通、无需外网，包含镜像加速、持久化挂载、初始化全流程。

步骤1：配置Docker国内镜像加速（必做）

macOS / Linux / 麒麟 / 统信 统一配置：

# 创建docker镜像加速配置
mkdir -p ~/.docker
cat > ~/.docker/daemon.json << EOF
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://ghcr.nju.edu.cn"
  ]
}
EOF

重启Docker生效：桌面端重启Docker应用，服务器执行：sudo systemctl restart docker

步骤2：国内加速拉取 Hermes 官方镜像

# 南京大学GHCR国内镜像（稳定免FQ）
docker pull ghcr.nju.edu.cn/nousresearch/hermes:latest

版本锁定建议：生产环境避免使用 latest 滚动标签，可指定固定版本号，例如 docker pull ghcr.nju.edu.cn/nousresearch/hermes:v0.4.0；升级时先拉取新版本镜像，重建容器即可，配置数据因挂载持久化不会丢失。

步骤3：启动持久化容器（挂载配置目录、端口映射、后台常驻）

docker run -d \
  --name hermes-agent \
  --restart always \
  -p 8080:8080 \
  -v ~/.hermes:/root/.hermes \
  ghcr.nju.edu.cn/nousresearch/hermes:latest

步骤4：进入容器执行初始化配置

docker exec -it hermes-agent hermes setup

步骤5：容器常用运维命令

# 启动Web服务
docker exec -it hermes-agent hermes serve
# 启动桌面端（仅带图形环境机器）
docker exec -it hermes-agent hermes desktop
# 环境自检
docker exec -it hermes-agent hermes doctor
# 查看日志
docker logs -f hermes-agent

容器持久化说明：挂载 ~/.hermes 宿主机目录，所有配置、密钥、记忆、会话数据全部宿主机留存，删除容器不丢失数据。

三、Hermes 初始化向导分步配置（避坑完整版）

执行初始化：

hermes setup

1.部署模式选择

• Quick Setup：Nous云端OAuth登录（国内网络极易超时，不推荐）
• Full setup：自定义全部模型/工具/API（推荐）
• Blank Slate：极简最小启动

1. Terminal backend 终端后端
   必须选择：Local - run directly on this machine
   严禁选择Docker（原生部署场景）

2. 消息机器人平台接入
   选择：Skip — set up later with 'hermes setup gateway'
   后续如需对接企业微信再单独配置网关。

3. 未授权用户访问策略
   默认 Use DM pairing 配对授权即可；无外部接入可直接Skip。

4. 图像生成模型服务商
   直接选择最后一项：Skip — keep defaults / configure later
   避免境外付费接口与网络问题。

初始化完成代表基础环境就绪。

常用启动命令

# 终端对话模式
hermes chat
# 桌面GUI客户端
hermes desktop
# Web网页服务端
hermes serve
# 环境自检排错
hermes doctor
# 编辑主配置
hermes config edit

四、大模型接入：智谱GLM API 详细配置

4.1 前置准备

前往智谱开放平台注册应用，获取 API_KEY。智谱提供两类主流接入方案：

• 通用模型系列：glm-4、glm-3-turbo、glm-5 等通用对话模型，通用 API 端点
• GLM Coding Plan 编码套餐：面向高频编码场景的订阅制套餐，独立编码专用路径，深度适配代码生成、调试、重构场景

通用接口默认端点：https://open.bigmodel.cn/api/paas/v4/
Coding 套餐专用路径：https://open.bigmodel.cn/api/coding/paas/v4/ 下编码模型专属通道，模型名使用编码系列标识。

4.2 方式1：命令行写入环境密钥（推荐，统一存入 .env）

所有 API Key 统一写入 Hermes 私有环境变量文件 ~/.hermes/.env，禁止硬编码到配置文件。通用模型与 GLM Coding 套餐共用同一 API Key，按模型名区分调用通道。

# 写入智谱API密钥，通用模型与Coding套餐通用
echo "ZHIPU_API_KEY=你的密钥" >> ~/.hermes/.env

4.3 方式2：修改核心配置文件 ~/.hermes/config.yaml

在 providers 节点新增智谱配置片段，通过 ${ZHIPU_API_KEY} 引用环境变量中的密钥。

通用模型配置

providers:
  zhipu:
    base_url: "https://open.bigmodel.cn/api/coding/paas/v4/"
    api_key: "${ZHIPU_API_KEY}"
    default_model: "glm-3-turbo"

GLM Coding 编码套餐配置

如需使用编码套餐专属能力，可单独声明编码服务商节点，指定编码系列模型：

providers:
  zhipu-coding:
    base_url: "https://open.bigmodel.cn/api/coding/paas/v4/"
    api_key: "${ZHIPU_API_KEY}"
    default_model: "glm-4-coding"

4.4 指定模型启动对话

调用通用对话模型

hermes chat --provider zhipu -m glm-4

调用 GLM Coding 编码模型

hermes chat --provider zhipu-coding -m glm-4-coding

4.5 设为全局默认LLM

编辑 config.yaml 顶层参数，可根据使用场景设置默认模型：

# 日常通用对话场景
default_provider: zhipu
default_model: glm-3-turbo

# 高频编码开发场景
# default_provider: zhipu-coding
# default_model: glm-4-coding

五、企业微信客户端插件安装与CLI对接

Hermes 企业微信网关支持长链接主动拉取模式与 Webhook 回调模式两种接入方式。优先推荐长链接模式：无需公网 IP、无需端口映射、无需将服务暴露到公网，内网环境即可正常运行，安全性与稳定性更高；回调模式依赖公网可达的回调地址，配置繁琐且存在公网暴露风险，不建议使用。

5.1 安装企业微信网关插件

# 网关子系统配置
hermes setup gateway
# 在网关列表选择 WeCom / 企业微信
# 接入模式选择「长链接模式」

5.2 企业微信后台配置步骤

长链接模式（推荐）

仅需获取应用凭证，无需配置回调 URL：

1. 企业微信后台 → 应用管理 → 创建自建应用；
2. 获取 企业ID、应用AgentID、应用Secret；
3. 将三项凭证写入 Hermes 环境变量文件：

WECOM_CORP_ID=xxx
WECOM_AGENT_ID=xxx
WECOM_SECRET=xxx

Webhook 回调模式（不建议）

仅在有明确公网部署需求时使用，需额外配置公网回调地址：

1. 完成上述长链接模式的凭证配置；
2. 配置消息接收 URL：http://部署机器公网IP:8080/wecom/webhook；
3. 在企业微信后台填写 Token 与 EncodingAESKey，并同步写入 Hermes 配置。

5.3 开启网关服务

长链接模式启动（默认推荐）

hermes gateway start --mode longpoll

启动后网关将通过长轮询主动从企业微信拉取消息，全程无需公网入站流量，内网即可正常收发指令。

回调模式启动（不建议）

hermes gateway start --mode webhook

需确保 8080 端口公网可达，且已在企业微信后台配置好回调地址。

启动成功后，即可在企业微信内@应用机器人下发指令，Hermes 执行终端/文件/联网任务并回传结果。

5.4 CLI 主动推送消息至企业微信

hermes send --wecom "服务器巡检已完成，无异常"

六、跨系统双向集成方案

Hermes 支持双向系统集成，覆盖两大核心方向：

1. 正向集成：外部业务系统调用 Hermes 的大模型与智能体能力，Hermes 作为服务端对外提供 HTTP API；
2. 反向集成：Hermes 主动调用第三方业务系统的接口与数据能力，基于 MCP（Model Context Protocol，模型上下文协议） 开放标准实现。

本章详细说明 MCP 标准规范、两种集成方式的落地步骤、自动生成对接技能的方法，以及面向信息系统开发者的接口开发指引。

6.1 正向集成：外部业务系统调用Hermes能力（Hermes作为服务端）

适合将 Hermes 的推理、任务执行、代码生成等能力嵌入到现有业务系统（OA、运维平台、数据中台等）中。

6.1.1 启动Web API服务

hermes serve --host 0.0.0.0 --port 8080

6.1.2 核心开放接口

• 创建会话：POST /api/sessions
• 下发任务指令：POST /api/chat
• 查询执行结果：GET /api/sessions/{id}

6.1.3 鉴权加固

在config.yaml开启API Token校验，避免未授权访问：

api_server:
  enable: true
  auth_token: "自定义强随机密钥"

调用时请求头携带 Authorization: Bearer {auth_token} 即可完成鉴权。

6.2 MCP 标准规范说明

MCP（Model Context Protocol）是一套行业通用的开放标准协议，专门定义了大模型智能体与外部工具、数据系统、业务服务之间的交互规范，是当前 AI Agent 领域应用最广泛的工具互联标准。

6.2.1 核心定位与特性

• 标准化互通：统一的工具声明、入参出参、错误码规范，一次开发即可兼容所有支持 MCP 标准的智能体运行时（Hermes、Claude Desktop 等）；
• 安全可控：原生支持鉴权、细粒度权限控制、操作审计日志；
• 多传输协议：支持 HTTP、WebSocket、Stdio 三种部署形态，适配内网、容器、本地工具等不同场景；
• 能力全覆盖：支持工具调用、资源读取、系统提示模板三类核心交互形态。

6.2.2 标准核心接口

符合 MCP 1.0 规范的服务端，至少需实现两类基础端点：

1. 工具列表接口：向智能体声明自身提供的所有工具、参数说明、返回格式；
2. 工具调用接口：接收智能体的调用请求，执行业务逻辑，返回结构化结果。

6.3 反向集成：第三方系统暴露MCP服务，Hermes主动调用

业务系统按 MCP 标准开发接口后，Hermes 可直接注册并调用系统能力，无需单独开发插件，实现“对话即操作业务系统”。

6.3.1 接入步骤

1. 业务系统实现 MCP 1.0 协议标准的服务端点；
2. 在 Hermes 中注册 MCP 服务源：

hermes mcp add --name business-system --url http://xxx:9000/mcp

1. 查看已接入的 MCP 服务列表：

hermes mcp list

1. 注册完成后，对话中 Hermes 会自动识别并调用对应系统的工具能力。

6.3.2 落地场景示例

示例1：对接企业人事OA系统

• 人事系统按 MCP 标准暴露接口，提供「查询员工考勤」「核算当月薪资」「查询请假记录」三个工具；
• 注册到 Hermes 后，用户可直接对话：“帮我查一下张三本月的考勤统计”，Hermes 会自动调用对应 MCP 接口，拉取数据并整理成自然语言结果返回。

示例2：对接运维监控平台

• 监控系统实现 MCP 接口，提供「查询服务器资源使用率」「获取当前告警列表」「导出巡检报告」工具；
• Hermes 可在定时巡检任务中自动调用接口，生成巡检报告后通过企业微信推送，无需人工登录系统操作。

6.4 Hermes 自动生成双向对接技能

Hermes 自身具备代码生成与能力封装能力，可基于业务系统的现有 API 文档，自动生成符合 MCP 标准的适配层代码与注册配置，大幅降低对接开发量。

操作流程

1. 将业务系统的 API 接口文档、字段说明、鉴权方式提供给 Hermes；
2. 下发指令：“基于这份接口文档，生成符合 MCP 1.0 标准的服务端适配代码，以及 Hermes 侧的注册配置”；
3. Hermes 会自动输出完整的 MCP 适配服务代码（支持 Python/Node.js 等语言）、部署说明、以及 Hermes 端的注册命令；
4. 将适配代码部署到业务系统侧后，执行注册命令即可完成双向连通。

适用场景

• 老系统无 MCP 接口，需要快速适配接入；
• 临时对接单个业务场景，无需投入大量开发资源；
• 快速验证集成方案可行性。

6.5 信息系统开发者 MCP 接口开发指引

面向信息系统开发人员，遵循以下规范开发 MCP 接口，可实现与 Hermes 及所有 MCP 生态智能体的无缝兼容。

开发规范要求

1. 协议版本：遵循 MCP 1.0 官方规范，优先实现工具调用能力，按需扩展资源、提示模板能力；
2. 接口形态：推荐使用 HTTP + JSON 格式，必须实现 tools/list（工具列表）、tools/call（工具调用）两个核心端点；
3. 鉴权要求：必须实现接口鉴权，推荐使用 Bearer Token 方式校验，禁止接口公网裸暴露；
4. 参数规范：入参、出参使用标准 JSON 结构，工具参数需附带清晰的字段说明与类型定义，便于大模型理解调用；
5. 错误处理：统一返回标准错误码与错误信息，方便 Hermes 进行异常处理与用户提示。

验证与上线

开发完成后，可通过 Hermes 自带命令进行连通性与兼容性测试：

# 测试MCP服务连通性
hermes mcp test --name business-system

测试通过后即可正式注册投入使用。

七、安全加固配置

7.1 禁止公网无鉴权访问

1. API服务必须开启auth_token；
2. 绑定监听内网IP，禁止0.0.0.0裸暴露公网；

api_server:
  host: 127.0.0.1
  port: 8080

7.2 命令执行沙箱与权限限制

修改config.yaml开启安全沙箱：

security:
  restrict_shell: true
  forbid_destructive_commands: true
  blocked_commands:
    - rm -rf /
    - chmod 777
    - dd
  working_directory_whitelist:
    - /home/user/work
    - ~/hermes-workspace

7.3 密钥加密存储

敏感Key统一存放~/.hermes/.env，禁止硬编码写入config.yaml；
设置文件权限：

chmod 600 ~/.hermes/.env
chmod 700 ~/.hermes

7.4 配对访问白名单

关闭公网任意接入，仅允许手动审批用户：

# 查看待授权设备
hermes pairing list
# 通过授权
hermes pairing approve
# 拉黑设备
hermes pairing reject

7.5 日志脱敏

开启日志敏感信息自动掩码：

logging:
  mask_secrets: true

八、配置文件路径清单 & 核心配置项

8.1 全路径清单（所有系统统一）

路径	用途
~/.hermes/	全局数据根目录
~/.hermes/config.yaml	主配置文件（必改）
~/.hermes/.env	密钥、API环境变量
~/.hermes/auth.json	Nous OAuth登录凭证
~/.hermes/SOUL.md	Agent人设与系统提示词
~/.hermes/sessions/	历史对话会话
~/.hermes/memories/	长期向量记忆库
~/.hermes/logs/	运行日志
~/.hermes/cron/	定时任务
~/.hermes/skills/	自定义工具技能

8.2 专项论证：Anaconda虚拟环境下【是否需要全局注册 hermes 命令】

核心原理论证

Hermes 通过 pip install -e ".[all]" 可编辑安装后：

1. 仅在当前激活的 Conda 虚拟环境内，系统可识别 hermes 命令；
2. 退出虚拟环境、新开终端、重启电脑后，hermes: command not found；
3. Conda 环境属于隔离环境，不会自动写入系统全局 PATH。

两种场景结论（精准取舍）

场景1：仅开发调试、每次手动 conda activate hermes

不需要执行步骤5全局注册
全程在激活环境内操作即可，干净无冗余、无环境冲突。

场景2：生产常驻、开机自启、任意终端调用、后台服务运行（推荐生产）

必须执行步骤5全局软链接注册
解决：退出conda环境仍可全局调用、桌面GUI启动、serve后台服务、开机自启、企业微信网关常驻运行问题。

最终规范建议

本手册保留原有步骤5命令不变，开发可跳过、生产必执行，兼顾隔离性与实用性。

8.3 config.yaml 高频核心配置项

# 默认大模型服务商
default_provider: zhipu
default_model: glm-3-turbo

# 终端执行权限
terminal:
  auto_confirm: false  # 高危命令手动确认
  timeout: 300

# 联网搜索工具
tools:
  web_search: true
  file_write: true
  computer_use: false

# API服务
api_server:
  enable: false
  host: 127.0.0.1
  port: 8080
  auth_token: "xxx"

# 记忆策略
memory:
  enable_longterm: true
  max_memory_items: 200

8.4 快捷编辑命令

hermes config show    # 查看当前配置
hermes config edit    # 编辑器直接修改
hermes config reset   # 重置配置

九、运维常用命令

会话管理

hermes sessions list
hermes sessions resume 会话名

定时任务

hermes cron add "0 9 * * *" "每日九点巡检磁盘"
hermes cron list

备份与迁移

# 打包全量配置与记忆
tar -zcvf hermes-backup.tar.gz ~/.hermes
# 恢复
tar -zxvf hermes-backup.tar.gz -C ~/

彻底卸载（非Docker）

hermes uninstall
rm -rf ~/.hermes ~/.local/bin/hermes
conda remove -n hermes --all

Docker卸载

docker rm -f hermes-agent
docker rmi ghcr.nju.edu.cn/nousresearch/hermes:latest

日志排查

# 实时查看日志
tail -f ~/.hermes/logs/latest.log

十、信创环境补充说明（麒麟/统信）

1. 若为ARM架构CPU，全部软件（Anaconda、Node、Ollama）下载ARM64架构安装包；
2. mirror-switcher 内适配apt/yum国内源，优先使用工具切换源避免外网下载失败；
3. 禁止使用Docker容器化部署如需符合等保规范，严格使用本手册原生Anaconda虚拟环境方案；
4. 系统防火墙放行端口仅开放内网网段，不暴露公网端口。

十一、常见故障排查

11.1 命令不存在：hermes: command not found

• 未激活conda虚拟环境：执行 conda activate hermes 后重试
• 未配置全局软链接：按照对应系统的步骤5完成全局注册
• PATH未生效：重新执行 source ~/.zshrc（macOS）或 source ~/.bashrc（Linux），或新开终端重试

11.2 pip安装依赖失败

• 未切换国内源：执行 switch-pip tsinghua 后重试
• Python版本不兼容：确保虚拟环境为Python 3.10~3.11，3.12以上可能存在依赖兼容问题
• 缺少系统依赖：macOS安装Xcode命令行工具，Linux安装build-essential、gcc等基础编译工具

11.3 Playwright浏览器安装失败

手动执行安装命令：

playwright install chrome

若网络超时，可设置Playwright国内镜像源后重试。

11.4 初始化向导Nous登录一直转圈

国内网络无法连通Nous官方验证服务器，直接按ESC退出，选择Full setup手动配置自有API或本地Ollama模型即可，无需强制登录。

11.5 桌面端启动失败

• 缺少Node.js环境：按照1.4节安装nvm与Node.js LTS版本
• 缺少系统图形依赖：Linux服务器无桌面环境无法启动GUI，使用hermes serve网页端替代

11.6 企业微信消息无响应

• 检查服务器端口8080是否放行，企业微信后台能否访问回调地址
• 确认WECOM_CORP_ID、WECOM_AGENT_ID、WECOM_SECRET三项凭证填写正确
• 查看日志排查报错：tail -f ~/.hermes/logs/latest.log

需要我补充一份部署验收检查清单，方便你落地验证每一步是否完成吗？

文章摘自：https://www.cnblogs.com/shylock/p/21651382/hermesagent-quan-ping-tai-bu-shu-yun-wei-zhong-wen