Ubuntu 24.04 Hermes Agent 安装

hello_zzw

218人浏览 · 2026-06-26 01:06:42

hello_zzw · 2026-06-26 01:06:42 发布

1. 前置系统环境准备

1.1 替换国内软件源（可选，大幅提速）

# 备份原有源文件
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
# 写入阿里云Ubuntu 24.04源
sudo tee /etc/apt/sources.list <<EOF
deb http://mirrors.aliyun.com/ubuntu/ noble main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ noble-security main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ noble-updates main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ noble-backports main restricted universe multiverse
EOF

# 更新源与系统组件
sudo apt update && sudo apt upgrade -y
# 安装必备基础依赖
sudo apt install -y git curl ripgrep ffmpeg python3-venv build-essential chromium-chromedriver chromium-browser

2. 预装uv包管理器（解决境外pip下载超时）

# 中科大镜像一键安装uv
curl -sL https://mirrors.ustc.edu.cn/github-release/astral-sh/uv/LatestRelease/uv-installer.sh | sh

# 写入国内PyPI镜像永久环境变量
echo 'export UV_INDEX_URL="https://mirrors.aliyun.com/pypi/simple/"' >> ~/.bashrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 验证uv安装成功
uv --version

3. Hermes Agent 国内一键安装脚本

# 国内加速安装（首选）
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash
# 备用ghproxy代理（上方链接失效时使用）
# curl -fsSL https://ghproxy.com/https://raw.githubusercontent.com/NousResearch/HermesAgent/main/install.sh | bash

# 刷新环境变量，加载hermes命令
source ~/.bashrc
# 校验安装
hermes --version

4. 初始化完整自定义配置 `hermes setup` 分步流程

执行配置命令：

hermes setup

4.1 配置模式选择

How would you like to set up Hermes?
  Select by number, Enter to confirm.

  (●)  1. Quick Setup (Nous Portal) — free OAuth login, no API keys, model + tools (recommended)
  (○)  2. Full setup — configure every provider, tool & option yourself (bring your own keys)
  (○)  3. Blank Slate — everything off except the bare minimum; opt in to each capability

Quick Setup：官方云端一键配置，需境外网络，国内易超时
Full setup（本次文档选用）：全自定义，自主配置国产大模型、机器人、本地工具，服务器自用首选
Blank Slate：极简空白模式，所有功能手动逐个开启

操作：光标选中 2. Full setup，回车确认

4.2 大模型推理服务商选择

Select provider:
  ↑↓ navigate  ENTER/SPACE select  ESC cancel

 → (●) Nous Portal (Everything your agent needs, 300+ models with bundled tool use)
   (○) OpenRouter (Pay-per-use API aggregator)
   (○) NovitaAI (Cloud: Model API, Agent Sandbox, GPU Cloud)
   (○) LM Studio (Local desktop app with built-in model server)
   (○) Anthropic (Claude models via API key or Claude Code)
   (○) OpenAI ▸ (Codex CLI or direct OpenAI API)
   (○) xAI Grok ▸ (Direct API or SuperGrok / Premium+ OAuth)
   (○) Xiaomi MiMo (MiMo-V2.5 and V2 models: pro, omni, flash)
   (○) Tencent TokenHub (Hy3 Preview via tokenhub.tencentmaas.com)
   (○) NVIDIA NIM (Nemotron models via build.nvidia.com or local NIM)
   (○) GitHub Copilot ▸ (GitHub token API or copilot --acp process)
   (○) Hugging Face Inference Providers
   (○) Google AI Studio (Native Gemini API)
   (○) DeepSeek (V3, R1, coder, direct API)
   (○) Z.AI / GLM (Zhipu direct API)
   (○) Kimi / Moonshot ▸ (Coding Plan, Moonshot global & China endpoints)
   (○) StepFun Step Plan (Agent / coding models via Step Plan API)
   (○) MiniMax ▸ (Global, OAuth Coding Plan & China endpoints)
   (○) Ollama Cloud (Cloud-hosted open models, ollama.com)
   (○) Arcee AI (Trinity models, direct API)
   (○) GMI Cloud (Multi-model direct API)
   (○) Kilo Code (Kilo Gateway API)
   (○) OpenCode ▸ (Zen pay-as-you-go or Go subscription)

