概念

Browser tool 讓 Agent 能「看」和「操作」網頁 — 像是一個自動化的瀏覽器。

底層使用 CDP（Chrome DevTools Protocol） 控制 Chromium 瀏覽器。

兩種 Profile

Profile	說明
`openclaw`	獨立管理的瀏覽器（推薦）
`chrome`	透過 extension 控制你的瀏覽器

// openclaw.json
{
  "browser": {
    "defaultProfile": "openclaw",  // 預設用獨立瀏覽器
    "profiles": {
      "openclaw": { "cdpPort": 18800 }
    }
  }
}

主要操作

// 1. 開啟網頁
{ "tool": "browser", "action": "open", "targetUrl": "https://example.com" }

// 2. 取得頁面結構（給 AI 看）
{ "tool": "browser", "action": "snapshot" }

// 3. 截圖
{ "tool": "browser", "action": "screenshot" }

// 4. 點擊元素
{ "tool": "browser", "action": "act", "request": { "kind": "click", "ref": "button" } }

// 5. 輸入文字
{ "tool": "browser", "action": "act", "request": { "kind": "type", "ref": "input", "text": "Hello" } }

// 6. 導航
{ "tool": "browser", "action": "navigate", "targetUrl": "https://google.com" }

Snapshot vs Screenshot

特性	Snapshot	Screenshot
格式	Accessibility Tree（文字）	圖片
Token 消耗	低	高
AI 理解	容易	需要 vision
用途	頁面結構、點擊元素	視覺驗證

推薦： 大部分情況用 snapshot，只有需要「看」的時候用 screenshot

核心代碼

1. Snapshot 輸出

// snapshot 回傳 accessibility tree
{
  "action": "snapshot",
  "response": {
    "tree": [
      { "role": "button", "name": "Submit", "ref": "e12" },
      { "role": "textbox", "name": "Email", "ref": "e13" },
      { "role": "link", "name": "Sign up", "ref": "e14" }
    ]
  }
}

// Agent 可以用 ref 操作元素
{ "tool": "browser", "action": "act", "request": { "kind": "click", "ref": "e12" } }

2. CDP 連接

// Browser tool 透過 CDP 控制瀏覽器
async function connectBrowser(profile) {
  const cdpUrl = config.browser.profiles[profile].cdpUrl 
    || `http://127.0.0.1:${config.browser.profiles[profile].cdpPort}`;
  
  // 連接 Chrome DevTools Protocol
  const browser = await puppeteer.connect({ browserURL: cdpUrl });
  
  return browser;
}

3. 執行動作

async function executeAction(request) {
  const { kind, ref, text } = request;
  const page = await getCurrentPage();
  
  // 找到元素
  const element = await findElementByRef(page, ref);
  
  switch (kind) {
    case 'click':
      await element.click();
      break;
      
    case 'type':
      await element.type(text);
      break;
      
    case 'select':
      await element.select(...request.values);
      break;
      
    case 'hover':
      await element.hover();
      break;
  }
}

設定範例

// openclaw.json
{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "headless": false,           // 看到瀏覽器視窗
    "executablePath": "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    
    "profiles": {
      "openclaw": { "cdpPort": 18800, "color": "#FF4500" },
      "work": { "cdpPort": 18801, "color": "#0066CC" }
    }
  }
}

使用流程

// 1. 啟動瀏覽器
await browser({ action: "start", profile: "openclaw" });

// 2. 開啟網頁
await browser({ action: "open", targetUrl: "https://github.com" });

// 3. 取得頁面結構
const snapshot = await browser({ action: "snapshot" });

// 4. 根據 snapshot 找到要點的元素
// snapshot 裡有：{ role: "button", name: "Sign in", ref: "e25" }

// 5. 點擊
await browser({ action: "act", request: { kind: "click", ref: "e25" } });

// 6. 輸入
await browser({ action: "act", request: { kind: "type", ref: "e30", text: "user@example.com" } });

💡 關鍵洞察

Snapshot 是「眼睛」
- 比截圖更有效率
- AI 直接理解頁面結構
- 不需要 vision model
Ref 是元素 ID
- snapshot 給每個元素一個 ref
- 用 ref 操作，不用 CSS selector
- 更穩定、更可靠
Profile 隔離很重要
- openclaw profile 不影響你的瀏覽器
- 登入狀態分開
- Cookies 分開
Headless 可以省資源
- headless: true = 看不到視窗
- 適合伺服器環境
- Debug 時用 headless: false

🔗 核心檔案

Browser 文檔：/opt/homebrew/lib/node_modules/openclaw/docs/tools/browser.md
Chrome Extension：/opt/homebrew/lib/node_modules/openclaw/docs/tools/chrome-extension.md

明天： Security（sandbox, tool policies, SSRF protection）

Day 12: Browser Control（CDP, profiles, snapshots）