本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。英文原文

WebMCP 浏览器桥接

状态：实验性范围：公开、当前状态最近审阅：2026-10-10 负责人：AX Code 维护者

WebMCP 桥接让智能体在隔离的 Chrome 窗口中打开页面、阅读它们，并（可选地）对它们采取行动。它是实验性的，默认关闭，需要 Chrome 150 或更新版本。

WebMCP 是一项提议中的 Web 标准。页面可以注册结构化工具——名称、描述和输入模式——以便智能体直接调用这些动作。AX Code 消费页面注册的工具，也可以自己阅读并操作页面。

Codex 和 ChatGPT Work 把其内置浏览器对同一标准的版本记录为站点工具。该页说明他们的桌面应用如何打开 WebMCP、访问者如何检查站点提供的工具，以及站点作者如何注册工具。下面的步骤是 AX Code 的。

用 Chrome 启用

安装 Google Chrome 150 或更新版本。相同主版本的 Chromium 也可以。AX Code 在全新配置档上启动自己的 Chrome 窗口，而不动已经打开的 Chrome 窗口。
用 ax-code 启动终端界面。
点击侧边栏页脚中的 WebMCP 芯片，或主页提示页脚上的同一芯片，或运行 /webmcp。点击或命令就是同意。在此之前不会启动浏览器。AX Code 会先在不启动浏览器的情况下检查通常位置是否安装了 Chrome 150 或更新版本，若没有则警告你；该检查是建议，从不会阻止尝试。你的选择保存到用户配置，因此下次启动时桥接会回来，无需再点一次。
AX Code 打开该隔离窗口并启用 WebMCP 功能（--enable-features=WebMCP）。在你亲手登录之前，窗口里没有登录状态。
让智能体打开一个页面。在产品默认下，导航不受限制。已配置或受管的来源列表会收窄它。
再次点击芯片以关闭桥接。这会结束临时的会话授予；已保存的批准会保留，直到你在 MCP 设置中撤销它们。

交互层级开启时，芯片显示 [act]。产品默认包含该层级。要关闭它，把 interact 在条目的 webmcp 配置档中设为 false。你更早保存的条目保留它当时的层级。

ax-code mcp webmcp 打印一段配置片段。它不安装包、不连接服务器，也不写文件。添加 --interact 可打印交互层级开启的条目，或用 --executable-path /absolute/path/to/chrome 指定某个 Chrome 150+ 二进制文件。设置该路径时，AX Code 会在启动前检查二进制文件的主版本。

在你自己打开的 Chrome 窗口中的工具

上面的隔离窗口已经启用了 WebMCP。要在你构建站点时使用的 Chrome 配置档中试用页面工具，请遵循 Chrome 的 WebMCP 指南：

打开 chrome://flags/#enable-webmcp-testing。
把标志设为 已启用。
重新启动 Chrome。

该标志适用于你打开的 Chrome 配置档。AX Code 桥接仍从芯片启动。

提示暗示

桥接关闭时，提到 URL 或本地服务器的提示（例如 localhost:3000）会显示指向芯片和 /webmcp 的一行指针。它每个会话最多出现一次，总共三次，并且从不改变发送给智能体的内容。

智能体能做什么

层级	工具	批准
页面	列出、打开、导航、关闭页面；运行页面通过 WebMCP 注册的工具	每次调用，除非已保存受支持的范围
读取	页面快照、截图、控制台、请求元数据	每个来源每个会话一次授予，或已保存的读取批准
交互	点击、悬停、等待、填写、填写表单、按键、回答对话框	见下文

页面内容不受信任：页面可以试图引导智能体。输出会标上来源并限制大小。

保存批准

合格的提示提供带红色背景的 加入 WebMCP 允许列表。选择它，审阅范围，然后选择 添加并允许。已保存的批准适用于本机上的此项目，并在浏览器重连和 AX Code 重启后仍然保留。

页面列表批准 AX Code 浏览器的 list_pages，包括所有打开来源的标题和 URL。它不批准页面内容。
导航批准打开或导航到一个确切来源。
读取批准一个确切来源上的快照、截图、控制台和网络元数据。其他来源和端口需要各自的批准。
关闭批准关闭当前位于一个确切来源上的任何页面，包括有未保存工作的页面。它是单独的选择：导航和读取批准并不授予它。关闭之前会再次检查目标来源。

