文檔說明

本文檔覆蓋 Docker容器部署 / 原生非Docker部署 兩大架構(gòu)；支持 macOS / Windows / Linux / 銀河麒麟 / 統(tǒng)信UOS；統(tǒng)一使用mirror-switcher 做全鏈路鏡像源切換；Anaconda 管控Python虛擬環(huán)境、nrm/nvm 管理Node.js版本與源；包含企業(yè)微信機(jī)器人接入、MCP雙向系統(tǒng)集成、安全加固、配置詳解、智譜GLM大模型接入全套流程。

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

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

mirror-switcher 是全平臺統(tǒng)一鏡像源切換工具集，覆蓋 pip/conda/npm/brew/docker/git/yum/apt 等 20 種包管理器與開發(fā)環(huán)境，命令格式與 nrm 完全一致，支持一鍵測速、配置備份還原、國產(chǎn)系統(tǒng)自動適配。部署 Hermes 前必須先完成本工具安裝，統(tǒng)一切換國內(nèi)源避免外網(wǎng)下載超時。

• 工具官方倉庫：https://gitee.com/eword/mirror-switcher
• 核心特性：零第三方 Python 依賴、自動注入系統(tǒng) PATH、原生支持銀河麒麟/統(tǒng)信UOS等信創(chuàng)系統(tǒng)、配置修改前自動備份。

1.1 方式A：遠(yuǎn)程一鍵安裝（官方推薦，全自動）

無需手動 git clone，一行命令完成全量工具安裝、軟鏈接注冊、PATH 環(huán)境變量自動寫入，全程免手動配置。

macOS / Linux / 銀河麒麟 / 統(tǒng)信UOS（bash/zsh）

# 國內(nèi)優(yōu)先 Gitee 源，自動識別系統(tǒng)發(fā)行版與架構(gòu)
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

安裝完成后執(zhí)行以下命令，讓當(dāng)前終端立即生效：

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

Windows PowerShell（管理員身份運行）

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

安裝完成后新開 PowerShell 窗口，即可全局調(diào)用所有 switch-* 命令。

自動安裝機(jī)制說明：

1. 優(yōu)先通過 git clone 拉取源碼，支持后續(xù)增量更新；無 git 環(huán)境自動回退到壓縮包安裝
2. 自動注冊全部 20 個 switch-* 命令到系統(tǒng)全局
3. 命令目錄冪等寫入系統(tǒng) PATH，重復(fù)安裝不會重復(fù)污染配置文件
4. 自動識別國產(chǎn)系統(tǒng)（麒麟/統(tǒng)信/openEuler 等），匹配對應(yīng)系統(tǒng)源管理工具

1.2 方式B：源碼本地手動安裝（備選，可定制）

適合離線部署、需修改源碼的場景，通過官方安裝腳本完成標(biāo)準(zhǔn)化注冊。

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

# 一鍵安裝全部工具（自動創(chuàng)建軟鏈接 + 自動寫入系統(tǒng) PATH）
./install.sh

# 可選：僅安裝指定工具
./install.sh --tools=pip,conda,npm

安裝完成后重載 shell 配置即可全局使用。

1.3 一鍵切換國內(nèi)源（部署 Hermes 前必執(zhí)行）

所有工具命令格式統(tǒng)一，與 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：列出所有預(yù)設(shè)源，* 標(biāo)記當(dāng)前生效源
• switch-xxx test：批量測速并按延遲排序
• switch-xxx backup：備份原始配置文件
• switch-xxx restore：從最新備份還原配置

1.4 Node.js 環(huán)境管控：nvm + nrm（兼容方案）

mirror-switcher 自帶 switch-node 可替代 nvm 實現(xiàn)多版本管理；如需沿用傳統(tǒng) nvm 方案，可按以下步驟部署：

安裝 nvm（版本管理器）

macOS/Linux/麒麟/UOS：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc
# 安裝 LTS 穩(wěn)定版 Node
nvm install --lts
nvm use lts

Windows：使用 nvm-windows，執(zhí)行 nvm install lts

nrm 管理 npm 鏡像源

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

二、方案A：非Docker原生部署（推薦，宿主機(jī)直接運行）

通用源碼拉?。℅itee免登錄，無賬號校驗）

# 國內(nèi)鏡像克隆Hermes-Agent源碼
git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git hermes-agent
cd hermes-agent

