Computer Use 功能指南

魔改说明：本功能是基于 Claude Code 泄露源码中的 Computer Use（内部代号 "Chicago"）进行的深度改造版本。官方实现依赖 Anthropic 内部私有原生模块（@ant/computer-use-swift、@ant/computer-use-input），无法公开获取。我们替换了整个底层操作层，使用 Python bridge（pyautogui + mss + pyobjc）实现所有系统交互，使得任何人都可以在 macOS 上运行 Computer Use 功能。

功能简介

Computer Use 让 AI 模型能够直接控制你的电脑——截屏、移动鼠标、点击按钮、输入文字、管理应用窗口。

支持的操作（共 24 个 MCP 工具）：

类别	工具
截屏	`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`
权限	`request_access`、`list_granted_applications`
剪贴板	`read_clipboard`、`write_clipboard`
其他	`wait`、`computer_batch`

支持的设备与平台

平台	芯片	状态	说明
macOS	Apple Silicon (M1/M2/M3/M4)	✅ 完整支持	推荐平台
macOS	Intel x86_64	✅ 完整支持
Windows	任意	⚠️ 理论可行	`pyautogui` + `mss` 跨平台，但 `pyobjc` 部分（应用管理）需替换为 `win32com`，当前未适配
Linux	任意	⚠️ 理论可行	同上，需替换 `pyobjc` 为 `wmctrl` + `xdotool`，当前未适配

运行环境要求

Bun >= 1.1.0
Python >= 3.8（首次运行自动创建 venv 并安装依赖）
macOS 系统权限：Accessibility（辅助功能）+ Screen Recording（屏幕录制）

工作原理

Computer Use 的核心是一个截图-分析-操作的闭环：

┌──────────────────────────────────────────────┐
│  AI 模型（Claude / 其他 Anthropic 协议模型）     │
│                                               │
│  1. 收到用户请求 "打开网易云搜索喜欢你"            │
│  2. 调用 screenshot 工具 → 收到屏幕截图           │
│  3. 模型分析截图像素，识别 UI 元素位置              │
│     → "搜索框在 (756, 342)"                     │
│  4. 调用 left_click { coordinate: [756, 342] }  │
│  5. 调用 type { text: "喜欢你" }                 │
│  6. 再次 screenshot → 确认结果 → 下一步...        │
└──────────────┬───────────────────────────────┘
               │ MCP Tool Call
               ▼
┌──────────────────────────────────────────────┐
│  TypeScript 工具层                              │
│  (vendor/computer-use-mcp)                     │
│                                               │
│  - 安全检查（应用白名单、TCC 权限）               │
│  - 坐标模式转换（pixels / normalized）           │
│  - 工具分发 → executor                          │
└──────────────┬───────────────────────────────┘
               │ callPythonHelper()
               ▼
┌──────────────────────────────────────────────┐
│  Python Bridge                                │
│  (runtime/mac_helper.py)                      │
│                                               │
│  pyautogui.click(756, 342)  ← 鼠标控制         │
│  mss.grab(monitor)          ← 截图             │
│  NSWorkspace.open(bundleId) ← 应用管理          │
└──────────────────────────────────────────────┘

关键：坐标分析完全由模型的视觉能力完成——模型"看"截图就像人看屏幕一样，直接从像素中识别按钮、输入框等 UI 元素的位置。

快速开始

1. 安装依赖

bash

bun install

2. 确保 Python 3 可用

bash

python3 --version  # 需要 >= 3.8

Python 依赖会在首次使用 Computer Use 时自动安装到 .runtime/venv/，无需手动操作。

3. 授予 macOS 权限

Accessibility（辅助功能）

bash

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"

将你的终端应用（如 iTerm、Terminal、Ghostty 等）添加到允许列表。

Screen Recording（屏幕录制）

bash

open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"

同样添加你的终端应用。授权后可能需要重启终端。

4. 启动

bash

./bin/claude-haha

5. 使用

在对话中用自然语言请求即可：

> 帮我打开网易云音乐，搜索一首歌
> 截个屏看看当前桌面
> 帮我在 VS Code 里打开终端

使用方式

首次使用 Computer Use 时，系统会弹出应用授权对话框，你需要选择允许 Claude 操作的应用。

