Claude Code 与 Playwright MCP

核心摘要

Claude Code 与 Playwright MCP 的最佳用法，不是“让智能体一直浏览到自己认为完成”，而是建立一连串可观察的任务约定：创建会话、检查实时页面、执行一次获准操作、重新获取页面状态，再把直接证据与预先定义的成功条件对照。本页重点讲这种运行方式；安装命令、作用域、连接检查和卸载方法可查看单独的 Playwright MCP 配置指南。

在 Claude Code 中配置 Playwright MCP

先判断 MCP 是否适合这项任务

官方 Playwright MCP 仓库已经区分 MCP 与 CLI 浏览器工作流。任务需要保持会话状态、深入读取页面结构，并在变化中的界面上反复判断时，MCP 更合适；如果编码智能体更看重简洁命令和上下文效率，CLI 或 skill 方式可能更轻；当执行路径与断言已经稳定、需要进入 CI 时，则应直接编写正式 Playwright 测试。

• 选择 MCP：探索式调试、陌生界面、动态工作流，或下一步必须根据当前页面状态决定的任务。
• 选择 CLI 或 skill：操作路径简洁明确，加载较大的 MCP 工具定义只会增加上下文负担。
• 选择正式测试：前置条件、定位方式、断言和输出均已固定，需要每次构建以相同方式运行。
• 选择人工处理：涉及法律判断、不可逆资金影响、敏感个人数据或模糊视觉判断。

接入凭据前先确定会话模式

Playwright MCP 可以使用持久化配置文件、隔离上下文、预先提供的 storage state，或通过浏览器扩展连接已有标签页。处理公开页面时，优先从隔离或一次性会话开始。持久化配置可以减少重复登录，但会保留 Cookie 和本地状态，因此应配合专用账号与专用配置使用，不要直接接管个人日常浏览器。扩展方式适合复用已经登录的标签页，但也会暴露更多无关会话状态，只应在任务范围非常清楚时采用。

围绕验收证据配置输出

不要默认开启所有能力。先判断任务究竟需要无障碍快照、截图、控制台信息、网络请求、下载文件、生成代码，还是保存完整会话。如果需要保留证据，应设置受控的输出目录；视觉验收需要固定视口；控制台级别要能捕获有效错误，同时避免无关日志淹没执行记录。只有结果确实与设备或视口相关时，才加入设备模拟。

建立干净的基线

在使用账号前，先让 Claude Code 打开公开页面，在不进行修改的情况下返回最终网址、页面标题、一个可见标题和一个具名控件；随后只允许一次可逆跳转，并要求返回新网址与标题。这样可以确认服务器进程、浏览器启动、页面快照、工具调用和状态刷新都正常。如果其中任何一层失败，应先停下来排查；此时继续加入登录状态或更多参数，只会让问题更难定位。

采用“检查—执行—验证”工作流程

把请求改写成可观察的任务约定

浏览器提示词不能只有一个目标，还要包含起始网址、用户可见的预期结果、允许域名、可执行动作、禁止事项、人工检查点和完成证据。“更新 Webhook”既不安全，也难以验收；“打开测试环境设置页，找到 Webhook 表单，填写这些值，报告所有字段，并在保存前停止”则给出了稳定目标和明确停止点。

执行严格的五步闭环

• 确认环境：核对实时网址、账号或环境、页面标题，并检查登录墙、Cookie 同意页或重定向是否改变了上下文。
• 检查页面：读取当前无障碍快照，通过角色、可见名称、标签或稳定测试 ID 定位控件。
• 执行动作：一次只做一个边界明确的导航、输入或点击，不要基于旧快照连续猜测操作。
• 重新获取：导航、刷新、弹窗、iframe 或动态内容变化后，再次检查实时页面。
• 验证结果：将最终网址和可见证据与成功条件对照；无法确认时如实报告，不要推断成功。

不同任务使用不同验收证据

网页调研应保留最终来源网址，以及答案实际使用的页面字段；复现缺陷需要记录起始状态、最短操作序列、可见错误、必要的控制台信息和失败前状态；表单准备应在提交前逐字段汇总；保存设置后，既要看到成功提示，也要刷新页面确认数据仍然存在；视觉验收则要提前规定视口尺寸和截图中必须出现的组件状态。