目錄分離說明：此處克隆的 hermes-agent 為程序源碼目錄，所有用戶配置、會話記錄、密鑰、記憶數(shù)據(jù)均獨立存放在 ~/.hermes/ 目錄下，刪除源碼文件夾不會丟失任何個人配置與數(shù)據(jù)。

2.1 macOS 詳細(xì)部署（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并創(chuàng)建獨立Python環(huán)境

1. 官網(wǎng)下載Anaconda macOS安裝包；
2. 初始化conda：

# 換conda國內(nèi)源
switch-conda tsinghua
# 創(chuàng)建Hermes專屬虛擬環(huán)境，鎖定Python3.11
conda create -n hermes python=3.11
conda activate hermes
# pip換源
switch-pip tsinghua

步驟4 項目本地可編輯安裝

執(zhí)行前請確認(rèn)終端前綴顯示 (hermes)，即已成功激活專屬虛擬環(huán)境。-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部署

安裝Anaconda，啟動Anaconda Prompt；

創(chuàng)建環(huán)境：

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

進(jìn)入源碼目錄執(zhí)行：

pip install -e ".[all]"

全局注冊hermes命令（生產(chǎn)環(huán)境推薦）：

• 找到Anaconda環(huán)境路徑，默認(rèn)位于 C:\ProgramData\anaconda3\envs\hermes\Scripts\hermes.exe
• 右鍵「此電腦」→ 屬性 → 高級系統(tǒng)設(shè)置 → 環(huán)境變量 → 系統(tǒng)變量Path → 編輯 → 新建，填入上述Scripts目錄路徑
• 重啟PowerShell或終端，執(zhí)行 hermes --version 驗證

2.3 Linux x86_64（Ubuntu/Debian/CentOS）

前置：安裝Anaconda

# 下載對應(yīng)架構(gòu)安裝包，以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
# 按提示完成安裝，執(zhí)行初始化
source ~/.bashrc

部署Hermes

# 系統(tǒng)依賴
sudo apt update && sudo apt install git ffmpeg build-essential
# 創(chuàng)建虛擬環(huán)境
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 信創(chuàng)環(huán)境部署

系統(tǒng)適配說明

麒麟基于Linux內(nèi)核，使用yum/dnf包管理器，先用mirror-switcher切換yum源：

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

后續(xù)Anaconda環(huán)境創(chuàng)建、源碼安裝步驟同標(biāo)準(zhǔn)Linux一致；如為ARM飛騰架構(gòu)，下載ARM版Anaconda，其余流程完全相同。

2.5 統(tǒng)信UOS 非Docker部署

switch-apt tsinghua
sudo apt install git ffmpeg make gcc

Anaconda選用對應(yīng)CPU架構(gòu)版本，創(chuàng)建hermes虛擬環(huán)境，pip install -e ".[all]"即可，流程無差異。

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

前置說明

全程國內(nèi)可通、無需外網(wǎng)，包含鏡像加速、持久化掛載、初始化全流程。

步驟1：配置Docker國內(nèi)鏡像加速（必做）

macOS / Linux / 麒麟 / 統(tǒng)信 統(tǒng)一配置：

# 創(chuàng)建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應(yīng)用，服務(wù)器執(zhí)行：sudo systemctl restart docker

步驟2：國內(nèi)加速拉取 Hermes 官方鏡像

# 南京大學(xué)GHCR國內(nèi)鏡像（穩(wěn)定免FQ）
docker pull ghcr.nju.edu.cn/nousresearch/hermes:latest

版本鎖定建議：生產(chǎn)環(huán)境避免使用 latest 滾動標(biāo)簽，可指定固定版本號，例如 docker pull ghcr.nju.edu.cn/nousresearch/hermes:v0.4.0；升級時先拉取新版本鏡像，重建容器即可，配置數(shù)據(jù)因掛載持久化不會丟失。

步驟3：啟動持久化容器（掛載配置目錄、端口映射、后臺常駐）

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

步驟4：進(jìn)入容器執(zhí)行初始化配置

docker exec -it hermes-agent hermes setup

步驟5：容器常用運維命令

