多终端后端让 Hermes 可以无缝融入现有基础设施

你需要什么

• 已安装的 Hermes Agent（支持 Linux、macOS 或 Windows；Windows 可直接通过 PowerShell 安装脚本运行，无需 WSL2）
• 至少一个 LLM Provider 的 API Key（如 Nous Portal、OpenAI、Anthropic 或自定义兼容接口）
• 会用到的基础工具：终端（bash/zsh/PowerShell）、Python 3.10+ 环境，可选 Docker
• 预计阅读 + 实操时间：25 分钟

最终成果
本章结束时，你将掌握三种让 Agent“活”起来的方式：

1. 在命令行中使用交互式会话或单次查询，随时调用 Agent；
2. 通过 Gateway 将 Agent 暴露为统一的 HTTP API，对接 Telegram、Discord 或自研前端；
3. 在自己的 Python 应用中以库的形式嵌入 Agent，自定义工具和回调。

这三种后端模式共享同一套推理与工具调度逻辑，无论你的基础设施是纯终端、微服务还是已有 Python 服务，你都能把 Hermes 无缝插进去。

CLI 模式：交互式会话与脚本调用

Hermes CLI 并非简单的命令行封装，而是一套完整的终端用户界面（TUI）。它提供了多行编辑、斜杠命令自动补全、实时状态栏和丰富的快捷键，让开发者能在终端内完成从聊天到配置的全部操作。

第一步：进入交互式会话

打开终端，直接执行：

hermes

预期结果：出现欢迎横幅，显示当前使用的模型、工具集、工作目录等信息，终端底部出现状态栏，可以开始输入对话。

如果这是你第一次运行，Hermes 会引导你完成初始化配置（选择 Provider、输入 API Key、选择模型等）。你也可以随时通过 hermes setup 重新运行配置向导。

第二步：尝试单次查询

在自动化脚本或 CI 流水线中，你可能只需要让 Agent 回答一个问题就退出。这时使用非交互模式：

hermes chat -q "列出当前目录下最近修改的 3 个文件"

预期结果：Agent 调用执行命令的工具（默认已开启），返回文件列表，然后进程结束。不会进入交互式界面。

注意：单次查询模式下，Hermes 只执行一轮对话。如果 Agent 判断需要多次工具调用，会像交互模式一样执行多步，完成后退出。对于需要多轮确认的复杂任务，建议使用交互模式。

第三步：管理和恢复会话

交互模式下，每次对话都会保存在本地会话历史中。退出后重新进入，可以恢复上次会话继续工作：

hermes --resume

结合 --max-turns 限制轮次，适合做实验：

hermes --resume --max-turns 30

你还可以查看历史会话列表并选择恢复某一特定会话：

hermes sessions          # 列出所有会话
hermes --session <id>   # 恢复指定会话

第四步：多个 Agent 并行工作（Git 工作树隔离）

Hermes 支持在独立的 Git 工作树中启动 Agent，这样多个 Agent 可以同时修改同一个仓库的不同分支而互不干扰：

hermes -w

每个工作树启动的 Agent 都拥有独立的工作目录，执行文件操作或代码修改时不会相互污染。测试多 Agent 协作场景时尤为实用。

踩坑经验：工作树功能依赖 Git。如果你在一个非 Git 仓库或未提交所有更改的目录下使用 -w，Hermes 会报错并拒绝启动。确保先做好 git init 和 git commit -a 再试。

CLI 常用参数速查

CLI 模式的精髓在于零上下文切换：你可以一边用 vim 写代码，一边在另一窗口让 Agent 为你查资料、执行命令，所有输出原生融入你的终端工作流。

Gateway 模式：将 Agent 暴露为 HTTP API

如果你想让其他服务、前端 Web 页面或即时通讯平台（Telegram、Discord、Slack 等）也能驱动同一个 Agent，就需要启动 Gateway。

第一步：启动 Gateway 服务

hermes gateway

首先会进入交互式配置（首次启动时），你需要设置：

• 监听端口（默认 8543）
• 是否需要 TLS（可自签名证书或 Let’s Encrypt）
• 鉴权方式：API Key 或 JWT Token
• 允许接入的消息平台（Telegram bot token、Discord bot 等可在此配置）

配置完成后，Gateway 会在后台启动一个 Web 服务，同时可选自动注册 Webhook 到指定平台。

注意：hermes gateway 启动后会持续占用当前终端。生产环境通常配合 systemd 或 screen / tmux 保持后台运行。若使用 Docker，可以直接拉取官方镜像并映射端口。

第二步：通过 HTTP API 调用 Agent

Gateway 暴露标准的 REST API。假设你在本地 8543 端口启动了 Gateway，并且设置了 API Key 为 hk-abc123，发送请求示例：

curl -X POST http://localhost:8543/v1/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hk-abc123" \
  -d '{
    "message": "帮我总结今天的大盘走势",
    "stream": false
  }'

响应格式（简化）：

{
  "reply": "今日上证指数...",
  "turns_used": 3,
  "usage": {
    "input_tokens": 234,
    "output_tokens": 156
  }
}

