UI-TARS Desktop 完整指南：自然语言驱动桌面 GUI Agent 的部署与实战
UI-TARS Desktop 完整指南自然语言驱动桌面 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-desktopUI-TARS Desktop 是一个开源的桌面 GUI Agent 应用由 UI-TARS 视觉语言模型VLM能看懂图像的多模态大模型驱动。你用一句自然语言下指令它会截图、识别屏幕元素、模拟鼠标键盘在你的电脑上完成任务。适合想在本地跑通 GUI 自动化、又不想自己搭模型服务的开发者和效率型用户。UI-TARS Desktop 快速上手从安装到跑通第一个任务第一步把应用装起来三条路按省事程度排序macOS 用户装了 Homebrew 的话直接brew install --cask ui-tars即可Windows / macOS 用户从 release 页面下载对应平台的安装包macOS 上把 UI TARS 图标拖进 Applications 文件夹想改代码的贡献者克隆源码用 pnpm 安装依赖后启动开发模式# 从源码运行需要 Node.js 20 git clone https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop cd UI-TARS-desktop pnpm install pnpm dev:ui-tars # 根目录下启动桌面应用开发模式第二步macOS 权限配置跳过这步等于白装macOS 上应用需要两个权限缺一不可辅助功能允许模拟键鼠和屏幕录制允许截图。去 系统设置 → 隐私与安全性 里分别开启然后重启应用。典型症状是任务跑了模型也在思考但鼠标纹丝不动——十有八九是辅助功能没给。第三步配置视觉语言模型应用本身不带模型需要你接一个 OpenAI 兼容的 VLM 端点。在 Settings 里填四项官方预设了两种开箱即用的 ProviderHugging Face for UI-TARS-1.5在 Hugging Face 上部署 UI-TARS-1.5-7B拿到 Base URL、API Key 和 Model NameVolcEngine Ark for Doubao-1.5-UI-TARS直接用火山引擎上托管的 Doubao-1.5-UI-TARS免去部署两个容易踩的坑先说在前面Base URL 必须以/v1/结尾Provider 一定要选和模型对应的那个选项因为它决定了应用如何解析模型返回的动作格式。填完点Check Model Availability验证通过了再开始任务。第四步发出第一条指令点右上角新建对话选择使用场景本地电脑操作 / 浏览器操作输入指令回车。成功标志屏幕开始真实地动——光标移动、窗口切换、输入框被敲字右侧步骤区逐步追加模型每一步的截图和动作记录。它是怎么操作的截图、决策、执行的一轮循环可以把 UI-TARS Desktop 理解成一个盯着屏幕干活的人。它不读 DOM、不依赖控件树整个任务就是一个循环截图Operator执行器抓取当前屏幕决策把指令加上最近 5 帧截图发给 VLM模型输出一个动作比如click(start_box(27,496))执行Operator 在真实屏幕上执行这个动作循环再截图、再决策直到模型判断任务完成或达到最大轮数Operator 分两种本地电脑 Operator直接控制你整台机器基于 NutJS 做跨平台输入注入浏览器 Operator则接管 Chrome、Edge 或 Firefox。看屏幕而不是读代码这个设计带来的好处是任何有图形界面的应用它都能碰页面结构怎么改都不影响代价是每一步都要过一次模型速度和成本都跟模型端点强相关。最影响体验的几个配置项语言、轮数与等待时间Languageen/zh只影响 VLM 的输出语言不改应用界面语言。中文界面跑中文指令时设zh会更稳Max Loop25~200默认 100单轮对话最多执行多少步。长流程任务多页面表单调大简单任务调小可以省 tokenLoop Wait Time0~3000ms默认 1000每次动作后等多少毫秒再截图。遇到点了之后要等页面跳转的操作调大它能避免截到中间状态纯本地小工具可以调小提速用 Preset 一键导入整套配置如果团队里多个人用同一套模型端点手动逐项填很烦。Preset 就是把这些设置打包成一个 YAML支持从本地文件导入手动更新或从 URL 导入应用每次启动自动拉取团队配置可以版本化管理# 最小可用 Preset 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仓库里 examples/presets/ 有完整示例格式说明见 docs/preset.md。想脱离桌面应用ui-tars/sdk如果你要的不是一个 App而是把 GUI Agent 能力嵌进自己的 Node.js 服务或 Web 页面monorepo 里的ui-tars/sdk提供同一套模型 Operator抽象截图和动作执行都由可替换的 Operator 接口完成。最快的体验方式是直接用配套 CLInpx ui-tars/cli start # 输入模型端点配置后在终端用自然语言控制电脑更多 API 细节见 docs/sdk.md。三个适合用它的场景GUI 回归验证。改完前端或桌面端界面后与其人肉点一遍不如把打开设置页、确认 X 选项存在、截个图写成一条指令反复跑。它靠视觉定位元素界面改版后传统坐标脚本全废而它只需要重新看一眼。浏览器信息操作。用 Browser Operator 让它打开网页、翻页、抓取信息、填表单。适合流程固定但页面结构偶有变动的重复性浏览任务——比如定期去后台查某个列表。繁琐的桌面设置类任务。README 里的官方示例很有代表性帮我打开 VS Code 的自动保存功能并把延迟设为 500 毫秒。这类我知道在哪但懒得点的任务正是它的甜点区步骤多、单步简单、容错空间大。高频坑与排障任务执行了但鼠标没反应macOS。先查两个权限辅助功能和屏幕录制都要开开完重启应用。如果屏幕录制开了但模型说看不到检查有没有误把权限给了别的同名进程。Check Model Availability 一直失败。按顺序排查Base URL 是不是漏了结尾的/v1/Provider 下拉框选的和你实际部署的模型是不是同一个直接curl一下端点的 chat 接口确认网络通、key 有效。三者都对还失败再看端点日志。多显示器环境任务偶发失败。官方目前只保证单显示器场景多屏布局下坐标换算可能出错。做关键任务时切到单显示器。Browser Operator 起不来。确认系统里装了 Chrome、Edge 或 Firefoxstable 到 canary 渠道均可并且启动任务前浏览器别正在被其他调试会话占用。任务中途截到半拉子状态导致走偏。把 Loop Wait Time 从 1000 调到 2000 左右再试如果还走偏多半是指令太模糊把打开 A然后点 B拆成两轮对话更可控。延伸阅读官方上手与模型部署流程docs/quick-start.md全部配置项说明含报告存储、UTIO 事件上报服务docs/setting.md构建与打包CONTRIBUTING.md想基于 SDK 自建 Agentdocs/sdk.md以及 examples/ 下的完整示例任务跑完后可以导出 HTML 报告分享执行过程整个事件与报告的数据流向在 docs/setting.md 的 UTIO 一节有图示说明。【免费下载链接】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），仅供参考
