Back to Details

browser-use

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

使用浏览器使用的CLI实现浏览器自动化

使用browser-use CLI实现浏览器自动化

The 
browser-use
command provides fast, persistent browser automation. It maintains browser sessions across commands, enabling complex multi-step workflows.
browser-use
命令可实现快速、持久的浏览器自动化。它能在多个命令间维持浏览器会话，支持复杂的多步骤工作流。

Prerequisites

前提条件

Before using this skill, 
browser-use
must be installed and configured. Run diagnostics to verify:
bash
browser-use doctor
For more information, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md
使用此技能前，必须安装并配置 
browser-use
。运行诊断命令以验证：
bash
browser-use doctor
如需了解更多信息，请查看：https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md

Core Workflow

核心工作流

  1. Navigate: 
    browser-use open <url>
    - Opens URL (starts browser if needed)
  2. Inspect: 
    browser-use state
    - Returns clickable elements with indices
  3. Interact: Use indices from state to interact (
    browser-use click 5
    , 
    browser-use input 3 "text"
    )
  4. Verify: 
    browser-use state
    or 
    browser-use screenshot
    to confirm actions
  5. Repeat: Browser stays open between commands
  1. 导航：
    browser-use open <url>
    - 打开指定URL（如需则启动浏览器）
  2. 检查：
    browser-use state
    - 返回可点击元素及其索引
  3. 交互：使用state命令返回的索引进行交互（如 
    browser-use click 5
    、
    browser-use input 3 "text"
    ）
  4. 验证：通过 
    browser-use state
    或 
    browser-use screenshot
    确认操作结果
  5. 重复操作：浏览器会在命令之间保持打开状态

Browser Modes

浏览器模式

bash
browser-use --browser chromium open <url>      # Default: headless Chromium
browser-use --browser chromium --headed open <url>  # Visible Chromium window
browser-use --browser real open <url>          # Real Chrome (no profile = fresh)
browser-use --browser real --profile "Default" open <url>  # Real Chrome with your login sessions
browser-use --browser remote open <url>        # Cloud browser
  • chromium: Fast, isolated, headless by default
  • real: Uses a real Chrome binary. Without 
    --profile
    , uses a persistent but empty CLI profile at 
    ~/.config/browseruse/profiles/cli/
    . With 
    --profile "ProfileName"
    , copies your actual Chrome profile (cookies, logins, extensions)
  • remote: Cloud-hosted browser with proxy support
bash
browser-use --browser chromium open <url>      # 默认：无头模式Chromium
browser-use --browser chromium --headed open <url>  # 可见的Chromium窗口
browser-use --browser real open <url>          # 真实Chrome浏览器（无配置文件则为全新会话）
browser-use --browser real --profile "Default" open <url>  # 使用您的登录会话的真实Chrome浏览器
browser-use --browser remote open <url>        # 云端浏览器
  • chromium：快速、隔离，默认无头模式
  • real：使用真实Chrome二进制文件。若未指定
    --profile
    ，则使用位于 
    ~/.config/browseruse/profiles/cli/
    的持久化但空白的CLI配置文件。若指定
    --profile "ProfileName"
    ，则复制您实际的Chrome配置文件（包含Cookie、登录信息、扩展程序）
  • remote：支持代理的云端托管浏览器

Essential Commands

核心命令

bash
undefined
bash
undefined

Navigation

导航

browser-use open <url> # Navigate to URL browser-use back # Go back browser-use scroll down # Scroll down (--amount N for pixels)
browser-use open <url> # 导航至指定URL browser-use back # 返回上一页 browser-use scroll down # 向下滚动（使用--amount N指定像素数）

Page State (always run state first to get element indices)

页面状态（请先运行state命令获取元素索引）

browser-use state # Get URL, title, clickable elements browser-use screenshot # Take screenshot (base64) browser-use screenshot path.png # Save screenshot to file
browser-use state # 获取URL、标题和可点击元素 browser-use screenshot # 截取屏幕截图（返回base64格式） browser-use screenshot path.png # 将屏幕截图保存至指定文件

Interactions (use indices from state)

交互操作（使用state命令返回的索引）

browser-use click <index> # Click element browser-use type "text" # Type into focused element browser-use input <index> "text" # Click element, then type browser-use keys "Enter" # Send keyboard keys browser-use select <index> "option" # Select dropdown option
browser-use click <index> # 点击指定元素 browser-use type "text" # 在焦点元素中输入文本 browser-use input <index> "text" # 点击元素后输入文本 browser-use keys "Enter" # 发送键盘按键 browser-use select <index> "option" # 选择下拉菜单选项

Data Extraction

数据提取

browser-use eval "document.title" # Execute JavaScript browser-use get text <index> # Get element text browser-use get html --selector "h1" # Get scoped HTML
browser-use eval "document.title" # 执行JavaScript代码 browser-use get text <index> # 获取元素文本内容 browser-use get html --selector "h1" # 获取指定选择器的HTML内容

