跳转至

Chrome 扩展

OpenClaw Chrome 扩展可让浏览器工具自动化你已登录 Chrome 配置文件中符合条件的标签页。它使用 chrome.debugger，因此不需要 Chrome 的阻塞式远程调试同意提示。

该扩展是浏览器自动化基础设施。它不包含聊天、页面共享、提示框或标签页副驾驶。其弹出窗口显示连接状态、当前访问模式、针对当前符合条件标签页的暂停/允许操作，以及设置链接。

要求

  • Google Chrome、Chrome for Testing 或 Chromium
  • 在 Chrome 所在同一台机器上安装 OpenClaw，或在该机器上有一个 OpenClaw 浏览器节点
  • macOS/Linux，或带有自包含 OpenClaw 原生引导可执行文件的 Windows
  • 对于 macOS 上除 Google Chrome 以外的浏览器，至少启动一次浏览器，使其用户数据目录存在

Windows 使用 OpenClaw.BrowserBootstrap.exe，而不是批处理或 PowerShell 启动器。 设置会查找打包的辅助程序或 Windows Companion 安装。便携安装可以使用 --native-host-executable 选择其绝对本地路径。 共享的 Windows 注册服务负责原生注册和 Store 请求。 独立的 Windows CLI 通过可执行文件的有界管理接口进行委托，显式绑定其 Windows Node/CLI、状态目录、配置路径和浏览器配置文件。Companion 使用其独立的受管 WSL 模式和实时 Gateway 权限。当任一模式不可用时，两者都不会回退到另一种模式。 私有的、经过验证的生成位于当前用户的 Local App Data OpenClawTray 目录之下。该服务在将 Chrome/Chromium 注册到两个适用的用户注册表视图之前，会验证二进制帧和准入。它不会覆盖外部注册、遮蔽机器注册，或将 WSL/UNC 路径或 SSH 回环 URL 视为本地 Windows 权限。缺失/不兼容的可执行文件或 unsafe ACLs 会保持设置被阻止；没有脚本回退或复制密钥提示。 不同的现有模式/上下文或旧版无法识别的注册会被保留并报告为冲突，而不是被静默替换。没有干净回执的中断管理是未知结果：在重试之前检查相同上下文。 Windows Store 移除使用 extension uninstall-host --remove-store；这会先移除拥有的 Store 请求，然后移除拥有的原生注册。macOS 的 uninstall-store 命令继续保持原生注册不变。

安装

在托管 Chrome 的机器上运行此命令。macOS 上的 Google Chrome 可以在首次启动前准备；其他受支持的浏览器需要先启动一次。有关完整的 browser extension 子命令参考，请参阅 openclaw browser：

openclaw browser extension install

在你完成 Chrome 设置期间保持命令运行。在 macOS 上，它首先注册原生主机，然后请求 Google Chrome 安装官方 Store 扩展。Chrome 会在浏览器启动时发现该请求。如果 Chrome 已在运行，请在方便时完全退出并重新打开它，然后在 Chrome 中批准或启用 OpenClaw。OpenClaw 绝不会替你重启 Chrome 或批准其权限提示。该请求适用于该 Chrome 用户数据目录中的所有配置文件。Chrome 控制每个配置文件中的批准。

原生 macOS 应用会在主要启动后以及成功安装或更新 CLI 后自动准备此设置。打包应用使用其经过验证的私有运行时，因此仅远程的 Mac 不需要单独安装 CLI。自动注册属于默认应用配置文件；命名配置文件保留显式设置，因为 Chrome 每个用户共享一个原生主机注册。

仪表盘 → 设置 → 此 Mac → 浏览器 → 在此设备上设置 Chrome 会重试相同的序列化规范设置控制器。它始终准备此 Mac，而不是远程 Gateway。浏览器设置和原生辅助程序读取配置，而不进行 Gateway 范围的 Doctor 或独立管理的 Gateway 数据库迁移。普通浏览器命令仍会报告无效配置。基于浏览器的仪表盘提供 Store 和设置指南链接，而不是在本地安装软件。

