👾 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
Linux Computer Use Runtime
目标
把 open-computer-use 从 macOS / Windows 扩展到 Linux 桌面,优先让同一组 9 个 Computer Use tools 能在 Ubuntu GNOME 桌面 session 里通过独立二进制跑通,并把 Linux 桌面自动化的能力边界记录清楚。
范围
- 包含:
- Linux 独立 runtime,不耦合 Swift
.app。 - Go CLI / MCP /
call --calls入口。 list_apps、get_app_state、click、perform_secondary_action、scroll、drag、type_text、press_key、set_value的功能性实现。- Linux arm64/amd64 构建脚本和基础 Go 单测。
- Ubuntu GNOME VM 上的 9-tool 实机 smoke。
- 架构文档、README、质量说明和 history。
- Linux 独立 runtime,不耦合 Swift
- 不包含:
- 替换 macOS Swift 主线。
- Linux installer、desktop entry、system package 或 code signing。
- visual cursor overlay。
- 完整 Linux fixture / 可重复 smoke runner。
背景
- 相关文档:
docs/ARCHITECTURE.mddocs/QUALITY_SCORE.mddocs/SECURITY.mddocs/RELIABILITY.md
- 相关代码路径:
apps/OpenComputerUseLinux/scripts/build-open-computer-use-linux.shscripts/ci.shapps/OpenComputerUseWindows/
- 已知约束:
- Linux 上最接近 macOS AX 的桌面接口是 AT-SPI2,经由 D-Bus 暴露 app/window/accessibility tree、actions、editable text 和 value 接口。
- Ubuntu GNOME 默认 Wayland session 下,任意后台坐标键鼠和截图都不是一套等价于 macOS AX 的通用模型。
- 第一版策略是 AT-SPI semantic action / editable text / value 优先,coordinate click / drag / key synthesis 仅作为 best-effort fallback。
- SSH tty 默认没有
XDG_RUNTIME_DIR/DBUS_SESSION_BUS_ADDRESS/ display 环境;runtime 会尝试为当前 Unix 用户自动发现已登录桌面 session,但跨用户 root 进程不应该被当作普通用户桌面的控制入口。
风险
- 风险:不同 toolkit 暴露的 AT-SPI tree 深度、role、action 名称差异大。
- 缓解方式:Linux bridge 单独放宽 tree traversal depth,并保留字段级容错。
- 风险:Wayland 下 screenshot 可能返回黑图或被 portal/ compositor 拒绝。
- 缓解方式:截图只做 best-effort;检测到全黑采样时不回传 image block,避免误导调用方。
- 风险:coordinate click / drag / key synthesis 可能影响当前 foreground context。
- 缓解方式:MCP instructions 和 README 明确写出 Linux background input boundary;优先使用 element-targeted AT-SPI action。
里程碑
- 确认 Linux 可用接口和边界。
- 完成 Linux Go runtime、Python AT-SPI bridge 和 9-tool 功能性实现。
- 完成本地单测、交叉编译和 Ubuntu GNOME VM 9-tool smoke。
- 后续补 Linux fixture、可重复 smoke runner、system package 和更稳定截图方案。
验证方式
- 命令:
(cd apps/OpenComputerUseLinux && go test ./...)./scripts/build-open-computer-use-linux.sh --arch arm64./scripts/build-open-computer-use-linux.sh --arch amd64open-computer-use mcpopen-computer-use call list_appsopen-computer-use call --calls-file <9-tool smoke json>
- 手工检查:
- 在 Ubuntu GNOME desktop session 里打开
gnome-text-editor。 - 运行
get_app_state -> set_value -> type_text -> press_key -> perform_secondary_action -> click -> scroll -> dragsequence。 - 确认每个 tool 返回
isError=false,并且 Text Editor 内容包含 marker。
- 在 Ubuntu GNOME desktop session 里打开
- 观测检查:
- 当前桌面用户缺少桌面环境变量时,runtime 应先尝试自动发现同用户 session env;如果找不到已登录 session,再返回明确错误,而不是误判为 AT-SPI 逻辑失败。
进度记录
- 确认 Ubuntu GNOME VM 有已登录
leoWayland session、AT-SPI bus、Python GI、Atspi、Gdk/GdkPixbuf。 - 新增
apps/OpenComputerUseLinux,用 Go 实现 CLI、MCP、tool schema、call --calls和 snapshot cache。 - 嵌入 Python AT-SPI bridge,实现 app/window discovery、tree rendering、semantic action、editable text、value、key/mouse fallback 和 best-effort screenshot。
- 新增 Linux arm64/amd64 构建脚本。
- 新增 Go 单测,并接入仓库基础 CI。
- 本地通过
(cd apps/OpenComputerUseLinux && go test ./...)。 - 本地通过
./scripts/build-open-computer-use-linux.sh --arch arm64和--arch amd64。 - 上传 arm64 二进制到 Ubuntu VM,验证
--version为0.1.33。 - 在 Ubuntu VM 中验证
call list_apps返回isError=false并包含gnome-text-editor。 - 在 Ubuntu VM 中验证 MCP
initialize/tools/list,tool count 为 9。 - 在 Ubuntu VM 中验证 8-tool sequence:
get_app_state、set_value、type_text、press_key、perform_secondary_action、click、scroll、drag均isError=false。 - 在 Ubuntu VM 中验证
0.1.36预发布二进制可在leo用户env -i下自动发现 session env,并跑通 MCPtools/list、tools/call(list_apps)和 9-tool sequence。 - 在 Ubuntu VM 中验证
npm i -g [email protected]后,npm launcher 选择 Linux arm64 binary,codex mcp list显示open-computer-use mcpenabled,raw MCPtools/list返回 9 个 tools,call list_apps返回isError=false。 - 扩展 Linux fixture 和可重复 smoke runner 到完整 9-tool sequence(已有动作回读的隔离 GTK / Xvfb smoke,见
docs/linux-action-read-back.md)。 - 评估 xdg-desktop-portal / compositor-specific screenshot 路径,补非黑图 capture。
- 将 Linux artifact 接入 npm release packaging,作为既有 npm root/alias packages 的 bundled artifacts 分发。
- 评估用原生 Go D-Bus/libatspi 替换 Python GI bridge 的收益和风险。
决策记录
- 2026-04-22:Linux runtime 不复用 Swift
.app或 Windows.exebridge,采用独立 Go binary,避免把 macOS / Windows 的权限和输入模型强行带到 Linux。 - 2026-04-22:第一版用 Go 管协议、状态和分发边界,用嵌入式 Python GI 调 AT-SPI/GDK,优先完成 9-tool 功能性闭环。
- 2026-04-22:Linux 默认使用 AT-SPI semantic action / editable text / value;coordinate mouse、drag、keyboard synthesis 作为 best-effort fallback,并在 MCP instructions 中明确不是通用 Wayland background input。
- 2026-04-22:GNOME Text Editor 的 AT-SPI tree 深度超过 Windows runtime 沿用的 16 层,Linux bridge 单独把 traversal depth 放宽到 64。
- 2026-04-22:GNOME Wayland 下 GDK root capture 在 VM 上返回黑图;Linux bridge 检测全黑采样后省略 image block,后续再评估 portal/compositor-specific capture。
- 2026-04-23:Linux release artifact 接入 npm package bundled artifacts,不新增系统 installer;root
open-computer-usepackage 通过 launcher 按linux-arm64/linux-x64自动选择 binary。 - 2026-04-23:Linux runtime 不把 session env 写入 Codex config 或 shell profile;Go runtime 在每次启动 Python AT-SPI bridge 前为当前 Unix 用户动态发现
/run/user/<uid>、session bus、Wayland / X11 display 和 AT-SPI 相关环境。