模型会先调用 request_access 请求权限
你在终端中确认允许哪些应用
之后模型就可以截图、点击、输入了

安全机制

机制	说明
应用白名单	每次会话需要明确授权允许操作的应用
并发保护	同一时间只有一个 Claude 会话可使用 Computer Use（文件锁机制）
剪贴板保护	通过剪贴板输入文本时会自动保存和恢复原始剪贴板内容
操作确认	敏感操作（如系统快捷键）需要额外授权

注意：由于底层改为 Python bridge，原生方案中的全局 Escape 快捷键中止和操作前自动隐藏应用功能暂不可用。可使用 Ctrl+C 中止。

环境变量

变量	默认值	说明
`CLAUDE_COMPUTER_USE_ENABLED`	`1`	设为 `0` 可禁用 Computer Use
`CLAUDE_COMPUTER_USE_COORDINATE_MODE`	`pixels`	坐标模式：`pixels` 或 `normalized_0_100`
`CLAUDE_COMPUTER_USE_CLIPBOARD_PASTE`	`1`	是否启用剪贴板粘贴输入
`CLAUDE_COMPUTER_USE_MOUSE_ANIMATION`	`1`	是否启用鼠标动画
`CLAUDE_COMPUTER_USE_HIDE_BEFORE_ACTION`	`0`	操作前是否隐藏其他窗口
`CLAUDE_COMPUTER_USE_DEBUG`	`0`	调试模式

技术架构详解

整体分层

src/
├── vendor/computer-use-mcp/     ← MCP 工具定义与分发（12 个文件）
│   ├── tools.ts                 ← 24 个工具的 schema 定义
│   ├── toolCalls.ts             ← 安全检查 + 工具分发
│   ├── mcpServer.ts             ← MCP 服务器创建
│   ├── types.ts                 ← 全部类型定义
│   └── ...
├── utils/computerUse/
│   ├── executor.ts              ← 执行器（调用 Python bridge）
│   ├── pythonBridge.ts          ← Python 子进程管理
│   ├── hostAdapter.ts           ← 权限检查适配器
│   ├── gates.ts                 ← 功能开关（已绕过灰度）
│   ├── wrapper.tsx              ← MCP 工具覆写层
│   ├── setup.ts                 ← MCP 配置初始化
│   └── ...
└── runtime/
    ├── mac_helper.py            ← Python 实现（659 行）
    └── requirements.txt         ← Python 依赖

灰度控制绕过

官方 Claude Code 中 Computer Use 通过三层门控限制访问：

层级	原始机制	我们的处理
编译时	`feature('CHICAGO_MCP')` (Bun 编译宏)	替换为 `true`
订阅检查	`hasRequiredSubscription()` (Max/Pro)	`getChicagoEnabled()` 直接返回 `true`
远程配置	GrowthBook `tengu_malort_pedway`	同上，不再依赖远程配置
默认禁用	`isDefaultDisabledBuiltin('computer-use')`	`isDefaultDisabledBuiltin()` 返回 `false`

Python Bridge 工作机制

typescript

// pythonBridge.ts
async function callPythonHelper<T>(command: string, payload: object): Promise<T> {
  await ensureBootstrapped()  // 首次调用自动创建 venv + pip install
  
  // 调用: python3 runtime/mac_helper.py <command> --payload '{...}'
  const result = execFile(pythonBin, ['mac_helper.py', command, '--payload', JSON.stringify(payload)])
  
  return JSON.parse(result.stdout)  // { ok: true, result: T }
}

首次运行自动完成：

创建 Python 虚拟环境 (.runtime/venv/)
安装 pip
安装依赖 (mss, Pillow, pyautogui, pyobjc-*)
SHA256 哈希验证（仅 requirements.txt 变更时重新安装）

我们尝试过的方案

方案一：从 Claude Code 二进制提取原生 .node 模块 ❌

思路：从已安装的 Claude Code 二进制 (~/.local/share/claude/versions/2.1.91，189MB Mach-O) 中定位并提取嵌入的原生 NAPI 模块。

实施：

成功从 Bun $bunfs 虚拟文件系统中提取了 computer-use-swift.node (ARM64 424KB + x64 430KB) 和 computer-use-input.node (ARM64 836KB + x64 821KB)
同步方法（TCC 权限检查、显示枚举）正常工作
创建了 npm 包装包并通过 workspace 注册

