claude-code/docs/features/computer-use.md

Computer Use — macOS / Windows / Linux 跨平台实施计划

更新时间：2026-04-04 参考项目：https://github.com/JrCx7scC/claude-code-source

1. 现状

参考项目的 Computer Use 仅支持 macOS——从入口到底层全部写死 darwin。我们的项目在 Phase 1-3 中已经完成了：

• ✅ @ant/computer-use-mcp stub 替换为完整实现（12 文件）
• ✅ @ant/computer-use-input 拆为 dispatcher + backends（darwin + win32）
• ✅ @ant/computer-use-swift 拆为 dispatcher + backends（darwin + win32）
• ✅ CHICAGO_MCP 编译开关已开
• ✅ src/ 层 macOS 硬编码全部移除，已支持 darwin / win32 / linux 三平台

2. 用户使用方式

Computer Use 由 CHICAGO_MCP feature flag 控制，无需额外 CLI 参数。

订阅要求：需要 Claude Pro、Max 或 Team 订阅，Computer Use 功能不向免费用户开放。

Dev 模式（默认已开启）

bun run dev

scripts/dev.ts 的默认 feature 列表已包含 CHICAGO_MCP，启动后自动注册 Computer Use MCP 工具。

构建产物

FEATURE_CHICAGO_MCP=1 node dist/cli.js

使用流程

1. 启动 CLI — bun run dev（或构建产物 + 环境变量）
2. 正常对话 — 在 REPL 中与 Claude 对话，当你让 Claude 操作电脑时（如"帮我打开浏览器并访问 xxx"），Claude 会调用 Computer Use 工具
3. 首次审批 — Claude 首次尝试操控某个 App 时，会弹出权限对话框，你需要确认允许哪些 App 被操控（可勾选"本次会话不再询问"）
4. 操作中 — 系统会发送通知"Claude is using your computer"，macOS 按 Esc、其他平台按 Ctrl+C 可中止
5. 操作结束 — Claude 完成操作后自动释放，被隐藏的窗口会自动恢复

可用的操作

• 截图（全屏 / 区域缩放）
• 鼠标移动、点击、拖拽、滚轮
• 键盘输入、组合键、长按
• 通过剪贴板粘贴多行文本
• 应用管理（列出、打开、隐藏/恢复）
• 多显示器支持（自动选择或手动指定）

Linux 依赖工具

工具	用途	安装命令（Ubuntu）
xdotool	键鼠模拟 + 窗口管理	sudo apt install xdotool
scrot 或 gnome-screenshot	截图	sudo apt install scrot
xrandr	显示器信息	通常已预装
xclip	剪贴板	sudo apt install xclip
wmctrl	窗口列表/切换	sudo apt install wmctrl

Wayland 环境需要替代工具：ydotool（替代 xdotool）、grim（替代 scrot）、wl-clipboard（替代 xclip）。初期只支持 X11，Wayland 标记为 todo。

macOS 权限

macOS 首次使用需要授予「辅助功能」和「屏幕录制」权限（系统会提示）。

Windows

无需额外权限，开箱即用。

3. 实施细节

3.1 功能开关（gates.ts）

• enabled 默认为 true，无需订阅检查
• hasRequiredSubscription() 直接返回 true
• 子开关（鼠标动画、隐藏窗口、剪贴板守卫等）均通过 GrowthBook 远程配置或使用默认值

3.2 平台分发

所有平台相关逻辑已通过 process.platform 判断分发：

文件	处理方式
executor.ts	剪贴板：darwin→pbcopy/pbpaste，win32→PowerShell，linux→xclip；粘贴键：darwin→command+v，其他→ctrl+v
drainRunLoop.ts	非 darwin 直接执行 fn()，不需要 CFRunLoop pump
escHotkey.ts	非 darwin 返回 false（已有 Ctrl+C fallback）
hostAdapter.ts	非 darwin 直接返回 { granted: true }，macOS 检查 TCC 权限
common.ts	动态获取 platform 标识，截图过滤按平台选择
swiftLoader.ts	自动检测包导出类型，跨平台实例化 ComputerUseAPI
main.tsx	仅检查 feature('CHICAGO_MCP') + 交互模式，无平台限制

3.3 每个平台的能力依赖

computer-use-input（键鼠）

功能	macOS	Windows	Linux
鼠标移动	CGEvent JXA	SetCursorPos P/Invoke	xdotool mousemove
鼠标点击	CGEvent JXA	SendInput P/Invoke	xdotool click
鼠标滚轮	CGEvent JXA	SendInput MOUSEEVENTF_WHEEL	xdotool scroll
键盘按键	System Events osascript	keybd_event P/Invoke	xdotool key
组合键	System Events osascript	keybd_event 组合	xdotool key combo
文本输入	System Events keystroke	SendKeys.SendWait	xdotool type
前台应用	System Events osascript	GetForegroundWindow P/Invoke	xdotool getactivewindow + /proc
工具依赖	osascript（内置）	powershell（内置）	xdotool（需安装）

computer-use-swift（截图 + 应用管理）

功能	macOS	Windows	Linux
全屏截图	screencapture	CopyFromScreen	gnome-screenshot / scrot / grim
区域截图	screencapture -R	CopyFromScreen(rect)	gnome-screenshot -a / scrot -a / grim -g
显示器列表	CGGetActiveDisplayList JXA	Screen.AllScreens	xrandr --query
运行中应用	System Events JXA	Get-Process	wmctrl -l / ps
打开应用	osascript activate	Start-Process	xdg-open / gtk-launch
隐藏/显示	System Events visibility	ShowWindow/SetForegroundWindow	wmctrl -c / xdotool
工具依赖	screencapture + osascript	powershell	xdotool + scrot/grim + wmctrl

executor 层

功能	macOS	Windows	Linux
drainRunLoop	CFRunLoop pump	不需要	不需要
ESC 热键	CGEventTap	跳过（Ctrl+C fallback）	跳过（Ctrl+C fallback）
剪贴板读	pbpaste	powershell Get-Clipboard	xclip -o / wl-paste
剪贴板写	pbcopy	powershell Set-Clipboard	xclip / wl-copy
粘贴快捷键	command+v	ctrl+v	ctrl+v
终端检测	__CFBundleIdentifier	WT_SESSION / TERM_PROGRAM	TERM_PROGRAM
系统权限	TCC check	直接 granted	检查 xdotool 安装

4. 完成状态

Phase	内容	状态
Phase 1	MCP 实现 + Windows 后端	✅ 已完成
Phase 2	移除 macOS 硬编码	✅ 已完成
Phase 3	Linux 后端（待新建 linux.ts）	❌ 未完成

Phase 1-2 完成后 macOS + Windows 可用。Phase 3（Linux 后端）需要新建 packages/@ant/computer-use-input/src/backends/linux.ts（~150 行）和 packages/@ant/computer-use-swift/src/backends/linux.ts（~200 行），并在对应 dispatcher 中加 case 'linux'。