---
title: "Browser Tool"
description: "基于 Cursor 官方 Browser 文档解释浏览器验证、console、network、设计侧栏、approval 和企业 allowlist。"
verifiedAt: "2026-05-09"
---

Cursor Browser Tool 让 Agent 控制浏览器，用于测试应用、视觉编辑布局、审计 accessibility、把设计转代码、调试 UI 和自动化测试流程。官方文档强调它能访问 console logs 和 network traffic，所以它不只是“截图工具”。

> [!NOTE]
> **阅读目标**：读完本章，你应该能让 Agent 用 Browser 验证本地 UI，并知道什么时候必须要求 manual approval 和 origin allowlist。

## 1. Browser 能做什么

官方列出的 browser capabilities：

| 能力 | 用途 |
| --- | --- |
| Navigate | 打开 URL、跟链接、前进后退、刷新 |
| Click | 点击、双击、右键、hover 可见元素 |
| Type | 填表单、搜索框、textarea |
| Scroll | 浏览长页面，找到隐藏内容 |
| Screenshot | 截图验证布局和视觉状态 |
| Console Output | 读取 JS 错误、日志和 warning |
| Network Traffic | 监控请求、响应、状态码和 payload |

```mermaid
flowchart TD
  UI["UI task"] --> Browser["Cursor Browser"]
  Browser --> Screenshot["Screenshot"]
  Browser --> Console["Console output"]
  Browser --> Network["Network traffic"]
  Browser --> Action["Click / Type / Scroll"]
  Screenshot --> Evidence["Visual evidence"]
  Console --> Debug["Runtime debugging"]
  Network --> API["API diagnosis"]
```

## 2. Native integration 的意义

官方文档说明 Browser actions、screenshots 会显示在 chat，也可以在 separate window 或 inline pane 中显示 browser window。Cursor 还优化了几件事：

- browser logs 写入文件，Agent 可以 grep 并选择性读取。
- screenshot 直接作为图片进入 file reading tool。
- Agent 会收到日志总行数和 preview snippets。
- Agent 会检测 running development servers 和正确端口，避免重复启动或猜端口。

这对网站断点和 UI 验收很重要：Agent 应该先识别已有 dev server，再打开正确端口截图，不应该随便另启一个服务。

## 3. Design sidebar 和视觉修改

官方 Browser 文档说明，Browser 包含 design sidebar，可以在 Cursor 里直接调整站点。

可调整：

| 类型 | 例子 |
| --- | --- |
| Position and layout | flex、grid、alignment |
| Dimensions | width、height、padding、margin |
| Colors | design tokens、color picker、gradient |
| Appearance | shadow、opacity、border radius |
| Theme testing | light / dark themes |

当视觉调整符合预期后，点击 apply 会触发 agent 更新代码。也可以选择多个元素并用文本描述改动。

> [!IMPORTANT]
> 视觉调整必须回到代码 diff。不要只看浏览器里“临时调好了”，最终要确认代码已经正确改动。

## 4. Tool approval 和安全模式

官方安全说明列出三种 approval 模式：

| Mode | 含义 |
| --- | --- |
| Manual approval | 每个 browser action 都要 review 和 approve，推荐 |
| Allow-listed actions | allow list 匹配的动作自动跑，其他要审批 |
| Auto-run | 全部自动执行，谨慎使用 |

官方明确提醒：不要在 untrusted code 或 unfamiliar websites 上使用 auto-run。Agent 可能执行恶意脚本或提交敏感数据。

## 5. 企业控制和 Origin Allowlist

企业用户可通过 MCP controls 管理 Browser。官方说明管理员可以：

- 在 MCP Configuration 中开启 browser features。
- 配置 Browser Origin Allowlist（按 origin 白名单，origin = 协议+域名+端口，如 `https://example.com:443`）。
- 限制 agent 自动导航到哪些 origin。
- 控制 MCP tools 能在哪些 origin 上运行。

重要边界：

- 用户仍可手动导航到 allowlist 外 URL。
- 但一旦在非 allowlist origin，browser tools 会被阻止。
- Redirect、link navigation、client-side navigation 有 edge cases，需要定期审查 allowlist。

<details>
<summary>深读：为什么 Browser 是断点验收的关键工具</summary>

代码 diff 看不出按钮是否在 390px 宽度溢出，也看不出移动端菜单是否遮挡内容。Browser Tool 能同时提供 screenshot、console、network 和交互路径证据，适合做真实 UI 断点检查。

对教程站这类文档站，最低应检查首页、导航、搜索、教程目录、正文页、代码块、表格、Cards、details、Mermaid 在 mobile、tablet、desktop 下是否溢出或遮挡。
</details>

## 本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. Browser Tool 除了截图，还能读取哪些运行时证据？
2. Manual approval、Allow-listed actions、Auto-run 的风险差异是什么？
3. 企业 Origin Allowlist 能控制什么，不能完全阻止什么 edge case？

通过标准：你能写出一条本地 UI 验收任务，要求 Cursor 检查 viewport、截图、console、network 和 diff。

## 官方来源

- [Cursor Browser Tool](https://cursor.com/docs/agent/tools/browser.md) —— 官方说明 browser capabilities、native integration、design sidebar、approval、security 和 enterprise origin allowlist。
- [Cursor Browser Help](https://cursor.com/help/ai-features/browser.md) —— Help Center 说明浏览器打开、点击、填表和截图能力。

## 接下来去哪

<Cards>
  <Card title="Search Tool" description="继续理解 semantic search、Instant Grep、indexing 和 Explore subagent。" href="/docs/cursor/official/01-agent-workflow/18-search-tool" />
  <Card title="Agent Security" description="把 Browser approval 和 allow/block list 放进安全策略。" href="/docs/cursor/official/01-agent-workflow/21-agent-security" />
</Cards>
