Telegram配置（最推荐）

Telegram是国内最容易连上的海外平台，而且Bot API很成熟。我强烈建议新手从这里开始。

第一步：创建Bot

1. 1. 打开Telegram，搜索 @BotFather
2. 2. 点Start，然后输 /newbot
3. 3. 按提示给Bot起名字（显示名）和用户名（必须以bot结尾，如 myhermes_bot）
4. 4. BotFather会给你一个Token，复制保存好

第二步：配置Hermes

hermes gateway setup

选择Telegram，粘贴你的Token，跟着向导走完。

第三步：启动网关

hermes gateway start

第四步：测试

在Telegram里给你的Bot发消息，它应该回复你。如果正常回复，就成了。

让Bot响应群聊消息

默认Bot只响应私聊。想在群里用：

1. 1. 把Bot加到群里
2. 2. 在群里 @Bot名字 你的消息

或者在配置里设置：

telegram:
  require_mention: false   # 不需要@也能响应（群里所有消息都回，可能很吵）

Discord配置

适合团队用，功能丰富。

第一步：创建Discord应用

1. 1. 访问 https://discord.com/developers/applications
2. 2. 点 "New Application"，起个名字
3. 3. 左边选 "Bot"，点 "Add Bot"
4. 4. 在Bot页面找到 Token，复制保存

第二步：邀请Bot加入服务器

1. 1. 左边选 "OAuth2" → "URL Generator"
2. 2. Scopes选 bot
3. 3. Bot Permissions选需要的权限（至少要有发消息、读消息）
4. 4. 复制生成的URL，在浏览器打开
5. 5. 选择你的服务器，授权

第三步：配置Hermes

hermes gateway setup

选Discord，粘贴Token，跟着向导走。

Discord的线程功能

Discord里@Bot，它会在频道里自动创建一个线程，对话都在线程里进行，不会刷屏。这个功能很贴心。

微信接入（国内用户最关心）

重要：Hermes官方不直接支持微信，因为微信的Bot接口限制很多。但社区有桥接方案。

方案1：HermesClaw（推荐）

这是一个社区项目，把Hermes和微信桥接起来。

项目地址：https://github.com/AaronWong1999/hermesclaw

原理：通过一个中间服务，把微信消息转发给Hermes，再把Hermes的回复转回微信。

安装步骤：

1. 1. 按项目README安装hermesclaw
2. 2. 配置微信登录（需要扫码）
3. 3. 配置Hermes网关指向hermesclaw

方案2：企业微信

如果你有企业微信，可以用企业微信的机器人API，官方支持更好。

钉钉/飞书

这两个平台Hermes原生支持，配置方式跟Telegram类似：

hermes gateway setup

选择对应的平台，按向导填写Webhook地址和Token。

多平台同时运行

你可以同时接多个平台：

hermes gateway setup   # 配置Telegram
hermes gateway setup   # 再配置Discord
hermes gateway setup   # 再配置Slack

然后：

hermes gateway start   # 一个命令启动所有平台

所有平台共享同一个Hermes实例，你在Telegram发的消息，Hermes记得，你在Discord接着聊也没问题。

平台间的对话连续性

这是我觉得最实用的功能之一。

场景：

1. 1. 早上在Telegram上让Hermes分析一份报告
2. 2. 中午在Discord上看到它还没分析完，追加了一个问题
3. 3. 晚上回家在CLI上继续聊

这三个平台的对话是连续的，Hermes记得之前聊了什么。不需要每个平台重新开始。

语音消息

Telegram和Discord支持发送语音消息，Hermes会自动转文字处理，然后文字回复你。

配置语音转文字：

hermes config set stt.provider local   # 本地转（需要装faster-whisper）
# 或
hermes config set stt.provider groq    # 用Groq API转（快）

安全设置

网关开放在公网上，安全很重要。

用户白名单

gateway:
  allowed_users:
    - telegram:12345678
    - discord:username#1234

不在白名单里的人发消息，Hermes不会回复。

未授权DM处理

unauthorized_dm_behavior: pair   # 未授权用户发消息，回复一个配对码（默认）
# unauthorized_dm_behavior: ignore  # 直接忽略

命令审批

远程操作时，危险命令需要审批：

