Back to Details

agent-browser

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Browser Automation via 
cloudrouter browser

基于
cloudrouter browser
的浏览器自动化

Automate browser interactions in cloud sandboxes. 
cloudrouter browser
wraps agent-browser and runs commands inside the sandbox via SSH.
Prerequisite: You need a running cloudrouter sandbox. Get the sandbox ID from 
cloudrouter ls
or create one with 
cloudrouter start .
.
在云沙箱中自动化浏览器交互。
cloudrouter browser
封装了agent-browser，并通过SSH在沙箱内运行命令。
前提条件： 你需要一个正在运行的cloudrouter沙箱。可以通过
cloudrouter ls
获取沙箱ID，或者使用
cloudrouter start .
创建一个新沙箱。

Core Workflow

核心工作流

Always follow this pattern: Open -> Snapshot -> Interact -> Re-snapshot
bash
cloudrouter browser open <id> "https://example.com"
cloudrouter browser snapshot -i <id>         # -i = interactive elements only
cloudrouter browser click <id> @e5           # Click element ref
cloudrouter browser fill <id> @e3 "text"     # Fill input
cloudrouter browser snapshot -i <id>         # Re-snapshot after change
请始终遵循以下流程：打开页面 -> 快照 -> 交互 -> 重新快照
bash
cloudrouter browser open <id> "https://example.com"
cloudrouter browser snapshot -i <id>         # -i = 仅包含可交互元素
cloudrouter browser click <id> @e5           # 点击元素引用
cloudrouter browser fill <id> @e3 "text"     # 填写输入框
cloudrouter browser snapshot -i <id>         # 操作后重新快照

Essential Commands

核心命令

Navigation

页面导航

bash
cloudrouter browser open <id> <url>          # Navigate to URL
cloudrouter browser back <id>                # Go back
cloudrouter browser forward <id>             # Go forward
cloudrouter browser reload <id>              # Refresh page
cloudrouter browser url <id>                 # Get current URL
cloudrouter browser title <id>               # Get page title
bash
cloudrouter browser open <id> <url>          # 跳转到指定URL
cloudrouter browser back <id>                # 返回上一页
cloudrouter browser forward <id>             # 前进到下一页
cloudrouter browser reload <id>              # 刷新页面
cloudrouter browser url <id>                 # 获取当前URL
cloudrouter browser title <id>               # 获取页面标题

Inspection

页面检查

bash
cloudrouter browser snapshot -i <id>         # Interactive elements only (RECOMMENDED)
cloudrouter browser snapshot <id>            # Full accessibility tree
cloudrouter browser snapshot -c <id>         # Compact output
cloudrouter browser screenshot <id>          # Screenshot (base64 to stdout)
cloudrouter browser screenshot <id> out.png  # Save screenshot to file
cloudrouter browser screenshot --full <id>   # Full page screenshot
cloudrouter browser eval <id> "document.title"  # Run JavaScript
bash
cloudrouter browser snapshot -i <id>         # 仅获取可交互元素（推荐）
cloudrouter browser snapshot <id>            # 获取完整可访问性树
cloudrouter browser snapshot -c <id>         # 获取精简输出
cloudrouter browser screenshot <id>          # 截图（输出base64编码到标准输出）
cloudrouter browser screenshot <id> out.png  # 将截图保存到文件
cloudrouter browser screenshot --full <id>   # 截取完整页面
cloudrouter browser eval <id> "document.title"  # 运行JavaScript代码

Interaction

页面交互