国内可用服务商推荐

DeepSeek（深度求索）、Z.AI / GLM（智谱）、Kimi / Moonshot（月之暗面）、Xiaomi MiMo、Tencent TokenHub
LM Studio：本地离线大模型，无需API密钥

操作示例：选中 DeepSeek 回车，粘贴DeepSeek官网获取的 DEEPSEEK_API_KEY

4.3 默认模型选择（以DeepSeek为例）

Select default model:
  ↑↓ navigate  ENTER/SPACE select  / search  ESC cancel

 → (●) deepseek-v4-flash
   (○) deepseek-v4-pro
   (○) deepseek-reasoner
   (○) deepseek-chat
   (○) Enter custom model name
   (○) Skip (keep current)

deepseek-v4-flash：日常对话、代码、工具调用，性价比最高，推荐默认选中
deepseek-v4-pro：长文档、复杂逻辑分析，单价高于flash
deepseek-reasoner：数学、复杂推理专用

操作：默认 deepseek-v4-flash，按回车确认即可；

复杂文档/项目分析选 deepseek-v4-pro；数学推理场景选 deepseek-reasoner。

4.4 终端运行后端选择

Select terminal backend:
  ↑↓ navigate  ENTER/SPACE select  ESC cancel

   (○) Local - run directly on this machine (default)
   (○) Docker - isolated container with configurable resources
   (○) Modal - serverless cloud sandbox
   (○) SSH - run on a remote machine
   (○) Daytona - persistent cloud development environment
   (○) Singularity/Apptainer - HPC-friendly container
 → (●) Keep current (local)

Local：本机直接运行，无容器隔离，服务器首选
Docker：容器隔离，需预装Docker，运维复杂

操作：默认 Keep current (local)，回车确认；

容器化场景选择Local，HPC高性能集群选对应容器方案。

4.5 第三方聊天机器人平台勾选页面

Select platforms to configure:
  ↑↓ navigate  SPACE toggle  ENTER confirm  ESC cancel

 → [ ] 💬 Mattermost  (not configured)
   [ ] 📡 Signal  (not configured)
   [ ] 💬 Weixin / WeChat  (not configured)
   [ ] 🐧 QQ Bot  (not configured)
   [ ] 💎 Yuanbao  (not configured)
   [ ] 🐳 DingTalk  (not configured)
   [ ] 🎮 Discord  (not configured)
   [ ] 📧 Email  (not configured)
   [ ] 🪽 Feishu / Lark  (not configured)
   [ ] 💬 Google Chat  (not configured)
   [ ] 🏠 Home Assistant  (not configured)
   [ ] 💬 IRC  (not configured)
   [ ] 💚 LINE  (not configured)
   [ ] 🔐 Matrix  (not configured)
   [ ] 🔔 ntfy  (not configured)
   [ ] 📱 iMessage via Photon  (not configured)
   [ ] 🔔 Raft  (not configured)
   [ ] 🔒 SimpleX Chat  (not configured)
   [ ] 💼 Slack  (not configured)
   [ ] 📱 SMS (Twilio)  (not configured)
   [ ] 💼 Microsoft Teams  (not configured)
   [ ] ✈️ Telegram  (not configured)
   [ ] 💼 WeCom (Enterprise WeChat)  (not configured)

操作说明

上下箭头 ↑↓：移动光标
空格键 SPACE：勾选/取消对应平台
回车 ENTER：确认当前勾选，进入下一步
ESC：退出配置向导
[ ] 代表未勾选、未配置；勾选后后续会要求填入对应机器人Token/密钥

全部选项中文释义&国内适配说明

