# actionbook

Adopt this skill: https://proskills.md/skills/other/smallnest-goclaw-internal-builtin-skills-actionbook

Page: https://proskills.md/skills/other/smallnest-goclaw-internal-builtin-skills-actionbook
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: internal/builtin_skills/actionbook/SKILL.md
size: 16572
sha: 82ceb3b35430ae02322cc6bda0df115ab7db759d
upstream: https://github.com/smallnest/goclaw/blob/master/internal/builtin_skills/actionbook/SKILL.md

````text
---
name: actionbook
description: This skill should be used when the user needs to automate multi-step website tasks. Activates for browser automation, web scraping, UI testing, or building AI agents. Provides complete action manuals with step-by-step instructions and verified selectors.
---

## When to Use This Skill

Activate this skill when the user:

- Needs to complete a multi-step task ("Send a LinkedIn message", "Book an Airbnb")
- Asks how to interact with a website ("How do I post a tweet?")
- Builds browser-based AI agents or web scrapers
- Writes E2E tests for external websites
- Navigates to any new page during browser automation
- Wants to control their existing Chrome browser (Extension mode)

## Browser Modes

Actionbook supports two browser control modes:

| Mode | Flag | Use Case |
|------|------|----------|
| **CDP** (default) | (none) | Launches a dedicated browser instance via Chrome DevTools Protocol |
| **Extension** | `--extension` | Controls the user's existing Chrome browser via a Chrome Extension + WebSocket bridge |

**When to use Extension mode:**
- The user wants to operate on their already-open Chrome (with existing logins, cookies, tabs)
- The task requires interacting with pages that need the user's real session state
- The user explicitly mentions their Chrome browser, extension, or existing tabs

**When to use CDP mode (default):**
- Clean browser environment is preferred
- Headless automation or CI/CD
- Profile-based session isolation is needed

All `actionbook browser` commands work identically in both modes. The only difference is adding `--extension` flag (or setting `ACTIONBOOK_EXTENSION=1`).

## How to Use

### Phase 1: Get Action Manual

```bash
# Step 1: Search for action manuals
actionbook search "arxiv search papers"
# Returns: area IDs with descriptions

# Step 2: Get the full manual (use area_id from search results)
actionbook get "arxiv.org:/search/advanced:default"
# Returns: Page structure, UI Elements with CSS/XPath selectors
```

### Phase 2: Execute with Browser (CDP mode — default)

```bash
# Step 3: Open browser
actionbook browser open "https://arxiv.org/search/advanced"

# Step 4: Use CSS selectors from Action Manual directly
actionbook browser fill "#terms-0-term" "Neural Network"
actionbook browser select "#terms-0-field" "title"
actionbook browser click "#date-filter_by-2"
actionbook browser fill "#date-year" "2025"
actionbook browser click "form[action='/search/advanced'] button.is-link"

# Step 5: Wait for results
actionbook browser wait-nav

# Step 6: Extract data
actionbook browser text

# Step 7: Close browser
actionbook browser close
```

### Phase 2 (alt): Execute with Extension mode

Extension mode uses identical browser commands — just add `--extension`. But you **must** follow the full lifecycle below.

```bash
# Step 3: Open URL in user's Chrome
actionbook --extension browser open "https://arxiv.org/search/advanced"

# Step 4-7: Same commands, just add --extension
actionbook --extension browser fill "#terms-0-term" "Neural Network"
actionbook --extension browser select "#terms-0-field" "title"
actionbook --extension browser click "#date-filter_by-2"
actionbook --extension browser fill "#date-year" "2025"
actionbook --extension browser click "form[action='/search/advanced'] button.is-link"
actionbook --extension browser wait-nav
actionbook --extension browser text

# Step 8: Cleanup (CRITICAL — see Extension Mode Lifecycle below)
actionbook --extension browser close    # release debug connection FIRST
actionbook extension stop               # then stop bridge server
```

## Action Manual Format

Action manuals return:
- **Page URL** - Target page address
- **Page Structure** - DOM hierarchy and key sections
- **UI Elements** - CSS/XPath selectors with element metadata

```yaml
  ### button_advanced_search

  - ID: button_advanced_search
  - Description: Advanced search navigation button
  - Type: link
  - Allow Methods: click
  - Selectors:
    - role: getByRole('link', { name: 'Advanced Search' }) (confidence: 0.9)
    - css: button.button.is-small.is-cul-darker (confidence: 0.65)
    - xpath: //button[contains(@class, 'button')] (confidence: 0.55)
```

## Action Search Commands

```bash
actionbook search "<query>"                    # Basic search
actionbook search "<query>" --domain site.com  # Filter by domain
actionbook search "<query>" --url <url>        # Filter by URL
actionbook search "<query>" -p 2 -s 20         # Page 2, 20 results

actionbook get "<area_id>"                     # Full details with selectors
# area_id format: "site.com:/path:area_name"

actionbook sources list                        # List available sources
actionbook sources search "<query>"            # Search sources by keyword
```

## Extension Setup & Management

Commands for managing the Chrome Extension bridge:

