UI-TARS-desktop：超详细部署与使用教程

UI-TARS-desktop 是字节跳动 UI-TARS 团队官方开源的 GUI Agent 仓库，当前对外打包了两件产品：UI-TARS Desktop（基于 UI-TARS 与 Seed-1.5-VL/1.6 系列多模态模型的桌面端 GUI Agent，用自然语言直接控制本机电脑和浏览器）与 Agent TARS（面向终端、电脑、浏览器与第三方产品的通用多模态 Agent 栈，提供 CLI 与 Web UI）。仓库把桌面安装包、CLI 工具、跨平台 SDK（UI TARS SDK）和云部署文档全部放在一起，是「让 AI 像人一样操作电脑」方向上字节官方的主力开源项目。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

这个仓库同时承载「给人用的桌面 App」和「给开发者用的 Agent 栈」两条线：

1. UI-TARS Desktop：原生桌面 GUI Agent，驱动模型为字节自研的 UI-TARS 系列（UI-TARS-1.5 及 Seed-1.5-VL/1.6 系列）。用户在聊天框输入一句自然语言（例如「帮我在 VS Code 里打开自动保存，并把 AutoSave 延迟设为 500 毫秒」），Agent 会截图、理解界面、移动鼠标键盘去真实操作电脑，全程实时反馈。
2. Agent TARS：通用多模态 AI Agent 栈，把 GUI Agent 与视觉能力带进终端（CLI）、电脑、浏览器和第三方产品；核心基于 MCP 协议，支持挂载 MCP Server 连接真实工具，提供有界面的 Web UI 与无界面的 server 两种执行方式。

二者共用 UI-TARS 这一多模态 GUI 模型底座，仓库 README 明确指向「用前沿多模态大模型 + 真实工具集成，逼近人类完成任务的方式」。

1.2 核心功能

UI-TARS Desktop 能力：

• 🤖 由视觉-语言模型驱动的自然语言控制电脑；
• 🖥️ 截屏 + 视觉识别，理解当前界面内容；
• 🎯 精准的鼠标与键盘控制；
• 💻 跨平台（Windows / macOS / Browser Operator）；
• 🔄 实时反馈与执行状态展示；
• 🔐 隐私安全——Agent 本体完全在本地运行，模型请求走你自己配置的 VLM 端点。

Agent TARS 能力：

• 🖱️ 一键即用的 CLI：同时支持有界面的 Web UI（headful）与无界面的 server（headless）执行；
• 🌐 混合浏览器 Agent：GUI Agent 视觉定位、DOM 定位、或两者混合策略控制浏览器；
• 🔄 事件流（Event Stream）：协议驱动的事件流支撑上下文工程与 Agent UI；
• 🧰 MCP 集成：内核基于 MCP 构建，可挂载 MCP Server 接入真实世界工具。

模型侧： 仓库配套模型 UI-TARS-1.5-7B 托管在 HuggingFace，另有 ModelScope 镜像；部署文档同时覆盖 HuggingFace 端点与火山引擎方舟（Doubao-1.5-UI-TARS）两种接入方式。

1.3 技术架构

整体架构可以概括为三层：

• 模型层（VLM）：UI-TARS 系列视觉-语言模型（本地或云端端点），负责「看懂屏幕 + 决策下一步动作」；
• 应用层：UI-TARS Desktop（Electron 桌面 App，负责本地 Computer Operator / Browser Operator）与 Agent TARS CLI/Web UI（@agent-tars/cli npm 包）；
• 工具层：MCP Server 生态、浏览器桥（Chrome/Edge/Firefox）、云部署（火山引擎 OS Agent 服务）。

开发人员还可以用仓库内的 UI TARS SDK（docs/sdk.md）自己构建 GUI 自动化 Agent，而不必套桌面 App。

二、环境要求

说明：本地 Computer Operator 只是「控制本机」，模型推理走你配置的 VLM API；不要求本机有 GPU，但你自己部署的模型端点（如 HF 端点、自建 vLLM）需要 GPU。

三、部署方式

下面给出三条路径：① 桌面 App（UI-TARS Desktop）→ ② Agent TARS CLI → ③ 配置模型端点让 Agent 跑起来。

3.1 方式一：安装 UI-TARS Desktop（桌面 App）

Windows：

1. 打开仓库 Releases 页：https://github.com/bytedance/UI-TARS-desktop/releases/latest ；
2. 下载对应 Windows 安装包（.exe / 安装器），双击安装并运行；
3. 首次打开后按 3.3 配置 VLM 端点。

macOS：

# 方式 A：如果你装了 Homebrew，一行命令安装
brew install --cask ui-tars

# 方式 B：从 Releases 页下载 dmg，把 UI TARS 拖进「应用程序」文件夹
# 然后在：系统设置 -> 隐私与安全性 中开启
#   - 辅助功能（Accessibility）
#   - 屏幕录制（Screen Recording）

安装完成后打开 UI TARS 应用，能看到主界面即安装成功。

