Hermes-Agent 接入教程

配置 Hermes-Agent 使用 XiDao Api 作为后端 AI 服务，享受强大的终端 AI 助手体验

什么是 Hermes-Agent?

Hermes-Agent 是由 NousResearch 开发的开源 AI 助手，支持在终端中直接与 AI 交互。它具备强大的工具调用能力、代码执行、文件操作等功能，是目前最活跃的开源 AI Agent 项目之一。

提示: Hermes-Agent 原生支持 OpenAI 兼容接口，可以完美接入 XiDao Api 中转服务。
🖥️

终端原生

完全在命令行中运行，支持多种终端后端（本地/Docker/SSH/云沙箱）

🔧

强大工具集

内置文件读写、代码执行、网络搜索、MCP 服务器等丰富工具

🧠

持久记忆

支持长期记忆系统，能记住用户偏好和项目上下文

🌐

API 服务器

可作为 OpenAI 兼容的 HTTP 端点暴露给其他应用使用

环境要求

依赖 最低版本 检查命令 用途
Python 3.10+ python --version 运行 Hermes-Agent 核心
pip 23+ pip --version 包管理器
Git v2.23+ git --version 版本控制
注意: 推荐使用 Python 3.11 或 3.12 以获得最佳兼容性。Windows 用户建议使用 WSL2 或 Git Bash。

安装 Hermes-Agent

方式一：通过 pip 安装（推荐）

bash
# 安装 Hermes-Agent
pip install hermes-agent

# 验证安装
hermes --version
hermes config check

方式二：从源码安装（开发版）

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

# 安装依赖
pip install -e .

# 验证安装
hermes --version

方式三：Docker 安装

bash
# 拉取镜像并运行
docker run -d \
  --name hermes \
  -v ~/.hermes:/root/.hermes \
  -e OPENAI_API_KEY=sk-your-key \
  -e OPENAI_BASE_URL=https://api.xidao.online/v1 \
  nousresearch/hermes-agent:latest

# 进入容器
docker exec -it hermes bash

配置 API 密钥

Hermes-Agent 的所有配置存储在 ~/.hermes/ 目录中：

1. 创建环境变量文件

bash
# 创建配置目录
mkdir -p ~/.hermes

# 创建环境变量文件
nano ~/.hermes/.env

2. 添加 API 配置

bash
# XiDao Api 配置（将 sk-your-api-key 替换为你的实际密钥）
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_BASE_URL=https://api.xidao.online/v1

# 如果使用全球加速节点，改为：
# OPENAI_BASE_URL=https://global.xidao.online/v1
安全提醒: 请勿将 .env 文件提交到公开仓库！设置权限：chmod 600 ~/.hermes/.env

3. 使用命令行设置（替代方案）

bash
# 设置 API Key
hermes config set OPENAI_API_KEY sk-your-api-key-here

# 设置 Base URL
hermes config set OPENAI_BASE_URL https://api.xidao.online/v1

# 验证配置
hermes config check

配置模型

编辑配置文件来选择默认模型和备用模型：

编辑 config.yaml

bash
# 打开配置文件
hermes config edit
# 或直接编辑
nano ~/.hermes/config.yaml

推荐配置示例

yaml
# 主模型配置
model: anthropic/claude-opus-4

# 备用模型（主模型不可用时自动切换）
fallback_models:
  - openai/gpt-5.1
  - google/gemini-2.5-pro

# 辅助功能配置
auxiliary:
  vision:
    provider: "main"
    model: "gpt-4o"
    
# 终端后端配置
terminal:
  backend: local  # local | docker | ssh | modal
  cwd: "."
  timeout: 180

# 上下文压缩设置
compression:
  mode: safeguard  # safeguard | aggressive | none
  max_tokens: 128000

通过命令行快速设置

bash
# 设置默认模型
hermes config set model anthropic/claude-opus-4

