configure

# sponsio-openclaw — configure the host plugin

You are walking the user through configuring the **sponsio-openclaw**
plugin so it actually wraps tool calls in this OpenClaw session.
Without these steps, the plugin loads but every per-plugin library
is empty and every tool call passes through unguarded.

The plugin sends `host: "openclaw"` in its hook payload so the
runtime fallback library is `_host_openclaw` (OpenClaw canonical
tool names — `exec` / `read` / `write` / `edit` / `apply_patch` /
`web_fetch` / `send_message` — with `path` / `command` / `url`
params), not the Claude-Code-shaped `_host`.  Both libraries live
under the same `~/.sponsio/plugins/` tree.

## Prerequisites (check silently first)

Run:

```bash
sponsio --version
```

* Not found → tell the user to install: `pip install sponsio` (or
  `pip install -e ".[all]"` from a local clone).  Stop here until
  they confirm.
* Present → continue.

If the user owns the agent code and wants to wire Sponsio into their
own framework integration **instead of** running it as an OpenClaw
host plugin, delegate to the `sponsio` skill (`sponsio onboard .`).
This skill is only for the host-plugin case where the user is gating
tool calls inside an OpenClaw session.

## Routing rules from a policy document

Sponsio has two layers, and rules must land in the right YAML or they
do nothing. When the user hands you a policy document / instruction
file / "list of things the agent must not do" and asks you to encode
it, classify **each rule** before writing anywhere.

| Signal | → Layer 1 (this skill — write to `~/.sponsio/plugins/<id>/sponsio.yaml`) | → Layer 2 (delegate to `sponsio` skill — writes `<project>/sponsio.yaml`) |
|---|---|---|
| Tool names mentioned | `exec`, `read`, `write`, `edit`, `apply_patch`, `web_fetch`, `send_message` (OpenClaw primitives), `mcp__*` | tool names from the user's project's tool inventory |
| Path form | absolute or `~/...` paths outside the user's project | paths relative to the project (`src/...`) |
| Subject of the rule | "OpenClaw must not…", "the coding agent must not…" | "the loan agent must…", "the chatbot should…" |
| Domain language | shell, git, file system, MCP server primitives | AML, KYC, refund, PII, approval, faithfulness, hallucination |
| `./sponsio.yaml` exists in cwd | weaker signal — Layer 2 is in play, but rule may still be Layer 1 | stronger signal — most rules belong here |

Process:
1. For each rule, score by the signals above.
2. Route unambiguously-Layer-1 rules to this skill's flow.
3. For Layer-2 rules, **stop writing here** and tell the user
   "rules X, Y look like rules for the agent you're building, not
   the OpenClaw host — switching to the `sponsio` skill (`sponsio
   onboard`) for those". Do not silently dump them into a host-plugin
   YAML.
4. For genuinely ambiguous rules ("PII must not leak"), ask the user
   which layer they mean before writing.

The default failure mode is over-writing to Layer 1 because that's
this skill's home turf. Cross-layer leakage is a worse user error
than the extra clarification round.

## Step 1 — bootstrap the library root

Run:

```bash
sponsio plugin init
```

This creates `~/.sponsio/plugins/_host/sponsio.yaml` (Claude-Code-
shape, mostly inert in an OpenClaw session) and
`~/.sponsio/plugins/_host_openclaw/sponsio.yaml` (OpenClaw-shape,
the one that actually fires for OpenClaw fallback tools — `exec`
fork-bombs, dotenv reads, SSH-key writes, `~/.clawdbot/.env`
exfiltration patterns, etc.).  Show the user the output verbatim;
if the smoke test fails, **stop** and surface the error — the
install is broken.

If the file already exists (re-running setup), the command prints
`…already exists. Re-run with --force to overwrite.`  Informational,
not an error.

## Step 2 — enumerate the user's plugins / MCP servers

You need to know which plugins / MCP servers the user actually has
installed before deciding which contract libraries to author.  Two
discovery paths:

* **OpenClaw plugins** — read `~/.openclaw/plugins.json` or the
  equivalent the user's install uses.  If they don't know, ask them
  to list registered plugins from their OpenClaw config.
* **MCP servers** — same conventions as Claude Code; look for `.mcp.json`
  in any registered plugin's directory.

There are no bundled OpenClaw starter libraries today (Claude Code
ships `github` / `filesystem` / `playwright` because those MCP
servers were prioritised first).  Every OpenClaw plugin goes through
**Step 3** below.

## Step 3 — generate per-plugin libraries via `sponsio plugin scan`

Three discovery paths in priority order:

### 3.1 — `--introspect` (preferred for MCP servers)

sponsio spawns the server, does the JSON-RPC `initialize` +
`tools/list` handshake, and auto-populates the tool inventory along
with parameter schemas.  Read the plugin's manifest to find the
spawn command, then:

```bash
sponsio plugin scan \
  --plugin-id <name> \
  --target-host openclaw \
  --introspect "<spawn-cmd>"
```

For OpenClaw, ALWAYS pass `--target-host openclaw` so the generated
contracts use **flat** tool names (matching how OpenClaw surfaces
them) rather than Claude Code's `mcp__<plugin>__` prefixed shape.

### 3.2 — Static-tool list

When the plugin doesn't run an MCP server (e.g. an OpenClaw skill
that exposes tools through the SDK directly), pass tool names via
`--tools`:

```bash
sponsio plugin scan <plugin-dir> --tools tool_a,tool_b,tool_c \
  --target-host openclaw
```

### 3.3 — Operator-supplied tool list

Last resort — ask the user "what tools does this plugin expose?"
and pass them via `--tools`.  Use only when introspection fails or
the plugin isn't structured as an MCP server.

### 3.4 — Dry-run

```bash
sponsio plugin scan --plugin-id <id> --target-host openclaw \
  --introspect "<spawn-cmd>"
```

Output has two parts:

1. **Heuristic library yaml** (one per routed group) — name-pattern
   rules covering destructive verbs, rate-limit / loop-detection
   caps.  Deterministic floor.

2.