3.2 方式二：安装 Agent TARS CLI（终端 Agent）

# 1) 要求 Node.js >= 22，先确认版本
node -v

# 2) 零安装直接用 npx 启动
npx @agent-tars/cli@latest

# 3) 或全局安装
npm install @agent-tars/cli@latest -g

带模型参数直接启动：

# 火山引擎豆包视觉模型
agent-tars --provider volcengine --model doubao-1-5-thinking-vision-pro-250428 --apiKey your-api-key

# 或 Anthropic
agent-tars --provider anthropic --model claude-3-7-sonnet-latest --apiKey your-api-key

3.3 方式三：配置 VLM 模型端点（让 Agent 真正能干活）

桌面 App 打开「Settings」，按所选服务商填写：

方案 A：HuggingFace 部署 UI-TARS-1.5-7B

1. 在 HuggingFace Endpoints 页点击 Deploy from Hugging Face，选择模型 UI-TARS-1.5-7B；
2. 按 https://github.com/bytedance/UI-TARS/blob/main/README_deploy.md 获取 Base URL、API Key、Model Name；
3. 回到 App Settings 填写：

Language: en
VLM Provider: Hugging Face for UI-TARS-1.5
VLM Base URL: https:xxx   # 注意必须以 /v1/ 结尾
VLM API KEY: your_api_key
VLM Model Name: xxx

关键：VLM Provider 必须选「Hugging Face for UI-TARS-1.5」，否则 VLM Action 解析会不匹配。

方案 B：火山引擎方舟 Doubao-1.5-UI-TARS（国内推荐）

1. 打开 https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-1-5-ui-tars ；
2. 点「立即体验」→「API 接入」，获取 API Key，切到 OpenAI SDK 标签页拿 Base URL 与 Model name；
3. App 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

3.4 验证部署成功

# 1) CLI 能起
agent-tars --help   # 或 npx @agent-tars/cli@latest --help

# 2) 桌面 App：Settings 填好端点后，新建一个聊天，选择使用场景（Computer Operator / Browser Operator）
# 3) 输入一句测试指令，例如：
#    「帮我查一下 UI-TARS-Desktop 项目在 GitHub 上最新的 open issue」
# Agent 能截图、操作浏览器并给出结果，即整条链路打通。

注意：官方 Remote Operator 免费服务已于 2025-08-20 停止；如需远程控制别的电脑/浏览器，官方引导改用火山引擎的 OS Agent 服务（Computer Use Agent / Browser Use Agent 模板），部署链接以官方 quick-start 文档为准。

四、使用方法

4.1 基础用法：桌面 App 下指令

1. 打开 UI TARS App → 新建聊天；
2. 先选场景：Local Computer Operator（操作本机）或 Browser Operator（操作浏览器）；
3. 在输入框写自然语言任务，回车；
4. Agent 自动执行：截图 → 分析界面 → 移动鼠标键盘 → 反馈结果；每一步的动作与状态实时显示。

官方示例指令（直接可用）：

• 「请帮我打开 VS Code 的自动保存功能，并把 AutoSave 操作延迟设为 500 毫秒」；
• 「帮我查一下 UI-TARS-Desktop 项目在 GitHub 上最新的 open issue」；
• 「请帮我在 Priceline 上订 9 月 1 日从圣何塞到纽约最早的航班，以及 9 月 6 日最晚的返程航班」。

4.2 Agent TARS CLI 常用命令

# 启动交互模式
npx @agent-tars/cli@latest

# 指定服务商与模型
agent-tars --provider volcengine --model <模型名> --apiKey <key>

# headless server 执行（无人值守/CI 场景，配置见官方文档）
# https://agent-tars.com/guide/advanced/server.html

常用扩展：

• MCP Server：在 CLI 里挂载 MCP Server，给 Agent 接真实工具（查天气、读数据库、调内部 API），配置方式见 https://agent-tars.com/guide/basic/mcp.html ；
• Web UI：除 CLI 外可用有界面的 Web UI，见 https://agent-tars.com/guide/basic/web-ui.html ；
• Agent TARS SDK：docs/sdk.md 提供跨平台 GUI 自动化 Agent 构建能力，可嵌入自己的产品。

4.3 进阶功能

• 混合浏览器控制：GUI 视觉定位 + DOM 定位可按页面类型自动切换，应对纯图标按钮、Canvas 绘制内容；
• 事件流调试：CLI v0.3.0 起支持 Event Stream Viewer，可视化追踪数据流，便于排查 Agent 决策过程；
• AIO Agent Sandbox：v0.3.0 起支持 agent-infra/sandbox，把 Agent 的 shell 命令等工具执行放进隔离沙箱；
• 流式工具调用：多工具（shell 命令、多文件结构化展示）支持流式输出，并带工具调用耗时统计与深度思考计时。

4.4 适用场景

