wehub/microsoft--webwright
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: make Chinese README the default

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 10:18:32 +00:00
parent 1dedf139eb
commit 5edad4431d
1 changed files with 132 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+132 -126
View File
@@ -1,10 +1,16 @@
<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/microsoft/Webwright) · [上游 README](https://github.com/microsoft/Webwright/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
# Webwright
<p align="center">
<img src="assets/webwright_logo.svg" alt="Webwright logo" width="320">
</p>
<p align="center"><b>Turn Your Coding Models to Be State-of-the-art Browser Agents</b></p>
<p align="center"><b>让你的编程模型成为一流的浏览器智能体（Browser Agent）</b></p>
<p align="center">
<img src="https://img.shields.io/badge/python-%E2%89%A53.10-blue?logo=python&logoColor=white" alt="Python">
@@ -13,94 +19,94 @@
<img src="https://img.shields.io/badge/footprint-%E2%89%A4~1.5k%20LoC-brightgreen" alt="Footprint">
</p>
- 📝 **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/)
- 🌐 **Project Page:** [microsoft.github.io/Webwright](https://microsoft.github.io/Webwright/)
- 📝 **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 gives LLM a terminal where it can launch multiple browser sessions to inspect the page and complete a web task. It captures and inspects page screenshots/states only when needed. It enforces each web task to be completed end-to-end within a re-runnable Python script, i.e. your web agent browsing history is a single code file. No multi-agent system, no graph engine, no plugin layer, no hidden orchestration — just a terminal, a browser, and a model.
Webwright 为 LLM 提供一个终端，使其能够启动多个浏览器会话来检查页面并完成 Web 任务。它仅在需要时捕获并检查页面截图/状态。它要求每个 Web 任务都必须在可重复运行的 Python 脚本中端到端完成——也就是说，你的 Web 智能体浏览历史就是单个代码文件。没有多智能体系统、没有图引擎、没有插件层、没有隐藏的编排——只有终端、浏览器和模型。
Already got your favorite agents, and wonder how to make Claude Code, Codex, Hermes, OpenClaw more capable in browser tasks? Consider adding [Webwright plugin/skills](#-use-as-a-claude-code-skill)!
已有自己喜爱的智能体，想知道如何让 Claude Code、Codex、Hermes、OpenClaw 在浏览器任务中更强？可以考虑添加 [Webwright 插件/技能](#-use-as-a-claude-code-skill)！
---
## 📰 News
## 📰 新闻
- **2026-05-11** — Support Task2UI mode: Webwright completes the task and renders task results into an HTML-based web app you can easily view and reuse.
- **2026-05-06** — Codex and Claude Code plugin manifests added; install via `/plugin install webwright@webwright`. OpenClaw and Hermes Agent integrations shipped; the same `skills/webwright/` folder now loads across Claude Code, Codex, OpenClaw, and Hermes.
- **2026-05-04** — Initial public release: ~1.5k LoC, OpenAI / Anthropic / OpenRouter backends, Playwright environment.
- **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 环境。
---
<details>
<summary><strong>💡 Motivation: Beyond Step-by-Step Web Interaction in a Stateful Browser</strong></summary>
<summary><strong>💡 动机：超越有状态浏览器中的逐步 Web 交互</strong></summary>
Most web agents today treat the browser session itself as the workspace: at each step the model receives the current page state and predicts a single next operation — a click, a type, a DOM selector, or a short tool call. Whatever the format, the agent is locked into predicting one web action at a time inside a predefined interaction loop. That harness was useful when LLMs were weaker. As models get stronger at writing and debugging code, the same harness becomes a bottleneck.
当今大多数 Web 智能体将浏览器会话本身视为工作区：每一步模型接收当前页面状态并预测单个下一步操作——点击、输入、DOM 选择器或简短的工具调用。无论格式如何，智能体都被锁定在预定义交互循环内一次预测一个 Web 操作。当 LLM 较弱时，这种框架很有用；随着模型在编写和调试代码方面越来越强，同样的框架反而成为瓶颈。
Webwright takes a different stance: **separate the agent from the browser**, and treat the browser as something the agent can launch, inspect, and discard while developing a program. The persistent artifact is not the browser session — it's the **code and logs in the local workspace**.
Webwright 采取不同立场：**将智能体与浏览器分离**，把浏览器视为智能体在开发程序时可以启动、检查并丢弃的对象。持久化产物不是浏览器会话——而是**本地工作区中的代码和日志**。
- 🧱 **Robust, reusable interaction with web environments** — instead of fragile pixel-level actions, a coding agent with a terminal queries elements, waits for conditions, and handles dynamic behaviors like lazy loading or re-rendering. The resulting scripts can be rerun, adapted, and shared across tasks rather than rediscovered from scratch.
- ⚡ **Efficient composition of complex workflows** — multi-step interactions like selecting a date or filling a form become a compact program. Loops, functions, and abstractions let the agent generalize across similar tasks (e.g. different dates) without re-predicting the same low-level sequences. Fewer interaction rounds, faster execution, less error accumulation on long horizons.
- 🧪 **Workspace-as-state, not browser-as-state** — the agent can write exploratory scripts, spawn fresh browser sessions, and decide for itself when to capture screenshots and inspect failures, much like a human engineer iterating on an RPA script.
- 🪄 **Surprisingly effective despite being minimal** — this stripped-down setup turns out to handle complex and especially long-horizon web tasks well (see [Performance](#-performance)).
- 🧱 **与 Web 环境进行稳健、可复用的交互** — 编程智能体通过终端查询元素、等待条件，并处理懒加载或重新渲染等动态行为，而非脆弱的像素级操作。生成的脚本可重新运行、适配并在任务间共享，而不必从头摸索。
- ⚡ **高效组合复杂工作流** — 选择日期或填写表单等多步交互可变成紧凑程序。循环、函数和抽象让智能体在相似任务（如不同日期）间泛化，而无需重复预测相同的底层序列。更少交互轮次、更快执行、长程任务中更少错误累积。
- 🧪 **工作区即状态，而非浏览器即状态** — 智能体可编写探索性脚本、启动全新浏览器会话，并自行决定何时捕获截图和检查失败，类似人类工程师迭代 RPA 脚本。
- 🪄 **极简却出人意料地有效** — 这种精简配置在处理复杂且尤其长程的 Web 任务时表现良好（见[性能](#-performance)）。
</details>
---
<details>
<summary><strong>🌟 Why Webwright</strong></summary>
<summary><strong>🌟 为什么选择 Webwright</strong></summary>
Most web agent frameworks bury the actual agent loop under layers of abstractions. Webwright takes the opposite stance:
大多数 Web 智能体框架将实际智能体循环埋在层层抽象之下。Webwright 采取相反立场：
- 🪶 **Lightweight by design** — core agent loop in a single ~450-line file, Playwright environment in ~570 lines, CLI in ~150 lines.
- 🧩 **Pluggable model backends** — OpenAI, Anthropic, and OpenRouter, each ~150–200 lines.
- 🔍 **Zero hidden frameworks** — just `httpx`, `pydantic`, `playwright`, and `typer`.
- 🔁 **Flat prompt → observe → execute script loop** — readable end-to-end, easy to debug, easy to fork.
- 🧪 **Run-artifact first** — every run writes trajectories and screenshots to disk for inspection.
- 🪶 **设计上轻量** — 核心智能体循环在单个约 450 行的文件中，Playwright 环境约 570 行，CLI 约 150 行。
- 🧩 **可插拔的模型后端** — OpenAI、Anthropic 和 OpenRouter，各约 150–200 行。
- 🔍 **零隐藏框架** — 只有 `httpx`、`pydantic`、`playwright` 和 `typer`。
- 🔁 **扁平的 prompt → observe → execute script 循环** — 端到端可读、易于调试、易于 fork。
- 🧪 **运行产物优先** — 每次运行都将轨迹和截图写入磁盘以供检查。
If you want a minimal, easy-to-debug starting point for browser-using agents instead of another heavyweight platform, this is it.
如果你想要一个极简、易于调试的浏览器智能体起点，而不是又一个重量级平台，这就是它。
</details>
---
<details>
<summary><strong>🆚 How Webwright Differs From Other Browser-Agent Repos</strong></summary>
<summary><strong>🆚 Webwright 与其他浏览器智能体仓库的区别</strong></summary>
How they differ at the architectural level:
架构层面的差异：
| | **Stagehand (Browserbase)** | **agent-browser (Vercel)** | **browser-use** | **Webwright** |
| ------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- |
| **Paradigm** | Hybrid: code + NL primitives (`act` / `extract` / `agent`) | CLI tool that *another* agent (Claude Code, Codex, etc.) calls | Autonomous LLM agent loop over DOM/AX snapshots | **Coding agent with a terminal**; browser is just an environment it spawns |
| **Action space** | Playwright code, or NL → LLM-translated Playwright | Discrete subcommands (`open`, `click @e2`, `snapshot`, `eval`) | Indexed click/type actions selected by the LLM | **Free-form Python (writes Playwright scripts itself)** |
| **What is "state"?**| The browser session | The browser session (held by daemon across CLI calls) | The browser session | **The local workspace — code, screenshots, logs.** Browser is disposable. |
| **Loop shape** | Imperative; `agent()` does multi-step when needed | One CLI invocation per micro-step | observe → predict next action → execute → repeat | write code → execute → inspect screenshots → repair (code-as-action) |
| **范式** | 混合：代码 + 自然语言原语（`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） |
</details>
---
## 🎥 Demo
## 🎥 演示
https://github.com/user-attachments/assets/4ed94cd5-11be-4daa-b2d7-1260a803baca
---
## 📊 Performance
## 📊 性能
State-of-the-art on two real-website benchmarks with a 100-step budget — see the [blog post](https://www.microsoft.com/en-us/research/articles/webwright-a-terminal-is-all-you-need-for-web-agents/) for full details.
在两个真实网站基准测试上以 100 步预算达到一流水平——详见[博客文章](https://www.microsoft.com/en-us/research/articles/webwright-a-terminal-is-all-you-need-for-web-agents/)。
- 🏆 **Online-Mind2Web (300 tasks):** **86.7%** with GPT-5.4 — highest among open-sourced harnesses in the AutoEval category. Claude Opus 4.7 reaches **84.7%**, and is stronger on the hard split (**80.5%** vs. 76.6% for GPT-5.4 at N=100).
- 🚀 **Odysseys (200 long-horizon tasks):** **60.1%** with GPT-5.4 (avg. 76.1 steps) — **+15.6 points** over the prior SOTA (Opus 4.6 at 44.5%, using vision based approach and persistent browser) and **+26.6 points** over base GPT-5.4 (33.5% using xy-coordinate prediction and persistent browser).
- 🧠 **Code-as-action beats coordinate prediction:** Webwright substantially outperforms a reproduced GPT-5.4 screenshot+xy-coordinate baseline across all difficulty splits.
- 🧰 **Small models + reusable tools:** generated scripts can be packaged as parameterized CLI tools — even **Qwen-3.5-9B** completes tasks well on Online-Mind2Web sites with 5+ tools available.
- 🏆 **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+ 个可用工具时也能很好地完成任务。
<p align="center">
<img src="assets/odysseys_eval_step100.png" alt="Odysseys long-horizon eval @ 100 steps" width="49%">
<img src="assets/odysseys_eval_step100.png" alt="Odysseys 长视野评测 @ 100 steps" width="49%">
<img src="assets/om2w_autoeval_step100.png" alt="Online-Mind2Web AutoEval @ 100 steps" width="49%">
</p>
---
## 🗺️ Project Map
## 🗺️ 项目地图
```
webwright/
@@ -124,23 +130,24 @@ webwright/
---
## 📰 Task Showcase (repeatable runs as a dashboard)
## 📰 任务展示（可重复运行，仪表板形式）
A tiny Flask app under [`assets/task_showcase/`](assets/task_showcase/README.md) consolidates
Webwright runs for **repeatable** odyssey tasks (deals, inventory, listings,
job boards, weather, etc.) into a single dashboard. Each task ships only two
files — `task.json` (metadata) and `report.json` (curated, structured output:
sources + result sections like tables, lists, summaries) — and the templates
render them generically, so adding a new task is just dropping a new folder
in `assets/task_showcase/tasks/`.
位于 [`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
```
To have Webwright produce a renderer-ready task folder at runtime, stack the
Task Showcase overlay:
若要在运行时让 Webwright 生成可供渲染器使用的任务文件夹，请叠加
Task Showcase 覆盖层：
```bash
python -m webwright.run.cli \
@@ -150,13 +157,12 @@ python -m webwright.run.cli \
-o outputs/default
```
> **Note:** `report.json` is only generated when `-c task_showcase.yaml` is
> included. A plain `base.yaml` run produces `trajectory.json` and debug
> artifacts but no `report.json`.
> **注意：** 仅当包含 `-c task_showcase.yaml` 时才会生成 `report.json`。
> 普通的 `base.yaml` 运行会产生 `trajectory.json` 和调试
> 产物，但不会生成 `report.json`。
The run writes `task_showcase/tasks/<short_id>/task.json` and `report.json`
inside the output workspace. Render those generated files without copying them
back into the repo:
运行会在输出工作区内写入 `task_showcase/tasks/<short_id>/task.json` 和 `report.json`。
直接渲染这些生成的文件，无需将它们复制回仓库：
```bash
python assets/task_showcase/app.py \
@@ -165,27 +171,27 @@ python assets/task_showcase/app.py \
---
## 🚀 Quick Start
## 🚀 快速开始
### Prerequisites
### 前置条件
- Python 3.10+
- Chromium installed through Playwright
- An API key for your chosen backend (OpenAI, Anthropic, or OpenRouter)
- 通过 Playwright 安装的 Chromium
- 所选后端（OpenAI、Anthropic 或 OpenRouter）的 API 密钥
### Install
### 安装
```bash
pip install -e .
playwright install chromium
```
### Run
### 运行
Export credentials for the configured backend (for example, `OPENAI_API_KEY`
with `model_openai.yaml` or `ANTHROPIC_API_KEY` with `model_claude.yaml`). The
`image_qa` and `self_reflection` tools use the same configured model by default,
so an Anthropic run does not require an OpenAI key. Then:
为已配置的后端导出凭据（例如，`OPENAI_API_KEY`
配合 `model_openai.yaml`，或 `ANTHROPIC_API_KEY` 配合 `model_claude.yaml`）。默认情况下，
`image_qa` 和 `self_reflection` 工具使用同一已配置模型，
因此使用 Anthropic 运行无需 OpenAI 密钥。然后：
```bash
python -m webwright.run.cli \
@@ -196,23 +202,23 @@ python -m webwright.run.cli \
-o outputs/default
```
### 🚩 Flags
### 🚩 标志
| Flag | Description |
|------|-------------|
| `-c` | Config file(s) from `src/webwright/config/` (stackable). |
| `-t` | Task instruction. |
| `--start-url` | Initial page. |
| `--task-id` | Output subfolder name. |
| `-o` | Output directory. |
| Flag | 说明 |
|------|------|
| `-c` | 来自 `src/webwright/config/` 的配置文件（可叠加）。 |
| `-t` | 任务指令。 |
| `--start-url` | 初始页面。 |
| `--task-id` | 输出子文件夹名称。 |
| `-o` | 输出目录。 |
---
## 🔌 Use as a Plugin
## 🔌 作为插件使用
Webwright ships plugin manifests for both [Claude Code](https://docs.claude.com/en/docs/claude-code/plugins) ([`.claude-plugin/plugin.json`](.claude-plugin/plugin.json)) and [OpenAI Codex](https://developers.openai.com/codex/plugins) ([`.codex-plugin/plugin.json`](.codex-plugin/plugin.json)), with the shared skill at [`skills/webwright/`](skills/webwright/) and slash commands at [`skills/webwright/commands/`](skills/webwright/commands/). The host agent drives the Webwright loop natively — no extra LLM API key or cost beyond your host subscription. Hosts that read PNG screenshots natively skip the `image_qa` / `self_reflection` tools.
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` 工具。
Common runtime deps (install once after either path):
通用运行时依赖（任选一种安装路径后安装一次即可）：
```bash
pip install -e .
@@ -222,9 +228,9 @@ playwright install chromium
<details>
<summary><b>Claude Code</b></summary>
### Install
### 安装
Install through the bundled marketplace inside Claude Code:
通过 Claude Code 内置的市场安装：
```text
# 1. Add this repo as a Claude Code plugin marketplace
@@ -234,37 +240,37 @@ Install through the bundled marketplace inside Claude Code:
/plugin install webwright@webwright
```
Prefer a local checkout? Point the marketplace command at the cloned repo instead:
更倾向于使用本地检出？将市场命令指向克隆的仓库即可：
```text
/plugin marketplace add /absolute/path/to/Webwright
/plugin install webwright@webwright
```
### Use
### 使用
**Start a new Claude Code session** after installing — plugins are loaded at session start and won't appear until you restart.
安装后**启动新的 Claude Code 会话** — 插件在会话开始时加载，重启前不会出现。
You can either ask Claude Code in plain English (the skill auto-activates from its description), or use one of the slash commands:
你可以用自然语言向 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` (or any plain prompt) produces a **one-shot** `final_script.py` for the literal task values.
- `/webwright:craft` produces a **reusable CLI tool**: `final_script.py` becomes one parameterized function with a Google-style `Args:` docstring and an `argparse` wrapper whose flags default to the concrete task values, so you can rerun it later with different arguments — e.g. `python final_script.py --origin JFK --destination LAX --depart-date 2026-07-01`.
- `/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`。
In both modes Claude Code scaffolds a workspace with `plan.md`, runs instrumented Playwright scripts under `final_runs/run_<id>/`, and visually self-verifies each critical point against the saved screenshots.
在两种模式下，Claude Code 都会使用 `plan.md` 搭建工作区，在 `final_runs/run_<id>/` 下运行插桩的 Playwright 脚本，并针对保存的截图对每个关键点进行可视化自检。
</details>
<details>
<summary><b>OpenAI Codex</b></summary>
### Install
### 安装
Codex reads Claude-style marketplaces, so the same repo works as a Codex plugin marketplace. From the Codex CLI:
Codex 可读取 Claude 风格的市场，因此同一仓库可作为 Codex 插件市场使用。在 Codex CLI 中：
```bash
# 1. Add this repo as a Codex plugin marketplace
@@ -275,129 +281,129 @@ codex
/plugins
```
Prefer a local checkout?
更倾向于使用本地检出？
```bash
codex plugin marketplace add /absolute/path/to/Webwright
```
Then restart Codex so the new marketplace and plugin are picked up.
然后重启 Codex，以加载新的市场和插件。
### Use
### 使用
In a new Codex thread, either ask in plain English (the skill auto-activates from its description) or invoke the bundled skill explicitly with `@webwright`:
在新的 Codex 线程中，可以用自然语言提问（技能会根据其描述自动激活），或使用 `@webwright` 显式调用内置技能：
```
@webwright search Google Flights for flights from SEA to JFK on 2026-08-15 to 2026-08-20
```
Codex scaffolds a workspace with `plan.md`, runs instrumented Playwright scripts under `final_runs/run_<id>/`, and visually self-verifies each critical point against the saved screenshots.
Codex 会使用 `plan.md` 搭建工作区，在 `final_runs/run_<id>/` 下运行插桩的 Playwright 脚本，并针对保存的截图对每个关键点进行可视化自检。
To turn the plugin off without uninstalling, set its entry in `~/.codex/config.toml` to `enabled = false` and restart Codex.
若要在不卸载的情况下关闭插件，请将其在 `~/.codex/config.toml` 中的条目设为 `enabled = false` 并重启 Codex。
</details>
<details>
<summary><b>🦞 OpenClaw</b></summary>
### Install
### 安装
Install directly from a local checkout (path, archive, npm spec, git repo, or `clawhub:` spec all work):
直接从本地检出安装（路径、压缩包、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
```
Verify:
验证：
```bash
openclaw plugins list | grep webwright
openclaw skills list | grep webwright # should show "✓ ready"
```
### Use
### 使用
The `webwright` skill is now available to any OpenClaw agent surface (CLI, Telegram, etc.) — invoke it by asking the agent in natural language, or via the slash commands shipped under [`skills/webwright/commands/`](skills/webwright/commands/), e.g. `/webwright run <task>`.
`webwright` 技能现可在任意 OpenClaw 智能体界面（CLI、Telegram 等）上使用 — 可通过自然语言向智能体提问，或通过 [`skills/webwright/commands/`](skills/webwright/commands/) 下附带的斜杠命令调用，例如 `/webwright run <task>`。
To uninstall: `openclaw plugins uninstall webwright`.
卸载：`openclaw plugins uninstall webwright`。
</details>
<details>
<summary><b>Hermes Agent</b></summary>
### Install
### 安装
[Hermes Agent](https://github.com/NousResearch/hermes-agent) is a [skills-compatible client](https://agentskills.io), so the same `skills/webwright/` folder loads as a Hermes skill. Symlink it into your Hermes user-skills directory:
[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
```
No Hermes-specific manifest is needed; only `SKILL.md` is loaded.
无需 Hermes 专用 manifest；仅加载 `SKILL.md`。
### Use
### 用法
Start Hermes (`hermes`) and ask it to drive a web task in natural language — the skill auto-activates from its description. You can also invoke it explicitly with `/webwright`.
启动 Hermes（`hermes`），用自然语言让它驱动一项 Web 任务——技能会根据其描述自动激活。你也可以通过 `/webwright` 显式调用。
Note: the named subcommands shipped under [`skills/webwright/commands/`](skills/webwright/commands/) (`/webwright:run`, `/webwright:craft`) are a Claude Code / Codex convention and are inert in Hermes; the skill itself still works end-to-end.
注意：[`skills/webwright/commands/`](skills/webwright/commands/) 下提供的命名子命令（`/webwright:run`、`/webwright:craft`）属于 Claude Code / Codex 约定，在 Hermes 中不起作用；技能本身仍可端到端运行。
</details>
## 📃 Trajectory Comparison & Viewer
## 📃 轨迹对比与查看器
You can run the same tasks using the Webwright harness and its Codex / GitHub Copilot skill variant, and see how token usage and trajectories stack up between different harnesses. The trajectory viewer supports Codex, GitHub Copilot and Webwright harness traces.
你可以使用 Webwright harness 及其 Codex / GitHub Copilot 技能变体运行相同任务，并比较不同 harness 之间的 token 用量与轨迹。轨迹查看器支持 Codex、GitHub Copilot 和 Webwright harness 的轨迹。
![Trajectory comparison](assets/trajectory-compare.png)
![轨迹对比](assets/trajectory-compare.png)
### How to use
### 使用方法
```bash
cd assets/compare_trajectory/
python3 -m http.server
```
Open the webpage in your browser and upload the Webwright `raw_responses.jsonl` and attach `trajectory.json` to view. Then on the other side you can upload your Codex or GitHub Copilot trace.
在浏览器中打开该网页，上传 Webwright 的 `raw_responses.jsonl`，并附加 `trajectory.json` 以查看。随后在另一侧上传你的 Codex 或 GitHub Copilot 轨迹。
### Obtaining Codex traces:
### 获取 Codex 轨迹：
```
ls ~/.codex/sessions/2026/MONTH/DAY/SESSION_ID.jsonl
```
### Obtaining GitHub Copilot traces:
### 获取 GitHub Copilot 轨迹：
```
/export file session
-> session.md is the uploadable trace
```
### Quick Comparison
### 快速对比
#### "Find the cheapest used 8-cylinder bmw made between 2005-2015 and priced from 25,000 to 50,000 dollars with mileage less than 50,000 miles or less."
#### "查找 2005–2015 年间制造、售价 25,000 至 50,000 美元、里程不超过 50,000 英里的最便宜二手 8 缸 BMW。"
| Tokens | Webwright Harness (Local Browser Mode) | Codex Webwright Skill |
| Tokens | Webwright Harness（本地浏览器模式） | Codex Webwright Skill |
| --- | ---: | ---: |
| Input | 420,433 | 3,271,143 |
| Output | 3,593 | 20,040 |
| Reasoning | 0 | 4,410 |
| Cached | 217,216 | 3,081,3440 |
| Total | 424,026 | 3,291,183 |
| 输入 | 420,433 | 3,271,143 |
| 输出 | 3,593 | 20,040 |
| 推理 | 0 | 4,410 |
| 缓存 | 217,216 | 3,081,3440 |
| 总计 | 424,026 | 3,291,183 |
Individual runs and results may vary.
单次运行及结果可能有所不同。
---
## Credits
## 致谢
- [SWE-agent/mini-swe-agent](https://github.com/SWE-agent/mini-swe-agent/tree/main) — design inspiration for the minimal agent loop.
- [Playwright](https://playwright.dev/) — browser automation.
- [SWE-agent/mini-swe-agent](https://github.com/SWE-agent/mini-swe-agent/tree/main) — 极简 agent 循环的设计灵感。
- [Playwright](https://playwright.dev/) — 浏览器自动化。
## Citation
## 引用
If you use Webwright in your research or build on it, please cite this repository:
若你在研究中使用 Webwright 或在其基础上进行开发，请引用本仓库：
```bibtex
@misc{webwright2026,