run-agent-browser

run-agent-browser

将 agent-browser 用作实时终端 REPL：执行一条命令，读取结果，然后决定下一步。除非用户要求可复用的测试框架，否则不要在脚本或 && 中串联临时浏览器操作。

升级处理，绝不陷入死路。 如果某一层失败，诊断一次，然后转到下一层。如果所有自动化层都失败，请向用户索取凭据 / CDP URL / 部署决策——不要以“无法完成”收尾。

权威依据

agent-browser skills get core
agent-browser COMMAND --help
agent-browser --version

已安装的 CLI 帮助优先于语法说明。本技能负责此主机的运行时选择和故障升级。

优先级阶梯（始终从第 1 层开始）

层级	适用情况	方法
1. 本地模式	每项新任务的默认选项	取消设置 provider 环境变量；使用隐身参数启动本地 Chrome
2. Steel CDP	第 1 层失败（没有 Chrome、显示器或沙箱），或用户要求使用托管 CDP	加载 Steel 环境变量；通过 --cdp 连接；详情见 references/cdp-and-steel.md
3. 云服务提供商	第 2 层失败或不可用	Browser Use → Kernel → Browserless → Browserbase（或用户指定的服务）；如果 Browser Use 返回 CDP WebSocket connect failed: HTTP error: 400 Bad Request，则跳过并继续后续选项——不要重试（见下文第 3 层）；详情见 references/providers.md
4. 询问用户	所有层都失败或没有凭据	请求 CDP URL、服务提供商密钥，或安装 / 部署批准——然后配置并重试

特殊情况（仅在明确需要时跳过优先级阶梯）：

需求	处理方式
仅需获取公开 URL 的文本	agent-browser read URL（不使用浏览器）
捕获 Google AI Overview / AI Mode / Gemini 内容	Patchright 抓取 API — references/managed-cdp-pool.md（不是 CDP）
用户启动的 Chrome 已有身份验证	--auto-connect 或 connect <port|url> — references/cdp-and-steel.md
Electron / Slack / AgentCore 沙箱	agent-browser skills get <name> 专用技能

隐身模式为默认设置（适用于每一层）

始终优先使用反自动化默认设置。官方不存在 agent-browser-plugin-stealth npm 包（404）；请使用内置功能和服务提供商的隐身标记：

# Local / Steel launch args (tier 1; also apply when launching unmanaged Chrome)
STEALTH_ARGS='--disable-blink-features=AutomationControlled'

# Browserless: stealth ON by default (BROWSERLESS_STEALTH=true)
# Kernel: stealth OFF by default — always set KERNEL_STEALTH=true for this skill
# Proxy (optional, all tiers): --proxy "$AGENT_BROWSER_PROXY" when configured

切勿将代理密码、API 密钥或 Cookie 值放入命令输出、提交内容或聊天中。

第 1 层 — 本地模式（从这里开始）

在此环境中，新的 zsh shell（默认 shell）不会通过 rc 文件自动加载服务提供商环境变量；但 .bashrc 会自动加载 agent-browser-kernel.env（AGENT_BROWSER_PROVIDER=kernel），而在第 3 层操作期间手动加载任何服务提供商文件，也会让该变量在当前 shell 的剩余时间内保持导出状态。第 1 层始终要取消设置该变量，无论使用哪种 shell 或之前运行了什么命令，否则你会在不知情的情况下连接云服务提供商，而不是本地 Chrome。

SESSION="local-$(agent-browser session id --scope cwd --prefix task)"

env -u AGENT_BROWSER_PROVIDER \
  agent-browser --session "$SESSION" \
  --args "--disable-blink-features=AutomationControlled" \
  open https://example.com

env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" snapshot -i
env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" get title
env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" close

出现以下情况时，应视为第 1 层失败并升级处理：找不到 Chrome/Chromium、显示器/Xvfb 错误、沙箱/--no-sandbox 崩溃、CDP 绑定失败、反复出现没有 DOM 的空白页面，或用户使用的机器没有本地浏览器（CI、仅远程连接的笔记本）。

如果错误明确为 Cannot use --cdp and -p/--provider together，说明混用了不同层级——使用 CDP 时移除 -p/AGENT_BROWSER_PROVIDER，使用服务提供商时移除 --cdp。

第 2 层 — Steel CDP（在此机群上自托管）

更改端点或诊断连接失败之前，请先阅读 references/cdp-and-steel.md。快捷步骤：

source "$HOME/.config/steel-browser-cdp.env"   # no-op if missing — then ask user / deploy
# If STEEL_AGENT_BROWSER_CDP is empty: ask user for a CDP websocket URL, or offer to deploy Steel
# (deploy path: Coolify compose in crawler-service/deploy/steel-browser/ — use deploy-coolify-cloud skill)

SESSION="steel-$(agent-browser session id --scope cwd --prefix task)"

# Optional clean slate (Steel is single-session / shared page — see reference)
curl -fsS -X POST "$STEEL_API_URL/v1/sessions/release" >/dev/null 2>&1 || true

env -u AGENT_BROWSER_PROVIDER \
  agent-browser --session "$SESSION" --cdp "$STEEL_AGENT_BROWSER_CDP" \
  open https://example.com

env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" --cdp "$STEEL_AGENT_BROWSER_CDP" snapshot -i
env -u AGENT_BROWSER_PROVIDER agent-browser --session "$SESSION" --cdp "$STEEL_AGENT_BROWSER_CDP" close
curl -fsS -X POST "$STEEL_API_URL/v1/sessions/release" >/dev/null 2>&1 || true   # full reset; close only detaches

Steel 关键事实（不得跳过）： 多个任务共用一个 Chromium，实际上只有一个页面；Steel 任务必须串行执行；--session 仅隔离守护进程状态；close 会断开连接，POST …/v1/sessions/release 会重置。完整语义、端口、tailnet URL 和故障排查，请参阅 references/cdp-and-steel.md。

