Hermes Agent本地部署教程：从环境准备到定时推送实战-二趣网

关注 Agent 方向有一段时间了，最明显的感受是：开源项目更新太快，教程很难跟得上。尤其是在 Hermes Agent 这个项目上，社区讨论不少，但多数资料要么只有概念介绍，要么直接跳到代码，中间缺了环境准备、模型接入和部署这一步。本文按照真实上手顺序，把 Hermes Agent 从安装到部署的完整流程整理成一份图文教程，后续再配合视频课程逐集跟练，会轻松很多。

整篇文章不会假设你已经本地部署过大模型。你会看到每一步的命令、参数解释、常见报错和配置建议。如果跟着文章把环境搭起来，跑通一个最简单的 Agent 对话，再配置一个“定时生成日报 + 钉钉推送”的小例子，后面继续深入 Agent 开发时，就不会再被部署细节绊住。

1. 先弄清楚：Hermes Agent 到底是什么？

1.1 从 Hermes 系列模型说起

Nous Research 是一个以开源语言模型研究为主的团队，Hermes 系列就是它比较有代表性的开源模型系列。在社区里，Hermes 系列通常以“指令遵循能力强、适合做 Agent 底座”著称。名字里带 Agent 的 Hermes Agent，简单理解就是围绕这套模型生态构建的智能体框架：它负责把大模型和工具连接起来，让模型不再只是聊天回答问题，而是能够完成一系列需要调用外部能力的任务。

这样说可能还是有点抽象。我们可以把一个 Agent 框架拆成三个部分：

模型层：负责理解用户目标、生成计划和回复，比如本地部署的 Qwen、Llama、Hermes 系列模型。
工具层：负责执行具体动作，比如网页搜索、执行 Python 脚本、请求外部 API、读取文件、发送通知。
编排层：负责管理“模型 → 工具 → 观察结果 → 再决策”的循环，这就是 Agent 的核心逻辑。

Hermes Agent 所承担的正是编排层和工具层的工作。它并不要求你只能使用 Hermes 系列模型，只要模型服务能通过 OpenAI 兼容接口提供服务，就可以接入。

1.2 Agent 和聊天助手的区别

如果你用过 ChatGPT、Kimi、文心一言这类产品，你会发现它们的典型交互方式是“你问一句，它答一句”。用户提出问题，模型直接生成回答，没有中间环节。

而 Agent 的交互方式不同。它会把一个任务拆成多步执行：

用户提出一个目标，例如“帮我查一下明天北京天气，然后写一份出行建议”。
Agent 决定调用天气查询工具。
工具返回天气数据。
Agent 根据数据生成出行建议的文本。
如果需要发送到手机，Agent 再调用消息通知工具，把结果推给用户。

也就是说，Agent 不再只是“生成文字”，而是变成“执行任务的系统”。这也是 2025 年以来各类 Agent 产品集中爆发的核心原因：大模型本身不会操作你的电脑、不会访问外部系统，但借助 Agent 框架，模型可以驱动工具去完成真实操作。

1.3 为什么值得在本地跑一个 Agent

我总结了几个比较典型的理由。

第一是数据可控。如果你处理的是一些敏感信息，比如公司内部文档、个人笔记、财务报表，把数据发到云端 API 不一定合适。使用 Hermes Agent 搭配本地模型，可以做到数据不出内网。

第二是成本可控。本地模型虽然需要硬件资源，但调用次数多了以后，总成本通常低于频繁调用云端大模型 API，尤其是需要高频跑定时任务或批量处理数据的场景。

第三是便于二次开发。开源 Agent 框架允许你修改工具列表、修改 Prompt、增加新的通知通道，而不是被 SaaS 产品限制在固定功能里。

所以，Hermes Agent 适合的人群也比较明确：希望自己掌控 Agent 全流程的开发者、需要做自动化的运维和后端工程师、以及正在学习 LangChain、大模型应用开发的初学者。

2. 零基础环境准备：先把主机环境打好

网上很多教程一上来就让你克隆仓库、跑命令，结果第一步就卡在 Python 版本不对、Git 没安装、依赖装不上。这一节先把基础环境补上。