Wait

等待操作

browser-use wait selector "h1" # Wait for element browser-use wait text "Success" # Wait for text
browser-use wait selector "h1" # 等待元素出现 browser-use wait text "Success" # 等待文本出现

Session

会话管理

browser-use sessions # List active sessions browser-use close # Close current session browser-use close --all # Close all sessions
browser-use sessions # 列出所有活跃会话 browser-use close # 关闭当前会话 browser-use close --all # 关闭所有会话

AI Agent

AI Agent

browser-use -b remote run "task" # Run agent in cloud (async by default) browser-use task status <id> # Check cloud task progress
undefined
browser-use -b remote run "task" # 在云端运行Agent（默认异步执行） browser-use task status <id> # 检查云端任务进度
undefined

Commands

命令详情

Navigation & Tabs

导航与标签页

bash
browser-use open <url>                    # Navigate to URL
browser-use back                          # Go back in history
browser-use scroll down                   # Scroll down
browser-use scroll up                     # Scroll up
browser-use scroll down --amount 1000     # Scroll by specific pixels (default: 500)
browser-use switch <tab>                  # Switch to tab by index
browser-use close-tab                     # Close current tab
browser-use close-tab <tab>              # Close specific tab
bash
browser-use open <url>                    # 导航至指定URL
browser-use back                          # 返回历史记录上一页
browser-use scroll down                   # 向下滚动
browser-use scroll up                     # 向上滚动
browser-use scroll down --amount 1000     # 滚动指定像素数（默认：500）
browser-use switch <tab>                  # 通过索引切换标签页
browser-use close-tab                     # 关闭当前标签页
browser-use close-tab <tab>              # 关闭指定索引的标签页

Page State

页面状态

bash
browser-use state                         # Get URL, title, and clickable elements
browser-use screenshot                    # Take screenshot (outputs base64)
browser-use screenshot path.png           # Save screenshot to file
browser-use screenshot --full path.png    # Full page screenshot
bash
browser-use state                         # 获取URL、标题和可点击元素
browser-use screenshot                    # 截取屏幕截图（输出base64格式）
browser-use screenshot path.png           # 将屏幕截图保存至指定文件
browser-use screenshot --full path.png    # 截取整页屏幕截图

Interactions

交互操作

bash
browser-use click <index>                 # Click element
browser-use type "text"                   # Type text into focused element
browser-use input <index> "text"          # Click element, then type text
browser-use keys "Enter"                  # Send keyboard keys
browser-use keys "Control+a"              # Send key combination
browser-use select <index> "option"       # Select dropdown option
browser-use hover <index>                 # Hover over element (triggers CSS :hover)
browser-use dblclick <index>              # Double-click element
browser-use rightclick <index>            # Right-click element (context menu)
Use indices from 
browser-use state
.
bash
browser-use click <index>                 # 点击指定元素
browser-use type "text"                   # 在焦点元素中输入文本
browser-use input <index> "text"          # 点击元素后输入文本
browser-use keys "Enter"                  # 发送键盘按键
browser-use keys "Control+a"              # 发送组合按键
browser-use select <index> "option"       # 选择下拉菜单选项
browser-use hover <index>                 # 悬停在元素上（触发CSS :hover效果）
browser-use dblclick <index>              # 双击元素
browser-use rightclick <index>            # 右键点击元素（打开上下文菜单）
请使用
browser-use state
命令返回的索引进行操作。

JavaScript & Data

JavaScript与数据处理

bash
browser-use eval "document.title"         # Execute JavaScript, return result
browser-use get title                     # Get page title
browser-use get html                      # Get full page HTML
browser-use get html --selector "h1"      # Get HTML of specific element
browser-use get text <index>              # Get text content of element
browser-use get value <index>             # Get value of input/textarea
browser-use get attributes <index>        # Get all attributes of element
browser-use get bbox <index>              # Get bounding box (x, y, width, height)
bash
browser-use eval "document.title"         # 执行JavaScript代码并返回结果
browser-use get title                     # 获取页面标题
browser-use get html                      # 获取完整页面HTML
browser-use get html --selector "h1"      # 获取指定选择器的元素HTML
browser-use get text <index>              # 获取元素文本内容
browser-use get value <index>             # 获取输入框/文本域的值
browser-use get attributes <index>        # 获取元素的所有属性
browser-use get bbox <index>              # 获取元素的边界框（x、y、宽度、高度）

Cookies

Cookie管理

