OpenClaw 2026.4.9 浏览器自动化配置完全指南

概述

OpenClaw 2026.4.9 提供强大的浏览器自动化能力，支持两种模式：

• OpenClaw托管模式：独立浏览器实例，自动管理生命周期
• 已登录Chrome模式：连接现有Chrome会话，复用登录状态

本文档详细讲解配置步骤和使用方法。

---

一、配置步骤

1.1 配置文件修改

编辑配置文件：~/.openclaw/openclaw.json

{
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "your-gateway-token"
    },
    "remote": {
      "token": "your-gateway-token"
    }
  },
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "headless": false,
    "profiles": {
      "openclaw": {
        "driver": "openclaw",
        "cdpPort": 18800,
        "color": "#4ECDC4"
      },
      "my-logged-in-chrome": {
        "driver": "existing-session",
        "attachOnly": true,
        "cdpUrl": "http://localhost:9222",
        "color": "0000FF"
      }
    }
  },
  "plugins": {
    "entries": {
      "browser": {
        "enabled": true
      }
    }
  }
}

1.2 配置说明

字段	值	说明
browser.enabled	true	启用浏览器功能
browser.defaultProfile	"openclaw"	默认使用的profile
browser.headless	false	是否无头模式
gateway.remote.token	与 gateway.auth.token 保持一致	Gateway连接token

1.3 Profile配置详解

Profile 1: openclaw（OpenClaw托管）

"openclaw": {
  "driver": "openclaw",
  "cdpPort": 18800,
  "color": "#4ECDC4"
}

特点：

• ✅ 自动启动和管理浏览器
• ✅ 独立用户数据目录
• ✅ 无需手动干预
• ⚠️ 需要重新登录网站

适用场景：

• 自动化测试
• 数据采集
• 网页爬虫
• 批量操作

Profile 2: my-logged-in-chrome（已登录Chrome）

"my-logged-in-chrome": {
  "driver": "existing-session",
  "attachOnly": true,
  "cdpUrl": "http://localhost:9222",
  "color": "0000FF"
}

特点：

• ✅ 复用现有登录状态
• ✅ 保留Cookie和Session
• ✅ 绕过二次验证
• ⚠️ 需要手动启动Chrome（带远程调试端口）

适用场景：

• 操作已登录的重要网站（银行、交易所）
• 需要登录状态的操作
• 避免重复登录验证

---

二、操作流程

2.1 OpenClaw托管模式（推荐）

启动Gateway

openclaw gateway restart

使用浏览器（自动启动）

方式1：直接使用

browser({
  action: "navigate",
  url: "https://www.baidu.com"
})

OpenClaw会自动启动浏览器，无需手动操作。

方式2：显式启动

browser({
  action: "start",
  profile: "openclaw"
})

检查浏览器状态

browser({
  action: "status"
})

返回示例：

{
  "enabled": true,
  "profile": "openclaw",
  "running": true,
  "cdpReady": true,
  "pid": 18680,
  "cdpPort": 18800,
  "userDataDir": "C:\\Users\\xxx\\.openclaw\\browser\\openclaw\\user-data"
}

基本操作流程

步骤1: 导航到网页
browser({ action: "navigate", url: "https://example.com" })

步骤2: 获取页面快照（查看结构）
browser({ action: "snapshot" })

步骤3: 根据快照定位元素（使用ref）

步骤4: 执行操作
browser({
  action: "act",
  request: {
    kind: "type",
    ref: "e13",
    text: "输入内容"
  }
})

2.2 已登录Chrome模式（需手动启动）

步骤1：关闭所有Chrome进程

Windows：

# 任务管理器 → 详细信息 → 结束所有 chrome.exe 进程
task kill /F /IM chrome.exe /T

macOS/Linux：

pkill -9 chrome

步骤2：以管理员身份启动Chrome

Windows PowerShell：

# 以管理员身份运行
Start-Process "C:\Users\YourName\AppData\Local\Google\Chrome\Application\chrome.exe" -ArgumentList "--remote-debugging-port=9222"

macOS：

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Linux：

