⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

actionbook

smallnest@smallnest⭐ 601 stars· last commit 7mo ago· 4 open issues

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.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐ 601 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

goclaw (🐾 狗爪)

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

License go.dev reference github actions Go Report Card Coverage Status

功能特性

  • 🛠️ 完整的工具系统:FileSystem、Shell、Web、Browser,支持 Docker 沙箱与权限控制
  • 📚 技能系统 (Skills):兼容 OpenClaw 和 AgentSkills 规范,支持自动发现与环境准入控制 (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. 列出可用技能

    ./goclaw skills list
    
  2. 安装技能 将技能文件夹放入以下任一位置:

    • ~/.goclaw/skills/ (用户全局目录)
    • ${WORKSPACE}/skills/ (工作区目录)
    • ./skills/ (当前目录,最高优先级,后加载会覆盖前面的)
  3. 编写技能 创建一个目录 my-skill,并在其中创建 SKILL.md:

    ---
    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             # 主入口

快速开始

安装

# 克隆仓库
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):

{
  "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
    }
  }
}

运行

# 启动 Agent 服务
./goclaw start

# 交互式 TUI 

// HOW IT'S BUILT

// FILES

5 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • internal/builtin_skills/actionbook/SKILL.md16 KB82ceb3b35430upstream ↗
    ---
    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 |
  • internal/builtin_skills/actionbook/references/authentication.md5.3 KBa98daec88c41upstream ↗
    # 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
       ```
    
  • internal/builtin_skills/actionbook/references/command-reference.md8.6 KB613aa1e500b8upstream ↗
    # 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" "[email protected]"
    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
    ```
    
  • internal/builtin_skills/actionbook/references/extension-troubleshooting.md1.4 KB91dc30e7bd02upstream ↗
    # 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
    ```
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/smallnest-goclaw-internal-builtin-skills-actionbook.md

// REPO STATS

601 stars
4 open issues
Last commit: 7mo ago