Hermes Agent安装、使用方法详细全解

洛星核

744人浏览 · 2026-06-04 09:21:50

洛星核 · 2026-06-04 09:21:50 发布

Hermes Agent 安装、使用方法详细全解

数据来源：Hermes Agent 官方文档 (hermes-agent.nousresearch.com/docs)、GitHub 仓库

Hermes Agent 概述
安装指南
配置指南
快速入门
CLI 命令参考
会话内斜杠命令
AI 服务商配置
工具与工具集
记忆系统
技能系统
MCP 集成
定时任务 (Cron)
Profiles 多配置
子代理委派与多代理
消息网关 (Gateway)
语音 STT/TTS
安全与隐私
会话管理
Kanban 协作看板
常见问题与故障排除

一、Hermes Agent 概述

Hermes Agent 是由 Nous Research 构建的开源自改进 AI 智能体框架。它运行在终端、消息平台和 IDE 中，与 Claude Code（Anthropic）、Codex（OpenAI）、OpenClaw 属于同类产品——通过工具调用与系统交互的自主编码和任务执行智能体。

核心特性

内置学习循环（技能系统）：从经验中创建可复用技能（Skills），在使用过程中不断改进，使 Agent 越来越了解你的任务和偏好
跨会话持久化记忆：记住用户身份、偏好、环境信息和经验教训，支持可插拔记忆后端（内置、Holographic、Honcho、Mem0 等）
多平台网关：同一 Agent 运行在 Telegram、Discord、Slack、WhatsApp、钉钉、飞书、企业微信等 10+ 平台，完整工具访问权限
服务商无关：支持 20+ LLM 提供商（OpenRouter、Anthropic、OpenAI、DeepSeek、通义千问、Kimi、MiniMax 等），支持凭证池自动轮换 API Key
Profiles 多配置：运行多个独立 Hermes 实例，隔离配置、会话、技能和记忆
高度可扩展：插件、MCP 服务器、自定义工具、Webhook 触发器、Cron 定时任务和完整的 Python 生态系统

应用场景

软件开发、研究、系统管理、数据分析、内容创作、智能家居、以及任何受益于持久上下文和完整系统访问权限的 AI 智能体任务。

技术栈

语言：Python
包管理：uv
会话存储：SQLite
配置格式：YAML
支持平台：Linux、macOS、Windows（原生 + WSL2）、Android（Termux）

二、安装指南

2.1 系统要求

项目	要求
操作系统	Linux、macOS、Windows 10/11、WSL2、Android (Termux)
架构	x86_64、ARM64（Apple Silicon）
网络	需要互联网连接（下载依赖 + API 调用）
磁盘空间	约 2-4 GB（含 Python 环境、Node.js、依赖等）

2.2 Linux / macOS / WSL2 安装

一行命令完成安装（基于 Git，跟踪 main 分支）：

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

安装程序做了什么？

安装程序是完整的自动化脚本，依次完成：

安装 uv（Python 包管理器）
安装 Python 3.11
安装 Node.js 22
安装 ripgrep（代码搜索工具）
安装 ffmpeg（音视频处理）
克隆 hermes-agent 仓库到本地
创建 Python 虚拟环境
将 hermes 命令添加到系统 PATH

普通用户 vs 根用户安装

模式	安装路径	说明
普通用户（推荐）	`~/.hermes/`	不需要 root 权限，仅当前用户可用
根用户	系统级目录	所有用户可用，需要 root 权限

2.3 Windows 原生安装

Windows 无需 WSL 即可原生运行 Hermes——CLI、Gateway、TUI 和所有工具均支持。

安装步骤

打开 PowerShell，以管理员身份运行：

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

Windows 安装程序处理的依赖

安装程序处理所有依赖，包括：

uv、Python 3.11
Node.js 22
ripgrep、ffmpeg
便携式 Git Bash（PortableGit）：自包含的 Git-for-Windows 发行版，提供 bash.exe 和完整的 POSIX 工具链

Windows 特别注意事项

项目	说明
安装路径	`%LOCALAPPDATA%\hermes\hermes-agent`
PATH 配置	`hermes` 命令自动添加到用户 PATH
终端重启	安装完成后需要重启终端或打开新的 PowerShell 窗口
Git 处理	如果 PATH 中已有 git，安装程序直接使用现有安装
64 位系统	安装 PortableGit（含 bash.exe 和完整 POSIX 工具链）
32 位系统	回退使用 MinGit（缺少 bash，禁用 terminal-tool 和 agent-browser 功能）
输入方式	Alt+Enter 不插入换行（Windows Terminal 拦截为全屏），使用 Ctrl+Enter

2.4 Android（Termux）安装

使用与 Linux 相同的命令，安装程序会自动检测 Termux 环境：

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

2.5 桌面版应用程序

提供图形化安装程序：

macOS：签名/公证的安装包
Windows：安装程序 + 校验和文件

下载地址：GitHub Releases 页面

2.6 安装后验证

# 检查安装
hermes --version

# 运行诊断
hermes doctor

# 检查配置
hermes config check

2.7 更新

hermes update

2.8 卸载

hermes uninstall

三、配置指南

3.1 配置文件位置

文件	路径	说明
主配置	`~/.hermes/config.yaml`	所有设置
API 密钥	`~/.hermes/.env`	密钥和敏感信息
OAuth 令牌	`~/.hermes/auth.json`	OAuth 凭证和凭证池
会话存储	`~/.hermes/sessions/`	对话记录
日志文件	`~/.hermes/logs/`	网关和错误日志
技能目录	`~/.hermes/skills/`	已安装的技能
源代码	`~/.hermes/hermes-agent/`	Git 安装的源码

3.2 交互式配置向导

hermes setup              # 完整交互式向导
hermes setup --portal     # 使用 Nous Portal（推荐，一条 OAuth 覆盖模型+工具）
hermes setup model        # 仅配置模型
hermes setup terminal     # 仅配置终端
hermes setup gateway      # 仅配置网关
hermes setup tools        # 仅配置工具
hermes setup agent        # 仅配置 Agent

3.3 config.yaml 完整结构

# ==================== 模型配置 ====================
model:
  default: "qwen3-coder-plus"          # 默认模型
  provider: "alibaba"                   # 服务商：nous, openrouter, anthropic, alibaba, deepseek 等
  base_url: ""                          # 自定义端点（可选）
  api_key: ""                           # API Key（可选，推荐放在 .env 中）
  context_length: 128000                # 上下文长度

# ==================== 服务商配置 ====================
# 在 .env 文件中设置 API Key，例如：
# DASHSCOPE_API_KEY=sk-xxx
# DEEPSEEK_API_KEY=sk-xxx

# ==================== Agent 配置 ====================
agent:
  max_turns: 90                         # 每轮最大工具调用次数
  tool_use_enforcement: true            # 强制工具使用

