文章目录
- 从仓库源码来看，“不支持”更像是不保证原生 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：ptyprocessWindows：pywinpty
- 本地 terminal 执行依赖 bash：tools/environments/local.py 在 Windows 下会寻找 Gitfor 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 环境
- 新版本 Hermes 的模型/provider/base_url 的单一真相来源是 config.yaml。像 LLM_MODEL 这类旧式环境变量不再作为主模型来源（容易出现“我以为切了，其实还在用 OpenRouter”的现象）。
- python -m hermes_cli.main model在向导中选择 Custom endpoint，填入 base_url、api_key、model。
- 将 model 配置成 dict 形式，例如（按你的模型填写）： model: default: qwen3.5-35b-a3b provider: custom base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: <你的key>
- 仓库里的 hermes web（hermes_cli/web_server.py）更像配置/会话/日志管理面板，并不提供聊天接口。
- 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（更适合事件流与长任务）
- 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
- 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
- 当 Hermes 触发危险命令检测时，希望 Web 前端能弹窗让用户选择： allow once allow session allow always deny
- 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 弹窗审批，需要做一小段后端扩展
- 原因：/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.requestdata: { run_id, command, description, pattern_keys }（可选）event: hermes.approval.resolveddata: { 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 继续执行
- 强制 API_SERVER_KEY（浏览器请求必须带 Authorization: Bearer …）CORS 只允许 localhost：API_SERVER_CORS_ORIGINS 严格白名单不要把 key 直接写死在前端（本地验证可以；生产建议加本机反向代理注入 Authorization）
目录
- 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. 总结
Hermes-Agent 的官方安装说明写得很明确——原生 Windows 不支持，Windows 唯一受支持方式是 WSL2。但我就是 Windows 环境，让我来研究下如何在 Windows部署Hermes-Agent，并且可用。
于是我决定不盲装，先从源码入手：看它到底在哪些地方依赖 POSIX/TTY/PTY，哪些地方已经做了 Windows 防护，再按“最短闭环”顺序逐步把能力跑通：先 chat，后 UI，再工具。
从仓库源码来看，“不支持”更像是不保证原生 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
- 本地 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 环境
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 环境
你当前是 Windows + conda Python 3.11，下面按“最短可用路径”给步骤。
conda activate <你的环境名>
python --version
在仓库根目录执行：
cd D:githubaihermes-agent python -m pip install -U pip python -m pip install -e ".[cli,pty]"
- TUI：hermes –tui 需要 Node + ui-tui/node_modules
- Web Dashboard（web/）：开发模式需要 Node；生产构建输出到 hermes_cli/web_dist/
TUI 依赖安装：
cd ui-tui npm install cd ..
新版本 Hermes 的模型/provider/base_url 的单一真相来源是 config.yaml。
像 LLM_MODEL 这类旧式环境变量不再作为主模型来源（容易出现“我以为切了，其实还在用 OpenRouter”的现象）。
python -m hermes_cli.main model
在向导中选择 Custom endpoint，填入 base_url、api_key、model。
将 model 配置成 dict 形式，例如（按你的模型填写）：
model: default: qwen3.5-35b-a3b provider: custom base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: <你的key>
交互式：
python -m hermes_cli.main 一问一答快速验证： python -m hermes_cli.main chat -q "用一句话确认你是谁，以及你当前的模型名"
确保已装 Node + ui-tui 依赖后：
python -m hermes_cli.main --tui --tui-dev
常见提示：
hermes-tui: no TTY：说明你在非 TTY 环境启动（如某些 IDE Run 面板），请用 Windows Terminal/PowerShell 真终端运行
仓库里的 hermes web（hermes_cli/web_server.py）更像配置/会话/日志管理面板，并不提供聊天接口。
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（更适合事件流与长任务）
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
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
当 Hermes 触发危险命令检测时，希望 Web 前端能弹窗让用户选择：
allow once allow session allow always deny
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 弹窗审批，需要做一小段后端扩展
原因：/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 继续执行
强制 API_SERVER_KEY（浏览器请求必须带 Authorization: Bearer …）
CORS 只允许 localhost：API_SERVER_CORS_ORIGINS 严格白名单
不要把 key 直接写死在前端（本地验证可以；生产建议加本机反向代理注入 Authorization）
- 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 事件流来做交互。
都适用。
Server。
/v1/runs 的 SSE 事件流来做交互。
到此这篇关于Windows上部署Hermes-Agent的实现步骤的文章就介绍到这了,更多相关Hermes-Agent部署内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！