← 返回主页
Nous Research · MIT 开源 · 2026

# Hermes Agent 完整指南

安装 · DeepSeek 接入 · Telegram Gateway · 中文配置 · 程序坞启动
macOS / Windows 双平台，所有踩坑已替你填平

⚡ 本教程是从零开始的完整安装指南。如果你已经安装了 Hermes Agent，只需要桌面快捷启动，请直接去 一键启动器页面。

## 0 Hermes Agent 是什么

Hermes Agent 是 Nous Research 开发的开源 AI Agent 框架（MIT 协议）。和 Claude Code 类似——在终端里运行，能读文件、写代码、执行命令、操控浏览器。但它不绑定任何模型厂商，可以自由接入 DeepSeek、OpenAI、Anthropic 等任意模型。

🔓

### 完全开源

MIT 协议，代码公开，可自由修改和分发

🔌

### 模型自由

支持 DeepSeek / OpenAI / Anthropic / Google 等任意厂商

🧰

### 89 个内置技能

浏览器操控、GitHub 管理、论文写作、代码执行、音乐创作

🧠

### 长期记忆

跨会话保持上下文，SOUL.md 系统提示词持久注入

💬

### Telegram 原生集成

内置 Gateway，一条命令接入 Telegram Bot

🖥️

### 电脑操控

cua-driver 驱动，可操控 macOS 桌面应用

一句话总结：Hermes Agent = 开源版 Claude Code + 内置 Telegram Bot + 更多技能。如果你想要一个能接国产模型、能跑在 Telegram 上的 AI Agent，这就是目前最好的选择。

## ◆ Hermes Agent vs Claude Code

维度 | Hermes Agent 推荐 | Claude Code
--- | --- | ---
开源协议 | MIT（完全自由） | 专有（Anthropic）
模型支持 | DeepSeek / OpenAI / Anthropic / Google / 任意 | 仅 Anthropic 官方 + 第三方兼容
Telegram Bot | 内置 Gateway，一条命令接入 | 需自己写 bot 脚本
技能系统 | 89 个内置 Skill，可自定义 | 需手动安装第三方 Skill
记忆系统 | SOUL.md + 跨会话持久记忆 | CLAUDE.md + memory/ 目录
电脑操控 | 内置 cua-driver（macOS） | 需额外配置
部署方式 | 一条命令安装 + launchd 开机自启 | brew install + 手动配置
更新方式 | `hermes update` 自动更新 | `brew upgrade claude-code`

## 1 安装 Hermes Agent

一条命令完成安装。脚本自动处理 uv、Python 3.11、Node.js 及全部依赖。

### ▎macOS 安装

### 打开终端

按 Command + 空格 搜索「终端」，打开终端 App。

### 执行安装脚本 无需魔法

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

脚本会自动完成：安装 uv 包管理器 → 创建 Python 3.11 虚拟环境 → 安装 100+ 依赖包 → 安装 Node.js → 安装 cua-driver。

### 重启终端

安装完成后关闭终端重新打开，让 PATH 生效。然后验证：

hermes --version

输出版本号（如 `hermes 0.14.0`）即安装成功。

⚠️ 常见坑：HTTP/2 下载失败。安装脚本在下载 Node.js 时可能报 `curl: (92) HTTP/2 stream error`。这是因为 nodejs.org 的 HTTP/2 在某些网络下不稳定。
解决方法：如果脚本卡在 Node.js 下载，按 `Ctrl+C` 终止，然后手动下载：
curl --http1.1 -L "https://nodejs.org/dist/v22.11.0/node-v22.11.0-darwin-arm64.tar.gz" -o /tmp/node.tar.gz mkdir -p ~/.hermes/node tar -xzf /tmp/node.tar.gz -C ~/.hermes/node --strip-components=1 rm /tmp/node.tar.gz
关键是用 `--http1.1` 标志强制使用 HTTP/1.1 协议。然后重新运行安装脚本即可跳过 Node.js 下载步骤。

### ▎Windows 安装

### 先装 Git Bash 无需魔法

Hermes Agent 在 Windows 依赖 Git Bash。按 Win + R 输入 `wt` 打开终端：

winget install Git.Git

### 在 Git Bash 中执行安装脚本

打开 Git Bash，执行：

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

### 重启 Git Bash 验证

hermes --version
安装后目录结构：程序在 `~/.local/bin/hermes`，配置在 `~/.hermes/`，日志在 `~/.hermes/logs/`。

## 2 初始化配置（setup 向导）

安装完成后运行 `hermes setup` 进入交互式配置向导，配置模型和 API Key。

