UI-TARS Desktop 快速上手：从安装应用到配置 UI-TARS-1.5 / Doubao-1.5-UI-TARS 本地 GUI Agent

本文是 UI-TARS-desktop 仓库 快速上手文档 的完整技术解读。读完你将掌握：如何下载并安装 UI-TARS Desktop 应用（macOS/Windows）、如何为本地 Computer/Browser Operator 接入 Hugging Face 上的 UI-TARS-1.5 或火山引擎上的 Doubao-1.5-UI-TARS 模型服务，以及如何理解 App 内 VLM Provider 选项背后的源码逻辑（系统提示词与动作解析策略的选择）。

前置要求与环境限制

在开始之前，需要确认本机满足以下条件，这些限制在快速上手文档中明确给出：

1. Browser Operator 依赖系统浏览器。使用浏览器操作模式前，必须安装以下任一浏览器（stable/beta/dev/canary 各渠道均可）：
   • Chrome
   • Edge
   • Firefox
2. 单显示器限制。UI-TARS Desktop 目前仅支持单显示器环境；多显示器配置可能导致部分任务执行失败。

之所以有浏览器依赖，是因为 Browser Operator 走的是本地浏览器自动化链路，而非无头浏览器；Local Computer Operator 则直接操作桌面屏幕（截屏 + 鼠标键盘事件），这正是 macOS 需要授予「辅助功能」与「屏幕录制」权限的原因。

下载应用

获取应用的两种方式：

1. 从仓库 Releases 页面下载最新版 UI-TARS Desktop（对应 0.1.0 起的新版 Desktop App，同时支持 Computer 与 Browser Operator，取代 0.0.8 版本）；
2. 如果已安装 Homebrew，可直接执行：

brew install --cask ui-tars

安装步骤

macOS

macOS 端是权限要求最完整的平台，按以下三步走：

1. 将 UI TARS 应用拖入 Applications 文件夹：

   

2. 在系统设置中授予 UI TARS 两项隐私权限：

   • System Settings → Privacy & Security → Accessibility（辅助功能，用于鼠标键盘操作）
   • System Settings → Privacy & Security → Screen Recording（屏幕录制，用于任务执行的截屏输入）

3. 打开 UI TARS 应用，进入主界面。

提示：若跳过第 2 步，Local Computer Operator 将无法截屏或控制指针，任务会在启动阶段即报错。仓库主进程中也有对应的权限校验逻辑（见 权限 IPC 路由）。

Windows

Windows 端目前仍处于「To run」状态（早期阶段）：从 Releases 下载后直接运行应用即可进入主界面，无需额外系统权限配置。

Remote Operator（已停用的远程服务）

原 Remote Operator 服务（免费试用）已公告将于 2025 年 8 月 20 日下线。如果需要在免费试用结束后继续使用远程 Computer/Browser Agent，文档给出的替代路径是火山引擎的 OS Agent Services（Computer Use Agent / Browser Use Agent 的 FaaS 部署模板，部署指引为中文）。因此当前的主流用法是「本地 Operator + 远程/本地部署的 VLM 模型」，下文两条路线都基于此前提。

路线一：Hugging Face 部署 UI-TARS-1.5 + 本地 Operator

这是文档给出的完整本地化路线，共 6 步：

1. 在应用界面（或 Hugging Face 侧）点击 Deploy from Hugging Face 按钮，发起模型部署；
2. 选择模型 UI-TARS-1.5-7B；
3. 按 UI-TARS 模型仓库的 README_deploy.md 完成部署，最终获得三个关键凭证：Base URL、API Key、Model Name；
4. 打开 UI-TARS Desktop 的 Settings 设置页，按如下方式填写：

Language: en
VLM Provider: Hugging Face for UI-TARS-1.5
VLM Base URL: https:xxx
VLM API KEY: your_api_key
VLM Model Name: xxx

两个关键注意点（原文档 NOTE 强调）：

• VLM Provider 必须选择 "Hugging Face for UI-TARS-1.5"——不同 Provider 对应不同的 VLM 动作解析策略，选错会导致模型输出的动作格式无法被正确解析；
• VLM Base URL 必须以 /v1/ 结尾（OpenAI 兼容端点协议），具体值可在 Hugging Face endpoint 页面查看；
• VLM Model Name 可在同一 endpoint 页面查到。

5. 点击新建会话按钮（New Chat），选择使用场景（Computer / Browser）；
6. 输入自然语言指令，即开始一轮 GUI 操作任务。

这套配置与仓库中的预设模板一致，可对照 示例预设：

name: UI TARS Desktop Example Preset
language: en
vlmProvider: Hugging Face for UI-TARS-1.5
vlmBaseUrl: https://your-endpoint.huggingface.cloud/v1
vlmApiKey: your_api_key
vlmModelName: your_model_name
reportStorageBaseUrl: https://your-report-storage-endpoint.com/upload
utioBaseUrl: https://your-utio-endpoint.com/collect

可以看到 vlmBaseUrl 末尾正是 /v1，与上文 NOTE 的要求吻合；reportStorageBaseUrl 与 utioBaseUrl 属于可选的报告/遥测配置，详见 设置配置指南。

路线二：火山引擎 Doubao-1.5-UI-TARS + 本地 Operator

不部署自有模型时，可直接使用火山引擎（VolcEngine Ark）托管的 Doubao-1.5-UI-TARS 模型，共 8 步：

