remote-browser

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Remote Browser Automation for Sandboxed Agents

面向沙盒Agent的云端浏览器自动化工具

This skill is for agents running on sandboxed remote machines (cloud VMs, CI, coding agents) that need to control a browser. Install

browser-use

and drive a cloud browser — no local Chrome needed.

本工具适用于运行在沙盒化远程机器（云虚拟机、CI环境、代码Agent）中的Agent，帮助其控制浏览器。安装

browser-use

即可驱动云端浏览器——无需本地Chrome。

Setup

安装配置

—

仅远程安装（推荐沙盒Agent使用）

Remote-only install (recommended for sandboxed agents)

bash

curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --remote-only

This configures browser-use to only use cloud browsers:

No Chromium download (~300MB saved)
```
browser-use open <url>
```
automatically uses remote mode (no
```
--browser
```
flag needed)

If API key is available, you can also pass it during install:

bash

curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --remote-only --api-key bu_xxx

Manual install (alternative)

bash

pip install "browser-use[cli]"

bash

curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --remote-only

此配置会将browser-use设置为仅使用云端浏览器：

无需下载Chromium（节省约300MB空间）
```
browser-use open <url>
```
自动使用远程模式（无需
```
--browser
```
参数）

如果已有API密钥，也可在安装时传入：

bash

curl -fsSL https://browser-use.com/cli/install.sh | bash -s -- --remote-only --api-key bu_xxx

Install cloudflared for tunneling:

手动安装（替代方案）

macOS:

—

brew install cloudflared

bash

pip install "browser-use[cli]"

Linux:

安装cloudflared用于隧道功能：

—

macOS系统：

curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o ~/.local/bin/cloudflared && chmod +x ~/.local/bin/cloudflared

brew install cloudflared

Windows:

Linux系统：

winget install Cloudflare.cloudflared


**Then configure your API key:**
```bash
export BROWSER_USE_API_KEY=bu_xxx   # Required for cloud browser

Verify installation:

bash

browser-use doctor

curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o ~/.local/bin/cloudflared && chmod +x ~/.local/bin/cloudflared

Core Workflow

Windows系统：

When installed with

--remote-only

, commands automatically use the cloud browser — no

--browser

flag needed:

bash

undefined

winget install Cloudflare.cloudflared

undefined

Step 1: Start session (automatically uses remote mode)

配置API密钥

browser-use open https://example.com

bash

export BROWSER_USE_API_KEY=bu_xxx   # 使用云端浏览器必需

Returns: url, live_url (view the browser in real-time)

验证安装

Step 2+: All subsequent commands use the existing session

—

browser-use state # Get page elements with indices browser-use click 5 # Click element by index browser-use type "Hello World" # Type into focused element browser-use input 3 "text" # Click element, then type browser-use screenshot # Take screenshot (base64) browser-use screenshot page.png # Save screenshot to file

bash

browser-use doctor

Done: Close the session

核心工作流程

browser-use close # Close browser and release resources

undefined

使用

--remote-only

安装后，命令会自动使用云端浏览器——无需

--browser

参数：

bash

undefined

Understanding Installation Modes

步骤1：启动会话（自动使用远程模式）

Install Command	Available Modes	Default Mode	Use Case
`--remote-only`	remote	remote	Sandboxed agents, no GUI
`--local-only`	chromium, real	chromium	Local development
`--full`	chromium, real, remote	chromium	Full flexibility

When only one mode is installed, it becomes the default and no

--browser

flag is needed.

browser-use open https://example.com

Exposing Local Dev Servers

返回：url, live_url（实时查看浏览器）

—

步骤2及后续：所有命令复用现有会话

If you're running a dev server on the remote machine and need the cloud browser to reach it:

bash

undefined

browser-use state # 获取带索引的页面元素 browser-use click 5 # 通过索引点击元素 browser-use type "Hello World" # 在聚焦元素中输入文本 browser-use input 3 "text" # 点击元素后输入文本 browser-use screenshot # 生成截图（base64格式） browser-use screenshot page.png # 将截图保存到文件

Start your dev server

完成操作：关闭会话

python -m http.server 3000 &

browser-use close # 关闭浏览器并释放资源

undefined

Expose it via Cloudflare tunnel

安装模式说明

browser-use tunnel 3000

安装命令	可用模式	默认模式	使用场景
`--remote-only`	remote	remote	沙盒Agent、无GUI环境
`--local-only`	chromium, real	chromium	本地开发
`--full`	chromium, real, remote	chromium	全场景灵活使用

当仅安装一种模式时，该模式会成为默认，无需使用

--browser

参数。

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

暴露本地开发服务器

Now the cloud browser can reach your local server

—

browser-use open https://abc.trycloudflare.com


Tunnel commands:
```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

