1. 项目概述：为什么UI-TARS桌面版的协作功能值得深挖？

最近在自动化测试和RPA（机器人流程自动化）的圈子里，UI-TARS Desktop（桌面版）的热度持续攀升。很多朋友在搜索“手把手部署ui-tars”、“codex桌面版安装教程”，核心诉求很明确：想找一个能稳定运行在个人电脑或服务器上，并且能方便地与他人协作的自动化工具。这正是UI-TARS桌面版相较于其云端版本或纯命令行版本的核心优势所在。它把强大的UI自动化能力封装成了一个带图形界面的本地应用，而“协作功能”则是将这个本地应用的价值从个人效率工具，升级为团队生产力平台的关键。

简单来说，UI-TARS桌面版的协作功能，解决的痛点就是“任务孤岛”。你辛辛苦苦写了一个自动登录系统、自动填报报表或者自动监控网页的脚本（在UI-TARS里通常称为“任务”或“流程”），它可能只存在于你的电脑上。当同事需要执行类似操作，或者你需要把任务部署到另一台机器上时，传统方式就是复制脚本文件、重新配置环境，繁琐且容易出错。而多用户自动化任务共享，就是要打破这个壁垒，实现“一次编写，多处运行；一人创建，团队复用”。

这不仅仅是文件共享那么简单。它涉及到任务资产（脚本、配置、依赖库）的集中管理、执行权限的分配、运行日志的集中查看，以及最关键的在多用户、多终端环境下保持任务稳定运行的能力。我看到很多搜索词如“ubuntu多用户远程桌面”、“win11 解决多用户同时远程连接教程”，这恰恰说明了用户在实际部署中遇到的真实场景：如何在服务器上搭建一个环境，让多个团队成员都能连接上去，使用同一个UI-TARS桌面版实例来管理和运行任务。这正是本指南要深入拆解的核心。

2. 核心思路拆解：从单机到协同的架构演进

要实现多用户共享，我们不能简单地把UI-TARS桌面版当成一个普通的单机软件来用。需要从架构层面理解其协作模式。根据网络上的讨论和官方文档的蛛丝马迹，UI-TARS桌面版的协作通常通过两种路径实现，这也是很多“codex桌面版使用教程”里语焉不详的部分。

2.1 路径一：远程桌面模式下的共享会话

这是最直观、门槛相对较低的方式，对应搜索热词“win11 远程多用户”、“winserver2022设置多用户远程桌面服务”。其核心思路是：将UI-TARS桌面版安装在一台性能较好的中央服务器（可以是Windows Server、安装了桌面环境的Linux服务器如Ubuntu，甚至是一台始终开机的PC），并在这台服务器上配置支持多用户同时登录的远程桌面服务（如Windows的RDS，或Linux下的Xrdp、VNC等）。

为什么选择这种方式？

• 环境统一：所有用户连接的都是同一个UI-TARS实例，任务脚本、依赖的Python库、浏览器驱动版本完全一致，彻底避免了“在我机器上能跑，在你那就报错”的经典问题。
• 资源集中：自动化任务往往需要占用CPU、内存和网络资源。集中部署便于监控和管理资源消耗，也方便对接公司内网的其他系统。
• 数据安全：任务脚本作为公司资产，保留在中央服务器上，避免了通过聊天工具传来传去导致版本混乱或泄露。

这种模式的局限性：

• 并发限制：受服务器硬件和远程桌面协议性能限制，同时操作的用户数有限。
• 操作冲突：如果多个用户同时编辑同一个任务，需要良好的版本管理习惯（通常需要结合Git）。
• 网络依赖：用户需要稳定的网络连接才能流畅操作。

2.2 路径二：客户端-服务器（C/S）架构下的任务调度

这是一种更高级、更工程化的方式，隐约体现在“ui-tars远程api调用”、“hermes agent 桌面版”等搜索词中。在这种架构下，UI-TARS桌面版本身或其核心引擎作为“服务器端”在后台运行，提供一套API（可能是HTTP API、RPC或消息队列）。用户则通过一个轻量级的“客户端”（可能是Web界面、命令行工具CLI，或另一个简化版的桌面程序）来提交任务、查询状态、下载结果。