# 啟動Web服務(wù)
docker exec -it hermes-agent hermes serve
# 啟動桌面端（僅帶圖形環(huán)境機(jī)器）
docker exec -it hermes-agent hermes desktop
# 環(huán)境自檢
docker exec -it hermes-agent hermes doctor
# 查看日志
docker logs -f hermes-agent

容器持久化說明：掛載 ~/.hermes 宿主機(jī)目錄，所有配置、密鑰、記憶、會話數(shù)據(jù)全部宿主機(jī)留存，刪除容器不丟失數(shù)據(jù)。

三、Hermes 初始化向?qū)Х植脚渲茫ū芸油暾妫?/h2>

執(zhí)行初始化：

hermes setup

部署模式選擇

• Quick Setup：Nous云端OAuth登錄（國內(nèi)網(wǎng)絡(luò)極易超時，不推薦）
• Full setup：自定義全部模型/工具/API（推薦）
• Blank Slate：極簡最小啟動

Terminal backend 終端后端

• 必須選擇：Local - run directly on this machine
• 嚴(yán)禁選擇Docker（原生部署場景）

消息機(jī)器人平臺接入

• 選擇：Skip — set up later with 'hermes setup gateway'
• 后續(xù)如需對接企業(yè)微信再單獨配置網(wǎng)關(guān)。

未授權(quán)用戶訪問策略

默認(rèn) Use DM pairing 配對授權(quán)即可；無外部接入可直接Skip。

圖像生成模型服務(wù)商

• 直接選擇最后一項：Skip — keep defaults / configure later
• 避免境外付費接口與網(wǎng)絡(luò)問題。

初始化完成代表基礎(chǔ)環(huán)境就緒。

常用啟動命令

# 終端對話模式
hermes chat
# 桌面GUI客戶端
hermes desktop
# Web網(wǎng)頁服務(wù)端
hermes serve
# 環(huán)境自檢排錯
hermes doctor
# 編輯主配置
hermes config edit

四、大模型接入：智譜GLM API 詳細(xì)配置

4.1 前置準(zhǔn)備

前往智譜開放平臺注冊應(yīng)用，獲取 API_KEY。智譜提供兩類主流接入方案：

• 通用模型系列：glm-4、glm-3-turbo、glm-5 等通用對話模型，通用 API 端點
• GLM Coding Plan 編碼套餐：面向高頻編碼場景的訂閱制套餐，獨立編碼專用路徑，深度適配代碼生成、調(diào)試、重構(gòu)場景
• 通用接口默認(rèn)端點：https://open.bigmodel.cn/api/paas/v4/
• Coding 套餐專用路徑：https://open.bigmodel.cn/api/coding/paas/v4/ 下編碼模型專屬通道，模型名使用編碼系列標(biāo)識。

4.2 方式1：命令行寫入環(huán)境密鑰（推薦，統(tǒng)一存入 .env）

所有 API Key 統(tǒng)一寫入 Hermes 私有環(huán)境變量文件 ~/.hermes/.env，禁止硬編碼到配置文件。通用模型與 GLM Coding 套餐共用同一 API Key，按模型名區(qū)分調(diào)用通道。

# 寫入智譜API密鑰，通用模型與Coding套餐通用
echo "ZHIPU_API_KEY=你的密鑰" >> ~/.hermes/.env

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

在 providers 節(jié)點新增智譜配置片段，通過 ${ZHIPU_API_KEY} 引用環(huán)境變量中的密鑰。

通用模型配置

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

GLM Coding 編碼套餐配置

如需使用編碼套餐專屬能力，可單獨聲明編碼服務(wù)商節(jié)點，指定編碼系列模型：

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 指定模型啟動對話

調(diào)用通用對話模型

hermes chat --provider zhipu -m glm-4

調(diào)用 GLM Coding 編碼模型

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

4.5 設(shè)為全局默認(rèn)LLM

編輯 config.yaml 頂層參數(shù)，可根據(jù)使用場景設(shè)置默認(rèn)模型：

# 日常通用對話場景
default_provider: zhipu
default_model: glm-3-turbo

# 高頻編碼開發(fā)場景
# default_provider: zhipu-coding
# default_model: glm-4-coding

五、企業(yè)微信客戶端插件安裝與CLI對接