Note: Tunnels are independent of browser sessions. They persist across

browser-use close

and can be managed separately.

Cloudflared is installed by

install.sh --remote-only

. If missing, install manually (see Setup section).

如果在远程机器上运行开发服务器，需要让云端浏览器访问它：

bash

undefined

Commands

启动开发服务器

Navigation

—

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)

python -m http.server 3000 &

Page State

通过Cloudflare隧道暴露

bash

browser-use state                   # Get URL, title, and clickable elements
browser-use screenshot              # Take screenshot (base64)
browser-use screenshot path.png     # Save screenshot to file
browser-use screenshot --full p.png # Full page screenshot

browser-use tunnel 3000

Interactions (use indices from

state

)

→ 生成链接：https://abc.trycloudflare.com

—

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

bash

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 keys "Control+a"        # Key combination
browser-use select <index> "option" # Select dropdown option
browser-use hover <index>           # Hover over element
browser-use dblclick <index>        # Double-click
browser-use rightclick <index>      # Right-click

browser-use open https://abc.trycloudflare.com


隧道命令：
```bash
browser-use tunnel <port>           # 启动隧道（返回访问链接）
browser-use tunnel <port>           # 幂等操作——返回已存在的链接
browser-use tunnel list             # 查看活跃隧道
browser-use tunnel stop <port>      # 停止指定端口的隧道
browser-use tunnel stop --all       # 停止所有隧道

注意： 隧道与浏览器会话相互独立。它们会在

browser-use close

后继续存在，可单独管理。

使用

install.sh --remote-only

安装时会自动安装cloudflared。如果缺失，可手动安装（见安装配置部分）。

JavaScript & Data

命令列表

—

导航操作

bash

browser-use eval "document.title"   # Execute JavaScript
browser-use extract "all prices"    # Extract data using LLM
browser-use get title               # Get page title
browser-use get html                # Get page HTML
browser-use get html --selector "h1"  # Scoped HTML
browser-use get text <index>        # Get element text
browser-use get value <index>       # Get input value
browser-use get attributes <index>  # Get element attributes
browser-use get bbox <index>        # Get bounding box (x, y, width, height)

bash

browser-use open <url>              # 导航到指定URL
browser-use back                    # 后退到上一页
browser-use scroll down             # 向下滚动页面
browser-use scroll up               # 向上滚动页面
browser-use scroll down --amount 1000  # 滚动指定像素（默认：500）

Wait Conditions

页面状态

bash

browser-use wait selector "h1"                         # Wait for element
browser-use wait selector ".loading" --state hidden    # Wait for element to disappear
browser-use wait text "Success"                        # Wait for text
browser-use wait selector "#btn" --timeout 5000        # Custom timeout (ms)

bash

browser-use state                   # 获取URL、标题和可点击元素
browser-use screenshot              # 生成截图（base64格式）
browser-use screenshot path.png     # 将截图保存到指定文件
browser-use screenshot --full p.png # 生成整页截图

Cookies

页面交互（使用

state

返回的元素索引）

bash

browser-use cookies get             # Get all cookies
browser-use cookies get --url <url> # Get cookies for specific URL
browser-use cookies set <name> <val>  # Set a cookie
browser-use cookies set name val --domain .example.com --secure  # With options
browser-use cookies set name val --same-site Strict  # SameSite: Strict, Lax, 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 to JSON
browser-use cookies import <file>   # Import from JSON

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>           # 悬停在元素上方
browser-use dblclick <index>        # 双击元素
browser-use rightclick <index>      # 右键点击元素

Tab Management

JavaScript与数据处理

bash

browser-use switch <tab>            # Switch tab by index
browser-use close-tab               # Close current tab
browser-use close-tab <tab>         # Close specific tab

bash

browser-use eval "document.title"   # 执行JavaScript代码
browser-use extract "all prices"    # 使用LLM提取数据
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, 宽度, 高度）

Python Execution (Persistent Session)

等待条件

bash

browser-use python "x = 42"           # Set variable
browser-use python "print(x)"         # Access variable (prints: 42)
browser-use python "print(browser.url)"  # Access browser object
browser-use python --vars             # Show defined variables
browser-use python --reset            # Clear namespace
browser-use python --file script.py   # Run Python file

The Python session maintains state across commands. The

browser

object provides:

```
browser.url
```
- Current page URL
```
browser.title
```
- Page title
```
browser.html
```
- Get page HTML
```
browser.goto(url)
```
- Navigate
```
browser.click(index)
```
- Click element
```
browser.type(text)
```
- Type text
```
browser.input(index, text)
```
- Click element, then type
```
browser.keys(keys)
```
- Send keyboard keys
```
browser.screenshot(path)
```
- Take screenshot
```
browser.scroll(direction, amount)
```
- Scroll page
```
browser.back()
```
- Go back in history
```
browser.wait(seconds)
```
- Sleep/pause execution
```
browser.extract(query)
```
- Extract data using LLM

bash

browser-use wait selector "h1"                         # 等待元素出现
browser-use wait selector ".loading" --state hidden    # 等待元素消失
browser-use wait text "Success"                        # 等待文本出现
browser-use wait selector "#btn" --timeout 5000        # 自定义超时时间（毫秒）

Agent Tasks

Cookie管理

bash

browser-use run "Fill the contact form with test data"   # AI agent
browser-use run "Extract all product prices" --max-steps 50

bash

browser-use cookies get             # 获取所有Cookie
browser-use cookies get --url <url> # 获取指定URL的Cookie
browser-use cookies set <name> <val>  # 设置Cookie
browser-use cookies set name val --domain .example.com --secure  # 带参数设置Cookie
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 import <file>   # 从JSON文件导入Cookie

Specify LLM model

标签页管理

browser-use run "task" --llm gpt-4o browser-use run "task" --llm claude-sonnet-4-20250514 browser-use run "task" --llm gemini-2.0-flash

bash

browser-use switch <tab>            # 通过索引切换标签页
browser-use close-tab               # 关闭当前标签页
browser-use close-tab <tab>         # 关闭指定索引的标签页

Proxy configuration (default: us)

Python执行（持久会话）

browser-use run "task" --proxy-country gb # UK proxy browser-use run "task" --proxy-country de # Germany proxy

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            # 清空命名空间
browser-use python --file script.py   # 运行Python文件

Python会话会在多个命令间保持状态。

browser

对象提供以下功能：

```
browser.url
```
- 当前页面URL
```
browser.title
```
- 页面标题
```
browser.html
```
- 获取页面HTML
```
browser.goto(url)
```
- 导航到指定URL
```
browser.click(index)
```
- 点击指定元素
```
browser.type(text)
```
- 输入文本
```
browser.input(index, text)
```
- 点击元素后输入文本
```
browser.keys(keys)
```
- 发送键盘按键
```
browser.screenshot(path)
```
- 生成截图
```
browser.scroll(direction, amount)
```
- 滚动页面
```
browser.back()
```
- 后退到上一页
```
browser.wait(seconds)
```
- 暂停执行
```
browser.extract(query)
```
- 使用LLM提取数据

Session reuse (run multiple tasks in same browser session)

Agent任务

browser-use run "task 1" --keep-alive

bash

browser-use run "Fill the contact form with test data"   # 执行AI Agent任务
browser-use run "Extract all product prices" --max-steps 50

Returns: session_id: abc-123

指定LLM模型

browser-use run "task 2" --session-id abc-123

browser-use run "task" --llm gpt-4o browser-use run "task" --llm claude-sonnet-4-20250514 browser-use run "task" --llm gemini-2.0-flash

Execution modes

代理配置（默认：美国）

browser-use run "task" --no-wait # Async, returns task_id immediately browser-use run "task" --wait # Wait for completion browser-use run "task" --stream # Stream status updates browser-use run "task" --flash # Fast execution mode

browser-use run "task" --proxy-country gb # 英国代理 browser-use run "task" --proxy-country de # 德国代理

Advanced options

会话复用（在同一会话中执行多个任务）

browser-use run "task" --thinking # Extended reasoning mode browser-use run "task" --vision # Enable vision (default) browser-use run "task" --no-vision # Disable vision

browser-use run "task 1" --keep-alive

Use cloud profile (preserves cookies across sessions)

返回：session_id: abc-123

browser-use run "task" --profile <cloud-profile-id>

browser-use run "task 2" --session-id abc-123

Task configuration

执行模式

browser-use run "task" --start-url https://example.com # Start from specific URL browser-use run "task" --allowed-domain example.com # Restrict navigation (repeatable) browser-use run "task" --metadata key=value # Task metadata (repeatable) browser-use run "task" --secret API_KEY=xxx # Task secrets (repeatable) browser-use run "task" --skill-id skill-123 # Enable skills (repeatable)

browser-use run "task" --no-wait # 异步执行，立即返回task_id browser-use run "task" --wait # 等待任务完成 browser-use run "task" --stream # 流式输出状态更新 browser-use run "task" --flash # 快速执行模式

Structured output and evaluation

高级选项

browser-use run "task" --structured-output '{"type":"object"}' # JSON schema for output browser-use run "task" --judge # Enable judge mode browser-use run "task" --judge-ground-truth "answer" # Expected answer for judge

undefined

browser-use run "task" --thinking # 扩展推理模式 browser-use run "task" --vision # 启用视觉功能（默认开启） browser-use run "task" --no-vision # 禁用视觉功能

Task Management

使用云端配置文件（跨会话保留Cookie）

Manage cloud tasks:

bash

browser-use task list                     # List recent tasks
browser-use task list --limit 20          # Show more tasks
browser-use task list --status running    # Filter by status
browser-use task list --status finished
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      # Compact: all steps with reasoning
browser-use task status <task-id> -v      # Verbose: full details with URLs + actions
browser-use task status <task-id> --last 5   # Show only last 5 steps
browser-use task status <task-id> --step 3   # Show specific step number
browser-use task status <task-id> --reverse  # Show steps newest first
browser-use task status <task-id> --json

browser-use task stop <task-id>           # Stop a running task

browser-use task logs <task-id>           # Get task execution logs

browser-use run "task" --profile <cloud-profile-id>

Cloud Session Management

任务配置

Manage cloud browser sessions:

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 run "task" --start-url https://example.com # 从指定URL开始执行 browser-use run "task" --allowed-domain example.com # 限制导航域名（可重复设置） browser-use run "task" --metadata key=value # 任务元数据（可重复设置） browser-use run "task" --secret API_KEY=xxx # 任务密钥（可重复设置） browser-use run "task" --skill-id skill-123 # 启用技能（可重复设置）

Create a new cloud session manually

结构化输出与评估

browser-use session create # Create with defaults browser-use session create --profile <id> # With cloud profile browser-use session create --proxy-country gb # With geographic proxy browser-use session create --start-url https://example.com # Start at URL browser-use session create --screen-size 1920x1080 # Custom screen size browser-use session create --keep-alive # Keep session alive browser-use session create --persist-memory # Persist memory between tasks

browser-use run "task" --structured-output '{"type":"object"}' # 输出遵循JSON schema browser-use run "task" --judge # 启用评估模式 browser-use run "task" --judge-ground-truth "answer" # 评估用的预期答案

undefined

Share session publicly (for collaboration/debugging)

任务管理

browser-use session share <session-id> # Create public share URL browser-use session share <session-id> --delete # Delete public share

undefined

管理云端任务：

bash

browser-use task list                     # 查看近期任务
browser-use task list --limit 20          # 查看更多任务
browser-use task list --status running    # 按状态筛选：运行中
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   # 仅显示最后5个步骤
browser-use task status <task-id> --step 3   # 显示指定步骤
browser-use task status <task-id> --reverse  # 按从新到旧的顺序显示步骤
browser-use task status <task-id> --json

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

Cloud Profile Management

云端会话管理

Cloud profiles store browser state (cookies) persistently across sessions. Use profiles to maintain login sessions.

bash

browser-use profile list                  # List cloud profiles
browser-use profile list --page 2 --page-size 50  # Pagination
browser-use profile get <id>              # Get profile details
browser-use profile create                # Create new profile
browser-use profile create --name "My Profile"  # Create with name
browser-use profile update <id> --name "New Name"  # Rename profile
browser-use profile delete <id>           # Delete profile

Using profiles:

bash

undefined

管理云端浏览器会话：

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>      # 获取会话详情及实时查看链接
browser-use session get <session-id> --json

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

Run task with profile (preserves cookies)

手动创建新的云端会话

browser-use run "Log into site" --profile <profile-id> --keep-alive

browser-use session create # 使用默认配置创建 browser-use session create --profile <id> # 关联云端配置文件 browser-use session create --proxy-country gb # 使用指定地区代理 browser-use session create --start-url https://example.com # 从指定URL启动 browser-use session create --screen-size 1920x1080 # 自定义屏幕尺寸 browser-use session create --keep-alive # 保持会话活跃 browser-use session create --persist-memory # 跨任务保留会话内存

Create session with profile

公开分享会话（用于协作/调试）

browser-use session create --profile <profile-id>

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

undefined

Open URL with profile

云端配置文件管理

browser-use open https://example.com --profile <profile-id>


**Import cookies to cloud profile:**
```bash

