OpenClaw × Hermes 部署指南

首页 / AI/技术
📊 SkyCetus 五行飞轮分析报告

📑 目录

  1. 前置条件
  2. macOS / Linux 前置条件
  3. 安装 Hermes
  4. 配置模型提供商
  5. macOS / Linux 安装
  6. Windows 适配修复
  7. 🔀 双通道冗余架构 (NEW)
  8. 部署 Agent Bridge
  9. 测试验证
  10. 踩坑大全（6 个已知陷阱）
  11. 进阶用法

架构总览


┌──────────────┐      JSON files      ┌─────────────────┐

│  Your Agent  │ ────────────────────→ │  lucas-to-       │

│  (OpenClaw)  │                       │  hermes/         │

│              │ ←──────────────────── │  hermes-to-      │

│              │      JSON files       │  lucas/          │

└──────────────┘                       └────────┬────────┘

                                                │ poll 30s

                                       ┌────────┴────────┐

                                       │  Hermes Worker   │

                                       │  (独立进程)       │

                                       │  无父进程超时      │

                                       └─────────────────┘

🔀 双通道冗余架构（CetusDuo v2.0）

生产环境推荐：ACP标准协议作为主路径（实时快速），File-as-API作为冗余路径（可靠持久）。两条通道互为备份，心跳检测自动切换。


┌──────────────┐                              ┌─────────────────┐

│  Your Agent  │ ═══ ACP 实时通道 (主路径) ══→ │  Hermes Agent   │

│  (OpenClaw)  │      延迟: ~100ms             │                 │

│              │      协议: JSON-RPC/SSE       │                 │

│              │ ←══ ACP 实时通道 ═════════════ │                 │

│              │                               │                 │

│              │ ─── File Bridge (冗余) ──────→ │  shared/        │

│              │      延迟: ~30s (轮询)         │  lucas-to-hermes│

│              │      持久化: 自带审计日志      │  hermes-to-lucas│

│              │ ←── File Bridge ────────────── │                 │

└──────┬───────┘                               └────────┬────────┘

       │                                                │

       └──────── 心跳检测 (30s) ─── 自动切换 ──────────┘

🟢 ACP通道（主路径）

  • ✅ 实时交互，延迟低（毫秒级）
  • ✅ 标准协议，跨Agent互通
  • ✅ bind模式保持上下文连续性
  • ✅ 适合：对话式协作、实时任务派发
  • 📖 参考：i龙虾 ACP教程

🔵 File Bridge（冗余路径）

  • ✅ 天然持久化，自带审计日志
  • ✅ ACP挂了自动切换，零数据丢失
  • ✅ 支持大payload（长文档、数据文件）
  • ✅ 适合：异步任务、大文件、断线恢复
  • 📖 本页下方有完整File Bridge部署教程

⚡ 自动切换逻辑

  1. 默认走ACP（快）
  2. 心跳检测ACP健康状态（每30秒）
  3. ACP超时/断连 → 自动降级到File Bridge
  4. ACP恢复 → 自动切回
  5. File Bridge的记录同时作为操作日志（双重保障）

💡 i龙虾文章只讲ACP，我们页面只讲File Bridge——双通道冗余方案是SkyCetus的差异化。

📋 前置条件

项目要求
操作系统Windows 10 / 11 / Server 2019+
Python3.10+（推荐 3.11）
Git已安装并在 PATH 中
OpenClaw已安装并运行
磁盘空间~500MB（Hermes + 依赖）

🍎 macOS / Linux 前置条件

项目要求
操作系统macOS 10.15+ 或 Linux (Ubuntu 20.04+)
Python3.10+（推荐 3.11）
Git已安装并在 PATH 中
OpenClaw已安装并运行
Homebrew (macOS)可选，用于安装依赖
 
# 验证 Python 版本

python3 --version    # 需要 3.10+



# macOS 可选：安装 Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"



# Linux (Ubuntu)

sudo apt update && sudo apt install python3 git
💡 macOS 自带 Python（通常 3.9.x），建议用 pyenv 安装 3.11+：
brew install pyenv && pyenv install 3.11 && pyenv global 3.11

