Open Computer Use 架构总览图解：MCP stdio、app agent 与 9 个 Computer Use 工具的 5 层运行模型

Open Computer Use 架构总览图解：MCP stdio、app agent 与 9 个 Computer Use 工具的 5 层运行模型

【免费下载链接】open-codex-computer-use👾 Open Computer Use – Open-Source Alternative to Codex Computer Use项目地址: https://gitcode.com/gh_mirrors/op/open-codex-computer-use

Open Computer Use（open-computer-use）是一个开源的 Computer Use 服务：它以MCP stdio协议对外暴露一个 MCP server，让任意 AI agent 都能驱动 macOS、Windows 和 Linux 上的桌面应用。整套系统围绕 9 个原生 Computer Use 工具构建，运行在由app agent支撑的 5 层模型上。下面用图解方式带你快速看懂它的架构。

🗺️ 架构全景：5 层运行模型一览

Open Computer Use 的主线是 Swift 实现的 macOS automation MCP server，其运行逻辑清晰地分成 5 层（跨平台的 Windows / Linux runtime 在第 5 层之外作为扩展分支）。官方架构文档 docs/ARCHITECTURE.md 对每一层都有完整描述：

① App Mode 层：为什么需要一个隐藏的 app agent

在 macOS 上，Automation 能力（Accessibility、屏幕录制）必须挂在.appbundle 的权限身份下才能稳定工作。因此 Open Computer Use 做了一个聪明的设计：

• 你从终端执行open-computer-use mcp、call或snapshot时，CLI 会通过 LaunchServices 拉起同一个Open Computer Use.app的隐藏 app agent（无 Dock 图标）；
• CLI 与 agent 之间通过用户临时目录下的Unix domain socket转发请求，真正调用 Accessibility 和 ScreenCaptureKit 的进程始终是.app本体；
• 只有缺失权限时，才会弹出PermissionOnboardingApp权限引导窗口，一次性授予 Accessibility 与 Screen Recording 后自动关闭。

这套代理逻辑集中在 apps/OpenComputerUse/Sources/OpenComputerUse/MacOSAppAgentProxy.swift，嵌入式宿主还可以通过 AppAgentSocketNamespace.swift 设置私有 socket 命名空间，避免多个实例共用同一个 agent。

② MCP 层：stdio 传输与 6 个 JSON-RPC 方法

面向 MCP host 的外部 transport 保持最朴素的stdio：一行一个 JSON-RPC message，无端口、无鉴权复杂化，任何支持 stdio 的 MCP client 即插即用。

StdioMCPServer当前支持的 method 非常克制，见 MCPServer.swift：

• initialize/notifications/initialized：握手与就绪；
• tools/list：返回 9 个工具的 schema；
• tools/call：真正执行工具调用；
• ping：存活探测；
• notifications/turn-ended：开源版显式的回合边界钩子，收到后清理 visual cursor overlay。

值得一提的是initialize的 instructions 字段内置了一段“使用守则”（每回合先get_app_state、优先element_index而非坐标、破坏性操作前先询问用户），让不同 agent 接入时行为保持一致。

③ Tool Service 层：9 个 Computer Use 工具详解

这是整个架构的心脏。ToolDefinitions.swift 与官方 Codex Computer Use 的 9 个工具保持协议面对齐，可压缩为「发现 → 读状态 → 做动作」三段式：

几个对新手很关键的架构决策：

1. element_index是第一公民。get_app_state产出的 Accessibility 树是主导航面，截图只是补充——官方逆向文档 baseline-architecture.md 明确记录了这一判断，开源版沿用了它；
2. 非侵入优先。click/scroll/drag默认通过CGEvent.postToPid定向投递到目标进程，不移动用户真实鼠标；显式click_method=global才需要设置OPEN_COMPUTER_USE_ALLOW_GLOBAL_POINTER_FALLBACKS=1安全门（见 ComputerUseService.swift）；
3. JS REPL 扩展面。Codex plugin 的默认入口不是直接暴露 9 个工具，而是启动 open-computer-use-repl.mjs 这个 Node.js REPL，向模型只暴露js/js_reset两个入口，代码执行在 Worker 中，超时自动重建 session——协议细节记录在 docs/references/js-repl.md。

④ Fixture Bridge 层：让架构可以被测试

没有可复现的测试，自动化架构就是空中楼阁。Open Computer Use 用一个本地 fixture app（apps/OpenComputerUseFixture）承载可预测的点击/输入目标，FixtureBridge通过显式 command 通道对接；端到端的 OpenComputerUseSmokeSuite 会真实拉起 MCP server 并 JSON-RPC 调用全部 9 个工具。这条链路只服务确定性冒烟测试，不代表对第三方 app 的能力边界。

⑤ Cursor Lab 层：把“光标会动”做成科学

视觉光标是 Computer Use 最有辨识度的体验。为了让主 runtime 不被实验噪音污染，项目刻意隔离出两个独立 lab：

• StandaloneCursor：直接复用 Python 逆向脚本收敛出的 20 条候选路径 + spring 时间线；
• CursorMotion：heading-driven 的direct / turn / brake / orbit候选族 + 独立 visual dynamics 的调参实验场。

两者都不接真实 tool call，也不回写主SoftwareCursorOverlay。主 runtime 最终采纳的是 reverse-engineering 约束下的双层模型——“路径层给目标点、visual dynamics 层给可见姿态”，详见 SoftwareCursorOverlay.swift 与运动模型文档 software-cursor-motion-model.md。

🌍 跨平台扩展：Windows 与 Linux 如何复用同一套 9 工具

5 层模型之外，Open Computer Use 还有两条平行的 runtime 分支，协议面与 macOS 完全一致：

• Windows（apps/OpenComputerUseWindows/main.go）：Go 二进制内嵌 PowerShell 的System.Windows.Automationbridge，UIA pattern 优先、Win32 message 兜底，sky_click等 macOS 专属路径会明确返回 unsupported；
• Linux（apps/OpenComputerUseLinux/main.go）：Go 二进制内嵌 Python 的 AT-SPI2 bridge，元素语义动作优先、事件合成兜底，两者都支持max_tree_nodes/max_tree_depth相同的树预算。

两者的click_method映射关系（accessibility→ UIA / AT-SPI 语义动作，app_post→ HWND 定向投递）都写在各自执行计划里：windows-computer-use-runtime 与 linux-computer-use-runtime。

✅ 总结：这套架构好在哪里

1. 权限与能力分离：app agent 保证 Automation 跑在正确的权限身份下，MCP stdio 层保持对任意 client 的开放性；
2. 小内核 + 大对齐：只保留 9 个工具的极简 automation kernel，schema 与官方 Computer Use 对齐，迁移成本低；
3. 实验与产品隔离：Cursor Lab 与主 runtime 解耦，运动模型可以大胆迭代；
4. 可测试性内建：Fixture Bridge + smoke suite 让 5 层链路每次改动都有确定性回归。

想深入某一层，建议从 docs/ARCHITECTURE.md 的「运行分层」章节入手，配合 docs/references/ 下的逆向分析文档阅读。

【免费下载链接】open-codex-computer-use👾 Open Computer Use – Open-Source Alternative to Codex Computer Use项目地址: https://gitcode.com/gh_mirrors/op/open-codex-computer-use