---
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="/zh-Hant/docs/cursor/official/01-agent-workflow/18-search-tool" />
  <Card title="Agent Security" description="把 Browser approval 和 allow/block list 放進安全策略。" href="/zh-Hant/docs/cursor/official/01-agent-workflow/21-agent-security" />
</Cards>