bash
cloudrouter browser click <id> @e1           # Click element
cloudrouter browser dblclick <id> @e1        # Double-click
cloudrouter browser fill <id> @e2 "text"     # Clear input and type text
cloudrouter browser type <id> @e2 "text"     # Type without clearing (appends)
cloudrouter browser press <id> Enter         # Press key (Enter, Tab, Escape, etc.)
cloudrouter browser hover <id> @e5           # Hover over element
cloudrouter browser focus <id> @e3           # Focus element
cloudrouter browser scroll <id> down         # Scroll down (default pixels)
cloudrouter browser scroll <id> down 500     # Scroll down 500px
cloudrouter browser scroll <id> up           # Scroll up
cloudrouter browser scrollintoview <id> "#element"  # Scroll into view (CSS selector only, NOT @e refs)
cloudrouter browser select <id> @e7 "value"  # Select dropdown option
cloudrouter browser check <id> @e8           # Check checkbox
cloudrouter browser uncheck <id> @e9         # Uncheck checkbox
cloudrouter browser upload <id> @e10 /path   # Upload file
cloudrouter browser drag <id> @e1 @e2        # Drag and drop
cloudrouter browser wait <id> @e3            # Wait for element to appear
cloudrouter browser wait <id> 2000           # Wait milliseconds
bash
cloudrouter browser click <id> @e1           # 点击元素
cloudrouter browser dblclick <id> @e1        # 双击元素
cloudrouter browser fill <id> @e2 "text"     # 清空输入框并输入文本
cloudrouter browser type <id> @e2 "text"     # 输入文本（不清空原有内容，追加输入）
cloudrouter browser press <id> Enter         # 按下按键（Enter、Tab、Escape等）
cloudrouter browser hover <id> @e5           # 悬停在元素上
cloudrouter browser focus <id> @e3           # 聚焦到元素
cloudrouter browser scroll <id> down         # 向下滚动（默认像素值）
cloudrouter browser scroll <id> down 500     # 向下滚动500像素
cloudrouter browser scroll <id> up           # 向上滚动
cloudrouter browser scrollintoview <id> "#element"  # 滚动到元素可见区域（仅支持CSS选择器，不支持@e引用）
cloudrouter browser select <id> @e7 "value"  # 选择下拉选项
cloudrouter browser check <id> @e8           # 勾选复选框
cloudrouter browser uncheck <id> @e9         # 取消勾选复选框
cloudrouter browser upload <id> @e10 /path   # 上传文件
cloudrouter browser drag <id> @e1 @e2        # 拖拽元素
cloudrouter browser wait <id> @e3            # 等待元素出现
cloudrouter browser wait <id> 2000           # 等待指定毫秒数

Get Information

信息获取

bash
cloudrouter browser get-text <id> @e1        # Get element text
cloudrouter browser get-value <id> @e2       # Get input value
cloudrouter browser get-attr <id> @e3 href   # Get attribute
cloudrouter browser get-html <id> @e4        # Get innerHTML
cloudrouter browser get-count <id> ".item"   # Count matching elements
cloudrouter browser is-visible <id> @e1      # Check visibility
cloudrouter browser is-enabled <id> @e1      # Check if enabled
cloudrouter browser is-checked <id> @e1      # Check if checked
bash
cloudrouter browser get-text <id> @e1        # 获取元素文本
cloudrouter browser get-value <id> @e2       # 获取输入框值
cloudrouter browser get-attr <id> @e3 href   # 获取元素属性
cloudrouter browser get-html <id> @e4        # 获取元素innerHTML
cloudrouter browser get-count <id> ".item"   # 统计匹配元素数量
cloudrouter browser is-visible <id> @e1      # 检查元素是否可见
cloudrouter browser is-enabled <id> @e1      # 检查元素是否可用
cloudrouter browser is-checked <id> @e1      # 检查复选框是否已勾选

Semantic Locators (alternative to refs)

语义定位器（替代元素引用）

