通过 Chrome DevTools Protocol 连接到现有浏览器¶

# Start Chrome with: google-chrome --remote-debugging-port=9222

# Connect once, then run commands without --cdp
agent-browser connect 9222
agent-browser snapshot
agent-browser tab
agent-browser close

# Or pass --cdp on each command
agent-browser --cdp 9222 snapshot

会话会一直保持连接，直到执行 agent-browser close。之后不带连接标志的命令将针对同一个浏览器运行，就像再次传入了 --cdp 一样。如果该浏览器消失，命令会失败，而不是启动本地浏览器。

如果调试端口尚未打开，connect 和 --cdp 会最多等待 2 秒，然后才失败。

远程 WebSocket URL¶

通过 WebSocket URL 连接到远程浏览器服务：

# Connect to remote browser service
agent-browser --cdp "wss://browser-service.com/cdp?token=..." snapshot

# Works with any CDP-compatible service
agent-browser --cdp "ws://localhost:9222/devtools/browser/abc123" open example.com

# Authenticated CDP WebSocket (e.g. Cloudflare Browser Rendering)
agent-browser --cdp "wss://api.cloudflare.com/.../devtools/browser" \
  --cdp-headers '{"Authorization":"Bearer YOUR_API_TOKEN"}' snapshot

--cdp 标志接受以下两种形式：

• 端口号（例如 9222），用于通过 http://localhost:{port} 进行本地连接
• 完整的 WebSocket URL（例如 wss://... 或 ws://...），用于远程浏览器服务

当服务通过 WebSocket 握手而不是 URL 进行身份验证时，请使用 --cdp-headers（或 AGENT_BROWSER_CDP_HEADERS）。它接受一个值为字符串的 JSON 对象，并在 HTTP 发现（/json/version、/json/list）和 WebSocket 握手时发送，对 URL 和端口号同样适用。它与 --headers 是分开的，后者用于设置页面请求的 HTTP 头。

对于 https:// CDP URL，发现过程会保持输入的加密方式：请求通过 https:///wss:// 发送，因此凭据绝不会以明文形式传输，也不会回退到未加密的协议。只有在信任的网络上，才应对 http:///ws:// 目标传入 --cdp-headers。

根 WebSocket 端点接受带或不带显式斜杠的查询字符串，因此 wss://browser-service.com?token=... 和 wss://browser-service.com/?token=... 都可以使用。

自动连接¶

使用 --auto-connect 自动发现并连接到正在运行的 Chrome 实例，而无需指定端口：

# Auto-discover running Chrome with remote debugging
agent-browser --auto-connect open example.com
agent-browser --auto-connect snapshot

# Or via environment variable
AGENT_BROWSER_AUTO_CONNECT=1 agent-browser snapshot

自动连接通过以下方式发现 Chrome：

1. 从默认用户数据目录读取 Chrome 的 DevToolsActivePort 文件并连接到其 WebSocket 端点，然后对较旧版本的 Chrome 执行 HTTP 发现（/json/version、/json/list）
2. 回退到探测常用调试端口（9222、9229）

Chrome 144+ 在首次连接时会显示远程调试权限提示。自动连接会等待最多 20 秒以获得批准。如果此后提示仍然打开，命令将失败并显示一条消息，要求你批准后重试，而不会打开第二个提示。

这在以下场景中很有用：

• Chrome 144+ 已通过 chrome://inspect/#remote-debugging 启用远程调试（使用动态端口）
• 你想要零配置地连接到现有浏览器
• 你不想跟踪 Chrome 正在使用哪个端口

标签页固定¶

当多个会话通过 CDP 共享一个浏览器时，每个会话都会记住它绑定到哪个标签页（通过 CDP target id，在守护进程重启后仍然保留）。重启后的守护进程会重新连接到会话自己的标签页，而不是采用当前活动的标签页——在共享浏览器中，当前活动的标签页通常是另一个会话的。

传入 --pin-tab（或设置 AGENT_BROWSER_PIN_TAB=1）以启用严格的绑定：

# Two agents sharing one Chrome, each pinned to its own tab
agent-browser --session agent1 --cdp 9222 --pin-tab open https://site-a.com
agent-browser --session agent2 --cdp 9222 --pin-tab open https://site-b.com

使用 --pin-tab 时：

• 无绑定时附加会打开一个新的标签页，而不是采用现有的标签页
• 如果绑定的标签页被关闭，命令将失败并返回 tab_gone 错误，而不是静默地对另一个标签页执行操作。JSON 响应包含 "code": "tab_gone"、data.targetId 和可选的 data.lastUrl
• 在该状态下，tab list、tab new 和 tab <ref> 仍然有效，因此 agent 可以通过绑定新的标签页来恢复
• 其他会话或用户打开的标签页永远不会抢占已固定会话的活动标签页
• 当固定会话正在运行时，其他会话无法通过 tab <ref> 获取已固定的标签页；切换会失败并返回 tab_locked，其中会指明所有者

该标志按会话具有粘性：传入一次后，后续命令都会保持严格的语义。守护进程重启后仍会保留固定状态；显式关闭会释放固定，以便其他会话可以获取该标签页，而下一次带固定标志的命令会再次固定。传入 --no-pin-tab 可显式再次关闭固定。多会话工作流请参阅 Sessions，通过 CDP target id 引用标签页请参阅 Commands。

结构化的 lastUrl 仅针对经过净化的 HTTP(S) URL 和 about:blank 发出。凭据、查询字符串和片段会从 HTTP(S) URL 中移除，而 data: 等不透明 URL 则会被省略。批量 JSON 会在 result 下暴露恢复对象。

当重新运行共享标签页的脚本时（例如来自 #1530 的复现脚本），请为每个会话的第一个命令添加 --pin-tab。如果不添加，open 会有意保留旧行为并导航共享的活动标签页，因此原始脚本仍然会发生冲突。当会话使用 --auto-connect 而不是 --cdp 附加时，同样适用此规则。

颜色方案¶

通过 CDP 连接时，使用 --color-scheme 设置持久的偏好：

agent-browser --cdp 9222 --color-scheme dark open https://example.com
agent-browser --cdp 9222 snapshot  # stays in dark mode

或者通过配置或环境变量进行全局设置：

AGENT_BROWSER_COLOR_SCHEME=dark agent-browser --cdp 9222 open https://example.com

使用场景¶

这可以控制以下内容：

• Electron 应用
• 启用了远程调试的 Chrome/Chromium
• WebView2 应用
• 远程浏览器服务（通过 WebSocket URL）
• 任何暴露 CDP 端点的浏览器

全局选项¶

云提供商¶

使用 -p 标志连接到云浏览器提供商或已配置的 browser.provider 插件，而不是启动本地浏览器：

agent-browser -p browserbase open https://example.com

有关每个内置提供商的设置和配置，请参阅 提供商 部分：Browser Use、Browserbase、Browserless、Kernel 和 AgentCore。