Hermes Agent 安装与配置：从零搭建你的专属AI终端代理

引言

Hermes Agent 是由 Nous Research 开发的开源 AI Agent 终端工具。它不同于传统的 AI 开发框架——你不需要编写复杂的代码，只需要通过 pip install 安装，几分钟就能拥有一个功能完整的 AI 终端助手。

本文将手把手带你完成从安装、配置到实际使用的全过程。

一、环境准备

系统要求

Python: 3.10 或更高版本
操作系统: macOS / Linux / Windows（通过 WSL）
终端: 支持 True Color 的现代终端（推荐 iTerm2、Windows Terminal、Kitty）

验证环境

# 检查 Python 版本
python --version
# Python 3.10.12

# 检查 pip 版本
pip --version
# pip 24.0

# Windows 用户请确保在 WSL 中运行
# 检查 WSL
wsl --status

二、安装 Hermes Agent

方法一：pip 安装（推荐）

# 安装最新稳定版
pip install hermes-agent

# 验证安装
hermes --version

方法二：从源码安装

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

# 以开发模式安装
pip install -e .

# 验证安装
hermes --version

安装后的目录结构

安装完成后，Hermes Agent 会在用户目录下创建配置文件目录：

~/.hermes/
├── config.yaml          # 主配置文件
├── memory/              # 记忆数据存储
│   └── vectors/         # 向量索引（如果启用）
├── skills/              # 技能目录
│   └── built-in/        # 内置技能
├── logs/                # 日志文件
└── sessions/            # 会话记录

三、初始化配置

运行初始化向导

hermes setup

初始化向导会引导你完成以下配置：

? 选择默认模型提供商:
  1) OpenAI
  2) Anthropic (Claude)
  3) DeepSeek
  4) Ollama (本地)
  5) 稍后配置

? 输入你的 API Key: [********]

? 选择交互模式:
  1) TUI (图形化终端界面)
  2) CLI (命令行模式)

? 是否启用 Telegram 网关? (y/N)

? 是否启用语音支持? (y/N)

手动配置 config.yaml

初始化完成后，你也可以直接编辑 ~/.hermes/config.yaml 进行精细配置。

基础配置模板

# ─────────────────────────────────────────────
# Hermes Agent 基础配置
# ─────────────────────────────────────────────

provider:
  default: deepseek

  deepseek:
    api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    model: deepseek-chat
    base_url: https://api.deepseek.com

interface:
  mode: tui
  theme: dark
  language: zh-CN

behavior:
  max_tool_calls: 25
  auto_approve: true
  verbose: false

每次修改配置文件后，可以通过 hermes doctor 验证配置的正确性：

hermes doctor

这条命令会检查配置文件的完整性、API Key 有效性、依赖完整性等。

四、多模型提供商配置

Hermes Agent 支持同时配置多个模型提供商，并动态切换。

配置 OpenAI

provider:
  openai:
    api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    model: gpt-4o
    base_url: https://api.openai.com/v1
    max_tokens: 8192
    temperature: 0.7

配置 Anthropic Claude

provider:
  anthropic:
    api_key: "sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    model: claude-sonnet-4-20250514
    max_tokens: 8192

配置 DeepSeek（推荐免费方案）

DeepSeek 提供慷慨的免费 API 额度，非常适合新手体验：

provider:
  deepseek:
    api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    model: deepseek-chat
    base_url: https://api.deepseek.com

在 platform.deepseek.com 注册即可获取免费 API Key。

配置 OpenRouter

OpenRouter 是一个模型聚合平台，可以访问多种模型：

provider:
  openrouter:
    api_key: "${OPENROUTER_API_KEY}"
    model: openai/gpt-4o
    base_url: https://openrouter.ai/api/v1

配置 Ollama（完全免费，本地运行）

如果你希望完全免费的体验，Ollama 是最佳选择：

provider:
  ollama:
    base_url: http://localhost:11434
    model: llama3.2
    keep_alive: 5m
    num_ctx: 4096

使用前需要先安装和启动 Ollama：

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 下载模型（以 llama3.2 为例）
ollama pull llama3.2

# 或者使用其他模型
ollama pull qwen2.5:7b
ollama pull deepseek-r1:8b

# 启动 Ollama 服务（通常自动运行）
ollama serve

动态切换模型

在 TUI 或对话中，你可以随时切换模型：

