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)#

bash

# 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)#

bash

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

List Tabs#

bash

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

Open a Page#

bash

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

Execute JavaScript#

bash

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

Take Screenshot#

bash

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():

bash

# 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:

bash

# 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#

bash

# 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#

PlatformFrameworkKnown IssueSolution掘金Vue 2发布弹出层按钮 CDP 点击无效click-smart auto-syncs editor → tries Vue enhanced clickCSDNVue 3 + CKEditor iframe字数统计更新但按钮无反应editor-sync fires CKEditor change:data + iframe input event头条号React ByteUIonClick 调用成功但无变化click-smart tries React 18 root delegation + deep fiber traversal阿里云开发者语雀编辑器非 contenteditable，注入困难editor-sync triggers lake-editor input events百家号Lexicalcontenteditable 注入editor-sync calls lexical update + dispatchCommand

Framework Detection Commands#

bash

# 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#

TaskCommandWhySimple click (known site)interactLightweight, uses CDP native eventsClick on React/Vue SPAclick-smartAuto-tries 6 strategies + diagnosticsClick keeps failingdetect-framework + analyze-buttonDebug overlay/modals/disabled stateForm button that won't clickclick-smartAuto-tries Enter key + form submit

Wait for Page State#

bash

# 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#

bash

# 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#

TaskCommandWhyRead contentevalNo interaction neededSimple clickeval "el.click()"Trusted sitesAnti-detection clickinteractisTrusted=trueFill form (anti-bot)type --humanChar-by-charFill form (fast)typeBulk insertWait for contentwaitDynamic pagesInfinite scrollscrollLazy loadingExplore pageelementsUnknown structure

Command Reference#

All commands go through cdp_exec.py:

CommandDescriptionlistList open tabsstatusCheck browser statusopen <url>Open URL in new tabclose <tab_id>Close tabeval <tab_id> <js>Execute JavaScriptscreenshot <tab_id> [file]Take screenshotinteract <tab_id>CDP native mouse clicktype <tab_id> <text>Type textkey <tab_id> <key>Press keyboard keywait <tab_id>Wait for page statescroll <tab_id>Smooth scrollelements <tab_id>List interactive elementspage-status <tab_id>Page load statuspagination <tab_id>Detect pagination buttonscount <tab_id>Count elements by selectorlocate <tab_id>Get element coordinateshighlight <tab_id>Highlight element outlinesnapshot <tab_id>Lightweight DOM snapshotclick-smart <tab_id>Multi-strategy click (React/Vue auto-fallback)detect-framework <tab_id>Detect JS framework on pageanalyze-button <tab_id>Deep-analyze a button element

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#

ProblemFixCDP HTTP errorCheck Brave is running with curl -s http://localhost:9222/json/version. If not, ask user to restart Brave with --remote-debugging-port=9222``Tab not foundRun cdp_exec.py list to get current tab IDsJS ErrorCheck if page loaded; add --await-promise for async opswebsockets not installed``pip3 install websocketsBrave won't respondAsk user to restart Brave. **DO NOT kill the process yourself.**Click not workingUse interact instead of eval ".click()" for anti-bot sitesElement not foundUse elements to check page structure; wait before interacting