When refs are unreliable on dynamic pages:
bash
cloudrouter browser find <id> text "Sign In" click                 # By visible text
cloudrouter browser find <id> label "Email" fill "user@test.com"   # By label
cloudrouter browser find <id> placeholder "Search" type "query"    # By placeholder
cloudrouter browser find <id> testid "submit-btn" click            # By data-testid
Note: 
find <id> role button click
finds the FIRST button on the page — it cannot filter by name. Use 
find <id> text "Button Name" click
to target a specific button. There is no 
--name
flag.
当元素引用在动态页面中不可靠时：
bash
cloudrouter browser find <id> text "Sign In" click                 # 通过可见文本定位并点击
cloudrouter browser find <id> label "Email" fill "user@test.com"   # 通过标签定位并填写
cloudrouter browser find <id> placeholder "Search" type "query"    # 通过占位符定位并输入
cloudrouter browser find <id> testid "submit-btn" click            # 通过data-testid定位并点击
注意： 
find <id> role button click
会找到页面上的第一个按钮——无法通过名称筛选。请使用
find <id> text "Button Name" click
来定位特定按钮。该命令不支持
--name
参数。

JavaScript & Debugging

JavaScript与调试

bash
cloudrouter browser eval <id> "document.title"          # Evaluate JS
cloudrouter browser console <id>                        # View console output
cloudrouter browser errors <id>                         # View JS errors
bash
cloudrouter browser eval <id> "document.title"          # 执行JavaScript代码
cloudrouter browser console <id>                        # 查看控制台输出
cloudrouter browser errors <id>                         # 查看JavaScript错误

Tabs & Frames

标签页与框架

bash
cloudrouter browser tab-list <id>                       # List tabs
cloudrouter browser tab-new <id> "https://..."          # New tab
cloudrouter browser tab-switch <id> 2                   # Switch tab
cloudrouter browser tab-close <id>                      # Close tab
cloudrouter browser frame <id> "#iframe"                # Switch to iframe
cloudrouter browser frame <id> main                     # Back to main
bash
cloudrouter browser tab-list <id>                       # 列出所有标签页
cloudrouter browser tab-new <id> "https://..."          # 新建标签页
cloudrouter browser tab-switch <id> 2                   # 切换到指定标签页
cloudrouter browser tab-close <id>                      # 关闭当前标签页
cloudrouter browser frame <id> "#iframe"                # 切换到指定iframe
cloudrouter browser frame <id> main                     # 返回主页面

Cookies & Storage

Cookie与存储

bash
cloudrouter browser cookies <id>                        # List cookies
cloudrouter browser cookies-set <id> name value         # Set cookie
cloudrouter browser cookies-clear <id>                  # Clear cookies
cloudrouter browser storage-local <id>                  # Get localStorage
cloudrouter browser storage-local-set <id> key value    # Set localStorage
cloudrouter browser storage-local-clear <id>            # Clear localStorage
bash
cloudrouter browser cookies <id>                        # 列出所有Cookie
cloudrouter browser cookies-set <id> name value         # 设置Cookie
cloudrouter browser cookies-clear <id>                  # 清除所有Cookie
cloudrouter browser storage-local <id>                  # 获取localStorage内容
cloudrouter browser storage-local-set <id> key value    # 设置localStorage
cloudrouter browser storage-local-clear <id>            # 清除localStorage

State Management

状态管理

bash
cloudrouter browser state-save <id> /tmp/auth.json      # Save cookies + storage
cloudrouter browser state-load <id> /tmp/auth.json      # Restore state
bash
cloudrouter browser state-save <id> /tmp/auth.json      # 保存Cookie与存储状态
cloudrouter browser state-load <id> /tmp/auth.json      # 恢复Cookie与存储状态

Browser Settings

浏览器设置

bash
cloudrouter browser set-viewport <id> 1920 1080         # Set viewport
cloudrouter browser set-device <id> "iPhone 14"         # Emulate device
cloudrouter browser set-geo <id> 37.77 -122.42          # Set geolocation
cloudrouter browser set-offline <id> on                 # Toggle offline
cloudrouter browser set-media <id> dark                 # Color scheme
bash
cloudrouter browser set-viewport <id> 1920 1080         # 设置视口尺寸
cloudrouter browser set-device <id> "iPhone 14"         # 模拟指定设备
cloudrouter browser set-geo <id> 37.77 -122.42          # 设置地理位置
cloudrouter browser set-offline <id> on                 # 切换离线模式
cloudrouter browser set-media <id> dark                 # 设置配色方案

