Windows上部署Hermes-Agent的实现方式步骤实用指南

作者：袖梨 2026-08-26

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Windows上部署Hermes-Agent的实现方法步骤”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

目录
  • 0.前言
  • 1. 源码分析
    • 1.1 官方“原生 Windows 不兼容”的真实含义
    • 1.2 Windows 上最核心的差异点（决定“体验是否稳定”）
  • 2.环境安装
    • 2.1 激活 conda 环境
    • 2.2 安装 Hermes（editable 安装，便于本地开发/调试）
    • 2.3 （可选）准备 Node（仅 TUI/Web 前端开发需）
  • 3. 模型设置
    • 3.1 关键认知：主模型以 config.yaml 为准
    • 3.2 设置方式 A（建议）：用向导写入设置
    • 3.3 设置方式 B：直接编辑 config.yaml
  • 4. 运行验证
    • 4.1 经典 CLI（最先验证 chat 链路）
    • 4.2 TUI（更快验证 UI 链路）
  • 5. 自定义 Web 前端
    • 5.1 不建议直接对接 hermes web 的原因
    • 5.2 建议后端：Gateway 的 API Server（OpenAI-compatible）
    • 5.3 启用 API Server（写入 HERMES_HOME/.env）
    • 5.4 最小纯前端示例（非流式）
  • 6. Web 前端如何处理“工具调用确认/危险命令审批”？
    • 6.1 你要的目标（B：弹窗审批 + SSE）
    • 6.2 当前实现现状（重要）
    • 6.3 建议架构：基于 /v1/runs 做审批交互（最适合事件流）
    • 6.4 安全建议（必须做）
  • 7. 总结

0.前言

落到代码里，Hermes-Agent 的官方安装说明写得很明确——原生 Windows 不兼容，Windows 唯一受兼容方式是 WSL2。但我就是 Windows 环境，让我来研究下如何在 Windows部署Hermes-Agent，同时且可用。

在这个场景下，于是我决定不盲装，先从源码入手：看它到底在哪些地方依赖 POSIX/TTY/PTY，哪些地方已经做了 Windows 防护，再按“最短闭环”顺序逐步把能力跑通：先 chat，后 UI，再工具。

1. 源码分析

1.1 官方“原生 Windows 不兼容”的真实含义

理解这一步时，从仓库源码来看，“不兼容”更像是不保证原生 Windows 上的终端/PTY/信号语义与体验稳定，而不是“完全不能跑”：

在这个场景下，仓库里有 Windows 安装脚本：scripts/install.ps1；scripts/install.cmd
在这个场景下，有 Windows 兼容性测试：tests/tools/test_windows_compat.py，用来确保 os.setsid/os.killpg 等 POSIX-only 行为不会被无条件调用
pyproject.toml 的可选依赖对 PTY 做了平台分流：
非 Windows：ptyprocess
Windows：pywinpty

1.2 Windows 上最核心的差异点（决定“体验是否稳定”）

  • 本地 terminal 执行依赖 bash：tools/environments/local.py 在 Windows 下会寻找 Git
    for Windows 的 bash.exe（Git Bash） 进程组/中断语义不同：后台进程、kill、Ctrl+C 等在
    落到代码里，Windows 与 POSIX 存在差异，源码里用 _IS_WINDOWS 分支做了兼容，但行为无法完全等价 TUI 是 Node + Ink（React）：ui-tui/ 前端由 Node 启动，Python 侧 tui_gateway 负责会话与工具；两者借助stdio JSON-RPC 通信，所以 hermes --tui 必须有 Node 环境

2.环境安装

结合项目来看，你当前是 Windows + conda Python 3.11，下面按“最短可用路径”给步骤。

2.1 激活 conda 环境

conda activate <你的环境名>
python --version

2.2 安装 Hermes（editable 安装，便于本地开发/调试）

在仓库根目录执行：

cd D:githubaihermes-agent
python -m pip install -U pip
python -m pip install -e ".[cli,pty]"

2.3 （可选）准备 Node（仅 TUI/Web 前端开发需）

  • TUI：hermes --tui 需 Node + ui-tui/node_modules
  • 在这个场景下，Web Dashboard（web/）：开发模式需 Node；生产构建输出到 hermes_cli/web_dist/

TUI 依赖安装：

cd ui-tui
npm install
cd ..

3. 模型设置

3.1 关键认知：主模型以 config.yaml 为准

从实现思路看，新版本 Hermes 的模型/provider/base_url 的单一真相来源是 config.yaml。
实际处理时，像 LLM_MODEL 这类旧式环境变量不再作为主模型来源（容易出现“我以为切了，其实还在用 OpenRouter”的现象）。

3.2 设置方式 A（建议）：用向导写入设置

python -m hermes_cli.main model
落到代码里，在向导中选择 Custom endpoint，填入 base_url、api_key、model。

3.3 设置方式 B：直接编辑 config.yaml

将 model 设置成 dict 形式，比如（按你的模型填写）：

model:
  default: qwen3.5-35b-a3b
  provider: custom
  base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
  api_key: <你的key>

4. 运行验证

4.1 经典 CLI（最先验证 chat 链路）

交互式：

python -m hermes_cli.main
一问一答快速验证：

python -m hermes_cli.main chat -q "用一句话确认你是谁，以及你当前的模型名"

4.2 TUI（更快验证 UI 链路）

确保已装 Node + ui-tui 依赖后：

python -m hermes_cli.main --tui --tui-dev

常用提示：

hermes-tui: no TTY：说明你在非 TTY 环境启动（如某些 IDE Run 面板），请用 Windows Terminal/PowerShell 真终端运行

5. 自定义 Web 前端

5.1 不建议直接对接 hermes web 的原因

