BrowserForce：让AI代理直接操作真实浏览器，实现零配置自动化

1. 项目概述：BrowserForce，一个让你掌控浏览器的AI代理平台

如果你和我一样，对AI代理（Agent）的潜力感到兴奋，但又对“沙盒”环境束手束脚，觉得它们离真实世界总隔着一层玻璃，那么BrowserForce的出现，绝对值得你花上十分钟了解一下。这不是又一个让你在独立浏览器里“玩沙子”的工具，而是直接把AI请进你正在使用的、登录了所有账号的真实Chrome浏览器里。想象一下，你的AI助手能像你一样，打开你的Gmail收件箱，浏览你关注的X（Twitter）时间线，或者在你公司的内部管理后台帮你提取数据——所有这些，都不需要你交出任何密码、API密钥或会话Cookie。

BrowserForce的核心哲学非常直接：“狮子不会关心令牌计数，10倍效率的用户不会关心沙盒浏览器——沙盒是给小孩玩的。”这句话精准地戳中了当前AI代理工具的一个痛点：为了安全，它们往往运行在隔离的、无状态的浏览器环境中，这意味着每次任务都要重新登录，无法利用你已有的身份和上下文。BrowserForce反其道而行，它通过一个Chrome扩展程序，在你的真实浏览器和AI代理之间架起一座安全的桥梁，让代理能直接操作你已登录的浏览器会话。

我最初接触这个项目，是因为需要让我的OpenClaw代理自动处理一些重复性的网页数据收集工作。传统的方案要么需要我预先配置好复杂的登录脚本和Cookie管理，要么代理只能在“干净”的浏览器里操作，完全无法触及那些需要复杂身份验证的内部系统。BrowserForce完美地解决了这个问题。它不提取、不存储你的任何凭证，只是作为一个“遥控器”，让AI通过标准的Chrome DevTools Protocol（CDP）来操作你已经打开的浏览器窗口。这种设计在安全性和便利性之间找到了一个绝佳的平衡点：你的登录状态永远只存在于浏览器中，AI只是获得了操作权限，而非数据副本。

2. 核心架构与工作原理深度解析

要理解BrowserForce为何强大，我们需要拆解它的技术栈。它不是一个单一的应用，而是一个由几个精密组件协同工作的系统。

2.1 组件交互流程图解

整个系统的数据流可以清晰地分为三层：代理层、中继层和浏览器层。

[你的AI代理 (如OpenClaw, Claude Desktop)] | | 通过MCP协议或CLI命令 v [BrowserForce MCP服务器 / CLI] | | 通过WebSocket (CDP over WebSocket) v [本地中继服务器 (localhost:19222)] | | 通过扩展程序消息传递 v [Chrome扩展程序 (MV3 Service Worker)] | | 调用 chrome.debugger API v [你的真实Chrome浏览器 & 标签页]

代理层：这是你发出指令的地方。无论是通过OpenClaw的聊天界面、Claude Desktop的侧边栏，还是直接使用命令行，你的指令最终都会被封装成对BrowserForce MCP服务器的调用。

中继层：这是运行在你本机上的browserforce serve进程。它扮演着“翻译官”和“交通警察”的角色。一方面，它将来自MCP服务器或CLI的高层指令（如“执行这段JavaScript”）翻译成浏览器能理解的CDP原始命令；另一方面，它也管理着连接状态、安全策略和插件系统。中继服务器默认监听127.0.0.1:19222，确保所有通信都发生在你的电脑内部，不会泄露到外网。

浏览器层：这是魔法发生的地方。BrowserForce的Chrome扩展程序被加载到你的浏览器中。当它被激活后，会使用Chrome官方提供的chrome.debuggerAPI，以调试模式附加到你指定的浏览器标签页上。这个API与Chrome开发者工具使用的是同一套底层接口，因此它能获得对页面DOM、网络请求、JavaScript执行环境的完全控制权，就像你手动打开开发者工具并输入命令一样。关键在于，这个“调试”连接是由你本地的扩展程序建立的，所有数据（包括页面内容、Cookie）都不会离开你的浏览器进程。

