> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/microsoft/Webwright) · [上游 README](https://github.com/microsoft/Webwright/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
# Webwright
让你的编程模型成为一流的浏览器智能体（Browser Agent）
- 📝 **Blog：** [Webwright: A Terminal Is All You Need For Web Agents](https://www.microsoft.com/en-us/research/articles/webwright-a-terminal-is-all-you-need-for-web-agents/)
- 🌐 **项目主页：** [microsoft.github.io/Webwright](https://microsoft.github.io/Webwright/)
Webwright 为 LLM 提供一个终端，使其能够启动多个浏览器会话来检查页面并完成 Web 任务。它仅在需要时捕获并检查页面截图/状态。它要求每个 Web 任务都必须在可重复运行的 Python 脚本中端到端完成——也就是说，你的 Web 智能体浏览历史就是单个代码文件。没有多智能体系统、没有图引擎、没有插件层、没有隐藏的编排——只有终端、浏览器和模型。
已有自己喜爱的智能体，想知道如何让 Claude Code、Codex、Hermes、OpenClaw 在浏览器任务中更强？可以考虑添加 [Webwright 插件/技能](#-use-as-a-claude-code-skill)！
---
## 📰 新闻
- **2026-05-11** — 支持 Task2UI 模式：Webwright 完成任务后将任务结果渲染为基于 HTML 的 Web 应用，便于查看和复用。
- **2026-05-06** — 新增 Codex 与 Claude Code 插件清单；可通过 `/plugin install webwright@webwright` 安装。已交付 OpenClaw 与 Hermes Agent 集成；同一 `skills/webwright/` 文件夹现可在 Claude Code、Codex、OpenClaw 和 Hermes 中加载。
- **2026-05-04** — 首次公开发布：约 1.5k 行代码，支持 OpenAI / Anthropic / OpenRouter 后端与 Playwright 环境。
---
💡 动机：超越有状态浏览器中的逐步 Web 交互
当今大多数 Web 智能体将浏览器会话本身视为工作区：每一步模型接收当前页面状态并预测单个下一步操作——点击、输入、DOM 选择器或简短的工具调用。无论格式如何，智能体都被锁定在预定义交互循环内一次预测一个 Web 操作。当 LLM 较弱时，这种框架很有用；随着模型在编写和调试代码方面越来越强，同样的框架反而成为瓶颈。
Webwright 采取不同立场：**将智能体与浏览器分离**，把浏览器视为智能体在开发程序时可以启动、检查并丢弃的对象。持久化产物不是浏览器会话——而是**本地工作区中的代码和日志**。
- 🧱 **与 Web 环境进行稳健、可复用的交互** — 编程智能体通过终端查询元素、等待条件，并处理懒加载或重新渲染等动态行为，而非脆弱的像素级操作。生成的脚本可重新运行、适配并在任务间共享，而不必从头摸索。
- ⚡ **高效组合复杂工作流** — 选择日期或填写表单等多步交互可变成紧凑程序。循环、函数和抽象让智能体在相似任务（如不同日期）间泛化，而无需重复预测相同的底层序列。更少交互轮次、更快执行、长程任务中更少错误累积。
- 🧪 **工作区即状态，而非浏览器即状态** — 智能体可编写探索性脚本、启动全新浏览器会话，并自行决定何时捕获截图和检查失败，类似人类工程师迭代 RPA 脚本。
- 🪄 **极简却出人意料地有效** — 这种精简配置在处理复杂且尤其长程的 Web 任务时表现良好（见[性能](#-performance)）。
---
🌟 为什么选择 Webwright
大多数 Web 智能体框架将实际智能体循环埋在层层抽象之下。Webwright 采取相反立场：
- 🪶 **设计上轻量** — 核心智能体循环在单个约 450 行的文件中，Playwright 环境约 570 行，CLI 约 150 行。
- 🧩 **可插拔的模型后端** — OpenAI、Anthropic 和 OpenRouter，各约 150–200 行。
- 🔍 **零隐藏框架** — 只有 `httpx`、`pydantic`、`playwright` 和 `typer`。
- 🔁 **扁平的 prompt → observe → execute script 循环** — 端到端可读、易于调试、易于 fork。
- 🧪 **运行产物优先** — 每次运行都将轨迹和截图写入磁盘以供检查。
如果你想要一个极简、易于调试的浏览器智能体起点，而不是又一个重量级平台，这就是它。
---
🆚 Webwright 与其他浏览器智能体仓库的区别
架构层面的差异：
| | **Stagehand (Browserbase)** | **agent-browser (Vercel)** | **browser-use** | **Webwright** |
| ------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- |
| **范式** | 混合：代码 + 自然语言原语（`act` / `extract` / `agent`） | 供*其他*智能体（Claude Code、Codex 等）调用的 CLI 工具 | 基于 DOM/AX 快照的自主 LLM 智能体循环 | **带终端的编程智能体**；浏览器只是其启动的环境 |
| **动作空间** | Playwright 代码，或自然语言 → LLM 翻译的 Playwright | 离散子命令（`open`、`click @e2`、`snapshot`、`eval`） | 由 LLM 选择的索引化点击/输入操作 | **自由形式 Python（自行编写 Playwright 脚本）** |
| **何为「状态」？**| 浏览器会话 | 浏览器会话（由守护进程在多次 CLI 调用间保持） | 浏览器会话 | **本地工作区——代码、截图、日志。** 浏览器可丢弃。 |
| **循环形态** | 命令式；`agent()` 在需要时执行多步 | 每个微步骤一次 CLI 调用 | observe → predict next action → execute → repeat | 编写代码 → 执行 → 检查截图 → 修复（code-as-action） |
---
## 🎥 演示
https://github.com/user-attachments/assets/4ed94cd5-11be-4daa-b2d7-1260a803baca
---
## 📊 性能
在两个真实网站基准测试上以 100 步预算达到一流水平——详见[博客文章](https://www.microsoft.com/en-us/research/articles/webwright-a-terminal-is-all-you-need-for-web-agents/)。
- 🏆 **Online-Mind2Web（300 项任务）：** 使用 GPT-5.4 达到 **86.7%** — AutoEval 类别中开源框架最高。Claude Opus 4.7 达到 **84.7%**，在困难子集上更强（**80.5%** vs. GPT-5.4 在 N=100 时的 76.6%）。
- 🚀 **Odysseys（200 项长程任务）：** 使用 GPT-5.4（平均 76.1 步）达到 **60.1%** — 较先前 SOTA（Opus 4.6 为 44.5%，采用基于视觉的方法与持久化浏览器）**+15.6 个百分点**，较基础 GPT-5.4（33.5%，采用 xy 坐标预测与持久化浏览器）**+26.6 个百分点**。
- 🧠 **Code-as-action 优于坐标预测：** Webwright 在所有难度子集上均大幅优于复现的 GPT-5.4 截图+xy 坐标基线。
- 🧰 **小模型 + 可复用工具：** 生成的脚本可打包为参数化 CLI 工具 — 即便 **Qwen-3.5-9B** 在 Online-Mind2Web 站点上、有 5+ 个可用工具时也能很好地完成任务。
---
## 🗺️ 项目地图
```
webwright/
├── pyproject.toml # package: webwright
├── src/webwright/
│ ├── run/cli.py # CLI entrypoint (`webwright`)
│ ├── agents/default.py # core agent loop
│ ├── environments/ # Playwright browser workspace
│ ├── tools/ # image_qa, self_reflection
│ ├── models/ # openai_model, anthropic_model, base
│ ├── config/ # base.yaml, model_openai.yaml, model_claude.yaml
│ └── utils/
├── assets/
│ └── task_showcase/ # tiny Flask dashboard for repeatable runs
│ ├── app.py
│ ├── templates/ # dashboard.html, task.html
│ └── tasks// # task.json + report.json per task
├── tests/
└── outputs/ # run artifacts (trajectories, screenshots)
```
---
## 📰 任务展示（可重复运行，仪表板形式）
位于 [`assets/task_showcase/`](assets/task_showcase/README.md) 下的小型 Flask 应用将
针对**可重复** odyssey 任务（优惠、库存、列表、
招聘板、天气等）的 Webwright 运行结果汇总到
单一仪表板中。每个任务仅包含两个
文件 — `task.json`（元数据）和 `report.json`（精心整理的结构化输出：
来源 + 表格、列表、摘要等结果区块）— 模板
以通用方式渲染它们，因此添加新任务只需在
`assets/task_showcase/tasks/` 中放入一个新文件夹即可。
```bash
pip install flask
python assets/task_showcase/app.py # http://127.0.0.1:5005
```
若要在运行时让 Webwright 生成可供渲染器使用的任务文件夹，请叠加
Task Showcase 覆盖层：
```bash
python -m webwright.run.cli \
-c base.yaml -c model_openai.yaml -c task_showcase.yaml \
-t "" \
--task-id my_repeatable_task \
-o outputs/default
```
> **注意：** 仅当包含 `-c task_showcase.yaml` 时才会生成 `report.json`。
> 普通的 `base.yaml` 运行会产生 `trajectory.json` 和调试
> 产物，但不会生成 `report.json`。
运行会在输出工作区内写入 `task_showcase/tasks//task.json` 和 `report.json`。
直接渲染这些生成的文件，无需将它们复制回仓库：
```bash
python assets/task_showcase/app.py \
--tasks-dir outputs/default//task_showcase/tasks
```
---
## 🚀 快速开始
### 前置条件
- Python 3.10+
- 通过 Playwright 安装的 Chromium
- 所选后端（OpenAI、Anthropic 或 OpenRouter）的 API 密钥
### 安装
```bash
pip install -e .
playwright install chromium
```
### 运行
为已配置的后端导出凭据（例如，`OPENAI_API_KEY`
配合 `model_openai.yaml`，或 `ANTHROPIC_API_KEY` 配合 `model_claude.yaml`）。默认情况下，
`image_qa` 和 `self_reflection` 工具使用同一已配置模型，
因此使用 Anthropic 运行无需 OpenAI 密钥。然后：
```bash
python -m webwright.run.cli \
-c base.yaml -c model_openai.yaml \
-t "Search for flights from SEA to JFK on 2026-08-15 to 2026-08-20" \
--start-url https://www.google.com/flights \
--task-id demo_openai \
-o outputs/default
```
### 🚩 标志
| Flag | 说明 |
|------|------|
| `-c` | 来自 `src/webwright/config/` 的配置文件（可叠加）。 |
| `-t` | 任务指令。 |
| `--start-url` | 初始页面。 |
| `--task-id` | 输出子文件夹名称。 |
| `-o` | 输出目录。 |
---
## 🔌 作为插件使用
Webwright 为 [Claude Code](https://docs.claude.com/en/docs/claude-code/plugins) ([`.claude-plugin/plugin.json`](.claude-plugin/plugin.json)) 和 [OpenAI Codex](https://developers.openai.com/codex/plugins) ([`.codex-plugin/plugin.json`](.codex-plugin/plugin.json)) 均提供了插件清单，共享技能位于 [`skills/webwright/`](skills/webwright/)，斜杠命令位于 [`skills/webwright/commands/`](skills/webwright/commands/)。宿主智能体以原生方式驱动 Webwright 循环 — 除宿主订阅费用外，无需额外的 LLM API 密钥或成本。原生支持读取 PNG 截图的宿主会跳过 `image_qa` / `self_reflection` 工具。
通用运行时依赖（任选一种安装路径后安装一次即可）：
```bash
pip install -e .
playwright install chromium
```
Claude Code
### 安装
通过 Claude Code 内置的市场安装：
```text
# 1. Add this repo as a Claude Code plugin marketplace
/plugin marketplace add microsoft/Webwright
# 2. Install the plugin from that marketplace
/plugin install webwright@webwright
```
更倾向于使用本地检出？将市场命令指向克隆的仓库即可：
```text
/plugin marketplace add /absolute/path/to/Webwright
/plugin install webwright@webwright
```
### 使用
安装后**启动新的 Claude Code 会话** — 插件在会话开始时加载，重启前不会出现。
你可以用自然语言向 Claude Code 提问（技能会根据其描述自动激活），或使用其中一个斜杠命令：
```
/webwright:run search Google Flights for flights from SEA to JFK on 2026-08-15 to 2026-08-20
/webwright:craft search a ticket on Google Flights from LAX to SFO depart June 7 return June 14
```
- `/webwright:run`（或任意普通提示）会为字面任务值生成**一次性** `final_script.py`。
- `/webwright:craft` 会生成**可复用的 CLI 工具**：`final_script.py` 变成一个参数化函数，带有 Google 风格的 `Args:` docstring 和 `argparse` 包装器，其标志默认为具体任务值，因此你可以稍后使用不同参数重新运行 — 例如 `python final_script.py --origin JFK --destination LAX --depart-date 2026-07-01`。
在两种模式下，Claude Code 都会使用 `plan.md` 搭建工作区，在 `final_runs/run_/` 下运行插桩的 Playwright 脚本，并针对保存的截图对每个关键点进行可视化自检。
OpenAI Codex
### 安装
Codex 可读取 Claude 风格的市场，因此同一仓库可作为 Codex 插件市场使用。在 Codex CLI 中：
```bash
# 1. Add this repo as a Codex plugin marketplace
codex plugin marketplace add microsoft/Webwright
# 2. Open the plugin browser and install Webwright
codex
/plugins
```
更倾向于使用本地检出？
```bash
codex plugin marketplace add /absolute/path/to/Webwright
```
然后重启 Codex，以加载新的市场和插件。
### 使用
在新的 Codex 线程中，可以用自然语言提问（技能会根据其描述自动激活），或使用 `@webwright` 显式调用内置技能：
```
@webwright search Google Flights for flights from SEA to JFK on 2026-08-15 to 2026-08-20
```
Codex 会使用 `plan.md` 搭建工作区，在 `final_runs/run_/` 下运行插桩的 Playwright 脚本，并针对保存的截图对每个关键点进行可视化自检。
若要在不卸载的情况下关闭插件，请将其在 `~/.codex/config.toml` 中的条目设为 `enabled = false` 并重启 Codex。
🦞 OpenClaw
### 安装
直接从本地检出安装（路径、压缩包、npm spec、git 仓库或 `clawhub:` spec 均可）：
```bash
openclaw plugins install /absolute/path/to/Webwright
openclaw gateway restart # reload so the plugin and skill are picked up
```
验证：
```bash
openclaw plugins list | grep webwright
openclaw skills list | grep webwright # should show "✓ ready"
```
### 使用
`webwright` 技能现可在任意 OpenClaw 智能体界面（CLI、Telegram 等）上使用 — 可通过自然语言向智能体提问，或通过 [`skills/webwright/commands/`](skills/webwright/commands/) 下附带的斜杠命令调用，例如 `/webwright run `。
卸载：`openclaw plugins uninstall webwright`。
Hermes Agent
### 安装
[Hermes Agent](https://github.com/NousResearch/hermes-agent) 是一款 [skills-compatible client](https://agentskills.io),，因此同一 `skills/webwright/` 文件夹可作为 Hermes 技能加载。请将其符号链接到你的 Hermes 用户技能目录：
```bash
mkdir -p ~/.hermes/skills
ln -sfn /absolute/path/to/Webwright/skills/webwright ~/.hermes/skills/webwright
```
无需 Hermes 专用 manifest；仅加载 `SKILL.md`。
### 用法
启动 Hermes（`hermes`），用自然语言让它驱动一项 Web 任务——技能会根据其描述自动激活。你也可以通过 `/webwright` 显式调用。
注意：[`skills/webwright/commands/`](skills/webwright/commands/) 下提供的命名子命令（`/webwright:run`、`/webwright:craft`）属于 Claude Code / Codex 约定，在 Hermes 中不起作用；技能本身仍可端到端运行。
## 📃 轨迹对比与查看器
你可以使用 Webwright harness 及其 Codex / GitHub Copilot 技能变体运行相同任务，并比较不同 harness 之间的 token 用量与轨迹。轨迹查看器支持 Codex、GitHub Copilot 和 Webwright harness 的轨迹。
### 使用方法
```bash
cd assets/compare_trajectory/
python3 -m http.server
```
在浏览器中打开该网页，上传 Webwright 的 `raw_responses.jsonl`，并附加 `trajectory.json` 以查看。随后在另一侧上传你的 Codex 或 GitHub Copilot 轨迹。
### 获取 Codex 轨迹：
```
ls ~/.codex/sessions/2026/MONTH/DAY/SESSION_ID.jsonl
```
### 获取 GitHub Copilot 轨迹：
```
/export file session
-> session.md is the uploadable trace
```
### 快速对比
#### "查找 2005–2015 年间制造、售价 25,000 至 50,000 美元、里程不超过 50,000 英里的最便宜二手 8 缸 BMW。"
| Tokens | Webwright Harness（本地浏览器模式） | Codex Webwright Skill |
| --- | ---: | ---: |
| 输入 | 420,433 | 3,271,143 |
| 输出 | 3,593 | 20,040 |
| 推理 | 0 | 4,410 |
| 缓存 | 217,216 | 3,081,3440 |
| 总计 | 424,026 | 3,291,183 |
单次运行及结果可能有所不同。
---
## 致谢
- [SWE-agent/mini-swe-agent](https://github.com/SWE-agent/mini-swe-agent/tree/main) — 极简 agent 循环的设计灵感。
- [Playwright](https://playwright.dev/) — 浏览器自动化。
## 引用
若你在研究中使用 Webwright 或在其基础上进行开发，请引用本仓库：
```bibtex
@misc{webwright2026,
title = {Webwright: A terminal is all you need for web agents},
author = {Lu, Yadong and Xu, Lingrui and Huang, Chao and Awadallah, Ahmed},
year = {2026},
howpublished = {\url{https://github.com/microsoft/Webwright}},
note = {GitHub repository}
}
```