Windows上部署Hermes-Agent的实现步骤

2026-04-23 15:58:50 Yaphetshl

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:\github\ai\hermes-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=http://127.0.0.1:3000,http://localhost:3000
然后启动 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部署内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！