```bash
actionbook extension install              # Install extension files to local config dir
actionbook extension path                 # Show extension directory (for Chrome "Load unpacked")
actionbook extension serve                # Start WebSocket bridge (keep running in background)
actionbook extension stop                 # Stop the running bridge server (sends SIGTERM)
actionbook extension status               # Check bridge and extension connection status
actionbook extension ping                 # Ping the extension to verify link is alive
```

**Setup flow (one-time):**
1. `actionbook extension install` — extract extension files and register native messaging host
2. Open `chrome://extensions` → enable Developer mode → Load unpacked → select the path from `actionbook extension path`
3. `actionbook extension serve` — start bridge (keep running)
4. Extension auto-connects via native messaging (no manual token needed in most cases). If auto-pairing fails: copy token from `serve` output → paste in extension popup → Save

**Connection check before automation:**
```bash
actionbook extension status    # should show "running"
actionbook extension ping      # should show "responded"
```

## Browser Commands

> All browser commands below work in both CDP and Extension mode.
> For Extension mode, add `--extension` flag or set `ACTIONBOOK_EXTENSION=1`.

### Navigation

```bash
actionbook browser open <url>                  # Open URL in new tab
actionbook browser goto <url>                  # Navigate current page
actionbook browser back                        # Go back
actionbook browser forward                     # Go forward
actionbook browser reload                      # Reload page
actionbook browser pages                       # List open tabs
actionbook browser switch <page_id>            # Switch tab
actionbook browser close                       # Close browser
actionbook browser restart                     # Restart browser
actionbook browser connect <endpoint>          # Connect to existing browser (CDP port or URL)
```

### Interactions (use CSS selectors from Action Manual)

```bash
actionbook browser click "<selector>"                  # Click element
actionbook browser click "<selector>" --wait 1000      # Wait then click
actionbook browser fill "<selector>" "text"            # Clear and type
actionbook browser type "<selector>" "text"            # Append text
actionbook browser select "<selector>" "value"         # Select dropdown
actionbook browser hover "<selector>"                  # Hover
actionbook browser focus "<selector>"                  # Focus
actionbook browser press Enter                         # Press key
```

### Get Information

```bash
actionbook browser text                        # Full page text
actionbook browser text "<selector>"           # Element text
actionbook browser html                        # Full page HTML
actionbook browser html "<selector>"           # Element HTML
actionbook browser snapshot                    # Accessibility tree
actionbook browser viewport                    # Viewport dimensions
actionbook browser status                      # Browser detection info
```

### Wait

```bash
actionbook browser wait "<selector>"                   # Wait for element
actionbook browser wait "<selector>" --timeout 5000    # Custom timeout
actionbook browser wait-nav                            # Wait for navigation
```

### Screenshots & Export

```bash
# Ensure target directory exists before saving screenshots
actionbook browser screenshot                  # Save screenshot.png
actionbook browser screenshot output.png       # Custom path
actionbook browser screenshot --full-page      # Full page
actionbook browser pdf output.pdf              # Export as PDF
```

### JavaScript & Inspection

```bash
actionbook browser eval "document.title"               # Execute JS
actionbook browser inspect 100 200                     # Inspect at coordinates
actionbook browser inspect 100 200 --desc "login btn"  # With description
```

### Cookies

```bash
actionbook browser cookies list                # List all cookies
actionbook browser cookies get "name"          # Get cookie
actionbook browser cookies set "name" "value"  # Set cookie
actionbook browser cookies set "name" "value" --domain ".example.com"
actionbook browser cookies delete "name"       # Delete cookie
actionbook browser cookies clear               # Clear all
```

## Global Flags

```bash
actionbook --json <command>              # JSON output
actionbook --headless <command>          # Headless mode (CDP only)
actionbook --verbose <command>           # Verbose logging
actionbook -P <profile> <command>        # Use specific profile (CDP only)
actionbook --cdp <port|url> <command>    # CDP connection
actionbook --extension <command>         # Use Chrome Extension mode
# or: ACTIONBOOK_EXTENSION=1 actionbook <command>
```

## Guidelines