Tauri 桌面应用也会在启动时以及本地 CLI 设置后准备本地辅助程序。发布版本可以在其应用数据目录中配置匹配的仅限浏览器的运行时，而无需更改 Gateway 服务或其已安装代码。在注册成功后，使用托盘中的 设置 Chrome 扩展… 重试并打开官方 Store。启动时绝不会打开 Store 窗口或撤销 Chrome 移除/禁用选择。开发版本需要一个现有 CLI，并且 Windows Tauri 测试版本不会配置此运行时。仅远程的桌面连接仍需要在 Chrome 主机上有一个浏览器节点，以将其标签页暴露给 Gateway。

此 Mac 页面在打开时以及你从 Chrome 返回时会检查安装。现有扩展会显示 已安装，包括 Chrome 仍需要你启用它的情况。如果其本地辅助程序缺失，在此设备上设置 Chrome 会修复自动配对，而不会将扩展视为不存在。刷新设置状态 会刷新此状态而不安装任何内容。安装状态并不能证明实时连接；请单独打开扩展以检查。当自动状态检查不可用时，旧版 Mac 应用会保留其设置操作。更新 Mac 应用以检测现有安装，而无需运行设置。

在 Linux 和其他受支持的 Chromium 浏览器中，在原生主机注册成功后，添加 来自 Chrome Web Store 的 OpenClaw。Linux 不支持此按用户的 Store 安装请求。在 Windows 上，在原生可执行文件通过设置后添加 Store 扩展。受支持的同一主机配对随后通过原生通道发生，无需复制密钥。Chrome 仍拥有其安装和权限批准。

你也可以使用 Store 链接，如果 Chrome 未提供所请求的安装。 如果你之前移除了扩展，Chrome 会记住该选择。请从 Store 中显式再次添加它。OpenClaw 不会清除 Chrome 的移除决定。

在 macOS 和 Linux 上，源锁定原生主机允许确切的官方 Store 身份和 OpenClaw 的确定性开发 ID。启用后，扩展会在其首次原生调用时配对。安装程序会检查配置文件的 Preferences 和 Secure Preferences 后备文件，并独立于任何扩展路径验证确切的 Store ID。Chromium 根据设置强制策略选择后备文件。Linux 通常使用 Preferences。两个文件都会接受相同的所有权、路径、文件类型、权限和大小检查。

对于扩展开发，请跳过创建 Store 安装请求：

openclaw browser extension install --no-store

这仍会将捆绑的扩展复制到稳定的 OpenClaw 拥有的目录，并注册原生主机。它不会更改任何现有 Store 请求。将未打包副本用作开发回退方案：

  1. 打开 chrome://extensions。
  2. 启用 开发者模式。
  3. 点击 加载未打包。
  4. 选择命令打印的路径。

在完成 Store 或开发设置期间，请保持安装命令运行。对于未打包开发，安装程序会验证 Chrome 是否在其预测的确定性 ID 下加载了已批准的 realpath。

安装程序仅通过确切的 Foundation Store ID 识别官方 Store 安装。该身份永远不会使已记录的路径由 OpenClaw 拥有。对于未打包开发，只有当以下所有条件都为真时，它才会接受某个 ID：

  • 该 ID 符合 Chrome 的 32 字符扩展 ID 格式。
  • Chrome 将安装位置记录为未打包。
  • 已记录的扩展路径精确解析到已安装或捆绑的 OpenClaw 扩展目录。
  • 已记录的 ID 等于 Chromium 针对该确切规范 realpath 的确定性路径 ID。

扩展名称不受信任。具有相同主机名的现有原生主机文件不会被覆盖，除非可以验证它们由 OpenClaw 拥有。

需要时使用不同的有界等待：

openclaw browser extension install --wait-ms 60000

对于自动化，请使用 --json。结果会分别报告 Store 安装请求、Store 发现和批准、已批准的未打包 ID 和路径，以及原生主机注册健康状况。这些本地观察结果不能证明存在实时连接。请验证扩展的连接状态，并针对目标 Gateway 或浏览器节点运行 openclaw browser --browser-profile chrome tabs。JSON 输出从不包含中继密钥或配对字符串。

共享设置控制器

CLI、原生桌面适配器和终端设置流程在托管 Chrome 的机器上使用同一个由 Browser 拥有的控制器。

