browser-profile-guide

name	browser-profile-guide
description	OpenClaw Browser 配置文件系统完全指南 — 哪个 profile 何时用、如何选
trigger	browser profile / 浏览器配置 / openclaw browser / 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" 等待网络空闲