2.1 Python 环境安装与验证

Hermes Agent 是 Python 项目，所以 Python 环境是必须的。建议使用当前主流版本，例如 3.10、3.11 或 3.12。太老的 3.8、3.9 部分新依赖可能不再支持，太新的版本如果依赖没有适配也可能出现编译问题，具体以项目 README 声明为准。

安装完成后，在终端验证：

python --version

如果你的 Windows 系统安装了多个 Python 版本，也可以试试：

py --version

如果你还没有安装 Python，建议下载官方安装包时勾选“Add Python to PATH”选项。这个选项很关键，否则后续在命令行里输入 python 会提示找不到命令。

2.2 Git 安装与配置

Git 用来克隆 Hermes Agent 仓库，也是后续自行改动代码、更新版本时必备的工具。安装完成后验证：

git --version

建议顺手配置一下用户信息，方便以后提交自己的改动：

git config --global user.name "YourName" git config --global user.email "you@example.com"

这里你可能会问：我只是用别人的开源项目，也需要提交代码吗？其实不一定。但 Git 的价值不只是提交代码，你还可以用git pull合并官方仓库的最新改动，用git diff查看修改了哪些文件。这些在跟进 2026 年社区最新版本时非常有用。

2.3 Windows 用户建议先启用 WSL 2

如果你使用 Windows，我会优先建议启用 WSL 2。原因有三个：

Hermes Agent 很多依赖编译和运行说明默认针对 Linux 环境，WSL 2 能减少环境差异；
后续如果需要用 Docker 部署，WSL 2 是 Windows 上 Docker Desktop 的推荐后端；
Linux 下的 shell 命令、权限模型和运行日志，和 Windows CMD 体验差别较大，统一在 WSL 里操作有助于减少踩坑。

在管理员权限的 PowerShell 里执行：

wsl --install

安装完成后按提示重启电脑，再从 Microsoft Store 安装一个 Ubuntu 发行版即可。

2.4 本地模型服务：Ollama 或 LM Studio

Hermes Agent 本身不直接运行模型权重，而是调用一个“模型服务”。最常用的本地模型服务就是 Ollama，其次是 LM Studio。

Ollama 的优势是命令行简单，安装方便，社区模型丰富。安装完成后，先启动服务：

ollama serve

再拉取一个模型，例如：

ollama pull qwen2.5:7b

如果你机器没有独立显卡，也可以先拉一个更小的模型测试链路，比如qwen2.5:3b或llama3.2:3b。先把流程跑通，再考虑换更大的模型。

3. 获取 Hermes Agent 源码并安装依赖

3.1 拉取官方仓库

Hermes Agent 的官方仓库在 GitHub 上，项目地址是NousResearch/Hermes-Agent。克隆仓库：

git clone https://github.com/NousResearch/Hermes-Agent.git cd Hermes-Agent

这里要强调一点：网络上会出现一些“中文官网”“汉化版”之类的站点，务必谨慎对待。开源项目的正确获取方式是官方 GitHub 仓库，不要从不明来源下载压缩包或者脚本，避免被植入恶意代码。

3.2 创建虚拟环境

Python 项目强烈建议使用虚拟环境。虚拟环境可以把项目的依赖和系统全局环境隔离开，避免不同项目之间因为依赖版本冲突而互相污染。

在项目目录下执行：

python -m venv .venv

创建成功后激活虚拟环境。Linux 或 macOS 使用：

source .venv/bin/activate

Windows CMD 使用：

.venv\Scripts\activate.bat

Windows PowerShell 使用：

.venv\Scripts\Activate.ps1

激活后，终端命令行前通常会显示(.venv)前缀。看到这个前缀，就说明当前已经在虚拟环境里了。

3.3 安装依赖

Hermes Agent 的依赖声明一般位于requirements.txt中。安装命令：

pip install --upgrade pip pip install -r requirements.txt

如果下载速度不理想，可以使用国内镜像源，例如清华 PyPI 镜像：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，可以检查关键依赖是否正常：