设置的安装状态描述的是 Google Chrome。openclaw browser extension install 和 openclaw browser extension status 命令也支持 Chromium 和 Chrome for Testing。

openclaw browser extension setup --action inspect --json
openclaw browser extension setup --action install --json
openclaw browser extension setup --action verify --browser-profile chrome --json

inspect 读取安装状态，而不进行安装或连接。install 准备自动本地引导；Chrome 仍然拥有扩展安装和权限批准。对于受支持的本地原生引导，没有需要复制的配对码。现有配对和显式的自动设置退出选项保持不变。verify 使用现有的每主机密钥对确切的本地配置文件中继进行身份验证。它不会创建密钥、启动另一个中继或获取远程 Gateway 密钥。

在 macOS 和 Linux 上，受支持的捆绑路径迁移会保留经过验证的私有清单和启动器中保存的配置文件。现有单槽源迁移规则保持不变：在修复之前，注册项已拥有但尚未为新捆绑做好准备。没有保存选择器的旧启动器会保留其原始选择：第一个已配置的扩展配置文件，独立于 browser.defaultProfile。无选择器的设置会拒绝未验证或外部的注册。显式的 inspect 和 verify 请求必须与已注册的配置文件匹配；使用 setup --action install --browser-profile <name> 来更改它。显式选择不能绕过所有权或源检查。设置不会轮换现有中继密钥或重写 Chrome 配对偏好设置。

设置还会保留已注册状态和配置选择。如果当前进程使用不同的配置，它会在安装或中继访问之前停止。请使用匹配的 OPENCLAW_STATE_DIR 和 OPENCLAW_CONFIG_PATH 重新运行；选择另一个浏览器配置文件不会授权更改配置文件。隐式默认配置及其显式路径被视为同一选择。设置在发布替换原生主机清单之前会重新检查已保存的选择。

在 Windows 上，省略配置文件选择会使用有界的、串行的只读检查来检查已配置的扩展配置文件。只有当前匹配的 C# 注册描述符，在针对其绑定和请求上下文独立验证后，才能选择已保存的配置文件。设置会在继续之前确认该观察结果；C# 所有者会重新验证单个安装操作。未知、冲突、已更改或不可用的证据绝不会静默选择 chrome。真正缺失的注册可以使用现有的全新安装默认值。

如果已保存的配置文件不再配置，或者 Node/CLI 路径或已批准的扩展源已更改，Windows 契约可能返回没有匹配的描述符。然后自动选择会停止，而不尝试安装。请审查预期的现有配置文件并显式修复，例如 openclaw browser extension setup --action install --browser-profile work。这不是自动运行时升级恢复：不同的状态、配置、配置文件或 Companion 模式仍然是上下文冲突，而不是接管。

JSON 结果包含 action、带有 kind: "local-host" 的 target、平台、主机名、配置文件和中继端口，以及 phase、reason、installation、connection 和 nextAction。安装报告将已安装的配置文件与已启用的配置文件分开计数，因此已禁用的扩展不会被显示为缺失。有效的 pending 或 blocked 结果会成功退出；命令或执行失败会返回非零退出码。结果从不包含配对字符串或中继密钥。现有 install 和 status 命令保留其文档中说明的输出格式。

安装、Chrome 批准和经过身份验证的连接是相互独立的事实。ready 表示所选中继具有经过身份验证的扩展；它并不意味着存在符合条件的标签页。空的标签页列表不代表扩展已断开连接。在使用自动化之前，请通过预期的 Gateway 或浏览器节点检查标签页。

目标是进程主机，而不是显示远程仪表板的计算机。通过 SSH 访问的 TUI 会在该 SSH 主机上运行设置。回环 URL 可能是 SSH 隧道，并不能证明 Gateway 和 Chrome 位于同一台机器上。原生设置不会静默重新指向当前显示的 Gateway。仅 Web 的仪表板会提供 Store 和设置指南链接，而不是在查看者设备上安装。

使用它

选择内置的 chrome 配置文件，或将其设为默认：

openclaw config set browser.defaultProfile chrome

{
  browser: {
    profiles: {
      chrome: { driver: "extension" },
    },
  },
}

新的自动配对使用 All tabs。现有有效配对永远不会被覆盖，旧配对会保留其存储的访问模式。