### 启动配置向导

hermes setup

向导会依次询问以下配置项。

### 选择模型提供商 → DeepSeek

向导列出支持的提供商，选择 DeepSeek（或用方向键选择后回车）。

### 输入 DeepSeek API Key

去 platform.deepseek.com 注册 → API Keys → 创建 Key → 复制粘贴到终端。

Key 以 `sk-` 开头。新用户有免费额度，轻度使用足够。

### 其余选项回车默认

模型名默认 `deepseek-v4-pro`、Base URL 默认 `https://api.deepseek.com/v1`，直接回车确认。TTS（文字转语音）选 N 跳过。

### 验证配置

hermes chat

输入一句话测试，收到回复说明模型连接成功。

配置文件位置：setup 向导会把配置写入 `~/.hermes/config.yaml`，密钥写入 `~/.hermes/.env`。你可以随时编辑这两个文件修改配置。
⚠️ 踩坑：DeepSeek API Key 有多个。如果你之前用过 Claude Code + DeepSeek，可能有两个不同的 Key：一个是 Claude Code 里用的 `ANTHROPIC_AUTH_TOKEN`，一个是 DeepSeek 原生 Key。两者格式相同但值不同。用 DeepSeek 平台上的原始 Key，不要用 Claude Code 转接的那个。如果配置后对话报 401 认证失败，说明 Key 无效——去 DeepSeek 平台重新创建一个。

## 3 接入 Telegram Gateway（核心功能）

Hermes Agent 内置 Telegram Gateway，让你的 Bot 在 Telegram 中 24 小时在线，自动回复消息。这是它相比 Claude Code 最大的优势之一。

### 3.1 架构原理

Telegram 消息 → Hermes Gateway → DeepSeek API → + 89 个技能 → AI 回复 → Telegram 聊天

Gateway 作为 macOS launchd 服务 24 小时运行，崩溃自动重启。支持 30+ 命令，DuckDuckGo 搜索、代码执行、浏览器操控全在 Telegram 里完成。

### 3.2 创建 Telegram Bot

### 去 @BotFather 创建 Bot

在 Telegram 中搜索 @BotFather → 发送 `/newbot` → 按提示设置名称和用户名 → 获取 Bot Token（格式：`123456:ABC-DEF1234ghiJKL`）。

### 获取你的 Telegram 用户 ID

在 Telegram 中搜索 @userinfobot → 发送 `/start` → 获取你的数字 ID。

### 3.3 配置环境变量

创建 `~/.hermes/.env` 文件：

DEEPSEEK_API_KEY=sk-你的deepseek密钥 TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghiJKL TELEGRAM_ALLOWED_USERS=你的Telegram数字ID TELEGRAM_HOME_CHANNEL=你的Telegram数字ID GATEWAY_ALLOW_ALL_USERS=true
🚨 最重要的坑：launchd 不读 .env 文件！这是整个配置过程中最隐秘的坑。Gateway 作为 launchd 服务运行时，不会 source shell 配置文件（.zshrc / .bashrc），也不读取 .env 文件。launchd 服务运行在最简系统环境中。
解决方法：必须把环境变量直接写入 launchd plist 的 `EnvironmentVariables` 字典中。详见下一步。

### 3.4 安装并启动 Gateway 服务

### 安装 Gateway（自动注册 launchd）

hermes gateway install

这条命令会：创建 launchd plist → 注册为开机自启服务 → 启动 Gateway。

### 🚨 关键步骤：把环境变量写入 plist

打开 launchd 配置文件：

open ~/Library/LaunchAgents/ai.hermes.gateway.plist

在 `<dict>` 中添加 `EnvironmentVariables` 段：

<key>EnvironmentVariables</key> <dict> <key>DEEPSEEK_API_KEY</key> <string>sk-你的deepseek密钥</string> <key>TELEGRAM_BOT_TOKEN</key> <string>你的Bot Token</string> <key>TELEGRAM_ALLOWED_USERS</key> <string>你的用户ID</string> <key>TELEGRAM_HOME_CHANNEL</key> <string>你的用户ID</string> <key>GATEWAY_ALLOW_ALL_USERS</key> <string>true</string> </dict>

保存后重启 Gateway：

hermes gateway restart

### 验证 Gateway 运行状态

hermes gateway status

看到 `✓ telegram connected` 即成功。

tail -f ~/.hermes/logs/gateway.log

实时查看日志，确认消息收发正常。