在这个场景下，仓库里的 hermes web（hermes_cli/web_server.py）更像设置/会话/日志管理面板，同时不提供聊天接口。

5.2 建议后端：Gateway 的 API Server（OpenAI-compatible）

落到代码里，Hermes Gateway 提供 OpenAI-compatible API Server，适合任意自写前端（包括纯 HTML+CSS+JS）：

POST /v1/chat/completions
POST /v1/responses（支持更强的服务端状态）
POST /v1/runs + GET /v1/runs/{run_id}/events（更适合事件流与长任务）

5.3 启用 API Server（写入 HERMES_HOME/.env）

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
API_SERVER_PORT=8642
API_SERVER_HOST=127.0.0.1

浏览器直连必须开 CORS（只允许本机 origin）

API_SERVER_CORS_ORIGINS=（链接已移除）,（链接已移除）
然后启动 gateway：

python -m hermes_cli.main gateway

5.4 最小纯前端示例（非流式）

index.html：

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Hermes Minimal Web</title>
    <style>
      body { font-family: system-ui; max-width: 900px; margin: 24px auto; }
      textarea { width: 100%; height: 100px; }
      pre { white-space: pre-wrap; border: 1px solid #ddd; padding: 12px; }
    </style>
  </head>
  <body>
    <h3>Hermes Web (OpenAI-compatible API)</h3>
    <textarea id="inp" placeholder="输入..."></textarea>
    <button id="send">发送</button>
    <pre id="out"></pre>
    <script>
      const BASE = "http://127.0.0.1:8642/v1";
      const KEY  = "change-me-local-dev";
      const out  = document.getElementById("out");
      document.getElementById("send").onclick = async () => {
        out.textContent = "请求中...";
        const content = document.getElementById("inp").value;
        const r = await fetch(`${BASE}/chat/completions`, {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            "Authorization": `Bearer ${KEY}`,
          },
          body: JSON.stringify({
            model: "hermes-agent",
            stream: false,
            messages: [{ role: "user", content }],
          }),
        });
        const j = await r.json();
        out.textContent = j?.choices?.[0]?.message?.content ?? JSON.stringify(j, null, 2);
      };
    </script>
  </body>
</html>

启动本地静态服务（避免 file://）：

python -m http.server 3000

6. Web 前端如何处理“工具调用确认/危险命令审批”？

6.1 你要的目标（B：弹窗审批 + SSE）

从实现思路看，Hermes 触发危险命令检测时，希望 Web 前端能弹窗让用户选择：

allow once
allow session
allow always
deny

6.2 当前实现现状（重要）

API Server（gateway/platforms/api_server.py）的 SSE 里已经有 工具进度事件：event: hermes.tool.progress
在这个场景下，但“危险命令审批”系统在 Hermes 内部由 tools/approval.py 实现，它借助 register_gateway_notify()/resolve_gateway_approval() 在网关交互平台里完成“请求→响应”的闭环
在这个场景下，API Server 目前没有现成的 HTTP 回传通道把审批结果发回去，所以要做真正的 Web 弹窗审批，需做一小段后端扩展

6.3 建议架构：基于 /v1/runs 做审批交互（最适合事件流）

原因：/v1/runs/{run_id}/events 本身就是“结构化事件流”，天然适合“等待用户输入”的交互状态。

后端需补的最小能力（建议）
在 run 里注册审批回调
实际处理时，tools/approval.py 触发审批请求时，借助回调把请求转换为 SSE 事件发给前端
增加审批响应接口

比如：POST /v1/runs/{run_id}/approval

body: { “choice”: “once” | “session” | “always” | “deny” }

后端调用：resolve_gateway_approval(session_key, choice, resolve_all=False)
在 run 结束/断开时清理
结合项目来看，unregister_gateway_notify(session_key)，防止阻塞线程悬挂
建议定义的 SSE 事件
event: hermes.approval.request
data: { run_id, command, description, pattern_keys }
（可选）event: hermes.approval.resolved
data: { run_id, choice, resolved_count }
前端处理逻辑（最小状态机）
订阅 GET /v1/runs/{run_id}/events（SSE）
收到 hermes.tool.progress：展示“工具调用进度”
从实现思路看，收到 hermes.approval.request：弹窗展示 description + command，让用户点 once/session/always/deny
从实现思路看，点击后 fetch(POST /v1/runs/{run_id}/approval) 回传选择，后端解除阻塞，agent 继续执行

6.4 安全建议（必须做）

强制 API_SERVER_KEY（浏览器请求必须带 Authorization: Bearer ……）
CORS 只允许 localhost：API_SERVER_CORS_ORIGINS 严格白名单
实际处理时，不要把 key 直接写死在前端（本地验证能够；生产建议加本机反向代理注入 Authorization）

7. 总结

  • 落到代码里，Windows 上建议按顺序验证：chat → TUI/Web UI → tools，先闭环再追求完整能力。
  • 实际处理时，切模型要遵循新版本的“设置真相来源”：以 config.yaml 为准，建议用 python -m hermes_cli.main
  • 在这个场景下，model 配 custom endpoint，无论是 Ollama 还是 阿里百炼 DashScope compatible-mode
    都适用。
  • 理解这一步时，纯 HTML+CSS+JS 自建 Web 前端完全可行，建议对接 Gateway 的 OpenAI-compatible API
    Server。
  • 落到代码里，若要实现 Web 端的“危险命令审批弹窗”，需在 API Server 上补一小段审批事件 + 审批回传接口；最佳落地形态是基于
    /v1/runs 的 SSE 事件流来做交互。

理解这一步时，到此这篇关于Windows上部署Hermes-Agent的实现步骤的文章就介绍到这了,更多相关Hermes-Agent部署内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多兼容脚本之家！

相关文章

精彩推荐