由 NousResearch 开源驱动

Hermes Agent
中文指南

专为中国大陆开发者优化的 NousResearch Hermes Agent 部署与使用手册。从零开始，快速搭建你的 AI 智能体。

国内快速起步查看官方 GitHub

开源免费

Apache 2.0 协议

多模型支持

OpenAI 兼容格式

工具调用

Function Calling

本地部署

Ollama / vLLM

什么是 Hermes Agent

由 NousResearch 开发的开源 AI Agent 框架，基于 Hermes 3 大语言模型，专为工具调用和结构化推理深度优化。

工具调用 (Function Calling)

Hermes Agent 原生支持工具调用协议，能自主决策调用外部 API、数据库查询、文件操作等，真正实现 Agent 自主行动。

JSON 结构化输出

严格遵循 JSON Schema 输出，确保每次响应格式一致可解析。适用于自动化管线和后端集成场景，消除人工解析成本。

多步推理与规划

基于 Hermes 3 模型微调，具备强大的多步推理和任务分解能力。在复杂工作流中可自主规划执行路径。

灵活的模型后端

兼容所有 OpenAI 格式 API。可对接 OpenRouter、Together AI，也可本地部署 Ollama 或 vLLM，自由切换推理后端。

Hermes Agent vs OpenClaw 对比

对比维度	Hermes Agent	OpenClaw
核心定位	轻量级 Agent 框架，专注工具调用与推理	多 Agent 协作平台，侧重复杂任务编排
模型依赖	自有 Hermes 模型系列，本地部署友好	通常依赖第三方 API 调用
工具调用	原生内置，模型层面微调优化	通过框架层面抽象实现
上手难度	极简 API 设计，几行代码启动	配置较复杂，学习曲线陡峭
离线运行	支持完全离线本地推理	通常需要在线 API 连接

搭建部署教程

从安装到运行，四步完成 Hermes Agent 的完整部署。

步骤 01

安装依赖

使用 pip 安装 Hermes Agent 核心包。建议使用虚拟环境隔离项目依赖。

terminalbash

# 创建并激活虚拟环境
python -m venv hermes-env
source hermes-env/bin/activate

# 安装 Hermes Agent（国内用户建议加速）
pip install hermes-agent -i https://pypi.tuna.tsinghua.edu.cn/simple

步骤 02

配置环境变量

设置 API 密钥和端点。支持 OpenAI 兼容格式的任意后端。

.envbash

# .env 文件配置
OPENAI_BASE_URL="https://api.your-provider.com/v1"
OPENAI_API_KEY="sk-your-api-key"

# 如使用本地 Ollama
# OPENAI_BASE_URL="http://localhost:11434/v1"
# OPENAI_API_KEY="ollama"

步骤 03

编写 Agent 脚本

几行 Python 代码即可启动一个具备工具调用能力的智能体。

main.pypython

from hermes_agent import Agent

agent = Agent(
    model="hermes-3",
    tools=["web_search", "calculator", "file_reader"],
)

response = agent.run("帮我搜索最新的 AI Agent 论文并总结")
print(response)

步骤 04

运行与调试

执行脚本，Agent 将自动规划任务、调用工具并返回结果。

terminalbash

# 运行 Agent
python main.py

# 启用详细日志模式
HERMES_LOG_LEVEL=debug python main.py

大陆网络环境使用指南

针对 API 连通性、依赖下载限速及 Docker 镜像获取困难等痛点，提供极简配置方案。

核心突破：API 端点与 Base URL 代理配置

Hermes Agent 默认调用外部 LLM API 进行推理。若使用 OpenAI 兼容格式或外部 API（如 OpenRouter、Together AI），需修改全局 Base URL。

使用国内 API 中转服务（如自建代理或第三方转发服务）
在 .env 文件中强制覆盖默认请求地址
代码级别可通过 base_url 参数显式传入

bash

# 环境变量配置法（推荐）
# 在 .env 文件或终端中设置

export OPENAI_BASE_URL="https://your-proxy-domain.com/v1"
export OPENAI_API_KEY="sk-your-proxy-key"

# 代码级修改法
from openai import OpenAI

client = OpenAI(
    base_url="https://your-proxy-domain.com/v1",
    api_key="sk-your-proxy-key"
)

本地化推理：Ollama / vLLM 零网络延迟方案

对数据隐私要求高或希望完全避开网络限制的开发者，推荐使用本地算力运行 Hermes 3 模型，实现毫秒级工具调用。

