Hermes Agent macOS 安装、配置与使用完全指南

Hermes Agent - 由 Nous Research 开发的自我改进型 AI 智能体
版本: 最新稳定版
适用系统: macOS (支持 Apple Silicon 和 Intel)
文档更新日期: 2026-04-13

---

1. 系统要求

硬件要求

• 处理器: Apple Silicon (M1/M2/M3) 或 Intel 处理器
• 内存: 最低 4GB RAM，推荐 8GB+
• 存储: 至少 2GB 可用磁盘空间
• 网络: 稳定的互联网连接

软件要求

• macOS: 12.0 (Monterey) 或更高版本
• Python: 3.11 或更高版本
• Homebrew: 最新稳定版
• 终端: Terminal.app、iTerm2 或 Warp

支持的模型提供商

• Nous Portal
• OpenRouter (200+ 模型)
• z.ai/GLM
• Kimi/Moonshot
• MiniMax
• OpenAI
• Anthropic
• 自定义 API 端点

---

2. 前置准备

2.1 安装 Homebrew（如果尚未安装）

bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，根据提示将 Homebrew 添加到 PATH：

bash
# Apple Silicon (M1/M2/M3)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Intel Mac
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

验证安装：

bash
brew --version

2.2 安装 Python 3.11+

bash
# 使用 Homebrew 安装 Python
brew install python@3.11

# 验证安装
python3.11 --version

# 设置默认 Python 版本（可选）
brew link python@3.11

2.3 安装 uv（推荐的 Python 包管理器）

bash
# 使用官方安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh

# 重新加载 shell 配置
source ~/.zshrc

# 验证安装
uv --version

2.4 安装其他依赖（可选）

bash
# Git（用于版本管理和更新）
brew install git

# wget（下载工具）
brew install wget

# tree（目录结构查看）
brew install tree

---

3. 安装步骤

方式一：一键安装脚本（推荐）

bash
# 下载并执行安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装脚本会自动：

• 检测操作系统和架构
• 安装必要的系统依赖
• 创建虚拟环境
• 安装 Hermes Agent 及其依赖
• 配置环境变量

方式二：手动安装（适合高级用户）

bash
# 1. 克隆仓库
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 2. 创建虚拟环境
uv venv venv --python 3.11
source venv/bin/activate

# 3. 安装所有功能（包含语音等额外依赖）
uv pip install -e ".[all]"

# 4. 验证安装
python -m pytest tests/ -q

安装后配置

bash
# 重新加载 shell 配置
source ~/.zshrc  # 或 source ~/.bashrc

# 验证安装
hermes --version

# 运行诊断工具
hermes doctor

---

4. 初始配置

4.1 运行设置向导

bash
hermes setup

设置向导会引导你完成：

1. 选择 LLM 提供商: OpenRouter、OpenAI、Anthropic 等
2. 配置 API Key: 输入你的 API 密钥
3. 选择默认模型: 设置默认使用的 AI 模型
4. 配置工具: 选择启用哪些工具
5. 设置消息平台（可选）: Telegram、Discord 等

4.2 手动配置 API Key

bash
# 设置 OpenRouter API Key
hermes config set openrouter_api_key "your-api-key-here"

# 设置 OpenAI API Key
hermes config set openai_api_key "your-api-key-here"

# 设置 Anthropic API Key
hermes config set anthropic_api_key "your-api-key-here"

4.3 选择模型

bash
# 交互式选择模型
hermes model

# 或直接指定模型
hermes model openrouter:anthropic/claude-3.5-sonnet

4.4 配置文件位置

Hermes 的配置文件位于：

bash
~/.hermes/config.yaml        # 主配置文件
~/.hermes/tools/             # 工具配置
~/.hermes/skills/            # 技能文件
~/.hermes/memories/          # 记忆文件

查看配置：

bash
cat ~/.hermes/config.yaml

---

5. 基本使用

5.1 启动交互模式

bash
# 启动终端交互界面
hermes

5.2 常用命令

在交互模式下，可以使用以下斜杠命令：

命令	功能	示例
/new 或 /reset	开始新对话	/new
/model	切换模型	/model openrouter:gpt-4
/personality	设置人格	/personality assistant
/retry	重试最后一次响应	/retry
/undo	撤销最后一次交互	/undo
/compress	压缩上下文	/compress
/usage	查看使用统计	/usage
/skills	浏览可用技能	/skills
/tools	查看启用的工具	/tools
/help	查看帮助	/help