为什么这是更优的长期方案？

• 职责分离：用户（客户端）只关心业务逻辑（创建、触发任务），无需关心任务在哪个具体的桌面环境执行。服务器端负责资源调度、任务队列管理和稳定执行。
• 高并发与弹性：可以更容易地实现任务队列，支持大量异步任务。甚至可以结合Docker等技术，实现执行环境的动态创建与销毁。
• 体验更佳：客户端可以做得非常轻量，响应迅速，不受远程桌面延迟和卡顿的影响。

实际部署中的混合形态：在大多数中小团队的实际场景中，往往是两种模式的结合。比如，开发人员通过远程桌面连接到服务器，使用UI-TARS桌面版的图形化界面进行任务的开发、调试和录制（因为图形化操作更直观）。然后将调试好的任务“发布”到某个中央任务库。其他非开发人员（如运营、测试）则通过一个简单的Web门户或脚本，来触发这些已发布的任务执行。这个“中央任务库”和“执行引擎”，可能就是运行在服务器后台的UI-TARS服务。

理解了这两种核心思路，我们接下来的步骤就有了明确的指导思想：我们的目标是搭建一个支持多用户通过远程桌面进行任务开发，同时具备任务集中存储和API调用能力的协作环境。

3. 环境准备与部署：打造稳定的协作基石

这一步是后续所有操作的基础，也是最容易踩坑的地方。很多“安装失败”、“启动报错”的问题都源于此。我们将以一台安装Ubuntu 22.04 LTS桌面版的服务器为例进行说明，Windows Server的思路类似，但具体操作不同。

3.1 服务器系统准备与优化

首先，为什么选择Linux服务器？从“ubuntu桌面版搭载服务器”、“麒麟v10桌面版”等搜索词可以看出，Linux在服务器领域的稳定性和资源占用优势是公认的。对于UI自动化这种可能需要长时间运行、占用图形资源的应用，一个轻量级的Linux桌面环境比Windows Server通常更具性价比。

关键操作与原理：

1. 系统安装：安装Ubuntu 22.04时，务必选择“Ubuntu Desktop”版本而非Server版。Server版默认没有图形界面，后续需要额外安装，更麻烦。
2. 用户管理：为每个需要使用的团队成员创建独立的系统账户（如user1,user2）。这是多用户隔离的基础。使用sudo adduser username命令创建。

   注意：强烈建议为UI-TARS的运行单独创建一个系统账户（如uitars），避免使用root或个人账户直接运行服务，以提高安全性。

3. 远程桌面服务安装：我们将使用Xrdp，它是一个开源的RDP（远程桌面协议）服务器，让用户能用Windows自带的远程桌面连接工具（mstsc.exe）访问Linux桌面。

   sudo apt update sudo apt install xrdp -y sudo systemctl enable xrdp sudo systemctl start xrdp

   安装后，默认监听3389端口。请确保服务器防火墙放行该端口：sudo ufw allow 3389。
4. 解决多用户同时登录问题：默认的Ubuntu桌面环境（GNOME）对多用户远程会话支持不友好。我们需要切换到更轻量级、对多会话支持更好的桌面环境，如Xfce或Xubuntu-desktop。

   sudo apt install xubuntu-desktop -y

   安装后，编辑Xrdp的启动配置文件，告诉它使用Xfce会话：

   echo “xfce4-session” > ~/.xsession # 将上面的配置复制到 /etc/xrdp/startwm.sh 的末尾（在最后一行 ‘. /etc/X11/Xsession’ 之前） sudo nano /etc/xrdp/startwm.sh # 在文件末尾，在 ‘. /etc/X11/Xsession’ 这一行之前，添加一行： # xfce4-session

   重启xrdp服务：sudo systemctl restart xrdp。