Hermes 企業(yè)微信網(wǎng)關(guān)支持長鏈接主動拉取模式與 Webhook 回調(diào)模式兩種接入方式。優(yōu)先推薦長鏈接模式：無需公網(wǎng) IP、無需端口映射、無需將服務(wù)暴露到公網(wǎng)，內(nèi)網(wǎng)環(huán)境即可正常運行，安全性與穩(wěn)定性更高；回調(diào)模式依賴公網(wǎng)可達(dá)的回調(diào)地址，配置繁瑣且存在公網(wǎng)暴露風(fēng)險，不建議使用。

5.1 安裝企業(yè)微信網(wǎng)關(guān)插件

# 網(wǎng)關(guān)子系統(tǒng)配置
hermes setup gateway
# 在網(wǎng)關(guān)列表選擇 WeCom / 企業(yè)微信
# 接入模式選擇「長鏈接模式」

5.2 企業(yè)微信后臺配置步驟

長鏈接模式（推薦）

僅需獲取應(yīng)用憑證，無需配置回調(diào) URL：

1. 企業(yè)微信后臺 → 應(yīng)用管理 → 創(chuàng)建自建應(yīng)用；
2. 獲取 企業(yè)ID、應(yīng)用AgentID、應(yīng)用Secret；
3. 將三項憑證寫入 Hermes 環(huán)境變量文件：

WECOM_CORP_ID=xxx
WECOM_AGENT_ID=xxx
WECOM_SECRET=xxx

Webhook 回調(diào)模式（不建議）

僅在有明確公網(wǎng)部署需求時使用，需額外配置公網(wǎng)回調(diào)地址：

1. 完成上述長鏈接模式的憑證配置；
2. 配置消息接收 URL：http://部署機(jī)器公網(wǎng)IP:8080/wecom/webhook；
3. 在企業(yè)微信后臺填寫 Token 與 EncodingAESKey，并同步寫入 Hermes 配置。

5.3 開啟網(wǎng)關(guān)服務(wù)

長鏈接模式啟動（默認(rèn)推薦）

hermes gateway start --mode longpoll

啟動后網(wǎng)關(guān)將通過長輪詢主動從企業(yè)微信拉取消息，全程無需公網(wǎng)入站流量，內(nèi)網(wǎng)即可正常收發(fā)指令。

回調(diào)模式啟動（不建議）

hermes gateway start --mode webhook

需確保 8080 端口公網(wǎng)可達(dá)，且已在企業(yè)微信后臺配置好回調(diào)地址。

啟動成功后，即可在企業(yè)微信內(nèi)@應(yīng)用機(jī)器人下發(fā)指令，Hermes 執(zhí)行終端/文件/聯(lián)網(wǎng)任務(wù)并回傳結(jié)果。

5.4 CLI 主動推送消息至企業(yè)微信

hermes send --wecom "服務(wù)器巡檢已完成，無異常"

六、跨系統(tǒng)雙向集成方案

Hermes 支持雙向系統(tǒng)集成，覆蓋兩大核心方向：

1. 正向集成：外部業(yè)務(wù)系統(tǒng)調(diào)用 Hermes 的大模型與智能體能力，Hermes 作為服務(wù)端對外提供 HTTP API；
2. 反向集成：Hermes 主動調(diào)用第三方業(yè)務(wù)系統(tǒng)的接口與數(shù)據(jù)能力，基于 MCP（Model Context Protocol，模型上下文協(xié)議） 開放標(biāo)準(zhǔn)實現(xiàn)。

本章詳細(xì)說明 MCP 標(biāo)準(zhǔn)規(guī)范、兩種集成方式的落地步驟、自動生成對接技能的方法，以及面向信息系統(tǒng)開發(fā)者的接口開發(fā)指引。

6.1 正向集成：外部業(yè)務(wù)系統(tǒng)調(diào)用Hermes能力（Hermes作為服務(wù)端）

適合將 Hermes 的推理、任務(wù)執(zhí)行、代碼生成等能力嵌入到現(xiàn)有業(yè)務(wù)系統(tǒng)（OA、運維平臺、數(shù)據(jù)中臺等）中。

啟動Web API服務(wù)

hermes serve --host 0.0.0.0 --port 8080

核心開放接口

• 創(chuàng)建會話：POST /api/sessions
• 下發(fā)任務(wù)指令：POST /api/chat
• 查詢執(zhí)行結(jié)果：GET /api/sessions/{id}

鑒權(quán)加固