# ==================== 终端配置 ====================
terminal:
  backend: "local"                      # local, docker, ssh, modal, singularity
  cwd: ""                               # 工作目录（可选）
  timeout: 180                          # 命令超时（秒）

# ==================== 上下文压缩 ====================
compression:
  enabled: true                         # 启用自动上下文压缩
  threshold: 0.50                       # 触发阈值（50% 上下文使用率）
  target_ratio: 0.20                    # 压缩目标比率

# ==================== 显示配置 ====================
display:
  skin: "default"                       # 主题
  tool_progress: true                   # 显示工具进度
  show_reasoning: false                 # 显示推理过程
  show_cost: true                       # 显示 Token 成本

# ==================== 语音转文字 (STT) ====================
stt:
  enabled: true
  provider: "local"                     # local, groq, openai, mistral
  local:
    model: "base"                       # tiny, base, small, medium, large-v3

# ==================== 文字转语音 (TTS) ====================
tts:
  enabled: true
  provider: "edge"                      # edge, elevenlabs, openai, minimax, mistral
  voice: "zh-CN-XiaoxiaoNeural"        # Edge TTS 中文语音

# ==================== 记忆系统 ====================
memory:
  memory_enabled: true
  user_profile_enabled: true
  provider:              # 空=内置, holographic, honcho, mem0 等

# ==================== 安全配置 ====================
security:
  tirith_enabled: true                  # 安全扫描
  redact_secrets: false                 # 自动脱敏（默认关闭）
  website_blocklist: []                 # 网站黑名单

# ==================== 命令审批 ====================
approvals:
  mode: "manual"                        # manual, smart, off

# ==================== 委派配置 ====================
delegation:
  max_iterations: 50                    # 子代理最大轮次
  max_concurrent_children: 3            # 并行子代理数
  max_spawn_depth: 1                    # 委派深度
  orchestrator_enabled: true            # 编排者模式
  child_timeout_seconds: 600            # 子代理超时
  model: ""                             # 子代理专用模型（可选）
  provider: ""                          # 子代理专用服务商（可选）

# ==================== 文件检查点 ====================
checkpoints:
  enabled: true
  max_snapshots: 50                     # 最大快照数

# ==================== 备用服务商 ====================
fallback_providers:
  - provider: "openrouter"
    model: "anthropic/claude-sonnet-4"
  - provider: "alibaba"
    model: "qwen3.5-plus"

# ==================== 模型别名 ====================
model_aliases:
  qwen:
    model: "qwen3-coder-plus"
    provider: "alibaba"
  deepseek:
    model: "deepseek-chat"
    provider: "deepseek"
  local-qwen:
    model: "qwen2.5-coder:32b"
    provider: "custom"
    base_url: "http://localhost:11434/v1"

# ==================== 辅助模型 ====================
auxiliary:
  vision:
    provider: "auto"                    # auto, 或指定服务商
    model: ""
  compression:
    provider: "auto"
    model: ""

3.4 配置操作命令

hermes config               # 查看当前配置
hermes config edit          # 在 $EDITOR 中打开 config.yaml
hermes config set KEY VAL   # 设置配置值
hermes config path          # 打印 config.yaml 路径
hermes config env-path      # 打印 .env 路径
hermes config check         # 检查缺失/过时的配置
hermes config migrate       # 更新配置以包含新选项

3.5 环境变量 (.env)

所有 API 密钥和敏感信息应放在 ~/.hermes/.env 文件中：

# 通义千问 / 阿里云
DASHSCOPE_API_KEY=sk-xxx

# DeepSeek
DEEPSEEK_API_KEY=sk-xxx

# Kimi / 月之暗面
KIMI_API_KEY=sk-xxx
KIMI_CN_API_KEY=sk-xxx

# MiniMax
MINIMAX_API_KEY=sk-xxx
MINIMAX_CN_API_KEY=sk-xxx

# 智谱 GLM
GLM_API_KEY=sk-xxx

# 腾讯混元
TOKENHUB_API_KEY=sk-xxx

# 阶跃星辰
STEPFUN_API_KEY=sk-xxx

# 小米 MiMo
XIAOMI_API_KEY=sk-xxx

# 国际服务商
OPENROUTER_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-xxx
OPENAI_API_KEY=sk-xxx

四、快速入门

4.1 第一步：安装

# Linux / macOS / WSL2
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

4.2 第二步：配置

推荐方式（最快路径）：

hermes setup --portal

一条 OAuth 认证即可覆盖模型以及全部四个 Tool Gateway 工具（网页搜索、图片生成、TTS 语音合成、浏览器）。

手动配置方式：

hermes model    # 交互式选择服务商和模型

4.3 第三步：首次对话

hermes

启动后，Hermes Agent 会显示交互式 TUI 界面。你可以：

直接对话：像聊天一样与 Agent 交流
执行任务：让 Agent 完成文件操作、代码编写、网页搜索等任务
单次提问：hermes chat -q "法国的首都是哪里？"

4.4 第四步：体验核心功能

记忆系统：

> 我主要使用 Python 和 TypeScript 开发

Agent 会将你的偏好存储在持久化记忆中，未来会话自动考虑。

技能系统：

> 帮我写一个 REST API 服务器

Agent 完成后会自动记住这个模式，下次类似任务更准确。

工具调用：
Agent 拥有 60+ 内置工具，包括文件系统、Shell、浏览器、代码执行等。

会话恢复：

hermes --continue    # 恢复最近的会话
hermes --resume <会话ID>    # 恢复特定会话

五、CLI 命令参考

5.1 全局入口

hermes [全局选项] <命令> [子命令/选项]

不指定子命令时默认为 chat。

5.2 全局选项

选项	说明
`--version, -V`	显示版本
`--profile, -p NAME`	使用指定 Profile
`--resume, -r SESSION`	通过 ID 或标题恢复会话
`--continue, -c [NAME]`	恢复最近或匹配的会话
`--worktree, -w`	隔离 git worktree 模式（并行代理）
`--skills, -s SKILL`	预加载技能（逗号分隔或重复）
`--yolo`	跳过危险命令确认
`--pass-session-id`	将会话 ID 包含在系统提示中
`--tui`	启动 TUI 界面
`--cli`	强制使用经典 CLI

5.3 聊天命令

hermes chat [选项]
  -q, --query "..."           单次提问，非交互式
  -m, --model MODEL           覆盖模型（如 anthropic/claude-sonnet-4）
  --provider PROVIDER         强制指定服务商
  -t, --toolsets LIST         逗号分隔的工具集
  -s, --skills NAME           预加载技能
  -v, --verbose               详细输出
  -Q, --quiet                 静默模式（无横幅、进度条）
  --checkpoints               启用文件检查点
  --image PATH                附加本地图片
  --max-turns N               每轮最大工具调用次数
  --source TAG                会话来源标签