google-chrome --remote-debugging-port=9222

步骤3：验证远程调试端口

# Windows
netstat -ano | findstr :9222

期望输出：

TCP    127.0.0.1:9222    0.0.0.0:0    LISTENING    xxxx

或访问调试接口：

Invoke-WebRequest -Uri "http://127.0.0.1:9222/json/version"

期望返回：

{
  "Browser": "Chrome/147.0.7727.55",
  "Protocol-Version": "1.3",
  "webSocketDebuggerUrl": "ws://127.0.0.1:9222/devtools/browser/..."
}

步骤4：使用已登录Chrome

browser({
  profile: "my-logged-in-chrome",
  action: "navigate",
  url: "https://mail.google.com"
})

Chrome会使用您的登录状态，无需重新登录。

---

三、常用操作示例

3.1 导航和快照

// 导航到网页
browser({
  action: "navigate",
  url: "https://www.example.com"
})

// 获取页面快照（查看页面结构和元素）
browser({
  action: "snapshot"
})

快照输出示例：

- document:
  - link "新闻" [ref=e1]
  - textbox [ref=e13]
  - button "搜索" [ref=e14]

使用ref定位元素：

• 每个元素有唯一的 ref 标识（如 e13）
• 在后续操作中使用 ref 定位元素

3.2 表单填写

// 输入文本
browser({
  action: "act",
  request: {
    kind: "type",
    ref: "e13",  // 搜索框的ref
    text: "OpenClaw 浏览器自动化"
  }
})

// 点击按钮
browser({
  action: "act",
  request: {
    kind: "click",
    ref: "e14"  // 搜索按钮的ref
  }
})

3.3 其他操作

操作类型	参数示例	说明
type	{ kind: "type", ref: "e13", text: "内容" }	输入文本
click	{ kind: "click", ref: "e14" }	点击元素
hover	{ kind: "hover", ref: "e15" }	鼠标悬停
fill	{ kind: "fill", ref: "e13", text: "内容" }	填充表单
press	{ kind: "press", key: "Enter" }	按键操作
wait	{ kind: "wait", timeMs: 1000 }	等待时间
select	{ kind: "select", ref: "e16", values: ["option1"] }	下拉选择
drag	{ kind: "drag", startRef: "e17", endRef: "e18" }	拖拽操作

3.4 页面截图

browser({
  action: "screenshot",
  path: "C:/temp/page-screenshot.png",
  fullPage: true
})

3.5 关闭浏览器

browser({
  action: "stop"
})

---

四、实际案例

案例1：百度搜索自动化

// 1. 导航到百度
browser({ action: "navigate", url: "https://www.baidu.com" })

// 2. 获取快照查看元素
browser({ action: "snapshot" })
// 输出: textbox [ref=e13], button [ref=e14]

// 3. 输入搜索内容
browser({
  action: "act",
  request: { kind: "type", ref: "e13", text: "OpenClaw教程" }
})

// 4. 点击搜索
browser({
  action: "act",
  request: { kind: "click", ref: "e14" }
})

// 5. 等待加载后获取结果
browser({ action: "snapshot" })

案例2：网页数据采集

// 1. 打开目标网站
browser({ action: "navigate", url: "https://example.com/products" })

// 2. 获取页面结构
browser({ action: "snapshot" })

// 3. 提取数据（从快照中识别产品列表）

// 4. 分页采集
browser({
  action: "act",
  request: { kind: "click", ref: "next-page-button" }
})

// 5. 重复采集...

案例3：批量表单填写

// 1. 导航到表单页面
browser({ action: "navigate", url: "https://example.com/form" })

// 2. 获取快照
browser({ action: "snapshot" })

// 3. 填写多个字段
browser({
  action: "act",
  request: { kind: "fill", ref: "name-field", text: "张三" }
})

browser({
  action: "act",
  request: { kind: "fill", ref: "email-field", text: "test@example.com" }
})

// 4. 提交表单
browser({
  action: "act",
  request: { kind: "click", ref: "submit-button" }
})

---

五、最佳实践

5.1 Profile选择建议

