Playwright CLI 使用入门：安装、Skills、会话管理与常用命令

如果你最近在用 Claude Code、GitHub Copilot 或其他 coding agent 做浏览器自动化，microsoft/playwright-cli 是一个很值得关注的新工具。它不是传统意义上那个“给人手动敲命令用”的浏览器小工具，而是一个面向 coding agent 的 Playwright CLI，强调的是更低 token 开销、更轻量的命令接口，以及和 Skills 工作流的结合。

从官方 README 来看，Playwright CLI 的核心思路很明确：相比 MCP 把大量工具 schema 和页面结构塞进模型上下文，CLI 命令方式更紧凑，更适合在大代码库、测试任务和浏览器自动化之间来回切换的 agent 工作流。

01 Playwright CLI 是什么

playwright-cli 是微软开源的一个 Playwright 命令行工具，官方描述是 “CLI for common Playwright actions”。它主要用来完成这些事情：

打开页面并驱动浏览器
记录和生成 Playwright 代码
抓取页面快照，获取元素引用
截图、导出 PDF
配合 coding agent 进行自动化测试和网页操作

当前 GitHub README 里把它定位得非常明确：如果你正在使用 coding agents，CLI 往往比 Playwright MCP 更合适；如果你更需要持久状态、丰富 introspection 和长时间 agentic loop，MCP 仍然有它的价值。

换句话说，Playwright CLI 更像“给 AI 编码助手准备的浏览器自动化接口”，而不只是给人类工程师手动点击网页的工具。

02 它的优点在哪里

1. 更适合 agent 工作流

官方 README 把第一优点直接写成了 Token-efficient。它不会强制把整页数据都塞进 LLM 上下文，而是通过更短、更专用的命令让 agent 操作浏览器。

这对 coding agent 很重要。因为在真实项目里，agent 不只是跑浏览器，还要看代码、改文件、跑测试、读日志。如果浏览器工具本身就很“吃上下文”，整体效率会明显下降。

2. 能和 Skills 一起工作

README 里专门强调了 playwright-cli install --skills。这说明官方不是把它当单纯的 shell 工具来做，而是把它设计成可以被 Claude Code、GitHub Copilot 等 agent 直接消费的技能入口。

如果你的工作流本身就建立在 Skills 之上，那 Playwright CLI 的接入会更自然。

3. 会话管理做得比较完整

Playwright CLI 支持 session。默认情况下，浏览器 profile 保存在内存里，同一个 session 里的 cookies 和 storage 会在多次 CLI 调用之间保留；如果加上 --persistent，还可以把 profile 落到磁盘，跨浏览器重启继续使用。

这让它比“一条命令打开浏览器，跑完就丢”的玩具型工具更实用，也更适合持续调试和 agent 长流程执行。

4. 自带可视化监控面板

README 里提供了 playwright-cli show，用于打开一个 dashboard，观察和控制所有运行中的浏览器 session。对于 agent 在后台跑自动化任务的场景，这一点很有价值，因为你可以随时接管、观察、排错，而不是只能盲跑。

03 安装与环境要求

根据当前 GitHub README，Playwright CLI 的基本要求是：

Node.js 18 或更高版本
Claude Code、GitHub Copilot 或其他 coding agent

安装命令如下：

1
2


npm install -g @playwright/cli@latest
playwright-cli --help

这里有个很容易踩坑的地方要特别注意：

官方当前推荐安装的是 @playwright/cli
不要把它和 npm 上历史遗留、已废弃的旧包 playwright-cli 混为一谈

也就是说，真正应该装的是 scoped package，而不是旧时代的同名历史包。

04 如何开始用

1. 安装 skills

如果你希望让 coding agent 直接使用 Playwright CLI，官方建议先安装 skills：

1

playwright-cli install --skills

README 里明确写到，Claude Code、GitHub Copilot 等工具会使用本地安装的 skills。

2. 直接让 agent 调用 CLI

如果你不想先处理 skills，也可以直接让 agent 读取 CLI 帮助信息：

1
2


Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Check playwright-cli --help for available commands.

官方把这种方式叫做 “Skills-less operation”。意思是即使不预先装 skill，也可以通过 CLI 自描述能力来驱动 agent。

3. 手动体验一遍最小流程

README 里给了一组很适合上手的 TodoMVC 示例：

1
2
3
4
5
6
7
8


playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli type "Water flowers"
playwright-cli press Enter
playwright-cli check e21
playwright-cli check e35
playwright-cli screenshot

这组命令的价值在于，它能让你很快理解 Playwright CLI 的交互方式：

open 负责打开页面
type 和 press 负责输入
check 用元素引用操作复选框
screenshot 保存结果

05 `--headed`、session 和监控面板

`--headed`

Playwright CLI 默认是 headless 的。如果你想直接看到浏览器窗口，需要在 open 时显式加上 --headed：

1

playwright-cli open https://playwright.dev --headed

这对于调试选择器、登录流程、验证码前后的交互观察会更方便。

session

官方 README 里强调了 session 的用法。你可以用不同 session 把不同项目或网站隔离开来：

1
2
3


playwright-cli open https://playwright.dev
playwright-cli -s=example open https://example.com --persistent
playwright-cli list

如果你是让 agent 长时间工作，还可以直接给它指定环境变量：

1

PLAYWRIGHT_CLI_SESSION=todo-app claude .

常用的 session 管理命令包括：

1
2
3


playwright-cli list
playwright-cli close-all
playwright-cli kill-all

其中：

list 用来列出所有 session
close-all 用来正常关闭所有浏览器
kill-all 用来强制杀掉所有浏览器进程

监控面板

如果你想看 agent 当前到底在浏览器里做了什么，可以运行：

1

playwright-cli show

按照 README 的说明，这个 dashboard 主要有两种视图：

Session grid：按 workspace 查看所有活动 session，带实时画面、URL 和页面标题
Session detail：查看单个 session 的实时界面，还能接管鼠标和键盘

这让 Playwright CLI 不只是“命令行可用”，而是具备了比较成熟的可观测性。

06 常用命令先记住哪些

如果你第一次接触 Playwright CLI，不需要一开始就把所有命令背下来。先记下面这些最核心的就够了：

页面与交互

1
2
3
4
5
6
7


playwright-cli open [url]
playwright-cli goto <url>
playwright-cli click <ref>
playwright-cli fill <ref> <text>
playwright-cli type <text>
playwright-cli hover <ref>
playwright-cli press <key>

获取页面结构

1
2
3
4


playwright-cli snapshot
playwright-cli snapshot <ref>
playwright-cli snapshot --depth=N
playwright-cli eval <func> [ref]

snapshot 很关键，因为很多后续操作都依赖元素引用 ref。你通常会先抓一次快照，再用返回的元素编号去点、填、勾选或截图。

输出结果

1
2


playwright-cli screenshot
playwright-cli pdf

标签页

1
2
3
4


playwright-cli tab-list
playwright-cli tab-new [url]
playwright-cli tab-close [index]
playwright-cli tab-select <index>

07 它适合谁

如果你属于下面这些场景，Playwright CLI 会很值得试：

你在用 Claude Code、Copilot 或其他 coding agent 做 E2E 测试
你希望浏览器自动化接口更轻量，不想把大量页面结构塞进上下文
你希望同一个浏览器 session 能跨多次命令持续存在
你想在 agent 自动跑网页任务时，随时打开监控面板观察进度

如果你的工作重点是“浏览器自动化如何与 coding agent 高效配合”，Playwright CLI 很可能会比传统的人类手动调试方式更顺手。