2.2 安全模型的基石：不碰触凭证

这是BrowserForce设计中最精妙也最让人安心的一点。我们对比一下常见的几种方案：

方案	凭证处理方式	风险点
传统RPA/自动化脚本	需要将用户名、密码、甚至2FA种子密钥硬编码在脚本或环境变量中。	凭证泄露风险极高；任何能访问脚本的人都能获得你的全部账号权限。
基于Cookie导出的方案	要求你从浏览器导出cookies.json文件，供自动化工具“回放”会话。	Cookie是敏感的会话令牌，导出即泄露；且Cookie会过期，需要定期更新，维护麻烦。
独立的浏览器配置文件	为自动化创建一个新的Chrome用户，需要你重新登录所有网站。	失去了“已登录”状态的便利性；对于需要公司SSO或复杂OAuth流程的网站，配置极其困难。
BrowserForce	完全不接触凭证。它直接操作你已登录的浏览器实例。	凭证始终由浏览器本身的安全机制（如密码管理器、系统钥匙串）保管。AI代理只是获得了“操作”的权限，而非“数据”的副本。

这种模式带来的直接好处是“零配置登录”。如果你的浏览器已经登录了GitHub、Notion、公司内网，那么BrowserForce驱动的AI代理就能直接在这些页面上工作，无需任何额外的身份验证步骤。这大大降低了使用门槛，也让自动化流程能够触及那些原本因为登录障碍而无法自动化的场景。

实操心得：信任边界使用BrowserForce意味着你信任该AI代理在你浏览器标签页内的操作。因此，务必只将它与你信任的、能力经过验证的AI模型（如Claude 3.5 Sonnet, GPT-4）结合使用，并充分利用其提供的安全控制功能（如只读模式、URL锁定）。这就像你把家门钥匙交给了一位高度专业且遵守严格指令的管家，而不是一个陌生人。

3. 详细安装与配置指南

BrowserForce的安装过程力求简洁，但其中一些步骤对于确保功能正常至关重要。下面我将以macOS系统为例，详细拆解每一步，并补充Windows和Linux用户的注意事项。

3.1 核心组件安装

首先，你需要安装Node.js环境（建议版本16+）。然后通过npm或pnpm全局安装BrowserForce命令行工具。

# 使用 npm (最通用) npm install -g browserforce # 或使用 pnpm (速度更快，磁盘空间更省) pnpm add -g browserforce

安装完成后，你可以通过browserforce --help验证安装是否成功。这个全局命令是你管理整个BrowserForce生态系统的入口。

3.2 Chrome扩展程序的加载：关键步骤详解

这是整个设置过程中最容易出错的一步。BrowserForce的功能依赖于一个Chrome扩展程序，这个扩展程序需要以“开发者模式”手动加载。

步骤1：安装扩展程序文件运行以下命令，它会将扩展程序文件包复制到一个固定的本地目录。

browserforce install-extension

命令执行后，请务必记住它输出的路径，例如：/Users/你的用户名/.browserforce/extension。这个路径稍后需要用到。

步骤2：在Chrome中加载扩展

1. 打开Chrome浏览器，在地址栏输入chrome://extensions/并访问。
2. 在页面右上角，找到并**打开“开发者模式”**的开关。
3. 点击页面左上角的“加载已解压的扩展程序”按钮。
4. 这时会弹出一个文件选择对话框。关键操作来了：
   • macOS用户：在文件选择对话框出现后，按下键盘快捷键Cmd + Shift + G。这会打开一个“前往文件夹”的输入框。将步骤1中得到的路径（如/Users/你/.browserforce/extension）完整粘贴进去，然后按回车。
   • Windows/Linux用户：在文件选择对话框的地址栏中，直接粘贴该路径。
5. 正确操作后，对话框会自动定位到extension文件夹。选中它（或进入后点击“选择文件夹”）。