场景	推荐Profile	原因
自动化测试	openclaw	环境独立，便于重现
数据采集	openclaw	无需登录状态
操作已登录网站	my-logged-in-chrome	复用登录，避免验证
批量操作	openclaw	自动管理，稳定可靠

5.2 自动管理机制

OpenClaw托管浏览器（openclaw profile）具有完整的生命周期管理：

功能	说明
自动启动	需要时自动启动，无需手动操作
自动重启	崩溃后自动恢复
自动清理	Gateway关闭时自动清理
进程隔离	独立进程，不影响系统浏览器

结论：使用 openclaw profile时，完全不需要手动管理浏览器生命周期。

5.3 错误处理

常见错误及解决方案：

错误	原因	解决方案
gateway connect failed: unauthorized	token不匹配	确保 gateway.remote.token 与 gateway.auth.token 一致
Could not connect to Chrome	远程调试端口未开启	手动启动Chrome（带 --remote-debugging-port=9222）
Element not found	元素ref不存在	先获取快照，使用正确的ref
timeout	页面加载慢	增加等待时间

---

六、进阶配置

6.1 超时配置

编辑 openclaw.json：

{
  "agents": {
    "defaults": {
      "timeoutSeconds": 600  // 增加超时时间（默认300秒）
    }
  }
}

重启Gateway：

openclaw gateway restart

6.2 多Profile配置

支持同时配置多个浏览器实例：

"browser": {
  "profiles": {
    "openclaw": {
      "driver": "openclaw",
      "cdpPort": 18800
    },
    "work": {
      "driver": "openclaw",
      "cdpPort": 18801
    },
    "my-logged-in-chrome": {
      "driver": "existing-session",
      "cdpUrl": "http://localhost:9222"
    }
  }
}

使用不同profile：

browser({ profile: "work", action: "navigate", url: "..." })

6.3 Headless模式

适合服务器环境：

"browser": {
  "headless": true,
  "profiles": {
    "openclaw": {
      "driver": "openclaw",
      "headless": true
    }
  }
}

---

七、常见问题FAQ

Q1: 浏览器会自动关闭吗？

A: 不会。Gateway运行期间浏览器保持运行。Gateway关闭时浏览器会自动清理。

Q2: 需要手动重启浏览器吗？

A: 使用 openclaw profile时不需要。OpenClaw自动管理所有生命周期。

Q3: 如何使用已登录的Chrome？

A: 需要手动以管理员身份启动Chrome，带上参数 --remote-debugging-port=9222。详见第二章。

Q4: 远程调试端口无法开启怎么办？

A: 常见原因：

1. Chrome后台进程干扰（完全关闭Chrome后再启动）
2. Windows防火墙限制（以管理员身份运行）
3. 端口被占用（检查端口占用情况）

Q5: 如何查看Gateway日志？

A:

openclaw logs --follow

Q6: 配置修改后如何生效？

A:

openclaw gateway restart

---

八、版本信息

当前版本: OpenClaw 2026.4.9

主要特性：

• ✅ Chrome DevTools Protocol支持
• ✅ 自动浏览器生命周期管理
• ✅ 已登录Chrome会话复用
• ✅ 多Profile并发支持
• ✅ 批处理操作优化
• ✅ 智能元素定位

---

九、参考资料

• OpenClaw官方文档：https://docs.openclaw.ai
• Chrome DevTools Protocol：https://chromedevtools.github.io/devtools-protocol/
• OpenClaw GitHub：https://github.com/openclaw/openclaw
• 技术社区：https://discord.com/invite/clawd

---

十、总结

OpenClaw 2026.4.9 提供两种浏览器自动化模式：

1. OpenClaw托管模式（推荐）

   • 完全自动化管理
   • 无需手动干预
   • 稳定可靠
   • 适合大多数场景

2. 已登录Chrome模式

   • 复用登录状态
   • 需手动启动Chrome
   • 适合特殊网站操作

推荐使用流程：

配置 → Gateway重启 → 直接使用 → 无需手动管理

OpenClaw让浏览器自动化变得简单、可靠、高效！