Qwen CUA Driverqwen-code 内置的跨平台桌面与浏览器自动化原生运行时【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-codeQwen CUA Driver 是 qwen-code 项目内 vendored随仓库分发的跨平台 Cua Driver 运行时为 AI 智能体提供原生桌面与浏览器自动化能力统一通过 MCPModel Context Protocol、一次性 CLI 以及进程内 Python / TypeScript SDK 三种方式暴露。本文以packages/cua-driver/下的文档与源码为准完整介绍其安装、Agent 集成、权限模型、归一化坐标、遥测边界与 SDK 使用方式帮助你快速把桌面自动化能力接入自己的 Agent 或桌面应用。定位与来源vendored 分发与 Qwen 差异packages/cua-driver/是 qwen-code 对上游cua-driver-rs的 vendored 分发。其上游快照记录在 packages/cua-driver/.vendored-fromcua-driver-rs-v0.20.0Qwen 自有的差异则在 packages/cua-driver/.vendored-patches.md 与 packages/cua-driver/docs/relative-coordinates-design.md 中归档。.vendored-patches.md说明了本仓库的补丁策略vendored 副本基于 0.20.0 快照外加少量以普通 commit 形式叠加的上游 trycua/cua PR。当前活跃补丁仅有一项list_windows需包含空标题/空标题的顶层窗口影响platform-windowscrate。历史上被 0.7.0、0.17.0 吸收并退役的补丁如 X11 合成点击误报成功、start_session复活闲置回收会话、daemon socket 写入EAGAIN/EWOULDBLOCK重试也一一登记在案。升级上游 ref 时scripts/sync-from-upstream.sh会比对.vendored-from到新 ref 的差异若某 PR 已合入新基线则冲突解决后需将对应行从活跃补丁表移除。安装与产品身份正式发布的 Qwen CUA Driver 在各平台均使用 Qwen 自有身份标识项目发布版标识可执行文件qwen-cua-driver/qwen-cua-driver.exemacOS App/Applications/QwenCuaDriver.appBundle IDcom.qwencode.cua-driver状态目录~/.cua-driverWindows 计划任务qwen-cua-driver-serve源码构建则安装为独立的qwen-cua-driver-local产品与上游 CuaDriver 的可执行文件、App、服务、本地构建身份完全隔离。注意正式发布版的状态目录统一为~/.cua-driver为兼容既有 Qwen 版本因此同一用户不建议同时安装两个发布版发行物它们可能共享或互相覆盖该状态目录。macOS / Linux 安装仓库内置的安装脚本位于 packages/cua-driver/scripts/install.sh通过CUA_DRIVER_RS_VERSION指定版本后执行CUA_DRIVER_RS_VERSION0.20.6 \ bash packages/cua-driver/scripts/install.sh安装完成后应得到qwen-cua-driver 0.20.6。脚本系列还包括install-local.sh/install-local.ps1构建当前 checkout 为qwen-cua-driver-local产品、uninstall.sh/uninstall.ps1移除已装驱动以及uninstall-local.sh/uninstall-local.ps1仅移除源码构建产品其职责对照见 packages/cua-driver/scripts/README.md。Windows 安装Windows 使用 PowerShell 安装脚本 packages/cua-driver/scripts/install.ps1$env:CUA_DRIVER_RS_VERSION 0.20.6 powershell -ExecutionPolicy Bypass -File packages/cua-driver/scripts/install.ps1Agent 集成MCP 与 CLI驱动以 MCP server 的形式直接运行qwen-cua-driver mcp注册到 qwen-codeqwen mcp add cua-driver qwen-cua-driver mcp注册完成后Agent 便可通过 MCP 工具调用桌面与浏览器自动化能力。其他支持 MCP 的客户端可以使用相同的可执行文件与参数面向 shell 的自动化场景也可以通过qwen-cua-driver call直接调用工具而不经过 MCP 通道。0.20 运行时与 SDK 表面0.20 基线包含以下能力SDK 自有的运行时与版本化 C ABI声明于 packages/cua-driver/rust/include/cua_driver_abi.h由 UniFFI 生成的 Python 与 TypeScript 绑定类型化浏览器自动化、权限模式、运行时自有 consent 适配器传输层自有的隐式生命周期会话implicit lifecycle sessions按动作per-action的目标选择、跨权限 profile 的能力清单capability manifests绑定于快照的元素令牌snapshot-bound element tokens、封闭的动作结果closed action resultsverify_state状态验证、前台焦点验证、原生菜单与剪贴板操作、窗口取景window framing、语义光标主题其中值得注意的变化是浏览器批准令牌approval tokens已被退役对既有 profile 的访问现在需要受信任的启动授权trusted launch grant、有界清单bounded manifest或嵌入宿主授权。Python 与 TypeScript 双 SDKPython 应用导入cua_driverTypeScript 应用导入 Qwen 自有的qwen-code/cua-sdknpm 包。两者共享同一个进程内原生运行时MCP 仍是面向 Agent 的边界由qwen-cua-driver实现。进程内 SDK 与 MCP 的契约层见 packages/cua-driver/contract/README.md其中记录的版本化兼容面如下字段当前值含义contract_version0.7.0生成的 manifest 与类型化 SDK 形状tools_list_schema_version1cua-drivertools/list扩展形状capability_version1可加性的能力令牌词汇表mcp_protocol_version2025-06-18提供给 Agent 运行时的 MCP 初始化协议契约覆盖跨平台会话生命周期工具start_session、get_session、list_sessions、end_session、整桌面循环工具get_desktop_state、get_screen_size、get_cursor_position、move_cursor、set_window_frame、invoke_menu、click、drag、scroll、type_text、press_key、hotkey、clipboard_read、clipboard_write、会话光标切片与verify_state检查观察切片。会话契约标记为canonical_runtime同一份类型化 Rust 输入/输出声明同时构建线上 MCP 工具桌面契约标记为portable_subset是更丰富平台 schema 的刻意收窄投影。普通调用无需start_session运行时为认证的传输租约创建一个隐式会话直到传输关闭、显式结束或闲置五分钟才回收escalate_session与get_session_state仅为遗留兼容工具。TypeScript SDK 的使用示例见 packages/cua-driver/typescript/README.mdimport { CuaDriver, CursorReducedMotion, EndSessionInput, GetDesktopStateInput, SetAgentCursorThemeInput, StartSessionInput, } from qwen-code/cua-sdk const driver CuaDriver.create(undefined) // 同进程无需 daemon await driver.startSession( StartSessionInput.new({ session: demo }), ) try { await driver.setAgentCursorTheme( SetAgentCursorThemeInput.new({ session: demo, themeId: cua.default, reducedMotion: CursorReducedMotion.Auto, }), ) const desktop await driver.getDesktopState( GetDesktopStateInput.new({ session: demo }), ) console.log(desktop.images[0]?.mimeType) } finally { await driver.endSession(EndSessionInput.new({ session: demo })) await driver.shutdown() driver.uniffiDestroy() }要点qwen-code/cua-sdk的 postinstall 从同版本qwen-cua-driverGitHub Release 下载 SDK 原生库与 Node 运行时并对照该 Release 的checksums.txt校验归档它只缓存这两个文件不会安装驱动应用或 daemon。macOS 负载要求 macOS 13 及以上。Windows 发布负载静态链接 Microsoft C 运行时因此干净的 x64/ARM64 Windows 无需单独安装 VC Redistributable。SDK 不使用 WASM——UniFFI 将同一份 Rust daemon-client 实现分发给 Python 与 Node同时保留 daemon 的权限身份与运行时所有权。权限模式与授权生命周期驱动提供三种权限模式standard普通自动化的默认模式无提示bounded只允许已审核的工具与资源unrestricted必须显式传入--dangerously-bypass-approvals才能启用。权限模式属于拥有运行时的进程且在启动时固定qwen-cua-driver serve通过命令行参数接收而qwen-cua-driver mcp与嵌入宿主则使用配套的环境变量CUA_DRIVER_PERMISSION_MODECUA_DRIVER_CAPABILITY_MANIFEST_FILECUA_DRIVER_CAPABILITY_MANIFEST_APPROVED因此必须在启动 daemon 之前选定模式运行中的 daemon 必须重启才能变更模式。附着到已登录的 Chromium 既有 profile 仍须显式授权qwen-cua-driver mcp --grant existing-profile嵌入应用也可以实现DriverAuthorizationHost接口自行掌管权限提示与授权生命周期返回请求摘要的Allow/Deny/Cancel。TypeScript 侧通过CuaDriver.createConfiguredWithAuthorizationHost(options, host)构造带授权宿主的运行时另有createConfiguredWithActivityObserver内容无关的动作/拒绝/授权/会话事件观察者不能改变授权或工具结果以及同时需要两者的createConfiguredWithHostIntegrations。策略文件YAML 与 Rego在 daemon 上设置CUA_DRIVER_POLICY_FILE可对来自 MCP 与 CLI 客户端的全部工具调用实施 deny-by-default 策略见 packages/cua-driver/rust/README.md。未设置或路径不存在时保持向后兼容、不做策略执行。支持三类路径.yaml/.yml单个 YAML 策略文件.rego单个 Rego 策略文件目录按排序顺序加载全部顶层.rego文件。YAML 策略通过allow.tools放行无约束工具、allow.rules约束特定调用、deny.tools显式覆盖例如allow: tools: [screenshot, scroll, wait] rules: - tool: click constraints: x: { min: 0, max: 1920 } y: { min: 0, max: 1080 } - tool: type_text constraints: text: { max_length: 1000, pattern: ^[a-zA-Z0-9\\s]$ } - tool: launch_app constraints: app: allowed: [Calculator, TextEdit, Safari] deny: tools: [shell_execute, file_delete]Rego 策略必须暴露data.cua.policy.allow布尔规则输入形状为{ server: cua-driver, tool: name, arguments: object }由 daemon 内置的 Regorus 求值无需外部 OPA 服务。Qwen 归一化坐标0–1000 网格契约像素坐标仍是默认。设置以下环境变量可启用 0–1000 的归一化坐标网格export CUA_DRIVER_RS_COORDINATE_SPACE1 export CUA_DRIVER_RS_COORDINATE_SCALE1000 # 可选1000 为默认值该契约的详细设计见 packages/cua-driver/docs/relative-coordinates-design.md核心要点转换层位于cua-driver-core由ToolRegistry调用。ToolRegistry是 MCP、CLI、daemon、私有 worker、replay、直接 SDK 执行共享的规范授权与分发边界——只改某个 MCP handler 或 daemon 路由会让其他传输绕过契约这正是放置在共享边界的根本原因。归一化后的公开参数保留用于授权、consent、记录与动作证据私有副本在放行之后、平台分发之前才转为像素转换公式为pixel round(normalized / scale * dimension)。坐标基准coordinate bases按作用域区分窗口局部动作使用对应(runtime, pid, window_id)最近的get_window_state快照尺寸桌面级动作使用最近的get_desktop_state截图尺寸屏幕空间动作move_cursor、set_window_frame使用最近一次逻辑get_screen_size尺寸缩放图片动作使用对应缩放结果的缓存尺寸。所有可变基准按运行时私有作用域缓存公开的 session id 无法选择另一个运行时的缓存。缺失或过期的坐标基准会 fail closed——分发直接失败并请求先做一次对应的新鲜状态调用绝不会把归一化值当作字面像素猜测。覆盖输入包括click、double_click、right_click、drag、mouse_drag、mouse_button_down、mouse_button_up、zoom含from_zoom、scroll、type_text/press_key/hotkey的焦点坐标、parallel_mouse_drag、move_cursor、set_window_frame以及verify_state的窗口 bounds。浏览器 CSS 坐标刻意不归一化在归一化模式下browser_click与browser_pointer会拒绝原始 CSS 坐标字段并引导调用方使用新鲜的浏览器元素引用。tools/list描述仅在归一化模式激活时改写同一 scale 会出现在字段描述与 MCP 指令中像素模式保持上游 schema。查询结果与上游字节兼容——screenshot_width、screenshot_height、可访问性框架、窗口 bounds 与光标位置仍保留真实像素/点值改写为 1000 会在单个 payload 内制造自相矛盾的几何信息。模型可见 payload 过滤设置MCP_MODEL_PAYLOAD_FILTER1可过滤受影响的面向 Qwen 的文本型 MCP payload。该过滤同时覆盖文本与结构化内容但对二进制图片/媒体 payload 保持不透明opaque。它默认关闭且不改变直接 SDK 的契约。遥测边界Qwen 发行版中遥测默认关闭可通过显式命令或环境变量开启qwen-cua-driver telemetry enable或设置CUA_DRIVER_RS_TELEMETRY_ENABLED1。显式开启后事件按上游的内容无关content-freeschema 发送到 Cua 的 PostHog 端点不经过任何 Qwen 遥测服务或代理。常用命令qwen-cua-driver telemetry status # 查看生效决策 qwen-cua-driver telemetry disable # 关闭正常卸载会保留遥测偏好与伪匿名安装标识符Unix 上使用--purge、Windows 上设置CUA_DRIVER_RS_UNINSTALL_PURGE1可一并删除。发行安装器在要求已装二进制记录任何事件前也会先展示遥测通知。macOS 身份与 TCC 权限macOS 将辅助功能Accessibility与屏幕录制Screen Recording授权归属于负责的应用身份。因此应安装并向QwenCuaDriver.app授予权限已安装的 CLI 可通过该 App 自有的 daemon 代理访问。注意qwen-cua-driver mcp --direct刻意使用发起宿主进程的 TCC 归属不能替代经过认证的嵌入宿主生产环境不要向任意松散二进制路径授予权限签名且公证notarized的发布产物仅由 Qwen 自有发布流程产出。本地构建的稳定签名macOS 的辅助功能/屏幕录制授权绑定 App 的 designated requirement。临时ad-hoc签名使用cdhashrequirement每次重新构建都会变化因此其授权无法在下次本地安装后保留。安装器会报告已装 requirement 是certificate-backed还是ad-hoc cdhashad-hoc 安装总会打印醒目的警告与引导说明。需要稳定路径做行为或 E2E 验证时见 packages/cua-driver/scripts/README.mdbash packages/cua-driver/scripts/install-local.sh \ --release --autostart --require-stable-signingCUA_DRIVER_REQUIRE_STABLE_SIGNING1是等效的环境变量。严格模式在无可用证书背书身份时会在替换线上 App 之前停止。最可靠的非交互重建方式是使用专用钥匙串keychainSIGNING_KEYCHAIN$HOME/Library/Keychains/cua-driver-signing.keychain-db security create-keychain $SIGNING_KEYCHAIN # 仅首次 security set-keychain-settings $SIGNING_KEYCHAIN security unlock-keychain $SIGNING_KEYCHAIN export CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN$SIGNING_KEYCHAIN首次安装会在该钥匙串创建Qwen Cua Driver Local Signing若codesign无法非交互使用其私钥需解锁钥匙串并在 Keychain Access 中信任证书再授权 Apple 代码签名工具security set-key-partition-list -S apple-tool:,apple:,codesign: ...然后重跑严格安装器并一次性授予辅助功能与屏幕录制权限。本地卸载uninstall-local.sh/uninstall-local.ps1只撤销com.qwencode.cua-driver.local的授权不影响qwen-cua-driver、QwenCuaDriver.app、发布服务、发布状态与发布 TCC 授权--keep-tcc可保留本地授权。仓库布局与开发指引packages/cua-driver/目录结构如下路径用途rust/CLI、daemon、SDK、平台 crate 与测试的 Cargo workspacepython/Python SDK 与捆绑运行时包装typescript/TypeScript SDK 与原生运行时加载器contract/生成的便携契约与 fixturestests/fixtures/跨平台 GUI harness 应用scripts/发布/本地安装、卸载、生成与同步辅助docs/包内架构与行为说明Rust workspacepackages/cua-driver/rust/README.md按平台拆分 cratecua-driver主 CLI/MCP daemon 与集成测试、cua-driver-core共享协议、工具模型、配置与 CDP 辅助、platform-macos/platform-windows/platform-linux各平台 AX/UIA/AT-SPI、捕获、输入、浏览器与 daemon 支持、cursor-overlay跨平台语义光标渲染等。平台 crate 由主 driver crate 通过cfg(target_os)选择。本地开发与验证cd packages/cua-driver/rust cargo fmt --all -- --check cargo check -p cua-driver -p cua-driver-core -p cua-driver-sdk cargo test -p cua-driver-core默认测试应保持 headless 且适合 CIcargo test -p cua-driver-core、cargo test -p cua-driver --test protocol_mcp_testGUI 与 VM 支撑的测试标记为#[ignore]需要tests/fixtures/build/下的 harness 应用与真实交互桌面会话如cargo test -p cua-driver --test harness_appkit_test -- --ignored --nocapture。契约与语言绑定必须在发布前用包内脚本校验从packages/cua-driver/rust运行cargo run -p cua-driver-contract --bin cua-contract-gen -- all加--check校验、cargo test -p cua-driver-contract、cargo test -p cua-driver-core --test contract_parity以及schema_consistency_test中的portable_desktop_contracts_are_accepted_by_active_backend。SDK 加载器测试位于python/tests/test_uniffi_loader.py与typescript/test/native-loader.test.mjs。变更运行时行为或测试覆盖时建议从 packages/cua-driver/rust/README.md、packages/cua-driver/docs/test-matrix.md 与 packages/cua-driver/tests/fixtures/README.md 入手。签名/公证的 macOS、Windows UIAccess、Linux X11/Wayland 以及真实 MCP/model 验证仍是各平台发布门禁相关文档还可继续查阅 packages/cua-driver/docs/action-result-contract.md动作结果与后置条件验证与 packages/cua-driver/docs/cursor-themes.md光标主题与 dotLottie 创作流程。小结Qwen CUA Driver 以运行时进程内 SDK MCP 面向 Agent的双层架构把原生桌面自动化以受控、可审核、跨平台的方式交付给 qwen-code 生态权限模式与策略文件把动作约束在授权范围内归一化坐标契约在共享工具注册边界完成透明换算并对缺失基准 fail closed遥测默认关闭、显式开启后也只走内容无关的事件 schema。无论你是想给 Agent 注册 MCP 工具、在桌面应用中嵌入原生自动化还是基于 0–1000 坐标网格做跨屏幕的稳定自动化都可以在本文基础上直接上手验证。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考