脚本化运行：

# 纯文本一次性入口
hermes -z "法国的首都是哪里？"

# 管道输入
answer=$(hermes -z "总结这个文件" < /path/to/file.txt)

5.4 配置管理

hermes setup [section]        交互式向导（model|terminal|gateway|tools|agent）
hermes model                  交互式模型/服务商选择器
hermes fallback               管理备用服务商
hermes config                 查看当前配置
hermes config edit            在编辑器中打开 config.yaml
hermes config set KEY VAL     设置配置值
hermes config path            打印 config.yaml 路径
hermes config env-path        打印 .env 路径
hermes config check           检查配置完整性
hermes config migrate         更新配置以包含新选项
hermes login [--provider P]   OAuth 登录（nous, openai-codex, qwen-oauth）
hermes logout                 清除存储的认证
hermes doctor [--fix]         检查依赖和配置
hermes status [--all]         显示组件状态

5.5 工具与技能管理

# 工具
hermes tools                  交互式工具启用/禁用（curses UI）
hermes tools list             显示所有工具及其状态
hermes tools enable NAME      启用工具集
hermes tools disable NAME     禁用工具集

# 技能
hermes skills list            列出已安装的技能
hermes skills search QUERY    搜索技能中心
hermes skills install ID      安装技能（ID 或 URL）
hermes skills inspect ID      预览而不安装
hermes skills config          按平台启用/禁用技能
hermes skills check           检查更新
hermes skills update          更新过时的技能
hermes skills uninstall N     移除技能
hermes skills publish PATH    发布到注册表
hermes skills browse          浏览所有可用技能
hermes skills tap add REPO    添加 GitHub 仓库作为技能源
hermes skills bundle list     列出技能包

5.6 MCP 服务器

hermes mcp serve              将 Hermes 运行 MCP 服务器
hermes mcp add NAME           添加 MCP 服务器（--url 或 --command）
hermes mcp remove NAME        移除 MCP 服务器
hermes mcp list               列出已配置的服务器
hermes mcp test NAME          测试连接
hermes mcp configure NAME     切换工具选择

5.7 网关 (Gateway)

hermes gateway run            前台运行网关
hermes gateway install        安装为后台服务（systemd/launchd）
hermes gateway start          启动服务
hermes gateway stop           停止服务
hermes gateway restart        重启服务
hermes gateway status         检查状态
hermes gateway setup          配置消息平台

5.8 会话管理

hermes sessions list          列出最近的会话
hermes sessions browse        交互式选择器
hermes sessions export OUT    导出为 JSONL
hermes sessions rename ID T   重命名会话
hermes sessions delete ID     删除会话
hermes sessions prune         清理旧会话（--older-than N 天）
hermes sessions stats         会话统计

5.9 定时任务 (Cron)

hermes cron list              列出任务（--all 含已禁用的）
hermes cron create SCHED      创建任务：'30m', 'every 2h', '0 9 * * *'
hermes cron edit ID           编辑调度、提示、投递
hermes cron pause/resume ID   控制任务状态
hermes cron run ID            在下一次触发时运行
hermes cron remove ID         删除任务
hermes cron status            调度器状态

5.10 Webhook

hermes webhook subscribe N    在 /webhooks/<name> 创建路由
hermes webhook list           列出订阅
hermes webhook remove NAME    移除订阅
hermes webhook test NAME      发送测试 POST

5.11 Profiles

hermes profile list           列出所有 Profile
hermes profile create NAME    创建（--clone, --clone-all, --clone-from）
hermes profile use NAME       设置为默认
hermes profile delete NAME    删除
hermes profile show NAME      显示详情
hermes profile alias NAME     管理包装脚本
hermes profile rename A B     重命名
hermes profile export NAME    导出为 tar.gz
hermes profile import FILE    从归档导入

5.12 凭证池

hermes auth add               交互式凭证向导
hermes auth list [PROVIDER]   列出凭证
hermes auth remove P INDEX    按提供商+索引移除
hermes auth reset PROVIDER    清除耗尽状态

5.13 其他命令

hermes insights [--days N]    使用分析
hermes update                 更新到最新版本
hermes dashboard              启动 Web 管理面板
hermes backup / import        备份和恢复
hermes logs                   查看、跟踪、过滤日志
hermes plugins list/install/remove  插件管理
hermes memory setup/status/off  记忆提供商配置
hermes completion bash|zsh    Shell 补全
hermes acp                    ACP 服务器（IDE 集成）
hermes proxy                  本地 OpenAI 兼容代理
hermes security audit         供应链安全审计
hermes secrets                管理外部密钥源
hermes portal                 Nous Portal 状态和订阅
hermes kanban                 多配置协作看板
hermes uninstall              卸载 Hermes

六、会话内斜杠命令

在交互式聊天会话中输入以下命令。完整列表可在会话中输入 /help 查看。

6.1 会话控制

命令	说明
`/new [name]`	开始新会话（可选标题）
`/clear`	清屏并新建会话
`/retry`	重发最后一条消息
`/undo`	移除最后一次用户/助手交换
`/title [name]`	设置/查看会话标题
`/compress [here [N]]`	手动压缩对话上下文
`/stop`	终止后台进程
`/rollback [N]`	恢复文件检查点
`/snapshot [sub]`	创建/恢复状态快照
`/resume [name]`	恢复已命名会话
`/sessions`	浏览和恢复之前的会话
`/history`	显示对话历史
`/save`	保存当前对话到文件
`/redraw`	强制 UI 重绘

6.2 目标管理

命令	说明
`/goal <text>`	设置持续目标，Agent 跨轮次执行直到完成
`/goal status/pause/resume/clear`	目标子命令
`/subgoal <text>`	为活跃目标追加子条件

6.3 后台任务

命令	说明
`/background <prompt>`	在独立后台会话中运行提示
`/queue <prompt>`	将提示排入下一轮
`/steer <prompt>`	注入中途指令（不中断当前执行）
`/agents`	显示活跃 Agent 和运行中的任务

6.4 配置与显示

命令	说明
`/model [name]`	显示或更改当前模型
`/fast [normal\|fast\|status]`	切换快速模式
`/reasoning [level]`	设置推理等级（none/minimal/low/medium/high/xhigh/show/hide）
`/verbose`	循环：关闭 → 新工具 → 全部 → 详细
`/config`	显示当前配置
`/yolo`	切换跳过审批模式
`/skin [name]`	更改主题
`/statusbar`	切换状态栏
`/voice [on\|off\|tts]`	语音模式
`/busy [sub]`	控制 Hermes 工作时 Enter 的行为
`/indicator [style]`	选择忙碌指示器样式
`/footer [on\|off]`	切换运行时元数据页脚

6.5 工具与技能