在config.yaml開啟API Token校驗，避免未授權(quán)訪問：

api_server:
  enable: true
  auth_token: "自定義強(qiáng)隨機(jī)密鑰"

調(diào)用時請求頭攜帶 Authorization: Bearer {auth_token} 即可完成鑒權(quán)。

6.2 MCP 標(biāo)準(zhǔn)規(guī)范說明

MCP（Model Context Protocol）是一套行業(yè)通用的開放標(biāo)準(zhǔn)協(xié)議，專門定義了大模型智能體與外部工具、數(shù)據(jù)系統(tǒng)、業(yè)務(wù)服務(wù)之間的交互規(guī)范，是當(dāng)前 AI Agent 領(lǐng)域應(yīng)用最廣泛的工具互聯(lián)標(biāo)準(zhǔn)。

核心定位與特性

• 標(biāo)準(zhǔn)化互通：統(tǒng)一的工具聲明、入?yún)⒊鰠?、錯誤碼規(guī)范，一次開發(fā)即可兼容所有支持 MCP 標(biāo)準(zhǔn)的智能體運行時（Hermes、Claude Desktop 等）；
• 安全可控：原生支持鑒權(quán)、細(xì)粒度權(quán)限控制、操作審計日志；
• 多傳輸協(xié)議：支持 HTTP、WebSocket、Stdio 三種部署形態(tài)，適配內(nèi)網(wǎng)、容器、本地工具等不同場景；
• 能力全覆蓋：支持工具調(diào)用、資源讀取、系統(tǒng)提示模板三類核心交互形態(tài)。

標(biāo)準(zhǔn)核心接口

符合 MCP 1.0 規(guī)范的服務(wù)端，至少需實現(xiàn)兩類基礎(chǔ)端點：

1. 工具列表接口：向智能體聲明自身提供的所有工具、參數(shù)說明、返回格式；
2. 工具調(diào)用接口：接收智能體的調(diào)用請求，執(zhí)行業(yè)務(wù)邏輯，返回結(jié)構(gòu)化結(jié)果。

6.3 反向集成：第三方系統(tǒng)暴露MCP服務(wù)，Hermes主動調(diào)用

業(yè)務(wù)系統(tǒng)按 MCP 標(biāo)準(zhǔn)開發(fā)接口后，Hermes 可直接注冊并調(diào)用系統(tǒng)能力，無需單獨開發(fā)插件，實現(xiàn)“對話即操作業(yè)務(wù)系統(tǒng)”。

接入步驟

業(yè)務(wù)系統(tǒng)實現(xiàn) MCP 1.0 協(xié)議標(biāo)準(zhǔn)的服務(wù)端點；

在 Hermes 中注冊 MCP 服務(wù)源：

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

查看已接入的 MCP 服務(wù)列表：

hermes mcp list

注冊完成后，對話中 Hermes 會自動識別并調(diào)用對應(yīng)系統(tǒng)的工具能力。

落地場景示例

示例1：對接企業(yè)人事OA系統(tǒng)

• 人事系統(tǒng)按 MCP 標(biāo)準(zhǔn)暴露接口，提供「查詢員工考勤」「核算當(dāng)月薪資」「查詢請假記錄」三個工具；
• 注冊到 Hermes 后，用戶可直接對話：“幫我查一下張三本月的考勤統(tǒng)計”，Hermes 會自動調(diào)用對應(yīng) MCP 接口，拉取數(shù)據(jù)并整理成自然語言結(jié)果返回。

示例2：對接運維監(jiān)控平臺

• 監(jiān)控系統(tǒng)實現(xiàn) MCP 接口，提供「查詢服務(wù)器資源使用率」「獲取當(dāng)前告警列表」「導(dǎo)出巡檢報告」工具；
• Hermes 可在定時巡檢任務(wù)中自動調(diào)用接口，生成巡檢報告后通過企業(yè)微信推送，無需人工登錄系統(tǒng)操作。

6.4 Hermes 自動生成雙向?qū)蛹寄?/h3>

Hermes 自身具備代碼生成與能力封裝能力，可基于業(yè)務(wù)系統(tǒng)的現(xiàn)有 API 文檔，自動生成符合 MCP 標(biāo)準(zhǔn)的適配層代碼與注冊配置，大幅降低對接開發(fā)量。

操作流程