bash
browser-use cookies get                   # Get all cookies
browser-use cookies get --url <url>       # Get cookies for specific URL
browser-use cookies set <name> <value>    # Set a cookie
browser-use cookies set name val --domain .example.com --secure --http-only
browser-use cookies set name val --same-site Strict  # SameSite: Strict, Lax, or None
browser-use cookies set name val --expires 1735689600  # Expiration timestamp
browser-use cookies clear                 # Clear all cookies
browser-use cookies clear --url <url>     # Clear cookies for specific URL
browser-use cookies export <file>         # Export all cookies to JSON file
browser-use cookies export <file> --url <url>  # Export cookies for specific URL
browser-use cookies import <file>         # Import cookies from JSON file
bash
browser-use cookies get                   # 获取所有Cookie
browser-use cookies get --url <url>       # 获取指定URL的Cookie
browser-use cookies set <name> <value>    # 设置Cookie
browser-use cookies set name val --domain .example.com --secure --http-only
browser-use cookies set name val --same-site Strict  # SameSite属性：Strict、Lax或None
browser-use cookies set name val --expires 1735689600  # 过期时间戳
browser-use cookies clear                 # 清除所有Cookie
browser-use cookies clear --url <url>     # 清除指定URL的Cookie
browser-use cookies export <file>         # 将所有Cookie导出至JSON文件
browser-use cookies export <file> --url <url>  # 导出指定URL的Cookie至JSON文件
browser-use cookies import <file>         # 从JSON文件导入Cookie

Wait Conditions

等待条件

bash
browser-use wait selector "h1"            # Wait for element to be visible
browser-use wait selector ".loading" --state hidden  # Wait for element to disappear
browser-use wait selector "#btn" --state attached    # Wait for element in DOM
browser-use wait text "Success"           # Wait for text to appear
browser-use wait selector "h1" --timeout 5000  # Custom timeout in ms
bash
browser-use wait selector "h1"            # 等待元素可见
browser-use wait selector ".loading" --state hidden  # 等待元素消失
browser-use wait selector "#btn" --state attached    # 等待元素加入DOM
browser-use wait text "Success"           # 等待文本出现
browser-use wait selector "h1" --timeout 5000  # 自定义超时时间（毫秒）

Python Execution

Python执行

bash
browser-use python "x = 42"               # Set variable
browser-use python "print(x)"             # Access variable (outputs: 42)
browser-use python "print(browser.url)"   # Access browser object
browser-use python --vars                 # Show defined variables
browser-use python --reset                # Clear Python namespace
browser-use python --file script.py       # Execute Python file
The Python session maintains state across commands. The 
browser
object provides:
  • browser.url
    , 
    browser.title
    , 
    browser.html
    — page info
  • browser.goto(url)
    , 
    browser.back()
    — navigation
  • browser.click(index)
    , 
    browser.type(text)
    , 
    browser.input(index, text)
    , 
    browser.keys(keys)
    — interactions
  • browser.screenshot(path)
    , 
    browser.scroll(direction, amount)
    — visual
  • browser.wait(seconds)
    , 
    browser.extract(query)
    — utilities
bash
browser-use python "x = 42"               # 设置变量
browser-use python "print(x)"             # 访问变量（输出：42）
browser-use python "print(browser.url)"   # 访问browser对象
browser-use python --vars                 # 显示已定义的变量
browser-use python --reset                # 清除Python命名空间
browser-use python --file script.py       # 执行Python文件
Python会话会在命令之间维持状态。
browser
对象提供以下功能：
  • browser.url
    、
    browser.title
    、
    browser.html
    — 页面信息
  • browser.goto(url)
    、
    browser.back()
    — 导航操作
  • browser.click(index)
    、
    browser.type(text)
    、
    browser.input(index, text)
    、
    browser.keys(keys)
    — 交互操作
  • browser.screenshot(path)
    、
    browser.scroll(direction, amount)
    — 可视化操作
  • browser.wait(seconds)
    、
    browser.extract(query)
    — 实用工具

Agent Tasks

Agent任务

Remote Mode Options

远程模式选项

When using 
--browser remote
, additional options are available:
bash
undefined
使用
--browser remote
时，可使用以下额外选项：
bash
undefined

Specify LLM model

指定LLM模型

browser-use -b remote run "task" --llm gpt-4o browser-use -b remote run "task" --llm claude-sonnet-4-20250514
browser-use -b remote run "task" --llm gpt-4o browser-use -b remote run "task" --llm claude-sonnet-4-20250514

Proxy configuration (default: us)

代理配置（默认：美国）

browser-use -b remote run "task" --proxy-country uk
browser-use -b remote run "task" --proxy-country uk

Session reuse

会话复用

browser-use -b remote run "task 1" --keep-alive # Keep session alive after task browser-use -b remote run "task 2" --session-id abc-123 # Reuse existing session
browser-use -b remote run "task 1" --keep-alive # 任务完成后保持会话活跃 browser-use -b remote run "task 2" --session-id abc-123 # 复用现有会话

Execution modes

执行模式

browser-use -b remote run "task" --flash # Fast execution mode browser-use -b remote run "task" --wait # Wait for completion (default: async)
browser-use -b remote run "task" --flash # 快速执行模式 browser-use -b remote run "task" --wait # 等待任务完成（默认：异步）

