# Hermes Webclaw

> Hermes Agent plugin that replaces the bundled Firecrawl plugin with native WebClaw v1 API support — search, scrape/extract, and crawl. Install when the user wants to use WebClaw as their web backend in Hermes, set up WEBCLAW_API_KEY, or switch from Firecrawl to WebClaw.

- Skill: `jal-co/hermes-webclaw` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add jal-co/hermes-webclaw`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jal-co/hermes-webclaw/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: AGPL-3.0
- Author: jal-co (https://skillmd.com/u/jal-co)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jal-co/hermes-webclaw

---


# hermes-webclaw

Hermes Agent plugin providing native [WebClaw](https://webclaw.io) v1 API
support as a drop-in replacement for the bundled Firecrawl plugin.

## What is WebClaw?

[WebClaw](https://github.com/0xMassi/webclaw) is a fast, open-source web
extraction toolkit built in Rust. It extracts clean markdown, JSON, or
LLM-optimized text from any website using HTTP with browser-grade TLS
impersonation — no headless browser required. 118ms average response time.

## What this plugin does

Registers a `WebSearchProvider` subclass (`webclaw`) that Hermes's built-in
`web_search`, `web_extract`, and `web_crawl` tools route through, **plus 9
dedicated tools** for the full WebClaw v1 API surface:

| Tool | WebClaw endpoint | What it does |
|---|---|---|
| `webclaw_scrape` | `/v1/scrape` | Single URL extraction — CSS filtering, screenshots, mobile UA, page Q&A |
| `webclaw_search` | `/v1/search` | Web search with optional parallel scraping of result URLs |
| `webclaw_crawl` | `/v1/crawl` | Async BFS site crawl with depth/page limits, sitemap seeding |
| `webclaw_extract` | `/v1/extract` | LLM-powered structured data extraction via JSON schema or prompt |
| `webclaw_summarize` | `/v1/summarize` | LLM-powered page summarization |
| `webclaw_diff` | `/v1/diff` | Content change tracking against a previous snapshot |
| `webclaw_map` | `/v1/map` | Sitemap discovery via sitemap.xml and robots.txt |
| `webclaw_batch` | `/v1/batch` | Multi-URL extraction in a single concurrent request |
| `webclaw_brand` | `/v1/brand` | Brand identity extraction — colors, fonts, logo, favicon |

## Install

### 1. Get a WebClaw API key

Sign up at [webclaw.io](https://webclaw.io) and create an API key from the
dashboard. Keys are prefixed with `wc_`.

### 2. Copy plugin files to Hermes

Run the install script on the Hermes host:

```bash
bash scripts/install.sh
```

Or manually:

```bash
PLUGIN_DIR=/usr/local/lib/hermes-agent/plugins/web/webclaw
mkdir -p "$PLUGIN_DIR"
cp scripts/plugin.yaml  "$PLUGIN_DIR/plugin.yaml"
cp scripts/__init__.py   "$PLUGIN_DIR/__init__.py"
cp scripts/provider.py   "$PLUGIN_DIR/provider.py"
```

### 3. Set the API key

Add to `~/.hermes/.env`:

```
WEBCLAW_API_KEY=wc_your_key_here
```

### 4. Set WebClaw as the web backend

Edit `~/.hermes/config.yaml`:

```yaml
web:
  backend: webclaw
```

Or set per-capability:

```yaml
web:
  search_backend: webclaw
  extract_backend: webclaw
  crawl_backend: webclaw
```

### 5. (Optional) Disable Firecrawl

Both plugins register as web providers. If Firecrawl has credentials
configured, disable it to avoid conflicts:

```bash
mv /usr/local/lib/hermes-agent/plugins/web/firecrawl \
   /usr/local/lib/hermes-agent/plugins/web/firecrawl.disabled
```

### 6. Restart the gateway

```bash
sudo systemctl restart hermes-gateway
```

### 7. Verify

Check the gateway logs for WebClaw registration:

```bash
journalctl -u hermes-gateway --no-pager -n 20 | grep -i webclaw
```

Or run `hermes tools` and confirm WebClaw appears as the web backend.

## Environment variables

| Variable           | Required | Description                                              |
|--------------------|----------|----------------------------------------------------------|
| `WEBCLAW_API_KEY`  | Yes      | Your WebClaw API key (`wc_...`). Get one at webclaw.io.  |
| `WEBCLAW_BASE_URL` | No       | Override API base URL. Default: `https://api.webclaw.io`. |

## Self-hosting WebClaw

If running [`webclaw-server`](https://github.com/0xMassi/webclaw) locally:

```bash
WEBCLAW_API_KEY=your_secret
WEBCLAW_BASE_URL=http://your-server:3000
```

## Uninstall

```bash
rm -rf /usr/local/lib/hermes-agent/plugins/web/webclaw
# If you renamed Firecrawl, restore it:
mv /usr/local/lib/hermes-agent/plugins/web/firecrawl.disabled \
   /usr/local/lib/hermes-agent/plugins/web/firecrawl
sudo systemctl restart hermes-gateway
```

## Credits

Powered by [WebClaw](https://github.com/0xMassi/webclaw) by
[@0xMassi](https://github.com/0xMassi).