1. 將業(yè)務(wù)系統(tǒng)的 API 接口文檔、字段說明、鑒權(quán)方式提供給 Hermes；
2. 下發(fā)指令：“基于這份接口文檔，生成符合 MCP 1.0 標(biāo)準(zhǔn)的服務(wù)端適配代碼，以及 Hermes 側(cè)的注冊配置”；
3. Hermes 會自動輸出完整的 MCP 適配服務(wù)代碼（支持 Python/Node.js 等語言）、部署說明、以及 Hermes 端的注冊命令；
4. 將適配代碼部署到業(yè)務(wù)系統(tǒng)側(cè)后，執(zhí)行注冊命令即可完成雙向連通。

適用場景

• 老系統(tǒng)無 MCP 接口，需要快速適配接入；
• 臨時對接單個業(yè)務(wù)場景，無需投入大量開發(fā)資源；
• 快速驗證集成方案可行性。

6.5 信息系統(tǒng)開發(fā)者 MCP 接口開發(fā)指引

面向信息系統(tǒng)開發(fā)人員，遵循以下規(guī)范開發(fā) MCP 接口，可實現(xiàn)與 Hermes 及所有 MCP 生態(tài)智能體的無縫兼容。

開發(fā)規(guī)范要求

1. 協(xié)議版本：遵循 MCP 1.0 官方規(guī)范，優(yōu)先實現(xiàn)工具調(diào)用能力，按需擴(kuò)展資源、提示模板能力；
2. 接口形態(tài)：推薦使用 HTTP + JSON 格式，必須實現(xiàn) tools/list（工具列表）、tools/call（工具調(diào)用）兩個核心端點；
3. 鑒權(quán)要求：必須實現(xiàn)接口鑒權(quán)，推薦使用 Bearer Token 方式校驗，禁止接口公網(wǎng)裸暴露；
4. 參數(shù)規(guī)范：入?yún)?、出參使用?biāo)準(zhǔn) JSON 結(jié)構(gòu)，工具參數(shù)需附帶清晰的字段說明與類型定義，便于大模型理解調(diào)用；
5. 錯誤處理：統(tǒng)一返回標(biāo)準(zhǔn)錯誤碼與錯誤信息，方便 Hermes 進(jìn)行異常處理與用戶提示。

驗證與上線

開發(fā)完成后，可通過 Hermes 自帶命令進(jìn)行連通性與兼容性測試：

# 測試MCP服務(wù)連通性
hermes mcp test --name business-system

測試通過后即可正式注冊投入使用。

七、安全加固配置

命令執(zhí)行沙箱與權(quán)限限制

修改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

密鑰加密存儲

敏感Key統(tǒng)一存放~/.hermes/.env，禁止硬編碼寫入config.yaml；

設(shè)置文件權(quán)限：

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

配對訪問白名單

關(guān)閉公網(wǎng)任意接入，僅允許手動審批用戶：

# 查看待授權(quán)設(shè)備
hermes pairing list
# 通過授權(quán)
hermes pairing approve
# 拉黑設(shè)備
hermes pairing reject

日志脫敏

開啟日志敏感信息自動掩碼：

logging:
  mask_secrets: true

八、配置文件路徑清單 & 核心配置項

8.1 全路徑清單（所有系統(tǒng)統(tǒng)一）

8.2 專項論證：Anaconda虛擬環(huán)境下【是否需要全局注冊 hermes 命令】

核心原理論證

Hermes 通過 pip install -e ".[all]" 可編輯安裝后：

1. 僅在當(dāng)前激活的 Conda 虛擬環(huán)境內(nèi)，系統(tǒng)可識別 hermes 命令；
2. 退出虛擬環(huán)境、新開終端、重啟電腦后，hermes: command not found；
3. Conda 環(huán)境屬于隔離環(huán)境，不會自動寫入系統(tǒng)全局 PATH。

兩種場景結(jié)論（精準(zhǔn)取舍）

場景1：僅開發(fā)調(diào)試、每次手動 conda activate hermes

不需要執(zhí)行步驟5全局注冊：全程在激活環(huán)境內(nèi)操作即可，干凈無冗余、無環(huán)境沖突。

場景2：生產(chǎn)常駐、開機(jī)自啟、任意終端調(diào)用、后臺服務(wù)運行（推薦生產(chǎn)）