使用 Ollama 一键拉取 Hermes 模型
将 Agent 后端指向 localhost:11434/v1
彻底解决跨国网络延迟问题

bash

# 第一步：部署本地模型
# 需提前安装 Ollama (https://ollama.ai)
ollama run hermes3

# 第二步：对接 Agent（修改 .env）
OPENAI_BASE_URL="http://localhost:11434/v1"
OPENAI_API_KEY="ollama"

# 验证本地服务是否正常
curl http://localhost:11434/v1/models

环境与依赖加速（Docker / Python）

在构建运行环境时，务必切换为国内镜像源，避免 Timeout 报错。

pip 切换为阿里云或清华镜像源
Docker Hub 配置国内加速器
Alpine Linux 替换为 USTC 镜像

bash

# Python pip 极速配置
pip config set global.index-url \
  https://mirrors.aliyun.com/pypi/simple/

# 或临时指定镜像源
pip install hermes-agent \
  -i https://pypi.tuna.tsinghua.edu.cn/simple

# Docker daemon.json 加速器配置
# 编辑 /etc/docker/daemon.json
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com"
  ]
}

Docker Compose 一键部署

针对大陆网络环境优化的 Docker 配置，解决容器访问宿主机本地模型的问题。

预配置 API 中转地址与时区
支持切换本地 Ollama 后端
host.docker.internal 桥接宿主机网络

yaml

version: '3.8'

services:
  hermes-agent:
    image: nousresearch/hermes-agent:latest
    container_name: hermes_agent_service
    restart: always
    environment:
      # 指向国内可访问的 API 中转地址
      - OPENAI_BASE_URL=https://api.your-proxy.com/v1
      - OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
      # 若使用本地 Ollama，取消下方注释
      # - OPENAI_BASE_URL=http://host.docker.internal:11434/v1
      - LANG=C.UTF-8
      - TZ=Asia/Shanghai
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
      - hermes_network

networks:
  hermes_network:
    driver: bridge

文档与代码示例

极简代码，快速通过国内网络发起你的第一次 Agent 对话。

example.pypython

"""
Hermes Agent - 国内网络首次对话示例 (Python)
通过配置 base_url 使用国内 API 代理
"""
from openai import OpenAI

# 初始化客户端 - 指向国内可用的代理端点
client = OpenAI(
    base_url="https://your-proxy-domain.com/v1",
    api_key="sk-your-proxy-key",
)

# 定义工具（Function Calling）
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的天气信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称，如：北京"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

# 发起 Agent 对话
response = client.chat.completions.create(
    model="NousResearch/hermes-3-llama3.1-8b",
    messages=[
        {"role": "system", "content": "你是一个有用的 AI 助手。"},
        {"role": "user", "content": "北京今天天气怎么样？"}
    ],
    tools=tools,
    tool_choice="auto",
)

print(response.choices[0].message)

提示：将 your-proxy-domain.com 替换为你的国内 API 代理地址。若使用本地 Ollama，将 base_url 改为 http://localhost:11434/v1。

准备就绪

准备好开启智能体之旅了吗？

查阅官方文档获取最新 API 参考、高级用法和社区最佳实践。

查看官方文档 GitHub 仓库

常见问题解答

针对中国大陆开发者最关心的部署、网络和兼容性问题。

Hermes Agent中文指南

什么是 Hermes Agent

工具调用 (Function Calling)

JSON 结构化输出

多步推理与规划

灵活的模型后端

Hermes Agent vs OpenClaw 对比

搭建部署教程

安装依赖

配置环境变量

编写 Agent 脚本

运行与调试

大陆网络环境使用指南

核心突破：API 端点与 Base URL 代理配置

本地化推理：Ollama / vLLM 零网络延迟方案

环境与依赖加速（Docker / Python）

Docker Compose 一键部署

文档与代码示例

准备好开启智能体之旅了吗？

常见问题解答

Hermes Agent 在中国大陆可以直接调用官方推荐的 API 吗？

为什么在大陆服务器上 pip install Hermes Agent 依赖会频繁失败？

Hermes Agent 支持接入国内的大语言模型（如 DeepSeek、Qwen）吗？

推荐的本地化模型量化版本是什么？

Docker 容器内的 Agent 如何访问宿主机上的 Ollama 服务？

Hermes Agent 与 LangChain、AutoGPT 有什么本质区别？

如何在国内环境下拉取 Hermes Agent 的 Docker 镜像？

Hermes Agent
中文指南