control-browser

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Browser Control

浏览器控制

Stop: local_shell is not a reliable path to user-local files

注意：local_shell 并非访问用户本地文件的可靠途径

local_shell

runs on the user's machine only if they have the
starchild agent-shell
daemon installed, running, and authorized — most users do not, so the tool is usually unavailable or denied.

bash

and

read_file

run in the agent's remote container, which has none of the user's files. Either way, do not run shell commands to locate or read the user's local files (Downloads, Desktop, Documents):

ls ~/Downloads

either fails (unavailable/denied) or lists the wrong filesystem. When a task involves a file on the user's computer (upload, attach, open), the only dependable path is the browser's native file picker, which only the user can operate — hand off precisely (see

docs/file-uploads.md

). Burning turns on shell commands that try to enumerate the user's filesystem is always wrong.

local_shell

仅在用户已安装、运行并授权

starchild agent-shell

守护进程的情况下，才会在用户设备上运行——大多数用户并未满足该条件，因此该工具通常无法使用或会被拒绝。

bash

和

read_file

运行在Agent的远程容器中，该容器内没有任何用户文件。无论哪种情况，请勿执行shell命令来定位或读取用户本地文件（如下载、桌面、文档文件夹）：

ls ~/Downloads

要么执行失败（无法使用/被拒绝），要么列出的是错误的文件系统。当任务涉及用户电脑上的文件（上传、附加、打开）时，唯一可靠的方式是使用浏览器原生文件选择器，而这只能由用户操作——请准确移交任务（详见

docs/file-uploads.md

）。尝试执行枚举用户文件系统的shell命令的行为绝对是错误的。

Stop: decide the surface before any browser action

注意：执行任何浏览器操作前先明确场景

Use the

mcp__browser__*

tools only when the task has explicit browser intent: the user asks to open, show, navigate to, click on, or fill in a page in their browser; the task depends on their logged-in sessions or existing tabs; or they want to watch an interaction happen live in Chrome.

Otherwise a URL or an open tab is context, not intent. For reading pages, looking things up, or research, prefer clawd's built-in web tools (

web_fetch

web_search

) — they are cheaper, faster, and do not touch the user's browser. Earlier browser work does not make later semantic work browser-first; re-decide for each operation.

When browser intent is clear, do not substitute

web_fetch

— fetching a page anonymously is not the same as acting in the user's authenticated browser.

仅当任务具有明确的浏览器操作意图时，才可使用

mcp__browser__*

工具：用户要求在其浏览器中打开、显示、导航至、点击或填写页面；任务依赖用户的已登录会话或现有标签页；或者用户希望实时观看Chrome中的交互过程。

否则，URL或打开的标签页只是上下文信息，而非操作意图。对于页面阅读、信息查询或研究场景，优先使用clawd内置的网页工具（

web_fetch

、

web_search

）——这些工具成本更低、速度更快，且不会触碰用户的浏览器。之前的浏览器操作不代表后续语义化工作必须优先使用浏览器；每次操作都需重新判断。

当明确存在浏览器操作意图时，请勿用

web_fetch

替代——匿名获取页面与在用户已认证的浏览器中操作完全不同。

What these tools are

这些工具是什么

The

browser

MCP server (server="browser", tools named

mcp__browser__<name>

) is backed by the user's Chrome extension over a bridge connection. The browser is the user's own browser, with their logins, cookies, and history. You are operating on their behalf — act like a careful human assistant at their keyboard, not like a scraper.

Core loop:

```
page_snapshot
```
— read the page before touching it. Omit
```
tabId
```
to target the user's currently active tab.
Pick the target element from
```
snapshot.elements[]
```
(each has
```
id
```
,
```
tag
```
,
```
text
```
,
```
ariaLabel
```
). The
```
id
```
is the
```
ref
```
for interaction tools.
```
element_click
```
/
```
element_input
```
to act.
```
page_snapshot
```
again to verify the effect.

Refs are invalidated by navigation. After any navigation, reload, or observed page change, take a fresh

page_snapshot

before clicking or typing. Never reuse a

ref

