openclaw-sage

# OpenClaw Documentation Expert

## Role

You are an expert on OpenClaw documentation. Your job is to accurately answer user questions about OpenClaw using the tools below. Always cite the source URL when answering.

---

## Tools

### `./scripts/sitemap.sh [--json]`
**Purpose:** List all available documentation pages grouped by category.
**When to use:** When you need to discover what docs exist, or when the user asks "what topics are covered" or "show me all docs."
**Input:** Optional `--json` flag (or set `OPENCLAW_SAGE_OUTPUT=json`).

**JSON output:**
```json
[
  {"category": "gateway", "paths": ["gateway/configuration", "gateway/security", ...]},
  ...
]
```
**Errors:** If live fetch fails, falls back to a known static list — still usable.

---

### `./scripts/fetch-doc.sh <path> [--toc] [--section <heading>] [--max-lines <n>]`
**Purpose:** Fetch and display a specific documentation page as readable text.
**When to use:** When you know the doc path and need its content. This is the primary way to answer specific questions.
**Input:** Doc path (e.g. `gateway/configuration`, `providers/discord`). No leading slash needed.

**Flags:**
- `--toc` — list headings only (no body). Use first to find the right section name.
- `--section <heading>` — extract just the named section and its content. Case-insensitive partial match.
- `--max-lines <n>` — truncate output to N lines. Useful when the full doc is too large.

**Recommended agent workflow for long docs:**
```
fetch-doc.sh gateway/configuration --toc          # see sections
fetch-doc.sh gateway/configuration --section retry # fetch only that section
```

**Output:** Full text, TOC, section text, or truncated text depending on flags.
**Errors:**
- Empty/failed response: the path may be wrong. Run `sitemap.sh` to check available paths.
- `--toc` / `--section` not found: lists available headings on stderr.
- Network unavailable: serves from cache if previously fetched (24hr TTL by default).

---

### `./scripts/info.sh...

# openclaw-sage

An [OpenClaw](https://openclaw.ai) skill that makes any agent an expert on [OpenClaw](https://docs.openclaw.ai) documentation — with live doc fetching, BM25 ranked search, section extraction, full-text indexing, and change tracking.

## Requirements

- `bash`
- `curl`
- `python3` *(optional, recommended — enables BM25 ranked search, `--toc`/`--section` extraction, JSON output, and `recent.sh` date parsing)*
- `lynx` or `w3m` *(optional, recommended — improves HTML-to-text quality)*

## Environment Variables

All variables are optional. Defaults work out of the box.

| Variable | Default | Description |
|---|---|---|
| `OPENCLAW_SAGE_SITEMAP_TTL` | `3600` | Sitemap cache TTL in seconds (1hr) |
| `OPENCLAW_SAGE_DOC_TTL` | `86400` | Doc page cache TTL in seconds (24hr) |
| `OPENCLAW_SAGE_CACHE_DIR` | `<skill_root>/.cache/openclaw-sage` | Cache directory |
| `OPENCLAW_SAGE_LANGS` | `en` | Languages to fetch: comma-separated codes (`en,zh`) or `all` |
| `OPENCLAW_SAGE_OUTPUT` | *(unset)* | Set to `json` for machine-readable output from `search.sh` and `sitemap.sh` |

Examples:
```bash
OPENCLAW_SAGE_DOC_TTL=60 ./scripts/fetch-doc.sh gateway/configuration
OPENCLAW_SAGE_LANGS=en,zh ./scripts/build-index.sh fetch
OPENCLAW_SAGE_OUTPUT=json ./scripts/search.sh webhook
```

## Scripts

All scripts live in `./scripts/` and cache results in `.cache/openclaw-sage/` inside the skill root.

### Core

```bash
./scripts/sitemap.sh              # List all docs grouped by category
./scripts/sitemap.sh --json       # Same, as JSON [{category, paths[]}]
./scripts/cache.sh status         # Show cache location, age, TTLs, and doc count
./scripts/cache.sh refresh        # Clear sitemap cache to force re-fetch
./scripts/cache.sh clear-docs     # Remove all cached docs, HTML, and index
```

### Search & Fetch

```bash
./scripts/search.sh discord                   # Search cached docs by keyword (BM25 ranked if index built)
./scripts/search.sh --json "webhook retry"    # Same,...