1. 进入火山引擎控制台中的 Doubao-1.5-UI-TARS 模型详情页；
2. 点击页面右上角 Try (立即体验) 按钮；
3. 点击 API inference (API 接入) 链接；
4. 在抽屉面板 STEP 1 中获取 API Key；
5. 在 STEP 2 完成实名认证，切换到 OpenAI SDK 标签页，获取 Base Url 与 Model name；
6. 打开 Settings 设置页 填写：

Language: cn
VLM Provider: VolcEngine Ark for Doubao-1.5-UI-TARS
VLM Base URL: https://ark.cn-beijing.volces.com/api/v3
VLM API KEY: YOUR_API_KEY
VLM Model Name: doubao-1.5-ui-tars-250328

同样注意：VLM Provider 必须选择 "VolcEngine Ark for Doubao-1.5-UI-TARS"，以保证 VLM 动作被正确解析。

7. 开始新会话前先选择使用场景；若使用 Browser Operator 模式，务必确认本机已安装 Chrome、Edge 或 Firefox；
8. 输入指令，开始一轮 GUI 操作任务。

完成配置后，可点击设置页的 Check Model Availability 按钮验证模型连通性（见 设置配置指南 的 Check Model Availability 一节）。

源码解读：为什么 VLM Provider 必须与模型严格匹配

快速上手文档反复强调"选对 Provider"，其底层原因可以从主进程源码确认。VLMProviderV2 枚举 定义了全部合法选项：

export enum VLMProviderV2 {
  ui_tars_1_0 = 'Hugging Face for UI-TARS-1.0',
  ui_tars_1_5 = 'Hugging Face for UI-TARS-1.5',
  doubao_1_5 = 'VolcEngine Ark for Doubao-1.5-UI-TARS',
  doubao_1_5_vl = 'VolcEngine Ark for Doubao-1.5-thinking-vision-pro',
}

在 agent 工具函数 中，Provider 会经过两次映射：

1. getModelVersion 把 Provider 映射为模型版本（V1_5、V1_0、DOUBAO_1_5_15B、DOUBAO_1_5_20B）；
2. getSpByModelVersion 再根据模型版本 + 语言（zh/en）+ 操作类型（browser/computer）选择专属系统提示词：

export const getSpByModelVersion = (
  modelVersion: UITarsModelVersion,
  language: 'zh' | 'en',
  operatorType: 'browser' | 'computer',
) => {
  switch (modelVersion) {
    case UITarsModelVersion.DOUBAO_1_5_20B:
      return getSystemPromptDoubao_15_20B(language, operatorType);
    case UITarsModelVersion.DOUBAO_1_5_15B:
      return getSystemPromptDoubao_15_15B(language);
    case UITarsModelVersion.V1_5:
      return getSystemPromptV1_5(language, 'normal');
    default:
      return getSystemPrompt(language);
  }
};

也就是说，Provider 不仅决定连到哪个端点，还决定了发给模型的 system prompt 模板与动作格式约定——UI-TARS-1.5、Doubao-1.5-15B、Doubao-1.5-20B 各自有独立的提示词实现（见 prompts 模块）。若 Provider 与真实模型不匹配，模型会按错误的动作协议输出，解析端（action parser）无法正确还原鼠标/键盘指令，任务即失败。这解释了快速上手文档中两条 NOTE 的必要性。

同时可以看到，设置项 Language（en/zh）直接参与系统提示词选择，这与 设置指南 中"Language 只影响 VLM 输出语言、不影响 App 界面语言"的说明一致。

关键配置参数速查

综合快速上手与 设置配置指南，本地 Operator 路线涉及的核心参数如下：

参数	类型	说明	取值/默认
VLM Provider	string（枚举）	决定端点协议与系统提示词/动作解析策略	必须与部署模型严格匹配，见上文枚举
VLM Base URL	string	OpenAI 兼容 API 端点；Hugging Face 端点需以 /v1/ 结尾	必填
VLM API KEY	string	模型服务鉴权密钥	必填
VLM Model Name	string	请求的模型名（HF endpoint 页面或火山引擎 OpenAI SDK 标签页可查）	必填，如 doubao-1.5-ui-tars-250328
Language	string	VLM 输出语言	en / zh
Max Loop	number	单轮对话最大步数	[25, 200]，默认 100
Loop Wait Time	number	每步截屏前等待时间（毫秒），保证动画/加载完成	[0, 3000]，默认 1000
Search Engine（本地 Browser）	string	Browser Operator 默认搜索引擎	Google / Bing / Baidu，默认 Google

其中 Max Loop 与 Loop Wait Time 影响任务循环的节奏：Loop Wait Time 对"页面跳转、加载动画"类交互尤其重要，过短会导致截屏捕捉到中间态。

验证与下一步

走到这里，你应该已经成功启动 UI-TARS Desktop 并跑通一轮 GUI 任务。按原文档的 "More" 指引，建议继续完成以下三件事以获得稳定使用体验：

1. 通读 Settings Configuration Guide：除 VLM 四要素外，还包括 Chat Settings（Max Loop / Loop Wait Time）、Operator Settings 与 Report Settings（HTML 报告上传端点、UTIO 事件收集服务）的完整配置；
2. 若自行部署模型，参考 部署指南 了解云端部署细节；
3. 若需要用代码方式复用同一套 GUI Agent 能力（而非桌面应用），可查看仓库中的 UI TARS SDK 文档 与 GUI Agent 2.0 示例。

至此，从「下载安装 → 模型接入 → 参数配置 → 发起任务」的完整链路即已在 UI-TARS Desktop 0.1.0+ 版本上闭环，后续所有能力（预设管理、报告导出、UTIO 观测）都建立在这条链路之上。