Hermes + CUA 完整集成指南（Windows + WSL2）

📌 最终目标

在 WSL2 (Ubuntu) 中运行 Hermes Agent，让它通过 HTTP API 控制 Windows 宿主机上的 CUA（Computer Use Agent），实现对 Windows 桌面的自动化操作（点击、输入、截图等）。
支持两种模式：

  • 前台模式（直接控制物理鼠标键盘，简单可靠）

  • 后台沙箱模式（可选，使用 CuaBot 隔离环境）

📦 第一部分：Windows 宿主机配置

1.1 安装 Python（≥3.11）

  • 从 python.org 下载安装 Python 3.11 或更高版本

  • 安装时勾选 Add Python to PATH

1.2 安装 CUA Computer Server

打开 Windows PowerShell（管理员身份可选，但推荐）：

powershell

pip install cua-computer-server

1.3 启动 CUA 服务器

在 PowerShell 中运行（保持窗口打开）：

powershell

python -m computer_server --host 0.0.0.0 --port 8000

成功启动日志示例：

text

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     MCP server available at /mcp endpoint

1.4 验证服务正常

在 Windows 浏览器访问：http://127.0.0.1:8000/docs
或打开 WSL2 终端执行：

bash

curl http://127.0.0.1:8000/status

应返回：

json

{"status":"ok","os_type":"windows","features":["mcp"]}

🐧 第二部分：WSL2 (Ubuntu) 环境准备

2.1 确保网络连通

WSL2 默认可以通过 127.0.0.1 访问 Windows 宿主机上绑定的服务（需 Windows 防火墙放行 8000 端口）。
测试：

bash

curl http://127.0.0.1:8000/status   # 应返回 JSON

2.2 安装 Hermes Agent（如未安装）

参考 Hermes 官方文档，通常：

bash

pip install hermes-agent   # 或使用其他安装方式

确保 hermes 命令可用。

2.3 确认 code_execution 工具已启用

启动 Hermes 会话：

bash

hermes

在会话中输入：

text

/tools

检查 code_execution 是否在 enabled 列表中。
若未启用，退出 Hermes，执行：

bash

hermes tools

在交互界面中启用 code_execution。

🤖 第三部分：编写 Hermes 自定义技能（可选但推荐）

虽然我们可以直接用 code_execution 工具，但自定义技能让调用更自然。以下提供完整的技能文件。

3.1 创建技能目录

bash

mkdir -p ~/.hermes/skills/win-cua
cd ~/.hermes/skills/win-cua

3.2 创建 main.py 文件

这是技能的核心执行脚本。完整代码如下：

python

#!/usr/bin/env python3
"""
Hermes skill to control Windows desktop via CUA computer_server.
API endpoint: http://127.0.0.1:8000/cmd
"""

import requests
import json
import sys
import base64

CUA_CMD_URL = "http://127.0.0.1:8000/cmd"

def execute_command(command, params=None):
    """Send command to CUA server and return parsed result."""
    payload = {"command": command, "params": params or {}}
    try:
        resp = requests.post(CUA_CMD_URL, json=payload, timeout=10)
        resp.raise_for_status()
        text = resp.text
        # Strip SSE "data: " prefix if present
        if text.startswith("data: "):
            text = text[6:]
        return json.loads(text)
    except Exception as e:
        return {"error": str(e)}

# ---------- 对外暴露的函数（Hermes 可调用）----------
def cua_action(action: str, params: dict = None):
    """
    通用 CUA 动作执行器。
    action: 命令名称（如 left_click, type_text, screenshot 等）
    params: 参数字典
    """
    return execute_command(action, params)

def click(x=None, y=None, button="left", clicks=1):
    if x is not None and y is not None:
        execute_command("move_cursor", {"x": x, "y": y})
    if button == "left":
        return execute_command("left_click", {"x": x, "y": y} if x else {})
    elif button == "right":
        return execute_command("right_click", {"x": x, "y": y} if x else {})
    elif button == "double":
        return execute_command("double_click", {"x": x, "y": y} if x else {})
    else:
        return {"error": f"Unsupported button: {button}"}