5. 图形驱动与虚拟显示：对于无物理显示器的服务器（如云服务器），需要配置虚拟显示驱动，否则UI自动化可能无法启动浏览器。安装xvfb(X Virtual Framebuffer)：

   sudo apt install xvfb -y

   可以配置一个服务，让系统启动时自动运行Xvfb，创建一个虚拟显示器（如:99）。

3.2 UI-TARS Desktop核心部署

这是“codex桌面版安装”的核心步骤。假设我们已经下载好了UI-TARS Desktop的Linux安装包（例如一个.AppImage文件或.deb包）。

部署最佳实践：

1. 安装位置：不要安装在个人用户目录下。建议安装在/opt目录下，方便所有用户访问（或通过共享方式访问）。

   sudo mkdir -p /opt/uitars # 假设安装包是 uitars-desktop-linux.AppImage sudo cp uitars-desktop-linux.AppImage /opt/uitars/ sudo chmod +x /opt/uitars/uitars-desktop-linux.AppImage

2. 依赖安装：UI-TARS通常依赖Python、Node.js、Chromium浏览器等。在系统级别安装这些依赖，确保所有用户环境一致。

   sudo apt install python3-pip chromium-browser -y # 安装可能需要的Python库，如 selenium, playwright等（具体看UI-TARS要求） sudo pip3 install selenium playwright sudo playwright install chromium

3. 以服务方式运行（关键）：为了实现路径二（C/S架构）的能力，我们需要让UI-TARS的核心服务在后台运行，而不是依赖于某个用户的图形会话。这通常需要研究UI-TARS是否提供了“无头模式”或“服务模式”的启动参数。
   • 查找启动参数：运行./uitars-desktop-linux.AppImage --help，查看是否有--headless,--server,--port等参数。
   • 创建系统服务：如果支持，我们可以创建一个Systemd服务文件/etc/systemd/system/uitars-server.service：

     [Unit] Description=UI-TARS Automation Server After=network.target xvfb.service [Service] Type=simple User=uitars # 使用专门的用户运行 Environment="DISPLAY=:99" # 指向虚拟显示器 ExecStart=/opt/uitars/uitars-desktop-linux.AppImage --headless --server --port 8080 Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target

   然后启动并启用服务：

   sudo systemctl daemon-reload sudo systemctl start uitars-server sudo systemctl enable uitars-server

   这样，UI-TARS的核心服务就在后台启动，并监听8080端口（假设）提供API。

3.3 共享存储空间配置

任务脚本、配置文件、数据文件需要在用户间共享。最简单的方式是使用一个共享目录，并设置合适的权限。

1. 创建共享目录：

   sudo mkdir -p /shared/uitars-projects sudo chown -R uitars:uitars /shared/uitars-projects # 所有者设为uitars用户 sudo chmod -R 775 /shared/uitars-projects # 允许同组用户读写

2. 将用户加入共享组：将需要协作的用户（如user1, user2）都加入到uitars组。

   sudo usermod -a -G uitars user1 sudo usermod -a -G uitars user2

   用户需要重新登录（或开启新会话）才能使组权限生效。
3. 在UI-TARS中设置默认项目路径：每个用户通过远程桌面登录后，首次打开UI-TARS桌面版时，将其项目工作区指向/shared/uitars-projects。这样，所有人创建的任务都保存在同一个地方。

4. 5步实现多用户任务共享实操

环境就绪后，我们进入核心的五个步骤。这五步是一个从基础到进阶的完整工作流。

4.1 第一步：用户接入与权限初始化

团队成员使用Windows“远程桌面连接”，输入服务器IP地址，使用各自的系统账号（user1, user2）登录。成功登录后，会看到一个独立的Xfce桌面环境。

首次登录后的必须操作：

1. 打开终端，验证共享目录权限：ls -la /shared/uitars-projects，应该可以看到目录属于uitars组，并且自己有读写权限。
2. 启动UI-TARS桌面版。通常可以通过在终端进入安装目录执行./uitars-desktop-linux.AppImage，或者如果已创建桌面快捷方式则直接点击。
3. 在UI-TARS中，设置工作区或项目根目录为/shared/uitars-projects/<你的名字>或直接使用根目录。建议每人建立自己的子文件夹，便于管理，例如/shared/uitars-projects/user1_scripts。