approvals:
  mode: manual   # 手动审批

Hermes会发消息问你"是否执行rm -rf /？"，你回复"yes"才执行。

把网关设为后台服务

如果你希望网关24小时运行：

Linux/macOS：

hermes gateway install     # 安装为用户级服务
# 或
sudo hermes gateway install --system   # 系统级服务

WSL2：
WSL2关机后服务会停。建议配Windows任务计划程序，或者买个小服务器跑。

第九讲：进阶配置——打造属于你的Hermes

---

Hermes的默认配置够用了，但调一调能让你用得更爽。这一讲我把最值得改的配置给你列出来。

配置文件在哪

Hermes的配置分两个文件：

文件	路径	存什么
config.yaml	~/.hermes/config.yaml	普通设置（模型、显示、工具等）
.env	~/.hermes/.env	API key和密码

为什么分开？因为 .env 存的是敏感信息，而 config.yaml 可以随便分享。

用命令改配置

不用手动编辑文件，Hermes提供了命令行工具：

hermes config              # 查看当前配置
hermes config set KEY VAL  # 修改某个值
hermes config edit         # 用编辑器打开config.yaml

比如：

hermes config set model deepseek/deepseek-chat
hermes config set terminal.backend docker
hermes config set display.tool_progress verbose

API key用 hermes config set 也会自动存到 .env，不用担心放错地方。

值得改的显示设置

输出详细程度

display:
  tool_progress: all       # off / new / all / verbose

• • off：静默，只显示最终结果
• • new：只在换工具时显示
• • all：显示每个工具调用（默认，推荐）
• • verbose：显示完整参数和调试信息

我日常用 all，出了问题调 verbose。

流式输出

display:
  streaming: true

开启后，Hermes的回复会一个字一个字实时显示，不用等它全部生成完。体验好很多。

显示花费

display:
  show_cost: true

在状态栏显示当前会话花了多少钱。用了贵的模型时看着数字涨，能帮你养成节约的习惯。

终端响铃

display:
  bell_on_complete: true

Hermes干完活后终端响一声。适合启动长任务后去干别的，听到铃声就知道完了。

上下文压缩设置

聊久了上下文会满，Hermes会自动压缩。可以调触发阈值：

compression:
  enabled: true
  threshold: 0.50    # 上下文用到50%时触发压缩

如果你用的大模型（200K+上下文），可以调高点：

compression:
  threshold: 0.70    # 用到70%再压缩

审批模式

Hermes执行危险命令前会问你。三个模式：

approvals:
  mode: manual    # 手动审批（默认，推荐）
  # mode: smart   # 智能审批，安全的自动过，危险的问你
  # mode: off     # 关闭审批，危险！

新手建议 manual，熟悉后切 smart，省事很多。

终端后端

默认命令在你本地执行。可以换到其他环境：

terminal:
  backend: local     # 本地（默认）
  # backend: docker  # Docker容器（隔离安全）
  # backend: ssh     # 远程服务器

Docker后端：命令在Docker容器里执行，不会影响你的主机。适合测试不熟悉的命令。

hermes config set terminal.backend docker

SSH后端：命令在远程服务器上执行。适合Hermes跑在云服务器上，你本地只是发指令。

terminal:
  backend: ssh

环境变量：

TERMINAL_SSH_HOST=你的服务器IP
TERMINAL_SSH_USER=用户名

语音设置

文字转语音（TTS）

Hermes说话给你听：

tts:
  provider: edge     # edge（免费）/ elevenlabs / openai / gemini

Edge TTS完全免费，支持中文，音质够用。

语音转文字（STT）

你说，Hermes听：

stt:
  provider: local    # 本地（需装faster-whisper）
  # provider: groq   # Groq API（快，需key）
  # provider: openai # OpenAI Whisper

本地转文字完全免费，隐私也好，但需要装依赖。

时区设置

默认用服务器本地时区。如果你服务器在国外，想按北京时间跑定时任务：

timezone: "Asia/Shanghai"

人格自定义

系统默认的人格是标准助手。你可以完全自定义：

编辑 ~/.hermes/SOUL.md：

# 身份

你是一个经验丰富但脾气有点暴躁的全栈开发者。说话直接，不爱废话，但技术能力很强。