def type_text(text: str):
    return execute_command("type_text", {"text": text})

def press_key(key: str):
    return execute_command("press_key", {"key": key})

def hotkey(keys: list):
    return execute_command("hotkey", {"keys": keys})

def move_cursor(x: int, y: int):
    return execute_command("move_cursor", {"x": x, "y": y})

def screenshot(format="png", quality=95):
    return execute_command("screenshot", {"format": format, "quality": quality})

def get_cursor_position():
    return execute_command("get_cursor_position")

def get_screen_size():
    return execute_command("get_screen_size")

# ---------- CLI 直接测试 ----------
if __name__ == "__main__":
    if len(sys.argv) < 2:
        print(json.dumps({"error": "Missing command"}))
        sys.exit(1)
    cmd = sys.argv[1]
    params = json.loads(sys.argv[2]) if len(sys.argv) > 2 else {}
    result = execute_command(cmd, params)
    print(json.dumps(result, indent=2))

3.3 创建 SKILL.md 文件

技能描述文件，Hermes 会读取它来理解技能用途。内容如下：

markdown

---
name: win-cua
description: Control Windows desktop via CUA (mouse, keyboard, screenshot)
tools:
  - name: cua_action
    description: Execute a desktop action like left_click, type_text, screenshot, etc.
    parameters:
      - name: action
        type: string
        required: true
        description: The command name (e.g., left_click, type_text, move_cursor, screenshot, get_cursor_position, hotkey, press_key)
      - name: params
        type: object
        required: false
        description: Optional parameters for the command (e.g., {"x":100,"y":200} for left_click)
    returns: Result of the action (success/error + data)
---

Use this skill to perform GUI automation on Windows.

Examples:
- `cua_action("left_click", {"x": 500, "y": 400})`
- `cua_action("type_text", {"text": "Hello"})`
- `cua_action("press_key", {"key": "enter"})`
- `cua_action("hotkey", {"keys": ["ctrl", "c"]})`
- `cua_action("move_cursor", {"x": 100, "y": 200})`
- `cua_action("screenshot")`
- `cua_action("get_cursor_position")`
- `cua_action("get_screen_size")`

3.4 注册技能

bash

chmod +x ~/.hermes/skills/win-cua/main.py
hermes skill register ~/.hermes/skills/win-cua

3.5 验证技能加载

启动 Hermes 会话：

bash

hermes

然后输入：

text

/skills

应该能看到 win-cua 技能列出。

🧪 第四部分：测试技能与直接 API 调用

4.1 查看 CUA 支持的所有命令

在 WSL2 终端执行：

bash

curl http://127.0.0.1:8000/commands

你会得到一个巨大的 JSON，其中包含所有可用命令名及其参数。
重要命令对照表（常用）：

操作命令名参数示例
左键单击left_click{"x":100, "y":200}（坐标可选）
右键单击right_click{"x":100, "y":200}
双击double_click{"x":100, "y":200}
移动鼠标move_cursor{"x":100, "y":200}
输入文本type_text{"text":"Hello"}
按键press_key{"key":"enter"}
组合键hotkey{"keys":["ctrl","c"]}
截图screenshot{"format":"png","quality":95}
获取鼠标位置get_cursor_position{}
获取屏幕尺寸get_screen_size{}
滚动scroll{"x":0, "y":3}

4.2 测试 API 直接调用（不经过 Hermes）

bash

# 左键单击坐标 (500,400)
curl -X POST http://127.0.0.1:8000/cmd \
  -H "Content-Type: application/json" \
  -d '{"command":"left_click", "params":{"x":500,"y":400}}'

# 截图
curl -X POST http://127.0.0.1:8000/cmd \
  -H "Content-Type: application/json" \
  -d '{"command":"screenshot"}'