命令	说明
`/tools [list\|disable\|enable]`	管理工具
`/toolsets`	列出工具集
`/skills`	搜索/安装技能
`/skill <name>`	加载技能到会话
`/reload-skills`	重新扫描技能目录
`/reload`	重新加载 .env 变量
`/reload-mcp`	重新加载 MCP 服务器
`/cron`	管理定时任务
`/curator [sub]`	后台技能维护
`/kanban [sub]`	多配置协作看板
`/plugins`	列出插件
`/browser [connect\|disconnect\|status]`	管理浏览器 CDP 连接

6.6 消息平台专属

命令	说明
`/approve`	批准待执行的命令
`/deny`	拒绝待执行的命令
`/restart`	重启网关
`/sethome`	设置主频道
`/update`	更新 Hermes
`/commands [page]`	浏览所有命令
`/status`	会话信息
`/whoami`	显示权限等级
`/profile`	当前 Profile 信息
`/usage`	Token 用量
`/debug`	上传调试报告
`/quit`	退出

6.7 自定义模型别名

在 ~/.hermes/config.yaml 中定义：

model_aliases:
  qwen:
    model: "qwen3-coder-plus"
    provider: "alibaba"
  deepseek:
    model: "deepseek-chat"
    provider: "deepseek"
  local-qwen:
    model: "qwen2.5-coder:32b"
    provider: "custom"
    base_url: "http://localhost:11434/v1"

然后在聊天中使用 /model qwen、/model deepseek。

6.8 自定义快捷命令

quick_commands:
  status:
    type: exec
    command: systemctl status hermes-agent
  deploy:
    type: exec
    command: scripts/deploy.sh

七、AI 服务商配置

Hermes Agent 支持 20+ LLM 提供商。以下重点介绍中国用户可访问的服务商。

7.1 中国可用服务商（推荐）

通义千问 (Qwen / DashScope / 阿里云)

API Key 方式：

# ~/.hermes/.env
DASHSCOPE_API_KEY=sk-你的密钥

hermes chat --provider alibaba --model qwen3.5-plus

OAuth 方式（Qwen Portal）：

hermes model   # 选择 "Qwen OAuth (Portal)"
# 浏览器登录阿里云账号，凭证保存到 ~/.hermes/auth.json

model:
  provider: "qwen-oauth"
  default: "qwen3-coder-plus"

阿里云编程计划（Coding Plan）：

hermes chat --provider alibaba_coding --model qwen3-coder-plus

使用相同的 DASHSCOPE_API_KEY，独立计费通道。

DeepSeek（深度求索）

# ~/.hermes/.env
DEEPSEEK_API_KEY=sk-你的密钥

hermes chat --provider deepseek --model deepseek-chat

服务商 ID: deepseek
API 地址: api.deepseek.com/v1

Kimi / 月之暗面 (Moonshot)

国际版：

KIMI_API_KEY=sk-你的密钥
hermes chat --provider kimi-coding --model kimi-for-coding

中国大陆版：

KIMI_CN_API_KEY=sk-你的密钥
hermes chat --provider kimi-coding-cn --model kimi-k2.5

服务商别名: kimi-cn, moonshot-cn
API 地址: api.moonshot.cn

MiniMax（稀宇科技）

API Key 方式：

MINIMAX_API_KEY=sk-你的密钥       # 全球端点
MINIMAX_CN_API_KEY=sk-你的密钥    # 中国端点

hermes chat --provider minimax --model MiniMax-M2.7       # 全球
hermes chat --provider minimax-cn --model MiniMax-M2.7    # 中国

OAuth 方式：

hermes model   # 选择 "MiniMax (OAuth)"

智谱 GLM (z.ai)

GLM_API_KEY=sk-你的密钥
hermes chat --provider zai --model glm-5

自动端点检测：自动探测全球/中国/编码端点

腾讯混元 (TokenHub)

TOKENHUB_API_KEY=sk-你的密钥
hermes chat --provider tencent-tokenhub --model hy3-preview

别名: tencent, tokenhub, tencentmaas

阶跃星辰 (StepFun)

STEPFUN_API_KEY=sk-你的密钥
hermes chat --provider stepfun --model step-3-mini

小米 MiMo

XIAOMI_API_KEY=sk-你的密钥
hermes chat --provider xiaomi --model mimo-v2-pro

GMI Cloud

GMI_API_KEY=sk-你的密钥
hermes chat --provider gmi --model zai-org/GLM-5.1-FP8

7.2 国际服务商

服务商	服务商 ID	环境变量	认证方式
OpenRouter	`openrouter`	`OPENROUTER_API_KEY`	API Key
Anthropic	`anthropic`	`ANTHROPIC_API_KEY`	API Key
OpenAI	`openai`	`OPENAI_API_KEY`	API Key
Google Gemini	`google`	`GOOGLE_API_KEY` / `GEMINI_API_KEY`	API Key
xAI / Grok	`x-ai`	`XAI_API_KEY`	API Key / OAuth
Hugging Face	`huggingface`	`HF_TOKEN`	Token
GitHub Copilot	`copilot`	`COPILOT_GITHUB_TOKEN`	OAuth
Nous Portal	`nous`	—	OAuth

7.3 Nous Portal（统一订阅门户）

一个 OAuth 登录覆盖 300+ 前沿模型（Claude、GPT、Gemini、DeepSeek、Qwen、Kimi、GLM、MiniMax、Grok 等）+ 工具网关。

hermes setup --portal     # 一键安装：OAuth + 服务商 + 网关
hermes portal status      # 检查登录和路由状态

7.4 自定义/本地端点

config.yaml 配置：

model:
  default: "qwen2.5-coder:32b"
  provider: "custom"
  base_url: "http://localhost:11434/v1"
  context_length: 64000

交互式配置：

hermes model   # 选择 "Custom endpoint"

支持的本地推理服务器：

服务器	适用场景
Ollama	零配置本地模型（推荐）
vLLM	高性能 GPU 推理
SGLang	RadixAttention 快速服务
llama.cpp	CPU/Metal 推理（Mac 用户）
LM Studio	桌面 GUI 应用

查询自托管端点的模型列表：

curl -s http://your-server:port/v1/models | python3 -m json.tool | grep '"id"'

7.5 备用服务商 (Fallback)

当主模型遇到限流/过载/连接错误时自动切换：

fallback_providers:
  - provider: "alibaba"
    model: "qwen3.5-plus"
  - provider: "deepseek"
    model: "deepseek-chat"

交互式管理：hermes fallback

7.6 配置服务商的交互方式

hermes model    # 完整设置向导：添加服务商、OAuth、API Key

命令	运行位置	功能
`hermes model`	终端（会话外）	完整设置向导
`/model`	聊天会话内	在已配置的服务商/模型间快速切换

八、工具与工具集

8.1 核心工具集

