CUAWright

环境要求

• Python 3.12+（桌面任务必需）
• 需能访问配置后端的模型 API Key（如 OPENAI_API_KEY 或 ANTHROPIC_API_KEY）
• 桌面任务需要 Docker，并已获得 OSWorld-V2 任务与资产快照的 Hugging Face 授权访问
• 需要本地克隆 CUAWright 源码仓库以便 pip install -e . 安装

安装与启动步骤

1. 1克隆源码仓库

   从 GitHub 拉取 CUAWright 源码并进入项目根目录，后续所有 install 命令都在这个目录里执行。

   git clone https://github.com/microsoft/CUAWright
   cd CUAWright

   复制

2. 2安装浏览器版依赖

   以可编辑模式安装项目本体，README 的 Browser Quick Start 中给出的命令就是这一条。

   pip install -e .

   复制

3. 3安装 Chromium 浏览器

   用 Playwright 安装 Chromium，供浏览器自动化运行时启动真实浏览器。

   playwright install chromium

   复制

4. 4导出模型密钥

   为所选后端导出密钥：model_openai.yaml 配 OPENAI_API_KEY，model_claude.yaml 配 ANTHROPIC_API_KEY。

   export OPENAI_API_KEY=sk-xxxxxxxx

   复制

5. 5跑浏览器脚本任务

   用 -c 分别加载基础配置与模型配置，指定任务描述和起始网址，结果写入 outputs/default。

   python -m cuawright.webwright.run.cli main 
       -c base.yaml -c model_openai.yaml 
       -t "Report the page title and the destination of its main link." 
       --start-url https://example.com 
       --task-id demo_openai 
       -o outputs/default

   复制

6. 6安装桌面版依赖

   如需在 Ubuntu VM 中执行桌面任务，先安装 desktop 可选依赖组，需 Python 3.12+ 与 Docker。

   pip install -e ".[desktop]"

   复制

7. 7准备 OSWorld 环境

   先在 Hugging Face 接受 tasks 与 assets 数据集访问，登录后下载固定版本源码、任务与 VM。

   pip install huggingface_hub
   hf auth login
   cuawright setup osworld --root ~/.cache/cuawright/osworld-v2-2026.08.08
   cuawright verify osworld 
     --setup ~/.cache/cuawright/osworld-v2-2026.08.08/setup.json

   复制

8. 8运行桌面任务

   用 --setup 指向 setup.json，--credentials 指向权限 0600 的密钥文件，results 用父目录已存在的新目录。

   cuawright desktop run 
     --setup /absolute/path/to/setup.json 
     --credentials /absolute/path/to/api-key 
     --results /absolute/path/to/results/custom 
     --model YOUR_MODEL 
     --instruction ""

   复制

关键配置

如何确认成功

浏览器运行后在 outputs/default 下生成可复用脚本与运行记录；桌面运行在 results 目录生成 manifest.json、trace.jsonl 与 result.json。

常见问题

注意事项

• 桌面运行不会导出单独的截图文件，Agent 查看的图片内嵌在 trace 中。
• 在 VM 内创建的文件不会自动复制回宿主机，需要自行处理产物导出。
• 结果目录要选一个新的、且其父目录已存在的路径。
• 除 OpenAI 外，可通过 --responses-url 接入其他 Responses 兼容提供商；官方任务 ID 与代理配置见 REPRODUCE.md。