第一次读取批准之后，AX Code 在再次检查页面后于同一次调用中继续该读取。页面或桥接变化会停止调用并要求新的读取。它不会重放失败的浏览器操作。

导航限制和管理员策略仍然适用。保存批准不会编辑 allowedOrigins。输入、重要点击、对话框和页面注册的工具保持其现有批准。允许一次 仍然是临时的；倒计时从不保存持久批准。

选择 WebMCP 芯片旁边的 WebMCP 允许列表 链接（会话侧边栏页脚和主页提示页脚），运行 /webmcp-allowlist，或打开 /mcp，选择桥接，并按 Ctrl+G。双击一个条目（或按两次 Enter）以撤销它；第一次激活标记该行，几秒内的第二次确认，因此单击从不会撤销。清除行以同样方式撤销此项目中该桥接的全部已保存批准。长列表可以滚动。按 Escape 或点击面板外部以关闭它。

搜索框也可以添加批准。输入确切的 https:// 来源（或 http://localhost），然后选择导航、读取或关闭行来保存它；在保存之前会提供页面列表行。桥接必须已连接：显式批准绑定到正在运行的桥接身份，并在每次调用时检查，与从提示保存的批准完全一样，因此受管来源列表、读取层级开关和管理员策略仍然适用。关闭 WebMCP 芯片会断开浏览器并保留已保存的选择。

本地存储默认是 ~/.local/share/ax-code/webmcp-approvals.json（适用 XDG 数据目录覆盖）。批准绑定到桥接身份；更改其启动或浏览器配置档需要新的批准。

页面打开或变化之后可能发生导航错误。错误在可用时报告可识别的超时、网络或页面缺失类别，而不回显原始桥接错误文本。决定是否再次导航之前先检查 list_pages。导航错误不会移除已保存的批准。

交互层级

悬停和普通点击在每个来源的一次授予下运行，有效 20 个动作，然后同一提示返回。

输入、按键、对话框、链接、双击，以及名称听起来重要的点击（提交、支付、删除、授权等）每次都询问，并显示目标和完整值。
名称看起来像凭据的字段会被标记并遮蔽。形态像 API 密钥或私钥的值会被拒绝：请自己输入凭据。
动作需要同一页面的新快照；页面移动或元素未知会被拒绝。一个回合中三次拒绝会停止进一步的动作。

基于名称的检查是启发式，不是保证。提示才是控制，所以请阅读它。

使用现有页面

让 AX Code 检查页面的能力、开发其原生工具，或诊断特定行为。browser_workflow 工具把这些任务分组，普通观察不需要你启动测试服务器。先启用桥接并指明目标页面；这些动作都不会打开页面、登录、更改浏览器配置档或安排未来工作。

例如：“检查我本地应用上的工具，并显示它们对应哪些应用函数”，或“在我复现空白结果之前捕获此页面，然后比较错误并指出候选源文件”。

检查原生工具及其源

调用 status，并带上 server、pageId 和确切的 origin，以查看实际准入的工具以及原生/快照可用性。空列表并不能确立无法访问的框架没有工具。现有连接器可能更适合不需要页面上下文的任务。

{
  "action": "inventory",
  "server": "webmcp",
  "pageId": 1,
  "origin": "http://localhost:3000",
  "sourceFiles": ["src/tools.ts", "public/search.html"]
}

保留返回的 inventoryId。在稍后的清点调用中把它作为 baselineId 传入，以查看新增/移除的工具和已变化的模式字段。文件经过显式权限检查、包含在仓库内且有界。静态的命令式注册和带引号的 HTML 表单属性会产生源候选；计算得到的名称、重复定义和不支持的模板仍未解决或含糊。匹配的名称和模式可以佐证候选，但不能证明浏览器加载了该源修订。

生成应用集成

使用 author 返回可审阅的集成代码：

{
  "action": "author",
  "name": "find_products",
  "description": "Find products matching a query in the current catalog.",
  "module": "./src/catalog.js",
  "exportName": "findProducts",
  "schema": {
    "type": "object",
    "properties": { "query": { "type": "string" } },
    "required": ["query"]
  },
  "format": "imperative",
  "effect": "read"
}

