browser-use（本地）操作手册

此环境中的默认约束条件

• 优先使用 browser-use（CLI/Python），而非 OpenClaw 的 browser 工具；若系统中未安装受支持的浏览器，OpenClaw browser 可能失败。
• 使用 持久化会话（persistent sessions） 执行多步骤操作：--session 。

快速 CLI 工作流（非 Agent 模式）

1. 打开页面

browser-use --session demo open https://example.com

2. 检查页面状态（在重型页面或含大量 JS 的页面上，state 有时返回 0 个元素）

browser-use --session demo --json state | jq '.data | {url,title,elements:(.elements|length)}'

3. 截图（始终可用；是最基础、最可靠的调试手段）

browser-use --session demo screenshot /home/node/.openclaw/workspace/page.png

4. 提取 HTML 内容用于链接发现（即使 state 返回空结果也有效）

browser-use --session demo --json get html > /tmp/page_html.json
python3 - <<'PY'
import json,re
html=json.load(open('/tmp/page_html.json')).get('data',{}).get('html','')
urls=set(re.findall(r"https?://[^s"'<>]+", html))
for u in sorted([u for u in urls if any(k in u for k in ['demo','login','console','qr','qrcode'])])[:200]:
    print(u)
PY

5. 通过 JavaScript 执行轻量级 DOM 查询（当 state 为空时尤为有用）

browser-use --session demo --json eval "location.href"
browser-use --session demo --json eval "document.title"

使用兼容 OpenAI 的大语言模型（Moonshot/Kimi）的 Agent 工作流

当 CLI 的 run 路径需要 Browser-Use 云密钥，或你需要对 LLM 参数进行严格控制时，请使用 Python 启动 Agent。

最小可运行 Kimi 示例

创建 .env 文件（或导出环境变量），内容如下：

• OPENAI_API_KEY=...
• OPENAI_BASE_URL=https://api.moonshot.cn/v1

然后运行预置脚本：

source /home/node/.openclaw/workspace/.venv-browser-use/bin/activate
python /home/node/.openclaw/workspace/skills/browser-use-local/scripts/run_agent_kimi.py

Kimi/Moonshot 在实际使用中观察到的特殊行为（及其修复方式）：

• temperature 必须设为 1（针对 kimi-k2.5）。
• frequency_penalty 必须设为 0（针对 kimi-k2.5）。
• Moonshot 可能拒绝结构化输出中使用的严格 JSON Schema。请启用以下选项：
  • remove_defaults_from_schema=True
  • remove_min_items_from_schema=True

若收到包含 response_format.json_schema ... keyword 'default' is not allowed 或 min_items unsupported 的 400 错误，应首先设置上述两个标志。

二维码提取（登录页/演示页）

推荐顺序

1. 对整页截图，并裁剪候选区域（速度快、鲁棒性强）。
2. 若 HTML 中包含 data:image/png;base64,...，则提取并解码该 Base64 数据。

裁剪候选区域

使用 scripts/crop_candidates.py 从一张截图中生成多个可能包含二维码的裁剪区域。

source /home/node/.openclaw/workspace/.venv-browser-use/bin/activate
python skills/browser-use-local/scripts/crop_candidates.py 
  --in /home/node/.openclaw/workspace/login.png 
  --outdir /home/node/.openclaw/workspace/qr_crops

从 HTML 中提取内嵌的 Base64 图像

source /home/node/.openclaw/workspace/.venv-browser-use/bin/activate
browser-use --session demo --json get html > /tmp/page_html.json
python skills/browser-use-local/scripts/extract_data_images.py 
  --in /tmp/page_html.json 
  --outdir /home/node/.openclaw/workspace/data_imgs

故障排查

• state 显示 elements: 0：改用 get html + 正则表达式提取链接，并辅以截图；也可使用 eval 直接查询 DOM。
• 页面就绪超时警告（Page readiness timeout warnings）：通常无害；建议依赖截图与 HTML 内容进行判断。
• CLI 参数顺序：全局参数必须置于子命令 之前：
  • ✅ 正确：browser-use --browser chromium --json open https://...
  • ❌ 错误：browser-use open https://... --browser chromium