如果一切顺利，你会在扩展程序列表里看到“BrowserForce”扩展，并且浏览器工具栏会出现一个灰色的BrowserForce图标。灰色表示扩展已加载但尚未连接到中继服务器。

注意事项：更新后的重载每次你通过npm update -g browserforce更新BrowserForce后，必须重新运行browserforce install-extension命令，然后在chrome://extensions/页面找到BrowserForce扩展，点击其卡片下方的“刷新”图标（↻）。这是因为扩展程序代码可能已更新，需要加载新版本。

3.3 连接你的AI代理：以Claude Desktop为例

BrowserForce通过MCP（Model Context Protocol）协议与各种AI客户端通信。MCP是一个新兴标准，旨在为AI模型提供访问工具和数据的统一方式。下面以Anthropic的Claude Desktop为例进行配置。

1. 找到配置文件：

   • macOS:~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows:%APPDATA%\Claude\claude_desktop_config.json
   • Linux:~/.config/Claude/claude_desktop_config.json

2. 编辑配置文件： 如果文件不存在，就创建它。如果已存在，在JSON结构中添加mcpServers部分。最终内容应类似如下：

{ "mcpServers": { "browserforce": { "command": "npx", "args": ["-y", "browserforce@latest", "mcp"] } } }

这段配置告诉Claude Desktop：“当你需要调用浏览器工具时，去执行npx -y browserforce@latest mcp这个命令来启动BrowserForce的MCP服务器。”

3. 重启与验证： 保存配置文件，并完全退出再重新启动Claude Desktop。重启后，当你新建一个对话时，Claude应该会提示“已连接工具”或类似信息。你可以通过一个简单的指令测试：“请用BrowserForce打开GitHub首页，并告诉我标题是什么。” 如果配置正确，Claude会生成并执行相应的JavaScript代码，并返回结果。

其他客户端的配置：

• Cursor / Windsurf / Codeium：配置文件路径通常是~/.cursor/mcp.json或类似位置，格式与上述Claude配置基本相同。
• OpenClaw：BrowserForce提供了更深度集成的命令browserforce setup openclaw，该命令会自动修改OpenClaw的配置并设置系统服务，实现开机自启。对于OpenClaw用户，这是最推荐的方式。

4. 核心功能与实操技巧

安装配置只是开始，真正发挥威力在于如何使用。BrowserForce通过两个核心的MCP工具execute和reset，将Playwright这个强大的浏览器自动化库的能力暴露给了AI。

4.1execute工具：你的自动化脚本执行器

这是最核心的工具。AI代理通过它向你的浏览器发送一段JavaScript代码，这段代码在特殊的上下文中执行，可以访问到几个预设好的关键对象。

一个典型的execute调用代码如下（这是AI模型会生成并执行的代码）：

// 示例：获取页面标题和所有链接 const page = context.pages()[0]; // 获取第一个标签页 await page.goto('https://news.ycombinator.com'); await waitForPageLoad(); // 等待页面加载完成 // 使用 snapshot() 获取轻量的页面内容摘要（推荐） const pageInfo = await snapshot(); console.log(`页面标题: ${pageInfo.title}`); // 或者，使用 evaluate 执行自定义DOM提取 const links = await page.evaluate(() => { const anchorTags = Array.from(document.querySelectorAll('a')); return anchorTags.map(a => ({ text: a.innerText.trim(), href: a.href })).slice(0, 10); }); return { title: pageInfo.title, topLinks: links };

关键对象解析：

