Brave Browser Agent

Attach to the user's daily Brave Browser via CDP on port 9222. The browser has all login sessions and bookmarks. Agents only attach — never start, restart, or kill the browser.

Critical Rules

> ⚠️ 绝对禁止启动/重启/关闭浏览器！ 浏览器由用户手动管理，agent 只 attach。
> ⚠️ 绝对不要使用 --restart 参数！ 除非用户明确要求。

Multiple agents share the same browser instance (port 9222), which has all user login states.

• Port: 9222 — Brave's remote debugging port (non-configurable)
• Do NOT start/restart/kill browser — Browser is manually managed by user, agents only attach
• Do NOT use openclaw browser start — Will crash Gateway
• Do NOT use openclaw gateway restart — Will crash Gateway
• Do NOT use --restart parameter — Strictly prohibited unless explicitly requested
• Read-first preference — Use eval to extract content, avoid modifying page state
• If 9222 doesn't respond, tell user: "Brave Browser 未启动远程调试，请手动开启" — do NOT auto-start

Quick Start

Diagnostic Health Check (Recommended)

# Full check: CDP connection, tabs, script syntax, SKILL.md health
python3 {{SKILL_DIR}}/scripts/check_cdp.py

# Quick check (connection only)
python3 {{SKILL_DIR}}/scripts/check_cdp.py --quick

# JSON output for debugging
python3 {{SKILL_DIR}}/scripts/check_cdp.py --json

Check Browser Status (Legacy)

python3 {{SKILL_DIR}}/scripts/check_brave.py

List Tabs

python3 {{SKILL_DIR}}/scripts/cdp_exec.py list

Open a Page

python3 {{SKILL_DIR}}/scripts/cdp_exec.py open "https://example.com"

Execute JavaScript

python3 {{SKILL_DIR}}/scripts/cdp_exec.py eval <tab_id> "document.title"

Take Screenshot

python3 {{SKILL_DIR}}/scripts/cdp_exec.py screenshot <tab_id> output.png

Smart Interaction (Anti-Detection)

For anti-bot sites (Xiaohongshu, etc.), use CDP native mouse events instead of JS .click():

# Click element — real mouse events, isTrusted=true
python3 {{SKILL_DIR}}/scripts/cdp_exec.py interact <tab_id> --selector "button.submit"

# Type text into focused element
python3 {{SKILL_DIR}}/scripts/cdp_exec.py type <tab_id> "search query" --human

# Press a key
python3 {{SKILL_DIR}}/scripts/cdp_exec.py key <tab_id> Enter

Framework-Aware Click (React/Vue/Angular SPAs)

For SPA sites where standard CDP clicks fail (React/Vue/Angular), use multi-strategy auto-fallback:

# Multi-strategy click (auto: CDP native → React Fiber → Vue emit → dispatchEvent → Enter)
python3 {{SKILL_DIR}}/scripts/cdp_exec.py click-smart <tab_id> --selector "button.submit"

# Or find by text content
python3 {{SKILL_DIR}}/scripts/cdp_exec.py click-smart <tab_id> --text "发布"

# Detect which JS framework the page uses
python3 {{SKILL_DIR}}/scripts/cdp_exec.py detect-framework <tab_id>

# Deep-analyze a button (debugging)
python3 {{SKILL_DIR}}/scripts/cdp_exec.py analyze-button <tab_id> --selector "button.submit"

What click-smart Does (Strategy Order)

1. Editor sync — Auto-syncs rich text editors before clicking (CKEditor 4/5, Lexical, ProseMirror, Quill, 语雀, iframe editors). Critical for Vue/React editors where content is not synced to framework state
2. Hit-test check — ScrollIntoView + elementFromPoint (ensures element is visible and uncovered)
3. CDP native click — Input.dispatchMouseEvent with complete event sequence
4. React Fiber invocation — Calls React's onClick handler via __reactProps$. Fallback: React 18 root container event delegation for ByteUI/headless UI
5. Vue emit invocation — Enhanced Vue 2/3 detection: component tree traversal, $emit, $listeners, setupState handlers, vnode event walk
6. dispatchEvent — Creates a native MouseEvent(isTrusted=true) and dispatches it
7. Enter key — Focus + Enter key + form submit (for form buttons)

Publish Validation (auto): After all strategies, detects success via toast messages, URL changes, modal state, and button state. Reports errors if found.

Returns JSON showing which strategy succeeded and debugging info.

New Standalone Commands

# Validate if publish was successful (after clicking)
python3 {{SKILL_DIR}}/scripts/framework_click.py publish-validate <tab_id>

# Sync editor data without clicking
python3 {{SKILL_DIR}}/scripts/framework_click.py editor-sync <tab_id>

Platform-Specific Notes

Framework Detection Commands

# Quick framework detection
python3 {{SKILL_DIR}}/scripts/cdp_exec.py detect-framework <tab_id>

# Deep button analysis (for debugging)
python3 {{SKILL_DIR}}/scripts/cdp_exec.py analyze-button <tab_id> --selector "button.submit"
python3 {{SKILL_DIR}}/scripts/cdp_exec.py analyze-button <tab_id> --selector "button.submit" --index 0

Click Strategy Quick Reference

Wait for Page State

# Wait for page load
python3 {{SKILL_DIR}}/scripts/cdp_exec.py wait <tab_id> --page-load --timeout 10

# Wait for element to appear
python3 {{SKILL_DIR}}/scripts/cdp_exec.py wait <tab_id> --selector ".result" --timeout 10

# Wait for network idle
python3 {{SKILL_DIR}}/scripts/cdp_exec.py wait <tab_id> --network-idle --timeout 15

Page State Analysis

# List interactive elements (useful for exploring unknown pages)
python3 {{SKILL_DIR}}/scripts/cdp_exec.py elements <tab_id>

# Check page load status
python3 {{SKILL_DIR}}/scripts/cdp_exec.py page-status <tab_id>

# Detect pagination buttons
python3 {{SKILL_DIR}}/scripts/cdp_exec.py pagination <tab_id>

# Count elements matching selector
python3 {{SKILL_DIR}}/scripts/cdp_exec.py count <tab_id> --selector ".item"

# Smooth scroll (triggers lazy loading)
python3 {{SKILL_DIR}}/scripts/cdp_exec.py scroll <tab_id> --direction down --steps 3

# Highlight element for screenshot debugging
python3 {{SKILL_DIR}}/scripts/cdp_exec.py highlight <tab_id> --selector "#target"

When to Use What

Command Reference

All commands go through cdp_exec.py:

Common Patterns

For detailed usage patterns and workflows, see references/PATTERNS.md.

For site-specific anti-detection strategies (Xiaohongshu, SPA pages, etc.), see references/site-patterns.md.

For React/Vue/Angular framework-aware clicking and platform-specific strategies (头条号, 掘金, CSDN, etc.), see references/framework-publish.md.

Troubleshooting