Back to Details

agent-browser-helper

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

agent-browser-helper

agent-browser-helper

Manages a local Chrome instance with anti-detection parameters and persistent profiles. After starting Chrome, use the agent-browser skill to operate it.
通过带有反检测参数和持久化配置文件的本地Chrome实例进行管理。启动Chrome后，使用agent-browser技能对其进行操作。

Prerequisites

前提条件

  • agent-browser skill: 
    npx skills add vercel-labs/agent-browser@agent-browser -g -y
  • agent-browser CLI: 
    npm i -g agent-browser && agent-browser install
  • Google Chrome or Chromium installed
IMPORTANT: The agent-browser skill must be installed for the AI agent to know how to operate the browser. Without it, the agent has no command reference and will guess incorrectly. Check 
chrome.sh start
output — if it shows a warning about missing skill, install it first.
  • agent-browser技能：
    npx skills add vercel-labs/agent-browser@agent-browser -g -y
  • agent-browser CLI：
    npm i -g agent-browser && agent-browser install
  • 已安装Google Chrome或Chromium
重要提示： 必须安装agent-browser skill，AI Agent才能知晓如何操作浏览器。如果没有该技能，Agent将没有命令参考，会做出错误的猜测。请检查
chrome.sh start
的输出——如果显示缺少skill的警告，请先安装它。

Workflow

工作流程

Step 1: Start Chrome

步骤1：启动Chrome

bash
bash $SCRIPTS/chrome.sh start
Output example:
json
{"status":"started","pid":12345,"cdpPort":9222,"profile":"default","userDataDir":"~/.agent-browser-helper/default/user-data"}
Read the output carefully — it tells you the CDP port and which profile is active. The profile's user-data-dir persists login state across sessions.
bash
bash $SCRIPTS/chrome.sh start
输出示例：
json
{"status":"started","pid":12345,"cdpPort":9222,"profile":"default","userDataDir":"~/.agent-browser-helper/default/user-data"}
请仔细阅读输出内容——它会告知你CDP端口以及当前激活的配置文件。配置文件的user-data-dir会在会话之间保留登录状态。

Step 2: Load agent-browser documentation

步骤2：加载agent-browser文档

MUST DO before running any agent-browser command. Run:
bash
agent-browser skills get core
This outputs the correct command syntax. Do NOT guess commands — they use non-standard conventions (e.g., 
open
not 
navigate
, positional args not 
--url
flags). If this command fails, the CLI is not installed.
在运行任何agent-browser命令之前必须执行此操作。运行：
bash
agent-browser skills get core
此命令会输出正确的命令语法。请勿猜测命令——它们使用非标准约定（例如使用
open
而非
navigate
，使用位置参数而非
--url
标志）。如果此命令执行失败，说明CLI未安装。

Step 3: Operate via agent-browser

步骤3：通过agent-browser进行操作

Connect using the CDP port from Step 1:
bash
agent-browser open <url> --cdp 9222
All subsequent commands in the same session inherit the CDP connection.
使用步骤1中的CDP端口建立连接：
bash
agent-browser open <url> --cdp 9222
同一会话中的所有后续命令都会继承该CDP连接。

Commands

命令

$SCRIPTS
= this skill's 
scripts/
absolute path.
$SCRIPTS
= 此skill的
scripts/
绝对路径。

start

start

bash
bash $SCRIPTS/chrome.sh start                    # default profile, headed, port 9222
bash $SCRIPTS/chrome.sh start --profile work     # named profile (isolated user-data)
bash $SCRIPTS/chrome.sh start --headless         # headless (default is HEADED)
bash $SCRIPTS/chrome.sh start --port 9333        # custom CDP port
bash
bash $SCRIPTS/chrome.sh start                    # 默认配置文件，有界面，端口9222
bash $SCRIPTS/chrome.sh start --profile work     # 命名配置文件（独立的用户数据）
bash $SCRIPTS/chrome.sh start --headless         # 无头模式（默认是有界面模式）
bash $SCRIPTS/chrome.sh start --port 9333        # 自定义CDP端口

stop

stop

bash
bash $SCRIPTS/chrome.sh stop
bash $SCRIPTS/chrome.sh stop --profile work
bash
bash $SCRIPTS/chrome.sh stop
bash $SCRIPTS/chrome.sh stop --profile work

status

status

bash
bash $SCRIPTS/chrome.sh status
bash
bash $SCRIPTS/chrome.sh status

Profile system

配置文件系统

Each profile has its own isolated user-data directory: 
~/.agent-browser-helper/{profile}/user-data
This means:
  • Cookies, localStorage, sessions persist across browser restarts
  • Extensions installed in a profile stay installed
  • Login state survives — no need to re-authenticate every time
  • Different profiles are fully isolated (different ports, different data)
