browser-use

浏览器使用

控制用户现有的真实 Chrome 配置文件，尤其适用于需要登录的工作和实时 UI 验证。

路径

1. 如果当前会话中可调用，请使用 Codex Chrome 或 Chrome [Internal] 插件。仅在磁盘上安装并不够。
2. 否则，优先使用由 OpenClaw 扩展支持的 mcporter 路径。
3. 仅将旧版直接 DevTools 连接作为明确的最后回退方案。

使用 mcporter 时，MCP 调用仍是面向 Agent 的控制接口。OpenClaw 扩展是底层传输方式，不是独立工具。在规范的全局 Chrome 服务定义中设置 chromeDevtoolsRelay: "require"，以强制仅通过 relay 路由。调用方策略也应明确设置：

MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.<tool>

因此，看到 Agent 请求 chrome-devtools MCP 工具是正常的。出现 Chrome Allow remote debugging? 提示或 relay 策略错误，表示未使用扩展传输。共享守护进程保留规范策略；仅在 shell 环境前缀中设置配置无法更改该策略。

除非用户明确要求使用隔离浏览器或新浏览器，否则绝不要使用隔离的 Chrome、Codex 应用内浏览器、Playwright、Puppeteer、AppleScript、osascript、通用 GUI 脚本，或 macOS open 来替代浏览器控制。Peekaboo 仅允许用于 Chrome 或扩展设置及可见提示。需要频繁登录的网站通常依赖真实配置文件中的 Cookie、SSO、设备信任和扩展。

对于渲染浏览器的 Bug，必须通过此真实配置文件验证行为。将 curl、源代码检查、API 检查和隔离测试浏览器视为辅助证据，而非实时 UI 验证的替代方案。

扩展 Relay 模型

OpenClaw 会在其权限模式为 0600 的凭据目录中创建每台主机随机的 relay 密钥。扩展和同一主机上的客户端会使用绑定 nonce 的双向 HMAC 证明。可重复使用的密钥绝不会发送给未经验证的 loopback 监听器、置于 URL 中，或传递给子 MCP 进程。请勿将凭据放入配置、命令输出、聊天、日志或屏幕截图中。

在同一主机的 relay 上，mcporter 会对 /json/version 进行身份验证，并将同一保留的 socket 升级到 /cdp，然后向 chrome-devtools-mcp 提供受保护的一次性本地交接。Agent 仍会调用标准 MCP 工具；成功通过 relay 路由，才能免去直接 DevTools 连接和 Chrome 的批准提示。

新的配对默认采用 All tabs：除在弹出窗口中明确暂停的标签页外，所有符合条件的普通标签页都会公开。现有配对会保留已存储的模式。在 Selected tabs 模式下，归属 Chrome 中标题为 OpenClaw 的标签页组即为共享边界。在两种模式下，受限／内部页面、无痕模式、其他配置文件，以及不含合格 URL 的标签页仍会被排除。

拓扑边界

通过 wss:// 直接与远程 Gateway 配对，可让 OpenClaw 的 Gateway 端浏览器工具控制本地 Chrome，但不会为本地 mcporter 进程创建本地 relay。不要常规地复制远程密钥，也不要围绕此边界搭建临时 SSH 隧道。

如果本地 mcporter 无法通过身份验证连接本地 relay，则扩展支持的 mcporter 路径不可用。请明确说明这一点，或使用注明标签的旧版回退方案；绝不要将远程 Gateway 控制或直接连接说成本地 relay 成功。

设置和修复

• 在 Load unpacked 之前运行 openclaw browser extension install。它会将扩展复制到由 OpenClaw 管理的稳定路径，预先注册该路径对应的确定性 Chrome ID，并打印要加载的路径。首次调用原生功能时，会自动完成配对，适用于本地或浏览器节点拓扑。
• 使用 openclaw browser extension status --json 验证已安装的副本、确切的来源和原生主机注册信息。状态不得报告任何问题，且 manualSetupRequired: false。
• 确认 Settings 显示自动设置已就绪，弹出窗口显示 Connected。新安装应显示 All tabs，除非用户更改访问模式；正常的本地流程不需要复制配对字符串，也不需要进行弹出窗口设置。
• Chrome 进程会缓存之前的原生主机连接失败。如果扩展在安装前尝试过原生消息传递，请在安装后重启一次 Chrome；在同一进程中反复重试无法修复该缓存。
• 配对或更改中继路由后，在重新运行仅中继验证之前，请停止 mcporter 守护进程。重启 Gateway 后，Chrome DevTools 子进程可能仍在运行，但上游套接字已经失效；mcporter daemon stop 会在下次调用建立新连接之前将其终止。
• 直接与远程 Gateway 配对仍属于高级手动流程。它用于 Gateway 浏览器路径，不会为本地 mcporter 创建本地中继。