# 在对话中输入
/switch deepseek
/switch claude
/switch ollama

# 查看可用模型
/models

也可以同时配置多个提供商，让 Hermes Agent 根据任务自动选择最优模型：

provider:
  default: deepseek
  router:
    strategy: cost_based     # cost_based / capability_based
    # 简单任务使用便宜的模型
    simple_tasks: deepseek
    # 复杂推理使用更强的模型  
    complex_tasks: anthropic

五、连接多平台

1. 连接 Telegram

gateways:
  telegram:
    enabled: true
    bot_token: "7234567890:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw"  # 从 @BotFather 获取
    allowed_users: ["123456789"]             # 限制用户，留空则允许所有人
    command_prefix: "/hermes "               # 群聊中的命令前缀

获取 Telegram Bot Token：

在 Telegram 中搜索 @BotFather
发送 /newbot 创建新机器人
按照提示设置机器人名称和用户名
复制获得的 Bot Token

获取用户 ID：

搜索 @userinfobot
发送 /start
获取你的数字 ID

启动 Telegram 网关：

# 启动带 Telegram 网关的 Hermes
hermes --gateway telegram

2. 连接微信/企业微信

gateways:
  wechat:
    enabled: true
    # 使用企业微信机器人 Webhook
    webhook_url: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxx"
    # 或使用个人微信（通过第三方桥接）
    mode: webhook      # webhook / bridge

企业微信 Webhook 配置：

登录企业微信管理后台
创建一个群聊机器人
复制 Webhook URL

3. 连接飞书/Lark

gateways:
  feishu:
    enabled: true
    webhook_url: "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxx"
    app_id: "cli_xxxxxxxxxxxxx"       # 飞书应用 ID
    app_secret: "${FEISHU_APP_SECRET}"  # 应用密钥

4. 连接 Discord

gateways:
  discord:
    enabled: true
    bot_token: "${DISCORD_BOT_TOKEN}"
    allowed_channels: ["general", "ai-assistant"]

创建 Discord Bot：

访问 discord.com/developers/applications
创建新应用
进入 Bot 页面创建机器人
复制 Token
在 OAuth2 URL Generator 中勾选 bot 权限
将机器人邀请到你的服务器

六、常用命令指南

核心命令

# 启动 Hermes Agent（TUI 模式，默认）
hermes

# CLI 模式下的提问
hermes ask "用 Python 实现一个二分查找算法"

# 连续对话（CLI 交互模式）
hermes chat

# 运行技能
hermes run-skill code-review

# 查看版本
hermes --version

技能管理

# 列出所有可用技能
hermes skills list

# 查看技能详情
hermes skills view code-review

# 安装技能（从本地目录）
hermes skills install ~/my-skills/code-review

# 卸载技能
hermes skills uninstall code-review

系统管理

# 配置诊断
hermes doctor

# 重新初始化配置
hermes setup

# 查看帮助
hermes --help

# 查看特定命令帮助
hermes ask --help

TUI 界面快捷键

快捷键	功能
`Ctrl+N`	新建会话
`Ctrl+Q`	退出
`Ctrl+S`	保存当前会话
`Ctrl+F`	搜索历史消息
`Ctrl+L`	清屏
`Tab`	切换焦点区域
`/`	输入命令模式
`Esc`	取消/返回

七、技能系统使用

1. 使用内置技能

Hermes Agent 自带了一些实用的内置技能：

# 代码审查
hermes run-skill code-review --param file=./app.py

# 文档生成
hermes run-skill generate-docs --param project=./src

# 测试生成
hermes run-skill generate-tests --param file=./utils.py

# Git 提交信息生成
hermes run-skill git-commit --param diff=$(git diff)

2. 创建自定义技能

创建一个简单的技能：

# 创建技能目录
mkdir -p ~/.hermes/skills/translate-latex

# 创建 SKILL.md
cat > ~/.hermes/skills/translate-latex/SKILL.md << 'EOF'
---
name: translate-latex
description: 将学术论文翻译为中文，保留 LaTeX 格式
author: AIEng Hub
version: 1.0.0
type: skill
parameters:
  source_lang: en
  target_lang: zh-CN
  preserve_format: true
tools:
  - file_read
  - file_write
---
EOF

