1. 桌面自动化这件事UI-TARS 到底解决了什么字节跳动开源的 UI-TARS 是一套原生 GUI 代理模型它把感知、推理、定位、记忆全部塞进一个视觉语言模型里不需要你预先写工作流也不需要手动维护一堆选择器规则直接看屏幕截图就能决定下一步点哪里、输入什么。适合谁适合那些想让桌面软件自动跑流程、又不想被商业方案按年付费卡脖子的开发者尤其是做 RPA、测试自动化、跨端操作编排的团队。Manus 之前火的时候很多人拿它做浏览器和桌面任务演示但实际落地会发现两个问题一是长任务跑到二三十步之后成功率断崖式下跌二是闭源方案你没法改内部逻辑遇到特定软件界面就卡住。UI-TARS 走的是端到端纯视觉路线官方在 OSWorld 这类基准上给出的长任务数据比传统拼接方案稳而且代码全开你能自己调 prompt、换模型后端、加记忆策略。我这次实测的重点不是跑分而是把它接到真实桌面环境里用 TaoToken 统一 Key 做模型调用层验证从配置到执行再到结果回读的完整链路。下面直接给可复制的 config.toml 骨架和 settings.json 片段你照着填就能跑。2. TaoToken 前置统一 Key 怎么拿、怎么配UI-TARS 本身是模型加执行器它需要调用一个视觉语言模型来做屏幕理解和动作决策。TaoToken 在这里的角色是统一 API 入口你不需要分别去开多家模型的 Key一个 Key 就能在模型对话、Coding Plan、API 调用之间切换。先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册然后进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建 API Key。如果你主要跑长期编码或 Agent 任务建议直接看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 额度模型更适合连续多步调用。拿到 Key 之后API 基地址用 https://taotoken.net/api 注意这个地址不加 UTM 参数直接写进配置文件即可。模型对话调试可以用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 先验证 Key 是否通。注意Key 只存在本地配置文件或环境变量里不要提交到 Git。UI-TARS 的 config.toml 和 settings.json 都要加进 .gitignore。3. 可复制配置config.toml 骨架与 settings.json 片段UI-TARS 的配置分两层一层是模型后端连接放在 config.toml一层是执行器行为放在 settings.json。下面是我实测能跑通的骨架。3.1 config.toml 模型接入骨架[model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model_name gpt-4o max_tokens 4096 temperature 0.2 timeout 120 [agent] max_steps 50 screenshot_interval 1.5 action_delay 0.8 memory_window 10 save_trajectory true trajectory_dir ./runs [executor] platform windows coordinate_scale 1.0 click_duration 0.05 type_interval 0.03这里 base_url 写 TaoToken 的 API 地址model_name 按你实际用的视觉模型填。temperature 建议压到 0.2 以下GUI 任务需要稳定决策太发散容易乱点。max_steps 先设 50跑通后再按任务复杂度调。3.2 settings.json 执行器配置片段{ ui_tars: { perception: { screenshot_format: png, resize_width: 1280, resize_height: 720, ocr_fallback: true }, action_space: { click: true, double_click: true, right_click: true, type: true, scroll: true, drag: true, hotkey: true }, safety: { confirm_before_delete: true, blocked_apps: [regedit, cmd], max_retry_per_step: 3 }, logging: { level: info, save_screenshots: true, log_dir: ./logs } } }blocked_apps 里我加了 regedit 和 cmd防止 Agent 在探索阶段误操作系统工具。你如果跑的是受控测试机可以按需放开。screenshot_format 用 png 保证清晰度resize 到 1280x720 是为了控制 token 消耗实测这个分辨率下小图标仍可识别。3.3 环境变量方式推荐不想把 Key 写进文件的话用环境变量export TAOTOKEN_API_KEYsk-你的TaoTokenKey export TAOTOKEN_BASE_URLhttps://taotoken.net/api然后 config.toml 里 api_key 留空或写${TAOTOKEN_API_KEY}UI-TARS 启动时会自动读取。4. 验证请求从单步截图到完整任务执行配置写完先别急着跑复杂任务。按下面三步验证每步都有明确的成功标志。4.1 第一步验证 Key 和模型连通用 curl 直接打 TaoToken 的模型对话接口确认 Key 有效curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 回复 OK}], max_tokens: 10 }返回里出现content: OK就说明 Key 和网络都通。如果报 401检查 Key 是否复制完整报 404检查 base_url 是否多了斜杠。4.2 第二步单步截图理解测试启动 UI-TARS 的 dry-run 模式只做感知不做动作python -m ui_tars.run --config config.toml --dry-run --task 描述当前屏幕内容成功标志终端输出对当前桌面的文字描述比如「屏幕中央有一个浏览器窗口地址栏显示 example.com左上角有三个标签页」。如果输出为空或报错看 logs 目录下的截图是否正常生成。4.3 第三步完整 GUI 任务执行跑一个可复现的小任务打开记事本输入一段文字保存到指定路径。python -m ui_tars.run \ --config config.toml \ --task 打开记事本输入 Hello UI-TARS保存到 D:/test/hello.txt \ --max-steps 20执行过程中你会看到它先截图定位任务栏点击记事本图标等待窗口出现再截图定位输入区模拟键盘输入最后用快捷键保存。跑完后检查 D:/test/hello.txt 是否存在且内容正确。实测下来这个任务在 8 到 12 步内完成成功率取决于记事本图标在任务栏的位置是否被遮挡。如果任务栏图标被折叠它会先点展开箭头再找多花两三步。5. 本篇常见错排查5.1 报错Connection refused 或 timeout先确认 base_url 写的是 https://taotoken.net/api 而不是带 UTM 的官网地址。API 地址不加参数。如果公司网络有出口限制检查是否允许访问该域名。timeout 设 120 秒视觉模型处理大截图会慢一些。5.2 报错Model not foundmodel_name 填的模型名必须是 TaoToken 支持的。去模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 看可用列表别直接抄别处的模型名。视觉任务要选支持图片输入的模型。5.3 点击位置偏移这是坐标缩放问题。config.toml 里 coordinate_scale 默认 1.0如果你系统缩放是 125% 或 150%要改成 1.25 或 1.5。另外 screenshot 的 resize 尺寸和实际屏幕比例不一致也会偏保持 16:9 比例最稳。5.4 任务跑到一半卡住看 logs 里最后一张截图通常是弹窗遮挡或加载等待不够。把 action_delay 从 0.8 调到 1.5screenshot_interval 从 1.5 调到 2.0。如果某个软件启动慢可以在任务描述里加「等待 3 秒」这类指令UI-TARS 会解析成等待动作。5.5 保存文件路径报错Windows 路径用正斜杠或双反斜杠。任务描述里写 D:/test/hello.txt 比 D:\test\hello.txt 更稳避免转义问题。目标目录要提前存在Agent 不会自动建文件夹。6. 接入文档与后续调试入口上面这套配置跑通后你手里就有一个可用的开源 GUI Agent 底座了。接下来调优方向主要是三块任务描述怎么写得更明确、记忆窗口开多大、以及针对特定软件做动作白名单。Key 管理和额度查看在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 接入细节和参数说明看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你要接 Claude Code 或 Anthropic 风格的 Agent 流程参考 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 里的配置方式和 UI-TARS 的模型层可以共用同一个 Key。我踩过的坑是一开始把 max_steps 设成 100结果 Agent 在找不到目标时反复截图重试烧了不少 token。后来改成 50 并加上 max_retry_per_step3单任务消耗降了四成。你先按 50 跑稳定后再按任务类型微调。
1. 桌面自动化这件事UI-TARS 到底解决了什么字节跳动开源的 UI-TARS 是一套原生 GUI 代理模型它把感知、推理、定位、记忆全部塞进一个视觉语言模型里不需要你预先写工作流也不需要手动维护一堆选择器规则直接看屏幕截图就能决定下一步点哪里、输入什么。适合谁适合那些想让桌面软件自动跑流程、又不想被商业方案按年付费卡脖子的开发者尤其是做 RPA、测试自动化、跨端操作编排的团队。Manus 之前火的时候很多人拿它做浏览器和桌面任务演示但实际落地会发现两个问题一是长任务跑到二三十步之后成功率断崖式下跌二是闭源方案你没法改内部逻辑遇到特定软件界面就卡住。UI-TARS 走的是端到端纯视觉路线官方在 OSWorld 这类基准上给出的长任务数据比传统拼接方案稳而且代码全开你能自己调 prompt、换模型后端、加记忆策略。我这次实测的重点不是跑分而是把它接到真实桌面环境里用 TaoToken 统一 Key 做模型调用层验证从配置到执行再到结果回读的完整链路。下面直接给可复制的 config.toml 骨架和 settings.json 片段你照着填就能跑。2. TaoToken 前置统一 Key 怎么拿、怎么配UI-TARS 本身是模型加执行器它需要调用一个视觉语言模型来做屏幕理解和动作决策。TaoToken 在这里的角色是统一 API 入口你不需要分别去开多家模型的 Key一个 Key 就能在模型对话、Coding Plan、API 调用之间切换。先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册然后进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建 API Key。如果你主要跑长期编码或 Agent 任务建议直接看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 额度模型更适合连续多步调用。拿到 Key 之后API 基地址用 https://taotoken.net/api 注意这个地址不加 UTM 参数直接写进配置文件即可。模型对话调试可以用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 先验证 Key 是否通。注意Key 只存在本地配置文件或环境变量里不要提交到 Git。UI-TARS 的 config.toml 和 settings.json 都要加进 .gitignore。3. 可复制配置config.toml 骨架与 settings.json 片段UI-TARS 的配置分两层一层是模型后端连接放在 config.toml一层是执行器行为放在 settings.json。下面是我实测能跑通的骨架。3.1 config.toml 模型接入骨架[model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model_name gpt-4o max_tokens 4096 temperature 0.2 timeout 120 [agent] max_steps 50 screenshot_interval 1.5 action_delay 0.8 memory_window 10 save_trajectory true trajectory_dir ./runs [executor] platform windows coordinate_scale 1.0 click_duration 0.05 type_interval 0.03这里 base_url 写 TaoToken 的 API 地址model_name 按你实际用的视觉模型填。temperature 建议压到 0.2 以下GUI 任务需要稳定决策太发散容易乱点。max_steps 先设 50跑通后再按任务复杂度调。3.2 settings.json 执行器配置片段{ ui_tars: { perception: { screenshot_format: png, resize_width: 1280, resize_height: 720, ocr_fallback: true }, action_space: { click: true, double_click: true, right_click: true, type: true, scroll: true, drag: true, hotkey: true }, safety: { confirm_before_delete: true, blocked_apps: [regedit, cmd], max_retry_per_step: 3 }, logging: { level: info, save_screenshots: true, log_dir: ./logs } } }blocked_apps 里我加了 regedit 和 cmd防止 Agent 在探索阶段误操作系统工具。你如果跑的是受控测试机可以按需放开。screenshot_format 用 png 保证清晰度resize 到 1280x720 是为了控制 token 消耗实测这个分辨率下小图标仍可识别。3.3 环境变量方式推荐不想把 Key 写进文件的话用环境变量export TAOTOKEN_API_KEYsk-你的TaoTokenKey export TAOTOKEN_BASE_URLhttps://taotoken.net/api然后 config.toml 里 api_key 留空或写${TAOTOKEN_API_KEY}UI-TARS 启动时会自动读取。4. 验证请求从单步截图到完整任务执行配置写完先别急着跑复杂任务。按下面三步验证每步都有明确的成功标志。4.1 第一步验证 Key 和模型连通用 curl 直接打 TaoToken 的模型对话接口确认 Key 有效curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 回复 OK}], max_tokens: 10 }返回里出现content: OK就说明 Key 和网络都通。如果报 401检查 Key 是否复制完整报 404检查 base_url 是否多了斜杠。4.2 第二步单步截图理解测试启动 UI-TARS 的 dry-run 模式只做感知不做动作python -m ui_tars.run --config config.toml --dry-run --task 描述当前屏幕内容成功标志终端输出对当前桌面的文字描述比如「屏幕中央有一个浏览器窗口地址栏显示 example.com左上角有三个标签页」。如果输出为空或报错看 logs 目录下的截图是否正常生成。4.3 第三步完整 GUI 任务执行跑一个可复现的小任务打开记事本输入一段文字保存到指定路径。python -m ui_tars.run \ --config config.toml \ --task 打开记事本输入 Hello UI-TARS保存到 D:/test/hello.txt \ --max-steps 20执行过程中你会看到它先截图定位任务栏点击记事本图标等待窗口出现再截图定位输入区模拟键盘输入最后用快捷键保存。跑完后检查 D:/test/hello.txt 是否存在且内容正确。实测下来这个任务在 8 到 12 步内完成成功率取决于记事本图标在任务栏的位置是否被遮挡。如果任务栏图标被折叠它会先点展开箭头再找多花两三步。5. 本篇常见错排查5.1 报错Connection refused 或 timeout先确认 base_url 写的是 https://taotoken.net/api 而不是带 UTM 的官网地址。API 地址不加参数。如果公司网络有出口限制检查是否允许访问该域名。timeout 设 120 秒视觉模型处理大截图会慢一些。5.2 报错Model not foundmodel_name 填的模型名必须是 TaoToken 支持的。去模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 看可用列表别直接抄别处的模型名。视觉任务要选支持图片输入的模型。5.3 点击位置偏移这是坐标缩放问题。config.toml 里 coordinate_scale 默认 1.0如果你系统缩放是 125% 或 150%要改成 1.25 或 1.5。另外 screenshot 的 resize 尺寸和实际屏幕比例不一致也会偏保持 16:9 比例最稳。5.4 任务跑到一半卡住看 logs 里最后一张截图通常是弹窗遮挡或加载等待不够。把 action_delay 从 0.8 调到 1.5screenshot_interval 从 1.5 调到 2.0。如果某个软件启动慢可以在任务描述里加「等待 3 秒」这类指令UI-TARS 会解析成等待动作。5.5 保存文件路径报错Windows 路径用正斜杠或双反斜杠。任务描述里写 D:/test/hello.txt 比 D:\test\hello.txt 更稳避免转义问题。目标目录要提前存在Agent 不会自动建文件夹。6. 接入文档与后续调试入口上面这套配置跑通后你手里就有一个可用的开源 GUI Agent 底座了。接下来调优方向主要是三块任务描述怎么写得更明确、记忆窗口开多大、以及针对特定软件做动作白名单。Key 管理和额度查看在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 接入细节和参数说明看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你要接 Claude Code 或 Anthropic 风格的 Agent 流程参考 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 里的配置方式和 UI-TARS 的模型层可以共用同一个 Key。我踩过的坑是一开始把 max_steps 设成 100结果 Agent 在找不到目标时反复截图重试烧了不少 token。后来改成 50 并加上 max_retry_per_step3单任务消耗降了四成。你先按 50 跑稳定后再按任务类型微调。
