Computer Use Agent（简称 CUA）是面向 AI Agent 场景的用户专属云端运行环境，为 Agent 提供可见、可操作的 Windows 云桌面。Agent 可在远端桌面中完成网页浏览、原生应用操作、终端执行、文件处理和多步骤工作流，并通过任务状态、上下文、产物与可观测链路将执行结果返回调用方。

本文将介绍购买 Agent Plan 套餐后，如何在 AI 工具中通过 Skill 接入并使用 Computer Use Agent。

能力介绍

CUA 是一套"本地操作、远端运行"的 Windows 云桌面系统。支持的核心能力如下：

能力	说明
Windows 云桌面	通过 ark-cua skill 获取私有的 URL，随时通过电脑、手机访问你的云桌面，并且支持移动端、PC 端的整体适配。桌面端交互： Replay Play 00:00 / 00:12 Live 00:00 Fullscreen Cssfullscreen 1x 2x 1.5x 1x 0.75x 0.5x Click and hold to drag 移动端交互： Replay Play 00:00 / 00:14 Live 00:00 Fullscreen Cssfullscreen 1x 2x 1.5x 1x 0.75x 0.5x Click and hold to drag
浏览器自动化	通过浏览器结构化能力完成 URL 访问、DOM 读取、网页表单和下载等 Web 任务。分析股票行情走势： Replay Play 00:00 / 00:00 Live 00:00 Fullscreen Cssfullscreen 1x 2x 1.5x 1x 0.75x 0.5x Click and hold to drag
视觉自动化	结合截图、鼠标键盘和 Windows UI Automation 操作原生桌面应用（如微信、豆包），以及无法通过 DOM 完成的图形交互。
长程任务	支持任务状态跟踪、需要用户输入时暂停、上下文复用、时间线、定时或周期任务。
虚拟外设	支持浏览器连接本地外设工具（摄像头、麦克风）。

典型场景：

登录业务系统并完成跨页面数据录入、查询和下载。

操作仅提供 Windows 客户端的办公、研发或行业软件。

组合浏览器、终端、桌面应用和文件工具完成端到端流程。

执行需要等待、追踪进度、人工补充信息或导出文件的长程任务。

按指定时间执行一次性或周期性桌面工作流。

通过连接器远程连接本地麦克风和摄像头完成交互。

使用限制

需订购 Agent Plan Medium 及以上套餐，并由平台为当前用户分配或绑定可用的 CUA 桌面。

根据管理需要，使用本能力前需在火山平台预先完成实名认证，否则可能会导致无法正常分配机器。

同一桌面同一时间只运行一个活动任务。

云桌面临时访问 URL 属于敏感凭证，不应写入公开文档、日志或群聊；使用完毕或疑似泄露时应立即撤销。

Agent Plan API Key 仅在用户本地终端输入并缓存，禁止粘贴到对话、任务目标、命令参数日志、仓库文件或截图中。

桌面重置会重建桌面，必须显式确认；任务取消仅在用户明确要求停止时执行。

接入方法

步骤一：订阅 Agent Plan

进入开通管理-Agent Plan 页面，选择并订购 Medium 及以上级别套餐（目前仅 Medium 及以上套餐支持购买 Computer Use Agent）。套餐说明参见套餐概览。

确认使用地域、账号实名认证和套餐状态符合要求。

步骤二：开启 Computer Use Agent Harness

在 Agent Plan 控制台单击 Harness。

在 Harness 区域找到 Computer Use Agent，开启抵扣开关。

确认当前用户已分配或绑定 CUA。若控制台尚未展示 CUA 服务项，表示能力尚未对当前账号开放，请先检查套餐等级是否为 Medium 及以上；如仍有问题请联系管理员或业务支持。

步骤三：安装或更新 CUA Skill

方式一：使用 arkcli 安装（推荐）

安装 arkcli。

npm i @volcengine/ark-cli -g --registry https://registry.npmjs.org

通过 arkcli 配置 agentplan 并安装 cua（以 codex 为例）。

arkcli helper mcp codex --capability cua

方式二：通过 Skill 安装器安装

以下以 Codex 为例；其他受支持的 AI 工具可替换 --agent 参数。

# 安装 ark-cua Skill​
npx skills add https://skills.volces.com/skills/volcengine/ark -s byted-util-ark-cua --agent codex​

使用方法

Skill 方式

在已安装 ark-cua 的 AI 工具中，直接用自然语言描述任务即可。例如：使用 ark-cua 打开浏览器，登录测试环境，查询今天创建的订单并导出 CSV。导出后告诉我记录数，并把文件作为产物返回；如遇验证码或需要业务确认，先向我提问。

AI 工具会依次检查登录状态、提交原始目标、记录任务 ID，并根据返回状态继续处理：