- Search by task description, not element name ("arxiv search papers" not "search button")
- **Use Action Manual selectors first** - they are pre-verified and don't require snapshot
- Prefer CSS ID selectors (`#id`) over XPath when both are provided
- **Fallback to snapshot when selectors fail** - use `actionbook browser snapshot` then CSS selectors from the output
- Re-snapshot after navigation - DOM changes invalidate previous state
- **Extension mode**: follow the full lifecycle — pre-flight → connect → execute → cleanup (see [Extension Mode Lifecycle](#extension-mode-lifecycle-critical))
- **Extension mode**: verify extension is installed before starting bridge; prefer auto-pair over manual token
- **Extension mode**: always run `browser close` before stopping the bridge to release the debug connection
- **Extension mode**: the user's real browser is being controlled — avoid destructive actions (clearing all cookies, closing all tabs) without confirmation
- **Extension mode**: L3 operations (some cookie/storage modifications) may require manual approval in the extension popup

## Fallback Strategy

### When Fallback is Needed

Actionbook stores pre-computed page data captured at indexing time. This data may become outdated as websites evolve:

- **Selector execution failure** - The returned CSS/XPath selector does not match any element
- **Element mismatch** - The selector matches an element with unexpected type or behavior
- **Multiple selector failures** - Several selectors from the same action fail consecutively

### Fallback Approaches

When Action Manual selectors don't work:

1. **Snapshot the page** - `actionbook browser snapshot` to get the current accessibility tree
2. **Inspect visually** - `actionbook browser screenshot` to see the current state
3. **Inspect by coordinates** - `actionbook browser inspect <x> <y>` to find elements
4. **Execute JS** - `actionbook browser eval "document.querySelector(...)"` for dynamic queries

### When to Exit

If actionbook search returns no results or action fails unexpectedly, use other available tools to continue the task.

## Examples

### End-to-end with Action Manual

```bash
# 1. Find selectors
actionbook search "airbnb search" --domain airbnb.com

# 2. Get detailed selectors (area_id from search results)
actionbook get "airbnb.com:/:default"

# 3. Automate using pre-verified selectors
actionbook browser open "https://www.airbnb.com"
actionbook browser fill "input[data-testid='structured-search-input-field-query']" "Tokyo"
actionbook browser click "button[data-testid='structured-search-input-search-button']"
actionbook browser wait-nav
actionbook browser text
actionbook browser close
```

### Extension mode: Operate on user's Chrome

```bash
# Verify bridge is running
actionbook extension status

# Use the user's existing logged-in session
actionbook --extension browser open "https://github.com/notifications"
actionbook --extension browser wait-nav
actionbook --extension browser text ".notifications-list"
actionbook --extension browser screenshot notifications.png
```

### Extension Mode Lifecycle (CRITICAL)

When using Extension mode, **always** follow this complete lifecycle: pre-flight → connect → execute → cleanup.

#### 1. Pre-flight: Ask user about extension installation

Before any technical checks, **ask the user** whether they have the Actionbook Chrome Extension installed.

- **User confirms installed** → proceed to Step 2 (Connect).
- **User says not installed** → run the installation flow:

```bash
# Install extension files locally
actionbook extension install
actionbook extension path
# → On macOS, copy to visible dir if needed:
#    cp -r "$(actionbook extension path)" ~/Document/actionbook-extension
```

Then guide the user to load it in Chrome:
1. Open `chrome://extensions` → enable Developer mode
2. Click "Load unpacked" → select the extension directory
3. After user confirms loaded → proceed to Step 2

> **Limitation:** The CLI can only verify that extension files exist locally. There is no way to detect whether Chrome has actually loaded the extension until a connection is attempted in Step 2.

#### 2. Connect: Start bridge, auto-pair with retry

Start the bridge server and attempt auto-pairing. **Retry up to 3 times** before considering manual fallback.

```bash
# Start bridge (run in background)
actionbook extension serve

# Attempt 1: Wait for auto-pairing via Native Messaging
sleep 3
actionbook extension ping
# → If ping succeeds → proceed to Step 3 (Execute)

# Attempt 2: If ping fails, wait longer and retry
sleep 5
actionbook extension ping
# → If ping succeeds → proceed to Step 3 (Execute)

# Attempt 3: Final retry
sleep 5
actionbook extension ping
# → If ping succeeds → proceed to Step 3 (Execute)
```

**Only after all 3 auto-pair attempts fail**, escalate based on the error:

- **"Extension not connected"** → Ask user to verify the extension is enabled in `chrome://extensions` and retry
- **"Invalid token"** → Only now provide the token from `serve` output for manual paste in the extension popup
- **Other errors** → Check `actionbook extension status` for diagnostics

**IMPORTANT:** Do NOT expose the session token prematurely. The token is a last-resort fallback — most users will connect successfully via auto-pair within 3 attempts.

#### 3. Execute: Browser automation

```bash
actionbook --extension browser open "https://example.com"
# ... perform browser operations ...
```

#### 4. Cleanup: Release debug connection, THEN stop bridge

```bash
# Step 1: Release the debugging connection (MUST come first)
actionbook --extension browser close

# Step 2: Stop the bridge server
actionbook extension stop

# Step 3: Verify Chrome no longer shows "debugging" banner
actionbook extension status    # should show "not running"
```

**WARNING:** Skipping Step 1 and directly killing the bridge process will leave Chrome showing "Actionbook is debugging this browser". Always release the debug connection before stopping the bridge.

### Extension mode: Troubleshooting

```bash
# Bridge not running?
actionbook extension serve              # Start it

# Extension not responding?
actionbook extension ping               # Check connectivity

# Token expired? (idle > 30 min)
# Restart serve and re-pair in extension popup
actionbook extension serve              # Prints new token
```

### Deep-Dive Documentation

For detailed patterns and best practices:

| Reference | Description |
|-----------|-------------|
| [references/command-reference.md](references/command-reference.md) | Complete command reference with all features |
| [references/authentication.md](references/authentication.md) | Login flows, OAuth, 2FA handling, state reuse |
````

## File: internal/builtin_skills/actionbook/references/authentication.md
size: 5399
sha: a98daec88c41c1cd383a5f268156c12b34c5a2eb
upstream: https://github.com/smallnest/goclaw/blob/master/internal/builtin_skills/actionbook/references/authentication.md

````text
# Authentication Patterns

Patterns for handling login flows, session persistence, and authenticated browsing using the Actionbook Rust CLI.

## Basic Login Flow

```bash
# Open login page
actionbook browser open "https://app.example.com/login"
actionbook browser wait-nav

# Take snapshot to identify form elements
actionbook browser snapshot

# Fill credentials using CSS selectors from snapshot
actionbook browser fill "#email" "$APP_USERNAME"
actionbook browser fill "#password" "$APP_PASSWORD"

# Submit
actionbook browser click "button[type=submit]"
actionbook browser wait-nav

# Verify login succeeded by checking the current URL
actionbook browser eval "window.location.href"
```

## Profile-Based Session Persistence

Profiles provide isolated browser sessions with separate cookies and storage. Use profiles to persist authentication across CLI invocations.

```bash
# Create a dedicated profile for the target site
actionbook profile create myapp

# Login using that profile
actionbook -P myapp browser open "https://app.example.com/login"
actionbook -P myapp browser wait-nav
actionbook -P myapp browser snapshot
actionbook -P myapp browser fill "#email" "$APP_USERNAME"
actionbook -P myapp browser fill "#password" "$APP_PASSWORD"
actionbook -P myapp browser click "button[type=submit]"
actionbook -P myapp browser wait-nav

# Later: reuse the profile — session cookies are preserved
actionbook -P myapp browser open "https://app.example.com/dashboard"
actionbook -P myapp browser wait-nav
actionbook -P myapp browser text "h1"  # Should show dashboard content

# List and inspect profiles
actionbook profile list
actionbook profile show myapp
```

## OAuth / SSO Flows

For OAuth redirects, use snapshot at each step to identify form elements:

```bash
# Start OAuth flow
actionbook browser open "https://app.example.com/auth/google"
actionbook browser wait-nav

# Google sign-in page — snapshot to find form elements
actionbook browser snapshot
actionbook browser fill "input[type=email]" "$GOOGLE_EMAIL"
actionbook browser click "#identifierNext"
actionbook browser wait-nav

# Password step
actionbook browser snapshot
actionbook browser fill "input[type=password]" "$GOOGLE_PASSWORD"
actionbook browser click "#passwordNext"
actionbook browser wait-nav

# Wait for redirect back to app (OAuth redirects can be slow)
actionbook browser eval "window.location.href"  # Should be app.example.com
```

## Two-Factor Authentication

Handle 2FA by running in headed mode (the default) and waiting for manual input:

```bash
# Login with credentials (browser is visible by default)
actionbook browser open "https://app.example.com/login"
actionbook browser wait-nav
actionbook browser snapshot
actionbook browser fill "#email" "$APP_USERNAME"
actionbook browser fill "#password" "$APP_PASSWORD"
actionbook browser click "button[type=submit]"
actionbook browser wait-nav

# Wait for user to complete 2FA manually
# Use a long timeout and wait for an element only present after 2FA
actionbook browser wait ".dashboard-header" --timeout 120000
```

## Cookie-Based Auth

Manually set authentication cookies:

```bash
# Open the target domain first (cookies need a page context)
actionbook browser open "https://app.example.com"
actionbook browser wait-nav

# Set auth cookie (use environment variable for the token value)
actionbook browser cookies set "session_token" "$SESSION_TOKEN" --domain ".example.com"

# Navigate to protected page
actionbook browser goto "https://app.example.com/dashboard"
actionbook browser wait-nav
```

## Token Refresh Handling

For sessions with expiring tokens:

```bash
#!/bin/bash
# Wrapper that handles token refresh using profiles

PROFILE="myapp"

# Try navigating directly with existing profile session
actionbook -P "$PROFILE" browser open "https://app.example.com/dashboard"
actionbook -P "$PROFILE" browser wait-nav

# Check if session is still valid via URL
URL=$(actionbook -P "$PROFILE" browser eval "window.location.href")
if [[ "$URL" == *"/login"* ]]; then
    echo "Session expired, re-authenticating..."

    # Perform fresh login
    actionbook -P "$PROFILE" browser snapshot
    actionbook -P "$PROFILE" browser fill "#email" "$APP_USERNAME"
    actionbook -P "$PROFILE" browser fill "#password" "$APP_PASSWORD"
    actionbook -P "$PROFILE" browser click "button[type=submit]"
    actionbook -P "$PROFILE" browser wait-nav
fi
```

## Security Best Practices

1. **Use environment variables for credentials** — source from a `.env` file, not inline
   ```bash
   # Load from .env file (avoid typing secrets in the terminal)
   source .env  # contains APP_USERNAME, APP_PASSWORD
   actionbook browser fill "#email" "$APP_USERNAME"
   actionbook browser fill "#password" "$APP_PASSWORD"
   ```

2. **Protect profile directories** — profiles store cookies and session data on disk
   ```bash
   # Profile data is equivalent to passwords — restrict access
   chmod 700 ~/.config/actionbook/
   ```

3. **Clean up sessions after automation**
   ```bash
   actionbook browser cookies clear
   actionbook browser close
   ```

4. **Delete profiles when no longer needed**
   ```bash
   actionbook profile delete myapp
   ```

5. **Use headless mode for CI/CD** (no visible browser)
   ```bash
   actionbook --headless browser open "https://app.example.com/login"
   # ... login and perform actions ...
   actionbook browser close
   ```
````

## File: internal/builtin_skills/actionbook/references/command-reference.md
size: 8848
sha: 613aa1e500b8e6b9e42c300eada6722bf909dc88
upstream: https://github.com/smallnest/goclaw/blob/master/internal/builtin_skills/actionbook/references/command-reference.md

````text
# actionbook Command Reference

Complete reference for all `actionbook` CLI commands.

## Action Search & Retrieval

### search - Search for action manuals

```bash
actionbook search "<query>"                    # Basic keyword search
actionbook search "<query>" --domain site.com  # Filter by domain
actionbook search "<query>" --url <url>        # Filter by specific URL
actionbook search "<query>" -p 2               # Page 2 (default: 1)
actionbook search "<query>" -s 20              # 20 results per page (default: 10, max: 100)
actionbook search "<query>" --domain site.com --url <url> -p 1 -s 5  # Combined
```

Returns area IDs with descriptions and relevance scores. Use the area_id with `actionbook get` to fetch full details.

### get - Get action details by area ID

```bash
actionbook get "<area_id>"
# area_id format: "site.com:/path:area_name"
# Examples:
#   actionbook get "airbnb.com:/:default"
#   actionbook get "github.com:/login:form"
#   actionbook get "arxiv.org:/search/advanced:default"
```

Returns complete action manual with CSS/XPath selectors, element types, and allowed methods.

### sources - List and search sources

```bash
actionbook sources list                        # List all available sources
actionbook sources search "<query>"            # Search sources by keyword
```

## Browser Automation

### Navigation

```bash
actionbook browser open <url>                  # Open URL in new tab
actionbook browser goto <url>                  # Navigate current page to URL
actionbook browser goto <url> --timeout 5000   # Custom navigation timeout (default: 30000ms)
actionbook browser back                        # Go back in history
actionbook browser forward                     # Go forward in history
actionbook browser reload                      # Reload current page
actionbook browser pages                       # List all open pages/tabs
actionbook browser switch <page_id>            # Switch to specific page by ID
actionbook browser close                       # Close the browser
actionbook browser restart                     # Restart the browser
actionbook browser connect <endpoint>          # Connect to existing browser (CDP port or ws:// URL)
actionbook browser status                      # Show detected browsers and session status
```

### Element Interactions

All interaction commands take CSS selectors. Use selectors from Action Manuals or from `snapshot` output.

```bash
actionbook browser click "<selector>"                  # Click element
actionbook browser click "<selector>" --wait 1000      # Wait 1s for element, then click
actionbook browser fill "<selector>" "text"            # Clear element, then type text
actionbook browser fill "<selector>" "text" --wait 500 # Wait for element, then fill
actionbook browser type "<selector>" "text"            # Type text (append, no clear)
actionbook browser type "<selector>" "text" --wait 500 # Wait for element, then type
actionbook browser select "<selector>" "value"         # Select dropdown option by value
actionbook browser hover "<selector>"                  # Hover over element
actionbook browser focus "<selector>"                  # Focus on element
actionbook browser press <key>                         # Press keyboard key
# Key examples: Enter, Tab, Escape, ArrowDown, ArrowUp, Backspace, Delete, Space
```

### Information Retrieval

```bash
actionbook browser text                        # Get full page text content
actionbook browser text "<selector>"           # Get text of specific element
actionbook browser html                        # Get full page HTML
actionbook browser html "<selector>"           # Get outer HTML of specific element
actionbook browser snapshot                    # Get accessibility snapshot (tree structure)
actionbook browser viewport                    # Get viewport dimensions
```

### Wait Conditions

```bash
actionbook browser wait "<selector>"                   # Wait for element to appear
actionbook browser wait "<selector>" --timeout 5000    # Custom timeout (default: 30000ms)
actionbook browser wait-nav                            # Wait for navigation to complete
actionbook browser wait-nav --timeout 10000            # Custom navigation timeout
```

### Screenshots & Export

```bash
actionbook browser screenshot                  # Save as screenshot.png
actionbook browser screenshot output.png       # Save to custom path
actionbook browser screenshot --full-page      # Full page screenshot
actionbook browser pdf output.pdf              # Export page as PDF
```

### JavaScript & DOM Inspection

```bash
actionbook browser eval "document.title"               # Execute JavaScript, return result
actionbook browser eval "document.querySelectorAll('a').length"
actionbook browser inspect <x> <y>                     # Inspect DOM element at viewport coordinates
actionbook browser inspect <x> <y> --desc "login btn"  # With description hint
```

### Cookie Management

```bash
actionbook browser cookies                     # List all cookies (default)
actionbook browser cookies list                # List all cookies
actionbook browser cookies get "<name>"        # Get specific cookie by name
actionbook browser cookies set "<name>" "<value>"              # Set cookie
actionbook browser cookies set "<name>" "<value>" --domain ".example.com"  # Set with domain
actionbook browser cookies delete "<name>"     # Delete specific cookie
actionbook browser cookies clear               # Clear all cookies
```

## Configuration

### config - Manage settings

```bash
actionbook config show                         # Display full configuration
actionbook config get <key>                    # Get specific config value
actionbook config set <key> <value>            # Set config value
actionbook config edit                         # Open config in $EDITOR
actionbook config path                         # Show config file location
```

**Config keys:**
- `api.base_url` - API endpoint (default: https://api.actionbook.dev)
- `api.api_key` - API authentication key
- `browser.executable` - Browser path override
- `browser.default_profile` - Default profile name
- `browser.headless` - Headless mode (true/false)

### profile - Manage browser profiles

```bash
actionbook profile list                        # List all profiles
actionbook profile create <name>               # Create new profile
actionbook profile create <name> --cdp-port 9222  # With specific CDP port
actionbook profile delete <name>               # Delete profile
actionbook profile show <name>                 # Show profile details
```

## Global Flags

These flags can be used with any command:

```bash
actionbook --json <command>                    # Output in JSON format
actionbook --headless <command>                # Run browser in headless mode
actionbook --verbose <command>                 # Enable verbose logging
actionbook -P <profile> <command>              # Use specific browser profile
actionbook --cdp <port|url> <command>          # Connect via CDP port or WebSocket URL
actionbook --browser-path <path> <command>     # Override browser executable path
```

## Environment Variables

```bash
ACTIONBOOK_API_URL="https://api.actionbook.dev"  # API endpoint
ACTIONBOOK_API_KEY="your-key"                     # API authentication key
ACTIONBOOK_BROWSER_PATH="/path/to/chrome"         # Browser executable
ACTIONBOOK_CDP="9222"                             # CDP port or WebSocket URL
ACTIONBOOK_PROFILE="default"                      # Default profile name
ACTIONBOOK_HEADLESS="true"                        # Headless mode
```

## Practical Examples

### Form Submission

```bash
actionbook browser open "https://example.com/form"
actionbook browser snapshot
# Read the snapshot to find selectors

actionbook browser fill "#email" "user@example.com"
actionbook browser fill "#password" "password123"
actionbook browser click "button[type=submit]"
actionbook browser wait-nav
actionbook browser text "h1"  # Check result
```

### Multi-page Navigation

```bash
actionbook browser open "https://example.com"
actionbook browser click "a[href='/products']"
actionbook browser wait-nav
actionbook browser click ".product-card:first-child a"
actionbook browser wait-nav
actionbook browser text ".product-details"
actionbook browser screenshot product.png
```

### Data Extraction

```bash
actionbook browser open "https://example.com/data"
actionbook browser wait-nav
actionbook browser text ".results-table"       # Get table text
actionbook browser eval "JSON.stringify([...document.querySelectorAll('.item')].map(e => e.textContent))"
actionbook browser close
```

### Connect to Existing Browser

```bash
# Start Chrome with debugging port
# google-chrome --remote-debugging-port=9222

actionbook browser connect 9222
actionbook browser pages
actionbook browser snapshot
```
````

## File: internal/builtin_skills/actionbook/references/extension-troubleshooting.md
size: 1430
sha: 91dc30e7bd029700df4b32e212c10da207046bdb
upstream: https://github.com/smallnest/goclaw/blob/master/internal/builtin_skills/actionbook/references/extension-troubleshooting.md

````text
# Extension Troubleshooting

Common issues and fixes for the Chrome Extension bridge.

## Bridge not running

```bash
actionbook extension serve              # Start the bridge
```

Keep `serve` running in a separate terminal — it is a foreground process.

## Extension not responding

```bash
actionbook extension ping               # Check connectivity
```

If ping fails, verify the extension is loaded in Chrome (`chrome://extensions`) and enabled.

## Token expired (idle > 30 min)

Restart the bridge and re-pair in the extension popup:

```bash
actionbook extension serve              # Prints new token
```

Copy the token from output → paste in extension popup → Save.

## Stale port/token files

**Symptoms:** bridge running but extension connects to wrong port, or "WebSocket handshake failed" errors in bridge output.

**Cause:** previous `serve` process was killed ungracefully.

**Fix:** restart `serve` — it auto-cleans stale files on startup:

```bash
actionbook extension serve
```

## Extension not installed

```bash
actionbook extension install            # Install extension files
actionbook extension path               # Get directory for Chrome "Load unpacked"
```

Then load in Chrome: `chrome://extensions` → Developer mode → Load unpacked → select the path.

## Uninstall extension

```bash
actionbook extension uninstall          # Remove extension files and native host registration
```
````

## File: README.md
upstream: https://github.com/smallnest/goclaw/blob/master/README.md

````text
# goclaw (🐾 狗爪)

Go 语言版本的 OpenClaw - 一个功能强大的 AI Agent 框架。

[![License](https://img.shields.io/:license-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/smallnest/goclaw) [![github actions](https://github.com/smallnest/goclaw/actions/workflows/go.yaml/badge.svg)](https://github.com/smallnest/goclaw/actions) [![Go Report Card](https://goreportcard.com/badge/github.com/smallnest/goclaw)](https://goreportcard.com/report/github.com/smallnest/goclaw) [![Coverage Status](https://coveralls.io/repos/github/smallnest/goclaw/badge.svg?branch=master)](https://coveralls.io/github/smallnest/goclaw?branch=master)

![](docs/goclaw.png)

## 功能特性

- 🛠️ **完整的工具系统**：FileSystem、Shell、Web、Browser，支持 Docker 沙箱与权限控制
- 📚 **技能系统 (Skills)**：兼容 [OpenClaw](https://github.com/openclaw/openclaw) 和 [AgentSkills](https://agentskills.io) 规范，支持自动发现与环境准入控制 (Gating)
- 💾 **持久化会话**：基于 JSONL 的会话存储，支持完整的工具调用链 (Tool Calls) 记录与恢复
- 📢 **多渠道支持**：Telegram、WhatsApp、飞书 (Feishu)、QQ、企业微信 (WeWork)、钉钉 (DingTalk)、百度如流 (Infoflow)、Gotify、Slack、Discord、Google Chat、Microsoft Teams、微信 (Weixin)
- 🔧 **灵活配置**：支持 YAML/JSON 配置，热加载，环境变量支持
- 🎯 **多 LLM 提供商**：OpenAI、Qianfan（百度千帆，OpenAI-compatible）、Anthropic、OpenRouter，支持故障转移
- 🌐 **WebSocket Gateway**：内置网关服务，支持实时通信
- ⏰ **Cron 调度**：内置定时任务调度器
- 🖥️ **Browser 自动化**：基于 Chrome DevTools Protocol 的浏览器控制
- 🧠 **记忆系统**：支持内置向量数据库和 QMD (Quick Markdown Database)
- 👥 **多账号支持**：每个通道支持配置多个账号实例
- 🪟 **跨平台**：支持 Linux、macOS、Windows

## 技能系统 (New!)

goclaw 引入了先进的技能系统，允许用户通过编写 Markdown 文档 (`SKILL.md`) 来扩展 Agent 的能力。

### 特性
*   **Prompt-Driven**: 技能本质上是注入到 System Prompt 中的指令集，指导 LLM 使用现有工具 (exec, read_file 等) 完成任务。
*   **OpenClaw 兼容**: 完全兼容 OpenClaw 的技能生态。您可以直接将 `openclaw/skills` 目录下的技能复制过来使用。
*   **自动准入 (Gating)**: 智能检测系统环境。例如，只有当系统安装了 `curl` 时，`weather` 技能才会生效；只有安装了 `git` 时，`git-helper` 才会加载。

### 使用方法

#### 配置文件加载优先级

goclaw 按以下顺序查找配置文件（找到第一个即使用）：

1. `~/.goclaw/config.json` (用户全局目录，**最高优先级**)
2. `./config.json` (当前目录)
3. 环境变量 `GOSKILLS_*` 前缀

可通过 `--config` 参数指定配置文件路径覆盖默认行为。支持 YAML 和 JSON 格式。

#### Skills 加载顺序

技能按以下顺序加载，**同名技能后面的会覆盖前面的**：

| 顺序 | 路径 | 说明 |
|-----|------|------|
| 1 | `~/.goclaw/skills/` | 用户全局目录（最低优先级） |
| 2 | `${WORKSPACE}/skills/` | 工作区目录 |
| 3 | `./skills/` (当前目录) | **最后加载，优先级最高** |

默认 `WORKSPACE` 为 `~/.goclaw/workspace`。

1.  **列出可用技能**
    ```bash
    ./goclaw skills list
    ```

2.  **安装技能**
    将技能文件夹放入以下任一位置：
    *   `~/.goclaw/skills/` (用户全局目录)
    *   `${WORKSPACE}/skills/` (工作区目录)
    *   `./skills/` (当前目录，**最高优先级，后加载会覆盖前面的**)

3.  **编写技能**
    创建一个目录 `my-skill`，并在其中创建 `SKILL.md`：
    ```yaml
    ---
    name: my-skill
    description: A custom skill description.
    metadata:
      openclaw:
        requires:
          bins: ["python3"] # 仅当 python3 存在时加载
    ---
    # My Skill Instructions
    When the user asks for X, use `exec` to run `python3 script.py`.
    ```

## 项目结构

```
goclaw/
├── agent/              # Agent 核心逻辑
│   ├── loop.go         # Agent 循环
│   ├── context.go      # 上下文构建器
│   ├── memory.go       # 记忆系统
│   ├── skills.go       # 技能加载器
│   ├── subagent.go     # 子代理管理器
│   └── tools/          # 工具系统
│       ├── filesystem.go   # 文件系统工具
│       ├── shell.go        # Shell 工具
│       ├── web.go          # Web 工具
│       ├── browser.go      # 浏览器工具
│       └── message.go      # 消息工具
├── channels/           # 消息通道
│   ├── base.go         # 通道接口
│   ├── manager.go      # 通道管理器
│   ├── telegram.go     # Telegram 实现
│   ├── whatsapp.go     # WhatsApp 实现
│   ├── feishu.go       # 飞书实现
│   ├── qq.go           # QQ 实现
│   ├── wework.go       # 企业微信实现
│   ├── dingtalk.go     # 钉钉实现
│   ├── infoflow.go     # 百度如流实现
│   ├── gotify.go       # Gotify 实现
│   ├── slack.go        # Slack 实现
│   ├── discord.go      # Discord 实现
│   ├── googlechat.go   # Google Chat 实现
│   ├── teams.go        # Microsoft Teams 实现
│   └── weixin.go       # 微信实现
├── bus/                # 消息总线
│   ├── events.go       # 消息事件
│   └── queue.go        # 消息队列
├── config/             # 配置管理
│   ├── schema.go       # 配置结构
│   └── loader.go       # 配置加载器
├── providers/          # LLM 提供商
│   ├── base.go         # 提供商接口
│   ├── factory.go      # 提供商工厂
│   ├── openai.go       # OpenAI 实现
│   ├── anthropic.go    # Anthropic 实现
│   └── openrouter.go   # OpenRouter 实现
├── gateway/            # WebSocket 网关
│   ├── server.go       # 网关服务器
│   ├── handler.go      # 消息处理器
│   └── protocol.go     # 协议定义
├── cron/               # 定时任务调度
│   ├── scheduler.go    # 调度器
│   └── cron.go         # Cron 任务
├── session/            # 会话管理
│   └── manager.go      # 会话管理器
├── cli/                # 命令行界面
│   ├── root.go         # 根命令
│   ├── agent.go        # Agent 命令
│   ├── agents.go       # Agents 管理命令
│   ├── sessions.go     # 会话命令
│   ├── cron_cli.go     # Cron 命令
│   ├── approvals.go    # 审批命令
│   ├── system.go       # 系统命令
│   └── commands/       # 子命令
│       ├── tui.go      # TUI 命令
│       ├── gateway.go  # Gateway 命令
│       ├── browser.go  # Browser 命令
│       ├── health.go   # 健康检查
│       ├── status.go   # 状态查询
│       ├── memory.go   # 记忆管理
│       └── logs.go     # 日志查询
├── internal/           # 内部包
│   ├── logger/         # 日志
│   └── utils/          # 工具函数
├── docs/               # 文档
│   ├── cli.md          # CLI 详细文档
│   └── INTRODUCTION.md # 项目介绍
└── main.go             # 主入口
```

## 快速开始

### 安装

```bash
# 克隆仓库
git clone https://github.com/smallnest/goclaw.git
cd goclaw

# 安装依赖
go mod tidy

# 仅编译 Go 程序
go build -o goclaw .

# 完整构建（包含 UI，推荐）
make build-full

# 或直接运行
go run main.go start
```

本地可以访问 dashboard:
```
http://localhost:28789/dashboard/
```

### 配置

goclaw 按以下顺序查找配置文件（找到第一个即使用）：

1. `~/.goclaw/config.json` (用户全局目录，**最高优先级**)
2. `./config.json` (当前目录)
3. 环境变量 `GOSKILLS_*` 前缀

可通过 `--config` 参数指定配置文件路径覆盖默认行为。支持 YAML 和 JSON 格式。

创建 `config.json` (参考 `internal/config.example.json`):

```json
{
  "workspace": {
    "path": ""
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "qianfan/kimi-k2.5"
      },
      "max_iterations": 15,
      "temperature": 0.7,
      "max_tokens": 4096
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "qianfan": {
        "baseUrl": "https://qianfan.baidubce.com/v2",
        "apiKey": "${QIANFAN_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "kimi-k2.5",
            "name": "Kimi K2.5",
            "contextWindow": 131072,
            "maxTokens": 8192,
            "input": ["text", "image"]
          }
        ]
      },
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "${OPENAI_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "contextWindow": 128000,
            "maxTokens": 16384,
            "input": ["text", "image"]
          }
        ]
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": false,
      "token": "your-telegram-bot-token",
      "allowed_ids": []
    },
    "feishu": {
      "enabled": false,
      "app_id": "",
      "app_secret": "",
      "domain": "feishu",
      "group_policy": "open"
    },
    "dingtalk": {
      "enabled": false,
      "client_id": "",
      "secret": "",
      "allowed_ids": []
    }
  },
  "tools": {
    "filesystem": {
      "allowed_paths": [],
      "denied_paths": []
    },
    "shell": {
      "enabled": true,
      "allowed_cmds": [],
      "denied_cmds": ["rm -rf", "dd", "mkfs", "format"],
      "timeout": 30,
      "working_dir": ""
    },
    "browser": {
      "enabled": true,
      "headless": true,
      "timeout": 30,
      "relay_url": "ws://127.0.0.1:18789",
      "relay_mode": "auto"
    }
  },
  "memory": {
    "backend": "builtin",
    "builtin": {
      "enabled": true,
      "database_path": "",
      "auto_index": true
    }
  }
}
```

### 运行

```bash
# 启动 Agent 服务
./goclaw start

# 交互式 TUI 
````