对于全新的本地设置，原生引导会通过本地 Gateway 的精确 /browser/extension 路由连接扩展。首次经过身份验证的连接会唤醒延迟加载的浏览器控制服务，并启动该配置文件的回环中继。OpenClaw 和 mcporter 等本地客户端随后使用该配置文件的中继端口。请保持 openclaw gateway run 或受管理的 Gateway 服务处于运行状态。无需单独的浏览器请求或预热步骤。

浏览器节点设置仍然不同：扩展连接到浏览器节点主机上的中继，而节点使用其配置的远程 Gateway。显式的 --gateway-url 配对会直接连接到该远程 Gateway，并且仍然是仅限手动操作的流程。

独立直接回环中继

对 ws://127.0.0.1:<port>/extension 的配对可以在没有本地 Gateway 或浏览器节点的情况下运行。在 macOS 和 Linux 上，捆绑的扩展可以在重新连接到该端点时请求已安装的原生主机启动独立中继。必须启用自动设置。请求限制为每分钟一次。扩展仍会使用与连接绑定的 v2 证明对中继进行身份验证。这需要更新后的原生主机以及包含中继唤醒支持的扩展构建。Store 发布可能滞后于捆绑扩展。捆绑的未打包开发副本是源码构建验证路径。

自动唤醒要求使用守护进程提供服务的精确 127.0.0.1 主机。其他回环别名，包括 localhost 和 IPv6，不会触发唤醒。为独立操作进行配对时，请使用规范的 IPv4 端点。

唤醒使用扩展现有规范配对中的端口。它不会切换到第一个配置的配置文件。原生主机会解析当前 browser.profiles，并且只允许扩展驱动程序的中继端口，包括自动分配的端口和显式 cdpPort 固定值。已删除的配置文件或过期端口会失败关闭。请更正配对以匹配当前配置文件。Gateway /browser/extension 路由和远程配对永远不会触发本地守护进程唤醒。使用直接回环中继的浏览器节点配对即使其 Gateway 提示指向远程主机也可以使用它。

现有监听器会保留其端口的所有权。否则，原生主机将 dist/extensions/browser/relay-daemon-entry.js 作为分离进程生成。守护进程使用相同的每主机中继密钥，并在扩展或 CDP 客户端连接期间保持存活。两者都断开后，它会在十分钟不活动后退出，每 30 秒检查一次。仅关闭 Chrome 不会在 CDP 客户端仍连接时停止它。稍后的重新连接可以再次唤醒它。

独立守护进程默认使用 仅 v2 身份验证，独立于 Gateway 中继的旧版默认设置。只有显式的 browser.extensionRelay.allowLegacyAuth=true 才会启用旧版身份验证。 未设置的值、false 或配置读取失败都不会启用它。请优先使用 v2 客户端，以免将持久密钥泄露给占用该端口的进程。

Gateway 浏览器控制可以加入已经拥有已配置配置文件和端口的独立中继。它会使用 v2 对该确切所有者进行身份验证，并使用其现有桥接。它不会启动第二个监听器。停止 Gateway 只会释放 Gateway 的连接，而守护进程、其直接扩展连接以及其他 CDP 客户端仍会继续运行。通过 /browser/extension 进行的 Gateway 优先自动设置仍然受支持。

守护进程和 Gateway 都必须运行实现了所有者访问协议的构建。混合版本不受支持。 不匹配的配置文件、端口、密钥或更严格的身份验证策略会产生错误。Gateway 永远不会接管监听器或回退到旧版凭据。守护进程更严格的仅 v2 默认设置与 Gateway 的默认设置兼容。

选择标签页访问

  • All tabs 会公开该 Chrome 配置文件中的所有符合条件的普通标签页， 但当前浏览器会话中已暂停的标签页除外。在弹出窗口中使用 Pause on this tab 和 Allow on this tab。
  • Selected tabs 使用 OpenClaw 标签页组作为访问控制 边界。将标签页移入该组会授予访问权限。将其移出会撤销 访问权限。

打开扩展的设置页面以更改访问模式。切换到 Selected tabs 会立即分离未分组的标签页，包括已在进行中的附加操作。代理创建的标签页在任一模式下都会保留在 OpenClaw 组中。

