安装 · DeepSeek 接入 · Telegram Gateway · 中文配置 · 程序坞启动
macOS / Windows 双平台，所有踩坑已替你填平
Hermes Agent 是 Nous Research 开发的开源 AI Agent 框架（MIT 协议）。和 Claude Code 类似——在终端里运行，能读文件、写代码、执行命令、操控浏览器。但它不绑定任何模型厂商，可以自由接入 DeepSeek、OpenAI、Anthropic 等任意模型。
MIT 协议，代码公开，可自由修改和分发
支持 DeepSeek / OpenAI / Anthropic / Google 等任意厂商
浏览器操控、GitHub 管理、论文写作、代码执行、音乐创作
跨会话保持上下文，SOUL.md 系统提示词持久注入
内置 Gateway，一条命令接入 Telegram Bot
cua-driver 驱动，可操控 macOS 桌面应用
| 维度 | 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 |
一条命令完成安装。脚本自动处理 uv、Python 3.11、Node.js 及全部依赖。
按 Command + 空格 搜索「终端」，打开终端 App。
脚本会自动完成：安装 uv 包管理器 → 创建 Python 3.11 虚拟环境 → 安装 100+ 依赖包 → 安装 Node.js → 安装 cua-driver。
安装完成后关闭终端重新打开，让 PATH 生效。然后验证：
输出版本号（如 hermes 0.14.0）即安装成功。
curl: (92) HTTP/2 stream error。这是因为 nodejs.org 的 HTTP/2 在某些网络下不稳定。Ctrl+C 终止，然后手动下载：
--http1.1 标志强制使用 HTTP/1.1 协议。然后重新运行安装脚本即可跳过 Node.js 下载步骤。
Hermes Agent 在 Windows 依赖 Git Bash。按 Win + R 输入 wt 打开终端：
打开 Git Bash，执行：
~/.local/bin/hermes，配置在 ~/.hermes/，日志在 ~/.hermes/logs/。安装完成后运行 hermes setup 进入交互式配置向导，配置模型和 API Key。
向导会依次询问以下配置项。
向导列出支持的提供商，选择 DeepSeek（或用方向键选择后回车）。
去 platform.deepseek.com 注册 → API Keys → 创建 Key → 复制粘贴到终端。
sk- 开头。新用户有免费额度，轻度使用足够。模型名默认 deepseek-v4-pro、Base URL 默认 https://api.deepseek.com/v1，直接回车确认。TTS（文字转语音）选 N 跳过。
输入一句话测试，收到回复说明模型连接成功。
~/.hermes/config.yaml，密钥写入 ~/.hermes/.env。你可以随时编辑这两个文件修改配置。
ANTHROPIC_AUTH_TOKEN，一个是 DeepSeek 原生 Key。两者格式相同但值不同。用 DeepSeek 平台上的原始 Key，不要用 Claude Code 转接的那个。如果配置后对话报 401 认证失败，说明 Key 无效——去 DeepSeek 平台重新创建一个。
Hermes Agent 内置 Telegram Gateway，让你的 Bot 在 Telegram 中 24 小时在线，自动回复消息。这是它相比 Claude Code 最大的优势之一。
Gateway 作为 macOS launchd 服务 24 小时运行，崩溃自动重启。支持 30+ 命令，DuckDuckGo 搜索、代码执行、浏览器操控全在 Telegram 里完成。
在 Telegram 中搜索 @BotFather → 发送 /newbot → 按提示设置名称和用户名 → 获取 Bot Token（格式：123456:ABC-DEF1234ghiJKL）。
在 Telegram 中搜索 @userinfobot → 发送 /start → 获取你的数字 ID。
创建 ~/.hermes/.env 文件：
EnvironmentVariables 字典中。详见下一步。
这条命令会：创建 launchd plist → 注册为开机自启服务 → 启动 Gateway。
打开 launchd 配置文件：
在 <dict> 中添加 EnvironmentVariables 段：
保存后重启 Gateway：
看到 ✓ telegram connected 即成功。
实时查看日志，确认消息收发正常。
hermes gateway status 是否 running → 再查日志 tail -f ~/.hermes/logs/gateway.log → 看到 "No messaging platforms enabled" 说明 Token 没读到 → 检查 plist 的 EnvironmentVariables → 改完 hermes gateway restart → 再次验证。
Hermes Agent 默认用英文回复。编辑 SOUL.md 文件可以改变它的行为、语言、知识库——这是 Hermes 最强大的定制入口。
SOUL.md 是 Hermes 的系统提示词文件，每次对话都会被注入。你可以在这里写入任何想让 Hermes 知道的信息。
在文件顶部添加：
你还可以在 SOUL.md 中写入：用户身份和技能、项目结构、代码规范、GitHub 仓库信息、常用命令…… 这些会成为 Hermes 的"长期记忆"，每次对话都能引用。
修改 SOUL.md 后必须重启 Gateway 才能生效。终端 chat 模式则无需重启，下次启动自动加载。
创建一个 .app 捆绑包放在程序坞，点击图标即可启动 Hermes Agent 对话。
用以下内容创建 ~/Applications/hermes.app/Contents/MacOS/hermes-launcher：
赋予执行权限：chmod +x ~/Applications/hermes.app/Contents/MacOS/hermes-launcher
在 Finder 中打开 ~/Applications/，将 hermes.app 拖入程序坞即可。点击图标 → 自动打开终端 → 启动 Hermes Agent 对话。
预期是"却找到未知的记号" 语法错误。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 前台运行。