pip list | findstr openai

不同版本对依赖的管理方式可能不同，有些版本使用pyproject.toml或setup.py，如果 README 建议以可编辑模式安装，可以执行：

pip install -e .

这样可以方便后续直接导入项目中的模块进行二次开发。

3.4 初始化配置文件

Hermes Agent 需要配置文件来指定模型地址、API Key、工具开关等信息。仓库一般会提供一个示例文件，例如.env.example。

我们可以复制一份作为自己的配置：

cp .env.example .env

如果仓库里没有.env.example，就直接创建.env文件，具体变量名以 README 的配置说明为准。

打开.env，会看到一个个 KEY=VALUE 形式的配置项。这里要注意一个原则：.env文件通常包含密钥，不要提交到 Git，也不要截图发到群里。

4. 配置模型接入

配置模型接入是整个部署过程中最重要的一步。很多人跑不起来 Agent，并不是项目本身有问题，而是模型服务地址、模型名、API Key 这三项没有对齐。

4.1 使用本地 Ollama 模型

如果你使用 Ollama，Hermes Agent 需要访问 Ollama 的 OpenAI 兼容接口。Ollama 默认监听本地11434端口，OpenAI 兼容路径是/v1。

所以在.env里可以这样配置：

# 以下变量名是常见示例，请以你仓库的 .env.example 为准 BASE_URL=http://127.0.0.1:11434/v1 API_KEY=not-needed MODEL=qwen2.5:7b

本地模型服务通常不需要真实 Key，但要注意两点：

地址必须写/v1，不能漏掉；
MODEL必须和 Ollama 里实际拉取的模型名称完全一致，包括标签，例如qwen2.5:7b不能写成qwen2.5。

4.2 使用云端 OpenAI 兼容 API

如果本机显存不足，也可以使用云端模型服务。目前国内很多服务商都提供 OpenAI 兼容接口，比如 DeepSeek、通义、月之暗面等。如果你的模型服务商暂时没有提供 OpenAI 兼容接口，也可以借助 One API 这类开源网关做转换。

配置示例：

BASE_URL=https://api.deepseek.com/v1 API_KEY=sk-你的真实密钥 MODEL=deepseek-chat

使用云端 API 时，密钥就非常重要了。不要把密钥提交到公开仓库。如果怀疑密钥泄露，第一时间到服务商后台重置。

4.3 验证模型服务是否可用

在启动 Hermes Agent 之前，我建议先用一个最小的 Python 脚本验证模型服务是否正常。这样可以快速把问题定位在“模型服务”还是“Agent 框架”。

创建一个test_model.py：

from openai import OpenAI client = OpenAI( base_url="http://127.0.0.1:11434/v1", api_key="not-needed", ) resp = client.chat.completions.create( model="qwen2.5:7b", messages=[ {"role": "user", "content": "你好，请用一句话介绍你自己"} ] ) print(resp.choices[0].message.content)

运行：

python test_model.py

如果返回了一段正常的模型自我介绍，说明模型服务没有问题。如果报Connection error，说明 Agent 和模型服务之间的链路还没有打通，先不要急着调试后面的代码。

5. 首次运行 Hermes Agent

5.1 启动 Agent

模型服务验证通过后，就可以启动 Hermes Agent 了。不同版本入口可能不同，常见入口包括main.py、run_agent.py，或安装后提供的hermes命令。以仓库 README 为准。

例如：

python main.py

启动成功后，你通常会看到一个命令行交互界面，输入问题后 Agent 会先思考，再决定是否调用工具，最后返回结果。

第一次运行时，建议先问一个不需要工具的问题，比如：

你好，请介绍一下你自己。

这样只是验证 Agent 的基础对话链路。链路通畅后再尝试工具调用。

5.2 让 Agent 调用工具

Hermes Agent 的插件系统中一般内置了几类常用工具：

工具类型	作用	典型场景
终端工具	执行 Shell 命令	查看系统状态、调用脚本
文件工具	读写本地文件	保存日志、读取配置
网络请求工具	请求外部 API	查天气、查快递、调接口
定时任务工具	按 Cron 表达式执行任务	定时生成报告
通知工具	发送消息到聊天软件	钉钉推送、飞书通知