# 设置备用模型
hermes config set fallback_models '["openai/gpt-5.1", "google/gemini-2.5-pro"]'

# 查看当前配置
hermes config
成功! 配置完成后即可开始使用。推荐使用 Claude Opus 4 作为主力模型，GPT-5.1 作为备选。

使用方法

启动交互式对话

bash
# 启动交互式对话
hermes chat

# 指定模型启动
hermes chat --model anthropic/claude-sonnet-4

# 带初始问题启动
hermes chat --prompt "帮我分析这个项目的结构"

# Print 模式（一次性问答）
hermes chat --print "解释这段代码的作用"

常用命令

命令 功能说明
hermes chat 启动交互式对话
hermes config 查看/编辑配置
hermes config check 检查配置问题
hermes config migrate 更新配置到最新格式
hermes gateway start 启动 API 服务器
hermes skills list 查看已安装技能

启动 API 服务器（可选）

Hermes-Agent 可以作为 OpenAI 兼容的 HTTP 端点运行，供其他应用调用：

bash
# 启动 API 服务器
hermes gateway start

# 默认监听 http://localhost:8787

# 设置访问密钥（可选但推荐）
export API_SERVER_KEY=your-secret-key

# 调用示例
curl http://localhost:8787/v1/chat/completions \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
注意: API Server 会暴露完整的工具集（包括终端命令），请确保设置访问密钥并限制绑定地址。

核心功能介绍

💻 多终端后端

支持本地执行、Docker 容器、SSH 远程服务器、Modal 云沙箱等多种后端：

yaml
terminal:
  backend: local        # 本地执行
  # backend: docker      # Docker 容器
  # backend: ssh         # SSH 远程
  # backend: modal       # Modal 云沙箱
  
  timeout: 180           # 单命令超时时间（秒）

🔧 内置工具集

Hermes-Agent 提供丰富的内置工具：

  • 文件操作: 读取、写入、编辑、搜索文件
  • 代码执行: 运行 Python、Bash、Node.js 代码
  • 网络搜索: 搜索网页、获取 URL 内容
  • Git 操作: 提交、分支、查看历史
  • MCP 服务器: 连接外部 MCP 工具服务

🧠 记忆系统

支持持久化记忆，自动保存重要信息：

text
~/.hermes/
├── memories/
│   ├── MEMORY.md      # 全局记忆
│   └── USER.md        # 用户偏好
├── SOUL.md            # Agent 身份定义
└── sessions/          # 会话历史

👁️ 视觉能力

支持图像理解和分析，可配置独立的视觉模型：

yaml
auxiliary:
  vision:
    provider: "main"     # 使用主模型
    model: "gpt-4o"      # 或专用视觉模型

常见问题排查

❌ 连接失败

检查以下几点：

  • 确认 ~/.hermes/.env 文件中的 OPENAI_BASE_URL 和 OPENAI_API_KEY 正确
  • 确认 Base URL 包含 /v1 后缀
  • 尝试切换国内/全球节点
  • 检查网络连接和防火墙设置

❌ API Key 无效

请确认：

  • API Key 格式正确（以 sk- 开头）
  • 令牌未过期且余额充足
  • 令牌状态为启用（非禁用）

❌ 模型名称错误

如果提示模型不存在，请检查模型 ID 是否正确。可通过以下方式获取可用模型列表：

bash
curl https://api.xidao.online/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

⚠️ 响应慢或超时

  • 切换到更快的模型（如 Gemini Flash）
  • 增加 terminal.timeout 值
  • 减少请求的上下文长度
  • 尝试切换国内/全球节点

⚠️ Python 版本问题

如果遇到 Python 相关错误，确保使用 Python 3.10+。建议使用虚拟环境：

bash
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# 安装 Hermes-Agent
pip install hermes-agent
提示: 遇到问题时，先运行 hermes config check 自动诊断配置问题。
上一篇 ← OpenClaw 教程 下一篇 Cline 教程 → ← 返回教程列表