OpenClaw 实战指南

Appearance

10.2 托管浏览器配置 ​

想象一下这个场景：

你决定用托管模式来自动发小红书。

终端输入 openclaw browser start，等了半天没反应。

换了个命令 openclaw browser status，显示 "enabled": false。

你疑惑：浏览器功能不是默认开启的吗？

托管浏览器是 OpenClaw 自动化的核心能力，但配置不对，什么都干不了。这一节，我们用 20 分钟，把托管浏览器配置到位。

快速检查：浏览器是否可用 ​

在终端运行：

bash
openclaw browser status

如果看到类似这样的输出，说明浏览器服务正常：

json
{
  "running": true,
  "pid": 12345,
  "chosenBrowser": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}

如果显示 "enabled": false，需要在配置中开启浏览器功能。

配置文件详解 ​

浏览器配置位于 ~/.openclaw/openclaw.json。

基础配置 ​

json5
{
  "browser": {
    "enabled": true,                    // 开启浏览器功能
    "defaultProfile": "openclaw",       // 默认使用托管模式
    "headless": false,                  // 是否无头模式（不显示窗口）
    "noSandbox": false,                 // 是否禁用沙箱（Linux 可能需要）
    "color": "#FF4500",                 // 浏览器主题色（橙色）
    "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  }
}

关键配置项说明 ​

配置项说明默认值
enabled是否启用浏览器功能true
defaultProfile默认使用的配置文件chrome
headless无头模式，不显示浏览器窗口false
noSandbox禁用沙箱（某些 Linux 环境需要）false
color浏览器窗口边框颜色#FF4500（橙色）
executablePath浏览器可执行文件路径自动检测

试一试：基础配置流程 ​

第一步：开启浏览器功能

bash
openclaw config set browser.enabled true

第二步：设置默认配置文件为 openclaw

bash
openclaw config set browser.defaultProfile "openclaw"

第三步：设置浏览器路径（可选）

OpenClaw 会自动检测系统默认的 Chromium 系浏览器（Chrome、Brave、Edge、Chromium）。如果你想指定特定浏览器：

bash
# macOS 使用 Brave
openclaw config set browser.executablePath "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"

# Linux 使用 Chrome
openclaw config set browser.executablePath "/usr/bin/google-chrome-stable"

# Windows 使用 Edge
openclaw config set browser.executablePath "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe"

第四步：重启 Gateway

bash
openclaw gateway restart

第五步：测试启动

bash
openclaw browser start
openclaw browser open https://www.baidu.com

看到橙色浏览器窗口弹出并打开百度，配置成功。

多配置文件支持 ​

如果你有多个账号需要管理（比如多个小红书账号），可以创建多个浏览器配置文件：

json5
{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "profiles": {
      "openclaw": {
        "cdpPort": 18800,
        "color": "#FF4500"
      },
      "work": {
        "cdpPort": 18801,
        "color": "#0066CC"
      },
      "personal": {
        "cdpPort": 18802,
        "color": "#00AA00"
      }
    }
  }
}

每个配置文件有独立的：

  • 用户数据目录（Cookie、登录状态隔离）
  • CDP 端口（互不干扰）
  • 主题颜色（便于区分）

试一试：创建多账号配置 ​

bash
# 创建工作账号配置文件
openclaw browser create-profile \
  --name work \
  --cdp-port 18801 \
  --color "#0066CC"

# 创建个人账号配置文件
openclaw browser create-profile \
  --name personal \
  --cdp-port 18802 \
  --color "#00AA00"

使用时指定配置文件：

bash
# 工作账号操作
openclaw browser --browser-profile work open https://xiaohongshu.com

# 个人账号操作
openclaw browser --browser-profile personal open https://weibo.com

每个配置文件的登录状态完全隔离，互不干扰。

远程 CDP 配置 ​

如果你在其他机器上运行浏览器，可以通过远程 CDP 连接：

json5
{
  "browser": {
    "profiles": {
      "remote": {
        "cdpUrl": "http://10.0.0.42:9222",
        "color": "#00AA00"
      }
    }
  }
}

这适用于：

  • 浏览器运行在远程服务器
  • 使用 Browserless 等托管服务
  • 通过 Tailscale 连接远程机器

常用 CLI 命令速查 ​

浏览器生命周期 ​

bash
# 查看状态
openclaw browser status

# 启动浏览器
openclaw browser start

# 停止浏览器
openclaw browser stop

# 重启浏览器
openclaw browser restart

标签页操作 ​

bash
# 列出所有标签页
openclaw browser tabs

# 打开新标签页
openclaw browser open https://example.com

# 切换到指定标签页
openclaw browser focus <targetId>

# 关闭标签页
openclaw browser close <targetId>

页面快照与截图 ​

bash
# 获取页面快照（AI 可读的文本描述）
openclaw browser snapshot

# 截图当前视口
openclaw browser screenshot

# 截图整个页面
openclaw browser screenshot --full-page

# 生成 PDF
openclaw browser pdf

故障排查 ​

问题 1："Failed to start Chrome CDP on port 18800" ​

原因：Linux 上默认的 Chromium 是 snap 包，受 AppArmor 限制。

解决方案：安装官方 Google Chrome

bash
# Ubuntu/Debian
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt --fix-broken install -y

# 配置 OpenClaw
openclaw config set browser.executablePath "/usr/bin/google-chrome-stable"
openclaw config set browser.headless true
openclaw config set browser.noSandbox true

问题 2：端口被占用 ​

现象：启动时报错端口 18800 已被占用。

解决方案：修改配置文件中的 cdpPort：

json5
{
  "browser": {
    "profiles": {
      "openclaw": {
        "cdpPort": 18803  // 换一个端口
      }
    }
  }
}

问题 3：浏览器闪退 ​

可能原因： 1。 可执行路径错误 2。 权限不足 3。 与系统浏览器冲突

排查步骤：

bash
# 检查路径是否正确
ls -la "$(openclaw config get browser.executablePath)"

# 尝试用命令行直接启动浏览器
/Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome --remote-debugging-port=18800

# 查看 Gateway 日志
openclaw gateway logs

问题 4：无头模式（headless）下某些网站无法操作 ​

注意：某些网站能检测无头模式。如果需要模拟真实用户，保持 headless: false。

这一节，你做了什么 ​

学了什么核心理解
配置文件位置~/.openclaw/openclaw.json
关键配置项enabled、defaultProfile、executablePath
多配置文件不同端口、不同颜色、完全隔离
常见问题Linux 用 Chrome、端口冲突换端口

下一节 ​

浏览器配置好了，但有一个问题：每次都要重新登录。下一节我们来解决这个痛点——登录态持久化。

基于 MIT 许可发布

Copyright © 2025 Gleam2Torch