outcome	含义	下一步
in_progress	任务仍在运行	继续执行返回的 next.command 或 watch。
needs_input	需要用户补充信息	原样转达 input_request.question，收到答复后执行 answer。
completed	任务完成	以 result.text 为最终结果，并处理产物。
failed	任务失败	报告错误码、请求 ID 和安全诊断；不要盲目重试。
cancelled	任务已取消	告知用户任务已停止。

通过 Skill 让 Agent 返回临时 URL 访问 Computer Use Agent。URL 有效期约 30 分钟，过期后重新获取指令即可。

使用返回的 URL 登录后，可以在左侧的聊天框内发布指令，也可以直接在右侧图形化界面中操作 CUA。

通过配置使用连接器和外设。 CUA 预装了多种软件连接器（Office CLI 等），选择最左侧连接器标签，跟随引导补充配置信息，即可通过 Skill 使用对应能力。当场景需要摄像头或麦克风输入时，也可将本地外设连接至 CUA。

关闭 CUA 停止计费

CUA 是按照使用时长计费的，计费频率为小时，因此当确认不再需要使用时，可以通过 Skill 请求关闭 CUA，同步停止计费，以节约使用成本。

关闭 CUA 后，之前签发的云桌面的访问地址同步失效，机器无法使用。

最佳实践

把目标写成可验收的任务。说明目标系统、环境、数据范围、交付物、成功标准和禁止动作。例如"在测试环境创建一条草稿，保存但不要提交审批，并返回草稿编号"比"帮我操作一下系统"更稳定。

优先使用确定性证据。同一目标可由多种工具完成时，优先选能产生结构化、可验证结果的路径：Terminal 适合命令和状态检查，Browser 适合网页 DOM 与表单，Computer / UIA 用于原生应用、拖拽和系统级弹窗。不要用坐标点击替代可以通过终端或 DOM 完成的操作。

一个请求只创建一次任务。保存首次返回的 invocation_id 或 task ID。等待超时不等于任务失败，继续 watch 即可；重复 delegate 既可能触发冲突，也可能造成重复业务操作和额外消耗。

正确处理人工介入。遇到验证码、登录确认、业务审批、不可逆操作或信息不足时，允许任务向调用方转达问题，由调用方将问题原样交给用户后再继续。

将进度、观察和结果分开。进度摘要、截图与观察日志只用于了解任务正在发生什么。完成判定必须基于 outcome == completed，文件交付必须确认 Artifact 存在可下载内容。

管好凭证和临时访问链接。 API Key 只在本地终端输入并妥善保管；临时桌面票据不进入仓库和群聊，使用完毕或疑似泄露时应立即撤销。

对外部副作用设置边界。生产环境写入、发送消息、提交审批、购买、删除和桌面重置等动作，应在目标中明确是否允许，并在不可逆步骤前要求确认。失败时根据稳定错误码处理，不通过盲目重试扩大影响。

计费说明

CUA 作为 Agent Plan Harness，计费遵循 Agent Plan Harness 的统一原则：按小时计算费用，抵扣用户积分。

场景	规则
套餐额度未用尽	优先消耗 Agent Plan 套餐额度 / AFP。目前折扣费率为312.5 AFP/CU/小时，活动期内限时2折优惠，费率低至62.5 AFP/CU/小时。套餐内用量通常不再就该 Harness 能力单独推送后付费账单；在 CUA 内的 agent也会消耗token，这部分token消耗是自动通过用户的agent plan结算。
超额后场景	当用户的套餐积分在周期内耗尽，默认关闭 CUA 使用入口，同时机器为用户保留 7 天，用户需要尽快补充积分。
计量口径	平台按照实际占用和使用情况结算费用，结算粒度为小时级别。

常见问题

为什么返回 AUTH_REQUIRED？

本地没有有效的 Agent Plan API Key，或 Key 已失效。请在自己的本地终端按提示完成配置后重试。不要把 Key 发到对话中。

为什么返回 DESKTOP_NOT_BOUND？

当前账号尚未分配 CUA 桌面。请确认已开通 CUA Harness，并联系管理员或业务支持完成资源分配。

为什么返回 ACTIVE_RUN_CONFLICT？

绑定桌面已有活动任务，新任务未启动。等待现有任务结束；除非用户明确要求，不要取消现有任务或重复提交。

watch 超时是否代表任务失败？

不是。超时只是本次等待窗口结束；只要 outcome 仍为 in_progress，继续执行 watch。

桌面访问链接失效怎么办？

通过 Skill 让 Agent 重新获取新链接。旧链接不应长期保存或转发。

服务协议

Harness 能力说明和产品专用条款

Computer Use Agent 服务规则

火山方舟