Hermes CUA 完整集成指南Windows WSL2 最终目标在WSL2 (Ubuntu)中运行Hermes Agent让它通过 HTTP API 控制Windows 宿主机上的 CUAComputer Use Agent实现对 Windows 桌面的自动化操作点击、输入、截图等。支持两种模式前台模式直接控制物理鼠标键盘简单可靠后台沙箱模式可选使用 CuaBot 隔离环境 第一部分Windows 宿主机配置1.1 安装 Python≥3.11从 python.org 下载安装Python 3.11 或更高版本安装时勾选Add Python to PATH1.2 安装 CUA Computer Server打开Windows PowerShell管理员身份可选但推荐powershellpip install cua-computer-server1.3 启动 CUA 服务器在 PowerShell 中运行保持窗口打开powershellpython -m computer_server --host 0.0.0.0 --port 8000成功启动日志示例textINFO: Uvicorn running on http://0.0.0.0:8000 INFO: MCP server available at /mcp endpoint1.4 验证服务正常在Windows 浏览器访问http://127.0.0.1:8000/docs或打开WSL2 终端执行bashcurl 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 端口。测试bashcurl http://127.0.0.1:8000/status # 应返回 JSON2.2 安装 Hermes Agent如未安装参考 Hermes 官方文档通常bashpip install hermes-agent # 或使用其他安装方式确保hermes命令可用。2.3 确认code_execution工具已启用启动 Hermes 会话bashhermes在会话中输入text/tools检查code_execution是否在enabled列表中。若未启用退出 Hermes执行bashhermes tools在交互界面中启用code_execution。 第三部分编写 Hermes 自定义技能可选但推荐虽然我们可以直接用code_execution工具但自定义技能让调用更自然。以下提供完整的技能文件。3.1 创建技能目录bashmkdir -p ~/.hermes/skills/win-cua cd ~/.hermes/skills/win-cua3.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, paramsNone): Send command to CUA server and return parsed result. payload {command: command, params: params or {}} try: resp requests.post(CUA_CMD_URL, jsonpayload, timeout10) 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(xNone, yNone, buttonleft, clicks1): 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: fUnsupported 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(formatpng, quality95): 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, indent2))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 注册技能bashchmod x ~/.hermes/skills/win-cua/main.py hermes skill register ~/.hermes/skills/win-cua3.5 验证技能加载启动 Hermes 会话bashhermes然后输入text/skills应该能看到win-cua技能列出。 第四部分测试技能与直接 API 调用4.1 查看 CUA 支持的所有命令在 WSL2 终端执行bashcurl 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 直接调用不经过 Hermesbash# 左键单击坐标 (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参数 x500,y400。Hermes 会生成 Python 代码并执行效果相同。 第五部分可选后台沙箱模式不抢鼠标如果你希望 AI 操作不影响你当前的鼠标活动使用 CuaBot 创建独立沙箱。5.1 在 Windows 上安装 Node.js如果未安装从 nodejs.org 下载安装 LTS 版本。5.2 启动 CuaBot 沙箱在 Windows PowerShell 中powershellnpx 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/statuspip install cua-computer-server报错 “externally-managed-environment”使用虚拟环境python -m venv cua_env cua_env\Scripts\activateWindowsHermes 技能注册后不可见确认~/.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.pypythonimport requests import json url http://127.0.0.1:8000/cmd payload {command: get_cursor_position, params: {}} resp requests.post(url, jsonpayload) print(Cursor position:, resp.text)运行bashpython3 test_cua.py应输出类似data: {x: 123, y: 456}。 总结你已获得✅ Windows 上运行的 CUA 服务器HTTP API✅ WSL2 中 Hermes 与 CUA 的无缝集成✅ 完整的自定义技能代码main.pySKILL.md✅ 所有测试命令和排错指南
hermes与cua联动配置
Hermes CUA 完整集成指南Windows WSL2 最终目标在WSL2 (Ubuntu)中运行Hermes Agent让它通过 HTTP API 控制Windows 宿主机上的 CUAComputer Use Agent实现对 Windows 桌面的自动化操作点击、输入、截图等。支持两种模式前台模式直接控制物理鼠标键盘简单可靠后台沙箱模式可选使用 CuaBot 隔离环境 第一部分Windows 宿主机配置1.1 安装 Python≥3.11从 python.org 下载安装Python 3.11 或更高版本安装时勾选Add Python to PATH1.2 安装 CUA Computer Server打开Windows PowerShell管理员身份可选但推荐powershellpip install cua-computer-server1.3 启动 CUA 服务器在 PowerShell 中运行保持窗口打开powershellpython -m computer_server --host 0.0.0.0 --port 8000成功启动日志示例textINFO: Uvicorn running on http://0.0.0.0:8000 INFO: MCP server available at /mcp endpoint1.4 验证服务正常在Windows 浏览器访问http://127.0.0.1:8000/docs或打开WSL2 终端执行bashcurl 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 端口。测试bashcurl http://127.0.0.1:8000/status # 应返回 JSON2.2 安装 Hermes Agent如未安装参考 Hermes 官方文档通常bashpip install hermes-agent # 或使用其他安装方式确保hermes命令可用。2.3 确认code_execution工具已启用启动 Hermes 会话bashhermes在会话中输入text/tools检查code_execution是否在enabled列表中。若未启用退出 Hermes执行bashhermes tools在交互界面中启用code_execution。 第三部分编写 Hermes 自定义技能可选但推荐虽然我们可以直接用code_execution工具但自定义技能让调用更自然。以下提供完整的技能文件。3.1 创建技能目录bashmkdir -p ~/.hermes/skills/win-cua cd ~/.hermes/skills/win-cua3.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, paramsNone): Send command to CUA server and return parsed result. payload {command: command, params: params or {}} try: resp requests.post(CUA_CMD_URL, jsonpayload, timeout10) 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(xNone, yNone, buttonleft, clicks1): 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: fUnsupported 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(formatpng, quality95): 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, indent2))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 注册技能bashchmod x ~/.hermes/skills/win-cua/main.py hermes skill register ~/.hermes/skills/win-cua3.5 验证技能加载启动 Hermes 会话bashhermes然后输入text/skills应该能看到win-cua技能列出。 第四部分测试技能与直接 API 调用4.1 查看 CUA 支持的所有命令在 WSL2 终端执行bashcurl 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 直接调用不经过 Hermesbash# 左键单击坐标 (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参数 x500,y400。Hermes 会生成 Python 代码并执行效果相同。 第五部分可选后台沙箱模式不抢鼠标如果你希望 AI 操作不影响你当前的鼠标活动使用 CuaBot 创建独立沙箱。5.1 在 Windows 上安装 Node.js如果未安装从 nodejs.org 下载安装 LTS 版本。5.2 启动 CuaBot 沙箱在 Windows PowerShell 中powershellnpx 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/statuspip install cua-computer-server报错 “externally-managed-environment”使用虚拟环境python -m venv cua_env cua_env\Scripts\activateWindowsHermes 技能注册后不可见确认~/.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.pypythonimport requests import json url http://127.0.0.1:8000/cmd payload {command: get_cursor_position, params: {}} resp requests.post(url, jsonpayload) print(Cursor position:, resp.text)运行bashpython3 test_cua.py应输出类似data: {x: 123, y: 456}。 总结你已获得✅ Windows 上运行的 CUA 服务器HTTP API✅ WSL2 中 Hermes 与 CUA 的无缝集成✅ 完整的自定义技能代码main.pySKILL.md✅ 所有测试命令和排错指南
