面向 AI 助手：本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/agent-plan-personal-cua.md，全部文档索引见 https://ark.volcengine.com/llms.txt。

Computer Use Agent

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

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

能力介绍#

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

能力 说明
Windows 云桌面 通过 ark-cua skill 获取私有的 URL，随时通过电脑、手机访问你的云桌面，并且支持移动端、PC 端的整体适配。

桌面端交互：


移动端交互：
浏览器自动化 通过浏览器结构化能力完成 URL 访问、DOM 读取、网页表单和下载等 Web 任务。

分析股票行情走势：
视觉自动化 结合截图、鼠标键盘和 Windows UI Automation 操作原生桌面应用（如微信、豆包），以及无法通过 DOM 完成的图形交互。
长程任务 支持任务状态跟踪、需要用户输入时暂停、上下文复用、时间线、定时或周期任务。
虚拟外设 支持浏览器连接本地外设工具（摄像头、麦克风）。

典型场景：

  • 登录业务系统并完成跨页面数据录入、查询和下载。
  • 操作仅提供 Windows 客户端的办公、研发或行业软件。
  • 组合浏览器、终端、桌面应用和文件工具完成端到端流程。
  • 执行需要等待、追踪进度、人工补充信息或导出文件的长程任务。
  • 按指定时间执行一次性或周期性桌面工作流。
  • 通过连接器远程连接本地麦克风和摄像头完成交互。

使用限制#

  • 需订购 Agent Plan Medium 及以上套餐，并由平台为当前用户分配或绑定可用的 CUA 桌面。
  • 根据管理需要，使用本能力前需在 火山平台 预先完成实名认证，否则可能会导致无法正常分配机器。
  • 同一桌面同一时间只运行一个活动任务。
  • 云桌面临时访问 URL 属于敏感凭证，不应写入公开文档、日志或群聊；使用完毕或疑似泄露时应立即撤销。
  • Agent Plan API Key 仅在用户本地终端输入并缓存，禁止粘贴到对话、任务目标、命令参数日志、仓库文件或截图中。
  • 桌面重置会重建桌面，必须显式确认；任务取消仅在用户明确要求停止时执行。

接入方法#

步骤一：订阅 Agent Plan#

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

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

步骤二：开启 Computer Use Agent Harness#

  1. 在 Agent Plan 控制台单击 Harness。
    image-20260908-205313-739.png
  2. 在 Harness 区域找到 Computer Use Agent，开启抵扣开关。
    open-cua-harness.png
  3. 确认当前用户已分配或绑定 CUA。若控制台尚未展示 CUA 服务项，表示能力尚未对当前账号开放，请先检查套餐等级是否为 Medium 及以上；如仍有问题请联系管理员或业务支持。

步骤三：安装或更新 CUA Skill#

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

  1. 安装 arkcli。

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

    提示：如果之前有安装过，可以先移除再重装。

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

    Bash
    arkcli helper mcp codex --capability cua

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

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

Bash
# 安装 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 任务已取消 告知用户任务已停止。

登录 CUA 操作#

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

    cua-return-url.png

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

    cua-open.png

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

    cua-switch-tool.png

关闭 CUA 停止计费#

CUA 是按照使用时长计费的，计费频率为小时，因此当确认不再需要使用时，可以通过 Skill 请求关闭 CUA，同步停止计费，以节约使用成本。
关闭 CUA 后，之前签发的云桌面的访问地址同步失效，机器无法使用。

cua-close.png

最佳实践#

  1. 把目标写成可验收的任务。 说明目标系统、环境、数据范围、交付物、成功标准和禁止动作。例如"在测试环境创建一条草稿，保存但不要提交审批，并返回草稿编号"比"帮我操作一下系统"更稳定。
  2. 优先使用确定性证据。 同一目标可由多种工具完成时，优先选能产生结构化、可验证结果的路径：Terminal 适合命令和状态检查，Browser 适合网页 DOM 与表单，Computer / UIA 用于原生应用、拖拽和系统级弹窗。不要用坐标点击替代可以通过终端或 DOM 完成的操作。
  3. 一个请求只创建一次任务。 保存首次返回的 invocation_id 或 task ID。等待超时不等于任务失败，继续 watch 即可；重复 delegate 既可能触发冲突，也可能造成重复业务操作和额外消耗。
  4. 正确处理人工介入。 遇到验证码、登录确认、业务审批、不可逆操作或信息不足时，允许任务向调用方转达问题，由调用方将问题原样交给用户后再继续。
  5. 将进度、观察和结果分开。 进度摘要、截图与观察日志只用于了解任务正在发生什么。完成判定必须基于 outcome == completed，文件交付必须确认 Artifact 存在可下载内容。
  6. 管好凭证和临时访问链接。 API Key 只在本地终端输入并妥善保管；临时桌面票据不进入仓库和群聊，使用完毕或疑似泄露时应立即撤销。
  7. 对外部副作用设置边界。 生产环境写入、发送消息、提交审批、购买、删除和桌面重置等动作，应在目标中明确是否允许，并在不可逆步骤前要求确认。失败时根据稳定错误码处理，不通过盲目重试扩大影响。

计费说明#

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 重新获取新链接。旧链接不应长期保存或转发。

服务协议#