• 个人效率自动化：跨软件重复性操作（填表单、改设置、查资料）；
• 测试与演示：把演示脚本录成自然语言任务，让 Agent 自动回放；
• 产品内嵌 Agent：通过 Agent TARS CLI/Web UI 与 MCP 把「AI 操作电脑」能力集成到内部工具；
• 自动化研究：GUI Agent 行为的二次开发与实验（官方仓库 Issue #842 汇总了大量社区用例）。

五、常见问题排查（FAQ）

Q1：桌面 App 打开后点不动电脑 / 无权限 - macOS 需在「系统设置 → 隐私与安全性」里分别开启辅助功能和屏幕录制两项；Windows 需允许应用的辅助功能权限。权限改完重启 App。

Q2：Browser Operator 启动失败 - 确认已安装 Chrome / Edge / Firefox 之一；确认是单显示器；确认 App Settings 里 VLM Provider 选对了对应服务商（动作解析依赖它）。

Q3：VLM 接口报错 / Agent 动作不对 - 检查 VLM Base URL 是否以 /v1/ 结尾；检查 API Key 额度；确认 VLM Provider 下拉项选的是「Hugging Face for UI-TARS-1.5」或「VolcEngine Ark for Doubao-1.5-UI-TARS」，选错会导致动作解析错位。

Q4：npx @agent-tars/cli 报 Node 版本错 - 该 CLI 要求 Node.js >= 22，升级 Node（nvm 安装 nvm install 22）后重试。

Q5：Remote Operator 用不了了 - 官方 Remote Operator 免费服务已于 2025-08-20 停止。需要远程控制时改走火山引擎 OS Agent 服务（官方 quick-start 里有中文部署模板链接）。

Q6：多显示器下 Agent 操作错位 - 官方当前版本只支持单显示器；多屏场景请先在系统显示设置里只保留一个主屏再用。

Q7：Agent 执行到一半停住/截图黑屏 - 先确认目标窗口没有被其他窗口完全遮挡；macOS 屏幕录制权限要授给 UI TARS 本身；再重发任务。

Q8：想自己二次开发 GUI 自动化 Agent - 不要魔改桌面 App，直接看仓库 docs/sdk.md（UI TARS SDK），按 SDK 方式组装 Computer Operator / Browser Operator。

Q9：Windows 下没有 Homebrew 怎么装？ - 直接从 Releases 页下载 Windows 安装包安装即可，Homebrew 只是 macOS 下的一条快捷路径。

Q10：模型部署成本高，有没有更省的用法？ - 用火山引擎方舟 Doubao-1.5-UI-TARS 按调用量付费；或自部署 UI-TARS-1.5-7B（7B 量级，单张消费级/数据中心卡可跑），用 OpenAI 兼容接口接 App。

六、部署注意事项与最佳实践

1. Provider 必须选对：桌面 App 的 VLM Provider 下拉项直接决定动作解析方式，这是最容易踩的坑。
2. 单显示器约束：多屏用户先切单屏，否则任务成功率明显下降。
3. 端点 URL 规范：Base URL 必须以 /v1/ 结尾，Key 与模型名一一对应。
4. 权限闭环：macOS 辅助功能 + 屏幕录制双权限缺一不可；Windows 注意应用辅助功能授权。
5. CLI 版本：Agent TARS CLI 已迭代到 v0.3.x，升级前看 Release Notes（沙箱、事件流等新能力在新版）。
6. 隐私边界：Agent 本体在本地，模型请求发往你配置的 VLM 端点；敏感操作（输密码、登账号）前想清楚截图内容会发给模型服务商。
7. Remote 已停服：不要再依赖官方免费 Remote Operator，远程需求走火山引擎 OS Agent 官方模板。
8. MCP 才是扩展方向：想接内部工具，优先用 MCP Server 生态，而不是改源码。
9. 模型选型：桌面 App 主打 UI-TARS-1.5 / Seed-1.5-VL 系列；Agent TARS CLI 兼容多种视觉模型（豆包视觉、Claude 等），按预算选。
10. 生产隔离：让 Agent 执行 shell 等危险操作时，开启 AIO Agent Sandbox 隔离，避免误操作宿主环境。

七、参考资料

• GitHub 仓库：https://github.com/bytedance/UI-TARS-desktop
• 快速开始文档：https://github.com/bytedance/UI-TARS-desktop/blob/main/docs/quick-start.md
• Agent TARS 官方站点：https://agent-tars.com
• Agent TARS 快速开始：https://agent-tars.com/guide/get-started/quick-start.html
• Agent TARS CLI（npm）：https://www.npmjs.com/package/@agent-tars/cli
• UI-TARS 模型（HuggingFace）：https://huggingface.co/ByteDance-Seed/UI-TARS-1.5-7B
• UI-TARS 模型部署文档：https://github.com/bytedance/UI-TARS/blob/main/README_deploy.md
• UI TARS SDK 文档：https://github.com/bytedance/UI-TARS-desktop/blob/main/docs/sdk.md
• 论文：https://arxiv.org/abs/2501.12326
• Releases 列表：https://github.com/bytedance/UI-TARS-desktop/releases