故障排查口诀：Bot 没反应 → 先查 `hermes gateway status` 是否 running → 再查日志 `tail -f ~/.hermes/logs/gateway.log` → 看到 "No messaging platforms enabled" 说明 Token 没读到 → 检查 plist 的 EnvironmentVariables → 改完 `hermes gateway restart` → 再次验证。

## 4 配置中文回复

Hermes Agent 默认用英文回复。编辑 `SOUL.md` 文件可以改变它的行为、语言、知识库——这是 Hermes 最强大的定制入口。

### 编辑 SOUL.md

`SOUL.md` 是 Hermes 的系统提示词文件，每次对话都会被注入。你可以在这里写入任何想让 Hermes 知道的信息。

open ~/.hermes/SOUL.md

### 添加中文语言规则

在文件顶部添加：

CRITICAL LANGUAGE RULE: You MUST reply in Chinese (简体中文) at all times. The user speaks Chinese. Never use English unless the user explicitly asks.
⚠️ 这会覆盖你已有的 SOUL.md，如果已有自定义内容请先备份。

### （可选）注入项目知识

你还可以在 SOUL.md 中写入：用户身份和技能、项目结构、代码规范、GitHub 仓库信息、常用命令…… 这些会成为 Hermes 的"长期记忆"，每次对话都能引用。

### 重启 Gateway 生效

hermes gateway restart

修改 SOUL.md 后必须重启 Gateway 才能生效。终端 chat 模式则无需重启，下次启动自动加载。

SOUL.md 的作用：它不仅控制语言，还能注入你的身份信息、项目上下文、代码规范、安全红线——相当于 Claude Code 的 CLAUDE.md + rules/ + memory/ 三合一。

## 5 程序坞一键启动（macOS）

创建一个 .app 捆绑包放在程序坞，点击图标即可启动 Hermes Agent 对话。

更简单的方法：一键启动器页面 提供了现成的 .app 创建命令，复制粘贴到终端即可完成，无需手动创建文件。

### 创建 .app 目录结构

mkdir -p ~/Applications/hermes.app/Contents/{MacOS,Resources}

### 创建启动脚本

用以下内容创建 `~/Applications/hermes.app/Contents/MacOS/hermes-launcher`：

#!/bin/bash HERMES_BIN="$HOME/.local/bin/hermes" if [ ! -f "$HERMES_BIN" ]; then osascript -e 'display dialog "Hermes Agent 未安装" buttons {"好"} with icon stop' exit 1 fi TMP_SCRIPT=$(mktemp /tmp/hermes-launch.XXXXXX) cat > "$TMP_SCRIPT" << 'SCRIPT' clear echo "⚕ Hermes Agent" echo "" export PATH="$HOME/.local/bin:$PATH" exec hermes chat SCRIPT chmod +x "$TMP_SCRIPT" osascript -e 'tell app "Terminal" to activate' \ -e "tell app \"Terminal\" to do script \"$TMP_SCRIPT; rm -f $TMP_SCRIPT\""

赋予执行权限：`chmod +x ~/Applications/hermes.app/Contents/MacOS/hermes-launcher`

### 创建 Info.plist

cat > ~/Applications/hermes.app/Contents/Info.plist << 'EOF' <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>CFBundleExecutable</key> <string>hermes-launcher</string> <key>CFBundleName</key> <string>Hermes</string> <key>CFBundleIdentifier</key> <string>ai.hermes.launcher</string> <key>CFBundleVersion</key> <string>1.0</string> <key>LSUIElement</key> <true/> </dict> </plist> EOF

### 拖入程序坞

在 Finder 中打开 `~/Applications/`，将 `hermes.app` 拖入程序坞即可。点击图标 → 自动打开终端 → 启动 Hermes Agent 对话。

⚠️ 踩坑：osascript 转义地狱。直接在 osascript 中内嵌复杂脚本会因为引号嵌套导致 `预期是"却找到未知的记号"` 语法错误。
正确做法：先把脚本写入临时文件，再让 osascript 调用该文件路径。如上面启动脚本所示——用 `mktemp` + heredoc + `chmod +x`，避免任何嵌套转义。

## ◆ 常用命令速查

命令 | 作用
--- | ---
`hermes chat` | 启动终端对话模式
`hermes --tui` | 启动 TUI 界面模式
`hermes setup` | 重新运行配置向导
`hermes gateway install` | 安装 Gateway launchd 服务
`hermes gateway status` | 查看 Gateway 运行状态
`hermes gateway restart` | 重启 Gateway（改配置后必执行）
`hermes gateway logs` | 查看 Gateway 日志
`hermes update` | 更新 Hermes Agent 到最新版
`hermes --version` | 查看版本号
`tail -f ~/.hermes/logs/gateway.log` | 实时查看 Gateway 日志
`launchctl list ai.hermes.gateway` | 查看 launchd 服务状态（macOS）