Advanced options

高级选项

browser-use -b remote run "task" --thinking # Extended reasoning mode browser-use -b remote run "task" --no-vision # Disable vision (enabled by default)
browser-use -b remote run "task" --thinking # 扩展推理模式 browser-use -b remote run "task" --no-vision # 禁用视觉功能（默认启用）

Using a cloud profile (create session first, then run with --session-id)

使用云端配置文件（先创建会话，再使用--session-id运行任务）

browser-use session create --profile <cloud-profile-id> --keep-alive
browser-use session create --profile <cloud-profile-id> --keep-alive

→ returns session_id

→ 返回session_id

browser-use -b remote run "task" --session-id <session-id>
browser-use -b remote run "task" --session-id <session-id>

Task configuration

任务配置

browser-use -b remote run "task" --start-url https://example.com # Start from specific URL browser-use -b remote run "task" --allowed-domain example.com # Restrict navigation (repeatable) browser-use -b remote run "task" --metadata key=value # Task metadata (repeatable) browser-use -b remote run "task" --skill-id skill-123 # Enable skills (repeatable) browser-use -b remote run "task" --secret key=value # Secret metadata (repeatable)
browser-use -b remote run "task" --start-url https://example.com # 从指定URL开始 browser-use -b remote run "task" --allowed-domain example.com # 限制导航域名（可重复指定） browser-use -b remote run "task" --metadata key=value # 任务元数据（可重复指定） browser-use -b remote run "task" --skill-id skill-123 # 启用技能（可重复指定） browser-use -b remote run "task" --secret key=value # 保密元数据（可重复指定）

Structured output and evaluation

结构化输出与评估

browser-use -b remote run "task" --structured-output '{"type":"object"}' # JSON schema for output browser-use -b remote run "task" --judge # Enable judge mode browser-use -b remote run "task" --judge-ground-truth "expected answer"
undefined
browser-use -b remote run "task" --structured-output '{"type":"object"}' # 输出JSON schema browser-use -b remote run "task" --judge # 启用评估模式 browser-use -b remote run "task" --judge-ground-truth "expected answer"
undefined

Task Management

任务管理

bash
browser-use task list                     # List recent tasks
browser-use task list --limit 20          # Show more tasks
browser-use task list --status finished   # Filter by status (finished, stopped)
browser-use task list --session <id>      # Filter by session ID
browser-use task list --json              # JSON output

browser-use task status <task-id>         # Get task status (latest step only)
browser-use task status <task-id> -c      # All steps with reasoning
browser-use task status <task-id> -v      # All steps with URLs + actions
browser-use task status <task-id> --last 5  # Last N steps only
browser-use task status <task-id> --step 3  # Specific step number
browser-use task status <task-id> --reverse # Newest first

browser-use task stop <task-id>           # Stop a running task
browser-use task logs <task-id>           # Get task execution logs
bash
browser-use task list                     # 列出近期任务
browser-use task list --limit 20          # 显示更多任务
browser-use task list --status finished   # 按状态筛选（已完成、已停止）
browser-use task list --session <id>      # 按会话ID筛选
browser-use task list --json              # 以JSON格式输出

browser-use task status <task-id>         # 获取任务状态（仅最新步骤）
browser-use task status <task-id> -c      # 获取包含推理过程的所有步骤
browser-use task status <task-id> -v      # 获取包含URL和操作的所有步骤
browser-use task status <task-id> --last 5  # 获取最近N个步骤
browser-use task status <task-id> --step 3  # 获取指定步骤
browser-use task status <task-id> --reverse # 按最新顺序显示步骤

browser-use task stop <task-id>           # 停止运行中的任务
browser-use task logs <task-id>           # 获取任务执行日志

Cloud Session Management

云端会话管理

bash
browser-use session list                  # List cloud sessions
browser-use session list --limit 20       # Show more sessions
browser-use session list --status active  # Filter by status
browser-use session list --json           # JSON output

browser-use session get <session-id>      # Get session details + live URL
browser-use session get <session-id> --json

browser-use session stop <session-id>     # Stop a session
browser-use session stop --all            # Stop all active sessions

browser-use session create                          # Create with defaults
browser-use session create --profile <id>           # With cloud profile
browser-use session create --proxy-country uk       # With geographic proxy
browser-use session create --start-url https://example.com
browser-use session create --screen-size 1920x1080
browser-use session create --keep-alive
browser-use session create --persist-memory

browser-use session share <session-id>              # Create public share URL
browser-use session share <session-id> --delete     # Delete public share
bash
browser-use session list                  # 列出云端会话
browser-use session list --limit 20       # 显示更多会话
browser-use session list --status active  # 按状态筛选
browser-use session list --json           # 以JSON格式输出

browser-use session get <session-id>      # 获取会话详情和实时URL
browser-use session get <session-id> --json

browser-use session stop <session-id>     # 停止指定会话
browser-use session stop --all            # 停止所有活跃会话

