跳转至

多配置文件和现有会话连接

配置文件(多浏览器)

OpenClaw 支持多个命名配置文件(路由配置)。配置文件可以是:

  • openclaw-managed:一个专用的基于 Chromium 的浏览器实例,拥有自己的用户数据目录和 CDP 端口
  • remote:一个显式的 CDP URL(在其他地方运行的基于 Chromium 的浏览器)
  • existing session:通过 Chrome DevTools MCP 自动连接使用您现有的 Chrome 配置文件

默认设置:

  • 如果缺少 openclaw 配置文件,则会自动创建。
  • user 配置文件是内建的,用于 Chrome MCP 现有会话附加。
  • 除 user 之外,现有会话配置文件是可选加入的;使用 --driver existing-session 创建它们。
  • 本地 CDP 端口默认从 18800-18899 分配。
  • 删除配置文件会将其本地数据目录移至废纸篓。

所有控制端点都接受 ?profile=<name>;CLI 使用 --browser-profile。

通过 Chrome DevTools MCP 使用现有会话

OpenClaw 还可以通过官方的 Chrome DevTools MCP 服务器附加到正在运行的基于 Chromium 的浏览器配置文件。这会复用该浏览器配置文件中已打开的标签页和登录状态。

官方背景和设置参考资料:

内建配置文件:user。如果您想要不同的名称或浏览器数据目录,可以创建自己的自定义现有会话配置文件。

默认情况下,内建的 user 配置文件使用 Chrome MCP 自动连接,目标是默认的本地 Google Chrome 配置文件。对于 Brave、Edge、Chromium 或非默认的 Chrome 配置文件,请使用 userDataDir。~ 会展开为您的操作系统主目录:

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
      },
    },
  },
}

然后在匹配的浏览器中:

  1. 打开该浏览器的检查页面以进行远程调试。
  2. 启用远程调试。
  3. 保持浏览器运行,并在 OpenClaw 附加时批准连接提示。

常见的检查页面:

  • Chrome: chrome://inspect/#remote-debugging
  • Brave: brave://inspect/#remote-debugging
  • Edge: edge://inspect/#remote-debugging

实时附加冒烟测试:

openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai

成功时的表现:

  • status 显示 driver: existing-session
  • status 显示 transport: chrome-mcp
  • status 显示 running: true
  • tabs 列出您已打开的浏览器标签页
  • snapshot 返回所选实时标签页中的引用

如果附加不起作用,请检查以下内容:

  • 目标基于 Chromium 的浏览器版本为 144+
  • 该浏览器的检查页面中已启用远程调试
  • 浏览器已显示,并且您已接受附加同意提示
  • 如果 Chrome 是以显式的 --remote-debugging-port 启动的,请将 browser.profiles.<name>.cdpUrl 设置为该 DevTools 端点,而不是依赖 Chrome MCP 自动连接
  • openclaw doctor 会迁移旧的基于扩展的浏览器配置,并检查默认自动连接配置文件的 Chrome 是否已在本地安装,但它无法为您启用浏览器端的远程调试

对于启动失败,请检查 browser/chrome-mcp 日志,以获取子进程 stderr 的有限、经过编辑的尾部(如有可用)。

代理使用:

  • 当您需要用户已登录的浏览器状态时,请使用 profile="user"。
  • 如果您使用自定义的现有会话配置文件,请传递该显式配置文件名称。
  • 仅在用户位于计算机旁并可以批准附加提示时才选择此模式。
  • Gateway 或节点主机会在自身的运行时(Node 或 Bun)上启动打包的 Chrome DevTools MCP 服务器。

备注:

  • 此路径比隔离的 openclaw 配置文件风险更高,因为它可以在您已登录的浏览器会话中操作。
  • OpenClaw 不会为此驱动程序启动浏览器;它只会附加。
  • 停止或附加失败会关闭所拥有的 MCP 子进程及其已验证的子进程,而不是已经运行的浏览器。替换附加会等待清理;如果无法验证清理,OpenClaw 会报告错误,而不是将会话视为已关闭。
  • OpenClaw 在此使用官方的 Chrome DevTools MCP --autoConnect 流程。如果设置了 userDataDir,则会将其传递给目标用户数据目录。
  • 现有会话可以在所选主机上附加,或通过已连接的浏览器节点附加。如果 Chrome 在其他地方且没有连接浏览器节点,请改用远程 CDP 或节点主机。
  • Chrome MCP 目标和快照引用限定在一个 MCP 子进程内。该进程重启后,请再次运行 browser tabs,在特定目标工作之前显式选择新目标,并在使用引用之前拍摄新快照。每个引用仅对其目标和最新快照有效。旧别名不会转移到替换标签页,即使其 URL 匹配也不行。
  • 启动快照刷新会使该标签页之前的引用失效,即使刷新失败也是如此。条件等待会重用当前文档快照并保留其引用。过期文档错误只会使该标签页的快照失效;后续轮询会捕获替换文档。导航后请拍摄新快照,然后再执行另一个基于引用的操作。
  • 带标签的截图可以包含多个框架中的控件。成功的捕获会在返回前从每个框架中移除其临时标签。
  • Chrome DevTools MCP 目前通过进程本地的数字页面 ID 来路由页面工具。进程范围的句柄可防止在子进程替换时重用,但相邻工具调用之间的进程内浏览器上下文替换仍可能重新定向操作。完全原子的路由需要上游页面工具支持稳定的目标 ID。