## ◆ 踩坑合集（全部亲测）

以下所有问题都是我在部署过程中实际遇到的，附详细原因和解决方法。

Q：安装脚本卡在 Node.js 下载？HTTP/2 报错？

原因：nodejs.org 的 HTTP/2 在某些网络环境下不稳定，curl 报 `HTTP/2 stream error (92)`。
解决：Ctrl+C 终止脚本 → 用 `curl --http1.1 -L "https://nodejs.org/dist/v22.11.0/..." -o /tmp/node.tar.gz` 手动下载 → 解压到 `~/.hermes/node/` → 重新运行安装脚本。关键是 `--http1.1` 标志。

Q：Gateway 启动后 Bot 完全没反应？

原因：最可能的原因是 launchd 没有读到环境变量。launchd 服务不 source shell 配置文件，也不读 .env 文件。
诊断：日志中出现 `No messaging platforms enabled` 即说明 Token 未加载。
解决：必须把 `TELEGRAM_BOT_TOKEN`、`DEEPSEEK_API_KEY` 等环境变量直接写入 `~/Library/LaunchAgents/ai.hermes.gateway.plist` 的 `EnvironmentVariables` 字典中，然后 `hermes gateway restart`。

Q：Bot 回复了但是英文？怎么改成中文？

解决：编辑 `~/.hermes/SOUL.md`，在顶部添加 `CRITICAL LANGUAGE RULE: You MUST reply in Chinese (简体中文) at all times.`，然后 `hermes gateway restart` 重启生效。

Q：DeepSeek API 返回 401 Authentication Fails？

原因：你可能有两个不同的 API Key（Claude Code 用的 ANTHROPIC_AUTH_TOKEN 和 DeepSeek 原生 Key）。setup 向导中输入的 Key 可能无效。
诊断：用 curl 测试 Key 是否有效：
`curl https://api.deepseek.com/v1/chat/completions -H "Authorization: Bearer sk-你的key" -H "Content-Type: application/json" -d '{"model":"deepseek-v4-pro","messages":[{"role":"user","content":"hi"}]}'`
返回 200 则 Key 有效，返回 401 则 Key 无效。
解决：用有效的 Key 替换 plist 中 `DEEPSEEK_API_KEY` 的值，重启 Gateway。

Q：Gateway 状态是 running 但 Bot 还是没反应？

原因：可能 Gateway 进程在运行但卡在某个步骤（如首次启动时自动安装 Node.js 卡住）。
诊断：`tail -f ~/.hermes/logs/gateway.log` 实时看日志，看卡在哪一步。
解决：如果日志中长时间无新输出，先 `launchctl unload ~/Library/LaunchAgents/ai.hermes.gateway.plist` 停止 → 检查环境变量配置 → 手动完成卡住的依赖安装 → `launchctl load ~/Library/LaunchAgents/ai.hermes.gateway.plist` 重新加载。

Q：程序坞 hermes.app 点击后报错打不开？

原因：通常是 osascript 脚本中的引号嵌套导致语法错误（"预期是"却找到未知的记号"）。
解决：不要在 osascript 中内嵌复杂脚本。用 `mktemp` 创建临时脚本文件，heredoc 写入内容，然后让 osascript 只调用文件路径。详见上方「程序坞一键启动」章节的完整脚本。

Q：安装完成后 `hermes` 命令找不到？

解决：安装脚本会在 `~/.zshrc` 中添加 PATH。执行 `source ~/.zshrc` 或关闭终端重新打开即可。确认 `~/.local/bin/hermes` 文件存在。

Q：Gateway 可以在 Windows 上运行吗？

Hermes Agent 本身支持 Windows，但 Gateway 的 launchd 服务模式是 macOS 专属。Windows 上可以通过任务计划程序（Task Scheduler）实现类似的开机自启效果，或者直接在终端中运行 `hermes gateway run` 前台运行。

### 相关链接

Hermes Agent github.com/NousResearch/hermes-agent MIT 开源
一键启动器Hermes Agent 桌面快捷启动
Telegram Bot Telegram AI 机器人项目页面
DeepSeek 平台platform.deepseek.com 无需魔法
BotFather t.me/BotFather（Telegram 内打开）
Claude Code 指南Claude Code 完整指南
本页被阅读 ... 次