必須執(zhí)行步驟5全局軟鏈接注冊：解決：退出conda環(huán)境仍可全局調(diào)用、桌面GUI啟動、serve后臺服務(wù)、開機(jī)自啟、企業(yè)微信網(wǎng)關(guān)常駐運行問題。

最終規(guī)范建議

本手冊保留原有步驟5命令不變，開發(fā)可跳過、生產(chǎn)必執(zhí)行，兼顧隔離性與實用性。

8.3 config.yaml 高頻核心配置項

# 默認(rèn)大模型服務(wù)商
default_provider: zhipu
default_model: glm-3-turbo
# 終端執(zhí)行權(quán)限
terminal:
  auto_confirm: false  # 高危命令手動確認(rèn)
  timeout: 300
# 聯(lián)網(wǎng)搜索工具
tools:
  web_search: true
  file_write: true
  computer_use: false
# API服務(wù)
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    # 查看當(dāng)前配置
hermes config edit    # 編輯器直接修改
hermes config reset   # 重置配置

九、運維常用命令

會話管理

hermes sessions list
hermes sessions resume 會話名

定時任務(wù)

hermes cron add "0 9 * * *" "每日九點巡檢磁盤"
hermes cron list

備份與遷移

# 打包全量配置與記憶
tar -zcvf hermes-backup.tar.gz ~/.hermes
# 恢復(fù)
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

十、信創(chuàng)環(huán)境補(bǔ)充說明（麒麟/統(tǒng)信）

1. 若為ARM架構(gòu)CPU，全部軟件（Anaconda、Node、Ollama）下載ARM64架構(gòu)安裝包；
2. mirror-switcher 內(nèi)適配apt/yum國內(nèi)源，優(yōu)先使用工具切換源避免外網(wǎng)下載失??；
3. 禁止使用Docker容器化部署如需符合等保規(guī)范，嚴(yán)格使用本手冊原生Anaconda虛擬環(huán)境方案；
4. 系統(tǒng)防火墻放行端口僅開放內(nèi)網(wǎng)網(wǎng)段，不暴露公網(wǎng)端口。

十一、常見故障排查

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

• 未激活conda虛擬環(huán)境：執(zhí)行 conda activate hermes 后重試
• 未配置全局軟鏈接：按照對應(yīng)系統(tǒng)的步驟5完成全局注冊
• PATH未生效：重新執(zhí)行 source ~/.zshrc（macOS）或 source ~/.bashrc（Linux），或新開終端重試

11.2 pip安裝依賴失敗

• 未切換國內(nèi)源：執(zhí)行 switch-pip tsinghua 后重試
• Python版本不兼容：確保虛擬環(huán)境為Python 3.10~3.11，3.12以上可能存在依賴兼容問題
• 缺少系統(tǒng)依賴：macOS安裝Xcode命令行工具，Linux安裝 build-essential、gcc等基礎(chǔ)編譯工具

11.3 Playwright瀏覽器安裝失敗

手動執(zhí)行安裝命令：

playwright install chrome

若網(wǎng)絡(luò)超時，可設(shè)置Playwright國內(nèi)鏡像源后重試。

11.4 初始化向?qū)ous登錄一直轉(zhuǎn)圈

國內(nèi)網(wǎng)絡(luò)無法連通Nous官方驗證服務(wù)器，直接按ESC退出，選擇Full setup手動配置自有API或本地Ollama模型即可，無需強(qiáng)制登錄。

11.5 桌面端啟動失敗

• 缺少Node.js環(huán)境：按照1.4節(jié)安裝nvm與Node.js LTS版本
• 缺少系統(tǒng)圖形依賴：Linux服務(wù)器無桌面環(huán)境無法啟動GUI，使用hermes serve網(wǎng)頁端替代

11.6 企業(yè)微信消息無響應(yīng)

• 檢查服務(wù)器端口8080是否放行，企業(yè)微信后臺能否訪問回調(diào)地址
• 確認(rèn)WECOM_CORP_ID、WECOM_AGENT_ID、WECOM_SECRET三項憑證填寫正確
• 查看日志排查報錯：tail -f ~/.hermes/logs/latest.log

以上就是Hermes Agent全平臺部署運維中文安裝配置手冊(2026)的詳細(xì)內(nèi)容，更多關(guān)于Hermes Agent部署的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論