你可以试着问：

请查看当前目录下有哪些文件，并列出文件名。

Agent 如果具备终端工具调用能力，会先生成一个计划，然后执行类似ls -la的命令，再把输出结果整理给你。整个过程和直接运行命令不一样：Agent 会尝试理解你的意图，检查命令输出，最后生成一段自然语言总结。

5.3 预期输出说明

不要期待第一次运行就非常完美。Agent 工具调用过程中可能会出现以下情况：

Agent 生成了工具调用，但没有执行成功；
工具返回了报错，Agent 根据自己的理解重新尝试；
多轮工具调用后上下文过长，导致回复中断。

这些都是正常现象。关键是先观察日志输出，确定问题出在哪一层。Hermes Agent 通常会打印模型调用信息、工具执行信息和错误栈，初学者可以先把日志级别调低，把过程看清楚。

6. 定时任务与钉钉通知实战

6.1 钉钉机器人创建与加签

定时任务和钉钉通知是 Hermes Agent 比较有代表性的实战场景。假设你想让 Agent 每天早上 9 点生成一份工作安排，然后推送到钉钉群。你需要先创建一个钉钉群机器人。

在钉钉群里打开“群设置 → 智能群助手 → 添加机器人”，选择自定义机器人。安全设置建议选择“加签”。加签后你会得到一个 Secret 值，同时得到 Webhook 地址。

Webhook 地址大致如下，其中access_token是群机器人的唯一标识：

https://oapi.dingtalk.com/robot/send?access_token=你的token

使用加签安全设置时，请求需要额外带上timestamp和sign参数。

6.2 编写钉钉加签代码

下面给出一段可直接运行的 Python 示例，用于计算签名并发送文本消息：

import base64 import hashlib import hmac import time import urllib.parse import requests def build_signed_url(access_token: str, secret: str) -> str: timestamp = str(round(time.time() * 1000)) string_to_sign = f"{timestamp}\n{secret}" hmac_code = hmac.new( secret.encode("utf-8"), string_to_sign.encode("utf-8"), digestmod=hashlib.sha256, ).digest() sign = urllib.parse.quote_plus(base64.b64encode(hmac_code)) return ( f"https://oapi.dingtalk.com/robot/send?access_token={access_token}" f"&timestamp={timestamp}&sign={sign}" ) def send_text(access_token: str, secret: str, content: str): url = build_signed_url(access_token, secret) payload = { "msgtype": "text", "text": {"content": content}, } resp = requests.post(url, json=payload) print(resp.json())

调用方式：

send_text( access_token="你的access_token", secret="你的加签Secret", content="这是来自 Hermes Agent 的定时通知。", )

如果返回{"errcode":0,"errmsg":"ok"}，说明消息发送成功。如果返回93000之类的错误码，通常是签名计算不正确或者安全设置和请求方式不匹配。

6.3 配置定时任务

定时任务的配置方式因版本而异，但核心是 Cron 表达式。以常见的 YAML 配置为例：

schedule: - name: "morning-report" cron: "0 9 * * *" task: "生成今天的工作安排，输出一份简洁待办清单" notify: - channel: dingtalk access_token: "你的access_token" secret: "你的加签Secret"

Cron 表达式0 9 * * *表示每天上午 9 点执行一次。这里注意，定时任务依赖 Agent 进程保持运行，所以如果进程退出，定时任务就不会触发。

6.4 效果验证

配置完成后，建议把第一次执行时间设置成当前时间的下一分钟，快速验证链路是否通畅。

例如当前是 14:32，可以先改成：

cron: "33 14 * * *"

等收到钉钉推送后再改回正常的时间。不要第一次就等第二天，出现问题很难定位是配置不对还是时间没到。

7. Docker 部署与你关心的话题

7.1 为什么用 Docker

如果你的 Hermes Agent 需要长时间运行，或者要部署到服务器、公司内网，用 Docker 会是更稳定的选择。