成功返回 data: {"success": true} 或包含图片 base64 的 JSON。

4.3 在 Hermes 中使用技能

启动 Hermes 会话后，输入：

text

使用 win-cua 技能的 cua_action 执行 left_click，参数 {"x": 500, "y": 400}

Hermes 会调用你的技能，Windows 桌面上鼠标应移动到 (500,400) 并点击。

4.4 使用 code_execution 工具（备选方案，无需技能）

直接在 Hermes 中说：

text

请用 code_execution 运行 Python 代码，调用 http://127.0.0.1:8000/cmd，命令 left_click，参数 x=500,y=400。

Hermes 会生成 Python 代码并执行，效果相同。

🔐 第五部分：可选后台沙箱模式（不抢鼠标）

如果你希望 AI 操作不影响你当前的鼠标活动，使用 CuaBot 创建独立沙箱。

5.1 在 Windows 上安装 Node.js（如果未安装）

从 nodejs.org 下载安装 LTS 版本。

5.2 启动 CuaBot 沙箱

在 Windows PowerShell 中：

powershell

npx cuabot -n hermes-sandbox

桌面会出现一个带彩色边框的新窗口，这是 AI 的独立工作区。

5.3 让 Hermes 控制沙箱

在 Hermes 中通过 code_execution 执行 npx cuabot 命令（需确保 WSL2 能调用 Windows 的 npx，可能需要 npx.cmd 或使用 powershell.exe -c）。
更简单的做法：直接在 WSL2 中使用 HTTP API 控制沙箱（沙箱本身也暴露 API，但端口不同）。
由于 CuaBot 沙箱默认 API 端口为 8080，且需要提供 X-Container-Name 头。具体请参考 cuabot 文档，但作为基础流程，建议先使用第一部分的前台模式，功能完整且简单。

📋 第六部分：完整排错清单

现象解决方法
curl http://127.0.0.1:8000/status 失败检查 Windows 防火墙入站规则，允许 TCP 8000 端口；或在 WSL2 中使用 curl http://$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):8000/status
pip install cua-computer-server 报错 “externally-managed-environment”使用虚拟环境：python -m venv cua_env && cua_env\Scripts\activate（Windows）
Hermes 技能注册后不可见确认 ~/.hermes/skills/win-cua/SKILL.md 中 name 字段与目录名一致；重启 Hermes 会话
left_click 命令报 “Unknown command”先运行 curl http://127.0.0.1:8000/commands 查看正确的命令名（有些版本可能是 click，但新版为 left_click）
鼠标移动但未点击检查坐标是否在屏幕内；尝试 {"command":"left_click"} 不带坐标（点击当前位置）
Hermes 说 “code_execution 工具未启用”运行 hermes tools 启用它，或修改配置文件 ~/.config/hermes/config.yaml 添加 code_execution: enabled

✅ 第七部分：一键验证脚本（在 WSL2 中运行）

创建文件 test_cua.py：

python

import requests
import json

url = "http://127.0.0.1:8000/cmd"
payload = {"command": "get_cursor_position", "params": {}}
resp = requests.post(url, json=payload)
print("Cursor position:", resp.text)

运行：

bash

python3 test_cua.py

应输出类似 data: {"x": 123, "y": 456}。

🎉 总结

你已获得：

  • ✅ Windows 上运行的 CUA 服务器（HTTP API）

  • ✅ WSL2 中 Hermes 与 CUA 的无缝集成

  • ✅ 完整的自定义技能代码（main.py + SKILL.md）

  • ✅ 所有测试命令和排错指南

Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

一台小主机同时跑 NAS、Windows 和软路由？ESXi +飞牛 All-in-One 搭建实战

avatar AtomGit开源社区
cover

不会做内网穿透？一篇 Natapp 入门教程，从零带你上手

avatar AtomGit开源社区
cover

小黑课堂【计算机二级】WPSoffice题库软件下载安装教程

avatar AtomGit开源社区