实操心得：建议为所有团队成员准备一份简单的“入门检查清单”，包含上述步骤和服务器连接信息。很多协作失败始于第一步的环境不一致。

4.2 第二步：标准化任务开发与版本控制

在共享目录中开发任务时，必须引入最基本的版本管理规范，否则很快就会陷入混乱。

1. 项目结构标准化：约定一个通用的项目结构。例如：

   /shared/uitars-projects/ ├── common/ # 公共模块，如登录函数、工具类 │ ├── login.py │ └── utils.py ├── project_a/ # 项目A │ ├── main.flow # UI-TARS任务流文件 │ ├── config.json # 配置文件 │ └── README.md └── project_b/ # 项目B └── ...

2. 初始化Git仓库：在/shared/uitars-projects目录下执行git init。虽然是在共享文件夹，但Git能完美记录每个人的更改，解决冲突。

   cd /shared/uitars-projects git init git add . git commit -m “初始提交”

3. 使用.gitignore：创建.gitignore文件，忽略临时文件、日志、截图等不需要版本控制的文件，例如*.log,screenshots/,tmp/。
4. 开发流程：每个成员在开发新功能或修复bug时，应创建新的分支（git checkout -b feature-xxx），完成后合并回主分支（git merge）。UI-TARS的任务文件（可能是JSON、YAML或特定格式）是文本文件，完全可以用Git进行版本对比和合并。

4.3 第三步：任务资产集中管理与复用

这是协作的核心价值。避免重复造轮子。

1. 创建公共组件库：在UI-TARS中，通常支持将一段通用的操作序列（如“登录OA系统”、“导出Excel”）保存为“组件”、“模块”或“子流程”。鼓励团队成员将验证稳定的流程片段保存到共享目录的common/components文件夹下。
2. 参数化配置：将任务中可能变化的部分（如URL、用户名、文件路径）提取为参数或外部配置文件（如config.json）。这样，同一个任务脚本，不同用户通过传入不同的配置文件，就能执行不同的业务。例如，一个数据抓取任务，其目标网站和存储数据库的配置就可以外置。
3. 文档化：在每个任务或组件的目录下，强制要求一个简短的README.md，说明其功能、输入参数、输出结果、依赖环境。这能极大降低其他成员的学习成本。

4.4 第四步：通过API实现任务调度与触发（进阶）

当任务开发并测试完成后，就可以将其“服务化”，供其他系统或非技术人员调用。这对应“ui-tars远程api调用”的需求。

1. 确认API模式：启动我们之前配置的UI-TARS后台服务（如果支持）。假设服务运行在http://服务器IP:8080。
2. 探索API端点：通过访问http://服务器IP:8080/docs或http://服务器IP:8080/api（如果提供）查看Swagger UI或API文档。常见的API可能包括：
   • POST /api/tasks/run：传入任务ID或任务文件路径，触发执行。
   • GET /api/tasks/status/{task_id}：查询任务执行状态。
   • GET /api/tasks/log/{task_id}：获取任务执行日志。
3. 编写调用客户端：你可以用任何语言（Python、Node.js、Shell）编写一个简单的客户端脚本。以下是一个Python示例：

   import requests import json server_url = “http://your-server-ip:8080” task_payload = { “project_path”: “/shared/uitars-projects/project_a”, “main_flow”: “main.flow”, “parameters”: {“url”: “https://example.com”, “headless”: True} } response = requests.post(f“{server_url}/api/tasks/run”, json=task_payload) if response.status_code == 200: task_info = response.json() task_id = task_info[‘task_id’] print(f“任务已提交，ID: {task_id}”) # 可以轮询查询状态 else: print(“任务提交失败:”, response.text)