• page: 当前活动的Playwright Page 对象。你可以用它进行导航、点击、输入等所有操作。
• context: Playwright的 BrowserContext 。通过context.pages()可以获取所有已附加的标签页，实现多标签管理。
• state: 一个在单次execute调用中持久化的对象。你可以用它来在不同步骤间传递数据。例如，第一步搜索时把结果存到state.searchResults，第二步再用来处理。
• snapshot():BrowserForce的杀手级功能。它返回一个基于浏览器无障碍树（Accessibility Tree）的页面快照。这个快照通常只有5-20KB，包含了页面的语义结构（标题、段落、按钮、链接及其文本），比动辄几百KB的截图轻量得多，非常适合让AI理解页面内容。在大多数只读场景下，应优先使用snapshot()而非screenshot()。
• waitForPageLoad(): 一个辅助函数，会等待页面导航完成并网络空闲，避免在页面加载中途进行操作。
• screenshotWithAccessibilityLabels(): 生成截图，并在图片上为可交互元素添加标签。这对于视觉调试或向用户展示“我点击了哪里”非常有用。

4.2 实战案例：构建一个多步骤数据提取工作流

假设你需要监控竞争对手的产品更新。他们的更新日志在一个需要登录的内部Confluence页面上。传统自动化工具在这里会卡在登录这一步，但BrowserForce可以轻松应对。

步骤一：导航与内容提取

// 假设你的浏览器已经登录了公司Confluence const page = context.pages()[0]; await page.goto('https://internal-wiki.company.com/space/Competitor/Release+Notes'); await waitForPageLoad(); // 使用 snapshot 获取页面结构，AI可以解析出版本列表 const snap = await snapshot(); // AI会分析snap数据，找到版本标题和日期 // 例如，它可能发现结构是 h2 > 版本号, p > 日期， ul > 更新项 // 更精确的提取：直接使用Playwright选择器 const releaseEntries = await page.evaluate(() => { const entries = []; // 假设页面结构是每个版本一个 <article class="release"> document.querySelectorAll('article.release').forEach(article => { const version = article.querySelector('h2')?.innerText; const date = article.querySelector('time')?.dateTime; const items = Array.from(article.querySelectorAll('ul li')).map(li => li.innerText); if(version) entries.push({ version, date, items }); }); return entries; }); // 将结果存入state，供后续步骤使用 state.latestReleases = releaseEntries.slice(0, 5); // 只存最新的5个 return `Found ${releaseEntries.length} release entries. Latest version is ${releaseEntries[0]?.version}.`;

步骤二：深度分析与摘要在同一个对话中，你可以继续要求AI分析提取到的数据。

// AI可以访问上一步存入的 state.latestReleases const releases = state.latestReleases; if (!releases || releases.length === 0) { return 'No release data found in state. Please run the extraction step first.'; } // 进行分析：例如，统计高频关键词 const allItems = releases.flatMap(r => r.items); const wordFrequency = {}; allItems.forEach(item => { // 简单的关键词提取逻辑（实际中AI会做得更智能） const words = item.toLowerCase().split(/\W+/); words.forEach(word => { if(word.length > 3) { // 忽略短词 wordFrequency[word] = (wordFrequency[word] || 0) + 1; } }); }); // 排序并获取Top 5关键词 const topKeywords = Object.entries(wordFrequency) .sort((a, b) => b[1] - a[1]) .slice(0, 5) .map(([word, count]) => `${word} (${count}次)`); return { summary: `分析了最近 ${releases.length} 个版本。`, latestVersion: releases[0], topKeywords: topKeywords, rawData: releases // 也可以返回原始数据供用户查看 };

通过这个流程，你无需编写复杂的爬虫或处理登录会话，AI代理就能利用你已有的浏览器会话，完成从导航、登录态保持、数据提取到智能分析的全过程。

4.3 插件系统：扩展AI的能力边界

BrowserForce的插件系统允许你为execute工具注入自定义的JavaScript函数，这些函数可以被AI像内置函数一样直接调用。这极大地扩展了自动化脚本的能力和可复用性。

安装官方插件： 例如，highlight插件可以高亮页面上的元素，对于调试或指引用户注意力非常有用。

browserforce plugin install highlight

安装后，重启你的MCP客户端（如重启Claude Desktop），之后在execute代码中就可以直接使用highlight(selector, color?)和clearHighlights()函数了。

使用插件函数：