以下情况应升级到第 3 层：缺少环境文件且用户没有 CDP URL；健康检查或 /json/version 失败；尝试恢复一次后连接仍被拒绝；或 Steel 串行执行导致所需的并行任务无法进行。

如果用户只有原始 CDP 链接（任意主机），请使用第 2 层的操作方式并指定该 URL：

env -u AGENT_BROWSER_PROVIDER agent-browser --session cdp-user --cdp "$USER_SUPPLIED_CDP_WS" open https://example.com

第 3 级 — 云服务提供商（询问、配置、重试）

阅读 references/providers.md，了解环境文件、隐身默认设置和安装。用户未指定服务提供商时，按以下顺序选择：

1. Browser Use（-p browseruse）——此主机上可能已有密钥，但依赖它之前请先查看下方的已知故障说明
2. Kernel（-p kernel）——设置 KERNEL_STEALTH=true；已确认在此主机上可正常工作
3. Browserless（-p browserless）——默认启用隐身模式；已确认在此主机上可正常工作
4. Browserbase（-p browserbase）——仅在已有密钥或用户提供密钥时使用

已知问题（此主机，agent-browser 0.33.2，检查日期：2026-08-03）： 每次尝试使用 -p browseruse 都会稳定失败，报错为 ✗ CDP WebSocket connect failed: HTTP error: 400 Bad Request——无论会话名称是否不同、是否使用 -v/--debug、是否启动全新 shell，还是是否使用文档中的原始语法。这并非密钥无效：经过身份验证的 API 探测返回 200，通过原始 API 创建会话成功，返回的 webSocketDebuggerUrl 也能直接接受原始 WebSocket 升级——因此故障出在 agent-browser 自身的 Browser Use 连接路径，而非账户或网络。将 -p browseruse 返回的一次 400 Bad Request 视为已知故障信号，而非暂时性问题——不要重试，直接切换到 Kernel。

# Example: Browser Use (do NOT print the key)
source "$HOME/.config/agent-browser-browseruse.env"   # if present
# If BROWSER_USE_API_KEY empty → ask user for the key; write to that env file (chmod 600); source; retry
# If it returns "CDP WebSocket connect failed: HTTP error: 400 Bad Request" → known-broken on this host, skip to Kernel

SESSION="prov-$(agent-browser session id --scope cwd --prefix task)"
env -u AGENT_BROWSER_PROVIDER \
  agent-browser --session "$SESSION" -p browseruse \
  open https://example.com

每条命令都必须显式传入 -p <name>（不要在整个会话中依赖全局 AGENT_BROWSER_PROVIDER 的持久设置——这会导致之后 Steel/CDP 出错）。不要将 -p 和 --cdp 同时使用。

如果没有服务提供商密钥： 询问用户希望使用哪家服务提供商，并索要 API 密钥（或控制面板邀请）。提供以下协助：

• 写入 ~/.config/agent-browser-<provider>.env（chmod 600），并在 ~/.zshrc 中添加受保护的 source 行；
• 打开 references/providers.md 中的服务提供商控制面板 URL；
• 完成配置后，重新运行失败的步骤。

不要编造密钥。不要将密钥值粘贴到聊天、提交记录或日志中——只确认“密钥存在 / 仅报告长度”。

第 4 级 — 仍受阻

请用户提供以下任意一项，然后完成配置并从相应级别重试：

1. 现有 Chrome 的 CDP websocket URL（ws:// / wss://）或 host:port
2. 服务提供商名称 + API 密钥（Browser Use / Kernel / Browserless / Browserbase）
3. 批准安装本地 Chrome / agent-browser（npm i -g agent-browser、agent-browser install）
4. 批准部署可自托管的 Steel（此集群：位于 deploy/steel-browser/ 下的 Coolify compose）

核心交互循环（适用于任何级别）

在流程中的每条命令上使用相同的运行时前缀：

# PREFIX is tier-1 env -u … --session … --args …   OR tier-2 … --cdp …   OR tier-3 … -p <name>
$PREFIX open https://example.com
$PREFIX snapshot -i          # refs like @e3 — never @ref=e3
$PREFIX click @e3
$PREFIX wait --url "**/expected"
$PREFIX snapshot -i          # refs stale after navigation — always re-snapshot
$PREFIX get url
$PREFIX get title
$PREFIX errors
$PREFIX close

将操作结果与操作是否成功分开验证。需要视觉证据时，使用截图。

辅助工具

路径	用途
scripts/check-agent-browser-version.sh	只读检查 CLI + Steel + 池健康状态
scripts/inspect-page.sh	Steel 页面捕获工具
assets/templates/*.sh	可复用的工作流（仅在用户要求提供工具模板时使用）
references/cdp-and-steel.md	Steel 端点、单会话语义、发布、tailnet、CDP 附加
references/providers.md	Browser Use / Browserbase / Browserless / Kernel 配置、隐身模式、凭据
references/managed-cdp-pool.md	Patchright Google AI/Gemini 抓取 API
references/commands.md	日常命令路由
references/sessions-and-refs.md	Refs、标签页、恢复、身份验证保险库
references/safety.md	恢复阶梯、共享运行时安全
references/trust-boundaries.md	密钥、注入、对外操作
references/advanced.md	代理、录制、引擎、React

输出要求

报告：最终 URL/标题 + 用户可见的结果；运行的级别（以及任何升级情况）；会话名称；确定性检查；已执行的清理（包括使用 Steel 时的 sessions/release）；产物及其敏感性；索要的凭据或写入的文件（仅报告名称，绝不报告值）；以及留给用户处理的任何安装/部署建议。