发现超时和守护进程配置

MCPorter 通过 openclaw browser extension cdp --json 发现实际中继。即使是打包版 OpenClaw，冷启动也可能超过 5 秒。在 mcporter 0.13.10 中，发现失败时会回退到端口 18799；因此，超时可能会在错误的端点上显示为 network-error，或者在后续发现返回实际端点时显示为 browser_owner_conflict。不要将这一系列情况解读为其他 Chrome 所有者或凭据轮换导致故障的证据。

对于共享的 Chrome 所有者，请使用 OS 帐户的规范文件 ~/.mcporter/mcporter.json（仅当 JSON 文件不存在时，才使用 mcporter.jsonc）。 将以下字段合并到现有的 Chrome 定义中，并保留其命令、 参数和其他设置：

{
  "chromeDevtoolsRelay": "require",
  "env": {
    "MCPORTER_CHROME_DEVTOOLS_RELAY_TIMEOUT_MS": "20000"
  }
}

中继超时限制每个发现或身份验证步骤；它不会延长客户端的总操作期限。初次启动 Chrome 时，在 MCP 初始化和调用所请求的工具之前，可能会进行多次发现检查。对于较旧的已安装客户端，请将规范设置 20000（每步超时）与初始调用或架构列表中的显式 --timeout 300000 配合使用。例如：

MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.list_pages --timeout 300000 --output text

较新的 Chrome 专用外层默认超时需要升级发起调用的客户端。显式的 --timeout、MCPORTER_CALL_TIMEOUT 和 MCPORTER_LIST_TIMEOUT 仍会覆盖这些默认值；较小的覆盖值可能会导致启动提前结束。

守护进程会有意从规范 Chrome 环境中移除继承的 MCPORTER_CHROME_DEVTOOLS_RELAY_* 和 OPENCLAW_* 控制项。Shell 导出不会更新现有所有者，也不是在守护进程重新生成后仍然有效的修复方法。请在规范定义的 env 中填写字面值；不要使用依赖这些已移除变量的占位符。如果必须指定端点，请在该处将 MCPORTER_CHROME_DEVTOOLS_RELAY_URL 设为已验证、不含凭据的 HTTP 环回基址，例如在确认端口后使用 http://127.0.0.1:28799。此覆盖项不接受 WebSocket CDP URL，例如 ws://127.0.0.1:28799/cdp。请优先使用足够长的超时进行发现，而不是猜测或硬编码端口，尤其是在多个 OpenClaw 安装共存时。

更改规范设置后，请等待正在进行的调用结束，然后运行 mcporter daemon stop。如果仍有调用处于活动状态，导致停止操作被拒绝，请等待这些调用结束后重试；只有停止成功后才能继续。下一次调用会使用已保存的设置启动守护进程，之后重新生成的守护进程也会使用相同配置。使用 mcporter daemon status --json 验证中继决策，并重复执行下方的就绪状态验证。依赖较新的超时默认值或显式的发现失败诊断信息之前，请先检查已安装的 mcporter 版本；源码修复不会更新已安装的二进制文件或正在运行的守护进程。

当前版本的 openclaw browser extension cdp --json 默认会输出非敏感元数据，但旧版本和旧式 bearer 选项可能会暴露凭据。日常诊断请优先使用 mcporter 已脱敏的状态信息，切勿请求旧式凭据，也不要转储进程参数。如果怀疑凭据已暴露，请轮换每台主机的密钥并重新配对。

失败即关闭的就绪证明

只有满足以下所有条件，才能将扩展路由判定为就绪：

1. 扩展状态显示稳定副本和准确的原生注册信息，且没有问题；设置页面显示自动设置已就绪。
2. 弹出窗口显示 Connected，且目标普通标签页未暂停。在 Selected tabs 模式下，该标签页还必须属于 OpenClaw 组。
3. 配对、relay 路由或规范配置发生变更后，mcporter 已停止，并且下一次调用已启动新的守护进程。
4. 规范 Chrome 定义使用 chromeDevtoolsRelay: "require"，且使用 MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require 的调用成功。规范策略禁止回退到直接 DevTools，因此成功即可证明 relay 可用。
5. 在已知符合条件的临时标签页中，选择和评估均成功。

MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.list_pages --args '{}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.select_page --args '{"pageId":9}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.evaluate_script --args '{"function":"() => ({title: document.title, href: location.href})"}' --output json

relay 策略错误意味着扩展传输不可用；应报告或修复问题，而不是在不使用 require 的情况下重试。出现阻止操作的 Allow remote debugging? 提示，证明曾尝试进行旧式连接。

典型流程

列出页面，仅选择一个共享目标，操作前先创建快照，并使用最新的快照 UID。除非布局很重要，否则优先使用 DOM 快照，而不是截图。

MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.list_pages --args '{}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.select_page --args '{"pageId":9}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.take_snapshot --args '{}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.click --args '{"uid":"1_38","includeSnapshot":true}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.fill --args '{"uid":"1_13","value":"text","includeSnapshot":true}' --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.evaluate_script --args '{"function":"() => document.title"}' --output json

如需证明界面当前状态，先捕获当前页面状态，再执行所需交互，然后对渲染结果进行快照或评估。不要让机密出现在 DOM、输入、网络、控制台或截图输出中。检查凭据时，只返回安全的概要信息，例如是否存在、长度、状态码或账户／组织标签。

如果自动化不可用，应报告验证缺口，而不是悄悄改用被禁止或隔离的工具。

参数与输出机制

--args 仅接受内联 JSON，不会读取 @file。采用标志形式的命名参数可以读取：

MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.navigate_page url=@/tmp/target-url.txt --output text
MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.evaluate_script function=@/tmp/probe.js --output json

应将此视为安全基元，而不只是便捷功能。登录 URL、魔法链接或回调 URL 等同于凭据：将其写入权限为 0600 的文件，并通过文件引用传递，以免其出现在 shell 历史记录、进程参数或捕获的工具输出中。同样的形式也可以传递多行 JavaScript 函数，避免引号或控制字符错误。

登录流程前，还需了解其他调用机制：

• 通用客户端的默认调用超时为 60 秒，列表操作超时为 30 秒；这与 relay 的逐步发现／身份验证超时相互独立。较旧客户端首次启动 Chrome 较慢时，需要按照上文说明使用 --timeout 300000。后续交互操作如有需要，请明确设置超时时间。
• 带有 filePath 的 take_screenshot 只能在服务配置的工作区根目录内操作，并会拒绝任意路径。省略 filePath，从 --output json 读取 base64 图像，并在本地解码。
• 目标未共享时，new_page 可能因标签页受限／不可用而失败。请导航到已有的共享标签页，而不是新建标签页。
• mcporter list <server> --schema 会打印真实的函数签名。请使用它，而不要猜测参数名称。

点击无效

按 uid 执行 click 可能会返回成功，但实际上什么也没做：有些页面绑定处理程序的方式会忽略合成点击。没有报错不代表操作成功，因此每次触发操作后都要确认状态，而不要想当然地认为它已生效。

点击无效时，使用键盘按 press_key（Tab、Shift+Tab、Enter）操作控件，并在确认焦点后截图，再执行操作。焦点环是判断哪个控件即将接收 Enter 的唯一可靠依据。确认页面通常会把看起来安全且醒目的按钮放在一个弱化显示的链接旁边，而实际需要选择的却是后者。在这类页面上盲目按 Enter 会选错控件。

任何导航或重新渲染都会使快照中的 uid 失效。每一步之后都要重新运行 take_snapshot 并重新解析 uid；过期的 uid 会报告元素已不存在，这提示你应重新获取快照，而不是重试同一个调用。

任务进行中继接入变为空

由于符合条件的标签页被关闭、当前标签页受到限制或暂停、“所选标签页”模式丢失了组成员，或扩展断开连接，中继可能在任务进行到一半时停止显示标签页。故障可能悄无声息：list_pages 可能返回空结果，后续调用也可能超时。

将空页面列表视为“中继没有符合条件的标签页”，而不是“浏览器已关闭”。确认 Chrome 正在运行，检查弹出窗口中的连接状态和当前标签页的“暂停／允许”状态，然后检查访问模式。只有“所选标签页”模式需要恢复 OpenClaw 组。重启 mcporter 无法修复扩展断开、标签页资格或访问策略问题。

不要升级到完整配置文件附加或独立浏览器来绕过问题。如果任务需要用户在场完成登录，更快且更坦诚的做法是将 URL 交给用户当前正在使用的浏览器；如果流程的回调监听在另一台主机上，则先将该端口转发到用户的计算机。否则，请说明访问受限。

旧版备用方案：完整配置文件直接附加

仅当可调用插件和已通过身份验证的本地扩展中继均不可用时，才使用此方案。它会公开完整的真实配置文件标签页集合，并可能显示 Chrome 的阻止提示 允许远程调试？。

当 Chrome 显示明确无误的提示，询问是否允许附加时，批准一次，然后重新运行 list_pages。如果提示缺失、含糊不清，或重试失败，请停止并询问用户，或报告 Chrome DevTools MCP 不可用。不要反复批准、重复重启 Chrome 或 mcporter，也不要终止浏览器进程。

操作前，请确认 list_pages 显示的是预期的真实配置文件标签页。始终将此路径标记为“完整配置文件直接附加”，切勿称其为 OpenClaw 扩展中继成功。