工具集	说明	默认启用
`terminal`	Shell 命令和进程管理	是
`file`	文件读写搜索修补	是
`web`	网页搜索和内容提取	是
`search`	仅网页搜索（web 的子集）	是
`browser`	浏览器自动化	是
`code_execution`	沙箱 Python 执行	是
`vision`	图像分析	是
`image_gen`	AI 图像生成	是
`video`	视频分析和生成	是
`tts`	文字转语音	是
`skills`	技能浏览和管理	是
`memory`	跨会话持久化记忆	是
`session_search`	搜索历史对话	是
`delegation`	子代理任务委派	是
`cronjob`	定时任务管理	是
`clarify`	向用户提问确认	是
`messaging`	跨平台消息发送	是
`todo`	会话内任务规划和跟踪	是

8.2 可选工具集

工具集	说明	默认状态
`kanban`	多代理工作队列工具	仅 Worker 可用
`debugging`	额外检查/调试工具	关闭
`safe`	最小化低风险工具集	关闭
`spotify`	Spotify 播放和播放列表控制	关闭
`homeassistant`	智能家居控制	关闭
`discord`	Discord 集成工具	关闭
`discord_admin`	Discord 管理/审核工具	关闭
`feishu_doc`	飞书（Lark）文档工具	关闭
`feishu_drive`	飞书（Lark）云盘工具	关闭
`yuanbao`	元宝集成工具	关闭
`rl`	强化学习工具	关闭
`moa`	Mixture of Agents	关闭

8.3 工具管理

hermes tools                  # 交互式启用/禁用（curses UI）
hermes tools list             # 列出所有工具及其状态
hermes tools enable NAME      # 启用工具集
hermes tools disable NAME     # 禁用工具集

会话内：

/tools [list|disable|enable]   # 管理工具
/toolsets                      # 列出工具集

注意： 工具更改在 /reset（新会话）后生效，不会在对话中途应用（为保护提示缓存）。

8.4 工具集选择建议

场景	推荐工具集
代码开发	`terminal, file, web, code_execution, delegation`
研究分析	`web, search, vision, file`
系统管理	`terminal, file`
内容创作	`web, file, image_gen, video, tts`
安全审计	`safe`（最小权限）
子代理委派	`terminal, file, web`（根据任务选择）

九、记忆系统

9.1 记忆类型

Hermes Agent 拥有多层记忆系统：

用户画像记忆 (User Profile)

记录用户身份、偏好、习惯、环境信息
声明式事实（如"用户偏好简洁沟通"）
每次会话自动注入上下文

笔记记忆 (Memory Notes)

环境事实、项目约定、工具技巧、经验教训
跨会话持久化
保持紧凑，仅保留长期有用的信息

9.2 记忆提供商

提供商	额外 LLM 成本	说明
内置	无	基础记忆
holographic	无	结构化实体+关系推理
honcho	有	Dialectic 推理
hindsight	有	实体解析需要 LLM
mem0/supermemory/retaindb/openviking/byterover	有	各自的云端 API

9.3 配置

memory:
  memory_enabled: true
  user_profile_enabled: true
  provider:  hindsight    # honcho, hindsight, mem0 等

9.4 记忆管理命令

hermes memory status    # 记忆状态
hermes memory setup     # 配置记忆提供商
hermes memory off       # 关闭记忆

十、技能系统

10.1 什么是技能

技能（Skills）是 Hermes 的程序化记忆——可复用的操作流程文档。当 Agent 解决了复杂问题、发现了一个工作流或被用户纠正后，可以将其持久化为技能文档，供未来会话加载使用。

10.2 技能文件结构

每个技能是一个 SKILL.md 文件，包含：

---
name: my-skill
description: "技能描述"
version: 1.0.0
author: 作者
license: MIT
platforms: [linux, macos, windows]
---

# 技能标题

## 触发条件
何时加载此技能...

## 步骤
1. 第一步...
2. 第二步...

## 注意事项
常见陷阱和边缘情况...

## 验证
如何验证任务完成...

10.3 技能分类

Hermes 技能按类别组织：

类别	示例技能
autonomous-ai-agents	claude-code, codex, opencode
creative	ascii-art, pixel-art, baoyu-comic, image_gen
data-science	jupyter-live-kernel
devops	kanban-orchestrator, kanban-worker
github	github-pr-workflow, github-issues, code-review
mlops	huggingface-hub, llama-cpp, fine-tuning-with-trl
research	arxiv, website-research-analysis
productivity	powerpoint, notion, google-workspace
social-media	xurl (X/Twitter)
software-development	tdd, debugging, plan-mode
以及其他…	gaming, media, security, smart-home 等

10.4 技能管理

hermes skills list                  # 列出已安装的技能
hermes skills search QUERY          # 搜索技能中心
hermes skills install ID            # 安装技能
hermes skills inspect ID            # 预览而不安装
hermes skills config                # 按平台启用/禁用
hermes skills check                 # 检查更新
hermes skills update                # 更新过时技能
hermes skills uninstall N           # 移除技能
hermes skills publish PATH          # 发布到注册表
hermes skills browse                # 浏览所有可用技能
hermes skills tap add REPO          # 添加 GitHub 仓库作为技能源
hermes skills bundle list           # 列出技能包

10.5 会话内加载技能

/skill <name>              # 加载指定技能
/skills                    # 搜索/安装技能
/reload-skills             # 重新扫描技能目录

10.6 Curator（技能生命周期管理）

后台自动维护 Agent 创建的技能：跟踪使用率、标记空闲技能、归档过期技能、保留备份。

hermes curator status        # 状态
hermes curator run           # 运行维护
hermes curator pause/resume  # 暂停/恢复
hermes curator pin NAME      # 固定技能（防止自动归档）
hermes curator archive NAME  # 归档
hermes curator restore NAME  # 恢复
hermes curator prune         # 清理
hermes curator backup        # 备份

固定技能（Pinned Skills）： 受保护免删除，但仍可打补丁和编辑。

十一、MCP 集成

11.1 什么是 MCP

MCP（Model Context Protocol）是标准化协议，允许 AI 智能体与外部工具和服务集成。Hermes 内置 MCP 客户端，支持通过 config.yaml 配置服务器，自动发现工具。

11.2 MCP 管理

hermes mcp serve              # 将 Hermes 作为 MCP 服务器运行
hermes mcp add NAME           # 添加 MCP 服务器
hermes mcp remove NAME        # 移除服务器
hermes mcp list               # 列出已配置服务器
hermes mcp test NAME          # 测试连接
hermes mcp configure NAME     # 切换工具选择

会话内： /reload-mcp 重新加载 MCP 服务器

11.3 配置 MCP 服务器

在 config.yaml 中或通过 hermes mcp add 交互配置：

mcp:
  servers:
    - name: "my-server"
      type: "stdio"        # stdio 或 http
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-xxx"]

十二、定时任务 (Cron)

12.1 基本概念

Cron 是 Hermes 的持久化调度器，支持：