# 风格

- 回复简短，直击要点
- 代码注释很少，认为好代码应该自解释
- 遇到蠢问题会吐槽，但还是会帮忙解决

这个文件的内容会替换掉Hermes的默认身份设定。每次启动都会加载，比 /personality 命令更持久。

项目上下文文件

在你的项目目录下放这些文件，Hermes会自动加载：

文件	优先级	用途
.hermes.md	最高	项目专属指令
AGENTS.md	高	项目规范（递归查找）
CLAUDE.md	中	Claude Code兼容
.cursorrules	低	Cursor兼容

比如你在项目根目录放 AGENTS.md：

# 项目规范

- 使用TypeScript，严格模式
- 缩进用2个空格
- 测试用Vitest
- 提交前必须跑过lint和test

Hermes在这个项目里操作时，会自动知道这些规范。

检查配置是否正确

hermes config check

这条命令会检查配置是否有缺失或错误，并给出修复建议。

 

---

第十讲：MCP扩展——连接无限可能

Hermes 入门 11 讲

---

MCP这玩意儿有点像USB接口，一个标准，插什么设备都行。Hermes支持MCP之后，能接的东西突然多了好多。

什么是MCP

MCP全称 Model Context Protocol，翻译过来就是"模型上下文协议"。

简单说，它是一个通用接口标准。任何人都可以按照这个标准做一个"服务"，然后Hermes（或其他支持MCP的AI）就能直接用这个服务里的功能。

打个比方：

• • 以前每个AI工具都要自己写代码接GitHub、接数据库、接各种API
• • 有了MCP，GitHub官方做了一个MCP服务，所有AI都能直接用
• • 你只需要配置一下地址，不用写一行代码

为什么要关心MCP

因为MCP让Hermes的能力边界无限扩展了。

官方内置的工具只有几十种，但MCP生态里已经有成百上千的服务：

• • GitHub MCP：管理代码仓库、PR、Issue
• • 文件系统MCP：读写指定目录的文件
• • PostgreSQL MCP：查询数据库
• • Slack MCP：发消息、读频道
• • 浏览器MCP：网页自动化
• • 甚至你家智能家居的MCP...

而且这些不需要Hermes官方支持，社区谁都可以做。

怎么配置MCP

好消息：纯配置，不写代码。只需要在 ~/.hermes/config.yaml 里加几行。

配置格式

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_你的token"

这段配置做了什么：

1. 1. 定义了一个叫 github 的MCP服务
2. 2. 用npx运行GitHub的官方MCP服务
3. 3. 传了一个GitHub Token用于认证

配置完重启Hermes，它会自动发现这个服务里的工具，然后就能用了。

实际示例

让Hermes帮你管GitHub：

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
    tools:
      include: [create_issue, list_issues, search_code]

然后你就可以说：

❯ 帮我看看我有哪些open的issue，给最urgent的那个加评论

让Hermes读写指定文件夹：

mcp_servers:
  mydocs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/你的用户名/Documents"]

然后：

❯ 帮我整理Documents里的文件，把超过1年的旧文件移到archive文件夹

常用MCP服务推荐

服务	用途	安装
GitHub	管理仓库、PR、Issue	npx -y @modelcontextprotocol/server-github
Filesystem	文件读写	npx -y @modelcontextprotocol/server-filesystem /path
PostgreSQL	数据库查询	npx -y @modelcontextprotocol/server-postgres
Slack	消息发送	npx -y @modelcontextprotocol/server-slack
Puppeteer	浏览器自动化	npx -y @modelcontextprotocol/server-puppeteer
Brave Search	网页搜索	npx -y @modelcontextprotocol/server-brave-search

大部分服务都只需要上面那种简单的配置，复制粘贴改改参数就行。

工具过滤

有些MCP服务提供的工具很多，但你可能只想让Hermes用其中几个。可以配置白名单：

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    tools:
      include: [create_issue, list_issues]   # 只用这两个

或者黑名单：

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    tools:
      exclude: [delete_customer]   # 除了删除客户，其他都能用

这既是功能管理，也是安全控制。

Hermes作为MCP服务器

不只是接别人的MCP服务，Hermes自己也能当MCP服务器。