云端配置文件会持久化存储浏览器状态（Cookie），跨会话保留。可用于维持登录状态。

bash

browser-use profile list                  # 查看云端配置文件
browser-use profile list --page 2 --page-size 50  # 分页查看
browser-use profile get <id>              # 获取配置文件详情
browser-use profile create                # 创建新配置文件
browser-use profile create --name "My Profile"  # 创建带名称的配置文件
browser-use profile update <id> --name "New Name"  # 重命名配置文件
browser-use profile delete <id>           # 删除配置文件

使用配置文件：

bash

undefined

Export cookies from current session

使用配置文件执行任务（保留Cookie）

browser-use cookies export /tmp/cookies.json

browser-use run "Log into site" --profile <profile-id> --keep-alive

Import to cloud profile

使用配置文件创建会话

browser-use cookies import /tmp/cookies.json --profile <profile-id>

undefined

browser-use session create --profile <profile-id>

Running Subagents

使用配置文件打开URL

Cloud sessions and tasks provide a powerful model for running subagents - autonomous browser agents that execute tasks in parallel.

browser-use open https://example.com --profile <profile-id>


**将Cookie导入云端配置文件：**
```bash

Key Concepts

从当前会话导出Cookie

Session = Agent: Each cloud session is a browser agent with its own state (cookies, tabs, history)
Task = Work: Tasks are jobs given to an agent. An agent can run multiple tasks sequentially
Parallel agents: Run multiple sessions simultaneously for parallel work
Session reuse: While a session is alive, you can assign it more tasks
Session lifecycle: Once stopped, a session cannot be revived - start a new one

browser-use cookies export /tmp/cookies.json

Basic Subagent Workflow

导入到云端配置文件

bash

undefined

browser-use cookies import /tmp/cookies.json --profile <profile-id>

undefined

1. Start a subagent task (creates new session automatically)

运行子Agent

browser-use run "Search for AI news and summarize top 3 articles" --no-wait

云端会话和任务提供了强大的子Agent运行模型——可并行执行任务的自主浏览器Agent。

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

核心概念

2. Check task progress

—

browser-use task status task-abc

会话 = Agent：每个云端会话都是一个独立的浏览器Agent，拥有自身状态（Cookie、标签页、历史记录）
任务 = 工作：任务是分配给Agent的工作。一个Agent可按顺序执行多个任务
并行Agent：同时运行多个会话以实现并行工作
会话复用：会话活跃期间，可分配更多任务
会话生命周期：会话停止后无法恢复——需创建新会话

Shows: Status: running, or finished with output

子Agent基础工作流程

3. View execution logs

—

browser-use task logs task-abc

undefined

bash

undefined

Running Parallel Subagents

1. 启动子Agent任务（自动创建新会话）

Launch multiple agents to work simultaneously:

bash

undefined

browser-use run "Search for AI news and summarize top 3 articles" --no-wait

Start 3 parallel research agents

返回：task_id: task-abc, session_id: sess-123

—

2. 检查任务进度

browser-use run "Research competitor A pricing" --no-wait

browser-use task status task-abc

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

显示：状态：运行中，或已完成及输出结果

—

3. 查看执行日志

browser-use run "Research competitor B pricing" --no-wait

browser-use task logs task-abc

undefined

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

运行并行子Agent

browser-use run "Research competitor C pricing" --no-wait

启动多个Agent以同时工作：

bash

undefined

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

启动3个并行的调研Agent

Monitor all running tasks

—

browser-use task list --status running

browser-use run "Research competitor A pricing" --no-wait

Shows all 3 tasks with their status

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

Check individual task results as they complete

—

browser-use task status task-1 browser-use task status task-2 browser-use task status task-3

undefined

browser-use run "Research competitor B pricing" --no-wait

Reusing an Agent for Multiple Tasks

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

Keep a session alive to run sequential tasks in the same browser context:

bash

undefined

browser-use run "Research competitor C pricing" --no-wait

Start first task, keep session alive

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

—

监控所有运行中的任务

browser-use run "Log into example.com" --keep-alive --no-wait

browser-use task list --status running

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

显示所有3个任务的状态

Wait for login to complete...

逐个查看任务完成结果

browser-use task status task-1

browser-use task status task-1 browser-use task status task-2 browser-use task status task-3

undefined

→ Status: finished

复用Agent执行多个任务

Give the same agent another task (reuses login session)

—

browser-use run "Navigate to settings and export data" --session-id sess-123 --no-wait

保持会话活跃，在同一浏览器上下文中执行多个任务：

bash

undefined

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

启动第一个任务，保持会话活跃

Agent retains cookies, login state, etc. from previous task

—

undefined

browser-use run "Log into example.com" --keep-alive --no-wait

Managing Active Agents

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

—

等待登录完成...

bash

undefined

browser-use task status task-1

List all active agents (sessions)

→ 状态：已完成

—

给同一个Agent分配新任务（复用登录会话）

browser-use session list --status active

browser-use run "Navigate to settings and export data" --session-id sess-123 --no-wait

Shows: sess-123 [active], sess-456 [active], ...

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

Get details on a specific agent

Agent会保留之前任务的Cookie、登录状态等信息

browser-use session get sess-123

undefined

Shows: status, started time, live URL for viewing

管理活跃Agent

Stop a specific agent

—

browser-use session stop sess-123

bash

undefined

Stop all agents at once

查看所有活跃Agent（会话）

browser-use session stop --all

undefined

browser-use session list --status active

Stopping Tasks vs Sessions

显示：sess-123 [活跃], sess-456 [活跃], ...

—

获取指定Agent的详情

bash

undefined

browser-use session get sess-123

Stop a running task (session may continue if --keep-alive was used)

显示：状态、启动时间、实时查看链接

—

停止指定Agent

browser-use task stop task-abc

browser-use session stop sess-123

Stop an entire agent/session (terminates all its tasks)

一次性停止所有Agent

browser-use session stop sess-123

undefined

browser-use session stop --all

undefined

Custom Agent Configuration

停止任务 vs 停止会话

bash

undefined

bash

undefined

Default: US proxy, auto LLM selection

停止运行中的任务（如果使用了--keep-alive，会话会继续存在）

browser-use run "task" --no-wait

browser-use task stop task-abc

Explicit configuration

停止整个Agent/会话（终止其所有任务）

browser-use run "task"
--llm gpt-4o
--proxy-country gb
--keep-alive
--no-wait

browser-use session stop sess-123

undefined

With cloud profile (preserves cookies across sessions)

自定义Agent配置

browser-use run "task" --profile <profile-id> --no-wait

undefined

bash

undefined

Monitoring Subagents

默认配置：美国代理、自动选择LLM

Task status is designed for token efficiency. Default output is minimal - only expand when needed:

Mode	Flag	Tokens	Use When
Default	(none)	Low	Polling progress
Compact	`-c`	Medium	Need full reasoning
Verbose	`-v`	High	Debugging actions

Recommended workflow:

bash

undefined

browser-use run "task" --no-wait

1. Launch task

显式配置

browser-use run "task" --no-wait

browser-use run "task"
--llm gpt-4o
--proxy-country gb
--keep-alive
--no-wait

→ task_id: abc-123

关联云端配置文件（跨会话保留Cookie）

2. Poll with default (token efficient) - only latest step

—

browser-use task status abc-123

browser-use run "task" --profile <profile-id> --no-wait

undefined

✅ abc-123... [finished] $0.009 15s

监控子Agent

... 1 earlier steps

—

2. I found the information and extracted...

—

3. ONLY IF task failed or need context: use --compact

—

browser-use task status abc-123 -c

任务状态设计兼顾Token效率。 默认输出极简——仅在需要时展开：

模式	参数	Token消耗	使用场景
默认	无	低	轮询进度
紧凑	`-c`	中	需要完整推理过程
详细	`-v`	高	调试操作

推荐工作流程：

bash

undefined

4. ONLY IF debugging specific actions: use --verbose

1. 启动任务

browser-use task status abc-123 -v


**For long tasks (50+ steps):**
```bash
browser-use task status <id> -c --last 5   # Last 5 steps only
browser-use task status <id> -c --reverse  # Newest first
browser-use task status <id> -v --step 10  # Inspect specific step