周期性任务（如每 30 分钟、每小时、每天）
一次性定时任务（ISO 时间戳）
5 字段 cron 表达式
脚本模式（纯脚本，跳过 LLM）
Agent 模式（LLM 驱动，支持推理）

12.2 调度格式

格式	示例	说明
持续时间	`"30m"`	每 30 分钟
持续时间	`"2h"`	每 2 小时
自然语言	`"every monday 9am"`	每周一早 9 点
Cron 表达式	`"0 9 * * *"`	每天早 9 点
ISO 时间戳	`"2026-06-01T09:00:00"`	一次性

12.3 创建任务

通过 CLI：

hermes cron create "every 2h"   # 创建每 2 小时的任务

通过会话内工具（cronjob 工具）：

# Agent 模式下（默认）
cronjob(action="create", prompt="总结今天的新闻", schedule="every 8h")

# 脚本模式下（跳过 LLM）
cronjob(
    action="create",
    script="scripts/check_disk.py",
    schedule="30m",
    no_agent=True
)

12.4 任务参数

参数	说明
`prompt`	自包含的任务提示
`schedule`	调度表达式
`name`	人类友好的名称
`skills`	预加载的技能列表
`model`	模型覆盖
`script`	脚本路径
`no_agent`	跳过 LLM，纯脚本执行
`context_from`	注入其他任务的输出
`workdir`	运行目录
`enabled_toolsets`	限制工具集

12.5 任务管理

hermes cron list              # 列出任务
hermes cron edit ID           # 编辑
hermes cron pause ID          # 暂停
hermes cron resume ID         # 恢复
hermes cron run ID            # 触发运行
hermes cron remove ID         # 删除
hermes cron status            # 调度器状态

会话内： /cron

12.6 脚本模式

当 no_agent=True 时：

调度器直接运行脚本，输出 verbatim 投递
空输出 = 静默（不通知用户）
非零退出/超时 = 发送错误警报
适用于：系统监控、磁盘/GPU 检查、心跳检测

12.7 任务链

通过 context_from 将任务 A 的输出注入任务 B：

# 任务 A：收集数据
cronjob(action="create", prompt="检查磁盘使用率", schedule="30m", name="disk-check")

# 任务 B：分析数据（注入 A 的输出）
cronjob(action="create", prompt="分析磁盘数据并生成报告", schedule="30m", name="disk-report", context_from=["disk-check-job-id"])

十三、Profiles 多配置

13.1 什么是 Profile

Profile 是独立的 Hermes 实例，拥有隔离的配置、会话、技能和记忆。适用于：

不同项目使用不同模型
不同团队共享同一服务器
开发/生产环境隔离

13.2 Profile 文件布局

~/.hermes/profiles/<name>/
├── config.yaml       # Profile 配置
├── .env              # Profile 密钥
├── skills/           # Profile 技能
├── sessions/         # Profile 会话
└── memories/         # Profile 记忆

13.3 Profile 管理

hermes profile list           # 列出所有 Profile
hermes profile create NAME    # 创建（--clone, --clone-all）
hermes profile use NAME       # 设置为默认
hermes profile delete NAME    # 删除
hermes profile show NAME      # 显示详情
hermes profile alias NAME     # 管理包装脚本
hermes profile rename A B     # 重命名
hermes profile export NAME    # 导出为 tar.gz
hermes profile import FILE    # 从归档导入

会话内： /profile 显示当前 Profile 信息

使用指定 Profile：

hermes --profile my-project   # 使用指定 Profile

十四、子代理委派与多代理

14.1 基本概念

delegate_task 工具可派生子 Agent 实例，每个子代理拥有：

隔离的上下文
限制的工具集
独立的终端会话
全新的对话历史

重要：子代理对父代理的对话历史一无所知！ 父代理必须在 goal 和 context 字段中传递所有必要信息。

14.2 单个任务委派

delegate_task(
    goal="调试测试失败的原因",
    context="test_foo.py 第 42 行断言失败...",
    toolsets=["terminal", "file"]
)

14.3 并行批量委派

默认最多 3 个并发子代理（可配置）：

delegate_task(tasks=[
    {"goal": "研究主题 A", "toolsets": ["web"]},
    {"goal": "研究主题 B", "toolsets": ["web"]},
    {"goal": "修复构建问题", "toolsets": ["terminal", "file"]}
])

14.4 角色系统

角色	说明
`leaf`（默认）	不能再委派，不能调用 clarify/memory
`orchestrator`	可继续委派（受 `max_spawn_depth` 限制）

14.5 配置

delegation:
  max_iterations: 50                       # 子代理最大轮次
  max_concurrent_children: 3               # 并行子代理数
  max_spawn_depth: 1                       # 委派深度
  orchestrator_enabled: true               # 全局开关
  child_timeout_seconds: 600               # 子代理超时
  model: ""                                # 子代理专用模型
  provider: ""                             # 子代理专用服务商

使用更便宜的模型运行子代理：

delegation:
  model: "qwen3-coder-plus"
  provider: "alibaba"

14.6 子代理被阻止的工具

delegate（叶节点）、clarify、memory、execute_code、send_message

14.7 委派 vs 代码执行 vs 进程派生

因素	delegate_task	execute_code	派生 hermes 进程
推理	完整 LLM 推理	仅 Python 脚本	完整 LLM 推理
上下文	全新隔离对话	无对话	全新隔离进程
工具	非阻止工具 + 推理	7 个 RPC 工具	完整工具
并行	3 个并发	单个脚本	不限
时长	分钟级	秒级	小时/天级
适用	需要判断力的任务	机械数据处理	长期自治任务

14.8 派生独立 Hermes 进程

一次性模式：

hermes chat -q "Research GRPO papers and write summary to ~/research/grpo.md"

交互式 PTY 模式（通过 tmux）：

# 启动
tmux new-session -d -s agent1 -x 120 -y 40 'hermes'

# 发送消息
tmux send-keys -t agent1 'Build a FastAPI auth service' Enter

# 读取输出
tmux capture-pane -t agent1 -p

# 退出
tmux send-keys -t agent1 '/exit' Enter
tmux kill-session -t agent1

十五、消息网关 (Gateway)

15.1 概述

Hermes Gateway 是一个后台进程，将 Hermes Agent 连接到多个消息平台。同一 Agent 实例可同时服务多个平台。

15.2 支持的平台

国际平台： Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email、Google Chat、Mattermost、Matrix、LINE、Microsoft Teams、Home Assistant、ntfy、BlueBubbles (iMessage)

中国平台：

钉钉 (DingTalk) — 支持图片、文件、表情反应、流式输出
飞书 (Feishu/Lark) — 完整功能支持（语音、图片、文件、线程、流式）
企业微信 (WeCom) — 支持语音、图片、文件
微信 (Weixin) — 支持语音、图片、文件、流式
QQ — 支持语音、图片、文件
元宝 (Yuanbao) — 支持语音、图片、文件、流式

