OpenClaw 通过 Chrome DevTools Protocol (CDP) 控制浏览器——这是驱动 Chrome 内置开发者工具的同一底层通信通道。截至 2026 年 3 月，这款拥有超过 68,000 个 GitHub Star 的 MIT 许可平台（版本 2026.2.6-3）提供了三种不同的浏览器控制模式，每种模式适合不同的自动化场景。无论你需要保留登录会话、运行完全隔离的自动化，还是将浏览器控制集成到云端流水线，从协议层面理解这些模式的工作原理，都能让你更有效地使用这款工具。
要点速览
OpenClaw 的浏览器控制基于 Chrome DevTools Protocol (CDP)，使用持久 WebSocket 连接而非 HTTP 轮询。共有三种模式：Extension Relay(端口 18792)用于控制现有 Chrome 标签页并保留登录状态；OpenClaw Managed(端口 18800–18899)用于完全隔离的 Chromium 实例，适合安全自动化；Remote CDP 用于连接云端浏览器基础设施。快照系统为每个可交互元素分配数字或基于角色的引用（ref）——这些 ref 在页面导航后会失效，因此每次页面变化后都必须重新获取快照。2026 年起，Playwright 作为底层引擎，为 PDF 生成和 AI 模式快照等高级功能提供支持。
OpenClaw 浏览器控制的工作原理：CDP 基础架构
OpenClaw 的浏览器控制能力并不依赖截图或视觉推断——它在协议层面运作。Chrome DevTools Protocol (CDP) 提供了双向 WebSocket 连接，可以直接向运行中的 Chrome（或任何基于 Chromium 的浏览器）发送命令。这与 Chrome 自带开发者工具检查元素或分析网络请求时使用的通道完全相同。
这种架构优势非常显著。与那些先截图、再视觉分析、然后模拟鼠标点击的工具不同，OpenClaw 实时与浏览器渲染引擎通信。当你执行 browser click 12 这样的命令时，OpenClaw 将其转换为相应的 CDP 操作——这意味着浏览器接收指令的层级与人类用户直接与 DOM 交互完全一致。这种确定性方法消除了视觉自动化工具中常见的不稳定性——按钮位置的轻微偏移或字体渲染差异都可能导致失败，而 CDP 方式则不会受到这些影响。
CDP 暴露了跨多个域的约 300 个命令：Page、Network、DOM、Runtime、Input 等。持久 WebSocket 连接支持实时事件流，因此 OpenClaw 可以异步监听网络请求、控制台日志和导航事件，而无需在每条命令后进行轮询。
在底层，OpenClaw 使用 Playwright 作为高级功能的 CDP 控制引擎。Playwright 通过其 aria-ref 系统处理元素解析，并管理浏览器生命周期事件。对于不安装 Playwright 的基础 ARIA 快照，OpenClaw 退回到可访问性树方案，这种方案更轻量，但对复杂交互的支持较弱。如果需要 AI 模式快照、PDF 生成或元素级截图，需要单独安装 Playwright。
要理解完整的集成方式，有必要了解组件链路。OpenClaw 网关（默认端口 18791）作为编排层，通过 HTTP 或 CLI 接口接收代理命令。控制服务（网关端口偏移量）管理与配置的浏览器模式的连接。Extension Relay 模式下，Chrome 扩展在端口 18792 创建 CDP 中继。Managed 模式下，OpenClaw 启动并管理自己的 Chromium 实例。无论由 GPT-4o、Claude 还是本地模型驱动的代理，都会向网关发送指令，网关再将其转换为针对浏览器的 CDP 操作。
对于在此基础上构建的开发者，laozhang.ai 提供了统一 API 网关，可稳定访问 Claude、GPT-4o 和其他模型，可用作 OpenClaw 浏览器自动化工作流的 AI 后端。文档地址：docs.laozhang.ai。
开始之前，请确保按照 OpenClaw 安装部署完整指南 安装好 OpenClaw，再尝试浏览器配置。
三种浏览器控制模式：如何选择适合你的方案
OpenClaw 的三种浏览器控制模式并不能互相替代——每种模式都是为了解决特定问题而存在的。选错模式会导致不必要的配置麻烦、安全隐患或自动化失败。决策取决于五个问题：你是否需要访问已登录的现有会话？你是否需要与个人浏览器数据隔离？浏览器是在本地还是云端运行？你能接受多复杂的配置？安全隔离有多重要？
Extension Relay 模式（端口 18792）通过一个小型 Chrome 扩展将 OpenClaw 连接到你现有的 Chrome 浏览器。这种方式让代理可以完全访问任何已打开的标签页，包括已经登录认证的标签页。如果你需要在 Gmail、Notion、公司内网或任何登录复杂或使用 SSO 的网站内自动化操作，Extension Relay 是正确的选择。该扩展创建一个本地 CDP 中继，OpenClaw 的控制服务连接到这个中继，将命令转发给 Chrome 的实际运行实例。
实际影响是 Extension Relay 需要安装 Chrome 扩展并与活动标签页关联。代理可以列出所有标签页，选择特定标签页，并接管该标签页（包括其 Cookie 和认证状态）。重要的安全注意事项是：任何自动化任务都应使用专用的 Chrome 配置文件，而非你的个人浏览配置文件——扩展在设计上可以访问该配置文件中的所有内容。
OpenClaw Managed 模式（端口 18800–18899）启动并管理一个独立的、隔离的 Chromium 实例，与你的个人浏览器完全分离。没有共享 Cookie、没有共享历史记录，浏览和自动化之间不存在交叉污染的风险。OpenClaw 可以同时运行多个托管浏览器配置文件，每个配置文件占用 18800–18899 范围内的不同端口。这是大多数自动化工作流（包括网页抓取、测试和批量表单处理）的推荐模式。
托管浏览器可以在无头模式（不可见，无 UI）下运行（适合服务器环境）或有头模式（可见窗口）下运行（适合调试）。地理位置模拟、设备仿真、自定义 HTTP 标头和离线模式模拟等高级功能在托管模式下均可通过配置选项实现。此配置中的 AI 模式快照需要安装 Playwright。
Remote CDP 模式将 OpenClaw 连接到外部 Chromium 浏览器，通常运行在云环境中。你在 OpenClaw 设置中配置端点 URL 和认证令牌。此模式适用于浏览器基础设施单独管理的生产流水线——例如，运行在负载均衡器后面的云浏览器集群。Remote CDP 配置支持 HTTPS 安全连接，超时设置（remoteCdpTimeoutMs 和 remoteCdpHandshakeTimeoutMs）可根据网络延迟进行调整。
以下对比表总结了关键决策标准：
| 标准 | Extension Relay | OpenClaw Managed | Remote CDP |
|---|---|---|---|
| 访问现有会话 | 是 | 否 | 取决于配置 |
| 需要 Chrome 扩展 | 是 | 否 | 否 |
| 与个人数据隔离 | 否 | 是 | 是 |
| 本地运行 | 是 | 是 | 否 |
| 云端/生产环境 | 否 | 可能 | 是 |
| 配置复杂度 | 中 | 低 | 高 |
| 默认端口 | 18792 | 18800+ | 自定义 |
关于在 Relay 和 Managed 两者都可行时如何选择：如果网站需要全新会话（无 Cookie），优先选择 Managed 模式；如果网站存在难以通过程序重新创建的现有认证会话，使用 Extension Relay 配合专用配置文件。
快照与引用系统的工作原理
快照和引用系统是 OpenClaw 让 AI 代理与浏览器元素交互的方式，无需依赖脆弱的 CSS 选择器或视觉模式匹配。当你运行 openclaw browser snapshot 时，OpenClaw 扫描整个页面并为每个可交互元素分配唯一的数字引用（ref）——按钮、输入框、链接、下拉菜单等。代理随后使用这些 ref 指定要交互的元素：browser click 12 点击元素 12，browser type e15 "hello" 在元素 15 中输入内容。
快照有两种不同模式，根据你的 Playwright 配置，差异至关重要。AI 模式快照生成数字 ref（如 12、34）。这些快照内部使用 Playwright 的 aria-ref 解析，将语义可访问性信息映射到稳定的数字标识符。当 Playwright 安装后，AI 模式快照是默认选项，更适合复杂交互，因为 Playwright 能可靠地处理元素解析。
角色模式快照生成带"e"前缀的 ref（如 e12、e34）。这些快照通过 getByRole() 匹配方式直接使用浏览器的可访问性树。角色快照无需安装 Playwright 即可工作，是最简配置的备用选项。代价是基于角色的匹配不够精细，对于具有不寻常可访问性属性的元素可能表现异常。
快照系统最重要的规则是 ref 持久性：ref 只在当前页面状态下有效。任何导航事件——无论是点击链接、调用 browser navigate，还是 JavaScript 重定向——都会使所有现有 ref 失效。导航后，新页面的 DOM 结构完全不同，旧 ref 编号毫无意义。同样，通过 AJAX 调用或 JavaScript 重新渲染大幅更新 DOM 的动态页面，可能在不触发完整导航的情况下使特定 ref 失效。
这种行为是有意为之，而非缺陷。ref 系统优先考虑正确性——指向已消失元素的过期 ref 要么静默失败，要么与错误的元素交互。操作上的影响是工作流纪律：在新页面上进行任何交互序列之前，始终先获取新的快照。
可靠自动化的实用模式如下：导航到 URL，获取快照，从快照输出中找到目标元素 ref，执行交互，检查交互是否导致导航或重大 DOM 变化，如果是，在继续之前再次获取快照。对于跨多个页面的多步骤工作流，这种"快照后交互"的循环在每次页面转换时重复。
值得注意的一个细节：快照输出包含每个元素的元数据，包括其角色（按钮、链接、文本框）、可访问名称或标签，以及其 ref。AI 代理使用这些信息来推断哪个元素对应"提交"按钮或搜索输入框。这种语义信息是 OpenClaw 自动化比基于 CSS 选择器方案更健壮的原因——当网站重新设计时，按钮标签几乎不会改变，而 CSS 类名往往会改变。
实用浏览器自动化工作流
当你将快照、导航和交互命令组合成连贯的工作流时，OpenClaw 的浏览器控制才真正发挥价值。以下三个工作流展示了当前工具能实现的范围。
工作流 1：使用 Extension Relay 的认证会话自动化
这是 Extension Relay 模式最常见的使用场景。场景是在你已登录的 Web 应用内自动化任务——例如，从商业智能仪表板导出报表、填写定期表单，或监控需要身份验证的状态页面。
首先通过 LLM 配置流程配置你的 AI 提供商。然后，在 Extension Relay 激活且 Chrome 扩展已连接的情况下，在浏览器中打开目标网站。操作序列如下：
bashopenclaw browser tabs # 列出可用标签页 openclaw browser tab select 3 # 切换到目标标签页 openclaw browser snapshot # 扫描可交互元素
快照返回元素及其 ref 的列表。代理解析此输出并识别需要交互的元素。从这里开始，工作流可能如下：点击导出按钮（ref 8），等待模态框出现，再次获取快照以获取模态框的元素 ref，填写日期范围输入框，点击确认。关键优势是所有这些都在你的认证浏览器会话中进行——无需登录过程。
工作流 2：使用 Managed 模式的隔离网页抓取
对于从公共网站提取数据，Managed 模式是正确的选择。隔离意味着你不会冒险使用个人 Cookie 或浏览状态，而且可以并行运行多个配置文件以提高吞吐量。
bashopenclaw browser start --profile scraper-1 # 启动托管浏览器 openclaw browser navigate "https://target-site.com/data" openclaw browser wait # 等待页面加载 openclaw browser snapshot
从快照中，代理识别数据元素——表格行、文本块、需要跟进的链接。它从特定 ref 中提取文本内容，通过点击"下一页"按钮 ref 翻页，并重复此过程直到处理完所有页面。对于 AJAX 加载内容的网站，browser wait 命令（可以等待特定文本出现）确保代理不会在元素存在之前就尝试交互。
OpenClaw 处理网页抓取的实际复杂性：可以提取 Cookie 进行会话管理，拦截网络请求以了解网站发出的 API 调用，以及模拟滚动事件触发懒加载内容。快照系统意味着代理无需提前知道 CSS 选择器——它从可访问性结构中进行推断。
工作流 3：监控与告警工作流
特别有用的模式是定期监控——检查页面的变化并在出现特定内容时触发操作。配置 AI 代理每隔几分钟检查一次仪表板：
bashopenclaw browser navigate "https://status-page.com" openclaw browser snapshot # 如果条件满足：通过已配置的渠道发送通知
由于 OpenClaw 连接到消息渠道（Telegram、Slack、Discord 等），监控工作流可以直接通过代理的通信渠道发送告警，无需额外集成。
对于生产监控工作流，需要注意 token 消耗——每次快照都会消耗 token，因为 AI 模型需要处理页面结构。在复杂页面上频繁运行快照时，token 管理最佳实践变得尤为重要。
浏览器中继的安全最佳实践
浏览器自动化引入了容易被忽视的安全考量，直到出问题才会引起注意。OpenClaw 的设计包含了多项安全默认值，但也有一些重要实践需要用户有意识地去实施。
OpenClaw 的浏览器控制服务默认绑定到回环地址（127.0.0.1），这意味着它只能从同一台机器访问。这是一个刻意的安全默认值——端口 18792 上的 CDP 中继绝不应该暴露给外部网络。2026 年 1 月，ZeroPath 安全研究团队发布了关于 OpenClaw 浏览器中继服务器漏洞的研究报告，在特定网络配置下回环绑定可以被绕过，允许恶意网站访问本地中继服务。OpenClaw 在后续版本中发布了补丁，但这一事件凸显了网络隔离的重要性。
大多数用户的实用安全配置包括三个层级。首先，为任何 Extension Relay 自动化使用专用的 Chrome 配置文件——绝不要在你用于个人浏览的同一配置文件中运行自动化任务。自动化配置文件应只包含特定任务所需的 Cookie 和凭据。如果该配置文件被入侵或行为异常，影响范围仅限于该配置文件。
其次，在防火墙层面阻止网关端口（18791）和中继端口（18792）的外部访问。如果你在服务器上运行 OpenClaw，配置防火墙规则，只允许 OpenClaw 进程绑定这些端口。除非你配置了显式认证，否则不要通过网络地址转换或端口转发将它们暴露出去。
第三，对于 Remote CDP 模式，始终使用 HTTPS 连接并配置认证令牌。remoteCdpToken 设置确保连接到云端浏览器端点时需要认证。定期轮换这些令牌，特别是当你在团队成员之间共享配置时。
对于 SSRF（服务端请求伪造）防护，OpenClaw 包含可配置的 SSRF 策略，限制托管浏览器可以访问的 URL。在浏览器可能被指示访问内部网络资源的环境中，启用私有网络封锁策略可以防止浏览器被用作访问内部服务的代理。
一个常被忽视的风险是通过快照的凭据泄漏。当代理处理包含敏感表单数据的页面快照时，该数据可能出现在 AI 模型处理的快照输出中。请谨慎对待你获取快照的页面——除非有特定控制措施，否则避免对显示完整账户号码、社会安全号码或类似敏感数据的页面进行快照。
浏览器控制故障排除：错误信息与修复方案
OpenClaw 浏览器控制中最常见的痛点是连接失败，几乎总是表现为"无法连接到 OpenClaw 浏览器控制服务（20000ms 后超时）"。这个错误有几个不同的原因，需要不同的修复方法，系统性地排查比随机尝试更高效。
首先检查 OpenClaw 网关是否实际在运行。打开终端运行 openclaw gateway status。如果网关未运行，使用 openclaw gateway start 启动它，或在 macOS 上通过菜单栏应用启动。网关必须运行，任何浏览器控制命令才会工作。如果网关正在运行但你仍然收到超时错误，检查控制端口（默认 18791）是否被另一个进程占用：macOS/Linux 上使用 lsof -i:18791，Windows 上使用 netstat -ano | findstr 18791。终止冲突进程并重启网关。
对于 Windows 用户，特别是在 WSL2 中运行 OpenClaw 的用户，常见问题是 Windows 防火墙阻止 WSL2 虚拟网络接口访问在 WSL2 中运行的网关。GitHub issue #30196 精确记录了这个问题。修复方法是创建从 Windows 主机到 WSL2 IP 的端口代理规则：netsh interface portproxy add v4tov4 listenport=18791 listenaddress=0.0.0.0 connectport=18791 connectaddress=$(wsl hostname -I)。这将连接从 Windows 主机端口转发到运行 OpenClaw 的 WSL2 实例。
代理环境变量会造成微妙而令人困惑的故障模式。如果你的 shell 中设置了 HTTP_PROXY、HTTPS_PROXY 或 ALL_PROXY 环境变量，OpenClaw 到浏览器的 CDP 连接尝试可能会通过代理路由，导致超时或连接被拒绝错误。GitHub issue #31219 记录了这一问题。修复方法很简单：将 localhost 和 127.0.0.1（以及 IPv6 的 ::1）添加到 NO_PROXY 环境变量。在你的 shell 配置中添加 export NO_PROXY="localhost,127.0.0.1,::1"。
"标签页未找到"错误及其变体"使用过期 ref 后 ref 未找到"有相同的根本原因：发生了导航，但 ref 没有刷新。在任何浏览器导航命令之后、任何导致页面变化的点击之后，或任何导致重大 DOM 变更的操作之后，你必须在引用任何元素之前获取新的快照。始终在导航后进行快照的工作流纪律可以完全消除这类错误。
对于 Extension Relay 失败（扩展似乎没有连接到活动标签页），通常原因是该标签页不允许 CDP 附加。这发生在扩展激活之前已打开标签页的情况下，或者标签页是浏览器内部页面（如 Chrome 设置或新标签页）时。检查扩展弹出窗口——它显示连接状态。点击 Chrome 工具栏中的扩展图标触发重新附加。如果扩展显示已连接但命令仍然失败，运行 browser tabs 列出可用标签页，运行 browser tab select {id} 显式选择目标标签页。
对于 Playwright 相关失败——特别是当 AI 模式快照因找不到 Playwright 而失败时——安装 Playwright 及其浏览器二进制文件：
bashnpm install playwright npx playwright install chromium
如果你想避免 Playwright 依赖，使用 browser snapshot --role 切换到角色模式快照。角色模式无需 Playwright 即可工作，但提供的元素解析不够精细。对于简单页面和直接交互模式，这是可靠的备用方案。
内置的 openclaw doctor 命令运行全面诊断，检查所有组件：网关连通性、浏览器可用性、Playwright 安装、扩展状态和端口绑定。故障排除时先运行此命令，可以全面了解哪些正常哪些异常，节省大量调试时间。
对于阻止 AI 模型处理快照的 API 密钥错误，API 密钥故障排除指南涵盖了最常见的配置问题。密集浏览器自动化会话中的速率限制错误，请参阅速率限制管理指南。
高级配置：端口、配置文件与性能
OpenClaw 的默认配置适用于单浏览器单用户场景，但该工具支持更复杂的安排。理解端口架构和配置文件系统，可以实现并行自动化、复杂的多步骤工作流和生产级可靠性。
端口方案遵循固定偏移模式。网关运行在端口 18791。控制服务运行在网关端口 + 9（默认配置文件为 18800）。每个额外的托管浏览器配置文件占用下一个端口：配置文件 1 使用 18800，配置文件 2 使用 18801，配置文件 99 使用 18899。Extension Relay 占用端口 18792。当你需要同时运行多个隔离的浏览器会话时——例如测试多用户工作流或运行并行抓取任务——启动多个配置文件：
bashopenclaw browser start --profile job-1 # 使用 18800 openclaw browser start --profile job-2 # 使用 18801 openclaw browser start --profile job-3 # 使用 18802
每个配置文件维护自己的 Cookie、存储和浏览状态。你分配的配置文件名称（如"job-1"）是人类可读的标签；OpenClaw 在内部管理端口映射。
对于无头与有头操作，无头模式适合无显示器的服务器环境和生产流水线，而有头模式（可见浏览器窗口）在开发过程中很有价值，因为你可以观察自动化的执行过程并发现视觉问题。两种模式之间切换只是配置标志，不影响 CDP 命令接口。性能上有轻微差异——无头模式使用略少的内存和 CPU，因为浏览器不需要渲染视觉合成层，但差异远小于被自动化页面的网络和 JavaScript 执行成本。
自定义可执行路径配置允许你指定 OpenClaw 在托管模式中使用哪个基于 Chromium 的浏览器。默认情况下，它使用系统 Chromium。如果自动化需要特定的浏览器行为，可以指向特定版本的 Chrome、Brave 或 Edge。这在跨浏览器版本测试网站兼容性时很有用。
对于大规模自动化，超时配置非常重要。默认的 remoteCdpTimeoutMs 和 remoteCdpHandshakeTimeoutMs 值针对本地连接进行了调优。如果 Remote CDP 端点存在网络延迟——例如位于不同地区的云端浏览器实例——增加这些超时值可以防止由于连接建立缓慢而导致的虚假失败。同样，应该审查 SSRF 策略配置：最严格的设置会阻止托管浏览器访问私有网络地址，这可以防止浏览器被用作内部网络代理，但可能会干扰合法需要访问本地开发服务器的自动化。
对于关注 API 访问成本的团队，每次快照操作消耗的 token 数量与页面复杂度成正比。交互元素少的简单页面消耗的 token 远少于密集的企业应用页面。使用角色模式快照（无 Playwright）产生的快照输出略小于 AI 模式快照，这对于高频监控工作流可以减少 token 消耗。
总结：OpenClaw 浏览器控制实践
OpenClaw 的浏览器控制系统代表了一种连贯的 AI 驱动 Web 自动化方案。CDP 基础为其提供了视觉自动化工具无法匹敌的确定性、可靠控制。三种模式覆盖了从个人认证工作流到生产云端部署的全部场景。快照和引用系统一旦理解了 ref 生命周期，就提供了一个清晰的抽象层，让 AI 代理无需知道 CSS 选择器或 XPath 表达式就能处理网页。
构建工作流时需要记住的实际约束：ref 在导航后失效，因此快照纪律不可妥协；Extension Relay 出于安全需要专用 Chrome 配置文件；Playwright 依赖是可选的，但解锁了最强大的快照模式；代理环境变量是生产环境中容易被忽视的常见静默故障原因。
随着 OpenClaw 生态系统持续演进——该项目在 2026 年初保持着显著的 GitHub 活跃度——浏览器控制仍然是其最强大的功能之一，用于构建能够真正在 Web 上采取行动的代理，而不仅仅是处理关于 Web 的文本。
本指南反映截至 2026 年 3 月的 OpenClaw 版本 2026.2.6-3。最新文档请访问 OpenClaw 官方文档。