被命名的函数必须是直接导出。生成的注册接受用于组件/路由清理的 AbortSignal。仅当应用函数接受并尊重第二个参数时才设置 acceptsSignal: true，该参数是 {signal}。format: "declarative" 返回一个表单加上供人工提交的模块绑定；把它的 webmcp-result 事件连接到应用界面。支持原始字段；不支持的模式约束会被拒绝，而不是静默丢弃。应用任一模板之前，请审阅应用校验、授权和实际效果。即使表单要求人工提交，字段编辑仍可能触发自动保存。

分别检查执行和模型选择

现有的 contract 步骤验证固定输入和预期结果。在路由或角色变化之后添加 {"action":"tool_presence","name":"admin_reset","present":false}，以检查不可用的操作已被注销。present: true 也可以固定 descriptorHash。这些是生命周期检查点，不是事件追踪。导出的回归包含相同的检查。

使用单独的选择评估来发现模型是否选择了正确的工具和参数：

{
  "action": "selection_eval",
  "inventoryId": "<returned inventory UUID>",
  "cases": [
    { "task": "Find AX products", "expected": { "name": "find_products", "arguments": { "query": "AX" } } },
    { "task": "Delete every product", "expected": { "name": null, "arguments": {} } }
  ],
  "repeats": 2
}

所选的 API 模型只收到任务和捕获的目录，没有执行工具或预期答案。调用经过批准，并限制为 12 个用例、三次重复和两分钟评估截止时间。报告记录模型身份、套件哈希、分开的确切选择/参数计数、联合正确性和未知结果。失败留在分母中。CLI 模型不能用于此评估，因为它们可以运行自己的工具。选择分数不能证明工具正确，也不能使 Arena 合格。

在动作前后诊断

调用 observe，使用相同的页面目标、可选的 sourceFiles，以及显式的 assertions，其模式沿用现有的角色/名称和计数/值/选中/禁用。通过已批准的工具或手工执行所请求的动作一次。然后调用 {"action":"diagnose","observationId":"<returned UUID>"}。结果比较断言结果、快照哈希、有界的控制台和请求元数据增量、语义清点变化和源候选。关联是需要调查的证据，不是已证明的根因。没有断言时状态是 observed，而不是 pass。

基线只保存在当前运行时会话中，30 分钟后过期，每个会话限制为 16 个。连接/页面位置变化会使复用失效。固定的桥接无法识别同一 URL 的重新加载，因此这些比较仍然是建议性的。只保留页面位置和快照的哈希；有界的诊断文本和工具描述符是不受信任的证据。

对于可复现的 localhost 问题，promote 接受观察 ID 和包含本地测试服务器命令与步骤的显式普通 manifest。它冻结一个新的受控场景。观察结果从不会复制进验收：编辑之前先运行失败的对照，并通过现有工作流使修复后的运行合格。

重复日常观察任务

按需配方检查现有页面，而不导航或调度：

{
  "action": "recipe",
  "server": "webmcp",
  "pageId": 1,
  "definition": {
    "version": 1,
    "name": "Preview health",
    "origin": "http://localhost:3000",
    "assertions": [{ "locator": { "role": "status", "name": "Ready" }, "property": "count", "equals": 1 }]
  }
}

默认仅快照。可选的 queries 包含确切的工具 name、descriptorHash、对象 input、resultPath 和 equals。它们在现有的逐次调用批准下调用真实的应用工具；只读提示并不能认证效果。结果明确区分快照观察和效果未验证的应用调用，并在查询之后重新检查快照。保存已审阅的定义，而不是捕获的内容或凭据。定义不携带权限，也从不变成 Arena 回执。通过只意味着声明的观察匹配；缺失的数据不能满足检查。

手动注册工具

让智能体添加一个复用页面已有逻辑的工具，或从页面的 JavaScript 注册一个。Chrome 的指南涵盖命令式 API 和声明式表单 API。最小的只读工具如下：

if (typeof document.modelContext?.registerTool === "function") {
  await document.modelContext.registerTool({
    name: "read_heading",
    description: "Read the main heading of the current page.",
    inputSchema: {
      type: "object",
      properties: {},
      additionalProperties: false,
    },
    annotations: { readOnlyHint: true },
    execute: async () => ({
      heading: document.querySelector("h1")?.textContent ?? "",
    }),
  })
}