Live view: Watch an agent work in real-time:

bash

browser-use session get <session-id>

browser-use run "task" --no-wait

→ Live URL: https://live.browser-use.com?wss=...

→ task_id: abc-123

—

2. 使用默认模式轮询（Token高效）——仅显示最新步骤


**Detect stuck tasks**: If cost/duration stops increasing, the task may be stuck:
```bash
browser-use task status <task-id>

browser-use task status abc-123

🔄 abc-123... [started] $0.009 45s ← if cost doesn't change, task is stuck

✅ abc-123... [已完成] $0.009 15s

—

... 1个更早的步骤

—

2. 我已找到信息并提取...

—

3. 仅当任务失败或需要上下文时：使用紧凑模式


**Logs**: Only available after task completes:
```bash
browser-use task logs <task-id>  # Works after task finishes

browser-use task status abc-123 -c

Cleanup

4. 仅当调试特定操作时：使用详细模式

Always clean up sessions after parallel work:

bash

undefined

browser-use task status abc-123 -v


**针对长任务（50+步骤）：**
```bash
browser-use task status <id> -c --last 5   # 仅显示最后5个步骤
browser-use task status <id> -c --reverse  # 按从新到旧的顺序显示
browser-use task status <id> -v --step 10  # 查看指定步骤

实时查看： 实时监控Agent工作：

bash

browser-use session get <session-id>

Stop all active agents

→ 实时查看链接：https://live.browser-use.com?wss=...

browser-use session stop --all


**检测停滞任务：** 如果成本/时长不再增加，任务可能已停滞：
```bash
browser-use task status <task-id>