该扩展会排除隐身标签页、内部页面（例如 chrome:// 和 chrome-extension://）以及没有可用当前 URL 的标签页。file:// 访问 还需要 Chrome 的 允许访问文件 URL 设置。

由代理创建的标签页可能从 about:blank 开始，而 CDP 客户端会在导航前对其进行初始化。扩展会允许该特定初始标签页，将其保留在 OpenClaw 组中，并应用相同的暂停和访问模式控制。 常规导航会使该标签页在任一访问模式下保持可用。 现有空白标签页、手动分组的空白标签页以及其他 about: 页面仍不可用。导航离开、替换标签页，或重启或重连 扩展，都会结束初始空白准入。返回 about:blank 不会恢复它。

如果扩展在返回目标之前创建失败，它只会在仍拥有该标签页时尝试关闭它。您在创建期间暂停、移动或导航过的标签页会被保留。重定向、连接丢失或 worker 关闭可能会遗留一个标签页。如有需要，请手动关闭它。

对已授权标签页的显式命令式主框架导航也可以使用精确的 about:blank，例如在性能跟踪重置期间。Chrome 必须确认同一附加上的根框架和加载器。仅 iframe 导航或空白 URL 本身不会授予访问权限。

该临时准入会在下一个非空白文档、调试器分离、访问模式变更、暂停、组或窗口变更、标签页关闭或替换、重连或扩展重启时结束。导航失败绝不会关闭现有标签页，也绝不会覆盖您的导航来恢复某个 URL。

自动设置控制

设置页面会显示已脱敏的中继/本地主机引导状态，以及 使用自动本地设置 开关。

  • 关闭自动设置会保留有效的现有配对，但会阻止新的本地主机引导和独立中继唤醒尝试。
  • 断开连接并禁用自动设置 会立即撤销配对，分离调试器会话，并持久化退出选择。
  • 使用本地 OpenClaw 会清除退出选择并重试本地主机。
  • 保存显式手动配对也会清除退出选择。

在本地 Gateway 唤醒路由之前完成配对的非正式发布开发安装会保持其现有配对不变。在设置中，使用 断开连接并禁用自动设置，然后使用 使用本地 OpenClaw 创建新的本地配对。正式发布版本不需要此恢复步骤。

从已退役的标签页 Copilot 升级

如果设置页面显示自动化已暂停以保护升级前的 Copilot 会话，请确认旧运行已完成。然后单击 断开连接并禁用自动设置 以丢弃已退役的恢复状态，接着使用 使用本地 OpenClaw 重新连接。在该显式断开连接成功之前，扩展会保留已退役状态，并阻止中继连接、本地主机设置、手动配对、标签页访问变更和调试器附加。

Chromium 会为当前运行的浏览器进程缓存首次缺失本地主机的结果。如果现有扩展在本地主机安装之前已经尝试过自动设置，请重启一次 Chrome（完整的浏览器进程重载）。从弹出窗口或设置中重试无法清除该进程级别的缺失。正常设置会通过在添加或重新打开 Store 扩展之前预注册主机来避免此问题。对于开发，请在 Load unpacked 之前预注册。

状态和移除

在不打印凭据的情况下检查安装：

openclaw browser extension status
openclaw browser extension status --json

JSON storeInstallRequests 条目会为已验证的 OpenClaw 拥有的请求报告 requested，在没有请求存在时报告 missing，对于无法识别的注册报告 foreign，或者在文件无法安全读取或验证时报告 invalid。storeDiscovered 会分别报告 enabled 和 awaitingApproval。已请求的安装、已发现的扩展或已启用的扩展并不能证明存在经过身份验证的中继连接。

owned 本地主机注册不一定可启动。状态会报告其已注册运行时和本地入口的文件系统就绪快照。它不会执行任一目标，也不会验证其代码能否成功运行。如果升级移除了任一目标，请重新运行 openclaw browser extension install 以修复拥有的注册。所有权检查仍会拒绝外部或格式错误的清单和启动器。

托管部署所有者可以在不读取 Chrome 配置文件或 Store 请求的情况下检查已注册的入口点：