⬇️ 安装 Hermes

1 克隆仓库

cd C:\

git clone https://github.com/hermes-ai/hermes-agent.git hermes-agent

cd hermes-agent
💡 GitHub 访问慢或不可用时，可用镜像：
git clone https://ghproxy.com/https://github.com/hermes-ai/hermes-agent.git hermes-agent
或 git clone https://gitclone.com/github.com/hermes-ai/hermes-agent.git hermes-agent

2 安装（editable 模式）

pip install -e .
⚠️ 必须用 -e .（editable 模式），Hermes 依赖项目目录结构。

3 验证

hermes --version

# 预期: Hermes Agent v0.10.0 或更新

⚙️ 配置模型提供商

配置文件：C:\Users\你的用户名\.hermes\config.toml

这是最容易踩坑的地方。provider 字段决定了 API 请求格式和端点路由。

方案 A：阿里云百炼（推荐国内）

[model]

provider = "alibaba"

model_id = "qwen3.5-plus"

api_key = "你的百炼API Key"



[model.base_url]

url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
⚠️ provider 必须是 "alibaba"，不能写 "openai"（会 fallback 到 OpenRouter）
⚠️ 模型名用 qwen3.5-plus，不是 qwen-plus（旧模型）
⚠️ 不要用第三方代理如 coding.aiapi.top（可能已失效）

方案 B：MiniMax

[model]

provider = "anthropic"

model_id = "MiniMax-M2.7"

api_key = "你的MiniMax API Key"



[model.base_url]

url = "https://api.minimaxi.com/anthropic/v1"
⚠️ 端点是 api.minimaxi.com（多一个 i）
⚠️ MiniMax 走 Anthropic 兼容格式，所以 provider = "anthropic"

方案 C：其他 OpenAI 兼容 API

[model]

provider = "auto"

model_id = "你的模型名"

api_key = "你的API Key"



[model.base_url]

url = "https://你的端点/v1"

验证配置

hermes chat -q "say hello" --yolo

🍎 macOS / Linux 安装 Hermes

macOS / Linux 无需 Windows 的 4 个修复步骤，直接安装即可：

1 克隆仓库

cd ~

git clone https://github.com/hermes-ai/hermes-agent.git hermes-agent

cd hermes-agent
💡 GitHub 访问慢或不可用时，可用镜像：
git clone https://ghproxy.com/https://github.com/hermes-ai/hermes-agent.git hermes-agent
或 git clone https://gitclone.com/github.com/hermes-ai/hermes-agent.git hermes-agent

2 创建虚拟环境（推荐）

# 使用 venv 创建隔离环境

python3 -m venv venv

source venv/bin/activate    # macOS/Linux

# Windows: venv\Scripts\activate

3 安装（editable 模式）

pip install -e .
⚠️ macOS/Linux 必须用 -e .（editable 模式），与 Windows 相同。

4 验证

hermes --version

# 预期: Hermes Agent v0.10.0 或更新

5 配置模型

配置文件：~/.hermes/config.toml（macOS/Linux 在用户目录下）

# macOS/Linux 配置示例（百炼）

[model]

provider = "alibaba"

model_id = "qwen3.5-plus"

api_key = "你的百炼API Key"



[model.base_url]

url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
💡 File-as-API Worker 启动（macOS/Linux）：
# 创建任务目录

mkdir -p ~/.hermes/hermes-agent/tasks/in ~/.hermes/hermes-agent/tasks/out



# 启动 Worker（后台运行）

cd ~/.hermes/hermes-agent

nohup python3 tasks/hermes_worker.py > /tmp/hermes_worker.log 2>&1 &



# 测试 Worker

python3 hermes_bridge.py "1+1等于几"
💡 hermes_bridge.py：完整源码见 hermes-worker 案例，或位于 ~/.hermes/hermes-agent/hermes_bridge.py

🔧 Windows 适配修复

Hermes 原生为 Linux 设计，Windows 上需要修复 4 个问题：

修复 1：terminal_tool 系统提示

文件：hermes\tools\terminal_tool.py

问题：硬编码 "Linux environment"，LLM 生成 python3、heredoc 等不兼容命令。