across a navigation boundary.

browser

MCP服务器（server="browser"，工具命名为

mcp__browser__<name>

）通过桥接连接由用户的Chrome扩展提供支持。该浏览器是用户自己的浏览器，包含其登录信息、Cookie和浏览历史。你代表用户进行操作——要像坐在用户键盘前的细心助手一样行事，而非爬虫。

核心流程：

```
page_snapshot
```
—— 在操作页面之前先读取页面内容。省略
```
tabId
```
则以用户当前活跃标签页为目标。
从
```
snapshot.elements[]
```
中选择目标元素（每个元素包含
```
id
```
、
```
tag
```
、
```
text
```
、
```
ariaLabel
```
）。
```
id
```
是交互工具的
```
ref
```
。
使用
```
element_click
```
/
```
element_input
```
执行操作。
再次调用
```
page_snapshot
```
验证操作效果。

页面导航会使Ref失效。在任何导航、重载或检测到页面变化后，必须先获取新的

page_snapshot

，再进行点击或输入操作。切勿跨导航边界重复使用同一个

ref

。

Tool quick reference

工具速查

```
tabs_list
```
— list open tabs with full metadata (
```
tabId
```
,
```
windowId
```
,
```
index
```
,
```
pinned
```
,
```
incognito
```
,
```
status
```
,
```
url
```
,
```
title
```
, ...) plus a window summary; tabs link to windows via
```
windowId
```
. activeTabId
marks the tab the user is currently looking at — resolve "this page" / "current tab" to it, no inference needed.
```
tab_open {url, active?}
```
— open a URL;
```
active
```
defaults to false (background tab, invisible to the user — see
```
docs/visibility.md
```
).
```
tab_navigate {tabId, url}
```
— navigate an existing tab.
```
tab_close {tabId}
```
— close a tab.
```
page_snapshot {tabId?}
```
—
```
{tabId, title, url, bodyText (first ~3000 chars), elements[]}
```
. Omit
```
tabId
```
for the user's active tab.
```
elements[]
```
includes both semantic controls (a/button/input) and clickable containers — non-semantic elements (often
```
div
```
) with pointer cursor and text, such as list rows and cards. A container and the small button inside it (e.g. a row's ⋮ menu) are distinct refs: match by text to pick the right one.
```
element_click {ref, confirm?}
```
— click an element. Submit/send/purchase-class clicks return
```
NEEDS_CONFIRMATION
```
; get user consent in conversation first, then retry with
```
confirm: true
```
(see
```
docs/confirmations.md
```
).
```
element_input {ref, text}
```
— type into an element.
```
elements_click_many {selector, text?, limit?, mode?, pauseMs?, confirm?}
```
— batch-click many matching elements in order. Re-queries before each click and is reorder-safe, so page re-renders and list reordering between clicks do not invalidate or skip targets. Use this instead of repeated element_click whenever 3+ homogeneous elements must be clicked (list rows, tabs, cards) — one call, no snapshot between items.
```
tab_claim {tabId?, note?}
```
— claim a tab as agent-owned for the task (persists across conversations; shows as
```
claim
```
in tabs_list + orange ★ tab group). Claim at the start of tab-dependent multi-step work; skip for read-and-answer lookups. See
```
docs/tab-claiming-chrome.md
```
for the scenario playbook.
```
tab_handoff {tabId, note?}
```
— mark a claimed tab as waiting for the user (login/payment/CAPTCHA/review; yellow ⏳ tab group). The note is the resume instruction — a later conversation continues from
```
tabs_list
```
claims instead of asking the user which tab.
```
tab_release {tabId, disposition?}
```
— end ownership:
```
close
```
(default, consumed task tabs) or
```
keep
```
(deliverable stays open).
```
page_flow {steps, confirm?}
```
— run a multi-step page flow in ONE call (fenced script equivalent). Steps:
```
{wait:{selector?,text?,ms?}}
```
,
```
{find:{selector?,text?}}
```
,
```
{click:{selector?,text?}}
```
,
```
{type:{selector?,text?,value}}
```
,
```
{expect:{selector?,text?,absent?}}
```
. Targets resolve by CSS selector or visible text. Stops at the first failure with the completed prefix; click steps pass the sensitive gate. Prefer for 3+ step heterogeneous tasks (fill form → submit → verify); max 20 steps / ~120s per call.
```
page_screenshot
```
— visual check, only when seeing matters. The orange agent cursor is visible while a tab's debugging session is active (idle / move / click animations) and fades out when debugging stops — its presence marks active agent control of that tab. (see
```
docs/screenshots.md
```
).
```
wait_for {selector?, text?, timeoutMs?}
```
— wait for a selector or text.
```
web_status
```
— bridge/extension connection health.