openclaw browser extension repair --dry-run --json

报告包括 retainedNativeHostPaths 和 retentionSafe。在相关注册迁移之前，请保留被引用的软件包版本。如果检查不完整（retentionSafe: false），请保留版本并报告警告；这不得将浏览器修复失败变成 Gateway 更新失败。

若要仅刷新属于某个已退役软件包的注册，请从该替换安装中运行命令，并使用精确的旧入口点：

openclaw browser extension repair --from /path/to/old/package/dist/extensions/browser/native-host-entry.js --json

修复会保持无关安装、缺失注册、稳定扩展副本、浏览器配置文件、Store 请求和配对凭据不变。即使修复命令在不同的环境设置下运行，它也会保留启动器保存的状态和配置选择。它使用与显式安装相同的所有权和来源检查。它不会重启 Chrome，也不会证明中继连接。替换启动器是不可变的；本地清单仅在其启动器完成后才会切换，因此清单写入失败会保留先前注册以供重试。通用 Doctor 仍会跳过个人浏览器配置文件发现；首次设置请使用 extension install。

仅移除 OpenClaw 的 macOS Chrome Store 安装请求：

openclaw browser extension uninstall-store

Chrome 可能会在请求被移除后的下次启动时移除外部安装的扩展。此命令会保留 native-host 注册和开发副本，并拒绝外部或格式错误的请求文件。

仅移除 OpenClaw 拥有的 native-host 清单和启动器：

openclaw browser extension uninstall-host

这不会从 Chrome 中移除 Store 或未打包扩展。请使用 chrome://extensions 执行该操作。它也不会删除稳定的开发副本或已有的中继密钥。

openclaw browser extension path 是只读的。如果存在稳定的已安装副本，则打印该副本；否则打印捆绑的源目录。

高级手动配对

设置页面负责手动配对。生成一个主机本地的配对字符串：

openclaw browser extension pair

手动配对对于不支持的拓扑和恢复仍然有用。请将完整的配对字符串视为密码。

在未提供 --gateway-url 或 --local-gateway 时，此命令会保留用于独立手动配对的本地 /extension 中继。它不会唤醒 Browser control。如果已安装原生唤醒支持并启用自动设置，扩展可以在重连时启动该中继，而无需本地 Gateway。否则，中继必须已经运行，例如通过 Browser control 或浏览器节点。

桌面原生辅助工具可以使用 openclaw browser extension pair --local-gateway --json 获取与自动原生引导相同的本地 Gateway 唤醒路由。这需要本地 Gateway 配置，拒绝 --gateway-url，并保持普通手动配对不变。其输出包含中继凭据，不得记录到日志中。

对于装有 Chrome 但未运行 OpenClaw 或浏览器节点的笔记本电脑，请直接配对到远程 Gateway：

openclaw browser extension pair \
  --gateway-url wss://gateway.example.com

将该字符串粘贴到 设置 → 高级手动配对 中。此流程不能使用原生引导：远程 Gateway 拥有不同的中继密钥，而本地原生主机永远不会获取或复制它。非回环远程 URL 要求使用 wss://，并且 Gateway 必须暴露精确的 /browser/extension WebSocket 路径，且不带路径重写代理前缀。

外部 CDP 客户端

中继支持 Browser Relay Authentication v2 客户端，例如 mcporter。OpenClaw 和外部客户端可以保持同时连接。当某个客户端启用 Runtime 时，扩展会在中继向该新订阅者重放现有执行上下文之前检查当前标签页访问权限。这不会重置其他客户端的 Runtime 会话。

Runtime 绑定回调只会发送到成功注册该绑定名称的逻辑会话，独立于 Runtime.enable 和 Runtime.disable。移除绑定或断开客户端连接会保留其他客户端对同一名称的注册。具有相同名称的上下文特定注册仍然共享底层原生 Runtime。当客户端需要独立的上下文选择时，请使用不同的名称。

Fetch 请求拦截在每个原生目标会话中只有一个所有者。另一个客户端可以使用其他 CDP 域，但不能替换该所有者的拦截设置或解决其已暂停的请求。相互竞争的拦截请求会返回错误，而不是静默更改当前所有者的策略。Fetch 响应流也属于获取它们的逻辑会话。

