cc-haha/docs/features/computer-use.md

Computer Use 使用指南

Computer Use 允许模型读取屏幕并操作鼠标、键盘、应用和剪贴板。它直接作用于当前电脑，启用前请先理解授权范围和平台差异。

支持平台

平台	状态	关键差异
macOS Apple Silicon / Intel	支持	需要“辅助功能”和“屏幕录制”权限；支持原生截图过滤
Windows	支持	使用 Windows Python 运行时；截图不会过滤未授权窗口
Linux	不支持	当前没有 Linux 执行器

打包桌面端不要求用户安装 Bun。Computer Use 需要可用的 Python 3，应用会在用户配置目录下创建隔离的虚拟环境并安装平台依赖。

快速开始

桌面端

1. 打开“设置 → Computer Use”。
2. 开启 Computer Use。
3. 检查 Python 状态；自动检测失败时，可选择 Python 可执行文件。
4. 执行安装或修复，让应用创建虚拟环境和安装依赖。
5. macOS 用户授予“辅助功能”和“屏幕录制”权限，然后重新检查。
6. 选择允许控制的应用，并按需要开启剪贴板和系统组合键权限。
7. 新建会话，用自然语言描述目标和允许操作的应用。

可以从简单、可撤销的任务开始：

截取当前屏幕并告诉我你看到了什么。
打开 Notes，新建一条标题为“测试”的空白笔记。
在已授权的应用中，帮我找到设置入口，但不要修改任何内容。

CLI

源码模式需要先安装项目依赖，并保证 Python 3 可用：

bun install
python3 --version
./bin/claude-haha

可以通过环境变量关闭动态 Computer Use MCP：

CLAUDE_COMPUTER_USE_ENABLED=0 ./bin/claude-haha

也可以在 ~/.claude/cc-haha/computer-use-config.json 中设置：

{
  "enabled": false
}

桌面设置页修改的是同一份托管配置。优先使用设置页，不要手工覆盖其中未知字段。

工具与 Teach 能力

代码中定义了 27 个 Computer Use 工具：

类别	工具
授权	request_access、list_granted_applications
截图	screenshot、zoom
鼠标	left_click、right_click、middle_click、double_click、triple_click、left_click_drag、mouse_move、left_mouse_down、left_mouse_up、cursor_position、scroll
键盘	type、key、hold_key
应用	open_application、switch_display
剪贴板	read_clipboard、write_clipboard
控制流	wait、computer_batch
Teach	request_teach_access、teach_step、teach_batch

基础控制能力包含 24 个工具。Teach 的 3 个工具只在宿主启用 Teach capability 时公开；未启用时，当前会话只会看到基础工具。

Teach 用于“带着用户一步一步操作”的场景：

1. request_teach_access 请求教学所需的应用授权。
2. teach_step 展示一个带锚点的说明，并等待用户点击下一步。
3. teach_batch 把可以预判的多个教学步骤合并，减少模型往返。

Teach 授权与普通控制授权相互独立。教学步骤仍经过应用白名单和输入安全检查；用户退出教学后，模型不应继续调用 Teach 工具。

工作原理

Computer Use 使用“截图 → 分析 → 操作 → 再截图”的闭环：

模型
  → 调用 Computer Use MCP 工具
  → TypeScript 调度与安全检查
  → Python Bridge
  → macOS / Windows 系统操作
  → 截图或操作结果返回模型

• 工具定义与授权逻辑位于 src/vendor/computer-use-mcp/。
• CLI 集成和 Python Bridge 位于 src/utils/computerUse/。
• 平台执行器位于 runtime/mac_helper.py 和 runtime/win_helper.py。
• 桌面安装、权限和预授权由 src/server/api/computer-use.ts 与 desktop/src/pages/ComputerUseSettings.tsx 管理。

授权模型

应用授权

模型必须先调用 request_access，说明需要哪些应用以及原因。用户可以批准或拒绝。设置页中的预授权应用是默认授权配置，不代表任意应用都可以被控制；运行中新增应用仍需要走相应授权流程。

应用按能力分为三个等级：

等级	能力
read	读取截图，不执行输入
click	点击、移动和滚动，不输入文字或执行高权限动作
full	在其他安全检查通过后允许键盘、拖拽等完整操作

剪贴板与系统组合键

剪贴板读取、剪贴板写入和系统级组合键是单独的授权标志。允许控制某个应用，不会自动获得这些权限。

并发

Computer Use 使用会话锁防止多个会话同时争夺鼠标和键盘。看到“正在被其他会话使用”时，应先停止或完成原会话，而不是删除锁文件。

平台安全边界

macOS

• 需要“辅助功能”才能输入和操作应用。
• 需要“屏幕录制”才能截图。
• 截图支持原生窗口过滤，只保留授权应用和桌面。

Windows

• 当前截图过滤能力为 none：截图中可能出现所有可见窗口。
• 应用白名单仍会阻止把输入动作发送给未授权的前台应用。
• 因为截图本身不做过滤，开始前应主动关闭或最小化包含敏感信息的窗口。

当前明确没有的保护

• 没有全局 Escape 中止热键。 桌面端应使用当前任务的停止操作；CLI 运行可用终端中断。
• 不会在每次操作前自动隐藏未授权窗口。 不要依赖自动隐藏来保护敏感内容。
• 像素陈旧验证默认关闭。 UI 变化后，模型应重新截图再点击。

这些限制是当前实现边界，不应在文档或 UI 中描述成已经可用。

Python 运行时

首次安装或修复时，应用会：

1. 把当前平台的 helper 和 requirements 同步到用户配置目录。
2. 使用自动检测或用户选择的 Python 创建 venv。
3. 安装或升级 pip。
4. 按 requirements 内容哈希决定是否重新安装依赖。
5. 通过 JSON payload 调用平台 helper，并解析统一 JSON 结果。

macOS 主要依赖 mss、Pillow、PyAutoGUI 和 PyObjC；Windows 还使用 pywin32、psutil、pyperclip 与 screeninfo。准确版本约束以 runtime/requirements*.txt 为准。

故障排查

macOS 仍提示缺少权限

• 确认授权的是实际启动 Claude Code Haha 的应用。
• 权限变更后完全退出并重新打开应用。
• 在设置页重新执行权限检查。

Python 安装失败

• 在设置页选择明确的 Python 3 可执行文件。
• 确认该 Python 支持 venv。
• 使用“安装/修复”重新创建运行时。
• 查看“诊断”页中的 Computer Use 安装日志。

截图可以但点击失败

• 确认目标应用处于授权列表。
• 确认它是当前前台应用。
• 检查授权等级是否允许该动作。
• UI 已变化时重新截图，不要复用旧坐标。

Windows 截图出现其他窗口

这是当前 Windows 截图能力的已知边界。输入白名单不会过滤截图内容；执行前请关闭或最小化敏感窗口。

深入阅读

• Computer Use 架构
• 桌面端架构