修复：将平台描述改为动态检测（platform.system()）。

修复 2：execute_code 工具

文件：hermes\tools\code_execution_tool.py

问题：sys.platform != "win32" 直接禁用 Windows。

修复：移除 Windows 检查，或改为 fallback 到 terminal_tool。

修复 3：local.py 路径分隔符

文件：hermes\tools\local.py

修复：将 ":" 替换为 os.pathsep（Windows 是 ";"），/tmp/ 替换为 os.environ.get('TEMP')。

修复 4：GBK 编码

# PowerShell 临时修复（每个窗口都要运行）

$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)



# 永久修复

[System.Environment]::SetEnvironmentVariable('PYTHONIOENCODING', 'utf-8', 'User')

🌉 部署 Agent Bridge

1 创建目录结构

mkdir D:\***\agent-bridge

mkdir D:\***\agent-bridge\lucas-to-hermes

mkdir D:\***\agent-bridge\hermes-to-lucas

mkdir D:\***\agent-bridge\status

mkdir D:\***\agent-bridge\logs
📝 可以把 D:\*** 换成你自己的工作目录，但后续所有路径都要一起改。

2 创建 bridge.py

协议层脚本，管理任务投递、结果收取、状态查询。完整代码见：

skycetus.cn/hermes-worker 或 D:\***\docs\hermes-windows-deployment-guide.md

核心 API：

  • python bridge.py send-task "任务描述" — 投递任务
  • python bridge.py check-inbox agent — 收取结果
  • python bridge.py status — 查看状态

3 创建 hermes_worker.py

核心守护进程。关键设计：

  • Write-Only Prompt：禁止 terminal_tool 和 execute_code，只允许 write_file
  • Python subprocess 直传：subprocess.run(['hermes', 'chat', '-q', prompt_text])，绕过 PowerShell
  • -Q 静默 + --max-turns 15：抑制 TUI，防止无限循环

4 常驻运行

# 前台运行（看日志）

python D:\***\agent-bridge\hermes_worker.py



# 计划任务开机启动（推荐）

schtasks /create /tn "HermesWorker" /tr "python D:\***\agent-bridge\hermes_worker.py" /sc onstart /ru SYSTEM
❌ 不要用 NSSM 创建 Windows 服务——NSSM 容易进入 SERVICE_PAUSED 死状态。用 schtasks 更可靠。

✅ 测试验证

# 1. 投递测试任务

python bridge.py send-task "Write a Python fibonacci function, save to utils/fibonacci.py"



# 2. 启动 Worker 处理

python hermes_worker.py --once



# 3. 检查结果

python bridge.py check-inbox agent



# 4. 查看生成的文件

type utils\fibonacci.py
看到 fibonacci.py 和 result JSON → 协作成功 🎉

🕳️ 踩坑大全

以下 6 个坑全部来自实战，每个都花了至少 30 分钟才定位。

🕳️ 坑 1：同步调用 = 必死

现象：exec 调 hermes chat，每次 60-90s 后 SIGKILL

原因：三层超时叠加（OpenClaw 90s + Hermes 启动 15-30s + LLM 思考）

教训：不要调大超时。异步解耦才是正确答案。

🕳️ 坑 2：Windows PTY stdout 黑洞

现象：terminal_tool 运行命令，stdout 永远为空

原因：Windows PTY 实现与 Linux 完全不同，Hermes 的捕获机制失效

教训：Windows 上不要让 Hermes 执行代码。Write-Only。

🕳️ 坑 3：PowerShell 多行文本展开

现象：hermes chat -q $p 参数被拆分

原因：PowerShell 展开换行符为参数分隔符

修复：用 Python subprocess.run(['hermes','chat','-q',text]) 绕过

🕳️ 坑 4：provider 配置陷阱

现象：配了百炼 Key，请求发到 OpenRouter

原因：provider="openai" 触发硬编码 OpenRouter fallback

修复：百炼用 "alibaba"，MiniMax 用 "anthropic"，通用用 "auto"

🕳️ 坑 5：NSSM 服务死锁