如果设置了 "stream": true，则会通过 Server-Sent Events（SSE）流式返回生成内容，适合前端逐字展示。

第三步：接入 Telegram 或其他平台

在 Gateway 配置中启用了 Telegram bot token 后，Hermes 会自动在启动时设置 Webhook。此时通过 Telegram 给 Bot 发送消息，就能直接与 Agent 对话，行为与 CLI 模式完全一致。

这套架构意味着：一个 Agent 实例，多个前端。你不需要为每个客户端写重复的工具调用逻辑。

踩坑经验：Gateway 的 TLS 配置不可跳过自签名证书验证。如果仅用 HTTP 本机测试没问题，但对接 Telegram / Discord 等平台时，对方强制要求 HTTPS Webhook 地址。最简单的方案是使用 ngrok 或 cloudflared 临时开启公网 HTTPS 隧道进行测试。

Python 库嵌入：在现有应用中集成 Agent

如果你的项目是一个已有的 Python Web 服务、自动化脚本或数据处理管道，你可以直接 import hermes_agent（或具体包名）来实例化 Agent，无需启动额外服务。

第一步：导入并初始化 Agent

from hermes_agent import Agent, ToolRegistry

# 1. 初始化 Agent，指定模型
agent = Agent(
    provider="openai",
    model="gpt-4.1",                     # 或 anthropic/claude-sonnet-4 等
    api_key="sk-xxxxxx",                 # 也可以用环境变量
    base_url="http://localhost:11434/v1" # 如果是本地模型代理
)

初始化成功后，Agent 会加载默认工具集，但尚未启动对话循环。

第二步：运行一次对话并获取结果

response = agent.chat("帮我创建一个 python 虚拟环境并安装 requests 库")
print(response)

这会触发 Agent 的工具调用与推理循环，并返回最终文本回答。如果需要查看中间步骤，可以设置回调。

第三步：自定义工具与回调

嵌入模式下你常常需要注册自己的工具，比如查询内部数据库或调用公司 API：

from hermes_agent import tool

@tool(name="get_order_status")
def get_order_status(order_id: str) -> dict:
    """查询订单状态"""
    # 实际调用内部系统
    return {"status": "已发货", "tracking_id": "SF1234567890"}

agent.register_tool(get_order_status)

你也可以在每次工具调用前后插入钩子，记录日志或做权限控制：

agent.on_tool_call(lambda tool, args: print(f"[LOG] 调用工具 {tool}，参数：{args}"))

第四步：集成到 Web 服务（FastAPI 示例）

from fastapi import FastAPI
from hermes_agent import Agent

app = FastAPI()
agent = Agent(provider="anthropic", model="claude-sonnet-4")

@app.post("/ask")
async def ask(prompt: str):
    result = agent.chat(prompt)
    return {"reply": result}

这个例子直接复用了与 CLI / Gateway 完全相同的推理和调度逻辑，无需重写任何工具代码。你可以将它打包进现有的微服务体系，享受 Hermes 的全部能力。

踩坑经验：Python 嵌入模式下，Agent 默认会读取用户主目录下的全局配置文件（~/.hermes/config.yaml）。如果你想在代码中隔离配置，可以将配置字典传入 Agent(config_dict=...)，避免覆盖用户的个人设置。同时要注意 API Key 的安全性，建议从环境变量或密钥管理服务中读取，不要硬编码在代码中。

回顾

在这一章中，我们完成了 Hermes Agent 三种启动模式的实践：

1. CLI 模式：在终端里交互式对话、单次查询、恢复会话，以及用 Git 工作树隔离并行 Agent；
2. Gateway 模式：将 Agent 暴露为 HTTP API，并通过 Telegram 机器人等渠道接收消息；
3. Python 库嵌入：在自己的代码中直接实例化 Agent，注册自定义工具，并集成到 Web 应用中。

无论你的工作流是纯终端操作、需要多端分发，还是深度嵌入已有系统，Hermes 都提供了一条平滑的接入路径。你无需为不同的部署形态改变 Agent 本身的业务逻辑，因为 CLI、Gateway 和 Python 库这三个后端共享了完全相同的推理与工具调度层。

下一步行动清单

1. 根据自己的使用场景，选择一种模式启动 Hermes（首次建议从 CLI 开始体验）；
2. 测试至少一个单次查询（hermes chat -q "..."），观察到工具调用链；
3. 尝试 hermes model，体验如何在不修改代码的情况下切换到不同模型提供商；
4. 如果做过 Gateway 的测试，用 curl 发送一次消息并检查响应结构；
5. 最后，在 Python 环境中写一个迷你脚本，注册一个你自己的 @tool，让 Agent 调用它。

在接下来的章节《模型路由支持 15+ 平台网关却不需要复杂配置》中，我们将更深入地探讨论模型层：Hermes 如何在一套抽象下接入 OpenAI、Anthropic、本地模型等多种 Provider，以及模型路由怎样在不增加配置复杂度的前提下，让你的 Agent 动态选择最合适的“大脑”。