10.5 常见问题排查

想象一下这个场景：

你设置好了自动发帖任务，满怀期待地点击运行。
浏览器启动了，页面打开了——
然后卡住了。AI 报错："Element not found"。
你翻日志、查配置、重启 Gateway，折腾了半小时还是不行。
最后发现：只是忘了等待页面加载。

浏览器自动化涉及多个组件协同工作，遇到问题很正常。这一节，我们用 15 分钟，建立一套完整的问题排查方法论。

问题 1：浏览器启动失败

现象

Error: Failed to start Chrome CDP on port 18800

或

Browser process exited with code 1

排查步骤

第一步：检查浏览器是否已安装

bash

# macOS
ls /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome

# Linux
which google-chrome-stable
which chromium-browser

# Windows
Get-Command "C:\Program Files\Google\Chrome\Application\chrome.exe"

第二步：检查可执行路径配置

bash

# 查看当前配置
openclaw config get browser.executablePath

# 如果路径错误或为空，重新设置
openclaw config set browser.executablePath "/usr/bin/google-chrome-stable"

第三步：Linux 特殊处理（snap Chromium）

Ubuntu 默认的 Chromium 是 snap 包，会触发权限问题。

解决方案：安装官方 Chrome

bash

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

第四步：检查端口占用

bash

# 查看 18800 端口是否被占用
lsof -i :18800

# 如果被占用，更换端口
openclaw config set browser.profiles.openclaw.cdpPort 18803

第五步：查看详细日志

bash

openclaw gateway logs | grep -i browser

问题 2：页面加载超时

现象

Timeout waiting for page to load

或页面一直空白。

可能原因与解决方案

原因 1：网络问题

bash

# 测试网络连通性
ping xiaohongshu.com

# 测试 DNS 解析
nslookup xiaohongshu.com

原因 2：页面资源加载慢

增加等待时间：

bash

openclaw browser wait --load networkidle --timeout-ms 30000

原因 3：被网站拦截

某些网站会检测自动化浏览器。尝试：

1。关闭无头模式（headless: false） 2。设置正常窗口大小 3。添加随机延迟

bash

# 设置窗口大小
openclaw browser resize 1280 720

# 等待时添加随机延迟
openclaw browser wait --text "加载完成" --timeout-ms 20000

原因 4：JavaScript 渲染问题

某些 SPA（单页应用）需要等待 JS 执行完成：

bash

# 等待特定 JS 条件
openclaw browser wait --fn "window.ready===true"

# 或等待特定元素出现
openclaw browser wait "#main-content"

问题 3：元素定位问题

现象

Element not found

或

Multiple elements match the selector

排查方法

第一步：获取最新快照

ref 在页面变化后会失效，需要重新获取：

bash

openclaw browser snapshot --interactive

第二步：使用高亮确认元素

bash

# 高亮显示 ref=12 的元素
openclaw browser highlight 12

这会在浏览器中用红色框标出目标元素，确认是否正确。

第三步：检查元素是否可见

bash

# 获取带标签的截图
openclaw browser snapshot --labels

截图上会显示每个元素的 ref 标签。

第四步：滚动到元素可见

bash

# 先滚动到元素位置
openclaw browser scrollintoview 12

# 再点击
openclaw browser click 12

第五步：使用角色 ref（更稳定）

bash

# 使用角色快照
openclaw browser snapshot --interactive --compact

# 输出示例：
# [e12] button "发布"
# [e13] input "标题"

# 使用角色 ref 操作
openclaw browser click e12
openclaw browser type e13 "笔记标题"

问题 4：操作被拦截

现象

Element is not clickable

或

Element is covered by another element

解决方案

原因 1：有弹窗遮挡

bash

# 先关闭弹窗（通常是第一个元素）
openclaw browser click 1

# 或按 ESC 键
openclaw browser press Escape

原因 2：元素被其他元素覆盖

bash

# 滚动到元素位置，确保在视口中心
openclaw browser scrollintoview 12

# 等待一下再点击
sleep 1
openclaw browser click 12

原因 3：需要悬停才能点击

bash

# 先悬停
openclaw browser hover 12

# 再点击
openclaw browser click 12

问题 5：登录状态丢失

现象

每次启动浏览器都需要重新登录。

排查步骤

第一步：检查用户数据目录

bash

# 查看目录是否存在
ls -la ~/.openclaw/browser/openclaw/user-data

# 查看目录大小（正常应该有几十MB）
du -sh ~/.openclaw/browser/openclaw/user-data

第二步：确认使用正确的配置文件

