👾 Open Computer Use – Open-Source Alternative to Codex Computer Use
Swift accessibilityai-agentai-agentsclaude-codecodexcodex-computer-usecomputer-usecomputer-use-agentcross-platformcuadesktop-automationgemini-cligui-automationmacosmcpmodel-context-protocolopen-computer-useopen-computer-use-mcpopenai-codexopencode
Official Tool Alignment
目标
把仓库内 open-computer-use 暴露给 MCP host 的 9 个 tools,按当前官方 computer-use 的真实 tools/list 和 tools/call 返回做一轮收口:尽量对齐 description、schema、annotations、错误语义、list_apps 列表形态,以及 get_app_state / action tool 的文本输出风格。
范围
- 包含:
- 用
scripts/computer-use-cli实测官方tools/list与代表性tools/call。 - 收敛 9 个 tools 的 description、input schema 和 annotations。
- 让
list_apps输出更接近官方的“运行中 + 近 14 天使用过 app”视图。 - 调整
get_app_state/ action tool 文本渲染,减少内部实现细节,靠近官方树形输出。 - 同步架构文档、history 和必要测试。
- 用
- 不包含:
- 当前阶段不承诺 100% 复刻官方闭源安全策略、session approval、overlay UI 或私有 host 集成。
- 当前阶段不把一次性本机样本抽成完整自动化 diff 平台。
背景
- 相关文档:
docs/ARCHITECTURE.mddocs/references/codex-computer-use-cli.mddocs/references/codex-local-runtime-logs.mddocs/references/codex-computer-use-reverse-engineering/tool-call-samples-2026-04-17.md
- 相关代码路径:
packages/OpenComputerUseKit/Sources/OpenComputerUseKit/ToolDefinitions.swiftpackages/OpenComputerUseKit/Sources/OpenComputerUseKit/AppDiscovery.swiftpackages/OpenComputerUseKit/Sources/OpenComputerUseKit/AccessibilitySnapshot.swiftpackages/OpenComputerUseKit/Sources/OpenComputerUseKit/ComputerUseService.swiftpackages/OpenComputerUseKit/Sources/OpenComputerUseKit/MCPServer.swift
- 已知约束:
- 官方
computer-use只能稳定通过codex app-server间接调用,不能假设普通 stdio client 可直连。 - 官方
list_apps的uses数值最终确认来自系统 Spotlight metadata(kMDItemUseCount/kMDItemLastUsedDate_Ranking),而不是此前猜测的Knowledge/knowledgeC.db。 - Accessibility 树和索引分配高度依赖宿主 app 与 AX 层结构,完全一致需要做裁剪和抽象,而不是原样暴露本地 AX 全量细节。
- 官方
风险
- 风险:只对齐 schema,不对齐结果文本,host 仍会看到明显不同的树结构和错误语义。
- 缓解方式:同一轮内连带调整
list_apps、get_app_state和 tool error payload。
- 缓解方式:同一轮内连带调整
- 风险:过度裁剪 AX 树导致现有 smoke path 或 action tool 命中能力退化。
- 缓解方式:保留底层 element map,只收口用户可见文本;行为命中继续依赖内部全量 snapshot。
- 风险:
list_apps引入新的系统数据源后,在某些机器上查不到 usage 数据。- 缓解方式:做只读、可失败的回退;查不到时仍返回运行中 app。
里程碑
- 官方 surface 与差异点实测确认。
- schema、错误语义、
list_apps、state rendering 收口。 - 双链路复测、文档同步和归档。
验证方式
- 命令:
swift testgo run . list-tools --transport app-servergo run . list-tools --transport direct --server-bin ../../.build/debug/OpenComputerUsego run . call list_apps --transport direct --server-bin ../../.build/debug/OpenComputerUse
- 手工检查:
- 官方与开源
tools/list的 9 个 tool surface 能一眼对齐。 - 官方 bundled
computer-use的 raw app-server helper 当前只用于tools/list探测;真实 tool call 走正常 Codex agent/tool 调用链或本仓库 direct server。 get_app_state文本不再暴露_NS:内部 identifier、frame 噪音和过量 cell 递归。appNotFound、安全拒绝等错误形态与官方一致地回到content+isError: true。
- 官方与开源
- 观测检查:
list_apps输出包含running、last-used、uses,且顺序接近官方。- 代表性 action tool 返回继续附带状态文本和截图。
进度记录
- 里程碑 1
- 里程碑 2
- 里程碑 3
决策记录
- 2026-04-17:本轮对齐以
computer-use-cli实测官方返回为准,而不是继续基于先前推测维护“近似文案”。 - 2026-04-17:
list_apps改为优先使用 Spotlight metadata query,按官方同源的kMDItemUseCount/kMDItemLastUsedDate_Ranking排序和筛选 app;运行态 app 继续由NSWorkspace合并补齐。 - 2026-04-17:对 bundle-id 直传的高风险 app 增加官方风格 safety denial,并让名称匹配路径默认不解析到这些 app,复刻官方
appNotFound("iTerm2")/not allowed to use the app 'com.googlecode.iterm2'的边界行为。 - 2026-04-17:直接 MCP tool
content[0].text的当前官方基线应从App=<bundle-id> (pid ...)起头,不再把Computer Use state (CUA App Version: 750)/<app_state>这层旧包裹当作响应文本的一部分。 - 2026-05-07:Issue #12 暴露出 Chrome 被内置 denylist 阻止的问题。回看本计划和 reverse-engineering 样本后,只能确认官方对 iTerm2 的安全拒绝;Chrome 只出现在
list_apps样本里,没有被拒绝的实测证据。随后按产品判断将内置 denylist 收缩到密码管理器,终端、Chrome / Atlas 和系统组件不再属于内置阻止目标,后续敏感 app 策略交给 session approval / policy 设计。