Network Interception

网络拦截

bash
cloudrouter browser network-route <id> "**/api/*"       # Intercept requests
cloudrouter browser network-route <id> "**/ads/*" --abort  # Block requests
cloudrouter browser network-unroute <id>                # Remove routes
cloudrouter browser network-requests <id>               # List requests
bash
cloudrouter browser network-route <id> "**/api/*"       # 拦截指定请求
cloudrouter browser network-route <id> "**/ads/*" --abort  # 阻止指定请求
cloudrouter browser network-unroute <id>                # 移除所有拦截规则
cloudrouter browser network-requests <id>               # 列出所有请求

Dialogs

对话框

bash
cloudrouter browser dialog-accept <id>                  # Accept alert/confirm
cloudrouter browser dialog-accept <id> "answer"         # Accept prompt with text
cloudrouter browser dialog-dismiss <id>                 # Dismiss dialog
bash
cloudrouter browser dialog-accept <id>                  # 确认警告/确认对话框
cloudrouter browser dialog-accept <id> "answer"         # 确认提示对话框并输入文本
cloudrouter browser dialog-dismiss <id>                 # 取消对话框

Element Selectors

元素选择器

  • Element refs from snapshot: 
    @e1
    , 
    @e2
    , 
    @e3
    ... (preferred)
  • CSS selectors: 
    #id
    , 
    .class
    , 
    button[type="submit"]
Snapshot output shows 
[ref=e1]
— use as 
@e1
in commands.
  • 元素引用（来自快照）：
    @e1
    、
    @e2
    、
    @e3
    ...（推荐使用）
  • CSS选择器：
    #id
    、
    .class
    、
    button[type="submit"]
快照输出中会显示
[ref=e1]
——在命令中使用
@e1
来引用该元素。

Common Patterns

常见使用场景

Login Flow

登录流程

bash
cloudrouter browser open <id> "https://app.example.com/login"
cloudrouter browser snapshot -i <id>
bash
cloudrouter browser open <id> "https://app.example.com/login"
cloudrouter browser snapshot -i <id>

→ @e1 [input] Email, @e2 [input] Password, @e3 [button] Sign In

→ @e1 [输入框] 邮箱, @e2 [输入框] 密码, @e3 [按钮] 登录

cloudrouter browser fill <id> @e1 "user@example.com" cloudrouter browser fill <id> @e2 "password123" cloudrouter browser click <id> @e3 cloudrouter browser wait <id> 2000 cloudrouter browser snapshot -i <id> # Verify login success cloudrouter browser screenshot <id> /tmp/result.png
undefined
cloudrouter browser fill <id> @e1 "user@example.com" cloudrouter browser fill <id> @e2 "password123" cloudrouter browser click <id> @e3 cloudrouter browser wait <id> 2000 cloudrouter browser snapshot -i <id> # 验证登录是否成功 cloudrouter browser screenshot <id> /tmp/result.png
undefined

Form Submission

表单提交

bash
cloudrouter browser open <id> "https://example.com/contact"
cloudrouter browser snapshot -i <id>
cloudrouter browser fill <id> @e1 "John Doe"
cloudrouter browser fill <id> @e2 "john@email.com"
cloudrouter browser fill <id> @e3 "Hello world"
cloudrouter browser click <id> @e4           # Submit
cloudrouter browser wait <id> 2000
cloudrouter browser snapshot -i <id>         # Verify submission
bash
cloudrouter browser open <id> "https://example.com/contact"
cloudrouter browser snapshot -i <id>
cloudrouter browser fill <id> @e1 "John Doe"
cloudrouter browser fill <id> @e2 "john@email.com"
cloudrouter browser fill <id> @e3 "Hello world"
cloudrouter browser click <id> @e4           # 提交表单
cloudrouter browser wait <id> 2000
cloudrouter browser snapshot -i <id>         # 验证表单是否提交成功