browser-use session create                          # 使用默认设置创建会话
browser-use session create --profile <id>           # 使用云端配置文件创建会话
browser-use session create --proxy-country uk       # 使用指定地区代理创建会话
browser-use session create --start-url https://example.com
browser-use session create --screen-size 1920x1080
browser-use session create --keep-alive
browser-use session create --persist-memory

browser-use session share <session-id>              # 创建公共共享URL
browser-use session share <session-id> --delete     # 删除公共共享链接

Tunnels

隧道管理

bash
browser-use tunnel <port>           # Start tunnel (returns URL)
browser-use tunnel <port>           # Idempotent - returns existing URL
browser-use tunnel list             # Show active tunnels
browser-use tunnel stop <port>      # Stop tunnel
browser-use tunnel stop --all       # Stop all tunnels
bash
browser-use tunnel <port>           # 启动隧道（返回访问URL）
browser-use tunnel <port>           # 幂等操作 - 返回已存在的URL
browser-use tunnel list             # 显示所有活跃隧道
browser-use tunnel stop <port>      # 停止指定端口的隧道
browser-use tunnel stop --all       # 停止所有隧道

Session Management

会话管理

bash
browser-use sessions                      # List active sessions
browser-use close                         # Close current session
browser-use close --all                   # Close all sessions
bash
browser-use sessions                      # 列出所有活跃会话
browser-use close                         # 关闭当前会话
browser-use close --all                   # 关闭所有会话

Profile Management

配置文件管理

Local Chrome Profiles (
--browser real
)

本地Chrome配置文件（
--browser real
模式）

bash
browser-use -b real profile list          # List local Chrome profiles
browser-use -b real profile cookies "Default"  # Show cookie domains in profile
bash
browser-use -b real profile list          # 列出本地Chrome配置文件
browser-use -b real profile cookies "Default"  # 显示配置文件中的Cookie域名

Cloud Profiles (
--browser remote
)

云端配置文件（
--browser remote
模式）

bash
browser-use -b remote profile list            # List cloud profiles
browser-use -b remote profile list --page 2 --page-size 50
browser-use -b remote profile get <id>        # Get profile details
browser-use -b remote profile create          # Create new cloud profile
browser-use -b remote profile create --name "My Profile"
browser-use -b remote profile update <id> --name "New"
browser-use -b remote profile delete <id>
bash
browser-use -b remote profile list            # 列出云端配置文件
browser-use -b remote profile list --page 2 --page-size 50
browser-use -b remote profile get <id>        # 获取云端配置文件详情
browser-use -b remote profile create          # 创建新的云端配置文件
browser-use -b remote profile create --name "My Profile"
browser-use -b remote profile update <id> --name "New"
browser-use -b remote profile delete <id>

Syncing

同步操作

bash
browser-use profile sync --from "Default" --domain github.com  # Domain-specific
browser-use profile sync --from "Default"                      # Full profile
browser-use profile sync --from "Default" --name "Custom Name" # With custom name
bash
browser-use profile sync --from "Default" --domain github.com  # 按域名同步
browser-use profile sync --from "Default"                      # 完整配置文件同步
browser-use profile sync --from "Default" --name "Custom Name" # 使用自定义名称同步

Server Control

服务器控制

bash
browser-use server logs                   # View server logs
bash
browser-use server logs                   # 查看服务器日志

Common Workflows

常见工作流

Exposing Local Dev Servers

暴露本地开发服务器

Use when you have a local dev server and need a cloud browser to reach it.
Core workflow: Start dev server → create tunnel → browse the tunnel URL remotely.
bash
undefined
当您有本地开发服务器，需要让云端浏览器访问时使用此工作流。
核心流程：启动开发服务器 → 创建隧道 → 远程浏览隧道URL。
bash
undefined

1. Start your dev server

1. 启动本地开发服务器

npm run dev & # localhost:3000
npm run dev & # 运行在localhost:3000

2. Expose it via Cloudflare tunnel

2. 通过Cloudflare隧道暴露服务

browser-use tunnel 3000
browser-use tunnel 3000

→ url: https://abc.trycloudflare.com

→ 返回URL: https://abc.trycloudflare.com

3. Now the cloud browser can reach your local server

3. 现在云端浏览器可以访问您的本地服务器了

browser-use --browser remote open https://abc.trycloudflare.com browser-use state browser-use screenshot

**Note:** Tunnels are independent of browser sessions. They persist across `browser-use close` and can be managed separately. Cloudflared must be installed — run `browser-use doctor` to check.
browser-use --browser remote open https://abc.trycloudflare.com browser-use state browser-use screenshot

**注意**：隧道独立于浏览器会话，即使运行`browser-use close`也会保持活跃，可单独管理。必须安装Cloudflared — 运行`browser-use doctor`检查是否已安装。

Authenticated Browsing with Profiles