把闭环应用到常见开发任务

调查界面问题时，先让 Claude Code 梳理相关控件和状态，再提出测试方案；复现缺陷时，固定起始账号与数据，沿最短路径执行，并在第一次偏离预期的位置停止；处理内容或设置时，把“填写”与“提交”分开，让人工复核确切内容；构建回归检查时，可以先用 MCP 探索定位方式和状态，再把稳定路径写成正式测试，不要长期依赖自由形式的浏览器提示词。

让每次执行都能形成可用交接

一次执行结束时，不能只返回“已完成”。应给出简洁交接记录，包括起始网址、运行环境、已完成动作、主动跳过的动作、取得的授权、最终网址、成功证据、仍未确认的问题和相关产物路径。如果结果是一项待批准修改，要列出准备提交的准确值或内容；如果结果是缺陷，则要说明最后一个符合预期的状态、第一个异常状态，以及目前已知的最短复现路径。这样，即使没有旁观整个浏览器会话，其他人也能复核结果。

停止条件应与成功条件一样在执行前定义清楚。出现意外域名跳转、无法确认当前账号或环境、缺少前置条件、页面请求新增权限、准备提交的内容与已批准值不一致、证据互相冲突，或操作即将从“准备”跨入“产生实际影响”时，都应停止。能够在边界处准确暂停并说明原因，本身就是控制机制成功，并不等于自动化失败。

恢复时不要重复高影响操作

控件消失后，应重新获取页面快照；DOM 可能已经变化，控件也可能进入弹窗或 iframe。操作超时后，要检查页面是否仍在导航、是否打开新窗口、登录是否失效，或下载是否已经开始。重复提交前，先查找确认提示、网址变化、已保存值或重复记录。保留最后一个已知状态和错误前的动作，让下一次尝试基于证据，而不是从头猜测。

安全与调试实践

区分观察、准备与实际影响

在获准域名内进行只读检查通常可以直接继续；打开筛选器、起草内容或填写但不提交表单等可逆准备，应在复核点暂停；发送消息、发布、下单、接受法律条款、修改访问权限、上传私密文件或删除记录等高影响操作，则必须在执行前即时取得明确授权。审批提示需要写清目标对象和具体内容，让用户知道究竟会发生什么变化。

把浏览器状态当作凭据管理

• 使用专用测试账号或配置文件，不要直接使用个人日常浏览器。
• 密码、API Key、恢复码和原始 Cookie 不应出现在提示词、截图或长期日志中。
• 陌生网站或一次性任务优先使用短期隔离会话。
• 上传或下载前，按准确文件名检查来源路径和目标位置。
• 证据不再需要后，关闭会话并清理留存的敏感产物。

不要把来源过滤当作完整安全边界

Playwright MCP 提供允许来源和阻止来源选项，但官方配置明确说明，允许列表并不构成安全边界，也无法约束重定向。这些设置可以减少误访问，却不能替代账号隔离、最小权限、工作区信任和人工审批。除非任务确实需要，否则不要开放无限制文件访问；也不要为了绕过原因不明的启动错误而随意关闭浏览器沙箱。

QVeris 如何与 Playwright MCP 协同

结构化工作交给 API，渲染状态交给浏览器

• 任务依赖渲染后的界面、登录状态、界面专属控件或探索式交互时，使用 Playwright MCP。
• 经过核验的 API 或工具能够以类型明确的输入、可预测输出和更清晰的错误处理完成任务时，使用 QVeris。
• 也可以先通过 API 准备或校验结构化数据，再由浏览器录入或进行视觉确认。
• 在已准备数据与会产生外部影响的浏览器操作之间，保留人工审批。

QVeris 不负责配置本地 MCP 服务器、管理浏览器配置文件，也不会替用户批准 Claude Code 工具调用。只有当更完整的工作流需要在界面自动化之外调用结构化能力时，它才开始发挥作用。如果某项操作已经有正式 API，直接调用通常比网页导航更简单；如果验收对象就是渲染后的体验，Playwright 才是正确执行层。

常见问题