安装#

全局安装（推荐）#

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

bash

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

这是最快的方式。命令会直接通过原生 Rust CLI 运行，解析开销低于 1 毫秒。

快速开始（无需安装）#

bash

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

项目安装（本地依赖）#

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

bash

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

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

Homebrew（macOS）#

bash

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

Cargo（Rust）#

bash

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

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

从源码安装#

bash

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

Linux 依赖#

在 Linux 上，安装系统依赖：

bash

agent-browser install --with-deps

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

更新#

升级到最新版本：

bash

agent-browser upgrade

会自动检测你的安装方式（npm、Homebrew 或 Cargo）并执行相应的更新命令。成功后会显示版本变化；如果你已经是最新版本，也会提示。

Doctor#

doctor 会诊断你的安装并自动清理过期的守护进程文件。每当某些功能意外失效时，或者升级之后，都可以运行它：

bash

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 --json              # Structured output

它会检查：

Category	What it checks
Environment	CLI version, platform, home directory, state and socket dirs, free disk space
Chrome	Chrome install path and version, cache dir, Puppeteer fallback, user-data dir and profile count, optional `lightpanda` engine
Daemons	Running daemons per session, stale `.sock` / `.pid` / `.version` / `.stream` files (auto-cleaned), version mismatch with the CLI, dashboard process liveness
Config	`~/.agent-browser/config.json`, `./agent-browser.json`, and any file at `AGENT_BROWSER_CONFIG` parse as valid JSON
Security	Encryption key env var or `~/.agent-browser/.encryption-key` (with 0600 permissions on unix), state file count and age vs `AGENT_BROWSER_STATE_EXPIRE_DAYS`, action policy file
Providers	Env vars for Browserless, Browserbase, Browser Use, Kernel, AgentCore (AWS creds), Appium (for `--provider ios`), and `AI_GATEWAY_API_KEY` for chat
Network	Reachability of the Chrome for Testing CDN, AI Gateway (if configured), and any currently selected provider endpoint (skipped under `--offline`)
Launch test	Spawns a scratch session, launches headless Chrome, navigates to `about:blank`, then closes. Measures wall time (skipped under `--quick`)

Stale sidecar files are always cleaned. Destructive actions are opt-in via --fix:

Check	What `--fix` does
Chrome missing	Runs `agent-browser install`
Version-mismatched daemons	Sends `close` to each and cleans files
Old state files	Deletes state files older than `AGENT_BROWSER_STATE_EXPIRE_DAYS` (default 30)
Missing encryption key	Generates a new key at `~/.agent-browser/.encryption-key` (0600, unix); never overwrites an existing key

如果所有检查都通过（警告不算失败），退出码为 0；如果有任一项失败，则为 1。

自定义浏览器#

使用自定义浏览器可执行文件来替代内置 Chromium：

Serverless - 使用 @sparticuz/chromium（约 50MB，对比约 684MB）
System browser - 使用现有的 Chrome 安装
Custom builds - 使用修改过的浏览器构建版本

bash

# 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 传入。

AI 代理设置#

agent-browser 可以直接与任何 AI 代理协同工作。若要获得更丰富的上下文：

AI 编码助手（推荐）#

为你的 AI 编码助手安装对应 skill：

bash

npx skills add vercel-labs/agent-browser

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

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

AGENTS.md / CLAUDE.md#

添加到你的指令文件中：

markdown

## Browser Automation

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

核心工作流：
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