UI-TARS Desktop：ByteDance 开源桌面自动化 AI Agent 实战指南

为什么桌面自动化需要 AI Agent？

传统的桌面自动化工具（如 AutoHotkey、PyAutoGUI）依赖硬编码的坐标和像素匹配，UI 稍有变化就会失效。而 RPA 平台（如 UiPath、Automation Anywhere）虽然功能强大，但配置复杂、许可费用高昂，且对非标准界面的适应性有限。

AI Agent 的出现改变了这个局面。通过视觉理解 + 自然语言指令，Agent 可以像人类一样”看到”屏幕内容，理解界面布局，然后执行鼠标点击、键盘输入等操作。你只需要告诉它”打开 Excel，把 A 列的数据求和填到 B1”，它就能自己完成。

ByteDance 开源的 UI-TARS Desktop 正是这一方向的代表作。截至 2026 年 5 月，GitHub 星标已超过 12,000，是桌面自动化领域最活跃的开源项目之一。

UI-TARS 架构解析

UI-TARS 的技术栈分为三层：

感知层：截图 + OCR + UI 元素识别

截图捕获 → 视觉编码器(ViT) → UI 元素检测 → 结构化场景描述

Agent 每一步都会截取当前屏幕，通过视觉模型解析 UI 元素的位置、类型和文本内容。这个过程不依赖 DOM 或 Accessibility API，纯视觉驱动，因此可以操作任意应用。

决策层：多模态 LLM 推理

感知层的输出（结构化 UI 描述 + 截图）与用户指令一起送入多模态 LLM。模型需要：

1. 理解当前界面状态
2. 规划下一步操作
3. 输出具体的动作指令（点击坐标、输入文本、快捷键等）

UI-TARS 支持多种后端模型：

执行层：系统级操控

决策层输出的动作通过系统 API 执行：

interface Action {
  type: 'click' | 'doubleClick' | 'rightClick' | 'type' | 'hotkey' | 'scroll' | 'drag';
  coordinates?: { x: number; y: number };
  text?: string;
  keys?: string[];
}

macOS 使用 CoreGraphics API，Windows 使用 Win32 API，确保操作精确可靠。

本地部署实战

前置条件

• Node.js 18+
• Git
• 如果使用本地模型：NVIDIA GPU（VRAM ≥ 8GB）+ CUDA 12.x

Step 1：克隆并安装

git clone https://github.com/bytedance/UI-TARS-desktop.git
cd UI-TARS-desktop

# 安装依赖
npm install

# 构建桌面客户端
npm run build

Step 2：配置模型后端

在 config/settings.json 中选择模型：

{
  "model": {
    "provider": "openai",
    "apiKey": "sk-your-api-key",
    "model": "gpt-4o",
    "baseUrl": "https://api.openai.com/v1"
  },
  "safety": {
    "confirmBeforeExecute": true,
    "allowedApps": ["*"],
    "blockedActions": ["shutdown", "format"]
  }
}

如果使用本地模型，配置 Ollama 后端：

{
  "model": {
    "provider": "ollama",
    "model": "ui-tars:7b",
    "baseUrl": "http://localhost:11434"
  }
}

Step 3：启动并授权

npm run start

首次启动时，macOS 会要求授予”辅助功能”权限（System Settings → Privacy & Security → Accessibility），Windows 需要以管理员模式运行。

Step 4：执行第一个任务

在 UI-TARS 的输入框中输入自然语言指令：

打开系统计算器，计算 1024 * 768，然后截图保存到桌面

Agent 会依次执行：

1. 通过 Spotlight/开始菜单打开计算器
2. 逐步点击数字和运算符
3. 截图并保存

整个过程你可以在 UI-TARS 的操作日志中实时查看每一步的截图和决策。

高级用法：多步工作流

场景 1：批量数据录入

打开 Excel 文件 /Users/demo/data.xlsx，
从第 2 行开始，把 A 列的公司名逐个粘贴到浏览器的 CRM 搜索框中，
搜索后把搜索结果页面中的联系人姓名和电话复制回 Excel 的 C 列和 D 列

这个任务涉及跨应用操作（Excel ↔ 浏览器），传统 RPA 需要分别配置两个应用的自动化脚本，UI-TARS 只需一段自然语言描述。

场景 2：自动化测试

# 使用 Python SDK 编写自动化测试脚本
from uitars import Agent

agent = Agent(model="gpt-4o")

# 定义测试步骤
agent.execute("""
1. 打开 Chrome 并访问 http://localhost:3000
2. 在登录页面输入用户名 admin 和密码 test123
3. 点击登录按钮
4. 验证页面标题包含 "Dashboard"
5. 截图保存测试结果
""")

# 检查执行结果
assert agent.last_screenshot_contains("Dashboard")

场景 3：定时巡检

结合 cron 定时任务，实现无人值守的系统巡检：

# crontab -e
0 9 * * * cd /path/to/ui-tars && node scripts/run-task.js "检查 Grafana 仪表板是否有红色告警，如果有则截图并通过飞书发送给运维群"

与同类工具的对比

UI-TARS 最大的优势是本地优先 + 开源，适合对数据隐私有要求的企业场景。

常见坑与解决方案

1. 高 DPI 显示器坐标偏移

Retina 屏幕的逻辑坐标和物理坐标不一致，导致点击位置偏移：

{
  "display": {
    "scaleFactor": 2,
    "useLogicalCoordinates": true
  }
}

2. 弹窗干扰

系统通知或应用弹窗会打断任务执行。建议：

• 开启勿扰模式（macOS: Focus Mode / Windows: Do Not Disturb）
• 在配置中启用弹窗自动关闭："autoDismissDialogs": true

3. 操作速度过快

有些应用需要等待加载，Agent 操作过快会导致界面还没渲染就执行下一步：

{
  "execution": {
    "stepDelay": 500,
    "waitForIdle": true,
    "idleTimeout": 3000
  }
}

4. 截图模糊导致识别失败

确保截图分辨率足够。如果使用虚拟桌面或远程连接，建议设置至少 1920x1080 分辨率：

{
  "capture": {
    "quality": "high",
    "format": "png"
  }
}

安全最佳实践

桌面自动化涉及系统级权限，安全不容忽视：

1. 最小权限原则：在 allowedApps 中只列出需要操作的应用
2. 操作审计：启用 "logAllActions": true，记录每一步操作的截图和决策
3. 沙盒隔离：对于不信任的任务，在虚拟机中运行
4. API Key 管理：使用环境变量而非硬编码存储密钥
5. 网络隔离：如果使用本地模型，可以完全断开网络运行

小结

UI-TARS Desktop 让桌面自动化从”编写脚本”进化到”描述任务”。它的核心价值在于：

• 零代码自动化：自然语言描述即可执行复杂任务
• 跨应用操作：不受单一应用限制
• 本地部署：数据不出本机，满足合规要求
• 开源可定制：支持替换模型、扩展动作类型

对于需要大量重复性桌面操作的团队（测试、数据录入、运维巡检），UI-TARS 是值得尝试的工具。建议从简单任务开始，逐步验证稳定性后再用于生产环境。

项目地址：https://github.com/bytedance/UI-TARS-desktop