🚀 核心特性与部署流程

BrowserAct 主要解决 AI 代理在自动化网页操作中遇到的反爬机制、多任务隔离和状态管理等问题。它的部署和使用可以分为以下三个主要环节：

环节一：环境准备与 CLI 安装
在开始之前，请确保你的系统满足以下要求：

  • 操作系统：Windows、macOS 或 Linux。
  • Python 版本：需要 Python 3.12 或更高版本。
  • 浏览器：需要安装 Chrome 或 Chromium 浏览器（用于 chrome 和 chrome-direct 两种浏览器模式）。
  • 包管理工具：推荐使用 uv 进行安装。

环节二：认证与配置（可选）
CLI 安装后即可使用基础功能。若要解锁更高级的反检测能力，需要配置 API Key。

环节三：核心工作流
完成安装和认证后，即可开始进行浏览器自动化任务。核心工作流包括内容提取和交互式会话两种模式。

📋 详细操作步骤

第1步：安装 CLI 工具

推荐使用 uv 工具进行安装，以确保环境干净。

1
2
3
4
5
# 安装 browser-act CLI
uv tool install browser-act-cli --python 3.12

# 验证安装是否成功
browser-act --version

如果提示命令未找到，需要将 uv 的工具目录添加到系统的 PATH 环境变量中。

第2步：配置 API Key（解锁高级功能）

基础浏览器自动化无需 API Key，但使用隐身浏览器（Stealth Browser）、自动验证码解决（solve-captcha）和受保护内容提取（stealth-extract）等功能时需要。可通过以下命令登录并设置密钥：

1
2
3
4
# 这将打开一个注册/登录页面
browser-act auth login
# 完成后，轮询并获取密钥
browser-act auth poll

你也可以直接设置已有的密钥：browser-act auth set <你的API密钥> 。

第3步：快速上手与核心命令

安装完成后，可以通过两种主要方式使用它。

方式一：快速提取页面内容 (stealth-extract)
当你只需要获取页面渲染后的文本内容时，使用此命令最方便。它会自动启动一个带有反检测能力的浏览器，获取内容后自动关闭。

1
2
3
4
5
# 提取页面内容并保存为 Markdown 文件
browser-act stealth-extract https://example.com --output ./page.md

# 提取原始 HTML 内容
browser-act stealth-extract https://example.com --content-type html

方式二：交互式浏览器会话 (--session)
当任务需要登录、点击、填表等多步交互时，需要使用会话模式。它的工作流程是：打开页面 → 查看状态 → 执行操作 → 再次查看状态 → 关闭会话。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 1. 查看可用的浏览器列表
browser-act browser list

# 2. 创建一个名为 "my-task" 的会话，并用指定浏览器打开网页
browser-act --session my-task browser open <浏览器ID> https://example.com

# 3. 查看当前页面的可交互元素状态（返回带索引的列表）
browser-act --session my-task state

# 4. 根据状态返回的索引进行交互（例如，点击索引为 3 的元素，在索引为 2 的输入框中输入文本）
browser-act --session my-task click 3
browser-act --session my-task input 2 "hello@example.com"

# 5. 任务完成后关闭会话
browser-act session close my-task

注意：state 命令是代理理解页面的核心，它返回的索引元素便于后续操作。页面变化后，索引可能失效，因此每次交互前都应重新获取状态。

🔧 进阶部署：集成到 AI 代理

BrowserAct 最大的优势在于它能被 AI 代理直接调用。对于支持 Skill（技能）的代理（如 Claude Code、Cursor、OpenClaw 等），可以通过以下方式集成：

  1. 告知代理安装：直接向你的 AI 代理发送指令，让它自行完成安装和配置。

    “请安装 browser-act。Skill 源地址：https://github.com/browser-act/skills/tree/main/browser-act 。安装后验证它是否正常工作。”

  2. 动态获取技能：代理在开始每个会话时，应首先运行 get-skills 命令，以获取当前环境的状态和可用的命令列表，而不是依赖过时的指令。

    1
    browser-act get-skills core --skill-version 2.0.2

💡 核心场景与最佳实践

  • 并发与隔离：通过为每个任务指定唯一的 --session 名称，可以实现多任务并行，且状态（Cookies、指纹等）完全隔离，互不干扰。
  • 反封锁三级策略：BrowserAct 设计了环境层（指纹伪装）、执行层（自动解验证码）和人工层（remote-assist 生成接管链接）的递进式方案，有效应对各类反爬机制。
  • 从探索到固化（Skill Forge）：如果某个网站的自动化流程需要反复执行，可以使用 Skill Forge 工具。它先让代理探索一次网站结构，然后自动生成一个可复用的 Skill 包，后续任务可直接调用，无需重复探索。