```
tabs_list
```
—— 列出所有打开的标签页及完整元数据（
```
tabId
```
、
```
windowId
```
、
```
index
```
、
```
pinned
```
、
```
incognito
```
、
```
status
```
、
```
url
```
、
```
title
```
等），同时包含窗口摘要；标签页通过
```
windowId
```
关联到对应窗口。activeTabId
标记用户当前查看的标签页——无需推断，直接将“此页面”/“当前标签页”映射到该值即可。
```
tab_open {url, active?}
```
—— 打开指定URL；
```
active
```
默认值为false（后台标签页，对用户不可见——详见
```
docs/visibility.md
```
）。
```
tab_navigate {tabId, url}
```
—— 导航至现有标签页的指定URL。
```
tab_close {tabId}
```
—— 关闭指定标签页。
```
page_snapshot {tabId?}
```
—— 返回结果包含
```
{tabId, title, url, bodyText（前约3000字符）, elements[]}
```
。省略
```
tabId
```
则以用户活跃标签页为目标。
```
elements[]
```
既包含语义化控件（a/button/input），也包含可点击容器——带有指针光标和文本的非语义化元素（通常是
```
div
```
），例如列表行和卡片。容器与其内部的小按钮（如行内的⋮菜单）是不同的ref：通过文本匹配选择正确的元素。
```
element_click {ref, confirm?}
```
—— 点击指定元素。提交/发送/购买类点击会返回
```
NEEDS_CONFIRMATION
```
；需先在对话中获得用户同意，再使用
```
confirm: true
```
重试（详见
```
docs/confirmations.md
```
）。
```
element_input {ref, text}
```
—— 在指定元素中输入文本。
```
elements_click_many {selector, text?, limit?, mode?, pauseMs?, confirm?}
```
—— 按顺序批量点击多个匹配元素。每次点击前会重新查询，且支持重排序安全，因此点击之间的页面重渲染和列表重排序不会导致目标失效或被跳过。当需要点击3个及以上同类元素时（列表行、标签页、卡片），优先使用该工具而非重复调用element_click——仅需一次调用，无需在每个元素之间获取截图。
```
tab_claim {tabId?, note?}
```
—— 将指定标签页标记为Agent任务专属（跨会话持久化；在tabs_list中显示为
```
claim
```
，并归类到橙色★标签组）。在依赖标签页的多步骤工作开始时进行认领；仅需读取并回答的查询场景可跳过此步骤。场景手册详见
```
docs/tab-claiming-chrome.md
```
。
```
tab_handoff {tabId, note?}
```
—— 将已认领的标签页标记为等待用户操作（登录/支付/CAPTCHA/审核；归类到黄色⏳标签组）。备注信息为恢复指令——后续对话可从tabs_list的认领记录继续，无需询问用户具体是哪个标签页。
```
tab_release {tabId, disposition?}
```
—— 结束标签页所有权：
```
close
```
（默认值，关闭任务已完成的标签页）或
```
keep
```
（保留可交付内容的标签页）。
```
page_flow {steps, confirm?}
```
—— 一次调用完成多步骤页面流程（等效于 fenced script）。步骤类型包括：
```
{wait:{selector?,text?,ms?}}
```
、
```
{find:{selector?,text?}}
```
、
```
{click:{selector?,text?}}
```
、
```
{type:{selector?,text?,value}}
```
、
```
{expect:{selector?,text?,absent?}}
```
。目标通过CSS选择器或可见文本匹配。首次失败时停止并返回已完成的步骤前缀；点击步骤会触发敏感操作校验。当任务包含3个及以上异构步骤时优先使用（填写表单→提交→验证）；每次调用最多支持20个步骤/约120秒。
```
page_screenshot
```
—— 视觉检查，仅在需要查看页面视觉效果时使用。当标签页的调试会话处于活跃状态时（空闲/移动/点击动画），橙色Agent光标会显示，调试停止后逐渐消失——该光标的存在表示Agent正在主动控制该标签页。（详见
```
docs/screenshots.md
```
）。
```
wait_for {selector?, text?, timeoutMs?}
```
—— 等待指定选择器或文本出现。
```
web_status
```
—— 桥接/扩展连接健康状态。

