安装

全局安装（推荐）{#global-installation-recommended}¶

安装原生 Rust 二进制文件以获得最佳性能：

npm install -g agent-browser
agent-browser install  # Download Chrome from Chrome for Testing (first time)

这是最快的选项——命令直接通过原生 Rust CLI 运行，解析开销低于毫秒级。

在 macOS 13 以下版本中，agent-browser install 会在下载 Chrome for Testing 之前停止，并打印更新 macOS 或手动安装 Chrome 的说明。通过系统设置 > 通用 > 软件更新将 macOS 更新至 13 或更高版本，或从 Google 的 Chrome 下载页面安装 Chrome。此检查在您运行 agent-browser install 时生效；上述包安装命令保持不变。如果 sw_vers -productVersion 不可用、报错退出、不返回版本，或返回格式错误的版本，agent-browser install 会报告检测错误，并在发起网络请求之前停止。

快速开始（无需安装）{#quick-start-no-install}¶

npx agent-browser install   # Download Chrome (first time only)
npx agent-browser open example.com

项目安装（本地依赖）{#project-installation-local-dependency}¶

适用于希望在 package.json 中锁定版本的项目：

npm install agent-browser
npx agent-browser install  # Download Chrome (first time)

然后通过 npx 或 package.json 脚本使用。

Homebrew（macOS）{#homebrew-macos}¶

brew install agent-browser
agent-browser install  # Download Chrome (first time)

Cargo（Rust）{#cargo-rust}¶

cargo install agent-browser
agent-browser install  # Download Chrome (first time)

从源码编译（约 2-3 分钟）。需要 Node.js 24+、pnpm 11+ 和 Rust 工具链（rustup.rs）。

从源码安装¶

git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install
pnpm build:source
pnpm link --global
agent-browser install

Windows 浏览器会话¶

无头 Chrome 在专用的 Windows 桌面上运行。这可以防止隐藏的浏览器窗口在您的桌面上留下可见矩形，包括受影响的 Chrome 150 构建。它适用于内置和自定义的 Chrome 可执行文件，以及会话中稍后创建的窗口。自动化、截图和 GPU 渲染继续通过 CDP 进行。

使用 --headed 在交互式桌面上显示 Chrome。使用扩展的会话也使用交互式桌面。Agent-browser 拥有它启动的 Chrome 进程：当守护进程退出或被强制终止时，Windows 会终止整个 Chrome 进程树。通过 --cdp 或 --auto-connect 附加的浏览器仍由外部拥有。

Linux 依赖项¶

在 Linux 上，安装系统依赖项：

agent-browser install --with-deps

如果包管理器无法安装所有必需的浏览器库，此命令将以非零状态退出。

以 root 身份运行时，此命令直接调用检测到的包管理器。对于非 root 用户，它使用 sudo。如果您不是 root 且 sudo 不可用，它会报告需要 root 权限或 sudo。

更新¶

升级到最新版本：

agent-browser upgrade

检测您的安装方式（npm、Homebrew 或 Cargo）并自动运行相应的更新命令。成功时显示版本变更，如果您已是最新版本，则会告知您。

诊断¶

doctor 诊断您的安装并自动清理过期的守护进程文件。当某些功能意外停止工作时，或在升级后运行它：

agent-browser doctor                     # Full diagnosis
agent-browser doctor --offline --quick   # Local-only, fastest (~<1s)
agent-browser doctor --fix               # Also run destructive repairs
agent-browser doctor --webgpu            # Also run a live WebGPU render probe
agent-browser doctor --json              # Structured output

它检查：

类别	检查内容
环境	CLI 版本、平台、主目录、状态和套接字目录、可用磁盘空间
Chrome	Chrome 安装路径和版本、缓存目录、Puppeteer 回退、用户数据目录和配置文件数量、可选的 `lightpanda` 引擎
守护进程	每个会话运行的守护进程、过期的 `.sock` / `.pid` / `.version` / `.stream` 文件（自动清理）、与 CLI 的版本不匹配、仪表盘进程活跃状态
配置	`~/.agent-browser/config.json`、`./agent-browser.json` 以及 `AGENT_BROWSER_CONFIG` 指定的任何文件都能解析为有效的 JSON
安全	加密密钥环境变量或 `~/.agent-browser/.encryption-key`（在 unix 上权限为 0600）、状态文件数量和期限与 `AGENT_BROWSER_STATE_EXPIRE_DAYS` 的比较、操作策略文件
提供商	用于 Browserless、Browserbase、Browser Use、Kernel、AgentCore（AWS 凭据）、Appium（用于 `--provider ios`）的环境变量，以及用于聊天的 `AI_GATEWAY_API_KEY`
网络	Chrome for Testing CDN、AI Gateway（如果已配置）以及当前选定的提供商端点的可达性（在 `--offline` 下跳过）
启动测试	生成一个临时会话，启动无头 Chrome，导航到 `about:blank`，然后关闭。测量挂钟时间（在 `--quick` 下跳过）
WebGPU 探针	通过 `--webgpu` 选择启用：使用 WebGPU 预设启动一个临时会话，通过真实的 WebGPU 渲染通道进行渲染，并对离屏回读和解码后的截图进行像素检查。添加 `--headed` 以验证有头/Xvfb 捕获路径

过期的 sidecar 文件始终会被清理。破坏性操作需通过 --fix 显式启用：

检查	`--fix` 的作用
Chrome 缺失	运行 `agent-browser install`
版本不匹配的守护进程	向每个进程发送 `close` 并清理文件
旧状态文件	删除早于 `AGENT_BROWSER_STATE_EXPIRE_DAYS`（默认 30 天）的状态文件
缺少加密密钥	在 `~/.agent-browser/.encryption-key` 生成新密钥（0600，Unix）；绝不覆盖已有密钥

如果所有检查通过，退出代码为 0（有警告也没关系）；如果任一检查失败，退出代码为 1。

自定义浏览器¶

使用自定义浏览器可执行文件，而不是内置的 Chromium：

Serverless - 使用 @sparticuz/chromium（约 50MB vs 约 684MB）
系统浏览器 - 使用现有的 Chrome 安装
自定义构建 - 使用修改过的浏览器构建版本

# Via flag
agent-browser --executable-path /path/to/chromium open example.com

# Via environment variable
AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com

Serverless 示例¶

使用 @sparticuz/chromium 或类似工具获取 Chromium 可执行文件路径，然后通过 --executable-path 或 AGENT_BROWSER_EXECUTABLE_PATH 传入。

例如，在 AWS Lambda 处理函数中：

import chromium from "@sparticuz/chromium";
import { execSync } from "child_process";

export async function handler() {
  const executablePath = await chromium.executablePath();
  const result = execSync(
    `AGENT_BROWSER_EXECUTABLE_PATH=${executablePath} agent-browser open https://example.com && agent-browser snapshot -i --json`,
    { encoding: "utf-8" }
  );
  return JSON.parse(result);
}

AI 智能体设置¶

agent-browser 可与任何 AI 智能体开箱即用地配合使用。如需更丰富的上下文：

AI 编码助手（推荐）¶

为你的 AI 编码助手安装技能：

npx skills add vercel-labs/agent-browser

它适用于 Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、Goose、OpenCode 和 Windsurf。该技能从仓库获取，并会自动保持最新。

不要从 node_modules 复制 SKILL.md ——随着新功能的增加，它会变得过时。请始终使用 npx skills add，或引用仓库版本。

AGENTS.md / CLAUDE.md¶

将以下内容添加到你的指令文件中：

## Browser Automation

Use `agent-browser` for web automation. Run `agent-browser --help` for all commands.

Core workflow:
1. `agent-browser open <url>` - Navigate to page
2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
4. Re-snapshot after page changes

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 agen/agent-browser