从零跑通 UI-TARS Desktop 的三步 GUI 自动化实战指南

从零跑通 UI-TARS Desktop 的三步 GUI 自动化实战指南【免费下载链接】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每天你要在两个系统之间手动倒数据先从内部平台导出表格再逐条填进另一边的表单。UI-TARS Desktop 这个开源 GUI Agent 就是干这件事的你输入一句打开浏览器并访问 GitHub Trending 页面它背后的视觉语言模型会自己识别屏幕、移动鼠标、点击和输入。本文覆盖从拉取源码、配置模型到跑通第一个任务的完整过程外加核心流程和高频故障排查共四部分。一分钟认识 UI-TARS Desktop是什么、给谁用项目定位一个跑在你自己电脑上的桌面 GUI Agent 应用基于 UI-TARS 系列视觉语言模型VLModel驱动解决的核心问题把在屏幕上找到某个元素并操作它这件事从写脚本变成说一句话技术路线截图 → 发给视觉语言模型 → 模型返回下一步动作点击/输入/滚动→ 本地执行循环往复两种操作模式本地电脑操作控制你当前这台机器和本地浏览器操作需要装 Chrome、Edge 或 Firefox你之前的做法用 UI-TARS Desktop 之后脚本里写死坐标界面一变就失效模型每步看当前截图界面变化也能识别每个任务都要写、维护一份脚本直接输入自然语言指令不用写代码桌面自动化和浏览器自动化各找一套工具一个应用内切换电脑操作与浏览器操作模糊需求找到那个按钮没法处理视觉语言模型能理解模糊的视觉描述适合谁想在自己电脑上做重复性界面操作、UI 回归测试的普通用户和初级开发者。不适合谁需要自己本地部署模型且不想用云端推理服务的人应用本身只负责调度模型服务需要一个 OpenAI 兼容的 API 端点另外官方明确目前只支持单显示器多显示器配置可能导致任务失败。最短路径跑通从拉取源码到第一次成功环境自检这一步在做运行前的最低要求确认。项目要求 Node.js 20 以上包管理器固定为 pnpm 9# 查看 Node 版本必须 20 以上 node --version # 查看 pnpm 版本没有就先安装 pnpm --version另外注意两点浏览器操作模式需要本机装有 Chrome、Edge 或 Firefox多显示器环境建议先切到单屏再试。拉取源码并构建# 拉取 UI-TARS Desktop 源码 git clone https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop # 进入仓库目录 cd UI-TARS-desktop # 安装全部依赖pnpm 工作区 pnpm install # 开发模式启动快速体验 pnpm run dev:ui-tars # 或构建可安装的桌面安装包 pnpm --filter ui-tars-desktop buildpnpm run dev:ui-tars会直接拉起应用窗口适合先验证环境确认没问题后再执行 build 打包。如果只想装成品包也可以不构建macOS 上通过 Homebrew 执行brew install --cask ui-tarsWindows 直接跑安装包即可。启动并授予权限⚠️ 这一步最容易卡住macOS 下如果不给权限应用既截不了图也动不了鼠标键盘任务会表现为完全没反应。各平台差异如下macOS把应用拖进 Applications 后进入 系统设置 → 隐私与安全性打开辅助功能Accessibility和屏幕录制Screen Recording两个开关再重启应用Windows运行安装包完成安装后直接启动无额外权限项Linux使用构建出的安装包启动即可macOS 下授予 UI-TARS 屏幕录制与辅助功能权限的界面两项都是视觉识别和鼠标控制的前提权限给好后进入设置页填好模型参数下一节讲点一下Check Model Availability按钮确认模型连通然后新建会话输入第一条指令。到这里界面长这样UI-TARS 桌面应用的任务界面输入一句自然语言指令右侧实时展示每一步的截图与动作关键配置详解真正影响体验的少数参数模型服务不是应用自带的你需要先部署一个比如在 Hugging Face 上部署 UI-TARS-1.5-7B在 Hugging Face 端点页面部署 UI-TARS-1.5-7B 模型部署完成后可拿到 Base URL、API Key 和模型名应用端只需要在设置里配置以下核心参数默认值、何时改、改了有什么效果language: en # 默认 en只改模型输出语言不改应用界面语言 vlmProvider: Hugging Face for UI-TARS-1.5 # 默认空必须与你的模型版本匹配 vlmBaseUrl: https://your-endpoint.huggingface.cloud/v1 vlmApiKey: your_api_key # 默认空从模型部署页获取 vlmModelName: your_model_name maxLoopCount: 100 # 默认 100范围 25-200单轮任务最多执行多少步 loopIntervalInMs: 1000 # 默认 1000ms范围 0-3000每步后等屏幕稳定的时间 useResponsesApi: false # 默认 false模型支持 Responses API 时开启逐项说明VLM Provider默认留空填错会导致模型输出无法正确解析。它是解析器选择——用 UI-TARS-1.5 就必须选Hugging Face for UI-TARS-1.5用豆包就必须选对应的 VolcEngine 选项VLM Base URL必须是一个可访问的 OpenAI 兼容端点。 用 Hugging Face 端点时务必确认 URL 以/v1结尾这是最高频的填错点Max LoopmaxLoopCount默认 100。简单任务把它调到 25出错时能更快刹车跨多页面的长流程才需要往 200 调Loop Wait TimeloopIntervalInMs默认 1000ms。如果任务里涉及页面跳转、刷新这类需要加载的操作动作总抢跑就调到 2000–3000Use Responses API默认关闭。你的模型支持时开启它可以少消耗 token 并提升响应速度设置页实际长这样模型服务四项参数都在这UI-TARS 的模型配置界面选择 VLM 提供商、填写 Base URL / API Key / 模型名后点击 Check Model Availability 验证连通性场景推荐配置单步简单任务打开某个页面、点一个按钮maxLoopCount: 25loopIntervalInMs 保持 1000跨页面多步流程maxLoopCount: 100–200动作后页面要加载跳转、刷新loopIntervalInMs: 2000–3000模型支持 Responses APIuseResponsesApi: true它是怎么工作的一张图看懂核心流程主链路是一个循环你输入指令 → 应用截图当前屏幕 → 连同指令发给视觉语言模型 → 模型返回下一步动作 → 本地执行该动作 → 再截图进入下一轮直到模型输出结束。UTIOUI-TARS Insights and Observation流程任务事件从应用发出、经模型推理与动作执行后回写结果想定位代码时看这几处就够apps/ui-tars/src/main/agent/operator.ts本地动作执行与截图apps/ui-tars/src/main/services/runAgent.ts任务循环调度apps/ui-tars/src/main/utils/screen.ts截屏与系统权限packages/ui-tars/sdk/GUIAgent 主循环SDK 核心packages/ui-tars/action-parser/把模型输出解析成具体动作踩坑速查4 个高频故障与排查顺序问题 1任务开始后鼠标键盘完全没反应常见于 macOS排查顺序确认系统设置里辅助功能开关已打开确认屏幕录制开关也已打开两个都要授予权限后确认重启过应用解决系统设置 → 隐私与安全性 → 分别进入辅助功能和屏幕录制为 UI-TARS 打开开关重启应用后重试任务。问题 2设置页 Check Model Availability 失败或任务发出后无响应排查顺序打开设置检查 VLM Base URL 是否完整、用浏览器能否访问该地址Hugging Face 端点确认 URL 以/v1结尾对照模型部署页核对 API Key 和模型名是否一字不差确认 VLM Provider 与模型版本匹配解决修正设置页的 Base URL / API KEY / Model Name 三项后重新点击 Check Model Availability按钮显示可用再发起任务。问题 3浏览器操作模式不可用或任务频繁失败排查顺序确认本机装有 Chrome、Edge 或 Firefox 之一确认发起任务时选择的模式是浏览器操作而非本地电脑操作确认当前是单显示器环境解决安装任一受支持的浏览器多显示器用户先切回单屏——官方文档明确多显示器配置可能导致任务失败。问题 4模型点错位置、动作解析异常排查顺序检查 VLM Provider 是否选错版本1.0 模型配了 1.5 的解析器或反之确认模型服务返回的是动作格式而非普通文本Provider 选错时最典型换一句描述更具体、指代更明确的指令重试解决在设置页把 VLM Provider 改为与模型严格匹配的选项例如豆包模型选VolcEngine Ark for Doubao-1.5-UI-TARS验证通过后再跑原任务。从能用到好用调优、扩展与资源入口性能与资源调优这个应用的开销大头在模型推理侧本地可调整的空间主要是循环参数。任务越简单、步数上限越低越安全useResponsesApi开启后按官方说明能降低 token 消耗、提升响应速度。# 简单任务的安全配置少步数、快速验证 maxLoopCount: 25 loopIntervalInMs: 1000 useResponsesApi: true自定义扩展桌面应用之外ui-tars/sdk允许你在自己的 Node.js 或浏览器项目里搭建 GUI Agent。写一个自定义 Operator 只需实现screenshot()截屏和execute()执行动作两个方法最小骨架如下import { GUIAgent } from ui-tars/sdk; import { NutJSOperator } from ui-tars/operator-nut-js; // 自定义 Operator 时实现 screenshot() 与 execute() 即可 const agent new GUIAgent({ model: { baseURL, apiKey, model }, operator: new NutJSOperator(), }); await agent.run(open Chrome);外部服务集成不想逐个手填配置的话可以用预设Preset——一段 YAML 文件或直接一个 URL应用导入后自动更新全部设置URL 预设还支持每次启动自动同步。四个官方支持的 Provider 值Hugging Face for UI-TARS-1.0、Hugging Face for UI-TARS-1.5、VolcEngine Ark for Doubao-1.5-UI-TARS、VolcEngine Ark for Doubao-1.5-thinking-vision-pro。name: My UI-TARS 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典型应用场景办公自动化把 A 系统的数据搬运到 B 系统的表单里全程只发一句指令UI 回归测试让 Agent 走一遍固定流程结束后用应用内的 Export as HTML 导出执行报告开发流程提效在 VS Code 设置里打开自动保存并设为延迟 500 毫秒这类杂务直接甩给 Agent浏览器信息任务搜索、翻页、提取页面信息配合浏览器操作模式完成资源入口docs/quick-start.md快速入门含各平台安装与模型部署步骤docs/setting.md全部设置项说明docs/preset.md预设导入与管理docs/sdk.mdSDK 与自定义 Operator 开发指南examples/presets/default.yaml官方预设示例CONTRIBUTING.md贡献指南建议的下一步先按第三节把应用跑起来并完成一次 Check Model Availability再回来第四节按你的实际任务类型调maxLoopCount和loopIntervalInMs。【免费下载链接】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），仅供参考