使用配置文件进行认证浏览

Use when a task requires browsing a site the user is already logged into (e.g. Gmail, GitHub, internal tools).
Core workflow: Check existing profiles → ask user which profile and browser mode → browse with that profile. Only sync cookies if no suitable profile exists.
Before browsing an authenticated site, the agent MUST:
  1. Ask the user whether to use real (local Chrome) or remote (cloud) browser
  2. List available profiles for that mode
  3. Ask which profile to use
  4. If no profile has the right cookies, offer to sync (see below)
当任务需要访问用户已登录的网站（如Gmail、GitHub、内部工具）时使用此工作流。
核心流程：检查现有配置文件 → 询问用户使用哪种浏览器模式和配置文件 → 使用该配置文件浏览。仅当没有合适的配置文件时才同步Cookie。
在浏览需要认证的网站前，Agent必须：
  1. 询问用户使用**real（本地Chrome）还是remote（云端）**浏览器模式
  2. 列出该模式下的可用配置文件
  3. 询问用户使用哪个配置文件
  4. 如果没有配置文件包含所需Cookie，提供同步选项（见下文）

Step 1: Check existing profiles

步骤1：检查现有配置文件

bash
undefined
bash
undefined

Option A: Local Chrome profiles (--browser real)

选项A：本地Chrome配置文件（--browser real模式）

browser-use -b real profile list
browser-use -b real profile list

→ Default: Person 1 (user@gmail.com)

→ Default: Person 1 (user@gmail.com)

→ Profile 1: Work (work@company.com)

→ Profile 1: Work (work@company.com)

Option B: Cloud profiles (--browser remote)

选项B：云端配置文件（--browser remote模式）

browser-use -b remote profile list
browser-use -b remote profile list

→ abc-123: "Chrome - Default (github.com)"

→ abc-123: "Chrome - Default (github.com)"

→ def-456: "Work profile"

→ def-456: "Work profile"

undefined
undefined

Step 2: Browse with the chosen profile

步骤2：使用选定的配置文件浏览

bash
undefined
bash
undefined

Real browser — uses local Chrome with existing login sessions

真实浏览器模式 — 使用本地Chrome的现有登录会话

browser-use --browser real --profile "Default" open https://github.com
browser-use --browser real --profile "Default" open https://github.com

Cloud browser — uses cloud profile with synced cookies

云端浏览器模式 — 使用已同步Cookie的云端配置文件

browser-use --browser remote --profile abc-123 open https://github.com

The user is already authenticated — no login needed.

**Note:** Cloud profile cookies can expire over time. If authentication fails, re-sync cookies from the local Chrome profile.
browser-use --browser remote --profile abc-123 open https://github.com

用户已处于认证状态 — 无需再次登录。

**注意**：云端配置文件的Cookie可能会过期。如果认证失败，请从本地Chrome配置文件重新同步Cookie。

Step 3: Syncing cookies (only if needed)

步骤3：同步Cookie（仅在需要时）

If the user wants to use a cloud browser but no cloud profile has the right cookies, sync them from a local Chrome profile.
Before syncing, the agent MUST:
  1. Ask which local Chrome profile to use
  2. Ask which domain(s) to sync — do NOT default to syncing the full profile
  3. Confirm before proceeding
Check what cookies a local profile has:
bash
browser-use -b real profile cookies "Default"
如果用户想使用云端浏览器，但没有云端配置文件包含所需Cookie，可从本地Chrome配置文件同步。
在同步前，Agent必须：
  1. 询问用户使用哪个本地Chrome配置文件
  2. 询问需要同步的域名 — 请勿默认同步完整配置文件
  3. 获得用户确认后再执行
检查本地配置文件包含的Cookie：
bash
browser-use -b real profile cookies "Default"

→ youtube.com: 23

→ youtube.com: 23

→ google.com: 18

→ google.com: 18

→ github.com: 2

→ github.com: 2


**Domain-specific sync (recommended):**
```bash
browser-use profile sync --from "Default" --domain github.com

**按域名同步（推荐）**：
```bash
browser-use profile sync --from "Default" --domain github.com

Creates new cloud profile: "Chrome - Default (github.com)"

创建新的云端配置文件："Chrome - Default (github.com)"

Only syncs github.com cookies

仅同步github.com的Cookie


**Full profile sync (use with caution):**
```bash
browser-use profile sync --from "Default"

**完整配置文件同步（谨慎使用）**：
```bash
browser-use profile sync --from "Default"

Syncs ALL cookies — includes sensitive data, tracking cookies, every session token

同步所有Cookie — 包含敏感数据、跟踪Cookie和所有会话令牌

Only use when the user explicitly needs their entire browser state.

**Fine-grained control (advanced):**
```bash
仅当用户明确需要完整浏览器状态时使用此方式。

**细粒度控制（高级）**：
```bash

Export cookies to file, manually edit, then import

将Cookie导出至文件，手动编辑后再导入