自定义 Chrome MCP 启动

OpenClaw 包含一个精确固定的 Chrome DevTools MCP 1.10.1 依赖,并带有一个临时性文档身份补丁;它直接在运行 OpenClaw、Node 或 Bun 的运行时中启动其 CLI。 npm 包携带了修补后的依赖;源码检出可通过 pnpm install 获取它。这使运行时使用的服务器与 OpenClaw 的浏览器契约测试保持一致。 该补丁在上游修复中被跟踪。

可按配置文件(profile)覆盖服务器,以使用自定义可执行文件或版本。自定义服务器由运维方管理,且必须保留 Chrome MCP 的连接参数和文档绑定的元素身份。

字段 作用
mcpCommand 自定义服务器可执行文件。绝对路径会被采用;省略或显式使用 npx 将选择 OpenClaw 打包的服务器。
mcpArgs 传递给 mcpCommand 的额外参数,原样透传。连接选项会覆盖生成的端点或自动连接参数。

mcpArgs 扩展所选服务器的参数。现有设置为 mcpCommand: "npx" 的配置仍会选择内置的固定版本服务器。 默认启动器启用 --experimentalVision 以支持原生坐标点击。 自定义 mcpCommand 必须暴露 click_at 工具以支持 click-coords;需要时,在 mcpArgs 中传入服务器对应的功能开关。

当 mcpArgs 未设置连接选项时,OpenClaw 会将配置的 cdpUrl 转发给 Chrome MCP,而不是生成 --autoConnect:

  • http(s)://... → --browserUrl <url>(DevTools HTTP 发现端点)。
  • ws(s)://... → --wsEndpoint <url>(直接 CDP WebSocket)。

mcpArgs 中的显式端点参数会覆盖 cdpUrl;在端点旁边添加 --autoConnect 不会隐藏该端点。OpenClaw 使用所选端点进行 CDP 控制,并在启动 Chrome MCP 之前检查浏览器 CDP 策略。即使私有网络访问被信任,匹配的 blockedHostnames 条目也会拒绝连接(attachment)。无关的阻止列表条目不会阻止连接,且默认的严格策略限制仍然适用。

无效、为空、重复或冲突的端点参数会在启动前报错并失败。提供一个有效端点,或省略 cdpUrl 和端点参数,以使用主机本地(host-local)连接。

当选择了端点时,userDataDir 会被忽略:Chrome MCP 会连接到该端点背后的运行中浏览器,而不是打开一个配置文件目录。

现有会话功能限制

与托管的 openclaw 配置文件相比,现有会话驱动受到更多限制:

  • 歧义 iframe 引用 - 打包的服务器将元素 ID 限定在其所属的 frame 和 document 中。如果自定义服务器对不同 document 返回相同的 ID,OpenClaw 会丢弃该快照并使相关引用失效。不带引用的页面截图仍然可用;请更新自定义服务器,或使用托管浏览器配置文件进行基于引用的操作。
  • 截图 - 页面捕获和 --ref 元素捕获可用;CSS --element 选择器不可用。页面或基于 ref 的元素截图不需要 Playwright。(在任何配置文件中,--full-page 都不能与 --ref 或 --element 组合使用,不仅仅是在现有会话中。)
  • 操作 - click、type、hover、scrollIntoView、drag 和 select 需要快照引用(不支持 CSS 选择器)。click-coords 在可见视口坐标处发送原生输入,无需快照引用,支持左键单击和双击。右键/中键以及非零延迟会返回不支持操作错误。click 仅支持左键(无按钮覆盖或修饰键)。type 不支持 slowly=true;请使用 fill 或 press。press 不支持 delayMs。type、hover、scrollIntoView、drag、select 和 fill 不支持每次调用单独设置 timeoutMs;evaluate 支持。select 接受一个精确的 HTML option 值,包括空值或仅空白值;重复的显示标签不会改变实际选中的值。不支持 batch;请逐个发送操作。
  • 等待 / 上传 / 对话框 - wait --url 支持精确、子串和 glob 模式(与托管相同);现有会话配置文件不支持 wait --load networkidle(在托管和 raw/remote CDP 配置文件中可用)。上传挂钩需要 ref 或 inputRef,不支持 CSS element;当页面的文件输入接受多个文件时,传入多个路径。对话框挂钩不支持超时覆盖或 dialogId。
  • 对话框可见性 - 当操作打开模态对话框时,托管的浏览器操作响应会包含 blockedByDialog 和 browserState.dialogs.pending;快照也会包含待处理的对话框状态。在对话框待处理时,使用 browser dialog --accept/--dismiss --dialog-id <id> 进行响应。在 OpenClaw 外部处理的对话框会出现在 browserState.dialogs.recent 下。
  • 仅限 Playwright 的功能 - PDF 导出、下载拦截、responsebody,以及代理操作 requests、errors、text 和 emulate 需要由 Playwright 支持的配置文件,例如托管的 openclaw 配置文件。使用 snapshot 检查现有会话页面。

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