aaaaqwq/browser-profile-guide

OpenClaw Browser Profile 完整指南

三种 Profile 用途速查

| Profile | 驱动 | 登录态 | 何时用 | 是否需要手动开浏览器 | |---------|------|--------|--------|-------------------| | openclaw（默认） | Playwright + Chrome CDP | ❌ 全新干净浏览器 | 自动化、批量操作、不需要登录 | ❌ 自动启动 | | user | Playwright + Chrome CDP | ✅ 复用你已有的 Chrome 登录态 | 需要 GitHub/邮箱等已登录网站 | ✅ 需先手动开 Chrome | | sandbox | Docker 内 Playwright | ❌ 隔离容器内全新浏览器 | 安全敏感操作 | ❌ 自动启动 |

你的当前配置（~/.openclaw/openclaw.json）

"browser": {
  "headless": false,
  "noSandbox": true,
  "profiles": {
    "user": {
      "attachOnly": true,    // 只连接已开的浏览器，不自动启动
      "cdpPort": 9222,       // Chrome 远程调试端口
      "driver": "openclaw",
      "color": "#00AA00"
    }
  }
}

注意：openclaw profile 没有显式定义，但是默认 profile，OpenClaw 会自动创建。

默认 Profile：openclaw（最常用）

browser(action="open", profile="openclaw", url="https://github.com")
browser(action="snapshot", profile="openclaw")
browser(action="act", profile="openclaw", ref="e1", kind="click")

• OpenClaw 自动管理浏览器生命周期
• 每次启动是干净的浏览器环境
• CDP 端口：18800（openclaw profile）

user Profile — 复用已有登录态

前置条件：你必须先手动打开 Chrome 并启用远程调试

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/Library/Application Support/Google/Chrome"

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

你的配置里 user profile 已设为 attachOnly: true，意味着：

• 如果 Chrome 没开 → 不会自动启动 → 会报错
• Chrome 开着且端口 9222 在监听 → 自动连接

// 需要登录 GitHub？用 user profile
browser(action="open", profile="user", url="https://github.com")
browser(action="snapshot", profile="user")

统一规则（你们团队所有人遵守）

任务需要登录网站（GitHub/邮箱/社交媒体）
  → profile="user" + 先手动开 Chrome --remote-debugging-port=9222

普通自动化、批量操作、无需登录
  → profile="openclaw"（默认，可省略 profile 参数）

CDP 直连模式（更快）

当前配置已有 chromeCdp 模式（browser.chromeCdp: true），这让 OpenClaw 直接用 Chrome DevTools Protocol，绕过 Playwright 的额外开销。

常用操作示例

// 1. 普通自动化（用默认 openclaw profile）
browser(action="open", url="https://example.com")
browser(action="snapshot")

// 2. 需要登录的网站
browser(action="open", profile="user", url="https://github.com/settings/applications")
browser(action="snapshot")

// 3. 截图
browser(action="screenshot", fullPage=true)

// 4. 复杂交互（先用 snapshot 获取 refs）
browser(action="snapshot")
// → 拿到 @e1, @e2 等 refs
browser(action="act", ref="e1", kind="click")
browser(action="act", ref="e3", kind="type", text="hello world")

// 5. PDF 导出
browser(action="pdf")

故障排除

| 问题 | 解决 | |------|------| | profile="user" 报错 "browser not running" | 先手动开 Chrome：google-chrome --remote-debugging-port=9222 | | profile="openclaw" 报错 "CDP not reachable" | 重启 Gateway：openclaw gateway restart | | 浏览器开着但连不上 | 检查端口：lsof -i :9222，确认是 Chrome 在监听 | | 截图是空白页 | 加 loadState="networkidle" 等待网络空闲 |