open-web-bridge 是一个让 AI 代理（Agent）能够直接控制和操作您本地 Chrome 浏览器的工具。它的核心价值在于，AI 可以利用您已登录的会话、指纹和身份来完成需要认证的任务。

它的“部署”本质上是在您的电脑上安装一个命令行工具和一个浏览器扩展，从而在 AI 和您的浏览器之间建立一座桥梁。下面为您提供一份详细的安装与配置指南。

🚀 快速安装指南

整个安装过程主要通过命令行完成，但最关键的一步（安装浏览器扩展）需要您手动操作。

第 1 步：安装 Node.js 环境

open-web-bridge 需要 Node.js 18 或更高版本。您可以在终端中运行以下命令检查版本：

1
node --version

如果未安装或版本过低，请从 Node.js 官网 下载安装。

第 2 步：全局安装 open-web-bridge

在终端中执行以下命令，这会同时安装命令行工具 (CLI)、浏览器扩展文件和 AI 技能文件：

1
npm install -g open-web-bridge

第 3 步：运行设置向导（关键步骤）

执行设置命令，它会引导您完成最重要的手动步骤：

1
owb setup
  • 该命令会打印出浏览器扩展的安装路径。
  • 您需要手动完成的操作：
    1. 打开您的 Chrome 或 Edge 浏览器。
    2. 在地址栏输入 chrome://extensions/ (或 edge://extensions/) 并回车。
    3. 开启右上角的 “开发者模式”。
    4. 点击 “加载已解压的扩展程序”，然后选择 owb setup 命令输出的那个文件夹路径。
  • 这是 唯一必须手动完成的步骤，因为扩展必须安装在您真实使用的、保存了登录会话的浏览器中。

第 4 步：验证安装

运行以下命令进行自检，确保 daemon（守护进程）和浏览器扩展已成功连接：

1
owb

如果输出中显示两个 ✓ 对勾，说明一切就绪。

第 5 步：为您的 AI 代理安装技能（可选但推荐）

为了让您的 AI 代理（如 Claude Code、Codex 等）更好地理解如何使用 open-web-bridge，可以安装专用的技能包：

1
owb skill install

它会自动检测并安装到它支持的多种 AI 工具中。

🤖 如何使用

安装完成后，您可以在终端中直接使用 owb 命令控制浏览器，或者让您的 AI 代理代劳。

  • 手动控制示例：

    1
    2
    3
    4
    owb open https://github.com     # 在浏览器中打开网址
    owb page                        # 获取当前页面的语义快照
    owb click @e3                   # 点击页面上编号为 @e3 的元素
    owb help                        # 查看所有支持的命令

  • 让 AI 代理执行任务：安装技能后，您只需在 AI 对话中提出需求，例如：

    “打开 Hacker News 并总结排名前三的故事。”

🌐 可选高级功能：中继模式 (Relay Mode)

如果您希望远程的 AI 代理也能控制您本地电脑上的浏览器，可以启用此模式。它通过 Cloudflare Workers 作为中继，无需暴露您电脑的端口。

安全提示：中继模式没有端到端加密，中继服务器能看见所有流量（包括 Cookie）。建议您在完全信任的 Cloudflare 账户下部署自己的中继服务，或仅在受信网络中使用。

  1. 部署自己的中继服务 (一次性)：

    1
    2
    3
    4
    cd owb-relay
    npm install
    npx wrangler login          # 授权 Cloudflare 账号
    npx wrangler deploy         # 部署，会输出一个 wss:// 开头的中继地址

  2. 配置扩展：点击浏览器工具栏中的扩展图标，切换到 Relay 标签页，填入中继地址，点击 Generate 生成令牌，然后 Save and reconnect。

  3. 配置 Daemon：在运行 owb 命令的终端中，设置环境变量并启动 daemon（需先停止本地模式的 daemon）：

    1
    2
    3
    export OWB_RELAY_URL="wss://你的中继地址.workers.dev"
    export OWB_RELAY_TOKEN="你在扩展中生成的令牌"
    owb-daemon

⚠️ 安全模型须知

在使用前，请务必理解其安全设计：

  • 本地模式 (默认)：daemon 只监听 127.0.0.1（本机）。任何运行在您电脑上的进程都可以连接它，因此不要在多用户或共享机器上运行。
  • 扩展权限：扩展需要 debugger 和 <all_urls> 权限才能控制浏览器和读取页面内容，这是技术上的必要要求，但它只能被您本地的 daemon 调用。
  • 数据存储：保存的会话状态（如 Cookies）存储在您电脑的 work/states/ 目录下，请确保此目录的安全。

💎 总结

open-web-bridge 是一个强大的“浏览器驱动”工具，但它的“部署”更像是一个本地开发工具的配置。核心在于正确安装并连接 CLI 和 浏览器扩展。一旦配置完成，您就可以让自己的 AI 代理像人一样操作浏览器，完成各种复杂的网络任务。