// 在点击前高亮目标按钮，确保AI操作的是正确元素 await highlight('button[type="submit"]', 'red'); await page.click('button[type="submit"]'); await waitForPageLoad(); // 操作完成后清除高亮 await clearHighlights();

开发自己的插件： 如果你有重复使用的自定义操作，可以将其封装成插件。插件就是一个放在~/.browserforce/plugins/下的文件夹。

1. 创建文件夹：mkdir -p ~/.browserforce/plugins/my-helper
2. 创建入口文件index.js:

// ~/.browserforce/plugins/my-helper/index.js export default { name: 'my-helper', helpers: { async extractTableData(page, ctx, state, selector = 'table') { // 一个通用的表格数据提取函数 return await page.evaluate((sel) => { const table = document.querySelector(sel); if (!table) return null; const rows = Array.from(table.querySelectorAll('tr')); return rows.map(row => { const cells = Array.from(row.querySelectorAll('th, td')); return cells.map(cell => cell.innerText.trim()); }); }, selector); }, async slowScrollToBottom(page, ctx, state, delay = 100) { // 缓慢滚动到底部，用于加载懒加载内容 await page.evaluate(async (scrollDelay) => { await new Promise((resolve) => { let totalHeight = 0; const distance = 100; const timer = setInterval(() => { const scrollHeight = document.body.scrollHeight; window.scrollBy(0, distance); totalHeight += distance; if(totalHeight >= scrollHeight){ clearInterval(timer); resolve(); } }, scrollDelay); }); }, delay); } } };

3. 创建技能描述文件SKILL.md(可选，但推荐):

   # My Helper Plugin Provides custom functions for web automation. ## Helpers - `extractTableData(selector?)`: Extracts data from an HTML table. - `slowScrollToBottom(delay?)`: Scrolls page slowly to trigger lazy-loading.

4. 重启MCP服务器，你的AI代理就可以在execute中调用await extractTableData('#data-table')了。

插件系统将BrowserForce从一个“浏览器遥控器”升级为了一个“可编程的浏览器自动化平台”，你可以根据自己常年的工作流，沉淀出专属的自动化工具箱。

5. 高级配置、安全控制与故障排查

将AI引入真实浏览器，安全和控制是重中之重。BrowserForce提供了细致入微的控制选项，让你既能放手让AI工作，又能随时拉紧缰绳。

5.1 安全控制面板详解

点击浏览器工具栏中的BrowserForce扩展图标，会弹出控制面板。这里是你的指挥中心。

• 运行模式 (Auto / Manual)：

  • 自动模式：AI代理可以自由创建新标签页并进行操作。适合探索性任务或你明确知道代理需要访问新网站的场景。
  • 手动模式：AI只能操作你手动“附加”的标签页。你点击“+ Attach Current Tab”，当前标签页才会被纳入控制。这是最安全的模式，适合在Gmail、银行网站等敏感页面上进行只读操作。

• 执行模式 (Execution Mode)：

  • 并行：AI可以同时操作多个标签页。适合批量、独立的数据抓取任务（例如同时查询10个商品在不同网站的价格）。
  • 串行：AI一次只能操作一个标签页，完成后再进行下一个。适合需要严格顺序、避免交叉请求干扰的流程（如结账流程测试）。

• 并行可见性 (Parallel Visibility)：目前主要选项是foreground-tab，即AI新打开的标签页会出现在你当前的浏览器窗口中，并且保持可见。这避免了标签页在后台默默运行，让你对AI的行为有直观的感知。

• 关键限制开关：

  • 锁定URL：开启后，AI无法使当前标签页导航到其他URL。非常适合让AI分析一个固定的仪表盘页面，防止它意外跳转。
  • 禁止新建标签页：即使是在自动模式下，也禁止AI创建新标签页。只能操作现有标签页。
  • 只读模式：AI只能“看”，不能“动”。它可以获取页面快照、截图，但无法进行点击、输入、滚动等任何交互操作。这是处理敏感信息时的黄金法则。
  • 自动分离：设置一个时间（5-60分钟），标签页在闲置超过该时间后会自动从AI控制中分离。
  • 自动关闭：设置一个时间，AI创建的标签页在闲置超过该时间后会自动关闭，帮你清理“战场”。