Docker 可以把运行环境、依赖、配置封装成一个镜像，避免服务器上的 Python 环境冲突，也方便迁移。使用 Docker 还有个额外好处：不会污染宿主机环境，不需要运行apt install安装一堆依赖包。

7.2 Docker 启动示例

如果仓库提供了 Dockerfile，可以按下面的流程构建和运行：

docker build -t hermes-agent .

运行时把本地的.env挂载进去，同时映射必要的端口：

docker run -it --rm \ --env-file .env \ -v "$(pwd)/logs:/app/logs" \ hermes-agent

这里有一个很常见的坑：如果 Hermes Agent 运行在容器内，而模型服务安装在宿主机上，那么容器内的127.0.0.1指向的是容器自身，不是宿主机。

解决方法是使用host.docker.internal：

BASE_URL=http://host.docker.internal:11434/v1

在 Linux 上如果使用--network=host启动容器，也可以继续使用127.0.0.1。

7.3 部署后要花钱吗？

这个问题的答案取决于你选择的模型后端，而不是 Hermes Agent 本身。

Hermes Agent 源码是开源的，本身不收费；
如果使用本地 Ollama 模型，软件层面基本免费，主要成本是硬件功耗；
如果使用云端大模型 API，按 Token 计费，跑的任务越频繁、输出越长，费用越高；
如果用云服务器，还需要考虑服务器租赁费用和带宽费用。

所以更准确的说法是：本地部署时，项目本身不花钱，但算力资源和工具本身可能有成本。如果你的任务是高频定时跑批量任务，建议先用本地小模型把流程跑通，再评估是否需要升级硬件或使用云端 API。

8. 常见问题与排查

8.1 安装阶段常见报错

问题现象	常见原因	解决思路
`python`不是内部或外部命令	Python 未安装或未加入 PATH	重新安装 Python 并勾选 Add to PATH
`pip`无法安装依赖	源地址慢或依赖冲突	使用国内镜像源，重建虚拟环境，升级 pip
`ModuleNotFoundError: No module named 'xxx'`	依赖未安装完整，或虚拟环境未激活	检查`pip list`，确保激活了`.venv`
启动时报依赖版本错误	项目依赖与本地 Python 版本不兼容	对齐 README 要求的 Python 版本，重新安装

8.2 模型接入阶段常见报错

问题现象	常见原因	解决思路
`Connection refused`	Ollama 服务未启动，或端口不对	确认`ollama serve`已运行，检查端口
`model not found`	模型名拼写不一致	执行`ollama list`查看真实模型名和标签
`401 Unauthorized`	API Key 填错或没有权限	打开`.env`检查 Key，确认配额充足
请求超时	模型响应慢，或反向代理配置错误	降低模型规模，或调大超时时间，检查网络
Agent 一直重复调用同一个工具	模型能力较弱，或 Prompt 设计不合理	更换更强模型，或精简工具数量

8.3 Docker 与通知常见问题

问题现象	常见原因	解决思路
容器内连不上宿主机 Ollama	使用了`127.0.0.1`	改成`host.docker.internal`
Docker 启动失败	WSL 2 未启用或 Docker Desktop 未启动	打开 Docker Desktop，执行`docker info`
钉钉返回`93000`	加签算法错误，或安全设置不匹配	检查 Secret、时间戳和 sign 拼接逻辑
定时任务不触发	Agent 进程退出，或时区不对	保持进程运行，检查容器时区设置

8.4 关于“中文官网”的提醒

搜索 Hermes Agent 时，你可能会看到一些声称是“中文官网”“一键汉化版”的站点。这些站点不一定可信。

官方仓库只有一个：GitHub 上的NousResearch/Hermes-Agent。以后项目发布了新版本，也应该以官方 GitHub 的 Release 说明为准。如果你发现某个网站要求你注册、下载额外工具、付费解锁功能，请保持警惕。开源项目在本地部署本身不需要这些流程。

9. 最佳实践与工程建议

9.1 配置管理：密钥隔离与分层

把密钥和配置集中放在.env文件里，并确保它被.gitignore忽略。不要直接把密钥写死在代码里。