4. 集成到其他系统：将这个客户端脚本集成到你的运维平台、监控系统、CI/CD流水线（如Jenkins）或甚至是一个简单的内部网页按钮上。这样，业务人员只需点击按钮，就能触发后台复杂的UI自动化任务。

4.5 第五步：监控、日志与错误处理闭环

协作环境下的任务执行，必须有统一的监控和排错手段。

1. 集中日志收集：配置UI-TARS服务，将任务日志统一输出到指定文件，如/var/log/uitars/tasks.log，并配置日志轮转（logrotate）。确保日志文件对所有协作用户可读。
2. 执行状态看板：如果UI-TARS服务未提供状态看板，可以自己实现一个简单的。通过定时调用GET /api/tasksAPI，获取所有任务状态，用Flask等框架快速搭建一个状态监控网页，显示任务列表、当前状态（运行中、成功、失败）、开始时间、耗时等。
3. 失败告警机制：在调用API的客户端脚本中，增加对失败状态的判断。一旦检测到任务失败，立即通过邮件、钉钉、企业微信等Webhook发送告警信息，附上任务ID和日志片段。
4. 截图与录像归档：UI自动化失败时，截图和操作录像是宝贵的排错资料。在任务配置中，开启失败自动截图功能，并将截图文件保存在共享目录下以任务ID和时间戳命名的文件夹中。定期归档清理。

5. 常见问题与深度排错指南

在实际部署和运行中，你一定会遇到下面这些问题。这里是我踩过坑后总结的解决方案。

5.1 远程桌面连接成功，但UI-TARS无法启动或白屏

现象：用户通过远程桌面登录后，双击UI-TARS图标，程序无法启动，或启动后主窗口空白（对应“claude code桌面版打开窗口空白”）。

排查思路：

1. 检查图形环境：在远程桌面的终端里运行echo $DISPLAY。正常应该显示类似:10.0或:100.0。如果为空或不对，可能是Xrdp配置问题。尝试在终端里直接执行DISPLAY=:xx.0 ./uitars-desktop-linux.AppImage（其中xx是$DISPLAY的值）来启动。
2. 检查依赖库：UI-TARS的桌面版可能依赖特定的图形库（如GTK、Qt）。尝试安装通用图形库：

   sudo apt install libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 xdg-utils -y

3. 查看应用日志：尝试从终端启动，观察终端输出的错误信息。通常会有动态链接库（.so）缺失的明确提示。
4. 虚拟显示缓冲：如果是在无显示器的服务器上，确保Xvfb服务已启动，并且UI-TARS的启动环境变量DISPLAY指向了正确的虚拟显示器（如:99）。

5.2 多用户同时操作时任务执行冲突

现象：用户A和用户B同时运行了操作同一个网站的任务，导致登录态混乱、页面元素互相干扰。

解决方案：

1. 浏览器实例隔离：这是根本解决方法。确保UI-TARS的每个任务启动时，都使用独立的、干净的浏览器用户数据目录（User Data Dir）。在任务配置或代码中，为每个任务或每次运行动态指定一个唯一的临时目录。
   • Playwright/Puppeteer示例：

     import tempfile user_data_dir = tempfile.mkdtemp(prefix=“chrome_profile_”) browser = await playwright.chromium.launch_persistent_context(user_data_dir, headless=False)

   • Selenium示例：通过ChromeOptions的--user-data-dir参数指定。
2. 任务队列化：对于操作同一关键资源（如同一个后台管理系统）的任务，不要允许并发执行。可以在服务器端实现一个简单的任务队列（例如使用Redis的List结构），任务触发后先进入队列，由单个消费者顺序执行。
3. 使用无头模式：在调度执行的服务器端，任务尽量以无头模式运行，减少图形资源冲突，也避免多个远程桌面会话对浏览器窗口的争抢。

5.3 任务在服务器端后台运行时无法操作浏览器

现象：通过API调用的任务在后台服务中执行失败，日志提示无法启动浏览器或找不到元素。

排查与解决：