API： OpenAI 兼容 API 服务器、Webhooks、Open WebUI（通过 API Server）

15.3 网关架构

Hermes Gateway（单一后台进程）
├── 各平台适配器
├── 每会话存储（per-chat session store）
├── AI Agent 处理引擎
├── 定时任务调度器
├── API 服务器（OpenAI 兼容）
└── Webhooks

15.4 快速设置

hermes gateway setup        # 交互式设置所有消息平台
hermes gateway run          # 前台运行
hermes gateway install      # 安装为 systemd/launchd 服务
hermes gateway start        # 启动服务
hermes gateway status       # 检查状态
hermes gateway restart      # 重启服务
hermes gateway stop         # 停止服务

15.5 安全控制

白名单： 通过环境变量限制允许的用户 ID
DM 配对码： 未知用户首次 DM 时收到一次性配对码
管理员/普通用户分级： 管理员可使用所有斜杠命令

15.6 会话重置策略

策略	默认值	说明
Daily	凌晨 4:00	每天固定时间重置
Idle	1440 分钟	空闲 N 分钟后重置
Both	组合	先触发者生效

十六、语音 STT/TTS

16.1 功能总览

功能	平台	说明
交互式语音	CLI	按 Ctrl+B 录音，自动检测静音并回复
自动语音回复	消息平台	Agent 发送语音消息
语音频道	Discord	Bot 加入语音频道，实时对话

16.2 安装

pip install "hermes-agent[voice]"          # CLI 语音模式
pip install "hermes-agent[messaging]"      # 消息平台（含 Discord 语音）
pip install "hermes-agent[tts-premium]"    # 高级 TTS
pip install "hermes-agent[all]"            # 全部安装

系统依赖：

# Ubuntu
sudo apt install portaudio19-dev ffmpeg libopus0

# macOS
brew install portaudio ffmpeg opus

16.3 语音转文字 (STT)

提供商	模型	速度	质量	费用	需 API Key
本地 (faster-whisper)	base/small/large-v3	取决于 CPU/GPU	好到最佳	免费	不需要
Groq	whisper-large-v3-turbo	极快 (~0.5s)	好	免费额度	需要
OpenAI	whisper-1 / gpt-4o-transcribe	快	好到最佳	付费	需要

中文 STT： faster-whisper 对中文支持良好，使用 small 或更大模型精度更高。

16.4 文字转语音 (TTS)

提供商	质量	费用	延迟	需 API Key
Edge TTS	好	免费	~1s	不需要
ElevenLabs	优秀	付费	~2s	需要
OpenAI	好	付费	~1.5s	需要
NeuTTS	好	免费	取决于硬件	不需要
KittenTTS	好	免费	取决于硬件	不需要
Piper	好	免费	取决于硬件	不需要

中文 TTS 推荐： Edge TTS 支持中文语音：

zh-CN-XiaoxiaoNeural（女声，自然）
zh-CN-YunxiNeural（男声）
zh-CN-YunyangNeural（男声，深沉）

16.5 配置

# ~/.hermes/config.yaml
voice:
  record_key: "ctrl+b"              # 录音快捷键
  max_recording_seconds: 120        # 最大录音时长
  auto_tts: false                   # 启动时自动启用 TTS
  silence_threshold: 200            # 静音检测阈值
  silence_duration: 3.0             # 连续静音秒数

stt:
  enabled: true
  provider: "local"                 # local, groq, openai
  local:
    model: "small"                  # 中文推荐 small 或更大

tts:
  provider: "edge"                  # edge, elevenlabs, openai, neutts
  voice: "zh-CN-XiaoxiaoNeural"     # 中文语音

16.6 CLI 语音操作

/voice on       # 启用语音模式
/voice off      # 禁用
/voice tts      # 切换 TTS 输出
/voice status   # 查看状态

按 Ctrl+B 开始录音 → 3 秒静音后自动停止 → Whisper 转录 → Agent 回复 → TTS 朗读。

十七、安全与隐私

17.1 命令审批

默认情况下（approvals.mode: manual），Hermes 在执行标记为破坏性的 Shell 命令（如 rm -rf、git reset --hard 等）前会提示用户确认。

模式	说明
`manual`	始终提示（默认）
`smart`	使用辅助 LLM 自动批准低风险命令，高风险时提示
`off`	跳过所有审批（等效于 `--yolo`）

hermes config set approvals.mode smart       # 推荐中间方案
hermes config set approvals.mode off         # 绕过所有审批（不推荐）

单次绕过： hermes --yolo ... 或 export HERMES_YOLO_MODE=1

17.2 密钥脱敏

默认关闭。启用后自动在工具输出中屏蔽 API Key、令牌等敏感信息：

hermes config set security.redact_secrets true    # 启用（需重启）
hermes config set security.redact_secrets false   # 禁用

注意： 需要全新会话才能生效。这是故意设计——防止 LLM 在任务中途自行切换。

17.3 PII 脱敏

当启用时，网关在将会话上下文发送给模型之前哈希用户 ID 并剥离电话号码：

hermes config set privacy.redact_pii true     # 启用
hermes config set privacy.redact_pii false    # 禁用（默认）

17.4 安全扫描

hermes security audit    # 供应链安全审计

17.5 工具禁用

如需完全阻止网络或媒体工具，运行 hermes tools 逐平台切换。新会话（/reset）后生效。

十八、会话管理

18.1 会话存储

所有会话以 SQLite 格式存储在 ~/.hermes/sessions/ 中。

18.2 会话操作

hermes sessions list          # 列出最近的会话
hermes sessions browse        # 交互式选择器
hermes sessions export OUT    # 导出为 JSONL
hermes sessions rename ID T   # 重命名
hermes sessions delete ID     # 删除
hermes sessions prune         # 清理旧会话（--older-than N 天）
hermes sessions stats         # 会话统计

18.3 会话恢复

hermes --continue              # 恢复最近的会话
hermes --continue session-name # 恢复匹配的会话
hermes --resume <ID>           # 恢复特定 ID 的会话

会话内： /resume [name]、/sessions

18.4 会话搜索

使用 session_search 工具搜索历史对话：

基于 FTS5 全文搜索
支持布尔表达式（AND、OR、NOT）
支持精确匹配（引号）和前缀通配符

18.5 上下文压缩

compression:
  enabled: true
  threshold: 0.50          # 触发阈值（50% 上下文使用率）
  target_ratio: 0.20       # 压缩目标比率

会话内： /compress 手动压缩

18.6 文件检查点

checkpoints:
  enabled: true
  max_snapshots: 50

会话内： /rollback [N] 恢复文件检查点

十九、Kanban 协作看板

19.1 概述

Kanban 是 Hermes 的持久化 SQLite 看板，用于多 Profile / 多 Worker 协作。