线上部署时，建议通过环境变量或密钥管理服务注入敏感信息。至少要做到“开发环境用开发 Key，生产环境用生产 Key”，避免一个 Key 到处用。

9.2 日志与观测

Agent 的运行过程包含多步模型调用和工具调用，一旦出错，如果不看日志，排查会非常痛苦。

建议做到以下几点：

开启详细日志并持久化到文件，不要只输出到终端；
记录每次模型请求的耗时和 Token 消耗；
记录工具调用的输入、输出和错误信息；
给定时任务增加一个“任务生成 + 发送结果”的双层日志，方便确认是生成失败还是推送失败。

9.3 安全边界

Agent 拥有终端工具时，就像给大模型开放了一个“执行命令”的门。如果 Prompt 被恶意注入，模型有可能会执行危险命令。

建议至少做三件事：

在非受信环境里，不要让 Agent 自动执行高权限命令；
给 Agent 配置独立的运行账号，使用最小权限；
对终端工具的允许命令做白名单，至少做好记录审计。

企业内使用时，更要评估数据流向。如果是私有化部署，确保所有请求都只走内网模型服务，不经过外部 API。

9.4 依赖与版本管理

Hermes Agent 这类项目迭代速度很快，依赖版本频繁变化。我的建议是：

在虚拟环境或容器中固定依赖版本；
记录当前项目能正常运行的requirements.txt或 lock 文件；
更新前先看官方 Release Notes，不要在业务中途贸然升级；
重要改动前用 Git 打 tag 或分支备份。

你要的不是“有没有最新版”，而是“当前项目的依赖是否可复现”。一个上周还能跑的项目，这周因为依赖升级挂掉，是很常见的事。

9.5 先小后大的调优策略

初次部署时，建议先用最小模型跑通全流程，再逐步换大模型；先跑单次对话，再配置工具调用；先配置简单通知，再增加定时任务。

这样做有两个好处：

模型越小，推理速度越快，链路问题更容易暴露；
每增加一个环节只引入一个变量，出了问题更容易定位。

10. 学习路线与最后建议

10.1 不要跳过的三步

很多初学者会在环境准备阶段着急，直接跳到代码运行。这里想强调三个不要跳过的步骤：

验证 Python、Git、Ollama 是否安装成功；
用最小 Python 脚本验证模型服务是否可访问；
先跑一个不调用工具的对话，确认 Agent 基础链路正常。

这三步做扎实了，后续的工具配置、定时任务、Docker 部署都会顺畅很多。

10.2 建议的学习顺序

如果你正在跟着 B 站的 68 集系列视频学习，可以参考下面的配套顺序：

先看 2 到 3 集，了解 Agent 的基本概念；
动手完成本地环境搭建，包括 Python、Git、Ollama；
克隆 Hermes Agent，跑通最简单的对话；
接入本地模型，完成一次真实的工具调用；
配置定时任务和钉钉通知；
用 Docker 把服务部署到服务器；
再深入学习 Prompt 设计、工具扩展和多 Agent 协作。

不要急着在第一天就部署到生产环境。Agent 应用的难点从来不是“能不能跑”，而是“能不能稳定跑”。

10.3 最后的建议

开源 Agent 框架发展很快，今天看到的安装方式、配置字段，可能下个月就会有变化。所以比起死记硬背命令，更重要的是懂得排查思路：先确认模型服务通不通，再确认配置对不对，最后看代码逻辑和日志输出。

这也是我写这篇文章的初衷：不只是把命令贴出来，而是把每一步背后的原理讲清楚。当你遇到问题、搜索资料、阅读官方文档时，能知道问题大概出在哪一层，就已经比很多只会复制粘贴的教程使用者前进了一大步。

如果你正在本地部署 Hermes Agent，建议现在就去检查一下环境，把自己的 Python 版本、Git 版本、Ollama 模型列表确认好，然后按文章顺序跑一遍。等 Agent 成功回你第一句话、并把第一条钉钉通知推到手机上的时候，你会觉得前面这些安装配置都值得。

企业官网建设流程全解析