Data Extraction

数据提取

bash
cloudrouter browser open <id> "https://example.com/products"
cloudrouter browser snapshot <id>            # Full tree for structure
cloudrouter browser get-text <id> @e5        # Extract specific text
cloudrouter browser eval <id> "JSON.stringify([...document.querySelectorAll('.product')].map(p => p.textContent))"
bash
cloudrouter browser open <id> "https://example.com/products"
cloudrouter browser snapshot <id>            # 获取完整页面结构树
cloudrouter browser get-text <id> @e5        # 提取指定文本
cloudrouter browser eval <id> "JSON.stringify([...document.querySelectorAll('.product')].map(p => p.textContent))"

Multi-page Navigation

多页面导航

bash
cloudrouter browser open <id> "https://example.com"
cloudrouter browser snapshot -i <id>
cloudrouter browser click <id> @e3           # Click a link
cloudrouter browser wait <id> 2000           # Wait for page load
cloudrouter browser snapshot -i <id>         # ALWAYS re-snapshot after navigation
bash
cloudrouter browser open <id> "https://example.com"
cloudrouter browser snapshot -i <id>
cloudrouter browser click <id> @e3           # 点击链接
cloudrouter browser wait <id> 2000           # 等待页面加载完成
cloudrouter browser snapshot -i <id>         # 页面导航后请务必重新快照

Auth State Persistence

认证状态持久化

bash
undefined
bash
undefined

Login once and save state

登录一次并保存状态

cloudrouter browser open <id> "https://app.example.com/login" cloudrouter browser snapshot -i <id> cloudrouter browser fill <id> @e1 "user@example.com" cloudrouter browser fill <id> @e2 "password" cloudrouter browser click <id> @e3 cloudrouter browser wait <id> 2000 cloudrouter browser state-save <id> /tmp/auth.json
cloudrouter browser open <id> "https://app.example.com/login" cloudrouter browser snapshot -i <id> cloudrouter browser fill <id> @e1 "user@example.com" cloudrouter browser fill <id> @e2 "password" cloudrouter browser click <id> @e3 cloudrouter browser wait <id> 2000 cloudrouter browser state-save <id> /tmp/auth.json

Restore in future sessions

在后续会话中恢复状态

cloudrouter browser state-load <id> /tmp/auth.json cloudrouter browser open <id> "https://app.example.com/dashboard"
undefined
cloudrouter browser state-load <id> /tmp/auth.json cloudrouter browser open <id> "https://app.example.com/dashboard"
undefined

Critical Rules

重要规则

  1. Flags go BEFORE the sandbox ID. 
    cloudrouter browser snapshot -i <id>
    works. 
    cloudrouter browser snapshot <id> -i
    silently returns empty/wrong results.
  2. ALWAYS re-snapshot after navigation or clicks. Page content changes, refs become stale.
  3. Use 
    -i
    flag     for snapshots — interactive elements only, much more efficient.
  4. Don't mix snapshot modes. Full 
    snapshot
    and 
    snapshot -i
    assign DIFFERENT ref numbers. Stick to one mode (use 
    -i
    ).
  5. Use 
    fill
    not 
    type
     for form fields. 
    fill
    clears first; 
    type
    appends.
  6. Refs are temporary. They reset after each snapshot. Always use fresh refs.
  7. Verify before interacting. Check snapshot output to confirm you have the right element.
  8. Handle loading states. If elements are missing, 
    wait
    and re-snapshot.
  1. 参数需放在沙箱ID之前。
    cloudrouter browser snapshot -i <id>
    可以正常运行。
    cloudrouter browser snapshot <id> -i
    会静默返回空结果或错误结果。
  2. 页面导航或点击后请务必重新快照。页面内容会发生变化，原有的元素引用会失效。
  3. 快照时使用
    -i
    参数    ——仅获取可交互元素，效率更高。
  4. 不要混合使用不同的快照模式。完整快照
    Snapshot
    和
    Snapshot -i
    会分配不同的元素引用编号。请坚持使用一种模式（推荐使用
    -i
    ）。
  5. 表单字段请使用
    fill
    而非
    type
    。
    fill
    会先清空输入框，而
    type
    是追加输入。
  6. 元素引用是临时的。每次快照后元素引用都会重置，请始终使用最新的元素引用。
  7. 交互前请先验证。检查快照输出以确认你选中了正确的元素。
  8. 处理加载状态。如果元素未找到，请使用
    wait
    命令并重新快照。

