如何搭建 UI-TARS 桌面版：从安装配置到自动执行桌面任务的实战指南
【免费下载链接】UI-TARS-desktopThe Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop
桌面上散落着 38 个 PDF，文件名五花八门，手动归档要翻来覆去点十几分钟。你只需要在输入框里打一句话："把桌面上所有 PDF 移动到文档目录的 PDF 文件夹"，剩下的建文件夹、选中、拖拽都由程序代劳。UI-TARS 桌面版（UI-TARS Desktop）就是这样一款基于视觉语言模型的开源 GUI 自动化工具：你用自然语言指令描述目标，它负责截图、决策、执行，替你走完整个操作闭环，属于典型的 AI 桌面自动化方案。
准备工作三步走：下载、安装、授权
官方目前提供 macOS 和 Windows 两个平台的桌面应用，整体要求如下：
| 项目 | 要求 |
|---|---|
| 操作系统 | macOS、Windows |
| 显示器 | 仅支持单显示器，多屏环境可能导致任务失败 |
| 浏览器 | 使用浏览器操作模式前，需安装 Chrome、Edge 或 Firefox 之一 |
第一步：获取安装包。从发行版本页下载对应平台的最新版；macOS 用户如果装过 Homebrew，也可以直接执行brew install --cask ui-tars完成安装。
macOS 安装与权限配置
- 打开安装包，把UI TARS图标拖进Applications文件夹。
- 进入「系统设置 → 隐私与安全性 → 辅助功能」，打开 UI TARS 右侧的开关。
- 回到同一层级的「屏幕录制」，点「打开系统设置」并允许 UI TARS 录屏。
两项权限分别对应"动鼠标键盘"和"看屏幕"，缺任何一项，任务都会卡在执行前。
Windows 安装步骤
- 双击运行
UI.TARS-0.1.0-preview.Setup.exe。 - 如果弹出"Windows 已保护你的电脑"提示，点「仍要运行」。
- 跟随安装向导完成，首次启动即可进入主界面。
接入模型服务：服务商选择、API Key 与 Base URL
应用本身不带模型，需要接入一个 OpenAI 兼容协议的视觉语言模型接口。目前比较省事的两条路：
- 火山引擎 Ark 的 Doubao-1.5-UI-TARS：托管服务，开通后直接拿 Key，免去部署。
- Hugging Face 自部署 UI-TARS-1.5-7B：自己申请端点，获得 Base URL、API Key、模型名三件套。
在「设置 → VLM Settings」里要填四个字段：VLM Provider、VLM Base URL、VLM API KEY、VLM Model Name。这里有两个高频坑点：
- Provider 必须与模型匹配。比如自部署选 "Hugging Face for UI-TARS-1.5"，火山引擎选 "VolcEngine Ark for Doubao-1.5-UI-TARS"，选错会导致动作解析失败。
- Base URL 格式要严格。以 Hugging Face 端点为例，地址必须以
/v1/结尾（形如https://xxx.huggingface.cloud/v1/），直接复制 Endpoint URL 漏掉后缀是最常见的报错原因；火山引擎 Ark 的示例则形如https://ark.cn-beijing.volces.com/api/v3。
填完后点Check Model Availability，能连通再开始任务，比跑到一半报错省时间。
首次运行：从一句指令到一份报告
- 点左上角New Chat新建会话。
- 选择操作模式：Use Local Computer（本机桌面）或Use Local Browser（本机浏览器）。
- 在输入框输入指令，按 Enter 开始执行。
执行期间界面分左右两栏：左侧是对话与动作日志，右侧是当前屏幕截图。每一轮循环都是"截图 → 模型给出下一步动作（点击、输入、滚动等）→ 执行 → 再截图"，你可以全程看到它做了什么、做没做对。默认最多执行 100 步（可配范围 25~200），每步之间默认等待 1000 毫秒，方便页面动画落定。
任务结束后，会话可以点Export as HTML导出成 HTML 报告：不配置报告服务时默认直接下载到本地；如果配过 Report Storage Base URL，则上传后自动把分享链接复制到剪贴板，方便发给同事复查。
操作模式对比：本地电脑、本地浏览器与远程
| 模式 | 运行位置 | 适合的任务 | 限制 |
|---|---|---|---|
| Use Local Computer | 你的本机 | 文件整理、桌面软件设置、跨应用流程 | 需要辅助功能+屏幕录制权限；单显示器 |
| Use Local Browser | 本机 Chrome/Edge/Firefox | 网页表单、页面导航、信息抓取 | 必须先装好兼容浏览器 |
| 远程电脑 / 远程浏览器 | 云端虚拟桌面 | 本机配置低、想在隔离环境跑任务 | 免费额度 30 分钟；官方文档注明该免费服务计划于 2025-08-20 停服，长期需求需自部署 |
选择入口在新建会话时的模式卡片里，选完再下指令：
远程模式下右上角会显示"30-minute free credit"倒计时，点Terminate可手动结束会话并释放资源：
踩坑清单
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| macOS 上模型看着动了、实际没点下去 | 辅助功能或屏幕录制权限未开启 | 两项都打开；重装过应用后重新授权 |
| Check Model 一直失败 | HF 端点 Base URL 没以/v1/结尾，或 Provider 选错 | 对照端点页面核对 URL、Key、模型名三字段 |
| 多屏环境下部分步骤失败 | 目前仅支持单显示器 | 改为单屏运行后再试 |
| 浏览器模式无法启动 | 缺少兼容浏览器 | 安装最新版 Chrome、Edge 或 Firefox |
| 任务反复循环不结束 | 指令模糊或触及 Max Loop 上限 | 拆成多条小指令；必要时调大 Max Loop（25~200） |
边界与适用人群
它擅长：步骤明确、可重复的 GUI 流程——文件批量归类、固定表单填写、跨页面收集信息、桌面软件的配置修改。指令越具体，完成度越高。
它不擅长：需要主观判断的任务（"帮我挑个好看的方案"）；超出 Max Loop 的超长流程；多显示器环境；以及界面经常改版、元素位置不稳定的网站。另外注意：截图会发送到所选模型服务做推理，涉密内容请先评估服务商的合规性。
适合谁：被重复性电脑操作消磨时间、想先用桌面应用验证 GUI 自动化价值的用户；以及想基于@ui-tars/sdk自建 Agent 的开发者（CLI 可直接跑npx @ui-tars/cli start体验）。
不适合谁：期待"一句话包办一切复杂工作"的用户；以及需要长期、多机、无人值守调度的生产场景——这类需求更适合自部署模型 + SDK 集成，而不是开箱即用的桌面端。
写在最后
UI-TARS 桌面版把"截图—决策—执行"的循环压缩成了一个输入框，适合先把重复流程跑通、再逐步扩展。建议从"整理文件"这类低风险任务起步，观察它的执行日志，再逐步尝试多步骤任务。如果它没完成，先看是权限、模型配置还是指令颗粒度的问题，比反复重跑更有效。
延伸阅读（仓库内文档）：
- 快速入门文档：安装、取模型、跑通本地任务
- 设置配置指南：VLM、对话参数与报告服务的全部字段
- 预设管理指南：用 YAML 或 URL 导入整套配置
- SDK 开发文档：用
@ui-tars/sdk构建自定义 GUI Agent - 示例预设目录：可直接参考的配置模板
【免费下载链接】UI-TARS-desktopThe Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