现象：NSSM 服务进入 SERVICE_PAUSED，无法停止/重启/删除

原因：NSSM 在 Windows Server 上有已知状态管理 bug

修复：放弃 NSSM，改用 schtasks 计划任务

🕳️ 坑 6：GBK 编码地狱

现象：hermes config show 崩溃 UnicodeEncodeError

原因：PowerShell 默认 GBK，无法显示 Unicode 特殊字符

修复：设环境变量 PYTHONIOENCODING=utf-8

⚡ Spark 补充：额外的坑

以下是 Spark 在实际使用中踩到的额外问题。

🕳️ 坑 7：SSL 代理黑洞

现象：urllib/requests 调 MiniMax API 间歇性 SSL: UNEXPECTED_EOF_WHILE_READING

原因：本地代理拦截 HTTPS 流量，SSL 握手被中间人破坏

修复：ssl.create_default_context() + ctx.verify_mode = ssl.CERT_NONE，或 requests 的 verify=False

教训：不要假设 API 调用一定能通，必须有 retry + fallback

🕳️ 坑 8：本地 vs 远程的「路径幻觉」

现象：文件写入成功、验证成功，但服务器上实际没有

原因：Agent 运行在本地机器（192.168.***.***），SSH 到服务器（*.*.*.*）。但本地也有 C:\***\content\ 目录，write 工具写的是本地不是远程

教训：Agent 必须明确自己在哪台机器上。用 hostname + IP 双重确认。浪费了 2 小时在这个问题上

🕳️ 坑 9：nginx 静态文件缓存

现象：文件确实在服务器 content 目录，但 nginx 返回 404

原因：nginx 的 try_files 在文件不存在时 fallback 到 Flask（返回 404），即使后来文件存在了，nginx 也不会自动发现

修复：每次部署新文件后必须 nginx -s reload

教训：部署脚本必须包含 reload 步骤，不能只传文件

🕳️ 坑 10：C:\tmp 文件消失

现象：之前生成的 HTML 文件在 C:\tmp\ 下，过几小时就没了

原因：系统有清理临时文件的策略

修复：重要文件保存到 workspace（~/.qclaw/workspace/）而非 tmp

教训：永远不要信任临时目录

✅ Spark 补充：实战验证的好处

1. File-as-API 模式很聪明

不走 HTTP，不走 WebSocket，就是文件读写。零依赖，零配置，零端口占用。对 Windows 兼容性最好。

2. Write-Only 原则是对的

Hermes 只负责写文件，Agent 负责验证和部署。职责清晰，出问题容易定位。避免了 Hermes 在 Windows 上执行命令的各种 PTY 问题。

3. 多模型路由的灵活性

百炼（provider="alibaba"）、MiniMax（provider="anthropic"）、通用（provider="auto"）。可以按任务类型选模型——这正是四象飞轮→ 已演化为五行飞轮的三模型编排思路：青龙用百炼发散，白虎用 MiniMax thinking，玄武用 Kimi 收敛。

4. 原子任务设计对飞轮的启发

"每个任务只写一个文件" → 对应认知 API 的单一职责。"上下文预加载" → 对应飞轮的认知记忆层。"Agent 来验证" → 对应白虎评估层。

🚀 进阶用法

场景 1：代码生成流水线

Agent 收到需求 → 拆分成文件级任务 → 逐个投递给 Hermes → 收取结果 → 组装验证

场景 2：文档/报告生成

Agent 分析数据 → 投递 "生成 HTML 报告" → Hermes 写 HTML → Agent 部署

场景 3：工具扩展

Agent 需要新工具 → 投递 "写一个 xxx.py" → Hermes 生成 → Agent 验证使用

四个关键原则

  1. 原子任务：每个任务只写一个文件
  2. 上下文预加载：prompt 中提供所有信息，不要让 Hermes 读文件
  3. Write-Only：Hermes 只写，Agent 来验证
  4. 信任路由：只路由到已验证能力（write_file），禁用未验证能力
📄 查看完整案例分析 ← 案例中心
“理想模型决定下限，人类残差决定上限。”
首页 知识树 飞轮分析库 金融日报
SkyCetus · 珑珠引擎