Mattermost：开源团队聊天，国内极少使用
Signal：境外加密通讯软件，国内无法直连
Weixin / WeChat：个人微信机器人，风控严格易封号，不建议配置
BlueBubbles (iMessage)：苹果iMessage，仅Mac设备可用，Ubuntu不支持
QQ Bot：QQ机器人，需申请QQ机器人开发权限
Yuanbao：字节豆包机器人通道
DingTalk：钉钉机器人，国内企业常用，内网/公网均可稳定接入
Discord：海外游戏社群软件，国内无法访问
Email：邮件通知通道，支持收发邮件调用Hermes
Feishu / Lark：飞书机器人，国内企业办公主流，适配性好
Google Chat：谷歌聊天，境外服务
Home Assistant：智能家居联动平台
IRC：老式开源聊天室，现已淘汰
LINE：日韩通讯软件，国内无法直连
Matrix：开源去中心化聊天协议
ntfy：轻量推送通知服务
iMessage via Photon：苹果短信，Ubuntu无支持
Raft：推送通知工具
SimpleX Chat：境外隐私聊天工具
Slack：海外企业办公软件，国内访问不稳定
SMS (Twilio)：海外短信服务，收费且国内无使用场景
Microsoft Teams：微软Teams，国内企业少量使用
Telegram：电报，境外工具，国内无法直连
WeCom (Enterprise WeChat)：企业微信机器人，国内企业办公首选

4.6 飞书机器人配置流程（勾选Feishu后）

4.6.1 机器人创建方式选择

How would you like to set up Feishu / Lark?
  ↑↓ navigate  ENTER/SPACE select  ESC cancel

 → (●) Scan QR code to create a new bot automatically (recommended)
   (○) Enter existing App ID and App Secret manually

界面操作说明

上下箭头切换选项，回车确认选中项；按ESC返回上一级多平台勾选页面。

两个选项中文详细解释

Scan QR code to create a new bot automatically (recommended)【推荐：扫码自动新建飞书机器人】

Hermes 内置一键创建流程，无需手动登录飞书开放平台、创建企业自建应用、配置事件回调。终端会生成链接/二维码，使用飞书App扫码授权后，自动完成机器人创建、权限开通、回调地址配置，自动保存AppID、AppSecret，企业/个人飞书用户都适用，新手首选。

Enter existing App ID and App Secret manually【手动填入已有应用ID与密钥】

适合已经在飞书开放平台创建好自建应用、拿到 App ID 和 App Secret 的用户；选择后手动输入两组凭证，适用于已有现成飞书应用、需要复用机器人的场景。

4.6.2 私聊消息授权规则配置

How should direct messages be authorized?
  ↑↓ navigate  ENTER/SPACE select  ESC cancel

 → (●) Use DM pairing approval (recommended)
   (○) Allow all direct messages
   (○) Only allow listed user IDs

操作说明

上下箭头切换选项，回车确认；ESC返回上一级飞书配置页面。

三个选项完整释义

Use DM pairing approval (recommended)【推荐：私聊配对审批模式】

安全可控模式：任何人第一次私聊机器人都需要提交访问申请，管理员在终端执行命令审核放行；仅审批通过的用户才能调用Hermes。

配套管理命令：

查看待审批用户：hermes pairing list
通过用户申请：hermes pairing approve
拒绝用户申请：hermes pairing reject

适合多人团队、防止无关人员滥用机器人，官方推荐。

Allow all direct messages【允许所有私聊消息】

无门槛开放，飞书内任何人直接私聊机器人即可使用大模型，无需审批。

风险：外部人员、临时访客均可调用，消耗API额度，仅内部封闭小团队使用。

Only allow listed user IDs【仅白名单用户ID可用】

严格白名单模式，只有手动录入到配置文件内的飞书用户ID才能发送指令；所有其他用户直接拦截，不会产生对话消耗。

适合仅固定几个人使用、完全不开放外部人员的场景，需要手动编辑 ~/.hermes/config.yaml 添加用户ID列表。

4.6.3 群聊消息处理规则配置

How should group chats be handled?
  ↑↓ navigate  ENTER/SPACE select  ESC cancel

 → (●) Respond only when @mentioned in groups (recommended)
   (○) Disable group chats

界面操作说明

