open-computer-use

开放式计算机使用

概览

Open 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。

核心工作流

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，并直接调用公开的计算机使用工具。请阅读 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。
• 使用 element_index 前，始终先运行 get_app_state；不要跨会话或在 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：权限、桌面会话、应用发现和操作失败。