兼容的智能体随后可以在该页面上发现 read_heading。OpenAI 的站点工具页面从 Codex 和 ChatGPT Work 一侧讲解同一想法，包括其内置浏览器如何列出站点提供的工具。

限制

没有脚本、上传、下载、Cookie、请求正文、坐标或拖拽。管理员可以用受管的 webmcp 要求禁用桥接或任一层级（allow、allowRead、allowInteract、allowedOrigins）；项目和用户配置不能放宽它。

你用 ax-code mcp add 添加的服务器是另一条信任路径。见 MCP 集成。

用五步调试 localhost 页面

对于渲染错误的页面、没有反应的控件，或失败的请求：

导航到页面并拍摄快照——无障碍树是结构基线。导航和读取使用现有批准。
在现有交互批准下执行失败的动作一次。
读取增量：动作周围的控制台错误和网络元数据（方法、URL、状态、类型——请求和响应正文不在范围内）。对于异步状态，请等待；从不重复触发动作。
判定：通过、失败，或受阻并指出缺失的能力。工具确认并不是应用成功的证明。
如果 localhost 失败可以表达为结构化断言，把它冻结为 browser_workflow 场景（见下），记录失败的对照，并在修复之后把同一哈希运行两次。

把证据附到缺陷报告

对于通过冻结场景调查的 localhost 失败，证据包使报告可审阅：场景名称和哈希、失败的断言结果（不含捕获的页面内容）、来自 browser_workflow inspect 的回执 ID、快照哈希、有界的控制台错误和网络元数据增量、带 explicit/local_map/unresolved 标签的源链接，以及来源。只包含运行时有界、运行时已脱敏的输出——从不要请求或响应正文、头、Cookie、存储、页面内容或形态像凭据的值。回执 ID 和复制的回执数据只是引用；权威回执状态仍归运行时所有。

复现并验证开发变更

browser_workflow 工具在你编辑 Web 应用之前冻结验收步骤，通过已连接的 WebMCP 桥接运行它们，并记录结构化断言。先启用桥接。第一个受支持的环境是 127.0.0.1 上的一次性 HTTP 服务器；每次运行分配不同的端口和临时数据目录，外加全新的隔离浏览器上下文。持久浏览器配置档会被拒绝。空上下文由上游桥接保留到断开为止；一条连接上运行 32 次之后，继续之前请重新连接桥接。工作流从不会复用它们的 Cookie 或存储。

让智能体用 action: "freeze" 冻结场景。例如，项目拥有的、接受端口参数的 test/browser-server.mjs 可以使用：

{
  "action": "freeze",
  "manifest": {
    "version": 1,
    "name": "Search returns a matching result",
    "server": "node test/browser-server.mjs {port}",
    "path": "/",
    "setup": [],
    "reset": [],
    "cleanup": [],
    "steps": [
      { "action": "fill", "locator": { "role": "textbox", "name": "Search" }, "value": "example" },
      {
        "action": "assert",
        "assertion": {
          "locator": { "role": "status", "name": "One result" },
          "property": "count",
          "equals": 1
        }
      }
    ]
  }
}

保留返回的哈希。用 {"action":"run","hash":"<hash>","server":"webmcp"} 运行（使用你已连接桥接的名称）。复现失败，做出变更，并把同一哈希运行两次。每次运行启动声明的服务器，打开自己的页面，检查步骤，关闭页面并停止其服务器。生命周期命令通过正常的 shell 权限在仓库根运行。{port} 展开为分配的端口；{data} 展开为带引号的临时目录。设置、重置和清理命令必须在 15 秒内终止；就绪有 15 秒截止时间，浏览器运行有 120 秒截止时间。浏览器动作保持其现有权限和交互预算。

支持的步骤是点击、悬停、填写、结构化断言和页面工具契约检查。定位器使用确切的角色和可访问名称。零个或多个匹配的动作以 unknown 停止；没有猜测的 UID 或 CSS/脚本回退。断言比较计数、值、选中或禁用状态。缺失的状态属性是未知。对于异步渲染，添加 timeoutMs（0-10000，默认 0）到 assert 步骤。运行器轮询新的结构化快照，直到断言匹配或截止时间到期；它从不重复前面的点击或填写。超时与场景一起冻结，并保留在其导出的测试中。场景限制为 32 步和 32 KiB。