When to use named profiles:
  • --profile xiaohongshu
    — keep XHS login separate
  • --profile work
    — corporate SSO sessions
  • --profile clean
    — fresh profile for testing
Important: If the user has previously logged into a site, remind them which profile contains that session. Don't start a new unnamed profile and lose their login state.
每个配置文件都有自己独立的用户数据目录： 
~/.agent-browser-helper/{profile}/user-data
这意味着：
  • Cookie、localStorage、会话会在浏览器重启后保留
  • 配置文件中安装的扩展会保持安装状态
  • 登录状态会保留——无需每次重新验证
  • 不同的配置文件完全独立（不同的端口，不同的数据）
何时使用命名配置文件：
  • --profile xiaohongshu
    — 保留小红书的独立登录状态
  • --profile work
    — 企业SSO会话
  • --profile clean
    — 用于测试的全新配置文件
重要提示： 如果用户之前已登录某个网站，请提醒他们哪个配置文件包含该会话。不要启动新的未命名配置文件，以免丢失登录状态。

Configuration

配置

Edit 
config.json
in the skill directory:
json
{
  "browser": {
    "headless": false,
    "noSandbox": true,
    "defaultProfile": "default",
    "extraArgs": [
      "--disable-blink-features=AutomationControlled",
      "--disable-infobars",
      "--window-size=1280,720"
    ],
    "profiles": {
      "default": { "cdpPort": 9222 }
    }
  }
}
编辑skill目录下的
config.json
：
json
{
  "browser": {
    "headless": false,
    "noSandbox": true,
    "defaultProfile": "default",
    "extraArgs": [
      "--disable-blink-features=AutomationControlled",
      "--disable-infobars",
      "--window-size=1280,720"
    ],
    "profiles": {
      "default": { "cdpPort": 9222 }
    }
  }
}

Profile options

配置文件选项

FieldDescriptionDefault
cdpPort
CDP debugging port9222
userDataDir
Custom user data directory
~/.agent-browser-helper/{profile}/user-data
字段描述默认值
cdpPort
CDP调试端口9222
userDataDir
自定义用户数据目录
~/.agent-browser-helper/{profile}/user-data

extraArgs for anti-detection

用于反检测的extraArgs参数

ArgPurposeDefault
--disable-blink-features=AutomationControlled
Hide 
navigator.webdriver
✅ on
--disable-infobars
Remove automation info bar✅ on
--window-size=1280,720
Normal viewport (avoids 800x600 fingerprint)✅ on
--proxy-server=http://HOST:PORT
HTTP proxyoff
--lang=zh-CN
Browser languageoff
--user-agent=...
Custom User-Agentoff
参数用途默认状态
--disable-blink-features=AutomationControlled
隐藏
navigator.webdriver
✅ 开启
--disable-infobars
移除自动化信息栏✅ 开启
--window-size=1280,720
标准视口（避免800x600的指纹特征）✅ 开启
--proxy-server=http://HOST:PORT
HTTP代理关闭
--lang=zh-CN
浏览器语言关闭
--user-agent=...
自定义User-Agent关闭

Anti-detection defaults

反检测默认设置

Out of the box, this skill applies:
  1. No 
    --enable-automation
     — 
    navigator.webdriver
    returns 
    undefined
  2. --disable-blink-features=AutomationControlled
     — removes CDP automation markers
  3. --disable-infobars
     — no "Chrome is being controlled" banner
  4. --window-size=1280,720
     — normal desktop viewport
  5. Headed mode — headless browsers have distinct fingerprints
  6. Persistent profile — real cookies/history make the browser look "lived-in"
  7. No Playwright/Puppeteer in launch path — no extra automation flags injected
For sites with aggressive detection (Cloudflare, DataDome), consider also adding a real User-Agent string and proxy to 
extraArgs
.
开箱即用，此skill会应用以下设置：
  1. 不添加
    --enable-automation
     — 
    navigator.webdriver
    返回
    undefined
  2. --disable-blink-features=AutomationControlled
     — 移除CDP自动化标记
  3. --disable-infobars
     — 无“Chrome正被控制”提示横幅
  4. --window-size=1280,720
     — 标准桌面视口
  5. 有界面模式 — 无头浏览器具有独特的指纹特征
  6. 持久化配置文件 — 真实的Cookie/历史记录让浏览器看起来“经常使用”
  7. 启动路径中无Playwright/Puppeteer — 不会注入额外的自动化标志
对于检测严格的网站（如Cloudflare、DataDome），建议在
extraArgs
中添加真实的User-Agent字符串和代理。