企业官网建设流程全解析

UI-TARS-desktop 如何设置 Max Loop 与 Loop Wait Time 控制任务执行轮次与截图等待

【免费下载链接】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 中执行任务时，Agent 按“轮次”工作：每一轮先对屏幕截图，把画面交给 VLM 预测下一步动作，再执行该动作，然后进入下一轮。任务步骤多时，可能因为达到轮次上限而中途被终止；目标界面有延迟加载时，截图又可能拍到中间状态。Max Loop与Loop Wait Time (ms)这两个 Chat 设置项正好分别控制“单轮任务最多跑多少轮”和“每轮截图前等多久”。本文给出它们的设置位置、取值范围、生效方式，以及跑任务后如何判断结果。

前提：已安装 UI-TARS Desktop，并且按 Quick Start 完成 VLM 配置（VLM Provider、VLM Base URL、VLM API KEY、VLM Model Name）。没有可用的模型就跑不了任务，也就无法验证这两项设置的效果。

两项设置在哪里：设置页的 Chat Settings

打开应用的Settings页面，Settings Configuration Guide 将这两项归在Chat Settings小节，界面上是两个数字输入框：

文档对两者的定义：

• Max Loop：“Maximum steps per conversation round”，即一轮对话中最多执行的步数；
• Loop Wait Time：“Waiting time for each loop”，对于需要一定时间才能完成的操作，该参数在截图前加入一段延迟，确保最终状态被正确记录。

界面上的输入框使用 zod 做范围校验：maxLoopCount为 25–200，loopIntervalInMs为 0–3000（见 chat.tsx）。默认值与主进程的初始设置一致（setting.ts 中maxLoopCount: 100、loopIntervalInMs: 1000）。

输入合法值后会立即写入本地存储ui_tars.setting（electron-store，见 setting.ts 与 chat.tsx 的自动保存逻辑），不需要额外的保存按钮；输入超出范围的值时校验失败，会保留原值。

可选路径：如果你用 preset 管理配置（见 Preset Management Guide），preset 的校验规则同样包含maxLoopCount（可选字段，范围 25–200），见 validate.ts。

这两个值如何作用于任务执行

桌面端启动任务前，会把两项设置传给 GUIAgent（runAgent.ts）：

maxLoopCount: settings.maxLoopCount, loopIntervalInMs: settings.loopIntervalInMs,

结合 Agent 主循环 GUIAgent.ts 可以看到具体行为：

1. Max Loop 限制总轮次。每轮开始先检查轮次计数，loopCnt >= maxLoopCount时任务被标记为错误并终止循环（L162-L170），产生的错误信息为Has reached max loop count（L546-L552）。
2. Loop Wait Time 是两轮之间的延迟。每轮动作执行完，若loopIntervalInMs > 0，Agent 先sleep对应毫秒数，再开始下一轮（L424-L432）。源码中对应的运行日志（示例）：

[GUIAgent] sleep for 1000ms before next loop

3. 截图环节自带重试。每轮先调用operator.screenshot()并允许重试，桌面端配置的截图重试上限为 5 次（runAgent.ts L217-L227）。若某一轮截图无效（解码不出宽高），该轮不占用轮次计数并重新计数错误（L202-L209）；截图错误累计达到上限时任务同样以SCREENSHOT_RETRY_ERROR终止（L172-L180）。

由此对应到使用判断：

• 任务较长、步骤多，容易“跑满轮次”结束 → 调大 Max Loop；
• 目标页面有加载、动画等延迟状态，截图常拍到中间状态 → 调大 Loop Wait Time (ms)；
• 填0表示两轮之间不额外等待。

操作步骤与结果判断

1. 打开 Settings，在 Chat 设置区找到Max Loop与Loop Wait Time (ms)，输入目标值；校验通过后立即生效并持久化。
2. 按 Quick Start 的操作方式：点击开始新会话，输入 GUI 操作指令，启动任务。
3. 根据运行结果判断：
   • 任务因轮次上限被终止时，错误信息包含Has reached max loop count；确认是该原因后，把 Max Loop 调大重跑；
   • 任务因截图失败终止时，错误为SCREENSHOT_RETRY_ERROR，与轮次设置无关，不要只靠调大 Max Loop 解决；
   • 调整 Loop Wait Time 后，可对比运行记录中相邻两轮截图的时间间隔，确认延迟已按设置插入（日志形式见上文示例）。

限制与已知差异

• 两项的有效范围由 UI 硬校验（[25, 200]与[0, 3000]），范围外输入不会写入。
• 桌面端 Max Loop 的默认值以 docs/setting.md 为准，为100；而 docs/sdk.md 中对 SDK 参数maxLoopCount的标注是 “(default: 25)”，两者口径不同，本文涉及桌面端设置时采用 docs/setting.md 的数值。
• 当前版本 UI-TARS Desktop 仅支持单显示器环境，多显示器配置可能导致部分任务失败（quick-start.md）；验证轮次与等待设置时请在单显示器下运行任务。

【免费下载链接】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