1. 确保浏览器可执行：在服务器上，确保chromium-browser或google-chrome-stable已安装且位于系统PATH中。可以通过which chromium-browser确认。
2. 解决无头环境依赖：无头服务器通常缺少一些浏览器运行所需的库。安装以下包：

   sudo apt install -y wget ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0 \ libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 \ libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 \ libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 \ libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 lsb-release \ xdg-utils

3. 虚拟显示缓冲区（Xvfb）：这是最关键的一步。浏览器（即使是无头模式）有时也需要一个显示环境。确保Xvfb服务已启动，并在启动UI-TARS服务或任务脚本前，设置DISPLAY=:99环境变量。

   # 启动Xvfb在:99显示端口，深度24，屏幕尺寸1920x1080 Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 # 然后再启动你的任务脚本或UI-TARS服务

4. 浏览器驱动匹配：确保使用的chromedriver或playwright的浏览器版本与系统安装的Chrome/Chromium版本兼容。不匹配是导致启动失败的常见原因。

5.4 权限问题导致文件读写失败

现象：用户A创建的任务，用户B无法读取或执行；通过API触发的任务，无法写入共享目录。

解决方案：

1. 遵循Linux权限原则：如前所述，使用共享组（uitars）并设置目录权限为775，文件权限为664。确保所有协作用户都在该组内。
2. SetGID位：对于共享目录/shared/uitars-projects，可以设置SetGID位，这样在该目录下创建的任何新文件，其所属组都会自动继承目录的组（uitars）。

   sudo chmod g+s /shared/uitars-projects

3. API服务用户：运行UI-TARS后台服务的用户（如uitars）必须对共享目录有读写权限。并且，通过API创建的文件，其所有者是uitars，需要确保其他组用户也能读写（通过775/664权限实现）。
4. 小心umask：用户的umask设置会影响新创建文件的默认权限。可以在共享目录下创建一个.bashrc或全局配置文件，为相关用户设置宽松的umask，例如umask 0002（对应文件权限664，目录权限775）。

5.5 性能瓶颈与优化建议

当用户和任务数量增多后，可能会遇到性能问题。

1. 服务器资源监控：使用htop,nvidia-smi（如果有GPU）监控CPU、内存、GPU使用情况。UI自动化，尤其是非无头模式，非常消耗内存和CPU。
2. 限制并发任务数：在UI-TARS服务端或任务调度器中，设置最大并发任务数。例如，限制同时运行的浏览器实例不超过5个，防止服务器过载。
3. 使用轻量级方案：
   • 尽可能使用无头模式：无头模式比图形模式节省大量资源。
   • 复用浏览器上下文：对于一系列短任务，可以考虑启动一个浏览器实例，在其下创建多个独立的“上下文”来执行不同任务，而不是为每个任务都完全启动和关闭一个浏览器进程。Playwright和Puppeteer支持此功能。
   • 优化选择器：低效的页面元素选择器（如复杂的XPath）会显著增加脚本执行时间。尽量使用稳定的ID、CSS选择器。
4. 考虑分布式执行：如果单台服务器成为瓶颈，可以考虑引入简单的分布式架构。例如，搭建多个UI-TARS执行节点（Worker），由一个中心调度器（Master）通过消息队列（如Redis, RabbitMQ）分发任务。这对应了更高级的“hermes agent”这类架构的探索方向。

部署和运维一个稳定的多用户UI-TARS协作环境，就像搭建一个小型的基础设施。它不仅仅是安装软件，更是对权限、流程、监控和排错体系的构建。从简单的远程桌面共享，到通过API实现自动化调度，每一步都解决了团队协作中的具体痛点。最深的体会是，标准化和文档化是协作能否持续下去的关键。再好的工具，没有约定俗成的使用规范，最终也会变得混乱不堪。建议在团队内推行一个简单的“任务开发模板”和“提交检查清单”，这能省去未来大量的沟通和维护成本。当一切就绪后，你会发现，自动化不再是某个人的“黑魔法”，而真正成为了整个团队触手可及的生产力。