19.2 CLI 命令

hermes kanban init            # 初始化看板
hermes kanban create          # 创建任务
hermes kanban list            # 列出任务（别名 ls）
hermes kanban show            # 显示任务详情
hermes kanban assign          # 分配任务
hermes kanban link            # 链接任务
hermes kanban comment         # 添加评论
hermes kanban complete        # 标记完成
hermes kanban block           # 阻塞任务
hermes kanban archive         # 归档
hermes kanban tail            # 查看最新活动
hermes kanban stats           # 统计信息
hermes kanban dispatch        # 分派任务
hermes kanban daemon          # 启动守护进程

19.3 架构

Board（看板）：硬边界，Worker 通过 HERMES_KANBAN_BOARD 环境变量锁定
Tenant（租户）：看板内的软命名空间，用于工作区路径 + 记忆键隔离
Dispatcher（分发器）：运行在 Gateway 中，回收过期声明、升级就绪任务、原子性认领、派生指定 Profile

19.4 Worker 工具集

Worker 看到精简的 kanban_* 工具集：kanban_show、kanban_complete、kanban_block、kanban_heartbeat、kanban_comment、kanban_create、kanban_link

二十、常见问题与故障排除

20.1 诊断工具

hermes doctor [--fix]         # 检查依赖和配置
hermes status [--all]         # 组件状态
hermes config check           # 配置完整性检查
hermes insights [--days N]    # 使用分析

20.2 语音不工作

检查 stt.enabled: true
验证提供商：pip install faster-whisper 或设置 API Key
网关中运行 /restart，CLI 中退出并重新启动

20.3 工具不可用

hermes tools — 检查工具集是否启用
某些工具需要环境变量（检查 .env）
启用工具后运行 /reset

20.4 模型/服务商问题

hermes doctor — 检查配置和依赖
hermes login — 重新认证 OAuth 服务商
检查 .env 中有正确的 API Key
Copilot 403：gh auth login 令牌不适用于 Copilot API，必须使用 hermes model → GitHub Copilot 的 OAuth 流程

20.5 自托管/自定义模型切换

/model 不显示自定义端点模型。 自定义提供商不会出现在内置模型目录中。查询端点：

curl -s http://your-server:port/v1/models | python3 -m json.tool | grep '"id"'

切换到不同端点：

hermes config set model.base_url "http://new-server:port/v1"
hermes config set model.default "model-name"

注意： Hermes 没有"备用模型池"——一次只能指向一个 base_url + model 对。更改后需要新会话（/reset）。

20.6 更改未生效

更改类型	生效方式
工具/技能	`/reset` 新会话
配置更改	网关：`/restart`；CLI：退出并重新启动
代码更改	重启 CLI 或网关进程

20.7 技能不显示

hermes skills list — 验证已安装
hermes skills config — 检查平台启用
显式加载：/skill name 或 hermes -s name

20.8 网关问题

# 查看日志
grep -i "failed to send\|error" ~/.hermes/logs/gateway.log | tail -20

常见问题：

SSH 退出后网关死亡： 启用 linger：sudo loginctl enable-linger $USER
WSL2 关闭后网关死亡： 需要在 /etc/wsl.conf 中设置 systemd=true
网关崩溃循环： 重置失败状态：systemctl --user reset-failed hermes-gateway

20.9 辅助模型不工作

如果 vision、compression、session_search 等辅助任务静默失败：

hermes config set auxiliary.vision.provider <your_provider>
hermes config set auxiliary.vision.model <model_name>

20.10 找不到资源

查找…	位置
配置选项	`hermes config edit`
可用工具	`hermes tools list`
斜杠命令	`/help`
技能目录	`hermes skills browse`
服务商设置	`hermes model`
平台设置	`hermes gateway setup`
MCP 服务器	`hermes mcp list`
Profiles	`hermes profile list`
Cron 任务	`hermes cron list`
记忆	`hermes memory status`
环境变量	`hermes config env-path`
CLI 命令	`hermes --help`
网关日志	`~/.hermes/logs/gateway.log`
会话文件	`~/.hermes/sessions/`
源代码	`~/.hermes/hermes-agent/`

附录 A：快速参考卡

安装与配置

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
hermes setup --portal
hermes

日常使用

hermes                        # 启动交互会话
hermes chat -q "问题"        # 单次提问
hermes -z "问题"              # 纯文本输出
hermes --continue             # 恢复最近会话

模型切换

hermes model                  # 终端中完整选择
/model [name]                 # 会话内快速切换

定时任务

hermes cron create "every 2h" # 创建任务
hermes cron list              # 列出任务

故障排查

hermes doctor                 # 诊断
hermes config check           # 配置检查
hermes update                 # 更新

附录 B：Hermes 核心概念图

Hermes Agent 架构
┌──────────────────────────────────────────────────┐
│                    用户入口                        │
│  CLI (TUI) │ 消息平台 │ API Server │ Webhooks    │
└────────────────────┬─────────────────────────────┘
                     │
┌────────────────────▼─────────────────────────────┐
│              Hermes Gateway                       │
│  ┌────────────┐  ┌────────────┐  ┌─────────────┐│
│  │ 平台适配器  │  │ 会话管理    │  │ 定时调度器   ││
│  └────────────┘  └────────────┘  └─────────────┘│
└────────────────────┬─────────────────────────────┘
                     │
┌────────────────────▼─────────────────────────────┐
│              AI Agent 核心                         │
│  ┌────────────┐  ┌────────────┐  ┌─────────────┐│
│  │ 提示构建器  │  │ 模型路由    │  │ 上下文压缩   ││
│  └────────────┘  └────────────┘  └─────────────┘│
└────────────────────┬─────────────────────────────┘
                     │
┌────────────────────▼─────────────────────────────┐
│              工具层                               │
│  terminal │ file │ web │ browser │ vision │ ...   │
└──────────────────────────────────────────────────┘
                     │
┌────────────────────▼─────────────────────────────┐
│              持久化层                              │
│  记忆 │ 技能 │ 会话 │ MCP │ Profiles │ Kanban     │
└──────────────────────────────────────────────────┘

数据来源：Hermes Agent 官方文档 (hermes-agent.nousresearch.com/docs)
GitHub: https://github.com/NousResearch/hermes-agent

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

AI重构项目开发全流程：效率革命与实践指南

AtomGit开源社区

Spring AI Tool Calling 工具调用实战

AtomGit开源社区

langchain框架中的stream()与stream_event()的区别

stream比起stream_event更加的原始，他就像一条流水线，不断输出消息对象，你需要对每一个对象进行判断，判断他的type（如messages，updates），在判断他token的type（如messages中的reasoning，或text），然后在输出，你过滤完的对象的值。stream_event相对高级点，有封装好的“事件”（多条流水线），从中获取数据需要两次循环，一次判断。st