Troubleshooting

问题排查

IssueSolution
Element not found / wrong elementRe-snapshot with 
-i
, refs are stale
snapshot <id> -i
returns empty		Put flags BEFORE id: 
snapshot -i <id>
Click doesn't workTry 
hover
first, then 
click
Page not loadingCheck URL with 
cloudrouter browser url <id>
Browser not readyWait a few seconds after sandbox creation, retry
Refs differ between snapshotsDon't mix full and 
-i
snapshots
Form field has old textUse 
fill
(clears first) instead of 
type
find ... role button click
clicks wrong button		Use 
find ... text "Button Name" click
instead
find ... --name "X"
fails		There is no 
--name
flag — use 
text
locator
npm install
EACCES error		Run 
cloudrouter ssh <id> "sudo chown -R 1000:1000 /home/user/.npm"
first
scrollintoview @e1
fails with "Unsupported token"
scrollintoview
and 
highlight
only accept CSS selectors (
"#id"
, 
".class"
), NOT 
@e
refs
pkill -f
kills SSH session (exit 143/255)
pkill -f
pattern may match the SSH session. Just run another command to recover
pdf
saves to remote, not local		File saves inside sandbox (e.g. 
/tmp/page.pdf
). Use 
cloudrouter download
to retrieve
storage-local <id> key
shows "Done" not value		Use 
eval <id> "localStorage.getItem('key')"
to get a specific localStorage value
Stale ref error: "Action timed out"Always re-snapshot after clicks/form submits that change the DOM
问题解决方案
元素未找到 / 选中错误元素使用
-i
参数重新快照，原元素引用已失效
snapshot <id> -i
返回空结果		将参数放在沙箱ID之前：
snapshot -i <id>
点击操作无效先尝试
hover
命令，再执行
click
页面无法加载使用
cloudrouter browser url <id>
检查当前URL
浏览器未就绪沙箱创建后等待几秒，然后重试
不同快照的元素引用不一致不要混合使用完整快照和
-i
快照模式
表单字段仍显示旧文本使用
fill
命令（会先清空）而非
type
find ... role button click
点击了错误按钮		使用
find ... text "Button Name" click
替代
find ... --name "X"
执行失败		该命令不支持
--name
参数——请使用文本定位器
npm install
出现EACCES错误		先执行
cloudrouter ssh <id> "sudo chown -R 1000:1000 /home/user/.npm"
scrollintoview @e1
提示“Unsupported token”错误
scrollintoview
和
highlight
仅支持CSS选择器（如
"#id"
、
".class"
），不支持
@e
引用
pkill -f
导致SSH会话终止（退出码143/255）
pkill -f
的匹配规则可能会包含SSH会话。只需重新执行命令即可恢复
pdf
保存到远程而非本地		文件会保存到沙箱内部（例如
/tmp/page.pdf
）。请使用
cloudrouter download
命令将文件下载到本地
storage-local <id> key
显示“Done”而非对应值		使用
eval <id> "localStorage.getItem('key')"
来获取指定的localStorage值
元素引用失效错误：“Action timed out”点击或表单提交导致DOM变化后，请务必重新快照