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）✅ 所有测试命令和排错指南