browser-use --browser real --profile "Default" cookies export /tmp/cookies.json browser-use --browser remote --profile <id> cookies import /tmp/cookies.json

**Use the synced profile:**
```bash
browser-use --browser remote --profile <id> open https://github.com
browser-use --browser real --profile "Default" cookies export /tmp/cookies.json browser-use --browser remote --profile <id> cookies import /tmp/cookies.json

**使用已同步的配置文件**：
```bash
browser-use --browser remote --profile <id> open https://github.com

Running Subagents

运行子Agent

Use cloud sessions to run autonomous browser agents in parallel.
Core workflow: Launch task(s) with 
run
→ poll with 
task status
→ collect results → clean up sessions.
  • Session = Agent: Each cloud session is a browser agent with its own state
  • Task = Work: Jobs given to an agent; an agent can run multiple tasks sequentially
  • Session lifecycle: Once stopped, a session cannot be revived — start a new one
使用云端会话并行运行自主浏览器Agent。
核心流程：使用
run
命令启动任务 → 使用
task status
轮询进度 → 收集结果 → 清理会话。
  • 会话 = Agent：每个云端会话是一个独立状态的浏览器Agent
  • 任务 = 工作：分配给Agent的任务；一个Agent可按顺序运行多个任务
  • 会话生命周期：会话停止后无法恢复 — 需启动新会话

Launching Tasks

启动任务

bash
undefined
bash
undefined

Single task (async by default — returns immediately)

单个任务（默认异步执行 — 立即返回）

browser-use -b remote run "Search for AI news and summarize top 3 articles"
browser-use -b remote run "搜索AI新闻并总结top3文章"

→ task_id: task-abc, session_id: sess-123

→ task_id: task-abc, session_id: sess-123

Parallel tasks — each gets its own session

并行任务 — 每个任务使用独立会话

browser-use -b remote run "Research competitor A pricing"
browser-use -b remote run "调研竞争对手A的定价"

→ task_id: task-1, session_id: sess-a

→ task_id: task-1, session_id: sess-a

browser-use -b remote run "Research competitor B pricing"
browser-use -b remote run "调研竞争对手B的定价"

→ task_id: task-2, session_id: sess-b

→ task_id: task-2, session_id: sess-b

browser-use -b remote run "Research competitor C pricing"
browser-use -b remote run "调研竞争对手C的定价"

→ task_id: task-3, session_id: sess-c

→ task_id: task-3, session_id: sess-c

Sequential tasks in same session (reuses cookies, login state, etc.)

同一会话中的顺序任务（复用Cookie、登录状态等）

browser-use -b remote run "Log into example.com" --keep-alive
browser-use -b remote run "登录example.com" --keep-alive

→ task_id: task-1, session_id: sess-123

→ task_id: task-1, session_id: sess-123

browser-use task status task-1 # Wait for completion browser-use -b remote run "Export settings" --session-id sess-123
browser-use task status task-1 # 等待任务完成 browser-use -b remote run "导出设置" --session-id sess-123

→ task_id: task-2, session_id: sess-123 (same session)

→ task_id: task-2, session_id: sess-123（同一会话）

undefined
undefined

Managing & Stopping

管理与停止任务

bash
browser-use task list --status finished      # See completed tasks
browser-use task stop task-abc               # Stop a task (session may continue if --keep-alive)
browser-use session stop sess-123            # Stop an entire session (terminates its tasks)
browser-use session stop --all               # Stop all sessions
bash
browser-use task list --status finished      # 查看已完成任务
browser-use task stop task-abc               # 停止指定任务（若使用--keep-alive，会话会继续存在）
browser-use session stop sess-123            # 停止整个会话（终止所有关联任务）
browser-use session stop --all               # 停止所有会话

Monitoring

监控任务

Task status is designed for token efficiency. Default output is minimal — only expand when needed:
ModeFlagTokensUse When
Default(none)LowPolling progress
Compact
-c
MediumNeed full reasoning
Verbose
-v
HighDebugging actions
bash
undefined
任务状态设计为高效节省Token。默认输出简洁 — 仅在需要时展开：
模式参数Token消耗使用场景
默认无低轮询进度
简洁
-c
中需要完整推理过程
详细
-v
高调试操作
bash
undefined

For long tasks (50+ steps)

长任务（50+步骤）

browser-use task status <id> -c --last 5 # Last 5 steps only browser-use task status <id> -v --step 10 # Inspect specific step

**Live view**: `browser-use session get <session-id>` returns a live URL to watch the agent.

**Detect stuck tasks**: If cost/duration in `task status` stops increasing, the task is stuck — stop it and start a new agent.

**Logs**: `browser-use task logs <task-id>` — only available after task completes.
browser-use task status <id> -c --last 5 # 仅查看最近5个步骤 browser-use task status <id> -v --step 10 # 检查指定步骤

