多配置文件与现有会话附加

配置文件（多浏览器）¶

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 的浏览器配置文件。这会复用该浏览器配置文件中已打开的标签页和登录状态。

官方背景和设置参考：

• Chrome for Developers：使用 Chrome DevTools MCP 调试你的浏览器会话
• Chrome DevTools MCP README

内置配置文件：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 的有限且已编辑的尾部（如果可用）。

Agent 使用：

• 当你需要用户已登录的浏览器状态时，使用 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.9.0 依赖，带有一个临时文档身份补丁，并直接以运行 OpenClaw、Node 或 Bun 的运行时启动其 CLI。 npm 包携带修补后的依赖；源码检出通过 pnpm install 获取该依赖。这使运行时使用的服务器与 OpenClaw 的浏览器契约测试保持一致。该补丁的跟踪见上游修复。

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

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 之前检查 Browser CDP 策略。即使私有网络访问受信任，匹配的 blockedHostnames 条目也会拒绝附加。无关的阻止列表条目不会阻止附加，且默认的严格策略限制仍然适用。

无效、为空、重复或冲突的端点参数会在启动前报错失败。请提供单个有效端点，或省略 cdpUrl 和端点参数以使用主机本地附加。

当选定端点时，userDataDir 会被忽略：Chrome MCP 附加到该端点背后的正在运行的浏览器，而不是打开配置文件目录。