open-computer-use

Open Computer Use

概述

Open Computer Use 将 Computer Use 提供为本地 CLI 和 stdio MCP 服务。它并非专为 Codex.app 设计；请根据你所使用的 Agent 运行时调整命令和 MCP 配置。

macOS 运行时要求 macOS 14.0 或更高版本。Windows 和 Linux 使用各自的平台运行时，不受此 macOS 最低版本要求限制。

macOS、Linux 和 Windows 均支持相同的核心工具集： list_apps、get_app_state、click、perform_secondary_action、scroll、 drag、type_text、press_key 和 set_value。

macOS 运行时还实现了 select_text，可在文本元素中选中指定文本，或将文本光标放在指定文本之前／之后（selection：text、cursor_before、 cursor_after）。请传入与无障碍树中完全一致的 text，并在文本不唯一时提供 prefix／ suffix；如果目标不明确，操作会安全失败，而不会悄悄选中第一个匹配项。JavaScript 提供 app.selectText(elementIndex, text, options?)。范围验证无法读取或不匹配时会抛出异常，包括关闭完整操作回读的情况。Windows 和 Linux 运行时目前尚未实现此工具。

macOS 还提供 query：一种定向的无障碍查询，可按文本和／或角色查找控件，无需渲染树或截取屏幕截图。

核心工作流

1. 在 macOS 上，调用 CLI 前运行 sw_vers -productVersion，并确认 macOS 版本为 14.0 或更高。对于较旧版本，请说明运行时无法启动；不要建议通过 doctor 或更改权限来解决二进制兼容性问题。
2. 使用 open-computer-use -h 或 ocu -h 检查是否已安装 CLI。如果尚未安装或未完成设置，请阅读 references/installation.md。
3. 在受支持的 macOS 版本上，首次执行实际 GUI 任务前运行 open-computer-use doctor。如果缺少权限，请让用户在引导界面中批准“辅助功能”和“屏幕录制”权限。
4. 操作前检查可用应用：open-computer-use call list_apps。
5. 使用 open-computer-use call get_app_state --args '{"app":"TextEdit"}' 获取当前 UI 状态。默认状态通常足以用于 UI 操作。
6. 当任务需要较长的语义文本，例如聊天记录、电子邮件正文、文档文本或长篇内容时，使用 text_limit: 1000 或 text_limit: "max" 调用 get_app_state。
7. 如果滚动后可见的长页面或列表仍不完整，请使用更大的 max_tree_nodes 或 max_tree_depth 调用 get_app_state。
8. 优先使用元素定向操作，并使用最新 get_app_state 结果中的 element_index。
9. 对于多步 CLI 操作，请使用 open-computer-use call --calls '<json-array>'，这样同一进程便可复用最新的元素索引映射。
10. 对于支持本地 MCP 服务的 Agent 运行时，请配置 open-computer-use mcp 或 ocu mcp，并直接调用公开的 Computer Use 工具。请阅读 references/usage.md。
11. 对于直接以代码为先的编排，请运行 ocu capabilities，然后使用一次性 ocu js 或持久运行的 ocu repl。请阅读 references/usage.md。
12. 如果通信、权限或桌面会话访问失败，请阅读 references/troubleshooting.md。

操作规则

• 将目标桌面视为用户的真实会话。除非用户明确要求执行相关任务，否则不要检查密码管理器、无关的私人内容或敏感应用。
• 发送、删除、购买、批准、上传或进行其他对外可见的更改前，先征求用户同意。
• 不要假定 Codex.app 插件辅助工具可用。请使用已安装的 open-computer-use / ocu CLI，或使用显式的 MCP 配置。
• 在同一个原生会话中使用 get_app_state 或 macOS query 返回的索引；不要跨会话或在 UI 发生重大变化后猜测索引。
• 优先使用语义操作和 set_value 操作可编辑控件。只有当元素树未提供更安全的目标时，才使用坐标执行 click、scroll 和 drag。
• 在 macOS 上，除非用户明确要求 click_method: "global"、要求通过 drag 驱动窗口服务器拖动会话（移动窗口、拖选文本、Finder 拖放），或要求执行可能移动真实指针的其他诊断操作，否则不要启用 OPEN_COMPUTER_USE_ALLOW_GLOBAL_POINTER_FALLBACKS=1。未启用时，drag 会报告 Drag delivered via app_post，且这些操作不会生效；替代方案请参阅 references/usage.md。
• 在 Windows 和 Linux 上，先确认命令是在已登录的桌面会话中运行，再假定 GUI 自动化可用。

常用 CLI 操作

open-computer-use -h
ocu -h
ocu capabilities --json
ocu js 'nodeRepl.write(6 * 7)'
ocu repl
open-computer-use doctor
open-computer-use call list_apps
ocu call list_apps
open-computer-use call get_app_state --args '{"app":"TextEdit"}'
open-computer-use call get_app_state --args '{"app":"TextEdit","text_limit":1000}'
open-computer-use call get_app_state --args '{"app":"TextEdit","text_limit":"max"}'
open-computer-use call get_app_state --args '{"app":"Google Chrome","max_tree_nodes":3000,"max_tree_depth":96}'
open-computer-use call click --args '{"app":"TextEdit","element_index":"0"}'
open-computer-use call type_text --args '{"app":"TextEdit","text":"Hello from Open Computer Use"}'

如需在一个进程中复用状态执行一系列简短操作：

open-computer-use call --calls '[
  {"tool":"get_app_state","args":{"app":"TextEdit"}},
  {"tool":"press_key","args":{"app":"TextEdit","key":"Return"}}
]'

MCP 用法

对于能够通过 stdio 启动本地 MCP 服务的运行时，请使用：

[mcp_servers.open_computer_use]
command = "open-computer-use"
args = ["mcp"]

请阅读 references/usage.md，了解 JSON 配置示例、直接调用工具的模式和平台说明。

参考资料

• references/installation.md：一次性 CLI 安装、Agent MCP 安装命令和 macOS 权限。
• references/usage.md：MCP 配置、直接调用 CLI、操作顺序和平台行为。
• references/troubleshooting.md：权限、桌面会话、应用发现和操作失败问题。