5.2 客户端模式：多客户端与单客户端

BrowserForce的中继服务器支持两种客户端连接仲裁模式，通过环境变量BF_CLIENT_MODE控制：

• multi-client（默认）：允许多个MCP或CDP客户端同时连接。适合你同时使用Claude Desktop和命令行工具，或者进行并行研究任务。
• single-active：同一时间只允许一个活跃客户端。当这个客户端连接时，其他客户端会收到409 Conflict错误。这种模式适用于处理敏感操作（如财务交易），你需要确保绝对不会有其他AI指令干扰当前流程。

你可以在MCP服务器启动命令中指定模式：

// 在Claude Desktop配置中指定单客户端模式 { "mcpServers": { "browserforce": { "command": "env", "args": ["BF_CLIENT_MODE=single-active", "npx", "-y", "browserforce@latest", "mcp"] } } }

5.3 常见问题与排查实录

在实际使用中，你可能会遇到一些问题。以下是我踩过坑后总结的排查清单：

问题1：扩展图标一直是灰色的，AI代理无法连接。

• 检查中继服务器：在终端运行browserforce serve，确保没有报错，并且显示“Relay server listening on port 19222”。
• 检查扩展连接：点击灰色扩展图标，查看弹出窗口中的状态。它应该显示“Connected to relay”。如果显示“Disconnected”，尝试点击“Reconnect”。
• 检查防火墙/安全软件：确保没有本地防火墙规则阻止了localhost:19222端口的连接。
• 重启大法：依次重启中继服务器 (Ctrl+C然后重新browserforce serve)、刷新扩展页面、重启浏览器。

问题2：AI代理执行命令时报错，提示“无法找到页面”或“执行超时”。

• 确认标签页已附加：在手动模式下，你必须先点击“+ Attach Current Tab”。在自动模式下，AI可以自己创建标签页。
• 检查页面加载状态：在execute代码中，在关键操作（如page.click()）前加入await waitForPageLoad();或await page.waitForLoadState('networkidle');，确保页面元素已经就绪。
• 使用更稳健的选择器：避免使用易变的CSS类名或ID。优先使用角色选择器 (role=button[name="Submit"]) 或包含部分文本的选择器 (button:has-text("Save"))。
• 查看完整日志：点击扩展弹出窗口中的“View Full Logs”，可以打开一个包含所有CDP通信详细信息的页面，对于调试复杂问题至关重要。

问题3：snapshot()返回的内容不完整或缺失关键信息。

• 理解快照原理：snapshot()基于无障碍树，如果网站没有正确实现ARIA标签或语义化HTML，某些内容可能无法被捕获。
• 备用方案：对于重要的文本内容，可以结合使用page.evaluate()进行更精确的DOM查询。对于复杂的视觉布局，回退到使用screenshotWithAccessibilityLabels()。
• 等待动态内容：对于单页应用（SPA）或大量使用JavaScript渲染的内容，在调用snapshot()前，确保等待足够时间或等待特定元素出现。

问题4：更新BrowserForce后功能异常。

• 牢记更新两步曲：
  1. npm update -g browserforce
  2. browserforce install-extension（覆盖扩展文件）
  3. 在chrome://extensions/页面，找到BrowserForce扩展并点击“刷新”图标。
• 清理旧缓存：有时可以尝试删除~/.browserforce目录（注意这会清除你的插件和配置），然后重新安装。

BrowserForce代表了一种新的AI代理交互范式：不是让AI在一个封闭的沙盒中模拟世界，而是让它直接进入你真实的工作环境，成为你数字工作流的延伸。它消除了自动化中最大的摩擦——身份验证，同时通过精细的控制权交还，让你在享受便利的同时，牢牢掌握着主导权。从简单的信息查询到复杂的多步骤工作流编排，它正在重新定义我们与AI协同处理网页任务的方式。