inspect 返回冻结的清单和运行时回执。回执把场景绑定到仓库修订/内容、操作结果、快照哈希和有界的控制台/网络元数据。源变化、被拒绝的操作、缺失的证据、超时和不完整的清理不能通过。这些结果验证声明的断言；它们并不证明应用的每一种行为。冻结状态和权威回执位于当前运行时会话中。重启之后请再次冻结并合格；复制的 JSON 回执不被接受为运行时权威。

导出回归测试

{"action":"export","hash":"<hash>"} 返回使用 playwright-core 的独立 Node 模块。把返回的代码保存为项目测试，并用指向 Chrome 的 AX_TEST_WEBMCP_CHROME 运行它。它启动同一夹具，并使用全新的浏览器上下文、稳定的角色/名称定位器和冻结的断言。在称之为已验证之前，请实际运行导出的测试。导出的测试是独立的回归产物；其输出不是 Arena 回执。页面工具契约步骤使用 Chrome 的原生 WebMCP 协议，带确切的描述符哈希和预期输出，而不求值任意页面脚本。Chrome 必须支持该实验协议，契约导出才能进行。

开发页面工具契约并调查失败

页面打开时，{"action":"contracts","server":"webmcp","pageId":1} 返回其已注册的描述符和确切的描述符哈希。冻结一个 contract 步骤，其中包含 name、descriptorHash、input、resultPath 和 equals。哈希变化会使检查失败。对否定输入设置 expectError: true：只有确认的页面工具执行错误才能满足它；取消的调用、权限拒绝和缺失的完成是未知。在变更之后添加断言，以同时检查结果页面状态和返回值。

template 动作接受 name、相对的应用 module、显式的 exportName 和 schema。它验证本地导出存在，并返回注册骨架。启用之前对照应用的输入校验、授权和业务逻辑审阅它；该工具不能从导出的函数名确立那些保证。

可选的 sources 列表命名仓库本地文件，带从 1 开始的 line 和从 0 开始的 column，以及可选的本地 map 文件。失败的运行返回有界诊断和标为 explicit、local_map 或 unresolved 的源链接。映射是建议性的，从不是根因或通过断言的证明。远程映射、仓库之外的路径和超过 1 MiB 的文件不会被读取。浏览器网络证据仍然只是元数据。

在实现 Arena 中要求浏览器证据

提供 browserScenario: "<hash>"，并带上 mode: "implement"。在启动 Arena 之前冻结场景，并在当前干净基线上记录一次真实的失败断言。每个候选在其隔离工作树中收到该冻结契约，并且必须通过其已连接的隔离桥接成功运行两次。浏览器激活和权限仍然受监督。缺少桥接访问、过期内容、未知结果或缺失回执会阻止提升，即使仓库检查通过。正常的代码验证和变更检查仍然运行，并且没有候选会自动合并。

高效选择证据

原生 WebMCP 工具描述应用操作；Chrome DevTools MCP 提供浏览器检查和自动化。对明确的应用操作优先使用页面已注册的工具，然后验证其结果和结果页面状态。对文本和稳定元素定位器使用无障碍快照。对于布局、画布或仅图像内容，拍摄截图：裁剪到新的快照 uid，或使用降低质量的 JPEG 以留在内联限制内。解释像素需要具备视觉能力的模型。WebMCP 和已记录的 DevTools MCP 工具列表都不提供专用 OCR 工具；推断的图像文本是建议性的，不能满足结构化验收断言。

用 types 和 pageSize 收窄控制台读取；用 resourceTypes 和 pageSize 收窄网络元数据。工作流回执保留动作前基线和有界增量，以便更容易找到复现引入的错误。网络正文和任意求值仍在桥接授予的表面之外。上游 DevTools MCP 中的性能追踪、仿真、Lighthouse、屏幕录制、内存和扩展工具是分开的能力，此配置档不暴露它们。

见 Chrome 的 WebMCP 调试指南和上游的 DevTools MCP 工具参考。上游主分支可能与 AX Code 固定的桥接不同；只有本地工具模式描述受支持的参数。