**实时查看**：`browser-use session get <session-id>` 返回可观看Agent操作的实时URL。

**检测停滞任务**：如果`task status`中的成本/时长停止增加，说明任务已停滞 — 停止任务并启动新Agent。

**日志**：`browser-use task logs <task-id>` — 仅在任务完成后可用。

Global Options

全局选项

OptionDescription
--session NAME
Use named session (default: "default")
--browser MODE
Browser mode: chromium, real, remote
--headed
Show browser window (chromium mode)
--profile NAME
Browser profile (local name or cloud ID). Works with 
open
, 
session create
, etc. — does NOT work with 
run
(use 
--session-id
instead)
--json
Output as JSON
--mcp
Run as MCP server via stdin/stdout
Session behavior: All commands without 
--session
use the same "default" session. The browser stays open and is reused across commands. Use 
--session NAME
to run multiple browsers in parallel.
选项描述
--session NAME
使用命名会话（默认："default"）
--browser MODE
浏览器模式：chromium、real、remote
--headed
显示浏览器窗口（仅chromium模式）
--profile NAME
浏览器配置文件（本地名称或云端ID）。适用于
open
、
session create
等命令 — 不适用于
run
命令（请使用
--session-id
替代）
--json
以JSON格式输出
--mcp
通过标准输入/输出以MCP服务器模式运行
会话行为：所有未指定
--session
的命令均使用同一个"default"会话。浏览器会保持打开状态并在命令间复用。使用
--session NAME
可并行运行多个浏览器。

Tips

技巧

  1. Always run 
    browser-use state
    first     to see available elements and their indices
  2. Use 
    --headed
    for debugging     to see what the browser is doing
  3. Sessions persist — the browser stays open between commands
  4. Use 
    --json
     for programmatic parsing
  5. Python variables persist across 
    browser-use python
    commands within a session
  6. CLI aliases: 
    bu
    , 
    browser
    , and 
    browseruse
    all work identically to 
    browser-use
  1. 始终先运行
    browser-use state
    ：查看可用元素及其索引
  2. 使用
    --headed
    调试    ：查看浏览器的实际操作
  3. 会话会持久化：浏览器在命令之间保持打开状态
  4. 使用
    --json
    ：便于程序解析输出
  5. Python变量会持久化：在同一会话中，
    browser-use python
    命令间的变量会保留
  6. CLI别名：
    bu
    、
    browser
    和
    browseruse
    与
    browser-use
    功能完全相同

Troubleshooting

故障排除

Run diagnostics first:
bash
browser-use doctor
Browser won't start?
bash
browser-use close --all               # Close all sessions
browser-use --headed open <url>       # Try with visible window
Element not found?
bash
browser-use state                     # Check current elements
browser-use scroll down               # Element might be below fold
browser-use state                     # Check again
Session issues?
bash
browser-use sessions                  # Check active sessions
browser-use close --all               # Clean slate
browser-use open <url>                # Fresh start
Session reuse fails after 
task stop
: If you stop a task and try to reuse its session, the new task may get stuck at "created" status. Create a new session instead:
bash
browser-use session create --profile <profile-id> --keep-alive
browser-use -b remote run "new task" --session-id <new-session-id>
Task stuck at "started": Check cost with 
task status
— if not increasing, the task is stuck. View live URL with 
session get
, then stop and start a new agent.
Sessions persist after tasks complete: Tasks finishing doesn't auto-stop sessions. Run 
browser-use session stop --all
to clean up.
首先运行诊断：
bash
browser-use doctor
浏览器无法启动？
bash
browser-use close --all               # 关闭所有会话
browser-use --headed open <url>       # 尝试使用可见窗口启动
找不到元素？
bash
browser-use state                     # 检查当前元素列表
browser-use scroll down               # 元素可能在视图外
browser-use state                     # 再次检查
会话问题？
bash
browser-use sessions                  # 检查活跃会话
browser-use close --all               # Clean slate
browser-use open <url>                # 重新开始
停止任务后会话复用失败： 如果停止任务后尝试复用会话，新任务可能会卡在"created"状态。请创建新会话：
bash
browser-use session create --profile <profile-id> --keep-alive
browser-use -b remote run "新任务" --session-id <new-session-id>
任务卡在"started"状态：使用
task status
检查成本 — 如果成本停止增加，说明任务已停滞。使用
session get
查看实时URL，然后停止任务并启动新Agent。
任务完成后会话仍存在：任务完成不会自动停止会话。运行
browser-use session stop --all
清理会话。

Cleanup

清理

Always close the browser when done:
bash
browser-use close                     # Close browser session
browser-use session stop --all        # Stop cloud sessions (if any)
browser-use tunnel stop --all         # Stop tunnels (if any)
使用完成后请务必关闭浏览器：
bash
browser-use close                     # 关闭浏览器会话
browser-use session stop --all        # 停止云端会话（如有）
browser-use tunnel stop --all         # 停止隧道（如有）