上下箭头切换选项，回车确认选中配置；ESC返回私聊授权上一页。

两个选项完整释义

Respond only when @mentioned in groups (recommended)【推荐：仅被@时才在群内回复】

群聊默认静默，只有群内成员@机器人时，Hermes才会响应提问、执行工具调用；

优势：不主动刷屏、不占用API额度、避免群内消息频繁触发机器人，团队群聊最优方案。

Disable group chats【完全禁用群聊功能】

机器人不会接收、回复任何群聊消息，仅支持一对一私聊；

适合只需要单人私聊、不希望机器人在任何群内生效的场景。

4.7 后台网关运行方式选择（服务器生产环境）

Choose how the gateway should run in the background:
  ↑↓ navigate  ENTER/SPACE select  ESC cancel

 → (●) User service (no sudo; best for laptops/dev boxes; may need linger after logout)
   (○) System service (starts on boot; requires sudo; still runs as your user)
   (○) Skip service install for now

界面操作说明

上下箭头切换选项，回车确认；ESC返回上一级消息平台配置页面。

三个选项完整释义

**User service (no sudo; best for laptops/**dev boxes; may need linger after logout)【默认推荐：用户级服务，无需sudo，笔记本/开发机首选】

无需root/sudo权限安装，以当前登录普通用户身份运行网关；
适配个人笔记本、开发测试机；
缺陷：系统登出会话后服务可能停止，如需后台常驻需开启 linger 会话持久；
优势：不修改系统全局服务，无权限风险，个人用户首选。

System service (starts on boot; requires sudo**; still runs as your user)【系统全局服务，开机自启，需要 sudo】**

全局systemd系统服务，服务器重启自动开机启动；
安装、管理必须执行sudo；进程依旧以你的普通用户身份运行；
适用场景：长期不关机的云服务器、生产常驻部署；
劣势：需要管理员权限，个人笔记本不推荐。

Skip service install for now【暂时跳过服务安装】

不注册后台常驻服务，本次配置结束后，只能手动在前台执行 hermes 启动网关；关闭终端程序即退出，适合临时测试、短期使用，后续可重新执行 hermes setup 补装服务。

4.8 CLI工具集权限勾选界面（System service系统服务模式）

选定 System service 回车，进入命令行可用工具集勾选配置页面：

Tools for 🖥️  CLI
  ↑↓ navigate  SPACE toggle  ENTER confirm  ESC cancel

 → [✓] 🔍 Web Search & Scraping  (web_search, web_extract)
   [✓] 🌐 Browser Automation  (navigate, click, type, scroll)
   [✓] 💻 Terminal & Processes  (terminal, process)
   [✓] 📁 File Operations  (read, write, patch, search)
   [✓] ⚡ Code Execution  (execute_code)
   [✓] 👁️  Vision / Image Analysis  (vision_analyze)  [no API key]
   [ ] 🎬 Video Analysis  (video_analyze (requires video-capable model))
   [✓] 🎨 Image Generation  (image_generate)
   [ ] 🎬 Video Generation  (video_generate (text-to-video + image-to-video))
   [ ] 🐦 X (Twitter) Search  (x_search (requires xAI OAuth or XAI_API_KEY))
   [ ] 🧠 Mixture of Agents  (mixture_of_agents)  [no API key]
   [✓] 🔊 Text-to-Speech  (text_to_speech)
   [✓] 📚 Skills  (list, view, manage)
   [✓] 📋 Task Planning  (todo)
   [✓] 💾 Memory  (persistent memory across sessions)
   [ ] 🧩 Context Engine  (runtime tools from the active context engine)
   [✓] 🔎 Session Search  (search past conversations)
   [✓] ❓ Clarifying Questions  (clarify)
   [✓] 👥 Task Delegation  (delegate_task)
   [✓] ⏰ Cron Jobs  (create/list/update/pause/resume/run, with optional attached skills)
   [ ] 🏠 Home Assistant  (smart home device control)  [no API key]
   [ ] 🎵 Spotify  (playback, search, playlists, library)
   [ ] 🤖 Yuanbao  (group info, member queries, DM)
   [✓] 🖱️  Computer Use (macOS/Windows/Linux)  (background desktop control via cua-driver)

操作说明

↑↓：上下移动光标
SPACE：勾选/取消当前工具
ENTER：确认当前勾选全部工具，完成整套配置
ESC：返回上一层服务运行模式选择页面
[✓] = 启用该工具；[ ] = 禁用该工具
标注 [no API key]：该功能需要额外对应平台密钥才能完整使用；标注依赖模型/第三方服务的工具需配套资源。

全部工具中文功能说明&国内适配建议

[✓] Web Search & Scraping 网页搜索与网页抓取：联网检索、提取网页正文，日常必备，建议保留勾选
[✓] Browser Automation 浏览器自动化：模拟点击、输入、滚动页面，爬虫/网页操作必备
[✓] Terminal & Processes 终端与进程管理：执行服务器shell命令、查看进程，服务器部署必开
[✓] File Operations 文件读写操作：读写/修改/检索本地文件，本地运维必备
[✓] Code Execution 代码运行：直接执行Python等代码，开发调试推荐开启
[✓] Vision / Image Analysis 图像视觉解析：识别图片内容；无专用视觉模型密钥会受限，不需要识图可取消

Video Analysis 视频解析：需要支持视频理解的大模型，国内模型极少，默认取消

[✓] Image Generation 文生图绘图：AI生成图片，有绘图需求保留勾选

Video Generation 文生视频：视频生成算力消耗极高，国内接口少，默认取消
X (Twitter) Search X推特检索：境外平台无法直连，无需勾选
Mixture of Agents 多智能体协同：需要额外付费API密钥，个人普通使用可关闭

[✓] Text-to-Speech 文字转语音：文本朗读，按需开启
[✓] Skills 技能管理：查看、新增、自定义工具技能，核心功能建议开启
[✓] Task Planning 任务待办：创建todo计划，日程管理常用
[✓] Memory 持久记忆：跨会话保存对话记忆，提升上下文连贯性，推荐开启

Context Engine 上下文引擎扩展：高级多工具联动，普通用户可关闭

[✓] Session Search 历史对话检索：搜索过往聊天记录，实用功能保留
[✓] Clarifying Questions 主动追问澄清：AI遇到模糊问题主动提问，优化对话体验
[✓] Task Delegation 任务委派：拆分复杂任务分步执行，复杂工作流必备
[✓] Cron Jobs 定时任务：创建定时脚本、定时执行指令，服务器自动化必开

Home Assistant 智能家居控制：无智能家居设备取消勾选
Spotify 音乐平台：境外流媒体，国内无法使用，不勾选
Yuanbao 豆包机器人联动：仅对接字节豆包渠道时勾选，纯本地CLI无需开启

[✓] Computer Use 全平台桌面控制：后台操控桌面窗口、鼠标键盘，自动化运维/办公推荐开启

4.9 浏览器自动化驱动选择

Choose a provider:
  ↑↓ navigate  ENTER/SPACE select  ESC cancel

 → (●) Local Browser [★ recommended · free] — Headless Chromium, no API key needed
   (○) Nous Subscription (Browser Use cloud) [subscription] — Managed Browser Use billed to your subscription  ★ via Nous Portal (login on select)
   (○) Camofox [free · local] — Anti-detection browser (Firefox/Camoufox)
   (○) Browser Use [paid] — Cloud browser with remote execution
   (○) Browserbase [paid] — Cloud browser with stealth and proxies
   (○) Firecrawl [paid] — Cloud browser with remote execution
   (○) Skip — keep defaults / configure later

操作说明

上下箭头切换选项，回车确认；ESC返回上一层工具配置页面。

各选项中文释义、优缺点、适用场景

Local Browser【默认推荐，免费本地无头Chrome，无需密钥】
1. 原理：本机内置无头Chromium浏览器，纯本地运行，不调用第三方云服务。
2. 优点：完全免费、无额度限制、不用注册账号、不用API Key、国内可正常访问网页。
3. 缺点：服务器需预装Chrome依赖；易被简单反爬识别。
4. 适用：个人服务器、日常网页浏览/抓取、国内网页场景，绝大多数用户首选，当前已默认选中，直接回车即可。
Nous Subscription（云端Browser Use，付费订阅）
1. 云端托管浏览器，费用计入Nous平台订阅套餐，选择后需要跳转Nous Portal登录账号。
2. 适用：已有Nous付费会员、不想本地部署浏览器的用户；国内访问Nous平台存在网络卡顿问题，不推荐。
Camofox【免费本地防检测火狐浏览器】
1. 本地Camoufox伪装版Firefox，自带指纹伪装、防爬虫检测。
2. 优点：免费、本地运行、反爬能力强，适合有简单反爬页面抓取需求。
3. 缺点：占用服务器资源更高，首次安装依赖体积大。
4. 适用：经常爬取有基础反爬的网页。
Browser Use / Browserbase / Firecrawl 三款付费云浏览器

统一特点：云端远程浏览器，自带代理、指纹隐身、分布式抓取；全部为按量付费，需要注册平台并填入API密钥。

缺点：境外服务商，国内网络访问不稳定、有额外成本，普通自用不推荐。

Skip — 保留默认配置，稍后再设置

跳过浏览器引擎配置，沿用程序内置默认，后续可通过 hermes config edit 重新修改浏览器驱动。

配套前置依赖（选Local Browser后服务器需安装）

sudo apt install chromium-chromedriver chromium-browser

4.10 专项工具独立批量配置环节（Browser、桌面控制、绘图、TTS、识图、网页检索）

浏览器驱动确认回车后，进入批量工具独立配置向导，界面示例：

Hermes Tool Configuration
  Enable or disable tools per platform.
  Tools that need API keys will be configured when enabled.
  Guide: https://hermes-agent.nousresearch.com/docs/user-guide/features/tools


  Configuring 6 tool(s):
    • 🌐 Browser Automation
    • 🖱️  Computer Use (macOS/Windows/Linux)
    • 🎨 Image Generation
    • 🔊 Text-to-Speech
    • 👁️  Vision / Image Analysis
    • 🔍 Web Search & Scraping
  You can skip any tool you don't need right now.


  --- 🌐 Browser Automation - Choose a provider ---

✓   Browser set to local mode
⚠     Node.js not found - browser tools require: npm install (in hermes-agent directory)
✓   Local Browser - no configuration needed!

  --- 🖱️ Computer Use (macOS/Windows/Linux) (cua-driver (background)) ---
    Background computer-use via cua-driver — does NOT steal your cursor or focus. Works with any model.
      Installing cua-driver (background computer-use)...

4.10.1 界面逐段释义

头部总说明

Hermes Tool Configuration：Hermes专项工具批量配置页面

支持分工具开启/关闭；带API密钥需求的工具会单独引导填写凭证
当前共6项工具进入独立配置流程：浏览器自动化、桌面控制、文生图、语音合成、图像识别、网页抓取
暂时不需要的工具可选择Skip跳过配置

🌐 Browser Automation 浏览器自动化模块提示说明

✓ Browser set to local mode：已启用本地无头Chrome驱动
⚠ Node.js not found 警告：系统缺少Node.js运行环境，浏览器前端脚本依赖缺失，需进入项目目录执行 npm install
✓ Local Browser - no configuration needed! 浏览器底层驱动无需密钥，仅缺失Node依赖

🖱️ Computer Use 后台桌面控制模块

底层驱动：cua-driver，后台静默运行，不会抢占鼠标、窗口焦点，兼容所有大模型
Installing cua-driver：程序自动下载、编译安装桌面驱动，等待完成即可

4.10.2 警告与安装提示对应解决方案

方案1：修复 Node.js not found 浏览器依赖警告

安装Node.js 20 LTS版本

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs npm -y
# 校验版本
node -v
npm -v

cd ~/.hermes/hermes-agent
npm install

安装完成后警告自动消除，完整使用网页自动化、页面交互功能。

方案2：cua-driver 桌面驱动安装处理

正常场景：等待自动安装，出现 ✓ cua-driver installed successfully 即完成；
卡住/网络拉取失败手动安装：

cd ~/.hermes/hermes-agent
uv pip install cua-driver

无需桌面自动化功能：工具配置页面选择Skip跳过安装。

4.10.3 其余配套工具简要说明

🔍 Web Search & Scraping：网页检索抓取，Local Browser就绪后无需额外密钥；
👁️ Vision / Image Analysis：图像视觉解析，高精度识图需额外视觉模型API Key，无需求可跳过；
🎨 Image Generation：文生图绘图，启用后引导填入绘图模型密钥；
🔊 Text-to-Speech 文字转语音，本地基础功能免密钥，高级音色需配置。

4.10.4 配置完成收尾

6项工具全部配置/跳过完毕，整套 hermes setup 初始化流程结束，系统自动执行：

生成systemd全局系统开机自启服务；
持久保存大模型、机器人、工具、浏览器全套配置至 ~/.hermes/；
后台自动启动Hermes网关；
输出指引命令：hermes 进入对话、hermes doctor 全环境自检。

5. 配置完成后系统服务管理（System service 开机自启模式）

5.1 常用运维命令

# 查看服务运行状态
systemctl --user status hermes-gateway
# 重启网关服务
systemctl --user restart hermes-gateway
# 停止服务
systemctl --user stop hermes-gateway
# 实时查看运行日志
journalctl --user -u hermes-gateway -f
# 取消开机自启
systemctl --user disable hermes-gateway
# 进入交互对话
hermes
# 校验环境完整性
hermes doctor
# 修改配置文件
hermes config edit
# 查看配对用户申请
hermes pairing list
# 通过用户私聊权限申请
hermes pairing approve
# 拒绝用户申请
hermes pairing reject

6. 国内安装常见卡死解决方案（uv下载失败）

# 手动指定国内镜像执行配置，规避境外源超时
UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/ hermes setup

7. 手动离线安装（GitHub完全无法访问时）

# Gitee国内镜像克隆源码
git clone https://gitee.com/mirrors/HermesAgent.git ~/.hermes/hermes-agent
cd ~/.hermes/hermes-agent
# 创建虚拟环境
uv venv venv --python 3.12
source venv/bin/activate
# 阿里云源安装依赖
UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/ uv pip install -e ".[cli]"
# 全局软链接hermes命令
mkdir -p ~/.local/bin
ln -sf $(pwd)/venv/bin/hermes ~/.local/bin/hermes
source ~/.bashrc
# 验证
hermes --version

8. 卸载 Hermes Agent 完整脚本

# 停止并注销systemd服务
systemctl --user stop hermes-gateway
systemctl --user disable hermes-gateway
rm -rf ~/.config/systemd/user/hermes-gateway.service
systemctl --user daemon-reload

# 删除程序配置与缓存
rm -rf ~/.hermes
# 删除uv工具
rm -rf ~/.cargo ~/.local/bin/uv ~/.local/bin/hermes
# 清除环境变量配置
sed -i '/UV_INDEX_URL/d' ~/.bashrc
sed -i '/PATH="$HOME\/.local\/bin/d' ~/.bashrc
source ~/.bashrc

9. 故障排查汇总

浏览器启动失败：执行 sudo apt install chromium-chromedriver chromium-browser 补全依赖
uv下载超时：执行配置前置的国内镜像环境变量命令，重载bashrc
systemd服务登出后停止：执行 loginctl enable-linger $USER 开启会话持久
机器人扫码链接打不开：切换手机流量，关闭VPN/代理
浏览器工具提示 Node.js not found
1. 原因：未安装node/npm，缺少浏览器自动化前端依赖
2. 解决：安装Node20.x LTS + 进入项目目录执行npm install
cua-driver 桌面驱动安装超时/失败
1. 原因：境外源拉取驱动缓慢
2. 解决：手动执行 uv pip install cua-driver；无需桌面自动化则直接Skip跳过该工具配置