什么意思？你可以让Claude Code、Cursor、或其他MCP客户端通过Hermes来：

• • 发Telegram消息
• • 读Discord频道
• • 查Hermes的记忆

启动方式：

hermes mcp serve

然后在Claude Code的配置里加上：

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

这样Claude Code写代码的时候，可以通过Hermes发消息通知你，或者读你的Hermes记忆来了解项目背景。

5个实用场景

不用写代码，纯配置就能实现：

1. 自动整理下载文件夹

配一个Filesystem MCP指向Downloads，然后创建定时任务：

❯ /cron add "every week" "整理~/Downloads，把图片移到Pictures，文档移到Documents，其他的问我" --skill file-organizer

2. GitHub Issue管理

配GitHub MCP，然后：

❯ 看看这周有哪些新bug，按严重程度排个序
❯ 给#123 issue回复：已修复，请测试

3. 数据库报表

配PostgreSQL MCP：

❯ 查一下上个月的用户增长数据，做个简单的趋势分析

4. 自动填网页表单

配Puppeteer MCP：

❯ 打开这个报名页面，帮我填一下信息：姓名xxx，邮箱xxx...

5. 跨AI工具协作

Hermes当MCP服务器，Claude Code当客户端：

• • Claude Code写代码时发现需要确认，通过Hermes发Telegram问你
• • 你手机上回复，Claude Code收到后继续写

故障排查

MCP服务连不上？检查这几点：

1. 1. Node.js装了吗：MCP服务大部分用Node.js运行，node --version 看看
2. 2. npx能用吗：npx --version 检查一下
3. 3. 服务装了吗：第一次用某个MCP服务时，npx会自动下载，需要等一会儿
4. 4. 配置对吗：YAML缩进很重要，少一个空格就报错

如果工具没出现，用 /reload-mcp 重新加载。

 

---

第十一讲：故障排查与最佳实践

Hermes 入门 11 讲

---

最后一讲，把我踩过的坑和总结的经验全倒出来。看完这讲，你基本上能独立解决90%的问题。

故障排查顺序

遇到问题不要慌，按这个顺序排查：

hermes doctor → hermes model → hermes setup → hermes sessions list

第一步：hermes doctor

hermes doctor

这条命令会自动检查：

• • 安装是否完整
• • 配置有没有问题
• • 模型提供商是否正常
• • 工具是否能用
• • 磁盘空间够不够

出问题了它会给出明确的修复建议，跟着做就行。

第二步：hermes model

如果doctor没发现问题，大概率是模型配置不对：

hermes model

重新选一下模型，确认：

• • 提供商选对了
• • API key有效（没过期、没用完额度）
• • 模型名称正确

常见坑：API key前面多了个空格、复制的时候少了一个字符、key被重置了。重新复制粘贴一遍往往就好了。

第三步：hermes setup

前两步都不行，重新跑设置向导：

hermes setup

这会重新走一遍配置流程，把可能配错的地方重置。

第四步：hermes sessions list

如果之前能聊，突然不能了：

hermes sessions list

看看会话状态是否正常。有时候会话文件损坏，恢复不了，用 hermes --new 新开一个就好。

常见问题速查

问题1：Hermes回复空内容或报错

原因：模型提供商配置有问题（key错误、模型不可用、网络不通）

解决：

hermes model    # 重新选择

如果用的是国内模型，检查能不能直连。Claude/OpenAI这些国外模型，国内需要代理。

问题2：工具不工作（比如不能搜索网页）

原因：

1. 1. 工具集没启用：hermes tools 检查
2. 2. API key没配：web工具需要 FIRECRAWL_API_KEY 或 TAVILY_API_KEY
3. 3. key用完了或过期了

解决：

hermes tools                    # 确认工具集启用了
hermes config set FIRECRAWL_API_KEY xxx   # 重新配key

问题3：上下文满了，开始忘事

现象：聊到一半，Hermes突然忘了前面的内容；或者回复质量明显下降。

解决：

❯ /compress          # 压缩上下文
❯ /usage             # 查看具体占用

长期解决：换个大上下文模型，或者调低压缩阈值：

compression:
  threshold: 0.40    # 更早触发压缩

问题4：网关启动但收不到消息

原因：