相关目标（例如 frames 和 workers）会为每个感兴趣的父级拥有独立的逻辑会话。每个父级的有序自动附加过滤器都会保留。原生附加使用它们的并集。新增或扩展的兴趣只有在扩展接受命令后，才会接收现有子级。原生附加时暂停设置仍然共享：最新更新生效，包括 DevTools 的暂停/恢复。恢复等待中的目标会影响其所有逻辑会话。

客户端仍然共享底层标签页。导航或页面更改可能会使另一个客户端的快照引用失效。这并非为每个客户端提供隔离的浏览器，也不是对每个 CDP 域和相互竞争的客户端策略进行完全隔离。当原生目标尚无法匹配到 Playwright 页面时，完整的标签页列表请求会返回错误，而不是将部分列表报告为完整。Chrome 永久拒绝调试的页面（例如 Chrome Web Store）会从该列表中排除。Gateway 会记录一条警告，指明被跳过的标签页和 Chrome 的拒绝；普通标签页仍然可用。临时附加失败仍会使完整请求失败。此处理在 Gateway 端进行，不需要发布新的 Chrome 扩展版本。

如果扩展连接断开，其调试器附加会在替换连接重新附加之前被移除。不确定的原生 Fetch 操作也会移除受影响的附加，而不是针对替换对象重试该操作。Fetch 清理是有界的。调试器拆除并不保证待处理的网络请求会被取消。这些路径不会更改访问模式或已暂停的标签页。在目标重新附加后，使用元素引用之前，请获取新的快照。如果客户端不再暴露该目标，请重新连接该客户端。

如果 Chrome 关闭了某个原生目标，但其标签页仍可访问，中继会为仍然订阅该标签页的客户端恢复自动附加。它会重新检查当前访问权限，并为客户端提供新的会话；它永远不会重放失败的命令。显式客户端分离和 Chrome 的调试器 Cancel 操作仍然有效。恢复后继续之前，请获取新的快照。

如果原生分离失败，错误会被报告，清理责任仍保留在该确切附加上。其他标签页仍可使用，但受影响的标签页在清理成功之前无法获取替换对象。恢复 Chrome 访问权限后，重试显式附加或 断开连接。Chrome 的调试器 Cancel 操作也可以结束原生附加。仅移除或替换标签页并不被视为其调试器客户端已关闭的证明。失败的 CDP 操作永远不会针对替换会话重试。

连接生命周期保护需要更新的扩展代码，也需要更新的 OpenClaw 安装。可用时请更新 Store 扩展。对于未打包的开发副本，重新运行 openclaw browser extension install，并从 chrome://extensions 重新加载已安装的副本。

打印非机密端点元数据：

openclaw browser extension cdp
openclaw browser extension cdp --json

输出包括回环端点、协议版本、密钥 ID 和固定的 challenge/complete 资源。它不包括中继密钥或授权头。

cdp --legacy-bearer 是带警告的兼容性逃生通道，面向无法使用 Browser Relay Authentication v2 的客户端。它仅在 browser.extensionRelay.allowLegacyAuth=true 时有效，并在请求时打印旧版凭据。

权限

扩展仅请求：

  • debugger：向允许的标签页发送 CDP 命令。
  • tabs 和 tabGroups：发现标签页并强制访问模式。
  • storage：持久化配对、访问模式、会话暂停和引导退出选择。
  • alarms：唤醒 MV3 工作线程以用于中继/引导重试。
  • nativeMessaging：请求本地引导配对或唤醒其已配置的中继。

它不请求 activeTab、contextMenus、scripting 或 sidePanel。

原生引导安全

原生主机为 ai.openclaw.browser_bootstrap。扩展会为一次请求打开一个 chrome.runtime.connectNative 端口，验证响应，然后断开连接。主机写入一个响应后退出。派生的独立中继会在此短生命周期的原生连接之后继续存在。

