CuaBot 多玩家计算机使用实战：用 Xpra 沙箱让多个 Agent 与人类共享同一桌面

CuaBot 多玩家计算机使用实战用 Xpra 沙箱让多个 Agent 与人类共享同一桌面【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua导读本文围绕 Cua 开源仓库中的 CuaBot 模块深入讲解多玩家计算机使用Multi-Player Computer-Use这一核心设计每个编程 AgentClaude Code、Gemini CLI、Codex、Aider、OpenClaw 等在自己的 Docker 沙箱内获得独立桌面、独立彩色光标与独立窗口管理而人类用户仍可随时在自己的宿主桌面上与这些 Agent 窗口交互。读完本文你将掌握 CuaBot 的容器 Xpra 流式窗口 hairpin 回环容器→宿主→容器的完整架构、多会话并行启动方法、computer-use MCP 工具全集以及 OpenClaw 的集成方式。CuaBot 界面截图从独占桌面到多玩家桌面为什么要重写计算机使用的交互模型传统计算机使用Computer-UseAgent 有一个根深蒂固的前提操作系统只有一个光标、一个键盘焦点、一个活动窗口——这套假设可以追溯到 Xerox PARC 时代。当 Agent 接管桌面时你的输入与 Agent 的输入互相冲突你只能等它跑完才能重新使用自己的电脑。CuaBot 试图打破这个假设其核心理念是多玩家Agent 和人类各自拥有自己的光标、自己的键盘焦点、自己的窗口管理全部共存于同一块屏幕上。这来自 Cua 社区的高频需求——用户希望把 cua-computer-server 直接跑在宿主机器上让 Agent 操作真实桌面但代价是 Agent 一运行你的屏幕就被接管。CuaBot 给出的答案是不把 Agent 放进你的桌面而是为每个 Agent 建一个独立桌面再以流式窗口的形式借给你看。该方案的设计取向在仓库文档中也有体现CuaBot 的定位是给任何编码 Agent 提供协作式计算机使用能力见 libs/cuabot/README.md它把 computer-use 视为通用 Agent 系统中的一件工具而不是独立的屏幕接管程序。核心架构容器 Xpra 流式窗口 hairpin 回环CuaBot 的运行链路由三层组成1. Docker 容器内的 X11 桌面CuaBot 启动一个 Docker 容器镜像trycua/cuabot:latest内部运行完整的 X11 Linux 桌面。容器入口脚本 entrypoint.sh 会先拉起 dbus 会话再以 seamless无缝模式启动 Xpradbus-daemon --session --fork --addressunix:path/tmp/dbus-session exec xpra seamless :100 --sharingyes --no-daemon --bind-tcp0.0.0.0:10000 --htmlon --dpi96这里:100是容器内的显示编号--sharingyes开启共享会话这是多玩家得以成立的前提之一--htmlon启用 Xpra 的 HTML5 客户端端点端口 10000 通过-p hostPort:10000映射到宿主。2. 宿主上的 cuabotd 服务宿主机上运行着一个名为cuabotd的 Node.js HTTP/WebSocket 服务默认端口 7842见 cuabotd.ts。它负责检查 Docker 连接、拉取镜像、创建并启动容器维护宿主上的 Xpra 客户端进程把容器内应用窗口附着attach到宿主桌面暴露一组计算机使用 API截图、点击、输入、滚轮、按键、拖拽等供容器内的 MCP 服务器调用维护多会话状态每个命名会话有独立的 PID 文件、端口文件与容器名。创建容器时注入的关键环境变量见ensureContainer逻辑环境变量值作用DISPLAY:100容器内 X 显示编号CUABOT_HOSThttp://host.docker.internal:serverPort容器内 MCP 服务器回连宿主 cuabotd 的地址CUABOT_TELEMETRYtrue/false使用遥测开关CUABOT_NAME/CUABOT_COLOR会话名 / 派生颜色用于 overlay 光标与窗口标识3. hairpin 回环容器 → 宿主 → 容器这是 CuaBot 最巧妙的设计。当容器内的 Agent 调用screenshot()或click(x, y)时请求链路如下容器内 Agent → computer-use MCP 服务器FastMCP运行在容器内 → HTTP POST 到 CUABOT_HOST即宿主上的 cuabotd → cuabotd 驱动 Playwright 控制的 headless Chromium → Chromium 打开 Xpra HTML5 客户端页面http://localhost:containerPort/?stealnosharingyes → 操作经 WebSocket 回传容器内的 X11 服务器这条容器 → 宿主 → 容器的路径被作者称为hairpin发夹。它虽然多绕了一圈却干净利落地把 Agent 的显示服务器与宿主操作系统隔离开来——这正是多玩家能够成立的根本原因Agent 的桌面是容器里的虚拟桌面宿主桌面永远是人类的。从代码可以印证这一点cuabotd.ts 中的ensurePlaywrightConnected()会launchPlaywright()启动chromium.launch({ headless: true })然后page.goto(http://localhost:{containerPort}/?stealnosharingyes)并轮询页面中是否出现canvas来判断 Xpra HTML5 是否就绪。多玩家并行 Agent、独立光标、独立窗口由于每个 Agent 运行在自己的容器、自己的 Xpra 实例中并行启动多个 Agent 是天然支持的cuabot claude # 第一个 AgentClaude Code cuabot gemini -n second # 第二个 AgentGemini CLI命名会话 second-n, --name name是 cuabot.tsx 中解析的会话名参数parseSessionName支持--name/-n两种写法。命名会话在源码中有完整的隔离机制容器名变为cuabot-xpra-session默认是cuabot-xpra服务 PID 文件与端口文件分别变为server.session.pid与server.session.port存放在~/.cuabot下端口自动避让findAvailableServerPort会从首选端口开始向上寻找可用端口Docker 映射端口也通过findAvailablePort扫描docker ps已占用端口来避让。每个 Agent 因此拥有自己的桌面独立容器 独立 Xpra display自己的光标颜色由会话名经 utils.ts 的nameToColor()用哈希 黄金比例0.618033988749895生成饱和度为 0.7、亮度 0.5保证不同会话颜色差异明显自己的窗口集合Xpra 以 seamless 模式把每个应用窗口作为宿主上的原生窗口展示并带彩色边框与独立托盘图标。Overlay 光标Agent 在哪里操作一目了然为了让人类能看到 Agent 当前的操作位置容器内运行着一个透明的浮动光标指示器 overlay-cursor.py。它是一个无边框、无任务栏、点击穿透input_shape_combine_region设为空区域的 GTK 弹窗会按会话名渲染指定颜色的光标图标cursor.png按颜色着色用带重力与风力扰动的路径算法模拟类人鼠标移动轨迹generate_path中gravity9.0、wind3.0、max_v15.0空闲 15 秒后开始 1 秒淡出通过 Unix 域套接字/tmp/cuabot-overlay-cursor.sock接收宿主端命令move / click / masked / hide / quit。宿主的 cuabotd.ts 还会做光标遮挡掩码计算每 500ms 轮询一次宿主窗口列表get-windows对非 Xpra 窗口区域添加掩码、对 Xpra 窗口区域挖洞AABB 差集运算 合并当 Agent 光标落入宿主窗口之下时隐藏 overlay 光标避免画在用户自己的窗口上面——这是多玩家体验里很关键的细节。Xpra 客户端的附着参数宿主端 Xpra 客户端由 cuabotd 以 detached 方式拉起getXpraAttachArgs见 utils.tsxpra attach tcp://localhost:containerPort \ --splashno --notificationsno \ --borderauto,4 --sharingyes \ --tray-iconicon --window-iconicon \ --session-namecuabot (name)--sharingyes是关键它允许 Playwright 的 HTML5 客户端与宿主的原生 Xpra 客户端同时挂接同一个会话也就是Agent 在容器里干活、你在宿主上看/插话并行不悖的技术基础。剪贴板与音频会随 Xpra 会话自动同步。computer-use MCP 工具全集容器内通过 computer-use-mcp.pyFastMCP 实现自包含 uv 脚本向 Agent 暴露桌面自动化工具。它通过CUABOT_HOST环境变量回连宿主 cuabotd每个工具最终落到 cuabotd 的 HTTP handler 上MCP 工具参数对应 cuabotd 端点说明screenshotsave_path?POST /screenshot返回 JPEGscaleScreenshot会把长边缩到 ≤1280 并记录缩放比坐标自动换算回原屏幕坐标clickx, y, buttonleftPOST /click支持 left/right/middle同步驱动 overlay 光标移动并播放点击动画double_clickx, yPOST /doubleClick双击type_texttext, delay50POST /type按键间隔默认 50msmouse_movex, yPOST /mouseMove移动光标mouse_down/mouse_upx, y, buttonleftPOST /mouseDown/mouseUp按下/释放鼠标键scrollx, y, delta_x, delta_yPOST /scroll滚轮deltaY 负值向上key_down/key_up/key_presskeyPOST /keyDown/keyUp/keyPress组合键与快捷键如 Enter、Tab、Shift、Controldragfrom_x, from_y, to_x, to_yPOST /drag拖拽中间 10 步插值移动MCP 客户端CLI 侧对应的完整命令见 cuabot.tsx 的帮助文本cuabot --screenshot [path]、--click x y [button]、--doubleclick、--move、--mousedown、--mouseup、--drag x1 y1 x2 y2、--scroll x y dx dy、--type text、--key、--keydown、--keyup。此外还有服务管理命令--serve [port]、--stop、--status、--reset [all|sandbox|settings]以及任意命令执行cuabot --bash command和交互式 WebSocket shellws://localhost:port/?command...基于 node-pty 的docker exec -itPTY 会话支持 stdin 与窗口 resize。沙箱内的环境Agent 一进沙箱就拥有一套可用的开发环境。容器内的系统提示词见 SYSTEM.md操作系统Ubuntu 22.04拥有 sudo 权限运行时Node.js 22.x、Python 3.10、pip3、uvPython 包管理器可运行带内联依赖的自包含脚本预装工具chromium、agent-browser浏览器自动化 CLI、agent-deviceadb / Android 自动化、feh、claude-code、x11-apps预装 Python 库matplotlib、numpy、pandas、seaborn、plotly。容器入口还会在后台通过npx skills安装callstackincubator/agent-device与vercel-labs/agent-browser技能写入挂载到宿主的~/.claude目录见 entrypoint.sh使 Agent 具备浏览器与 Android 设备自动化能力。支持的 Agent 与 OpenClaw 集成CuaBot 的 Agent 注册表见 settings.ts开箱支持六种编码 AgentAgent ID名称启动命令claudeClaude Codeclaude --mcp-config /home/user/.mcp.json --append-system-prompt-file /home/user/CLAUDE.mdgeminiGemini CLInpx google/gemini-clicodexOpenAI CodexcodexaiderAideraideropenclawOpenClawopenclawvibeVibevibe注意 Claude 的特殊处理runAgent会为它显式传入--mcp-config /home/user/.mcp.json即预配置好的 computer-use MCP并追加系统提示词文件其他 Agent 则使用注册表中的命令直接启动。cuabot 任意命令还能在沙箱中运行任意 shell 命令。OpenClaw开箱即用的配合CuaBot 与 OpenClaw 的集成分两种形态沙箱内运行cuabot openclaw在 CuaBot 沙箱内启动 OpenClawcomputer-use MCP 已预先配置好。OpenClaw 拥有完整桌面环境窗口流式传输到宿主你的机器不受影响无需额外配置无沙箱注入cuabot --add-mcp openclaw可将 CuaBot 的 MCP 服务器注入到已有的 OpenClaw 安装中为未沙箱化的 OpenClaw 补上计算机使用能力。由于每个 Agent 独立成沙箱、各有光标你完全可以让一个 OpenClaw 实例处理任务 A、一个 Claude Code 实例处理任务 B——它们在各自的桌面里并行工作互不干扰。快速开始一条命令跑起来npx cuabot首次运行会进入引导流程onboarding.tsx交互式 TUI检查 Docker 连接、Xpra 客户端、Playwright Chromium 与 Docker 镜像缓存拉取容器镜像约 2GB把cuabot别名写入 shell 配置文件macOS 写.bash_profile/.zshrcLinux 写.bashrcWindows 写 PowerShell profile 并生成cuabot.cmd然后选择默认 Agent。之后直接输入cuabot即可启动默认 Agent。运行前提Node.js 18Docker DesktopmacOS / Windows或 Docker 守护进程LinuxXpra 客户端macOS 需安装到/Applications/Xpra.app注意检查com.apple.quarantine隔离属性被隔离时需sudo xattr -c /Applications/Xpra.appWindows 在C:\Program Files\Xpra\xpra_cmd.exeLinux 通过apt install xpra或brew install xpra见 utils.ts 的XPRA_PATHS与依赖检查逻辑。依赖检查不通过时会给出明确指引例如Docker 未安装 / 未运行 → 提示安装并启动 Docker DesktopXpra 缺失 → 按平台给出安装命令Playwright Chromium 缺失 →npx playwright install chromium镜像未拉取 →docker pull trycua/cuabot:latest。服务日志写入~/.cuabot/server.log如需彻底重置可执行cuabot --reset all移除容器、镜像与~/.cuabot配置。多玩家进阶把多个 Agent 与你自己编排到同一屏综合以上机制一个典型的多玩家工作流是# 终端 1默认会话跑 Claude Code cuabot claude # 终端 2命名会话跑 Gemini CLI独立容器、独立光标颜色 cuabot gemini -n second # 终端 3随时查看两个会话的服务状态 cuabot --status cuabot --status -n second运行后你的宿主桌面上会看到两组带彩色边框的原生窗口一组属于 Claude默认颜色一组属于 Geminisecond会话派生颜色。你可以直接点击任意一组的窗口输入内容、切回自己的工作窗口继续干活Agent 不会因为你的操作而中断。若启用了遥测首次引导时可配置cuabotd 会记录 CLI 调用、MCP 工具调用等事件并在停止时刷新数据。未来方向按照发布文档的规划CuaBot 后续将推进macOS VM 支持借助 Lume为需要 macOS 原生应用的 Agent 提供沙箱化 macOS 环境跨沙箱的多 Agent 编排在多个沙箱之上统一调度任务沙箱上的 RL 训练环境以沙箱为底座构建 gym 风格的评估循环用于训练计算机使用模型。这些方向与 Cua 生态中计算机使用基础设施如 Lume、cua-sandbox、cua-bench 等模块一脉相承读者可在仓库中继续深入。小结CuaBot 用每人一个桌面取代大家抢一个桌面Docker 容器隔离出独立 X11 桌面Xpra seamless 会话把应用窗口流式呈现到宿主hairpin 回环让 Agent 的输入经由宿主 Playwright 回流容器而 overlay 光标与窗口掩码让谁在操作哪里一目了然。无论你用的是 Claude Code、Gemini CLI、Codex、Aider 还是 OpenClaw只需npx cuabot即可在保住自己机器使用权的同时让任意多个 Agent 与你共享同一块屏幕并行工作。【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考