失败原因：

Swift 异步方法（screenshot.captureExcluding）的 continuation 永远不会 resume
根因：提取的 .node 文件是针对 Claude Code 内置的 Bun 运行时编译的，与用户系统的 Bun 版本的 N-API 异步实现不兼容
错误信息：SWIFT TASK CONTINUATION MISUSE: captureScreenWithExclusion leaked its continuation without resuming it

方案二：创建空 Stub 包 ❌

思路：为 @ant/computer-use-mcp、@ant/computer-use-input、@ant/computer-use-swift 创建最小化的 stub 包，使代码能编译加载。

失败原因：代码能编译但 MCP 服务器注册后无法执行任何实际操作——截图、点击等全部报错。

方案三：Python Bridge 替代原生模块 ✅（当前方案）

思路：参考 wimi321/macos-computer-use-skill，用 Python 子进程替代所有原生模块调用。

优势：

零二进制依赖，不依赖特定 Bun/Node 版本
纯 Python 实现，首次运行自动安装
截图、鼠标、键盘、应用管理全部可用
macOS ARM64 + x86_64 均支持

已知限制

限制	说明
仅 macOS	Windows/Linux 需要适配 `pyobjc` 部分
无全局 Escape 中止	原生方案用 CGEventTap 实现，Python 版暂不支持，用 `Ctrl+C` 代替
操作前不自动隐藏窗口	原生方案的 `prepareDisplay` 依赖 Swift，Python 版未实现
性能略低	Python 进程启动 ~100ms 开销，但模型思考时间通常是秒级，用户感知不到
像素验证关闭	`pixelValidation` 默认关闭

参考项目与致谢

本功能的实现参考了以下开源项目，在此致以感谢：

项目	许可证	贡献
wimi321/macos-computer-use-skill	MIT	Python bridge 架构、`mac_helper.py` 运行时、`executor.ts` 适配方案。该项目从 Claude Code 工作流中提取了可复用的 TypeScript 逻辑，并用完全公开的 Python 库替代了私有原生模块
domdomegg/computer-use-mcp	MIT	独立的 Computer Use MCP 服务器实现（基于 nut.js），跨平台可用。在方案调研阶段提供了参考
paoloanzn/free-code	-	Feature flag 系统分析和构建系统参考
oboard/claude-code-rev	-	泄露源码的早期恢复工作，提供了 stub 包的参考实现

底层依赖

库	用途
pyautogui	鼠标和键盘控制
mss	屏幕截图
Pillow	图像处理和压缩
pyobjc	macOS Cocoa/Quartz 框架绑定（应用管理、显示枚举）

Computer Use 功能指南 ​

目录 ​

功能简介 ​

支持的设备与平台 ​

运行环境要求 ​

工作原理 ​

快速开始 ​

1. 安装依赖 ​

2. 确保 Python 3 可用 ​

3. 授予 macOS 权限 ​

Accessibility（辅助功能） ​

Screen Recording（屏幕录制） ​

4. 启动 ​

5. 使用 ​

使用方式 ​

安全机制 ​

环境变量 ​

技术架构详解 ​

整体分层 ​

灰度控制绕过 ​

Python Bridge 工作机制 ​

我们尝试过的方案 ​

方案一：从 Claude Code 二进制提取原生 .node 模块 ❌ ​

方案二：创建空 Stub 包 ❌ ​

方案三：Python Bridge 替代原生模块 ✅（当前方案） ​

已知限制 ​

参考项目与致谢 ​

底层依赖 ​

Computer Use 功能指南

目录

功能简介

支持的设备与平台

运行环境要求

工作原理

快速开始

1. 安装依赖

2. 确保 Python 3 可用

3. 授予 macOS 权限

Accessibility（辅助功能）

Screen Recording（屏幕录制）

4. 启动

5. 使用

使用方式

安全机制

环境变量

技术架构详解

整体分层

灰度控制绕过

Python Bridge 工作机制

我们尝试过的方案

方案一：从 Claude Code 二进制提取原生 .node 模块 ❌

方案二：创建空 Stub 包 ❌

方案三：Python Bridge 替代原生模块 ✅（当前方案）

已知限制

参考项目与致谢

底层依赖