Or stop specific sessions

🔄 abc-123... [已启动] $0.009 45s ← 如果成本未变化，任务已停滞

browser-use session stop <session-id>

undefined


**日志：** 仅在任务完成后可用：
```bash
browser-use task logs <task-id>  # 任务完成后可查看

Troubleshooting

清理

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. Solution: create a new agent instead.

bash

undefined

并行工作后务必清理会话：

bash

undefined

This may fail:

停止所有活跃Agent

browser-use task stop <task-id> browser-use run "new task" --session-id <same-session> # Might get stuck

browser-use session stop --all

Do this instead:

或停止指定会话

browser-use run "new task" --profile <profile-id> # Fresh session


**Task stuck at "started"**:
- Check cost with `task status` - if not increasing, task is stuck
- View live URL with `session get` to see what's happening
- Stop the task and create a new agent

**Sessions persist after tasks complete**:
Tasks finishing doesn't auto-stop sessions. Clean up manually:
```bash
browser-use session list --status active  # See lingering sessions
browser-use session stop --all            # Clean up

browser-use session stop <session-id>

undefined

Session Management

故障排除

bash

browser-use sessions                # List active sessions
browser-use close                   # Close current session
browser-use close --all             # Close all sessions

任务停止后会话复用失败： 如果停止任务后尝试复用会话，新任务可能会卡在“已创建”状态。解决方案：创建新Agent。

