Chrome 扩展¶
OpenClaw Chrome 扩展允许浏览器工具自动化您已登录的 Chrome 配置文件中的合格标签页。它使用 chrome.debugger,因此不需要 Chrome 的阻塞性远程调试同意提示。
该扩展是浏览器自动化基础设施。它不包含聊天、页面共享、提示框或标签页 Copilot。其弹窗显示连接状态、当前访问模式、当前合格标签页的暂停/允许操作,以及设置链接。
要求¶
- Google Chrome、Chrome for Testing 或 Chromium
- OpenClaw 与 Chrome 安装在同一台机器上,或该机器上有一个 OpenClaw 浏览器节点
- macOS/Linux,或带有自包含 OpenClaw 原生引导可执行文件的 Windows
- 在 macOS 上使用除 Google Chrome 以外的浏览器时,请至少启动一次浏览器,以使其用户数据目录存在
Windows 使用 OpenClaw.BrowserBootstrap.exe,而不是批处理或 PowerShell 启动器。设置过程会识别打包的辅助程序或 Windows 配套安装。便携式安装可以通过 --native-host-executable 选择其绝对本地路径。共享的 Windows 注册服务负责原生注册和 Store 请求。独立的 Windows CLI 通过可执行文件的受限管理接口进行委托,显式绑定其 Windows Node/CLI、状态目录、配置路径和浏览器配置文件。Companion 使用其独立的受管 WSL 模式和实时 Gateway 权限。当一种模式不可用时,不会回退到另一种模式。经过验证的私有生成物位于当前用户的 Local App Data OpenClawTray 目录之下。在两种适用的用户注册表视图中注册 Chrome/Chromium 之前,该服务会验证二进制帧格式与准入资格。它不会覆盖外部注册、遮蔽计算机级注册,也不会将 WSL/UNC 路径或 SSH 回环 URL 视为本地 Windows 权威。缺失/不兼容的可执行文件或不安全的 ACL 会使设置保持阻塞;没有脚本回退或复制密钥提示。已存在的不同模式/上下文或遗留的无法识别的注册会被保留并报告为冲突,而不会静默替换。管理操作被中断且没有明确回执时,结果是未知的:请在重试之前检查相同的上下文。Windows Store 移除使用 extension uninstall-host --remove-store;该命令先移除自身的 Store 请求,然后移除自身的原生注册。macOS 的 uninstall-store 命令继续保留原生注册不变。
安装¶
在承载 Chrome 的机器上运行此命令。macOS 上的 Google Chrome 可以在首次启动前准备;其他受支持的浏览器需要先启动一次。有关完整的 browser extension 子命令参考,请参阅 openclaw browser:
在完成 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 仍然控制其安装和权限批准。
You can also use the Store link if Chrome does not offer the requested install. If you previously removed the extension, Chrome remembers that choice. Explicitly add it again from the Store. OpenClaw does not clear Chrome's removal decision.
On macOS and Linux, the origin-locked native host permits the exact official
Store identity and OpenClaw's deterministic development IDs. Once enabled, the
extension pairs on its first native call. The installer inspects the profile's
Preferences and Secure Preferences
backing files and verifies the exact Store ID independently from any extension
path. Chromium selects the backing file by settings-enforcement policy. Linux
normally uses Preferences. Both files receive the same ownership, path, file
type, permission, and size checks.
For extension development, skip creating a Store installation request:
This still copies the bundled extension to a stable OpenClaw-owned directory and registers the native host. It leaves any existing Store request unchanged. Use the unpacked copy as a development fallback:
- Open
chrome://extensions. - Enable Developer mode.
- Click Load unpacked.
- Select the path printed by the command.
Leave the install command running while completing either Store or development setup. For unpacked development, the installer verifies that Chrome loaded the approved realpath under its predicted deterministic ID.
The installer recognizes the official Store installation only by the exact Foundation Store ID. That identity never makes a recorded path OpenClaw-owned. For unpacked development, it accepts an ID only when all of these are true:
- the ID matches Chrome's 32-character extension ID format.
- Chrome records the install location as unpacked.
- the recorded extension path resolves exactly to the installed or bundled OpenClaw extension directory.
- the recorded ID equals Chromium's deterministic path ID for that exact canonical realpath.
The extension name is not trusted. Existing native-host files with the same host name are not overwritten unless they are verifiably OpenClaw-owned.
Use a different bounded wait when needed:
For automation, use --json. The result reports Store installation requests,
Store discovery and approval, approved unpacked IDs and paths, and native-host
registration health separately. These local observations do not prove a live
connection. Verify the extension's connected state and run
openclaw browser --browser-profile chrome tabs against the intended Gateway
or browser node. JSON output never includes a relay key or pairing string.
Shared setup controller¶
CLI, native desktop adapters, and the terminal setup flow use the same Browser-owned controller on the machine that hosts Chrome.
Setup's installation status describes Google Chrome. The
openclaw browser extension install and openclaw browser extension status
commands also support Chromium and 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 reads installation state without installing or connecting. install
prepares automatic local bootstrap; Chrome still owns extension installation and
permission approval. There is no pairing code to copy for supported local native
bootstrap. Existing pairings and an explicit automatic-setup opt-out remain intact.
verify authenticates the exact local profile relay with the existing per-host
key. It does not create a key, start another relay, or fetch a remote Gateway key.
On macOS and Linux, a supported bundle-path migration retains the saved profile
from the validated private manifest and launcher. The existing one-slot origin
migration rule is unchanged: until repair, the registration is owned but not
ready for the new bundle. Older launchers without a saved selector retain their
original selection: the first configured extension profile, independently of
browser.defaultProfile. Selector-free setup refuses an unverified or foreign
registration. Explicit inspect and verify requests must match the registered
profile; use setup --action install --browser-profile <name> to change it.
An explicit selection cannot bypass ownership or origin checks. Setup does not
rotate the existing relay key or rewrite Chrome pairing preferences.
Setup also preserves the registered state and configuration selection. If the
current process uses a different configuration, it stops before installation or
relay access. Rerun with the matching OPENCLAW_STATE_DIR and
OPENCLAW_CONFIG_PATH; choosing another browser profile does not authorize
changing the configuration file. An implicit default config and its explicit
path count as the same selection. Setup rechecks the saved selection before
publishing a replacement native-host manifest.
On Windows, omitted profile selection uses bounded, serial read-only inspection of
already-configured extension profiles. Only a current matching C# registration
descriptor, independently validated against its binding and requested context,
can select a saved profile. Setup confirms that observation before proceeding;
the C# owner revalidates the single installation operation. Unknown, conflicting,
changed, or unavailable evidence never silently selects chrome. A genuinely
missing registration can use the existing fresh-install default.
If the saved profile is no longer configured, or the Node/CLI paths or approved
extension origins have changed, the Windows contract may return no matching
descriptor. Automatic selection then stops without an installation attempt.
Review the intended existing profile and repair explicitly, for example
openclaw browser extension setup --action install --browser-profile work. This
is not automatic runtime-upgrade recovery: a different state, configuration,
profile, or Companion mode remains a context conflict rather than a takeover.
JSON 结果包含 action、target(其 kind: "local-host")、平台、主机名、配置文件和中继端口,以及 phase、reason、installation、connection 和 nextAction。安装报告将已安装的配置文件与已启用的配置文件分开计数,因此禁用的扩展不会被显示为缺失。有效的 pending 或 blocked 结果会成功退出;命令或执行失败会以非零状态退出。结果从不包含配对字符串或中继密钥。现有的 install 和 status 命令保留其文档中说明的输出格式。
安装、Chrome 批准和已认证连接是相互独立的事实。ready 表示所选中继具有已认证的扩展;它并不意味着存在符合条件的标签页。空的标签页列表不代表扩展已断开连接。在使用自动化之前,请通过预期的 Gateway 或浏览器节点检查标签页。
目标是进程主机,而不是显示远程仪表板的计算机。通过 SSH 访问的 TUI 会在该 SSH 主机上运行设置。回环 URL 可能是 SSH 隧道,并不能证明 Gateway 和 Chrome 位于同一台机器上。原生设置不会静默重新指向当前显示的 Gateway。仅 Web 的仪表板提供商店和设置指南链接,而不是在查看者设备上安装。
使用它¶
选择内置的 chrome 配置文件,或将其设为默认:
新的自动配对使用 所有标签页。现有有效配对永远不会被覆盖,旧配对会保留其存储的访问模式。
对于新的本地设置,原生引导会通过本地 Gateway 的精确 /browser/extension 路由连接扩展。第一次已认证连接会唤醒惰性浏览器控制服务,并启动该配置文件的回环中继。OpenClaw 和 mcporter 等本地客户端随后使用该配置文件的中继端口。请保持 openclaw gateway run 或受管理的 Gateway 服务处于运行状态。无需单独的浏览器请求或预热步骤。
浏览器节点设置仍然不同:扩展连接到浏览器节点主机上的中继,而节点使用其配置的远程 Gateway。显式的 --gateway-url 配对会直接连接到该远程 Gateway,并且仍然是仅限手动操作的流程。
独立直接回环中继¶
位于 ws://127.0.0.1:<port>/extension 的配对可以在没有本地 Gateway 或浏览器节点的情况下运行。在 macOS 和 Linux 上,捆绑的扩展可以在重新连接到该端点时请求已安装的原生主机启动独立中继。必须启用自动设置。请求限制为每分钟一次。扩展仍会使用与连接绑定的 v2 证明来认证中继。这需要更新后的原生主机以及包含中继唤醒支持的扩展构建。商店发布可能滞后于捆绑扩展。捆绑的未打包开发副本是源码构建验证路径。
自动唤醒要求使用守护进程提供服务的精确 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 的默认值兼容。
选择标签页访问权限¶
- 所有标签页 会提供该 Chrome 配置文件中所有符合条件的普通标签页的访问,除了为当前浏览器会话暂停的标签页。在弹出窗口中使用 暂停此标签页 和 允许此标签页。
- 选定标签页 使用 OpenClaw 标签页组作为访问控制边界。将标签页移入该组会授予访问权限。将其移出会撤销访问权限。
打开扩展的设置页面以更改访问模式。切换到选定标签页会立即分离未分组的标签页,包括已在进行中的附加连接。代理创建的标签页在任一模式下都会保留在 OpenClaw 组中。
The extension excludes incognito tabs, internal pages such as chrome:// and
chrome-extension://, and tabs without a usable current URL. file:// access
also requires Chrome's 允许访问文件 URL 设置。
代理创建的标签页可能从 about:blank 开始,而 CDP 客户端会在导航前对其进行初始化。扩展会允许该特定初始标签页,将其保留在 OpenClaw 组中,并应用相同的暂停和访问模式控制。正常导航会在任一访问模式下保持该标签页可用。现有空白标签页、手动分组的空白标签页以及其他 about: 页面仍不可用。导航离开、替换标签页,或重启或重新连接扩展,都会结束初始空白准入。返回 about:blank 不会恢复它。
如果在扩展返回目标之前创建失败,它只会在仍拥有该标签页时尝试关闭它。在创建期间你暂停、移动或导航过的标签页将保持原样。重定向、连接丢失或 worker 关闭可能会遗留一个标签页。如有需要,请手动关闭它。
对已授权标签页的显式命令主框架导航也可以使用精确的 about:blank,例如在性能跟踪重置期间。Chrome 必须在同一附加上确认根框架和加载器。仅 iframe 导航或空白 URL 本身不会授予访问权限。
该临时准入会在下一个非空白文档、调试器分离、访问模式更改、暂停、组或窗口更改、标签页关闭或替换、重新连接或扩展重启时结束。导航失败绝不会关闭现有标签页,或覆盖你的导航来恢复 URL。
自动设置控制¶
设置页面显示已脱敏的中继/本地引导状态以及 使用自动本地设置 开关。
- 关闭自动设置会保留有效的现有配对,但会阻止新的本地引导和独立中继唤醒尝试。
- 断开连接并禁用自动设置 会立即撤销配对,分离调试器会话,并持久化选择退出。
- 使用本地 OpenClaw 会清除选择退出并重试本地主机。
- 保存显式手动配对也会清除选择退出。
在本地 Gateway 唤醒路由之前完成配对的预发布开发安装会保持现有配对不变。在设置中,使用 断开连接并禁用自动设置,然后使用 使用本地 OpenClaw 创建新的本地配对。正式发布版本不需要此恢复步骤。
从已退役的标签页副驾驶升级¶
如果设置显示自动化已暂停以保护升级前的副驾驶会话,请确认旧运行已完成。然后单击 断开连接并禁用自动设置 以丢弃已退役恢复状态,接着使用 使用本地 OpenClaw 重新连接。在该显式断开连接成功之前,扩展会保留已退役状态,并阻止中继连接、本地设置、手动配对、标签页访问更改和调试器附加。
Chromium 会为正在运行的浏览器进程缓存首次缺失本地主机的结果。如果现有扩展在本地主机安装之前已尝试自动设置,请重启一次 Chrome(完整的浏览器进程重载)。从弹出窗口或设置中重试无法清除该进程级缺失。正常设置通过在添加或重新打开商店扩展之前预注册主机来避免此问题。对于开发,请在 加载已解压的扩展程序 之前预注册。
状态与移除¶
在不打印凭据的情况下检查安装:
JSON storeInstallRequests 条目会为已验证的 OpenClaw 拥有的请求报告 requested,在没有请求时报告 missing,对于无法识别的注册报告 foreign,或者在文件无法安全读取或验证时报告 invalid。storeDiscovered 会分别报告 enabled 和 awaitingApproval。已请求的安装、已发现的扩展或已启用的扩展并不能证明存在经过身份验证的中继连接。
owned 本地主机注册不一定可启动。状态会报告其已注册运行时和本地入口的文件系统就绪快照。它不会执行任一目标,也不会验证其代码能否成功运行。如果升级移除了任一目标,请重新运行 openclaw browser extension install 以修复拥有的注册。所有权检查仍会拒绝外部或格式错误的清单和启动器。
托管部署所有者可以在不读取 Chrome 配置文件或商店请求的情况下检查已注册的入口点:
报告包括 retainedNativeHostPaths 和 retentionSafe。在相关注册迁移之前,请保留所引用的软件包版本。如果检查不完整(retentionSafe: false),请保留版本并报告警告;这不得将浏览器修复失败变成 Gateway 更新失败。
若要仅刷新属于某个已退役软件包的注册,请从其替换安装中运行该命令,并使用确切的旧入口点:
openclaw browser extension repair --from /path/to/old/package/dist/extensions/browser/native-host-entry.js --json
修复会保持无关安装、缺失注册、稳定的扩展副本、浏览器配置文件、商店请求和配对凭据不变。即使修复命令在不同的环境设置下运行,它也会保留启动器的已保存状态和配置选择。它使用与显式安装相同的所有权和来源检查。它不会重启 Chrome,也不会证明中继连接。替换启动器是不可变的;本地清单仅在其启动器完成后才会切换,因此清单写入失败会保留先前注册以供重试。通用 Doctor 仍会跳过个人浏览器配置文件发现;首次设置请使用 extension install。
仅移除 OpenClaw 的 macOS Chrome 商店安装请求:
Chrome 可能在请求被移除后的下一次启动时移除外部安装的扩展。此命令会保留 native-host 注册和开发副本,并拒绝外部或格式错误的请求文件。
仅移除 OpenClaw 拥有的 native-host 清单和启动器:
此操作不会从 Chrome 中移除商店扩展或未打包扩展。请使用 chrome://extensions 执行该操作。它也不会删除稳定的开发副本或现有的中继密钥。
openclaw browser extension path 是只读的。如果存在稳定安装副本,它会打印该副本;否则打印捆绑的源目录。
高级手动配对¶
设置页面负责手动配对。生成主机本地配对字符串:
手动配对对于不支持的拓扑和恢复仍然有用。请将完整的配对字符串视为密码。
如果没有 --gateway-url 或 --local-gateway,此命令会保留用于独立手动配对的主机本地 /extension 中继。它不会唤醒 Browser control。如果已安装原生唤醒支持并启用自动设置,扩展可以在重连时启动该中继,而无需本地 Gateway。否则,中继必须已经在运行,例如通过 Browser control 或浏览器节点。
桌面原生辅助工具可以使用 openclaw browser extension pair --local-gateway --json 获取与自动原生引导相同的本地 Gateway 唤醒路由。这需要本地 Gateway 配置,拒绝 --gateway-url,并保持普通手动配对不变。其输出包含中继凭据,不得记录日志。
对于装有 Chrome 但未运行 OpenClaw 或浏览器节点的笔记本电脑,请直接向远程 Gateway 配对:
将该字符串粘贴到 设置 → 高级手动配对 中。此流程不能使用原生引导:远程 Gateway 拥有不同的中继密钥,且本地 native host 永远不会获取或复制它。非回环远程 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 安装。可用时请更新商店扩展。
对于未打包的开发副本,重新运行 openclaw browser extension install,
并从 chrome://extensions 重新加载已安装的副本。
打印非机密端点元数据:
输出包括回环端点、协议版本、密钥 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 拥有的权限为 0700 的目录下的绝对规范路径。清单的权限为 0600。启动器仅所有者可执行。符号链接、外部所有权、不安全权限、路径遍历、通配符来源以及外部同名注册都会失败关闭。
受管清单授权精确的 Foundation Chrome Web 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,然后添加官方商店扩展。仅在命令提示原生引导已就绪后,才将 加载未打包 作为开发回退方案使用。 - 扩展在原生引导之前已加载: 重启一次 Chrome 以清除其缓存的原生主机未命中,然后重新运行有序安装流程。
- 扩展版本不匹配: 从
chrome://extensions重新加载未打包的 OpenClaw 扩展,然后重新运行 browser doctor。如果运行版本和捆绑版本仍然不同,请完全重启 Chrome。 - 正在等待本地 OpenClaw: 运行
extension status。安装或修复拥有的原生主机。 - 自动设置已禁用: 在设置中启用它,或点击 使用本地 OpenClaw。
- 需要手动设置: 使用设置进行高级配对流程。对于仅扩展的直接远程 Gateway 设置,这是预期行为。在 Windows 上,首先检查已打包的原生可执行文件和匹配的本地 CLI 是否已安装,并且它们的私有 ACL/上下文检查是否成功。
- 中继不可用: 对于
/browser/extension配对,请确认目标 Gateway 正在运行。对于直接回环/extension配对,请检查原生主机注册、扩展构建中的唤醒支持、自动设置,以及配对端口是否仍属于扩展配置文件。请考虑一分钟的唤醒节流,然后运行 browser doctor。独立路径不需要本地 Gateway。
有关完整的配置文件模型以及受管理的 openclaw 和 Chrome MCP user 配置文件,请参阅 浏览器。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw