Skill: saschabuehrle/cascadeflow (version 1.1.1)

--- name: cascadeflow description: OpenClaw-native domain cascading. Use when users need cost/latency reduction via cascading, domain-aware model assignment, OpenClaw-native event handling, and command setup including /model cflow and optional /cascade stats commands. --- # CascadeFlow: Cost + Latency Reduction | 17+ Domain-Aware Models + OpenClaw-Native Events Use CascadeFlow as an OpenClaw provider to lower cost and latency via cascading. Assign up to 17 domain-specific models (for coding, web search, reasoning, and more), including OpenClaw-native event handling, and cascade between them (small model first, verifier when needed). Keep setup minimal, then verify with one health check and one chat call. ## Why Use It - Reduce spend with drafter/verifier cascading. - Run 17+ domain-aware model assignments (code, reasoning, web-search, and more). - Support cascading with streaming and multi-step agent loops. - Handle OpenClaw-native event/domain signals for smarter model selection. ## Security Defaults - Install from PyPI and verify package artifact before first run. - Keep the server bound to localhost by default. - Use explicit auth tokens for chat and stats endpoints (recommended for production). - Expose remote access only behind TLS/reverse proxy with strong tokens. - Use least-privilege provider keys (separate test keys from production keys). ## How It Works 1. OpenClaw sends requests to CascadeFlow through OpenAI-compatible `/v1/chat/completions`. 2. CascadeFlow reads prompt context plus OpenClaw-native event/domain metadata (for example `metadata.method`, `metadata.event`, and channel/category hints). 3. CascadeFlow selects a domain-aware drafter/verifier pair (small model first). 4. If quality passes threshold, drafter answer is returned (cost/latency advantage). 5. If quality fails threshold, verifier runs and final answer is upgraded. 6. The same cascading behavior is supported for streaming and multi-step agent loops. ### Advantages - Lower average cost by avoiding verifier calls when not needed. - Lower average latency for simple and medium tasks. - Better quality on hard tasks through verifier fallback. - Better operational handling through OpenClaw-native event/domain understanding. ## Quick Start Or ask your OpenClaw agent to set it up for you as an OpenClaw custom provider with OpenClaw-native events and domain understanding. 1. Install and verify package source: ```bash python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade "cascadeflow[openclaw]>=0.7,<0.8" python -m pip show cascadeflow python -m pip download --no-deps "cascadeflow[openclaw]>=0.7,<0.8" -d /tmp/cascadeflow_pkg python -m pip hash /tmp/cascadeflow_pkg/cascadeflow-*.whl ``` Optional variants: ```bash python -m pip install --upgrade "cascadeflow[openclaw,anthropic]>=0.7,<0.8" # Anthropic-only preset python -m pip install --upgrade "cascadeflow[openclaw,openai]>=0.7,<0.8" # OpenAI-only preset python -m pip install --upgrade "cascadeflow[openclaw,providers]>=0.7,<0.8" # Mixed preset ``` 2. Pick preset + credentials: - Presets: `examples/configs/anthropic-only.yaml`, `examples/configs/openai-only.yaml`, `examples/configs/mixed-anthropic-openai.yaml` - Provider key(s): `ANTHROPIC_API_KEY=...` and/or `OPENAI_API_KEY=...` (required based on selected preset) - Service tokens: `--auth-token ...` and `--stats-auth-token ...` (recommended for production; use long random values) 3. Start server (safe local default): ```bash set -a; source .env; set +a python3 -m cascadeflow.integrations.openclaw.openai_server \ --host 127.0.0.1 --port 8084 \ --config examples/configs/anthropic-only.yaml \ --auth-token local-openclaw-token \ --stats-auth-token local-stats-token ``` Optional harness activation (runtime in-loop policy controls): ```bash # Observe first (recommended): log decisions, no blocking python3 -m cascadeflow.integrations.openclaw.openai_server \ --host 127.0.0.1 --port 8084 \ --config examples/configs/anthropic-only.yaml \ --harness-mode observe # Enforce mode with limits python3 -m cascadeflow.integrations.openclaw.openai_server \ --host 127.0.0.1 --port 8084 \ --config examples/configs/anthropic-only.yaml \ --harness-mode enforce \ --harness-budget 1.0 \ --harness-max-tool-calls 12 \ --harness-max-latency-ms 3500 \ --harness-compliance strict ``` 4. Configure OpenClaw provider: - `baseUrl`: `http://<cascadeflow-host>:8084/v1` (local default: `http://127.0.0.1:8084/v1`) - If remote: `http://<server-ip>:8084/v1` or `https://<domain>/v1` (TLS/reverse proxy) - `api`: `openai-completions` - `model`: `cascadeflow` - `apiKey`: same value as your `--auth-token` ## Commands - `/model cflow`: default OpenClaw model switch using alias `cflow`. - `/cascade`: optional custom command (if configured in OpenClaw). - `/cascade savings`: optional custom subcommand for cost stats. - `/cascade health`: optional custom subcommand for service status. ## Links - Full setup + configs: `references/clawhub_publish_pack.md` - Listing strategy: `references/market_positioning.md` - Official docs: `https://github.com/lemony-ai/cascadeflow/blob/main/docs/guides/openclaw_provider.md` - GitHub repository: `https://github.com/lemony-ai/cascadeflow`

path: agents/openai.yaml
content: interface:
  display_name: "CascadeFlow: Cost + Latency Reduction"
  short_description: "Cascading savings with OpenClaw-native routing"
  default_prompt: "Use $cascadeflow to configure a secure localhost provider, required keys/tokens, and /model cflow."


path: references/clawhub_publish_pack.md
content: # ClawHub Publish Pack

Use this pack to publish and support CascadeFlow as an OpenClaw custom provider for any user.

## Core Differentiator: OpenClaw-Native Event + Domain Routing

CascadeFlow does not only proxy chat completions. It understands OpenClaw-native routing signals and applies domain/channel-specific model routing.

- Reads `metadata.method` and `metadata.event` (plus compatible tags/flags).
- Detects domain/category/channel hints from OpenClaw payload metadata.
- Applies domain-specific drafter/verifier model pairs and thresholds.
- Supports channel routing for low-value operational events to cheaper models.

Minimal payload example (OpenClaw -> CascadeFlow):

```json
{
  "model": "cascadeflow",
  "messages": [{"role": "user", "content": "status ping"}],
  "metadata": {
    "method": "heartbeat",
    "event": "cron",
    "channel": "heartbeat"
  }
}
```

Result:

- operational events can route to cheap channel models
- code/reasoning/creative/user requests can route to domain-optimized cascades
- behavior works with Anthropic-only, OpenAI-only, and mixed presets

## Required Metadata

- `folder`: `cascadeflow`
- `slug`: `cascadeflow`
- `display_name`: `CascadeFlow: Cost + Latency Reduction`
- `source_url`: `https://github.com/lemony-ai/cascadeflow`
- `homepage_url`: `https://github.com/lemony-ai/cascadeflow/blob/main/docs/guides/openclaw_provider.md`

## Credentials To Declare In Listing

- `OPENAI_API_KEY` (required when using OpenAI models/preset)
- `ANTHROPIC_API_KEY` (required when using Anthropic models/preset)
- `CASCADEFLOW_AUTH_TOKEN` (recommended in production; maps to server `--auth-token`)
- `CASCADEFLOW_STATS_AUTH_TOKEN` (optional separate stats token; maps to server `--stats-auth-token`)

Do not leave credential requirements empty in listing metadata.
Use strong random token values in production (examples in this file are placeholders).

## Upload Folder

Upload this folder to ClawHub:

- `cascadeflow/` (the skill folder containing `SKILL.md`)

Minimum files included:

- `SKILL.md`
- `agents/openai.yaml`
- `references/clawhub_publish_pack.md`
- `references/market_positioning.md`

## 1) Install CascadeFlow

Fastest base setup (OpenClaw integration extras):

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade "cascadeflow[openclaw]>=0.7,<0.8"
python -m pip show cascadeflow
python -m pip download --no-deps "cascadeflow[openclaw]>=0.7,<0.8" -d /tmp/cascadeflow_pkg
python -m pip hash /tmp/cascadeflow_pkg/cascadeflow-*.whl
```

Quick provider variants:

```bash
# Anthropic-only preset users
python -m pip install --upgrade "cascadeflow[openclaw,anthropic]>=0.7,<0.8"

# OpenAI-only preset users
python -m pip install --upgrade "cascadeflow[openclaw,openai]>=0.7,<0.8"

# Mixed preset users (OpenAI + Anthropic + common providers)
python -m pip install --upgrade "cascadeflow[openclaw,providers]>=0.7,<0.8"
```

## 2) Pick A Preset Config (All 3)

Preset files:

- `examples/configs/anthropic-only.yaml`
- `examples/configs/openai-only.yaml`
- `examples/configs/mixed-anthropic-openai.yaml`

Notes:

- Anthropic-only: lower-cost Anthropic drafter -> stronger Anthropic verifier.
- OpenAI-only: current main uses `gpt-5-mini` drafter -> `gpt-5` verifier.
- Mixed: combines OpenAI and Anthropic for domain-specific routing.

## 3) Set API Keys

In `.env`:

```bash
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...
```

Use only keys required by the selected preset.

## 4) Start Server

### Option A (OpenClaw-specific server)

```bash
set -a; source .env; set +a
python3 -m cascadeflow.integrations.openclaw.openai_server \
  --host 127.0.0.1 \
  --port 8084 \
  --config examples/configs/anthropic-only.yaml \
  --auth-token local-openclaw-token \
  --stats-auth-token local-stats-token \
  --max-body-bytes 2000000 \
  --socket-timeout 30
```

### Option B (Gateway server)

```bash
set -a; source .env; set +a
cascadeflow-gateway --port 8084 --mode agent --config examples/configs/anthropic-only.yaml
```

Background mode:

```bash
nohup cascadeflow-gateway --port 8084 --mode agent --config examples/configs/anthropic-only.yaml > /tmp/cf.log 2>&1 &
```

## 5) Configure OpenClaw Custom Provider

```json
{
  "models": {
    "mode": "merge",
    "providers": {
      "cascadeflow": {
        "baseUrl": "http://<cascadeflow-host>:8084/v1",
        "apiKey": "local-openclaw-token",
        "api": "openai-completions",
        "models": [
          {
            "id": "cascadeflow",
            "name": "CascadeFlow",
            "reasoning": false,
            "input": ["text"],
            "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}
```

Host notes:
- If OpenClaw and CascadeFlow run on the same machine, keep `127.0.0.1`.
- If CascadeFlow runs on another machine, use that server IP or domain.

If server runs elsewhere, users should replace it with their host/IP, e.g.:
- `http://<server-ip>:8084/v1` or `https://<domain>/v1` (behind proxy/TLS).
- Keep `apiKey` equal to the server auth token value.

## 6) Create OpenClaw Agent

```json
{
  "id": "cascadeflow",
  "name": "CascadeFlow",
  "model": "cascadeflow/cascadeflow",
  "workspace": "/path/to/workspace-cascadeflow"
}
```

## 7) Optional Alias And Commands

Alias config:

```json
{
  "agents": {
    "defaults": {
      "models": {
        "cascadeflow/cascadeflow": {
          "alias": "cflow",
          "streaming": false
        }
      }
    }
  }
}
```

User commands:

- `/model cflow`: switch model using alias.
- `/cascade`: optional custom command only if OpenClaw side defines it.
- `/cascade savings`: optional custom subcommand pattern for cost breakdown.
- `/cascade health`: optional custom subcommand pattern for status checks.

## 8) Optional Binding Example

```json
{
  "bindings": [
    {
      "agentId": "cascadeflow",
      "match": {"channel": "telegram", "accountId": "cascadeflow"}
    }
  ]
}
```

## Key Concepts Users Must Understand

- CascadeFlow exposes OpenAI-compatible chat completions.
- OpenClaw treats CascadeFlow as a standard provider.
- Cascade routing: cheap drafter first, verifier only when needed.
- OpenClaw-native event/domain understanding: metadata-driven channel and domain routing.
- Domain routing: code, reasoning, creative, and others can use different model pairs.
- Savings metrics available at `/stats`.

Stats example:

```bash
curl -s http://<cascadeflow-host>:8084/stats -H "[REDACTED_SECRET]"
```

## Streaming And Compatibility Notes

- Keep base URL with `/v1` prefix.
- Handle clients that hardcode `stream: true`.
- Ensure SSE sends delta chunks, final stop chunk, optional usage chunk, then `[DONE]`.

## Validation Checklist

- `name` in `SKILL.md` equals `cascadeflow`.
- Upload folder name equals slug (`cascadeflow`).
- `/model cflow` guidance is present.
- `/cascade` is documented as optional/custom.
- All three preset files are documented.

Run validator:

```bash
python3 /path/to/skill-creator/scripts/quick_validate.py /path/to/cascadeflow
```


path: references/market_positioning.md
content: # Market Positioning For ClawHub

This note summarizes observed OpenClaw/ClawHub patterns and how to position CascadeFlow for a strong listing.

## What Existing Listings Signal

Observed from public ClawHub skill pages:

- `openclaw` emphasizes broad capability and direct install command.
- `context7` emphasizes practical developer utility and easy install.
- Skill pages are brief; the first value statement and install path carry most of the conversion.

Observed from OpenClaw docs:

- Slash command aliases are a first-class pattern (for example `/model myalias`).
- Users expect provider setup to be copy-paste and reversible.

## Winning Listing Principles

1. Lead with measurable outcome:
- "Reduce cost and latency" should be in title and short description.

2. Highlight OpenClaw-native intelligence:
- Emphasize event/domain understanding (`metadata.method`, `metadata.event`) as a unique capability.
- Explain that operational events and user domains route differently by design.

3. Keep time-to-first-success short:
- One install block.
- One provider config block.
- One command to switch model (`/model cflow`).

4. Remove ambiguity:
- Explicitly mark `/cascade` as optional custom command.
- Explicitly list all 3 presets and when to use each.

5. Build trust:
- Show secure defaults (`auth-token`, localhost bind, stats token).
- Show health/stats/smoke checks.

6. Keep compatibility messaging clear:
- Works as OpenAI-compatible provider transport.
- Works with OpenAI-only, Anthropic-only, and mixed routes.

## Suggested ClawHub Listing Copy

Display name:

- `CascadeFlow: Cost + Latency Reduction`

Short description:

- `Reduce LLM cost and latency with CascadeFlow routing`

One-line value prop:

- `OpenClaw provider with native event/domain understanding and drafter/verifier cascades for lower cost, lower latency, and quality control.`

## Recommended User-Facing Sections

- Quickstart (install + start + provider config)
- Presets (OpenAI-only, Anthropic-only, mixed)
- Commands (`/model cflow`, optional `/cascade`)
- Verification checks (`/health`, `/stats`, chat completion)
- Troubleshooting (streaming, auth, endpoint path)

## Sources

- OpenClaw + ClawHub docs: https://docs.openclaw.bot/guide/clawhub
- OpenClaw slash commands docs: https://docs.openclaw.bot/guide/faq/slash-commands
- ClawHub OpenClaw listing page: https://www.clawhub.ai/s/openclaw
- ClawHub Context7 listing page: https://www.clawhub.ai/s/context7


Security scan verdicts — ClawScan: clean | static analysis: suspicious | VirusTotal: clean | SkillSpector: clean (LOW)