5.3 键盘快捷键

快捷键	功能
Ctrl+C	中断当前任务
Ctrl+D	退出 Hermes
↑/↓	浏览命令历史
Tab	自动补全命令
Ctrl+R	搜索命令历史

5.4 查看帮助

bash
# 查看所有命令
hermes --help

# 查看子命令帮助
hermes model --help
hermes tools --help
hermes config --help

---

6. 高级功能

6.1 工具系统

Hermes 内置 40+ 工具，可以执行各种任务：

bash
# 查看可用工具
hermes tools

# 启用/禁用特定工具
hermes tools enable shell
hermes tools disable web_search

常用工具集

• Shell: 执行 shell 命令
• Web Search: 网络搜索
• File System: 文件操作
• Python: 执行 Python 代码
• Browser: 网页浏览
• Git: Git 操作

6.2 终端后端

支持多种终端后端：

bash
# 本地执行（默认）
hermes config set terminal_backend local

# Docker 容器
hermes config set terminal_backend docker

# SSH 远程
hermes config set terminal_backend ssh
hermes config set ssh_host "user@remote-server"

# Daytona（无服务器）
hermes config set terminal_backend daytona

6.3 子代理（Subagents）

可以生成隔离的子代理进行并行工作：

# 在对话中使用
/spawn 帮我分析这个数据集并生成报告

6.4 上下文文件

项目上下文文件会影响每次对话：

bash
# 创建项目上下文文件
echo "这是一个 Python 数据分析项目" > .hermes-context

# 上下文文件会自动加载到对话中

---

7. 多平台集成

7.1 消息网关

Hermes 可以同时作为多个消息平台的机器人：

bash
# 启动网关设置向导
hermes gateway setup

# 启动网关
hermes gateway start

7.2 Telegram 集成

bash
# 配置 Telegram
hermes gateway setup telegram

# 需要提供的信息：
# - Bot Token（从 @BotFather 获取）
# - 允许的用户 ID

获取 Telegram Bot Token:

1. 在 Telegram 中搜索 @BotFather
2. 发送 /newbot 命令
3. 按照提示创建机器人
4. 复制获得的 Token

7.3 Discord 集成

bash
# 配置 Discord
hermes gateway setup discord

# 需要提供的信息：
# - Bot Token
# - 允许的服务器 ID
# - 允许的频道 ID

获取 Discord Bot Token:

1. 访问 Discord Developer Portal
2. 创建新应用
3. 在 "Bot" 页面创建机器人并复制 Token
4. 启用必要的 Intents（Message Content Intent 等）

7.4 其他平台

bash
# Slack
hermes gateway setup slack

# WhatsApp
hermes gateway setup whatsapp

# Signal
hermes gateway setup signal

# Email
hermes gateway setup email

7.5 网关管理

bash
# 查看网关状态
hermes gateway status

# 停止网关
hermes gateway stop

# 重启网关
hermes gateway restart

---

8. 技能系统

8.1 技能是什么？

技能是 Hermes 的核心特性之一：

• 自动创建: 完成复杂任务后自动保存为技能
• 自我改进: 使用过程中自动优化
• 持久化: 跨会话保留
• 可共享: 可以从 Skills Hub 下载社区技能

8.2 查看和管理技能

bash
# 查看已安装的技能
hermes skills

# 查看特定技能详情
hermes skills view <skill-name>

# 启用/禁用技能
hermes skills enable <skill-name>
hermes skills disable <skill-name>

# 删除技能
hermes skills delete <skill-name>

8.3 使用技能

bash
# 列出可用技能
/skills

# 使用特定技能
/<skill-name>

# 在对话中自动触发
# 当检测到相关任务时，技能会自动激活

8.4 从 Skills Hub 安装技能

访问 Skills Hub 浏览社区技能：

bash
# 安装技能（假设命令）
hermes skills install <skill-url-or-id>

# 更新所有技能
hermes skills update

8.5 创建自定义技能

技能文件位于 ~/.hermes/skills/：

yaml
# ~/.hermes/skills/my-skill.yaml
name: my-custom-skill
description: "描述这个技能的用途"
triggers:
  - "触发关键词1"
  - "触发关键词2"
instructions: |
  这里是技能的详细指令
  可以包含多行文本
tools:
  - shell
  - python

---

9. 定时任务

9.1 创建定时任务

Hermes 内置 cron 调度器：

bash
# 创建定时任务（自然语言）
hermes cron add "每天早上 9 点发送今日待办事项"

# 创建定时任务（cron 表达式）
hermes cron add "0 9 * * *" "发送每日报告"

# 查看所有定时任务
hermes cron list

9.2 管理定时任务

bash
# 暂停任务
hermes cron pause <task-id>

# 恢复任务
hermes cron resume <task-id>

# 删除任务
hermes cron delete <task-id>

# 立即执行任务
hermes cron run <task-id>

9.3 常见定时任务示例

bash
# 每日备份
hermes cron add "0 2 * * *" "备份重要文件到云存储"

# 每周报告
hermes cron add "0 17 * * 5" "生成本周工作总结报告"

# 每月审计
hermes cron add "0 10 1 * *" "执行系统安全检查"

# 每小时提醒
hermes cron add "0 * * * *" "提醒我喝水和休息"

---

10. 故障排查

10.1 诊断工具

bash
# 运行完整诊断
hermes doctor

诊断工具会检查：

• Python 版本
• 依赖包完整性
• 配置文件语法
• API Key 有效性
• 网络连接

10.2 常见问题

问题 1: command not found: hermes

解决方案:

bash
# 重新加载 shell 配置
source ~/.zshrc

# 或检查 PATH
echo $PATH

# 如果 Hermes 不在 PATH 中，手动添加
echo 'export PATH="$HOME/.hermes/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

问题 2: API Key 错误

解决方案:

bash
# 检查 API Key 是否正确配置
hermes config get openrouter_api_key

# 重新设置 API Key
hermes config set openrouter_api_key "your-api-key"

问题 3: 依赖冲突

解决方案:

bash
# 重新创建虚拟环境
cd ~/.hermes
rm -rf venv
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all]"

问题 4: 权限问题

解决方案:

bash
# 修复文件权限
chmod -R 755 ~/.hermes
chown -R $(whoami) ~/.hermes

10.3 查看日志

bash
# 查看 Hermes 日志
tail -f ~/.hermes/logs/hermes.log

# 查看网关日志
tail -f ~/.hermes/logs/gateway.log

10.4 重置配置

bash
# 备份当前配置
cp -r ~/.hermes ~/.hermes.backup

# 删除配置（谨慎操作）
rm -rf ~/.hermes

# 重新运行设置向导
hermes setup

---

11. 更新升级

11.1 使用内置更新命令

bash
# 更新到最新版本
hermes update

# 查看当前版本
hermes --version

11.2 手动更新

bash
# 如果使用 Git 安装
cd hermes-agent
git pull origin main
source venv/bin/activate
uv pip install -e ".[all]"

# 重启服务（如果网关在运行）
hermes gateway restart

11.3 回滚到旧版本

bash
# 查看可用版本
git tag

# 切换到特定版本
git checkout v1.2.3
uv pip install -e ".[all]"

---

12. 完全卸载

12.1 停止所有服务

bash
# 停止网关
hermes gateway stop

# 查看并终止所有 Hermes 进程
ps aux | grep hermes
kill -9 <PID>

12.2 删除 Hermes 文件

bash
# 删除 Hermes 安装目录
rm -rf ~/.hermes

# 删除源代码（如果是从 Git 克隆的）
rm -rf ~/hermes-agent

# 删除虚拟环境（如果单独创建）
# 通常在 ~/.hermes/venv 中

12.3 清理环境变量

bash
# 编辑 shell 配置文件
nano ~/.zshrc  # 或 nano ~/.bashrc

# 删除以下行（如果存在）：
# export PATH="$HOME/.hermes/bin:$PATH"
# source ~/.hermes/venv/bin/activate

# 重新加载配置
source ~/.zshrc

12.4 清理 Homebrew 依赖（可选）

bash
# 清理未使用的依赖
brew autoremove

# 清理缓存
brew cleanup

12.5 删除 launchd 服务（如果创建了）

bash
# 查看是否存在 launchd 服务
launchctl list | grep hermes

# 停止并删除服务
launchctl stop com.nousresearch.hermes
launchctl unload ~/Library/LaunchAgents/com.nousresearch.hermes.plist
rm ~/Library/LaunchAgents/com.nousresearch.hermes.plist

12.6 验证卸载

bash
# 确认命令不存在
which hermes
# 应该返回空或 "hermes not found"

# 确认目录已删除
ls -la ~/.hermes
# 应该返回 "No such file or directory"

---

13. 常见问题 FAQ

Q1: Hermes Agent 和 OpenClaw 有什么区别？

A: Hermes Agent 是 OpenClaw 的继任者，增加了：

• 自我改进的学习循环
• 自动技能创建和优化
• 跨会话记忆
• 更好的多平台支持
• 内置定时任务调度

Q2: 可以在 M1/M2/M3 Mac 上运行吗？

A: 完全可以。Hermes 支持 Apple Silicon 架构，安装脚本会自动检测并配置。

Q3: 必须使用 OpenRouter 吗？

A: 不是。支持多种提供商：OpenAI、Anthropic、Kimi、MiniMax 等，也可以配置自定义 API 端点。

Q4: 如何在后台运行网关？

A: 使用 nohup 或创建 launchd 服务：

bash
# 使用 nohup
nohup hermes gateway start > /dev/null 2>&1 &

# 或创建 launchd 服务（推荐）
cat > ~/Library/LaunchAgents/com.nousresearch.hermes.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>Label</key>
    <string>com.nousresearch.hermes</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/$(whoami)/.hermes/venv/bin/hermes</string>
        <string>gateway</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.nousresearch.hermes.plist

Q5: 如何备份我的配置和记忆？

A:

bash
# 备份整个 Hermes 目录
tar -czf hermes-backup-$(date +%Y%m%d).tar.gz ~/.hermes

# 或只备份重要文件
cp -r ~/.hermes/config.yaml ~/hermes-config-backup/
cp -r ~/.hermes/memories ~/hermes-memories-backup/
cp -r ~/.hermes/skills ~/hermes-skills-backup/

Q6: 可以离线使用吗？

A: 部分功能可以。本地工具（shell、文件系统）可以离线使用，但 AI 对话需要网络连接来调用 LLM API。

Q7: 如何迁移到另一台 Mac？

A:

bash
# 旧 Mac 上备份
tar -czf hermes-backup.tar.gz ~/.hermes

# 传输到新 Mac（使用 scp、AirDrop 等）
scp hermes-backup.tar.gz user@new-mac:~

# 新 Mac 上恢复
tar -xzf hermes-backup.tar.gz
hermes doctor  # 验证配置

Q8: 如何保护 API Key 安全？

A:

bash
# 使用环境变量而不是直接写在配置中
export OPENROUTER_API_KEY="your-key"

# 在 config.yaml 中引用
# openrouter_api_key: ${OPENROUTER_API_KEY}

# 将环境变量添加到 .zshrc
echo 'export OPENROUTER_API_KEY="your-key"' >> ~/.zshrc

# 设置配置文件权限
chmod 600 ~/.hermes/config.yaml

Q9: 如何自定义提示词（Prompt）？

A: 编辑人格文件：

bash
# 查看可用的人格
ls ~/.hermes/personalities/

# 创建自定义人格
cat > ~/.hermes/personalities/my-assistant.md << EOF
你是一个专业的编程助手，擅长：
- Python 开发
- 系统架构设计
- 代码审查和优化

你的回答应该：
1. 简洁明了
2. 提供代码示例
3. 解释关键概念
EOF

# 使用自定义人格
/personality my-assistant

Q10: 性能优化建议？

A:

bash
# 1. 使用更快的模型
hermes model openrouter:google/gemini-flash

# 2. 减少工具数量
hermes tools disable <unused-tools>

# 3. 定期压缩上下文
/compress  # 在对话中

# 4. 使用本地模型（如果有 GPU）
hermes config set model_endpoint "http://localhost:8080"

# 5. 限制对话历史长度
hermes config set max_context_turns 20

---

📚 更多资源

• 官方文档: https://hermes-agent.nousresearch.com/docs
• GitHub 仓库: https://github.com/NousResearch/hermes-agent
• Skills Hub: https://skills.hermes-agent.com
• Discord 社区: https://discord.gg/nous-research
• 问题反馈: https://github.com/NousResearch/hermes-agent/issues

---

📝 文档维护

• 最后更新: 2026-04-13
• 版本: v1.0

---

祝你使用愉快！ 🎉