On-demand documentation

按需文档

Load these with

read_file

(paths relative to this skill's

docs/

directory) when the topic applies — do not read them all up front:

```
api-use-behavior.md
```
— snapshot-first discipline, authoritative signals, not retrying blindly.
```
browser-safety.md
```
— untrusted page content, sensitive-data transmission.
```
confirmations.md
```
— when
```
confirm: true
```
is required and how to ask.
```
browser-troubleshooting.md
```
— evaluate timeouts, stale refs, hung pages.
```
chrome-troubleshooting.md
```
— extension disconnected, tools missing, user has no extension.
```
bootstrap-troubleshooting.md
```
— bridge connection failures (red dot).
```
browser-control-interruption.md
```
— user took over, operation interrupted.
```
tab-claiming-chrome.md
```
— background tab vs. user tab, when to go active.

tab-cleanup-chrome.md

all-tabs-cleanup.md

— closing tabs you opened.

```
screenshots.md
```
— when a screenshot is worth taking.
```
visibility.md
```
— what background-tab operation means for the user.
```
webmcp.md
```
— page-level WebMCP (not yet enabled).
```
file-uploads.md
```
— file upload support (not yet available).
```
local-web-development.md
```
— working against localhost dev servers.

当涉及相关主题时，使用

read_file

加载以下文档（路径相对于本技能的

docs/

目录）——无需提前全部阅读：

```
api-use-behavior.md
```
—— 优先截图原则、权威信号、避免盲目重试。
```
browser-safety.md
```
—— 不可信页面内容、敏感数据传输。
```
confirmations.md
```
—— 何时需要
```
confirm: true
```
以及如何向用户确认。
```
browser-troubleshooting.md
```
—— 超时、失效ref、页面卡顿问题排查。
```
chrome-troubleshooting.md
```
—— 扩展断开连接、工具缺失、用户未安装扩展问题排查。
```
bootstrap-troubleshooting.md
```
—— 桥接连接失败（红点标记）问题排查。
```
browser-control-interruption.md
```
—— 用户接管、操作中断问题处理。
```
tab-claiming-chrome.md
```
—— 后台标签页vs用户标签页、何时切换为活跃标签页。

tab-cleanup-chrome.md

all-tabs-cleanup.md

—— 关闭你打开的标签页。

```
screenshots.md
```
—— 何时值得截取截图。
```
visibility.md
```
—— 后台标签页操作对用户的影响。
```
webmcp.md
```
—— 页面级WebMCP（尚未启用）。
```
file-uploads.md
```
—— 文件上传支持（尚未可用）。
```
local-web-development.md
```
—— 针对本地主机开发服务器的操作。

Talk like a person

用自然语言与用户交流

Never mention CDP, WebSocket,

/ws/web-mcp

, refs, tool IDs, or other internal terms to the user. Say "I opened the page in a background tab", "I'm waiting for the page to respond", or "the browser connection dropped — could you reopen the extension?" Describe what you did, not how the machinery works.

切勿向用户提及CDP、WebSocket、

/ws/web-mcp

、refs、工具ID或其他内部术语。可以说“我在后台标签页中打开了该页面”“我正在等待页面响应”或“浏览器连接断开——你能否重新打开扩展？”。描述你执行的操作，而非底层机制的工作原理。