# 创建 prompt 模板
cat > ~/.hermes/skills/translate-latex/prompt.md << 'EOF'
你是一个专业的学术翻译助手。请将以下 ${source_lang} 论文翻译为 ${target_lang}。

要求：
1. 保持 LaTeX 格式不变
2. 专业术语使用标准翻译
3. 数学公式和引用保留原样
4. 表格和图表标题需要翻译

原文内容：
${content}
EOF

# 安装技能
hermes skills install ~/.hermes/skills/translate-latex

3. 在对话中使用技能

在 TUI 或 CLI 对话中，可以直接触发技能：

用户: @code-review 帮我审查 app.py 的代码
Agent: 正在运行 code-review 技能...

[代码审查结果]
1. 第15行: 变量命名不规范，建议将 `a` 改为 `user_age`
2. 第32行: 缺少异常处理
3. 第45-60行: 建议提取为单独的函数
...

八、进阶配置

启用 MCP 服务器

MCP (Model Context Protocol) 扩展了 Hermes Agent 的工具能力：

mcp:
  servers:
    # GitHub MCP 服务器
    github:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"

    # 文件系统 MCP 服务器  
    filesystem:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

配置代理

如果你在需要代理的网络环境中：

network:
  http_proxy: "http://127.0.0.1:7890"
  https_proxy: "http://127.0.0.1:7890"
  no_proxy: "localhost,127.0.0.1"

Cron 定时任务

scheduler:
  enabled: true
  jobs:
    - name: daily-standup
      schedule: "0 9 * * 1-5"     # 工作日早上9点
      skill: daily-report
      params:
        format: markdown

    - name: weekly-code-review
      schedule: "0 18 * * 5"       # 每周五下午6点
      skill: code-review
      params:
        repo: ./my-project

九、常见问题

Q1: 安装后 `hermes` 命令找不到

# 可能是 pip 安装路径不在 PATH 中
# 解决：
python -m hermes --version

# 或者将 Python 脚本目录添加到 PATH
export PATH=$PATH:$HOME/.local/bin
# 将上面这行添加到 ~/.bashrc 或 ~/.zshrc

Q2: API Key 错误

# 检查 API Key 是否正确
hermes doctor

# 如果显示认证失败，检查 config.yaml 中的 API Key
# 确保没有多余的空格或引号
# 建议使用环境变量
export DEEPSEEK_API_KEY="sk-xxxxx"

Q3: TUI 界面显示异常

# 检查终端是否支持 True Color
echo $TERM
# 应该显示 xterm-256color 或类似

# 尝试强制使用 256 色
export TERM=xterm-256color
hermes

Q4: Ollama 连接失败

# 检查 Ollama 是否运行
ollama list

# 检查 Ollama 服务状态
systemctl status ollama

# 如果 Ollama 在 Docker 中运行
docker ps | grep ollama

# 检查 config.yaml 中的 base_url 是否正确
# 默认: http://localhost:11434

Q5: 记忆不持久

# 检查记忆目录是否存在
ls -la ~/.hermes/memory/

# 检查配置文件中的记忆设置
cat ~/.hermes/config.yaml | grep -A 5 "memory"
# 确保 memory.type 已设置（默认为 local）

# 手动清空记忆（如果需要）
rm -rf ~/.hermes/memory/*

Q6: 网关无法连接

# 检查网络连接
curl -I https://api.telegram.org

# 检查网关配置是否正确
hermes doctor

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

十、卸载与清理

# 卸载 Hermes Agent
pip uninstall hermes-agent

# 清理配置文件和数据（可选）
rm -rf ~/.hermes

# 清理缓存
rm -rf ~/.cache/hermes

总结

通过本文，你已经完成了 Hermes Agent 的完整安装和配置。回顾一下关键步骤：

安装: pip install hermes-agent
初始化: hermes setup
配置模型: 选择 DeepSeek（免费）或 Ollama（本地免费）
体验: hermes 进入 TUI，或 hermes ask "你好" 快速提问
进阶: 连接 Telegram/微信、创建自定义技能、配置 MCP 服务器

Hermes Agent 的设计哲学是”开箱即用但不失深度”。初学者可以快速上手，而高级用户可以通过技能系统、MCP 和插件系统构建复杂的工作流。

参考资源

本文基于 Hermes Agent 最新稳定版撰写。配置项和命令可能随版本更新而变化，请以官方文档为准。

引言