请求使用带版本、长度前缀的 JSON 帧，并带有新的 16 字节 nonce。主机将输入限制为 4 KiB，要求 UTF-8 解码失败即致命，并且字段必须精确，根据精确安装的清单验证调用方来源，并且只返回本地生成的配对、中继状态或有界的非机密失败代码。引导请求保持为完全精确的 {v:1, op:"bootstrap", nonce}。中继唤醒使用 {v:1, op:"ensure_relay", nonce, relayPort}，其中必需的整数端口范围为 1 到 65535。缺失、重复、格式错误或多余的字段都会被拒绝。在清单和调用方验证之后，主机会在探测或派生之前，将请求的端口与当前扩展配置进行核对。任何请求都不能向启动器提供主机、可执行文件路径或凭据。响应低于 Chrome 的 1 MiB 原生消息限制。配对密钥绝不会出现在启动器参数、清单、状态 JSON 或诊断信息中。

POSIX 启动器和清单使用 OpenClaw 拥有的 mode-0700 目录下的绝对规范路径。清单的 mode 为 0600。启动器为属主可执行。符号链接、外部所有权、不安全权限、路径遍历、通配符来源以及外部同名注册都会失败关闭。

受管理的清单授权精确的 Foundation Chrome Web Store 来源，以及按规范顺序排列的确定性开发来源。Store 身份是固定的产品信任授权，而不是证明任意路径由 OpenClaw 拥有的证据。

正常使用时请安装官方 Chrome Web Store 版本。只加载你信任的未打包开发副本：Chrome 可能将密钥匹配的未打包构建赋予相同的扩展身份和原生主机访问权限。

未打包开发 ID 的计算与 Chromium 的 crx_file::id_util::GenerateIdForPath 一致：使用 SHA-256 对规范绝对路径的原始字节进行哈希（在 Windows 上为原生 UTF-16LE 路径字节，仅将小写盘符大写），保留前 16 个摘要字节，然后将十六进制数字 0 到 f 映射为字母 a 到 p。未打包扩展清单没有 key。只有这些开发 ID 依赖于已批准的 OpenClaw 拥有的真实路径。

中继本身使用与连接绑定的 HMAC 证明。在 v2 认证期间，持久化的每主机密钥不会通过 URL、请求头、WebSocket 子协议或应用帧发送。在 POSIX 主机上，每次读取密钥都会拒绝外部拥有和非常规文件，并将属主拥有但组/其他可访问的文件收紧为 0600。如果收紧失败，则拒绝该密钥。Windows 使用其现有 ACL 策略。

故障排查

openclaw browser extension status --json
openclaw browser doctor --browser-profile chrome
openclaw doctor
  • 未预注册原生主机： 检查前面按浏览器列出的拒绝诊断信息，并解决报告的路径、所有权或权限问题。此摘要并不意味着 Chrome 的用户数据目录缺失。如果 Chrome 从未启动过，请先启动它，然后在添加扩展之前重新运行 extension install。
  • 未检测到扩展 ID： 保持 Chrome 运行，重新运行 extension install，然后添加官方 Store 扩展。只有在命令提示原生引导已就绪后，才将 Load unpacked 作为开发回退使用。
  • 扩展在原生引导之前已加载： 重启一次 Chrome 以清除其缓存的原生主机未命中，然后重新运行有序安装流程。
  • 扩展版本不匹配： 从 chrome://extensions 重新加载未打包的 OpenClaw 扩展，然后重新运行 browser doctor。如果运行版本和捆绑版本仍然不同，请完全重启 Chrome。
  • 正在等待本地 OpenClaw： 运行 extension status。安装或修复拥有的原生主机。
  • 自动设置已禁用： 在设置中启用它，或点击 Use local OpenClaw。
  • 需要手动设置： 使用设置进入高级配对流程。对于仅使用扩展的直接远程 Gateway 设置，这是预期行为。在 Windows 上，首先检查打包的原生可执行文件和匹配的本地 CLI 已安装，并且其私有 ACL/上下文检查成功。
  • 中继不可用： 对于 /browser/extension 配对，确认目标 Gateway 正在运行。对于直接回环 /extension 配对，检查原生主机注册、扩展构建中的唤醒支持、自动设置，以及配对端口是否仍属于扩展配置。允许一分钟的唤醒节流，然后运行 browser doctor。独立路径不需要本地 Gateway。

有关完整的配置文件模型以及受管理的 openclaw 和 Chrome MCP user 配置文件，请参阅 Browser。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw