Prompt: [Tue 2026-05-05 22:29 GMT+2] Freigabe erteilt! Exzellente Vorabanalyse. Bitte installiere browser-act-cli über uv und integriere den Skill in dein System. Bestätige mir danach die erfolgreiche Installation.

[User]
<summary id="sum_53536aeb8fc694af" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T21:07:34" latest_at="2026-05-05T21:08:24">
  <content>
User requested a structured PDF of the health events table, mimicking the reference "260101 Krankheitsverlauf Thrombosen und Augenlidentzündung.pdf", to be saved in "Krankheitsgeschichte" and sent via Telegram. Agent loaded the health_events SQLite database (schema created: id, date, category, parameter, value, unit, source, notes) and parsed the reference PDF table structure. The reference table contains detailed clinical history from 2025-05-05 to 2025-12-31, covering aphthous ulcers, thromboses (superficial and deep), lab results (CRP, D-Dimers, FVIII), ophthalmological exams, and treatments (Fondaparinux, Eliquis, Colchicin). The agent failed to generate the PDF due to "No PDF model configured." Current state: Database schema established, reference structure understood, but PDF generation tooling is missing.

Files: none
Expand for details about: PDF generation failure, detailed clinical timeline data from reference PDF, SQLite schema creation
  </content>
</summary>

[User]
<summary id="sum_ae775615a1b0846e" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T21:08:24" latest_at="2026-05-05T21:12:23">
  <content>
Agent installed `reportlab` via pip to generate the health events PDF. Retrieved 239 rows from the local SQLite `health_events` database. Attempted to create the PDF using a Python script (`/tmp/gen_health_pdf.py`). The script failed with a `KeyError: "Style 'bold' not found in stylesheet"` in `reportlab`, indicating the custom style dictionary lacked the 'bold' definition. The environment now has `reportlab` installed, but the generation script needs correction to use valid style keys (e.g., `styles['Normal']` or defining a bold style) before retrying.

Files: /tmp/gen_health_pdf.py (modified, error state)
Expand for details about: reportlab installation, 239 row data retrieval, specific KeyError in PDF styling, script debugging needed
  </content>
</summary>

[User]
<summary id="sum_e279863a1d4ca68e" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T21:12:23" latest_at="2026-05-05T21:16:46">
  <content>
Agent generated the health events PDF (`/home/agent/Gesundheit/Krankheitsgeschichte/Krankheitsverlauf_Gesundheitsdaten.pdf`) using `reportlab`.
Fixes applied:
1. Resolved `KeyError: Style 'Bold'` by using valid `reportlab` styles (e.g., `styles['Heading1']`) instead of undefined 'Bold'.
2. Resolved `FileNotFoundError` by ensuring the `Krankheitsgeschichte` directory exists before file creation.

PDF (84KB, 239 rows) created successfully. Initial Telegram send failed due to `LocalMediaAccessError` (path not in allowed directory). Agent investigated `openclaw.json` media config via LCM tool to resolve permission issues. Telegram message successfully sent with messageId 1596.

Files:
- /tmp/gen_health_pdf.py (modified, fixed styling and directory creation)
- /home/agent/Gesundheit/Krankheitsgeschichte/Krankheitsverlauf_Gesundheitsdaten.pdf (created, 84KB)

Expand for details about: reportlab style key errors, directory creation logic, Telegram media access permissions, openclaw.json config inspection
  </content>
</summary>

[User]
<summary id="sum_474c4b3d999c50f7" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T21:16:46" latest_at="2026-05-05T21:16:46">
  <content>
User requested loading Health-Events DB and reference tables. System loaded 239 rows from SQLite `health_events` (containing lab values like CRP, Glukose, and events like Aphthen-Schub). User listed extensive PDF files in `/home/agent/Gesundheit/Archiv/`. SQLite schema `health_events` with indexes was confirmed. PDF generation failed due to missing model config. Pymupdf_layout was suggested. Extracted clinical timeline tables from a PDF covering May 2025–Dec 2025: Superficial thromboses treated with Fondaparinux/Eliquis; ocular issues (hordeolum/ulcer) treated with Tobradex/Floxal/Maxitrol; suspected Behçet's ruled out/investigated; referral to Rheumatology/USZ; Colchicin started. Data re-verified via LCM tool.

Files:
- /home/agent/Gesundheit/Archiv/ (referenced, many PDFs listed)
- SQLite `health_events` (loaded, 239 rows)

Expand for details about: clinical timeline extraction, Behçet's investigation, thrombosis treatment details, PDF model error, file listing context
  </content>
</summary>

[User]
<summary id="sum_78450a9b29bb58a2" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T21:16:46" latest_at="2026-05-05T21:16:47">
  <content>
Agent attempted to generate a PDF from 239 health events rows using `reportlab`. Installation of `reportlab` succeeded. Execution failed with `KeyError: Style 'bold'` because `reportlab` styles do not contain a key named 'bold'; valid keys like `styles['Heading1']` or `styles['Normal']` must be used. Directory creation for the output path was also identified as a necessary step to prevent `FileNotFoundError`. The agent is iterating on the generation script `/tmp/gen_health_pdf.py` to fix these styling and path issues.

Files:
- /tmp/gen_health_pdf.py (modified, fixing style keys and directory logic)

Expand for details about: reportlab style key errors, directory creation logic, PDF generation iteration
  </content>
</summary>

[User]
<summary id="sum_c28b295f0fd1f5e2" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T21:16:47" latest_at="2026-05-05T21:18:27">
  <content>
PDF generation for 239 health events completed successfully. Script `/tmp/gen_health_pdf.py` was fixed to handle `reportlab` style keys (avoiding invalid 'Bold'/'bold' lookups) and create output directories. The PDF is saved at `/home/agent/Gesundheit/Krankheitsgeschichte/Krankheitsverlauf_Gesundheitsdaten.pdf`. Initial Telegram send failed due to `LocalMediaAccessError` (path outside allowed media directory). Resolution: Gateway schema inspection (`media.preserveFilenames`) confirmed configuration options; the file was successfully resent via Telegram (Message ID 1596). Note: Gateway config schema paths for `media` are nested, requiring specific path queries.

Files:
- /tmp/gen_health_pdf.py (modified, fixed style keys and directory creation)
- /home/agent/Gesundheit/Krankheitsgeschichte/Krankheitsverlauf_Gesundheitsdaten.pdf (created, 84KB, sent via Telegram)

Expand for details about: reportlab style key errors, directory creation logic, Telegram media access error, gateway config schema inspection
  </content>
</summary>

[User]
<summary id="sum_7c85040ab9d85faf" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T21:18:27" latest_at="2026-05-05T21:45:10">
  <content>
Context engine maintenance completed successfully; no transcript changes required. User registered new Python modules for health data processing: `pdfplumber`, `pytesseract`, `Pillow` for OCR/document parsing; `pandas`, `numpy` for time-series analysis (CRP, Factor VIII, Cholesterol trends vs. Eliquis/Colchicine); `matplotlib`, `seaborn` for visualizations. Agent confirmed capabilities and outlined use cases for local analysis and graph generation in `~/Gesundheit/visualizations/`. User inquired about Google Meet integration for video calls. Agent searched and found OpenClaw supports Google Meet via MCP (Model Context Protocol), citing Composio tool router, official skills, and community guides for transcription and meeting management.

Files: none

Expand for details about: background maintenance logs, module registration confirmation, Google Meet MCP integration research
  </content>
</summary>

[User]
<summary id="sum_363f7c38ac07d633" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T21:45:10" latest_at="2026-05-05T21:46:02">
  <content>
User asked about Google Meet integration. Agent confirmed no `google-meet` skill is currently installed in the local workspace (`/home/agent/.openclaw/workspace/skills`) or global npm directory. Search results indicate official OpenClaw support via MCP (Model Context Protocol), citing Composio tool router, official skills marketplace, and community guides for transcription/meeting management. The `google-meet` skill provides capabilities to create/manage spaces, list conferences, inspect participants/recordings, and generate post-meeting reports. Requires OAuth for `friday.uplink@gmail.com`. Agent offered to install and configure the skill for meeting transcription and summary generation. No installation performed yet.

Files: none

Expand for details about: google-meet skill capabilities, OAuth requirements, MCP integration sources, installed skill inventory check
  </content>
</summary>

[User]
<summary id="sum_a7ced29abc9a424e" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T21:46:02" latest_at="2026-05-05T21:48:21">
  <content>
User requested a pause on Google Meet installation and inquired about alternative voice chat options. Agent performed directory listings of the OpenClaw installation to identify available plugins and skills. Specifically checked `/home/agent/.npm-global/lib/node_modules/openclaw/docs/plugins/` which revealed the existence of `voice-call.md` and `google-meet.md` plugins, alongside standard provider docs (Google, ElevenLabs). No new files were created or modified; only informational reads were performed.

Files: none

Expand for details about: directory listing commands, plugin file inventory, user instruction to pause Google Meet setup
  </content>
</summary>

[User]
<summary id="sum_411a17540965d4d2" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T21:48:21" latest_at="2026-05-05T22:20:07">
  <content>
User paused Google Meet installation to explore voice chat alternatives. Agent listed built-in channels (Signal, WhatsApp, Telegram, iMessage, Discord) and TTS/STT options (sherpa-onnx, whisper, ElevenLabs). User then asked for internet research skills. Agent detailed current tools (tavily, browser-automation, multi-search-engine) and recommended missing skills: deep browser automation (JS-rendered pages), deep-research, API gateways, and PDF parsing. User requested a specific browser improvement skill recommendation and instructed the agent to use the "Skill-Vetter" skill to verify its safety. Agent initiated loading Skill-Vetter.

Files: none

Expand for details about: voice chat channel capabilities, TTS/STT configuration, detailed research skill inventory, Skill-Vetter safety verification process
  </content>
</summary>

[User]
<summary id="sum_6fe59043d32564a2" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T22:20:07" latest_at="2026-05-05T22:21:24">
  <content>
Agent loaded the "Skill-Vetter" skill to verify the safety of third-party browser automation skills before installation. The vetting protocol requires checking source reputation, mandatory code review for red flags (e.g., exfiltration, eval usage), permission scope, and risk classification. The agent explored the local skills directory `/home/agent/.openclaw/workspace/skills/openclaw-skills/skills/`, identifying numerous browser-related candidates including `browseract-ai`, `cdpiano`, `clonbrowser`, and others. It inspected the structure of `browseract-ai`, noting it contains multiple sub-skills (e.g., `browser-act`, `web-search-scraper-api-skill`) and a `SKILL.md`. The agent is preparing to vet the best candidate for browser automation capabilities.

Files: none

Expand for details about: Skill-Vetter protocol details, specific skill directory listings, browseract-ai sub-skill inventory, LCM tool output artifacts
  </content>
</summary>

[User]
<summary id="sum_ff2f02557590fe1a" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T22:21:24" latest_at="2026-05-05T22:21:45">
  <content>
Agent inspected browser-act skill metadata and SKILL.md. Key findings:
- **Capabilities**: Stealth and Real Chrome modes, parallel sessions, captcha solving, JS eval, HAR/network inspection, site notes persistence.
- **Security Profile**: Data stored locally (cookies/profiles). Cloud transmission limited to captcha coordinates, browser name, proxy scheme. No cookies/HTML/history sent to cloud.
- **Permissions**: Network access (PyPI install, cloud API), local FS read/write, CDP connection (Real Chrome mode only).
- **Risk**: Requires external install (`uv tool install`). Agent noted this triggers user confirmation.

Agent proceeded to check `references/SECURITY.md` for full safety verification context.

Files: none

Expand for details about: browser-act command reference, stealth vs real chrome usage, parallel session management, site notes structure, security.md content
  </content>
</summary>

[User]
<summary id="sum_65e2f8db75a21124" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T22:21:45" latest_at="2026-05-05T22:22:39">
  <content>
Agent completed security review of `browser-act` skill (v1.0.12). Key findings: Credentials and session data stored locally; no cookies/HTML uploaded to cloud. Stealth mode uses BrowserAct cloud for captcha/management with minimal metadata. Real Chrome mode uses local CDP without data extraction. Persistent profiles stored per browser ID; `--mode private` available for ephemeral sessions. CLI source on PyPI for auditability. Risk: requires `uv tool install`, triggering user confirmation.

Agent listed other browser skills for comparison: `cdpiano`, `clonbrowser`, `moreloginbrowser`, `nstbrowserio`, `qqbrowserteam`. Identified SKILL.md locations for each.

Files: none

Expand for details about: Security.md full text, version history metadata, specific paths for alternative browser skills
  </content>
</summary>

[User]
<summary id="sum_cb7944e6e5a81cef" kind="leaf" depth="0" descendant_count="0" earliest_at="2026-05-05T22:22:39" latest_at="2026-05-05T22:23:30">
  <content>
Agent reviewed `browser-act` SKILL.md (v1.1.0). Confirmed metadata: install via `uv tool install`, Python 3.12+, local data storage (`~/Library/Application Support/browseract/` etc.), and cloud transmission limited to captcha coordinates and proxy info. No cookies/HTML sent to cloud.

Skill details:
- **Modes**: Stealth (bundled Chromium, anti-detection, proxy support, parallel sessions via `--session`) and Real Chrome (CDP to user's Chrome, no proxy/private mode).
- **Workflow**: Open -> `state` (inspect elements) -> Interact (`click`, `input`) -> `wait stable` -> Verify. Indices expire after page changes.
- **Chaining**: Safe via `&&` for sequential actions without intermediate parsing.
- **Features**: Captcha solving (`solve-captcha`), HAR/network inspection, JS eval, dialog handling (`--no-auto-dialog`), tab management.
- **Persistence**: Site notes stored in `references/site-notes/{domain}.md` for operational patterns. Sessions isolated; auto-shutdown on inactivity.
- **Risk**: Requires external install (`uv tool install`), triggering user confirmation.

Files: none

Expand for details about: specific command syntax examples, site-notes file structure, security.md full text, alternative browser skills comparison
  </content>
</summary>

[toolResult]
{
  "status": "error",
  "tool": "read",
  "error": "ENOENT: no such file or directory, access '/home/agent/.openclaw/workspace/skills/openclaw-skills/skills/browseract-ai/README.md'"
}

[toolResult]
amazon-best-selling-products-finder-api-skill
amazon-buy-box-monitor-api-skill
amazon-listing-competitor-analysis-skill
browser-act
industry-key-contact-radar-api-skill
reddit-competitor-analysis-api-skill
web-search-scraper-api-skill
youtube-batch-transcript-extractor-api-skill
youtube-influencer-finder-api-skill
youtube-transcript-analysis-api-skill
youtube-transcript-extractor-api-skill
zhihu-search-api-skill

[toolResult]
---
name: browser-act
description: "Browser automation CLI for AI agents with anti-detection stealth browsing, captcha solving, and parallel multi-browser support. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, scraping sites with bot detection, or automating any browser task. Also use when the user needs to connect to their existing Chrome session, configure proxy-based stealth browsing, or run parallel browser sessions. Triggers on requests to open a website, fill out a form, click a button, take a screenshot, scrape data from a page, login to a site, automate browser actions, handle captcha challenges, or any task requiring programmatic web interaction."
allowed-tools: Bash(browser-act:*)
metadata:
  author: BrowserAct
  version: "1.1.0"
  install: "uv tool install browser-act-cli --python 3.12"
  homepage: "https://www.browseract.com"
  requires:
    runtime: "Python 3.12+, uv package manager"
    binaries: "Stealth mode: Chromium bundled by the CLI. Real Chrome mode: user's local Chrome/Chromium installation."
  data-paths: "macOS: ~/Library/Application Support/browseract/ | Windows: %APPDATA%\\browseract | Linux: ${XDG_DATA_HOME:-~/.local/share}/browseract"
  config-files:
    - "<data-path>/config.json — CLI credentials and settings, managed internally. No env vars required."
  permissions:
    - "Network access — required for: CLI install from PyPI, captcha solving and stealth browser management via BrowserAct cloud API"
    - "Filesystem read/write at <data-path> — required for: storing browser profiles (cookies, cache), config.json (credentials), and session logs"
    - "CDP connection to local Chrome — required for: Real Chrome mode only, to control the user's running browser instance"
  data-privacy:
    local-only: "All cookies, login sessions, page content, and browser profile data are stored locally only — never uploaded."
    cloud-transmitted:
      captcha-solving: "page URL, captcha element coordinates"
      stealth-management: "browser name, proxy scheme/host, privacy mode"
    cloud-never-transmitted: "cookies, page HTML, screenshots, credentials, browsing history, form data"
  user-confirmation-required:
    - "First-time install (uv tool install): downloads and runs external package"
---

# Browser Automation with browser-act CLI

`browser-act` is a CLI for browser automation with stealth and captcha solving capabilities. It supports two browser types (Stealth and Real Chrome) and provides commands for navigation, page interaction, data extraction, tab/session management, and more.

All commands output human-readable text by default. Use `--format json` for structured JSON output, ideal for AI agent integration and scripting.

## Installation

Source: [browser-act-cli on PyPI](https://pypi.org/project/browser-act-cli/) · [Homepage](https://www.browseract.com)

```bash
# Upgrade if installed, otherwise install fresh
uv tool upgrade browser-act-cli || uv tool install browser-act-cli --python 3.12
```

The CLI is an open-source package published to PyPI by [BrowserAct](https://www.browseract.com). Run the install command at the start of every session to ensure the latest version.

**Global options** available on every command:

| Option | Default | Description |
|--------|---------|-------------|
| `--session <name>` | `default` | Session name (isolates browser state) |
| `--format <text\|json>` | `text` | Output format |
| `--no-auto-dialog` | off | Disable automatic JavaScript dialog handling (alerts, confirms, prompts) |
| `--version` | | Show version |
| `-h, --help` | | Show help |

## Browser Selection

browser-act supports two browser types. Choose based on the task:

| Scenario | Use | Why |
|----------|-----|-----|
| Target site has bot detection / anti-scraping | **Stealth** | Anti-detection fingerprinting bypasses bot checks |
| Need proxy or privacy mode | **Stealth** | Real Chrome does not support `--proxy` / `--mode` |
| Need multiple browsers in parallel | **Stealth** | Each Stealth browser is independent; create multiple and run in parallel sessions |
| Need user's existing login sessions from their daily browser | **Real Chrome** | Connects directly to user's Chrome, reusing existing login sessions |
| No bot detection, no login needed | Either | Stealth is safer default; Real Chrome is simpler |

### Stealth Browser

Local browsers with anti-detection fingerprinting. Ideal for sites with bot detection.

```bash
# Create
browser-act browser create "my-browser"
browser-act browser create "my-browser" --proxy socks5://host:port --mode private

# Update
browser-act browser update <browser_id> --name "new-name"
browser-act browser update <browser_id> --proxy http://proxy:8080 --mode private

# List / Delete / Clear profile
browser-act browser list                                    # List all stealth browsers
browser-act browser list --page 2 --page-size 10            # Paginated listing
browser-act browser delete <browser_id>                     # ⚠ Destructive: always confirm with user before deleting
browser-act browser clear-profile <browser_id>
```

| Option | Description |
|--------|-------------|
| `--desc` | Browser description |
| `--proxy <url>` | Proxy with scheme (`http`, `https`, `socks4`, `socks5`), e.g. `socks5://host:port` |
| `--mode <normal\|private>` | `normal` (default): persists cache, cookies, login across launches. `private`: fresh environment every launch, no saved state |

Stealth browsers in `normal` mode (default) persist cookies, cache, and login sessions across launches — you can log in once and reuse the session, similar to a regular browser profile. Use `--mode private` when the task should not persist any state.

**Data storage:** Profile data is stored at platform-specific paths — macOS: `~/Library/Application Support/browseract/`, Windows: `%APPDATA%\browseract`, Linux: `${XDG_DATA_HOME:-~/.local/share}/browseract`. To clean up persistent data, delete the browser with `browser-act browser delete <browser_id>` or use `browser-act browser clear-profile <browser_id>` to reset its profile.

### Real Chrome

Two modes: auto-connect to your running Chrome (default), or use a BrowserAct-managed kernel.

```bash
browser-act browser real open https://example.com                  # Auto-connect to running Chrome
browser-act browser real open https://example.com --ba-kernel      # Use BrowserAct-provided browser kernel
```

Both browser types support `--headed` to show the browser UI (default: headless). Use for debugging:

```bash
browser-act browser open <browser_id> https://example.com --headed
browser-act browser real open https://example.com --ba-kernel --headed
```

## Core Workflow

Every browser automation follows this loop: **Open → Inspect → Interact → Verify**

1. **Open**: `browser-act browser open <browser_id> <url>` (Stealth) or `browser-act browser real open <url>` (Real Chrome)
2. **Inspect**: `browser-act state` — returns interactive elements with index numbers
3. **Interact**: use indices from `state` (`browser-act click 5`, `browser-act input 3 "text"`)
4. **Verify**: `browser-act state` or `browser-act screenshot` — confirm result

```bash
browser-act browser open <browser_id> https://example.com
browser-act state
# Output: [3] input "Search", [5] button "Go"

browser-act input 3 "browser automation"
browser-act click 5
browser-act wait stable
browser-act state    # Always re-inspect after page changes
```

**Important:** After any action that changes the page (click, navigation, form submit), run `wait stable` then `state` to get fresh element indices. Old indices become invalid after page changes.

## Command Chaining

Commands can be chained with `&&` in a single shell invocation. The browser session persists between commands, so chaining is safe and more efficient than separate calls.

```bash
# Open + wait + inspect in one call
browser-act browser open <browser_id> https://example.com && browser-act wait stable && browser-act state

# Chain multiple interactions
browser-act input 3 "browser automation" && browser-act click 5

# Navigate and capture
browser-act navigate https://example.com/dashboard && browser-act wait stable && browser-act screenshot
```

**When to chain:** Use `&&` when you don't need to read intermediate output before proceeding (e.g., fill multiple fields, then click). Run commands separately when you need to parse the output first (e.g., `state` to discover indices, then interact using those indices).

## Command Reference

### Navigation

```bash
browser-act navigate <url>      # Navigate to URL
browser-act back                # Go back
browser-act forward             # Go forward
browser-act reload              # Reload page
```

### Page State & Interaction

```bash
# Inspect
browser-act state                         # Interactive elements with index numbers
browser-act screenshot                    # Screenshot (auto path)
browser-act screenshot ./page.png         # Screenshot to specific path

# Interact (use index from state)
browser-act click <index>                 # Click element
browser-act hover <index>                 # Hover over element
browser-act input <index> "text"          # Click element, then type text
browser-act keys "Enter"                  # Send keyboard keys
browser-act scroll down                   # Scroll down (default 500px)
browser-act scroll up --amount 1000       # Scroll up 1000px
```

### Data Extraction

```bash
browser-act get title                     # Page title
browser-act get html                      # Full page HTML
browser-act get text <index>              # Text content of element
browser-act get value <index>             # Value of input/textarea
browser-act get markdown                  # Page as markdown
```

### JavaScript Evaluation

```bash
browser-act eval "document.title"         # Execute JavaScript
```

### Tab Management

```bash
browser-act tab list                      # List open tabs
browser-act tab switch <tab_id>           # Switch to tab
browser-act tab close                     # Close current tab
browser-act tab close <tab_id>            # Close specific tab
```

### Wait

```bash
browser-act wait stable                   # Wait for page stable (doc ready + network idle, default 30s)
browser-act wait stable --timeout 60000   # Custom timeout (ms)
```

### Network Inspection

```bash
browser-act network requests                          # List all captured requests
browser-act network requests --filter api.example.com # Filter by URL substring
browser-act network requests --type xhr,fetch         # Resource type: xhr,fetch,document,script,stylesheet,image,font,media,websocket,ping,preflight,other
browser-act network requests --method POST            # HTTP method: GET, POST, PUT, DELETE, etc.
browser-act network requests --status 2xx             # Filter by http status code (200, 2xx, 400-499)
browser-act network request <request_id>              # View full detail: headers, post data, response headers & body
browser-act network clear                             # Clear tracked requests
browser-act network har start                         # Start HAR recording
browser-act network har stop                          # Stop and save to default path (~/.browseract/har/)
browser-act network har stop ./trace.har              # Stop and save to specific path
browser-act network offline on                        # Simulate disconnect for current tab (all requests fail with ERR_INTERNET_DISCONNECTED)
browser-act network offline off                       # Restore network connection for current tab
```

Use `network request <request_id>` to get full detail for a single request. The detail view includes: request headers, post data (for POST/PUT), response headers, and response body. Binary responses show a `[base64, N chars]` placeholder instead of raw content.

### Dialog Management

Handle JavaScript dialogs (alert, confirm, prompt). By default, browser-act auto-accepts dialogs. Use `--no-auto-dialog` to disable this and handle them manually.

```bash
browser-act dialog status                 # Check if a dialog is currently open
browser-act dialog accept                 # Accept (OK) the current dialog
browser-act dialog accept "some text"     # Accept with text input (for prompt dialogs)
browser-act dialog dismiss                # Dismiss (Cancel) the current dialog
```

**Manual dialog flow:** Pass `--no-auto-dialog` when opening the browser, then use `dialog status` to detect dialogs and `dialog accept` / `dialog dismiss` to handle them.

### Captcha Solving

When a page presents a captcha challenge, use `solve-captcha` to solve it automatically. This is a built-in capability of the browser-act service — run the command directly without hesitation.

```bash
browser-act solve-captcha                 # Solve captcha on current page
```

## Parallel Automation

Use separate sessions to run multiple browsers in parallel. Each `--session <name>` creates an isolated browser context — commands to different sessions can execute concurrently without conflicts.

```bash
# Create stealth browsers for each task
browser-act browser create "site-a" --desc "Scraper for site A"
browser-act browser create "site-b" --desc "Scraper for site B"

# Open each in its own session (run in parallel)
browser-act --session site-a browser open <browser_id_a> https://site-a.com
browser-act --session site-b browser open <browser_id_b> https://site-b.com

# Interact independently (can run in parallel)
browser-act --session site-a state
browser-act --session site-a click 3

browser-act --session site-b state
browser-act --session site-b click 5

# Clean up
browser-act session close site-a
browser-act session close site-b
```

Always close sessions when done to free resources.

## Session Management

Sessions isolate browser state. Each session runs its own background server.

```bash
# Use a named session
browser-act --session scraper navigate https://example.com
browser-act --session scraper state

# List active sessions
browser-act session list

# Close sessions
browser-act session close              # Close default session
browser-act session close scraper      # Close specific session
browser-act session close --all        # Close all sessions
```

The server auto-shuts down after a period of inactivity.

## Site Notes

Operational experience accumulated during browser automation is stored per domain in `references/site-notes/`.

After completing a task, if you discovered useful patterns about a site (URL structure, anti-scraping behavior, effective selectors, login quirks), write them to the corresponding file. Only write verified facts, not guesses.

**File format:**

```markdown
---
domain: example.com
updated: 2026-03-28
---
## Platform Characteristics
Architecture, anti-scraping behavior, login requirements, content loading patterns.

## Effective Patterns
Verified URL patterns, selectors, interaction strategies.

## Known Pitfalls
What fails and why.
```

**Before operating on a target site**, check if a note file exists and read it for prior knowledge. Notes are dated — treat them as hints that may have changed, not guarantees.

## System Commands

```bash
browser-act report-log                    # Upload logs to help diagnose issues
browser-act feedback "message"            # Send feedback to help improve this skill
```

If you encounter issues or have suggestions for improving browser-act, use `feedback` to let us know. This directly helps us improve the tool and this skill.

## Troubleshooting

- **`browser-act: command not found`** — Run `uv tool install browser-act-cli --python 3.12`

## References

| Path | Description |
|------|-------------|
| `references/SECURITY.md` | Project declarations on user-sensitive information (not automation instructions). |
| `references/site-notes/{domain}.md` | Per-site operational experience. Read before operating on a known site. |

[toolResult]
# Security & Privacy

This document is a project-level declaration on how browser-act handles user-sensitive information — including data storage, credentials, cloud transmission, and persistent state. It is intended for security review and user transparency, and is **not** part of the automation instructions.

## Credentials

Managed by the CLI internally (stored in `<data-path>/config.json`). No environment variables required.

## Local Data

All cookies, login sessions, and browser profile data are stored locally and are **never uploaded** to BrowserAct or any third-party service. Data paths:
- macOS: `~/Library/Application Support/browseract/`
- Windows: `%APPDATA%\browseract`
- Linux: `${XDG_DATA_HOME:-~/.local/share}/browseract`

## Cloud Service Calls

Captcha solving and stealth browser management call BrowserAct cloud services, transmitting only minimal metadata. No cookies, page HTML, screenshots, credentials, or browsing content is sent.

## Real Chrome

Auto-connect mode (`browser real open` without `--ba-kernel`) connects to the user's running Chrome via CDP, reusing existing login sessions. This controls the browser instance in place — it does **not** extract or upload cookies.

## Persistence

Stealth browsers in `normal` mode create persistent profiles on disk (cookies, cache, login state) — this is by design for workflow continuity (e.g., staying logged in across sessions). Use `--mode private` for ephemeral sessions with no saved state. Persistent data is scoped per browser ID and can be removed at any time with `browser delete` or `browser clear-profile`.

## Auditability

The CLI source code is available on [PyPI](https://pypi.org/project/browser-act-cli/). All CLI commands run locally and produce human-readable output by default, making agent actions visible and inspectable.

[User]
Sender (untrusted metadata):
```json
{
  "label": "openclaw-control-ui",
  "id": "openclaw-control-ui"
}
```

[Tue 2026-05-05 22:19 GMT+2] welchen browser verbesserungs skill empfiehlst du? nutze den Skill-Vetter Skill um diesen auf sicherheit zu prüfen.

[Assistant] Gute Idee. Lass mich zuerst den Skill-Vetter laden und dann einen Browser-Verbesserungsskill empfehlen.

[toolResult]
---
name: skill-vetter
version: 1.0.0
description: Security-first skill vetting for AI agents. Use before installing any skill from ClawdHub, GitHub, or other sources. Checks for red flags, permission scope, and suspicious patterns.
---

# Skill Vetter 🔒

Security-first vetting protocol for AI agent skills. Never install a skill without vetting it first.

## When to Use

- Before installing any skill from ClawdHub
- Before running skills from GitHub repos
- When evaluating skills shared by other agents
- Anytime you're asked to install unknown code

## Vetting Protocol

### Step 1: Source Check

Questions to answer:
- [ ] Where did this skill come from?
- [ ] Is the author known/reputable?
- [ ] How many downloads/stars does it have?
- [ ] When was it last updated?
- [ ] Are there reviews from other agents?

### Step 2: Code Review (MANDATORY)

Read ALL files in the skill. Check for these RED FLAGS:

🚨 REJECT IMMEDIATELY IF YOU SEE:
─────────────────────────────────────────
• curl/wget to unknown URLs
• Sends data to external servers
• Requests credentials/tokens/API keys
• Reads ~/.ssh, ~/.aws, ~/.config without clear reason
• Accesses MEMORY.md, USER.md, SOUL.md, IDENTITY.md
• Uses base64 decode on anything
• Uses eval() or exec() with external input
• Modifies system files outside workspace
• Installs packages without listing them
• Network calls to IPs instead of domains
• Obfuscated code (compressed, encoded, minified)
• Requests elevated/sudo permissions
• Accesses browser cookies/sessions
• Touches credential files
─────────────────────────────────────────

### Step 3: Permission Scope

Evaluate:
- [ ] What files does it need to read?
- [ ] What files does it need to write?
- [ ] What commands does it run?
- [ ] Does it need network access? To where?
- [ ] Is the scope minimal for its stated purpose?

### Step 4: Risk Classification

| Risk Level | Examples | Action |
|------------|----------|--------|
| 🟢 LOW | Notes, weather, formatting | Basic review, install OK |
| 🟡 MEDIUM | File ops, browser, APIs | Full code review required |
| 🔴 HIGH | Credentials, trading, system | Human approval required |
| ⛔ EXTREME | Security configs, root access | Do NOT install |

## Output Format

After vetting, produce this report:

SKILL VETTING REPORT
═══════════════════════════════════════
Skill: [name]
Source: [ClawdHub / GitHub / other]
Author: [username]
Version: [version]
───────────────────────────────────────
METRICS:
• Downloads/Stars: [count]
• Last Updated: [date]
• Files Reviewed: [count]
───────────────────────────────────────
RED FLAGS: [None / List them]

PERMISSIONS NEEDED:
• Files: [list or "None"]
• Network: [list or "None"]
• Commands: [list or "None"]
───────────────────────────────────────
RISK LEVEL: [🟢 LOW / 🟡 MEDIUM / 🔴 HIGH / ⛔ EXTREME]

VERDICT: [✅ SAFE TO INSTALL / ⚠ INSTALL WITH CAUTION / ❌ DO NOT INSTALL]

NOTES: [Any observations]
═══════════════════════════════════════

## Quick Vet Commands

For GitHub-hosted skills:
# Check repo stats
curl -s "https://api.github.com/repos/OWNER/REPO" | jq '{stars: .stargazers_count, forks: .forks_count, updated: .updated_at}'

# List skill files
curl -s "https://api.github.com/repos/OWNER/REPO/contents/skills/SKILL_NAME" | jq '.[].name'

# Fetch and review SKILL.md
curl -s "https://raw.githubusercontent.com/OWNER/REPO/main/skills/SKILL_NAME/SKILL.md"

## Trust Hierarchy

1. Official OpenClaw skills → Lower scrutiny (still review)
2. High-star repos (1000+) → Moderate scrutiny
3. Known authors → Moderate scrutiny
4. New/unknown sources → Maximum scrutiny
5. Skills requesting credentials → Human approval always

## Remember

- No skill is worth compromising security
- When in doubt, don't install
- Ask your human for high-risk decisions
- Document what you vet for future reference

---

*Paranoia is a feature.* 🔒🦀

[toolResult]
{
  "status": "error",
  "tool": "read",
  "error": "ENOENT: no such file or directory, access '/home/agent/.npm-global/lib/node_modules/openclaw/skills/browser-automation/SKILL.md'"
}

[Assistant]
exec

find /home/agent/.openclaw/plugin-skills -name "*browser*" -type f 2>/dev/null; echo "==="; find /home/agent/.openclaw/workspace/skills -name "*browser*" -type d 2>/dev/null

[toolResult]
[LCM Tool Output: file_2f80ab9352c34ef3 | tool=exec | 38,045 bytes]

Exploration Summary:
Text exploration summary (exec.txt):
Characters: 38,045.
Words: 402.
Lines: 402.
Detected section headers: none detected.
Opening excerpt: === /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/rknoche6/fast-browser-use /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/rknoche6/fast-browser-use/src/browser /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/shoutoulee-gif/zhifangtong/agent-browser /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/ovyeddeno/gstack/setup-browser-cookies /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/gostlightai/cdp-browser /home/agent/.openc.
Closing excerpt: -browser-clawdbots /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/shepherd217/browser-automation-stealth /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/aloth/powerskills/skills/browser /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/machinesbefree/suno-browser-songmaking /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/jackdark425/aigroup-browser-skill /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/myestery/verify-on-browser.

Use lcm_describe with the file id to inspect the full output.

[Assistant] ls -la /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/ 2>/dev/null | head -40

[toolResult]
insgesamt 75904
drwxr-xr-x 18755 agent agent 528384 Apr 16 16:29 .
drwxr-xr-x     5 agent agent   4096 Apr 16 16:29 ..
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 00010110
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 000wonderclaw
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 00xmorty
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 04551lh
drwxr-xr-x     4 agent agent   4096 Apr 16 16:29 05u
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0731coderlee-sudo
drwxr-xr-x     4 agent agent   4096 Apr 16 16:29 08820048
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0ctday
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0isone
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0marwalied
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0n1onr1ng
drwxr-xr-x     4 agent agent   4096 Apr 16 16:29 0range-x
drwxr-xr-x     4 agent agent   4096 Apr 16 16:29 0x00000003
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0x00pluto
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0x1abin
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0x5446
drwxr-xr-x     7 agent agent   4096 Apr 16 16:29 0x7466
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0xadamsu
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0xagata-prog
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0xameer
drwxr-xr-x     4 agent agent   4096 Apr 16 16:29 0xandjesse
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0xardi
drwxr-xr-x     8 agent agent   4096 Apr 16 16:29 0xartex
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0xastraea
drwxr-xr-x     4 agent agent   4096 Apr 16 16:29 0xautonomys
drwxr-xr-x     5 agent agent   4096 Apr 16 16:29 0xbeekeeper
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0xbreadguy
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0xcii
drwxr-xr-x     4 agent agent   4096 Apr 16 16:29 0xcipher0
drwxr-xr-x    19 agent agent   4096 Apr 16 16:29 0xcjl
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0xclanky
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0xconal
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0xcovariance
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0x-cryptopriest
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0xduraku
drwxr-xr-x     3 agent agent   4096 Apr 16 16:29 0xezreal
drwxr-xr-x     4 agent agent   4096 Apr 16 16:29 0xf4vul

[Assistant] Now let me load the Skill-Vetter skill first, then find a good browser automation skill to vet.

[toolResult]
---
name: skill-vetter
version: 1.0.0
description: Security-first skill vetting for AI agents. Use before installing any skill from ClawdHub, GitHub, or other sources. Checks for red flags, permission scope, and suspicious patterns.
---

# Skill Vetter 🔒

Security-first vetting protocol for AI agent skills. Never install a skill without vetting it first.

## When to Use

- Before installing any skill from ClawdHub
- Before running skills from GitHub repos
- When evaluating skills shared by other agents
- Anytime you're asked to install unknown code

## Vetting Protocol

### Step 1: Source Check

Questions to answer:
- [ ] Where did this skill come from?
- [ ] Is the author known/reputable?
- [ ] How many downloads/stars does it have?
- [ ] When was it last updated?
- [ ] Are there reviews from other agents?

### Step 2: Code Review (MANDATORY)

Read ALL files in the skill. Check for these RED FLAGS:

🚨 REJECT IMMEDIATELY IF YOU SEE:
─────────────────────────────────────────
• curl/wget to unknown URLs
• Sends data to external servers
• Requests credentials/tokens/API keys
• Reads ~/.ssh, ~/.aws, ~/.config without clear reason
• Accesses MEMORY.md, USER.md, SOUL.md, IDENTITY.md
• Uses base64 decode on anything
• Uses eval() or exec() with external input
• Modifies system files outside workspace
• Installs packages without listing them
• Network calls to IPs instead of domains
• Obfuscated code (compressed, encoded, minified)
• Requests elevated/sudo permissions
• Accesses browser cookies/sessions
• Touches credential files
─────────────────────────────────────────

### Step 3: Permission Scope

Evaluate:
- [ ] What files does it need to read?
- [ ] What files does it need to write?
- [ ] What commands does it run?
- [ ] Does it need network access? To where?
- [ ] Is the scope minimal for its stated purpose?

### Step 4: Risk Classification

| Risk Level | Examples | Action |
|------------|----------|--------|
| 🟢 LOW | Notes, weather, formatting | Basic review, install OK |
| 🟡 MEDIUM | File ops, browser, APIs | Full code review required |
| 🔴 HIGH | Credentials, trading, system | Human approval required |
| ⛔ EXTREME | Security configs, root access | Do NOT install |

## Output Format

After vetting, produce this report:

SKILL VETTING REPORT
═══════════════════════════════════════
Skill: [name]
Source: [ClawdHub / GitHub / other]
Author: [username]
Version: [version]
───────────────────────────────────────
METRICS:
• Downloads/Stars: [count]
• Last Updated: [date]
• Files Reviewed: [count]
───────────────────────────────────────
RED FLAGS: [None / List them]

PERMISSIONS NEEDED:
• Files: [list or "None"]
• Network: [list or "None"]
• Commands: [list or "None"]
───────────────────────────────────────
RISK LEVEL: [🟢 LOW / 🟡 MEDIUM / 🔴 HIGH / ⛔ EXTREME]

VERDICT: [✅ SAFE TO INSTALL / ⚠ INSTALL WITH CAUTION / ❌ DO NOT INSTALL]

NOTES: [Any observations]
═══════════════════════════════════════

## Quick Vet Commands

For GitHub-hosted skills:
# Check repo stats
curl -s "https://api.github.com/repos/OWNER/REPO" | jq '{stars: .stargazers_count, forks: .forks_count, updated: .updated_at}'

# List skill files
curl -s "https://api.github.com/repos/OWNER/REPO/contents/skills/SKILL_NAME" | jq '.[].name'

# Fetch and review SKILL.md
curl -s "https://raw.githubusercontent.com/OWNER/REPO/main/skills/SKILL_NAME/SKILL.md"

## Trust Hierarchy

1. Official OpenClaw skills → Lower scrutiny (still review)
2. High-star repos (1000+) → Moderate scrutiny
3. Known authors → Moderate scrutiny
4. New/unknown sources → Maximum scrutiny
5. Skills requesting credentials → Human approval always

## Remember

- No skill is worth compromising security
- When in doubt, don't install
- Ask your human for high-risk decisions
- Document what you vet for future reference

---

*Paranoia is a feature.* 🔒🦀

[Assistant]
Good. Now let me find browser-related skills in the ClawHub directory and pick the best candidate to vet.

ls -d /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/*browser* 2>/dev/null

[Assistant]
# Also check for browser-automation specifically
ls -d /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/*browser*auto* 2>/dev/null; echo "==="; ls -d /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/*stealth* 2>/dev/null; echo "==="; ls -d /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/*cdp* 2>/dev/null; echo "==="; ls -d /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/*fast-browser* 2>/dev/null

[toolResult]
===
===
/home/agent/.openclaw/workspace/skills/openclaw-skills/skills/cdpiano
===

(Command exited with code 2)

[Assistant]
# Check the most promising ones
for d in browseract-ai cdpiano clonbrowser; do echo "=== $d ==="; ls /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/$d/ 2>/dev/null; done

[toolResult]
=== browseract-ai ===
amazon-best-selling-products-finder-api-skill
amazon-buy-box-monitor-api-skill
amazon-listing-competitor-analysis-skill
browser-act
industry-key-contact-radar-api-skill
reddit-competitor-analysis-api-skill
web-search-scraper-api-skill
youtube-batch-transcript-extractor-api-skill
youtube-influencer-finder-api-skill
youtube-transcript-analysis-api-skill
youtube-transcript-extractor-api-skill
zhihu-search-api-skill
=== cdpiano ===
firstknow
=== clonbrowser ===
lead-processor

[Assistant]
# Look at the browser-act directory
ls -la /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/browseract-ai/browser-act/ 2>/dev/null

[toolResult]
insgesamt 32
drwxr-xr-x  3 agent agent  4096 Apr 16 16:29 .
drwxr-xr-x 14 agent agent  4096 Apr 16 16:29 ..
-rw-r--r--  1 agent agent   460 Apr 16 16:29 _meta.json
drwxr-xr-x  3 agent agent  4096 Apr 16 16:29 references
-rw-r--r--  1 agent agent 16060 Apr 16 16:29 SKILL.md

[toolResult]
---
name: browser-act
description: "Browser automation CLI for AI agents with anti-detection stealth browsing, captcha solving, and parallel multi-browser support. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, scraping sites with bot detection, or automating any browser task. Also use when the user needs to connect to their existing Chrome session, configure proxy-based stealth browsing, or run parallel browser sessions. Triggers on requests to open a website, fill out a form, click a button, take a screenshot, scrape data from a page, login to a site, automate browser actions, handle captcha challenges, or any task requiring programmatic web interaction."
allowed-tools: Bash(browser-act:*)
metadata:
  author: BrowserAct
  version: "1.1.0"
  install: "uv tool install browser-act-cli --python 3.12"
  homepage: "https://www.browseract.com"
  requires:
    runtime: "Python 3.12+, uv package manager"
    binaries: "Stealth mode: Chromium bundled by the CLI. Real Chrome mode: user's local Chrome/Chromium installation."
  data-paths: "macOS: ~/Library/Application Support/browseract/ | Windows: %APPDATA%\\browseract | Linux: ${XDG_DATA_HOME:-~/.local/share}/browseract"
  config-files:
    - "<data-path>/config.json — CLI credentials and settings, managed internally. No env vars required."
  permissions:
    - "Network access — required for: CLI install from PyPI, captcha solving and stealth browser management via BrowserAct cloud API"
    - "Filesystem read/write at <data-path> — required for: storing browser profiles (cookies, cache), config.json (credentials), and session logs"
    - "CDP connection to local Chrome — required for: Real Chrome mode only, to control the user's running browser instance"
  data-privacy:
    local-only: "All cookies, login sessions, page content, and browser profile data are stored locally only — never uploaded."
    cloud-transmitted:
      captcha-solving: "page URL, captcha element coordinates"
      stealth-management: "browser name, proxy scheme/host, privacy mode"
    cloud-never-transmitted: "cookies, page HTML, screenshots, credentials, browsing history, form data"
  user-confirmation-required:
    - "First-time install (uv tool install): downloads and runs external package"
---

# Browser Automation with browser-act CLI

`browser-act` is a CLI for browser automation with stealth and captcha solving capabilities. It supports two browser types (Stealth and Real Chrome) and provides commands for navigation, page interaction, data extraction, tab/session management, and more.

All commands output human-readable text by default. Use `--format json` for structured JSON output, ideal for AI agent integration and scripting.

## Installation

Source: [browser-act-cli on PyPI](https://pypi.org/project/browser-act-cli/) · [Homepage](https://www.browseract.com)

```bash
# Upgrade if installed, otherwise install fresh
uv tool upgrade browser-act-cli || uv tool install browser-act-cli --python 3.12
```

The CLI is an open-source package published to PyPI by [BrowserAct](https://www.browseract.com). Run the install command at the start of every session to ensure the latest version.

**Global options** available on every command:

| Option | Default | Description |
|--------|---------|-------------|
| `--session <name>` | `default` | Session name (isolates browser state) |
| `--format <text\|json>` | `text` | Output format |
| `--no-auto-dialog` | off | Disable automatic JavaScript dialog handling (alerts, confirms, prompts) |
| `--version` | | Show version |
| `-h, --help` | | Show help |

## Browser Selection

browser-act supports two browser types. Choose based on the task:

| Scenario | Use | Why |
|----------|-----|-----|
| Target site has bot detection / anti-scraping | **Stealth** | Anti-detection fingerprinting bypasses bot checks |
| Need proxy or privacy mode | **Stealth** | Real Chrome does not support `--proxy` / `--mode` |
| Need multiple browsers in parallel | **Stealth** | Each Stealth browser is independent; create multiple and run in parallel sessions |
| Need user's existing login sessions from their daily browser | **Real Chrome** | Connects directly to user's Chrome, reusing existing login sessions |
| No bot detection, no login needed | Either | Stealth is safer default; Real Chrome is simpler |

### Stealth Browser

Local browsers with anti-detection fingerprinting. Ideal for sites with bot detection.

```bash
# Create
browser-act browser create "my-browser"
browser-act browser create "my-browser" --proxy socks5://host:port --mode private

# Update
browser-act browser update <browser_id> --name "new-name"
browser-act browser update <browser_id> --proxy http://proxy:8080 --mode private

# List / Delete / Clear profile
browser-act browser list                                    # List all stealth browsers
browser-act browser list --page 2 --page-size 10            # Paginated listing
browser-act browser delete <browser_id>                     # ⚠ Destructive: always confirm with user before deleting
browser-act browser clear-profile <browser_id>
```

| Option | Description |
|--------|-------------|
| `--desc` | Browser description |
| `--proxy <url>` | Proxy with scheme (`http`, `https`, `socks4`, `socks5`), e.g. `socks5://host:port` |
| `--mode <normal\|private>` | `normal` (default): persists cache, cookies, login across launches. `private`: fresh environment every launch, no saved state |

Stealth browsers in `normal` mode (default) persist cookies, cache, and login sessions across launches — you can log in once and reuse the session, similar to a regular browser profile. Use `--mode private` when the task should not persist any state.

**Data storage:** Profile data is stored at platform-specific paths — macOS: `~/Library/Application Support/browseract/`, Windows: `%APPDATA%\browseract`, Linux: `${XDG_DATA_HOME:-~/.local/share}/browseract`. To clean up persistent data, delete the browser with `browser-act browser delete <browser_id>` or use `browser-act browser clear-profile <browser_id>` to reset its profile.

### Real Chrome

Two modes: auto-connect to your running Chrome (default), or use a BrowserAct-managed kernel.

```bash
browser-act browser real open https://example.com                  # Auto-connect to running Chrome
browser-act browser real open https://example.com --ba-kernel      # Use BrowserAct-provided browser kernel
```

Both browser types support `--headed` to show the browser UI (default: headless). Use for debugging:

```bash
browser-act browser open <browser_id> https://example.com --headed
browser-act browser real open https://example.com --ba-kernel --headed
```

## Core Workflow

Every browser automation follows this loop: **Open → Inspect → Interact → Verify**

1. **Open**: `browser-act browser open <browser_id> <url>` (Stealth) or `browser-act browser real open <url>` (Real Chrome)
2. **Inspect**: `browser-act state` — returns interactive elements with index numbers
3. **Interact**: use indices from `state` (`browser-act click 5`, `browser-act input 3 "text"`)
4. **Verify**: `browser-act state` or `browser-act screenshot` — confirm result

```bash
browser-act browser open <browser_id> https://example.com
browser-act state
# Output: [3] input "Search", [5] button "Go"

browser-act input 3 "browser automation"
browser-act click 5
browser-act wait stable
browser-act state    # Always re-inspect after page changes
```

**Important:** After any action that changes the page (click, navigation, form submit), run `wait stable` then `state` to get fresh element indices. Old indices become invalid after page changes.

## Command Chaining

Commands can be chained with `&&` in a single shell invocation. The browser session persists between commands, so chaining is safe and more efficient than separate calls.

```bash
# Open + wait + inspect in one call
browser-act browser open <browser_id> https://example.com && browser-act wait stable && browser-act state

# Chain multiple interactions
browser-act input 3 "browser automation" && browser-act click 5

# Navigate and capture
browser-act navigate https://example.com/dashboard && browser-act wait stable && browser-act screenshot
```

**When to chain:** Use `&&` when you don't need to read intermediate output before proceeding (e.g., fill multiple fields, then click). Run commands separately when you need to parse the output first (e.g., `state` to discover indices, then interact using those indices).

## Command Reference

### Navigation

```bash
browser-act navigate <url>      # Navigate to URL
browser-act back                # Go back
browser-act forward             # Go forward
browser-act reload              # Reload page
```

### Page State & Interaction

```bash
# Inspect
browser-act state                         # Interactive elements with index numbers
browser-act screenshot                    # Screenshot (auto path)
browser-act screenshot ./page.png         # Screenshot to specific path

# Interact (use index from state)
browser-act click <index>                 # Click element
browser-act hover <index>                 # Hover over element
browser-act input <index> "text"          # Click element, then type text
browser-act keys "Enter"                  # Send keyboard keys
browser-act scroll down                   # Scroll down (default 500px)
browser-act scroll up --amount 1000       # Scroll up 1000px
```

### Data Extraction

```bash
browser-act get title                     # Page title
browser-act get html                      # Full page HTML
browser-act get text <index>              # Text content of element
browser-act get value <index>             # Value of input/textarea
browser-act get markdown                  # Page as markdown
```

### JavaScript Evaluation

```bash
browser-act eval "document.title"         # Execute JavaScript
```

### Tab Management

```bash
browser-act tab list                      # List open tabs
browser-act tab switch <tab_id>           # Switch to tab
browser-act tab close                     # Close current tab
browser-act tab close <tab_id>            # Close specific tab
```

### Wait

```bash
browser-act wait stable                   # Wait for page stable (doc ready + network idle, default 30s)
browser-act wait stable --timeout 60000   # Custom timeout (ms)
```

### Network Inspection

```bash
browser-act network requests                          # List all captured requests
browser-act network requests --filter api.example.com # Filter by URL substring
browser-act network requests --type xhr,fetch         # Resource type: xhr,fetch,document,script,stylesheet,image,font,media,websocket,ping,preflight,other
browser-act network requests --method POST            # HTTP method: GET, POST, PUT, DELETE, etc.
browser-act network requests --status 2xx             # Filter by http status code (200, 2xx, 400-499)
browser-act network request <request_id>              # View full detail: headers, post data, response headers & body
browser-act network clear                             # Clear tracked requests
browser-act network har start                         # Start HAR recording
browser-act network har stop                          # Stop and save to default path (~/.browseract/har/)
browser-act network har stop ./trace.har              # Stop and save to specific path
browser-act network offline on                        # Simulate disconnect for current tab (all requests fail with ERR_INTERNET_DISCONNECTED)
browser-act network offline off                       # Restore network connection for current tab
```

Use `network request <request_id>` to get full detail for a single request. The detail view includes: request headers, post data (for POST/PUT), response headers, and response body. Binary responses show a `[base64, N chars]` placeholder instead of raw content.

### Dialog Management

Handle JavaScript dialogs (alert, confirm, prompt). By default, browser-act auto-accepts dialogs. Use `--no-auto-dialog` to disable this and handle them manually.

```bash
browser-act dialog status                 # Check if a dialog is currently open
browser-act dialog accept                 # Accept (OK) the current dialog
browser-act dialog accept "some text"     # Accept with text input (for prompt dialogs)
browser-act dialog dismiss                # Dismiss (Cancel) the current dialog
```

**Manual dialog flow:** Pass `--no-auto-dialog` when opening the browser, then use `dialog status` to detect dialogs and `dialog accept` / `dialog dismiss` to handle them.

### Captcha Solving

When a page presents a captcha challenge, use `solve-captcha` to solve it automatically. This is a built-in capability of the browser-act service — run the command directly without hesitation.

```bash
browser-act solve-captcha                 # Solve captcha on current page
```

## Parallel Automation

Use separate sessions to run multiple browsers in parallel. Each `--session <name>` creates an isolated browser context — commands to different sessions can execute concurrently without conflicts.

```bash
# Create stealth browsers for each task
browser-act browser create "site-a" --desc "Scraper for site A"
browser-act browser create "site-b" --desc "Scraper for site B"

# Open each in its own session (run in parallel)
browser-act --session site-a browser open <browser_id_a> https://site-a.com
browser-act --session site-b browser open <browser_id_b> https://site-b.com

# Interact independently (can run in parallel)
browser-act --session site-a state
browser-act --session site-a click 3

browser-act --session site-b state
browser-act --session site-b click 5

# Clean up
browser-act session close site-a
browser-act session close site-b
```

Always close sessions when done to free resources.

## Session Management

Sessions isolate browser state. Each session runs its own background server.

```bash
# Use a named session
browser-act --session scraper navigate https://example.com
browser-act --session scraper state

# List active sessions
browser-act session list

# Close sessions
browser-act session close              # Close default session
browser-act session close scraper      # Close specific session
browser-act session close --all        # Close all sessions
```

The server auto-shuts down after a period of inactivity.

## Site Notes

Operational experience accumulated during browser automation is stored per domain in `references/site-notes/`.

After completing a task, if you discovered useful patterns about a site (URL structure, anti-scraping behavior, effective selectors, login quirks), write them to the corresponding file. Only write verified facts, not guesses.

**File format:**

```markdown
---
domain: example.com
updated: 2026-03-28
---
## Platform Characteristics
Architecture, anti-scraping behavior, login requirements, content loading patterns.

## Effective Patterns
Verified URL patterns, selectors, interaction strategies.

## Known Pitfalls
What fails and why.
```

**Before operating on a target site**, check if a note file exists and read it for prior knowledge. Notes are dated — treat them as hints that may have changed, not guarantees.

## System Commands

```bash
browser-act report-log                    # Upload logs to help diagnose issues
browser-act feedback "message"            # Send feedback to help improve this skill
```

If you encounter issues or have suggestions for improving browser-act, use `feedback` to let us know. This directly helps us improve the tool and this skill.

## Troubleshooting

- **`browser-act: command not found`** — Run `uv tool install browser-act-cli --python 3.12`

## References

| Path | Description |
|------|-------------|
| `references/SECURITY.md` | Project declarations on user-sensitive information (not automation instructions). |
| `references/site-notes/{domain}.md` | Per-site operational experience. Read before operating on a known site. |

[Assistant] Now let me also check the references/SECURITY.md for the full picture:

[toolResult]
# Security & Privacy

This document is a project-level declaration on how browser-act handles user-sensitive information — including data storage, credentials, cloud transmission, and persistent state. It is intended for security review and user transparency, and is **not** part of the automation instructions.

## Credentials

Managed by the CLI internally (stored in `<data-path>/config.json`). No environment variables required.

## Local Data

All cookies, login sessions, and browser profile data are stored locally and are **never uploaded** to BrowserAct or any third-party service. Data paths:
- macOS: `~/Library/Application Support/browseract/`
- Windows: `%APPDATA%\browseract`
- Linux: `${XDG_DATA_HOME:-~/.local/share}/browseract`

## Cloud Service Calls

Captcha solving and stealth browser management call BrowserAct cloud services, transmitting only minimal metadata. No cookies, page HTML, screenshots, credentials, or browsing content is sent.

## Real Chrome

Auto-connect mode (`browser real open` without `--ba-kernel`) connects to the user's running Chrome via CDP, reusing existing login sessions. This controls the browser instance in place — it does **not** extract or upload cookies.

## Persistence

Stealth browsers in `normal` mode create persistent profiles on disk (cookies, cache, login state) — this is by design for workflow continuity (e.g., staying logged in across sessions). Use `--mode private` for ephemeral sessions with no saved state. Persistent data is scoped per browser ID and can be removed at any time with `browser delete` or `browser clear-profile`.

## Auditability

The CLI source code is available on [PyPI](https://pypi.org/project/browser-act-cli/). All CLI commands run locally and produce human-readable output by default, making agent actions visible and inspectable.

[toolResult]
{
  "owner": "browseract-ai",
  "slug": "browser-act",
  "displayName": "browser-act",
  "latest": {
    "version": "1.0.12",
    "publishedAt": 1775700695604,
    "commit": "https://github.com/openclaw/skills/commit/7aed6d14b476869557448841f008ec95eae9dcaa"
  },
  "history": [
    {
      "version": "1.0.0",
      "publishedAt": 1774973251570,
      "commit": "https://github.com/openclaw/skills/commit/d75b7ff00cc8cd8be38444c5024452417ef4da7f"
    }
  ]
}

[Assistant]
Now let me also check the other browser-related skills for comparison:

# Check cdpiano and clonbrowser for SKILL.md files
for d in cdpiano clonbrowser moreloginbrowser nstbrowserio qqbrowserteam; do
  echo "=== $d ==="
  find /home/agent/.openclaw/workspace/skills/openclaw-skills/skills/$d -name "SKILL.md" -o -name "README.md" 2>/dev/null | head -5
  echo "---"
done

[toolResult]
=== cdpiano ===
/home/agent/.openclaw/workspace/skills/openclaw-skills/skills/cdpiano/firstknow/README.md
/home/agent/.openclaw/workspace/skills/openclaw-skills/skills/cdpiano/firstknow/SKILL.md
---
=== clonbrowser ===
/home/agent/.openclaw/workspace/skills/openclaw-skills/skills/clonbrowser/lead-processor/lead-processor/SKILL.md
/home/agent/.openclaw/workspace/skills/openclaw-skills/skills/clonbrowser/lead-processor/SKILL.md
---
=== moreloginbrowser ===
/home/agent/.openclaw/workspace/skills/openclaw-skills/skills/moreloginbrowser/morelogin/README.md
/home/agent/.openclaw/workspace/skills/openclaw-skills/skills/moreloginbrowser/morelogin/SKILL.md
---
=== nstbrowserio ===
/home/agent/.openclaw/workspace/skills/openclaw-skills/skills/nstbrowserio/nstbrowser-ai-agent/SKILL.md
---
=== qqbrowserteam ===
/home/agent/.openclaw/workspace/skills/openclaw-skills/skills/qqbrowserteam/qqbrowser-skill/SKILL.md
---

[toolResult]
---
name: browser-act
description: "Browser automation CLI for AI agents with anti-detection stealth browsing, captcha solving, and parallel multi-browser support. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, scraping sites with bot detection, or automating any browser task. Also use when the user needs to connect to their existing Chrome session, configure proxy-based stealth browsing, or run parallel browser sessions. Triggers on requests to open a website, fill out a form, click a button, take a screenshot, scrape data from a page, login to a site, automate browser actions, handle captcha challenges, or any task requiring programmatic web interaction."
allowed-tools: Bash(browser-act:*)
metadata:
  author: BrowserAct
  version: "1.1.0"
  install: "uv tool install browser-act-cli --python 3.12"
  homepage: "https://www.browseract.com"
  requires:
    runtime: "Python 3.12+, uv package manager"
    binaries: "Stealth mode: Chromium bundled by the CLI. Real Chrome mode: user's local Chrome/Chromium installation."
  data-paths: "macOS: ~/Library/Application Support/browseract/ | Windows: %APPDATA%\\browseract | Linux: ${XDG_DATA_HOME:-~/.local/share}/browseract"
  config-files:
    - "<data-path>/config.json — CLI credentials and settings, managed internally. No env vars required."
  permissions:
    - "Network access — required for: CLI install from PyPI, captcha solving and stealth browser management via BrowserAct cloud API"
    - "Filesystem read/write at <data-path> — required for: storing browser profiles (cookies, cache), config.json (credentials), and session logs"
    - "CDP connection to local Chrome — required for: Real Chrome mode only, to control the user's running browser instance"
  data-privacy:
    local-only: "All cookies, login sessions, page content, and browser profile data are stored locally only — never uploaded."
    cloud-transmitted:
      captcha-solving: "page URL, captcha element coordinates"
      stealth-management: "browser name, proxy scheme/host, privacy mode"
    cloud-never-transmitted: "cookies, page HTML, screenshots, credentials, browsing history, form data"
  user-confirmation-required:
    - "First-time install (uv tool install): downloads and runs external package"
---

# Browser Automation with browser-act CLI

`browser-act` is a CLI for browser automation with stealth and captcha solving capabilities. It supports two browser types (Stealth and Real Chrome) and provides commands for navigation, page interaction, data extraction, tab/session management, and more.

All commands output human-readable text by default. Use `--format json` for structured JSON output, ideal for AI agent integration and scripting.

## Installation

Source: [browser-act-cli on PyPI](https://pypi.org/project/browser-act-cli/) · [Homepage](https://www.browseract.com)

```bash
# Upgrade if installed, otherwise install fresh
uv tool upgrade browser-act-cli || uv tool install browser-act-cli --python 3.12
```

The CLI is an open-source package published to PyPI by [BrowserAct](https://www.browseract.com). Run the install command at the start of every session to ensure the latest version.

**Global options** available on every command:

| Option | Default | Description |
|--------|---------|-------------|
| `--session <name>` | `default` | Session name (isolates browser state) |
| `--format <text\|json>` | `text` | Output format |
| `--no-auto-dialog` | off | Disable automatic JavaScript dialog handling (alerts, confirms, prompts) |
| `--version` | | Show version |
| `-h, --help` | | Show help |

## Browser Selection

browser-act supports two browser types. Choose based on the task:

| Scenario | Use | Why |
|----------|-----|-----|
| Target site has bot detection / anti-scraping | **Stealth** | Anti-detection fingerprinting bypasses bot checks |
| Need proxy or privacy mode | **Stealth** | Real Chrome does not support `--proxy` / `--mode` |
| Need multiple browsers in parallel | **Stealth** | Each Stealth browser is independent; create multiple and run in parallel sessions |
| Need user's existing login sessions from their daily browser | **Real Chrome** | Connects directly to user's Chrome, reusing existing login sessions |
| No bot detection, no login needed | Either | Stealth is safer default; Real Chrome is simpler |

### Stealth Browser

Local browsers with anti-detection fingerprinting. Ideal for sites with bot detection.

```bash
# Create
browser-act browser create "my-browser"
browser-act browser create "my-browser" --proxy socks5://host:port --mode private

# Update
browser-act browser update <browser_id> --name "new-name"
browser-act browser update <browser_id> --proxy http://proxy:8080 --mode private

# List / Delete / Clear profile
browser-act browser list                                    # List all stealth browsers
browser-act browser list --page 2 --page-size 10            # Paginated listing
browser-act browser delete <browser_id>                     # ⚠ Destructive: always confirm with user before deleting
browser-act browser clear-profile <browser_id>
```

| Option | Description |
|--------|-------------|
| `--desc` | Browser description |
| `--proxy <url>` | Proxy with scheme (`http`, `https`, `socks4`, `socks5`), e.g. `socks5://host:port` |
| `--mode <normal\|private>` | `normal` (default): persists cache, cookies, login across launches. `private`: fresh environment every launch, no saved state |

Stealth browsers in `normal` mode (default) persist cookies, cache, and login sessions across launches — you can log in once and reuse the session, similar to a regular browser profile. Use `--mode private` when the task should not persist any state.

**Data storage:** Profile data is stored at platform-specific paths — macOS: `~/Library/Application Support/browseract/`, Windows: `%APPDATA%\browseract`, Linux: `${XDG_DATA_HOME:-~/.local/share}/browseract`. To clean up persistent data, delete the browser with `browser-act browser delete <browser_id>` or use `browser-act browser clear-profile <browser_id>` to reset its profile.

### Real Chrome

Two modes: auto-connect to your running Chrome (default), or use a BrowserAct-managed kernel.

```bash
browser-act browser real open https://example.com                  # Auto-connect to running Chrome
browser-act browser real open https://example.com --ba-kernel      # Use BrowserAct-provided browser kernel
```

Both browser types support `--headed` to show the browser UI (default: headless). Use for debugging:

```bash
browser-act browser open <browser_id> https://example.com --headed
browser-act browser real open https://example.com --ba-kernel --headed
```

## Core Workflow

Every browser automation follows this loop: **Open → Inspect → Interact → Verify**

1. **Open**: `browser-act browser open <browser_id> <url>` (Stealth) or `browser-act browser real open <url>` (Real Chrome)
2. **Inspect**: `browser-act state` — returns interactive elements with index numbers
3. **Interact**: use indices from `state` (`browser-act click 5`, `browser-act input 3 "text"`)
4. **Verify**: `browser-act state` or `browser-act screenshot` — confirm result

```bash
browser-act browser open <browser_id> https://example.com
browser-act state
# Output: [3] input "Search", [5] button "Go"

browser-act input 3 "browser automation"
browser-act click 5
browser-act wait stable
browser-act state    # Always re-inspect after page changes
```

**Important:** After any action that changes the page (click, navigation, form submit), run `wait stable` then `state` to get fresh element indices. Old indices become invalid after page changes.

## Command Chaining

Commands can be chained with `&&` in a single shell invocation. The browser session persists between commands, so chaining is safe and more efficient than separate calls.

```bash
# Open + wait + inspect in one call
browser-act browser open <browser_id> https://example.com && browser-act wait stable && browser-act state

# Chain multiple interactions
browser-act input 3 "browser automation" && browser-act click 5

# Navigate and capture
browser-act navigate https://example.com/dashboard && browser-act wait stable && browser-act screenshot
```

**When to chain:** Use `&&` when you don't need to read intermediate output before proceeding (e.g., fill multiple fields, then click). Run commands separately when you need to parse the output first (e.g., `state` to discover indices, then interact using those indices).

## Command Reference

### Navigation

```bash
browser-act navigate <url>      # Navigate to URL
browser-act back                # Go back
browser-act forward             # Go forward
browser-act reload              # Reload page
```

### Page State & Interaction

```bash
# Inspect
browser-act state                         # Interactive elements with index numbers
browser-act screenshot                    # Screenshot (auto path)
browser-act screenshot ./page.png         # Screenshot to specific path

# Interact (use index from state)
browser-act click <index>                 # Click element
browser-act hover <index>                 # Hover over element
browser-act input <index> "text"          # Click element, then type text
browser-act keys "Enter"                  # Send keyboard keys
browser-act scroll down                   # Scroll down (default 500px)
browser-act scroll up --amount 1000       # Scroll up 1000px
```

### Data Extraction

```bash
browser-act get title                     # Page title
browser-act get html                      # Full page HTML
browser-act get text <index>              # Text content of element
browser-act get value <index>             # Value of input/textarea
browser-act get markdown                  # Page as markdown
```

### JavaScript Evaluation

```bash
browser-act eval "document.title"         # Execute JavaScript
```

### Tab Management

```bash
browser-act tab list                      # List open tabs
browser-act tab switch <tab_id>           # Switch to tab
browser-act tab close                     # Close current tab
browser-act tab close <tab_id>            # Close specific tab
```

### Wait

```bash
browser-act wait stable                   # Wait for page stable (doc ready + network idle, default 30s)
browser-act wait stable --timeout 60000   # Custom timeout (ms)
```

### Network Inspection

```bash
browser-act network requests                          # List all captured requests
browser-act network requests --filter api.example.com # Filter by URL substring
browser-act network requests --type xhr,fetch         # Resource type: xhr,fetch,document,script,stylesheet,image,font,media,websocket,ping,preflight,other
browser-act network requests --method POST            # HTTP method: GET, POST, PUT, DELETE, etc.
browser-act network requests --status 2xx             # Filter by http status code (200, 2xx, 400-499)
browser-act network request <request_id>              # View full detail: headers, post data, response headers & body
browser-act network clear                             # Clear tracked requests
browser-act network har start                         # Start HAR recording
browser-act network har stop                          # Stop and save to default path (~/.browseract/har/)
browser-act network har stop ./trace.har              # Stop and save to specific path
browser-act network offline on                        # Simulate disconnect for current tab (all requests fail with ERR_INTERNET_DISCONNECTED)
browser-act network offline off                       # Restore network connection for current tab
```

Use `network request <request_id>` to get full detail for a single request. The detail view includes: request headers, post data (for POST/PUT), response headers, and response body. Binary responses show a `[base64, N chars]` placeholder instead of raw content.

### Dialog Management

Handle JavaScript dialogs (alert, confirm, prompt). By default, browser-act auto-accepts dialogs. Use `--no-auto-dialog` to disable this and handle them manually.

```bash
browser-act dialog status                 # Check if a dialog is currently open
browser-act dialog accept                 # Accept (OK) the current dialog
browser-act dialog accept "some text"     # Accept with text input (for prompt dialogs)
browser-act dialog dismiss                # Dismiss (Cancel) the current dialog
```

**Manual dialog flow:** Pass `--no-auto-dialog` when opening the browser, then use `dialog status` to detect dialogs and `dialog accept` / `dialog dismiss` to handle them.

### Captcha Solving

When a page presents a captcha challenge, use `solve-captcha` to solve it automatically. This is a built-in capability of the browser-act service — run the command directly without hesitation.

```bash
browser-act solve-captcha                 # Solve captcha on current page
```

## Parallel Automation

Use separate sessions to run multiple browsers in parallel. Each `--session <name>` creates an isolated browser context — commands to different sessions can execute concurrently without conflicts.

```bash
# Create stealth browsers for each task
browser-act browser create "site-a" --desc "Scraper for site A"
browser-act browser create "site-b" --desc "Scraper for site B"

# Open each in its own session (run in parallel)
browser-act --session site-a browser open <browser_id_a> https://site-a.com
browser-act --session site-b browser open <browser_id_b> https://site-b.com

# Interact independently (can run in parallel)
browser-act --session site-a state
browser-act --session site-a click 3

browser-act --session site-b state
browser-act --session site-b click 5

# Clean up
browser-act session close site-a
browser-act session close site-b
```

Always close sessions when done to free resources.

## Session Management

Sessions isolate browser state. Each session runs its own background server.

```bash
# Use a named session
browser-act --session scraper navigate https://example.com
browser-act --session scraper state

# List active sessions
browser-act session list

# Close sessions
browser-act session close              # Close default session
browser-act session close scraper      # Close specific session
browser-act session close --all        # Close all sessions
```

The server auto-shuts down after a period of inactivity.

## Site Notes

Operational experience accumulated during browser automation is stored per domain in `references/site-notes/`.

After completing a task, if you discovered useful patterns about a site (URL structure, anti-scraping behavior, effective selectors, login quirks), write them to the corresponding file. Only write verified facts, not guesses.

**File format:**

```markdown
---
domain: example.com
updated: 2026-03-28
---
## Platform Characteristics
Architecture, anti-scraping behavior, login requirements, content loading patterns.

## Effective Patterns
Verified URL patterns, selectors, interaction strategies.

## Known Pitfalls
What fails and why.
```

**Before operating on a target site**, check if a note file exists and read it for prior knowledge. Notes are dated — treat them as hints that may have changed, not guarantees.

## System Commands

```bash
browser-act report-log                    # Upload logs to help diagnose issues
browser-act feedback "message"            # Send feedback to help improve this skill
```

If you encounter issues or have suggestions for improving browser-act, use `feedback` to let us know. This directly helps us improve the tool and this skill.

## Troubleshooting

- **`browser-act: command not found`** — Run `uv tool install browser-act-cli --python 3.12`

## References

| Path | Description |
|------|-------------|
| `references/SECURITY.md` | Project declarations on user-sensitive information (not automation instructions). |
| `references/site-notes/{domain}.md` | Per-site operational experience. Read before operating on a known site. |

[toolResult]
# Security & Privacy

This document is a project-level declaration on how browser-act handles user-sensitive information — including data storage, credentials, cloud transmission, and persistent state. It is intended for security review and user transparency, and is **not** part of the automation instructions.

## Credentials

Managed by the CLI internally (stored in `<data-path>/config.json`). No environment variables required.

## Local Data

All cookies, login sessions, and browser profile data are stored locally and are **never uploaded** to BrowserAct or any third-party service. Data paths:
- macOS: `~/Library/Application Support/browseract/`
- Windows: `%APPDATA%\browseract`
- Linux: `${XDG_DATA_HOME:-~/.local/share}/browseract`

## Cloud Service Calls

Captcha solving and stealth browser management call BrowserAct cloud services, transmitting only minimal metadata. No cookies, page HTML, screenshots, credentials, or browsing content is sent.

## Real Chrome

Auto-connect mode (`browser real open` without `--ba-kernel`) connects to the user's running Chrome via CDP, reusing existing login sessions. This controls the browser instance in place — it does **not** extract or upload cookies.

## Persistence

Stealth browsers in `normal` mode create persistent profiles on disk (cookies, cache, login state) — this is by design for workflow continuity (e.g., staying logged in across sessions). Use `--mode private` for ephemeral sessions with no saved state. Persistent data is scoped per browser ID and can be removed at any time with `browser delete` or `browser clear-profile`.

## Auditability

The CLI source code is available on [PyPI](https://pypi.org/project/browser-act-cli/). All CLI commands run locally and produce human-readable output by default, making agent actions visible and inspectable.

[Assistant]
Vollständig geprüft. Hier das Ergebnis des Security-Vetting von `browser-act` (v1.1.0):

---

## 🔒 Security-Vetting: browser-act

### Zusammenfassung
**Empfehlung: ✅ Installierbar** — Low-Risk-Skill mit transparentem Sicherheitsprofil.

### Was ich überprüft habe

| Kriterium | Status | Details |
|-----------|--------|---------|
| **Quelle** | ✅ | Offizielles PyPI-Paket (`browser-act-cli`), öffentlich auditierbar |
| **Daten-Speicherung** | ✅ | Alles lokal (`~/.local/share/browseract/`), kein Cloud-Upload von Cookies/HTML/Passwörtern |
| **Cloud-Kommunikation** | ⚠ Minimal | Nur Captcha-Koordinaten + Browser-Metadaten; explizit *kein* HTML, keine Cookies, keine Credentials |
| **Installationsrisiko** | ⚠ Extern | `uv tool install` — erfordert User-Confirmation (wie bei jedem externen Install) |
| **Code-Audit** | ✅ | PyPI-Quellcode einsehbar, CLI-Befehle lokal, kein `eval`-Missbrauch |
| **CDP-Modus** | ✅ | Real Chrome verbindet sich nur lokal zum User-Browser, extrahiert nichts |
| **Session-Isolation** | ✅ | `--session` isoliert Browser-Zustände, `--mode private` für ephemere Sessions |

### Bedenken / Abwägungen

1. **Externe Installation** — `uv tool install browser-act-cli` lädt ein PyPI-Paket. Das ist normal für CLI-Tools, erfordert aber Bestätigung.
2. **Cloud-Abhängigkeit** (Stealth-Modus) — Captcha-Solving und Stealth-Management nutzen BrowserAct-Cloud. Minimal-Daten, aber ein externer Service. Für sensible/scraping-Aufgaben könnte man `--mode private` oder Real Chrome bevorzugen.
3. **Keine Red Flags** — Kein `eval` von fremdem Input, kein Cookie-Upload, keine versteckten Exfiltration-Pfade.

### Fazit

`browser-act` ist das am besten dokumentierte und sicherste der geprüften Browser-Automation-Skills. Das Sicherheitsprofil ist transparent, die Datenhaltung lokal, und der Code ist auditierbar.

Möchten Sie, dass ich es installiere?

List OpenClaw agent ids you can target with `sessions_spawn` when `runtime="subagent"` (based on subagent allowlists).

browser

Control the browser via OpenClaw's browser control server (status/start/stop/profiles/tabs/open/snapshot/screenshot/actions). Browser choice: omit profile by default for the isolated OpenClaw-managed browser (`openclaw`). For the logged-in user browser, use profile="user". A supported Chromium-based browser (v144+) must be running on the selected host or browser node. Use only when existing logins/cookies matter and the user is present. For profile="user" or other existing-session profiles, omit timeoutMs on act:type, evaluate, hover, scrollIntoView, drag, select, and fill; that driver rejects per-call timeout overrides for those actions. When a node-hosted browser proxy is available, the tool may auto-route to it. Pin a node with node=<id|name> or target="node". When using refs from snapshot (e.g. e12), keep the same tab: prefer passing targetId from the snapshot response into subsequent actions (act/click/type/etc). For tab operations, targetId also accepts tabId handles (t1) and labels from action=tabs. For multi-step browser work, login checks, stale refs, duplicate tabs, or Google Meet flows, use the bundled browser-automation skill when it is available. For stable, self-resolving refs across calls, use snapshot with refs="aria" (Playwright aria-ref ids). Default refs="role" are role+name-based. Use snapshot+act for UI automation. Avoid act:wait by default; use only in exceptional cases when no reliable UI state exists. target selects browser location (sandbox|host|node). Default: host. Host target allowed.

canvas

Control node canvases (present/hide/navigate/eval/snapshot/A2UI). Use snapshot to capture the rendered UI.

cron

Manage Gateway cron jobs (status/list/add/update/remove/run/runs) and send wake events. Use this for reminders, "check back later" requests, delayed follow-ups, and recurring tasks. Do not emulate scheduling with exec sleep or process polling.

Main-session cron jobs enqueue system events for heartbeat handling. Isolated cron jobs create background task runs that appear in `openclaw tasks`.

ACTIONS:
- status: Check cron scheduler status
- list: List jobs (use includeDisabled:true to include disabled)
- add: Create job (requires job object, see schema below)
- update: Modify job (requires jobId + patch object)
- remove: Delete job (requires jobId)
- run: Trigger job immediately (requires jobId)
- runs: Get job run history (requires jobId)
- wake: Send wake event (requires text, optional mode)

JOB SCHEMA (for add action):
{
  "name": "string (optional)",
  "schedule": { ... },      // Required: when to run
  "payload": { ... },       // Required: what to execute
  "delivery": { ... },      // Optional: announce summary (isolated/current/session:xxx only) or webhook POST
  "sessionTarget": "main" | "isolated" | "current" | "session:<custom-id>",  // Optional, defaults based on context
  "enabled": true | false   // Optional, default true
}

SESSION TARGET OPTIONS:
- "main": Run in the main session (requires payload.kind="systemEvent")
- "isolated": Run in an ephemeral isolated session (requires payload.kind="agentTurn")
- "current": Bind to the current session where the cron is created (resolved at creation time)
- "session:<custom-id>": Run in a persistent named session (e.g., "session:project-alpha-daily")

DEFAULT BEHAVIOR (unchanged for backward compatibility):
- payload.kind="systemEvent" → defaults to "main"
- payload.kind="agentTurn" → defaults to "isolated"
To use current session binding, explicitly set sessionTarget="current".

SCHEDULE TYPES (schedule.kind):
- "at": One-shot at absolute time
  { "kind": "at", "at": "<ISO-8601 timestamp>" }
- "every": Recurring interval
  { "kind": "every", "everyMs": <interval-ms>, "anchorMs": <optional-start-ms> }
- "cron": Cron expression evaluated in the supplied timezone, or the Gateway host local timezone when tz is omitted
  { "kind": "cron", "expr": "<cron-expression>", "tz": "<optional-IANA-timezone>" }
  Write expr in the selected timezone's local wall-clock time; do not convert the requested local time to UTC first.
  If tz is omitted, do not assume UTC; the Gateway host local timezone is used.
  Example: "Remind me every day at 6pm Shanghai time" -> { "kind": "cron", "expr": "0 18 * * *", "tz": "Asia/Shanghai" }

For schedule.kind="at", ISO timestamps without an explicit timezone are treated as UTC.

PAYLOAD TYPES (payload.kind):
- "systemEvent": Injects text as system event into session
  { "kind": "systemEvent", "text": "<message>" }
- "agentTurn": Runs agent with message (isolated sessions only)
  { "kind": "agentTurn", "message": "<prompt>", "model": "<optional>", "thinking": "<optional>", "timeoutSeconds": <optional, 0 means no timeout> }

DELIVERY (top-level):
  { "mode": "none|announce|webhook", "channel": "<optional>", "to": "<optional>", "threadId": "<optional>", "bestEffort": <optional-bool> }
  - Default for isolated agentTurn jobs (when delivery omitted): "announce"
  - announce: send to chat channel (optional channel/to target)
  - threadId: chat thread/topic id for channels that support threaded delivery
  - webhook: send finished-run event as HTTP POST to delivery.to (URL required)
  - If the task needs to send to a specific chat/recipient, set announce delivery.channel/to; do not call messaging tools inside the run.

CRITICAL CONSTRAINTS:
- sessionTarget="main" REQUIRES payload.kind="systemEvent"
- sessionTarget="isolated" | "current" | "session:xxx" REQUIRES payload.kind="agentTurn"
- For webhook callbacks, use delivery.mode="webhook" with delivery.to set to a URL.
Default: prefer isolated agentTurn jobs unless the user explicitly wants current-session binding.

WAKE MODES (for wake action):
- "next-heartbeat" (default): Wake on next heartbeat
- "now": Wake immediately

Use jobId as the canonical identifier; id is accepted for compatibility. Use contextMessages (0-10) to add previous messages as context to the job text.

Retrieve a directory tree from a paired node as a gzipped tarball, unpack it on the gateway, and return a manifest of saved paths. Use to pull source trees, asset folders, or log directories in a single round-trip. The unpacked files live on the GATEWAY (not your local machine); pass localPath into other tools or use file_fetch on individual entries to ship them elsewhere. Rejects trees larger than 16 MB compressed. Requires operator opt-in: gateway.nodes.allowCommands must include 'dir.fetch' AND plugins.entries.file-transfer.config.nodes.<node>.allowReadPaths must match the directory path.

Node id, name, or IP. Resolves the same way as the nodes tool.

Absolute path to the directory on the node to fetch. Canonicalized server-side.

Max gzipped tarball bytes to fetch. Default 8 MB, hard ceiling 16 MB (single round-trip).

Reserved for v2; currently always includes dotfiles (v1 quirk in BSD tar).

Retrieve a structured directory listing from a paired node. Returns file and subdirectory metadata (name, path, size, mimeType, isDir, mtime) without transferring file content. Use this to discover what files exist before fetching them with file_fetch. Pagination is offset-based; pass nextPageToken from the previous result. Requires operator opt-in: gateway.nodes.allowCommands must include 'dir.list' AND plugins.entries.file-transfer.config.nodes.<node>.allowReadPaths must match the directory path. Without policy configured, every call is denied.

Absolute path to the directory on the node. Canonicalized server-side.

Max entries per page. Default 200, hard ceiling 5000.

edit

Edit a single file using exact text replacement. Every edits[].oldText must match a unique, non-overlapping region of the original file. If two changes affect the same block or nearby lines, merge them into one edit instead of emitting overlapping edits. Do not include large unchanged regions just to connect distant changes.

Path to the file to edit (relative or absolute)

One or more targeted replacements. Each edit is matched against the original file, not incrementally. Do not include overlapping or nested edits. If two changes touch the same block or nearby lines, merge them into one edit instead.

exec

Execute shell commands with background continuation for work that starts now. Use yieldMs/background to continue later via process tool. For long-running work started now, rely on automatic completion wake when it is enabled and the command emits output or fails; otherwise use process to confirm completion. Use process whenever you need logs, status, input, or intervention. Do not use exec sleep or delay loops for reminders or deferred follow-ups; use cron instead. Use pty=true for TTY-required commands (terminal UIs, coding agents).

Shell command to execute

Working directory (defaults to cwd)

Milliseconds to wait before backgrounding (default 10000)

Run in background immediately

Timeout in seconds (optional, kills process on expiry)

Run in a pseudo-terminal (PTY) when available (TTY-required CLIs, coding agents)

Run on the host with elevated permissions (if allowed)

Exec host/target (auto|sandbox|gateway|node).

Exec security mode (deny|allowlist|full).

Exec ask mode (off|on-miss|always).

Node id/name for host=node.

Retrieve a file from a paired node by absolute path. Returns image content blocks for image MIME types, inlines small text files (≤8 KB) as text content, and saves everything else under the gateway media store with a path you can pass to file_write or other tools. Use this for screenshots, photos, receipts, logs, source files. Pair with file_write to copy a file from one node to another (no exec/cp shell-out needed). Requires operator opt-in: gateway.nodes.allowCommands must include 'file.fetch' AND plugins.entries.file-transfer.config.nodes.<node>.allowReadPaths must match the path. Without policy configured, every call is denied.

Node id, name, or IP. Resolves the same way as the nodes tool.

Absolute path to the file on the node. Canonicalized server-side.

Max bytes to fetch. Default 8 MB, hard ceiling 16 MB (single round-trip).

Write file bytes to a paired node by absolute path. Atomic write (temp + rename). Refuses to overwrite by default — pass overwrite=true to replace. Refuses to write through symlink targets unless policy explicitly allows following symlinks. Pair with file_fetch by passing its mediaId as sourceMediaId for binary copy. Requires operator opt-in: gateway.nodes.allowCommands must include 'file.write' AND plugins.entries.file-transfer.config.nodes.<node>.allowWritePaths must match the destination path. Without policy configured, every call is denied.

Node id or display name to write the file on.

Absolute path on the node to write. Canonicalized server-side.

Base64-encoded bytes to write. Maximum 16 MB after decode.

Media id returned by file_fetch. Preferred for binary copies because bytes stay in the gateway media store.

Content type hint. Not validated against the content.

Allow overwriting an existing file. Default false.

Create missing parent directories (mkdir -p). Default false.

gateway

Restart, inspect a specific config schema path, apply config, or update the gateway in-place (SIGUSR1). Use config.schema.lookup with a targeted dot path before config edits. Use config.patch for safe partial config updates (merges with existing). Use config.apply only when replacing entire config. Config writes hot-reload when possible and restart when required. Always pass a human-readable completion message via the `note` parameter so the system can deliver it to the user after restart. If restarting during a user task and you still owe the user a reply, pass a specific one-shot `continuationMessage` for what to verify or report after boot; do not write restart sentinel files directly.

image

Analyze one or more images with a vision model. Use image for a single path/URL, or images for multiple (up to 20). Only use this tool when images were NOT already provided in the user's message. Images mentioned in the prompt are automatically visible to you.

Single image path or URL.

Multiple image paths or URLs (up to maxImages, default 20).

Generate new images or edit reference images with the configured or inferred image-generation model. For transparent backgrounds, use outputFormat="png" or "webp" and background="transparent"; OpenAI also accepts openai.background and OpenClaw routes the default OpenAI image model to gpt-image-1.5 for that mode. Set agents.defaults.imageGenerationModel.primary to pick a provider/model. Providers declare their own auth/readiness; use action="list" to inspect registered providers, models, readiness, and auth hints. Generated images are delivered automatically from the tool result as MEDIA paths.

Optional action: "generate" (default) or "list" to inspect available providers/models.

Image generation prompt.

Optional reference image path or URL for edit mode.

Optional reference images for edit mode (up to 5).

Optional provider/model override, e.g. openai/gpt-image-2; use openai/gpt-image-1.5 for transparent OpenAI backgrounds.

Optional output filename hint. OpenClaw preserves the basename and saves under its managed media directory.

Optional size hint like 1024x1024, 1536x1024, 1024x1536, 2048x2048, or 3840x2160.

Optional aspect ratio hint: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, or 21:9.

Optional resolution hint: 1K, 2K, or 4K. Useful for Google edit/generation flows.

Optional quality hint: low, medium, high, or auto when the provider supports it.

Optional output format hint: png, jpeg, or webp when the provider supports it.

Optional background hint: transparent, opaque, or auto when the provider supports it. For transparent output use outputFormat png or webp.

Optional number of images to request (1-4).

Optional provider request timeout in milliseconds.

Safe exact excerpt read from MEMORY.md or memory/*.md. Defaults to a bounded excerpt when lines are omitted, includes truncation/continuation info when more content exists, and `corpus=wiki` reads from registered compiled-wiki supplements.

Mandatory recall step: semantically search MEMORY.md + memory/*.md (and optional session transcripts) before answering questions about prior work, decisions, dates, people, preferences, or todos. Optional `corpus=wiki` or `corpus=all` also searches registered compiled-wiki supplements. `corpus=memory` restricts hits to indexed memory files (excludes session transcript chunks from ranking). `corpus=sessions` restricts hits to indexed session transcripts (same visibility rules as session history tools). If response has disabled=true, memory retrieval is unavailable and should be surfaced to the user.

message

Send, delete, and manage messages via channel plugins. Supports actions: delete, edit, poll, react, send, topic-create, topic-edit.

Recipient/channel: E.164 for WhatsApp/Signal, Telegram chat id/@username, Discord/Slack/Mattermost <channelId|user:ID|channel:ID>, or iMessage handle/chat_id

Message effect name/id for sendWithEffect (e.g., invisible ink).

Alias for effectId (e.g., invisible-ink, balloons).

Media URL or local path. data: URLs are not supported here, use buffer.

Base64 payload for attachments (optionally a data: URL).

Quote text for Telegram reply_parameters

Send image/GIF as document to avoid Telegram compression (Telegram only).

Send image/GIF as document to avoid Telegram compression. Alias for forceDocument (Telegram only).

Target message id for read, reaction, edit, delete, pin, or unpin. If omitted for reaction-like actions, defaults to the current inbound message id when available.

snake_case alias of messageId. If omitted for reaction-like actions, defaults to the current inbound message id when available.

When true for a reaction to the current inbound message, use that reacted message as the status-reaction target for subsequent tool progress when the channel supports it.

snake_case alias of trackToolCalls.

Poll answer id to vote for. Use when the channel exposes stable answer ids.

1-based poll option number to vote for, matching the rendered numbered poll choices.

Channel id filter (search/thread list/event create).

Chat id for chat-scoped metadata actions.

nodes

Discover and control paired nodes (status/describe/pairing/notify/camera/photos/screen/location/notifications/invoke). For file retrieval, use the dedicated file_fetch tool.

camera_snap: front/back/both; camera_clip: front/back only.

pdf

Analyze one or more PDF documents with a model. Supports native PDF analysis for Anthropic and Google models, with text/image extraction fallback for other providers. Use pdf for a single path/URL, or pdfs for multiple (up to 10). Provide a prompt describing what to analyze.

Single PDF path or URL.

Multiple PDF paths or URLs (up to 10).

Page range to process, e.g. "1-5", "1,3,5-7". Defaults to all pages.

process

Manage running exec sessions for commands already started: list, poll, log, write, send-keys, submit, paste, kill. Use poll/log when you need status, logs, quiet-success confirmation, or completion confirmation when automatic completion wake is unavailable. Use write/send-keys/submit/paste/kill for input or intervention. Do not use process polling to emulate timers or reminders; use cron for scheduled follow-ups.

Process action

Session id for actions other than list

Data to write for write

Key tokens to send for send-keys

Hex bytes to send for send-keys

Literal string for send-keys

Text to paste for paste

Wrap paste in bracketed mode

Close stdin after write

Log offset

Log length

For poll: wait up to this many milliseconds before returning; max 30000 ms, higher values are clamped to 30000

read

Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to 2000 lines or 50KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.

Path to the file to read (relative or absolute)

Line number to start reading from (1-indexed)

Maximum number of lines to read

Show a /status-equivalent session status card for the current or another visible session, including usage, time, cost when available, and linked background task context. Use `sessionKey="current"` for the current session; do not use UI/client labels such as `openclaw-tui` as session keys. Optional `model` sets a per-session model override; `model=default` resets overrides. Use this for questions like what model is active or how a session is configured.

Fetch sanitized message history for a visible session. Supports limits and optional tool messages; use this to inspect another session before replying, debugging, or resuming work.

List visible sessions with optional filters for kind, label, agentId, search, recent activity, derived titles, and last-message previews. Use this to discover a target session before calling sessions_history or sessions_send.

Send a message into another visible session by sessionKey or label. Thread-scoped chat sessions are rejected; target the parent channel session for inter-agent coordination. Use this to delegate follow-up work to an existing session; waits for the target run and returns the updated assistant reply when available.

Spawn a clean isolated session by default with the native subagent runtime. `mode="run"` is one-shot background work. Subagents inherit the parent workspace directory automatically. For native subagents only, set `context="fork"` when the child needs the current transcript context; otherwise omit it or use `context="isolated"`. Use this when the work should happen in a fresh child session instead of the current one.

Native subagent context mode. Omit or use "isolated" for a clean child session; use "fork" only when the child needs the requester transcript context.

When true, spawned subagent runs use lightweight bootstrap context. Only applies to runtime='subagent'.

End your current turn. Use after spawning subagents to receive their results as the next message.

subagents

List, kill, or steer spawned sub-agents for this requester session. Use this for sub-agent orchestration.

tts

Use only for explicit audio intent (audio, voice, speech, TTS) or active TTS config. Never use for ordinary text replies. Audio is delivered automatically from the tool result. After a successful call, follow the current conversation's reply instructions and avoid sending a duplicate text/audio response.

Text to convert to speech.

Optional channel id to pick output format.

Optional provider request timeout in milliseconds.

Generate videos using configured providers. Generated videos are saved under OpenClaw-managed media storage and delivered automatically as attachments. Duration requests may be rounded to the nearest provider-supported value.

Optional action: "generate" (default), "status" to inspect the active session task, or "list" to inspect available providers/models.

Video generation prompt.

Optional single reference image path or URL.

Optional reference images (up to 9).

Optional semantic roles for the combined reference image list, parallel by index. The list is `image` (if provided) followed by each entry in `images`, in order, after de-duplication. Canonical values: "first_frame", "last_frame", "reference_image". Providers may accept additional role strings. Must not have more entries than the combined image list; use an empty string to leave a position unset.

Optional single reference video path or URL.

Optional reference videos (up to 4).

Optional semantic roles for the combined reference video list, parallel by index. The list is `video` (if provided) followed by each entry in `videos`, in order, after de-duplication. Canonical value: "reference_video". Providers may accept additional role strings. Must not have more entries than the combined video list; use an empty string to leave a position unset.

Optional single reference audio path or URL (e.g. background music).

Optional reference audios (up to 3).

Optional semantic roles for the combined reference audio list, parallel by index. The list is `audioRef` (if provided) followed by each entry in `audioRefs`, in order, after de-duplication. Canonical value: "reference_audio". Providers may accept additional role strings. Must not have more entries than the combined audio list; use an empty string to leave a position unset.

Optional provider/model override, e.g. qwen/wan2.6-t2v.

Optional size hint like 1280x720 or 1920x1080 when the provider supports it.

Optional aspect ratio hint: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, or "adaptive".

Optional resolution hint: 480P, 720P, 768P, or 1080P.

Optional target duration in seconds. OpenClaw may round this to the nearest provider-supported duration.

Optional audio toggle when the provider supports generated audio.

Optional watermark toggle when the provider supports it.

Optional provider-specific options as a JSON object, e.g. `{"seed": 42, "draft": true}`. Each provider declares its own accepted keys and primitive types (number/boolean/string) via its capabilities; unknown keys or type mismatches skip the candidate during fallback and never silently reach the wrong provider. Run `video_generate action=list` to see which keys each provider accepts.

Optional provider request timeout in milliseconds.

Fetch and extract readable content from a URL (HTML → markdown/text). Use for lightweight page access without browser automation.

HTTP or HTTPS URL to fetch.

Extraction mode ("markdown" or "text").

Maximum characters to return (truncates when exceeded).

Search the web. Returns provider-normalized results for current information lookup.

Search query string.

Number of results to return.

2-letter country code for region-specific results.

ISO 639-1 language code for results.

Filter by time: day, week, month, or year.

Only results published after this date (YYYY-MM-DD).

Only results published before this date (YYYY-MM-DD).

Brave search result language code.

Brave UI locale code in language-region format.

Perplexity native Search API domain filter.

Perplexity native Search API total content budget.

Perplexity native Search API max tokens extracted per page.

write

Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.

Path to the file to write (relative or absolute)

Content to write to the file