bash

# 检查当前使用的配置文件
openclaw config get browser.defaultProfile

# 确保是 openclaw，不是 chrome
openclaw config set browser.defaultProfile "openclaw"

第三步：检查是否使用了无痕模式

无痕模式不会保存 Cookie。确保配置中：

json5

{
  "browser": {
    "headless": false  // 不要设为 true 时意外触发无痕
  }
}

第四步：网站强制要求重新登录

某些网站（如银行、支付平台）出于安全考虑会定期要求重新验证。这种情况无法避免。

问题 6：扩展中继模式连接失败

现象

扩展图标显示 !，或提示"中继不可达"。

排查步骤

第一步：检查 Gateway 是否运行

bash

openclaw gateway status

第二步：确认扩展已正确加载

1。打开 chrome://extensions 2。确认 OpenClaw 扩展已启用 3。点击"重新加载"刷新扩展

第三步：检查扩展路径

bash

# 重新安装扩展
openclaw browser extension install

# 确认路径
openclaw browser extension path

第四步：确认在正确标签页点击扩展

扩展只控制你明确点击的那个标签页，不会自动接管所有标签页。

第五步：检查远程 Gateway 设置

如果 Gateway 运行在远程服务器，需要在本地运行节点主机：

bash

openclaw node start

调试技巧

1。开启 Trace 录制

bash

# 开始录制
openclaw browser trace start

# 执行你的操作
openclaw browser open https://example.com
openclaw browser click 12

# 停止录制
openclaw browser trace stop
# 输出: TRACE:/path/to/trace.zip

用 Chrome 打开 trace.zip，可以逐帧查看操作过程。

2。查看控制台错误

bash

# 查看浏览器控制台错误
openclaw browser console --level error

# 清空错误日志
openclaw browser errors --clear

3。查看网络请求

bash

# 查看所有 API 请求
openclaw browser requests --filter api

# 查看特定请求的响应体
openclaw browser responsebody "**/api/data" --max-chars 5000

4。截图排查

bash

# 截图当前页面
openclaw browser screenshot

# 截图特定元素
openclaw browser screenshot --ref 12

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

快速诊断清单

遇到问题时，按这个顺序排查：

步骤	检查项	命令
1	Gateway 是否运行	`openclaw gateway status`
2	浏览器配置是否正确	`openclaw config get browser`
3	浏览器是否能启动	`openclaw browser start`
4	页面是否能打开	`openclaw browser open URL`
5	快照是否正常	`openclaw browser snapshot`
6	查看错误日志	`openclaw gateway logs`

这一节，你做了什么

学了什么	核心理解
启动失败	检查路径、端口、Linux 用官方 Chrome
加载超时	增加等待时间、检查网络、等待 JS
元素定位	重新获取 snapshot、用 highlight 确认
调试技巧	trace 录制、控制台错误、网络请求

第十章总结

恭喜你！第十章到此结束。你已经掌握了浏览器自动化的完整能力：

章节	核心内容
10.1	两种模式：托管 vs 扩展中继
10.2	配置托管浏览器
10.3	登录态持久化
10.4	实战自动发帖
10.5	常见问题排查

下一步：第十一章，我们来学习如何用 Obsidian 管理 AI 的知识库。

10.5 常见问题排查 ​

问题 1：浏览器启动失败 ​

现象 ​

排查步骤 ​

问题 2：页面加载超时 ​

现象 ​

可能原因与解决方案 ​

问题 3：元素定位问题 ​

现象 ​

排查方法 ​

问题 4：操作被拦截 ​

现象 ​

解决方案 ​

问题 5：登录状态丢失 ​

现象 ​

排查步骤 ​

问题 6：扩展中继模式连接失败 ​

现象 ​

排查步骤 ​

调试技巧 ​

1。 开启 Trace 录制 ​

2。 查看控制台错误 ​

3。 查看网络请求 ​

4。 截图排查 ​

快速诊断清单 ​

这一节，你做了什么 ​

第十章总结 ​

10.5 常见问题排查

问题 1：浏览器启动失败

现象

排查步骤

问题 2：页面加载超时

现象

可能原因与解决方案

问题 3：元素定位问题

现象

排查方法

问题 4：操作被拦截

现象

解决方案

问题 5：登录状态丢失

现象

排查步骤

问题 6：扩展中继模式连接失败

现象

排查步骤

调试技巧

1。开启 Trace 录制

2。查看控制台错误

3。查看网络请求

4。截图排查

快速诊断清单

这一节，你做了什么

第十章总结