1. 1. Bot Token配错了
2. 2. 平台设置不完整（比如Telegram的webhook）
3. 3. 防火墙挡住了
4. 4. Hermes没权限访问平台API

解决：

hermes gateway setup    # 重新配置
hermes gateway status   # 查看状态

问题5：Hermes执行危险命令前不问我

原因：审批模式关掉了

解决：

hermes config set approvals.mode manual

问题6：定时任务不执行

原因：

1. 1. 网关没运行
2. 2. 任务被暂停了
3. 3. 时间格式写错了

解决：

hermes gateway status    # 确认网关运行中
hermes cron list         # 检查任务状态
hermes cron run 任务名    # 手动触发测试

问题7：装了技能但调不出来

原因：

1. 1. 技能没安装成功
2. 2. 技能名记错了
3. 3. 技能有平台限制（比如macOS专用）

解决：

hermes skills list       # 看看到底装上了没
❯ /skills               # 在对话里列出可用技能

问题8：恢复会话失败

原因：

1. 1. 切换了profile（配置集）
2. 2. 会话文件损坏
3. 3. 换了一台机器

解决：

hermes sessions list                    # 列出所有会话
hermes --resume 20260225_143052_a1b2c3  # 用ID恢复

成本控制技巧

用久了账单会涨，几个省钱方法：

1. 按场景选模型

场景	推荐模型	原因
日常闲聊	DeepSeek / GLM	便宜够用
写代码	Kimi / Claude	代码能力强
复杂分析	Claude Opus	推理能力最强
辅助任务	Gemini Flash	又快又便宜

2. 用Fallback降成本

主模型用贵的，fallback配便宜的：

fallback_providers:
  - provider: deepseek
    model: deepseek-chat

3. 精简工具集

只开需要的工具，减少每次请求的token消耗：

hermes tools    # 关掉不用的

4. 定时任务用便宜的模型

在config.yaml里给辅助任务单独配模型：

auxiliary:
  compression:
    provider: openrouter
    model: google/gemini-2.5-flash   # 压缩用便宜的

安全最佳实践

1. API key别泄露

.env 文件里的key是敏感信息：

• • 别上传到GitHub
• • 别截图发朋友圈（打码也不安全）
• • 定期轮换key

2. 远程操作开审批

approvals:
  mode: manual    # 或 smart

3. 网关配白名单

gateway:
  allowed_users:
    - telegram:你的ID

4. 容器隔离

不信任的命令用Docker后端执行：

hermes config set terminal.backend docker

5. 定期备份

hermes backup    # 备份配置、记忆、会话

进阶技巧

同时开多个Hermes

用profile隔离不同场景：

hermes -p work     # 工作profile
hermes -p personal # 个人profile

每个profile有独立的配置、记忆、会话。

工作树隔离

hermes -w    # 在独立的git worktree里运行

适合让Hermes做代码改动，不影响主分支。

批量查询

hermes chat -q "你的问题"    # 单轮查询，非交互式

适合脚本里调用，或者快速问个问题。

查看日志

hermes logs      # 查看日志
hermes logs -f   # 实时跟踪

日志里的API key会自动打码，可以放心分享。

社区资源

遇到问题自己搞不定？

• • GitHub Issues：https://github.com/NousResearch/hermes-agent/issues
• • Discord社区：https://discord.gg/NousResearch
• • 官方文档：https://hermes-agent.nousresearch.com/docs/

发issue的时候带上 hermes doctor 的输出，维护者能更快定位问题。

写在最后

11讲到这里就结束了。

回顾一下你学到了什么：认识Hermes、安装、选模型、界面操作、斜杠命令、工具、记忆、技能、定时任务、多平台集成、进阶配置、MCP扩展、故障排查。

从完全不懂到能独立使用，这个系列的目标就是让你少走弯路。我踩过的坑都给你标出来了，剩下的就是多动手、多尝试。

Hermes是个工具，真正发挥价值的是你怎么用它。希望你能用它提高效率、解决实际问题。

如果文章对你有帮助，欢迎转发给需要的朋友。有问题也可以在评论区讨论。

---

本系列文章基于Hermes Agent最新版本撰写，部分功能可能随版本更新有所变化，以官方文档为准。

 

---