bash

undefined

Global Options

此操作可能失败：

Option	Description
`--session NAME`	Named session (default: "default")
`--browser MODE`	Browser mode (only if multiple modes installed)
`--profile ID`	Cloud profile ID for persistent cookies
`--json`	Output as JSON
`--api-key KEY`	Override API key

browser-use task stop <task-id> browser-use run "new task" --session-id <same-session> # 可能卡住

Common Patterns

正确操作：

Test a Local Dev Server with Cloud Browser

—

bash

undefined

browser-use run "new task" --profile <profile-id> # 使用新会话


**任务卡在“已启动”状态：**
- 使用`task status`查看成本——如果成本未增加，任务已停滞
- 使用`session get`获取实时查看链接，查看当前状态
- 停止任务并创建新Agent

**任务完成后会话仍存在：**
任务完成后不会自动停止会话。需手动清理：
```bash
browser-use session list --status active  # 查看残留会话
browser-use session stop --all            # 清理所有会话

Start dev server

会话管理快捷命令

npm run dev & # localhost:3000

bash

browser-use sessions                # 查看活跃会话
browser-use close                   # 关闭当前会话
browser-use close --all             # 关闭所有会话

Tunnel it

全局选项

browser-use tunnel 3000

选项	描述
`--session NAME`	命名会话（默认："default"）
`--browser MODE`	浏览器模式（仅当安装了多种模式时可用）
`--profile ID`	云端配置文件ID，用于持久化Cookie
`--json`	以JSON格式输出
`--api-key KEY`	覆盖已设置的API密钥

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

常见使用场景

Browse with cloud browser

使用云端浏览器测试本地开发服务器

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

undefined

bash

undefined

Form Submission

启动开发服务器

bash

browser-use open https://example.com/contact
browser-use state

npm run dev & # localhost:3000

Shows: [0] input "Name", [1] input "Email", [2] textarea "Message", [3] button "Submit"

暴露隧道

browser-use input 0 "John Doe" browser-use input 1 "john@example.com" browser-use input 2 "Hello, this is a test message." browser-use click 3 browser-use state # Verify success

undefined

browser-use tunnel 3000

Screenshot Loop for Visual Verification

→ 访问链接：https://abc.trycloudflare.com

—

使用云端浏览器访问

bash

browser-use open https://example.com
for i in 1 2 3 4 5; do
  browser-use scroll down
  browser-use screenshot "page_$i.png"
done

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

undefined

Tips

表单提交

Install with
--remote-only
for sandboxed environments — no
```
--browser
```
flag needed
Always run
state
first to see available elements and their indices
Sessions persist across commands — the browser stays open until you close it
Tunnels are independent — they don't require or create a browser session, and persist across
```
browser-use close
```
Use
--json
for programmatic parsing
tunnel
is idempotent — calling it again for the same port returns the existing URL
Close when done —
```
browser-use close
```
closes the browser;
```
browser-use tunnel stop --all
```
stops tunnels

bash

browser-use open https://example.com/contact
browser-use state

Troubleshooting

显示：[0] 输入框 "Name", [1] 输入框 "Email", [2] 文本框 "Message", [3] 按钮 "Submit"

"Browser mode 'chromium' not installed"?

You installed with
```
--remote-only
```
which doesn't include local modes
This is expected behavior for sandboxed agents
If you need local browser, reinstall with
```
--full
```

Cloud browser won't start?

Verify
```
BROWSER_USE_API_KEY
```
is set
Check your API key at https://browser-use.com

Tunnel not working?

Verify cloudflared is installed:
```
which cloudflared
```
If missing, install manually (see Setup section) or re-run
```
install.sh --remote-only
```
```
browser-use tunnel list
```
to check active tunnels
```
browser-use tunnel stop <port>
```
and retry

Element not found?

Run
```
browser-use state
```
to see current elements

browser-use scroll down

then

browser-use state

— element might be below fold

Page may have changed — re-run
```
state
```
to get fresh indices

browser-use input 0 "John Doe" browser-use input 1 "john@example.com" browser-use input 2 "Hello, this is a test message." browser-use click 3 browser-use state # 验证提交是否成功

undefined

Cleanup

截图循环用于视觉验证

Close the browser when done:

bash

browser-use close              # Close browser session
browser-use tunnel stop --all  # Stop all tunnels (if any)

Browser sessions and tunnels are managed separately, so close each as needed.

bash

browser-use open https://example.com
for i in 1 2 3 4 5; do
  browser-use scroll down
  browser-use screenshot "page_$i.png"
done

—

使用技巧

—

沙盒环境推荐使用
--remote-only
安装——无需
```
--browser
```
参数
先运行
state
命令查看可用元素及其索引
会话会跨命令持久化——浏览器会保持打开状态，直到你主动关闭
隧道与会话相互独立——它们不需要依赖浏览器会话，且会在
```
browser-use close
```
后继续存在
使用
--json
选项便于程序解析输出
tunnel
命令是幂等的——再次调用同一端口会返回已存在的链接
使用完成后记得关闭——
```
browser-use close
```
关闭浏览器会话；
```
browser-use tunnel stop --all
```
停止所有隧道

—

故障排除

—

提示“Browser mode 'chromium' not installed”？

你使用了
```
--remote-only
```
安装，该模式不包含本地浏览器
这是沙盒Agent的预期行为
如果需要本地浏览器，使用
```
--full
```
参数重新安装

云端浏览器无法启动？

验证
```
BROWSER_USE_API_KEY
```
是否已正确设置
访问https://browser-use.com检查你的API密钥

隧道无法工作？

验证cloudflared是否已安装：
```
which cloudflared
```
如果缺失，可手动安装（见安装配置部分）或重新运行
```
install.sh --remote-only
```
使用
```
browser-use tunnel list
```
查看活跃隧道
使用
```
browser-use tunnel stop <port>
```
后重试

元素未找到？

运行
```
browser-use state
```
查看当前页面的元素
运行
```
browser-use scroll down
```
后再执行
```
browser-use state
```
——元素可能在页面下方
页面可能已更新——重新运行
```
state
```
获取最新的元素索引

—

清理

—

使用完成后关闭浏览器：

bash

browser-use close              # 关闭浏览器会话
browser-use tunnel stop --all  # 停止所有隧道（如果有）

浏览器会话和隧道是分开管理的，需根据需要分别关闭。

remote-browser

Original

Translation

Remote Browser Automation for Sandboxed Agents

面向沙盒Agent的云端浏览器自动化工具

Setup

安装配置

仅远程安装（推荐沙盒Agent使用）

Install cloudflared for tunneling:

手动安装（替代方案）

macOS:

Linux:

安装cloudflared用于隧道功能：

macOS系统：

Windows:

Linux系统：

Core Workflow

Windows系统：

Step 1: Start session (automatically uses remote mode)

配置API密钥

Returns: url, live_url (view the browser in real-time)

验证安装

Step 2+: All subsequent commands use the existing session

Done: Close the session

核心工作流程

Understanding Installation Modes

步骤1：启动会话（自动使用远程模式）

Exposing Local Dev Servers

返回：url, live_url（实时查看浏览器）

步骤2及后续：所有命令复用现有会话

Start your dev server

完成操作：关闭会话

Expose it via Cloudflare tunnel

安装模式说明

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

暴露本地开发服务器

Now the cloud browser can reach your local server

Commands

启动开发服务器

Navigation

Page State

通过Cloudflare隧道暴露

Interactions (use indices from state)

→ 生成链接：https://abc.trycloudflare.com

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

JavaScript & Data

命令列表

导航操作

Wait Conditions

页面状态

Cookies

页面交互（使用state返回的元素索引）

Tab Management

JavaScript与数据处理

Python Execution (Persistent Session)

等待条件

Agent Tasks

Cookie管理

Specify LLM model

标签页管理

Proxy configuration (default: us)

Python执行（持久会话）

Session reuse (run multiple tasks in same browser session)

Agent任务

Returns: session_id: abc-123

指定LLM模型

Execution modes

代理配置（默认：美国）

Advanced options

会话复用（在同一会话中执行多个任务）

Use cloud profile (preserves cookies across sessions)

返回：session_id: abc-123

Task configuration

执行模式

Structured output and evaluation

高级选项

Task Management

使用云端配置文件（跨会话保留Cookie）

Cloud Session Management

任务配置

Interactions (use indices from
`state`
)

页面交互（使用
`state`
返回的元素索引）