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:

bashCopy code
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.

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:

bashCopy code
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:

bashCopy code
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:

bashCopy code
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

bashCopy code
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. Tool inventory JSON under # === tool inventory ... === — every tool's name, description, input_schema, plus tool_name_in_contracts (flat for OpenClaw — no mcp__ prefix). This is the input for the agent's own contract extraction.

3.5 — Apply the contract-extraction prompt

The heuristic engine catches obvious cases by name; the agent (you) fills semantic gaps by reading each tool's description + input_schema. No API call needed — you ARE the LLM the prompt is written for.

1. Get the prompt:

   bashCopy code
   sponsio plugin prompt openclaw
   

2. Apply it to the JSON tool inventory from Step 3.4. Output a JSON object:

   jsonCopy code
   {"contracts": [{"desc": "...", "pattern": "...", "args": [...]}]}
   

3. Translate to YAML and merge into the heuristic library. Mark each semantic contract with source: agent-extracted for later traceability.

3.6 — Review every contract

ALWAYS start with the dry-run. Never --apply until the user has seen the output.

For each contract proposed, state:

• What it blocks — translate the regex / cap into plain English.
• Why — point at the heuristic (starter_irreversible, starter_bash, starter_rate_limit, starter_loop) or the LLM's desc. LLM proposals carry source: plugin-scan-llm for traceability.
• What it doesn't catch — be explicit about generic rules so the user doesn't assume coverage they don't have.

If a rule is wrong, drop it from the rendered yaml or add a customized: block:

yamlCopy code
customized:
  - match: { desc: "<offending desc>" }
    disabled: true

3.7 — Apply

Once the user is happy with the dry-run:

bashCopy code
sponsio plugin scan <plugin-dir> --target-host openclaw \
  --introspect "..." --apply

This writes one yaml per routed group under ~/.sponsio/plugins/<plugin-id>/.

3.8 — show the user what got loaded

After every successful apply, render the contract digest so the user sees what's now enforced before any later tuning:

bashCopy code
sponsio plugin show <plugin-id>

The digest groups rules by category (hard denies, rate limits, arg blocks, …). Surface it verbatim — paraphrasing strips the detail the operator needs to spot misroutes. sponsio plugin install <bundled-name> already calls this digest internally; for scan --apply, you call it manually.

Step 4 — tune the rules

Walk through three tuning axes the user should answer before flipping to enforce:

4.1 — workspace path

OpenClaw's capability/filesystem and incident/openclaw packs use <workspace>/ as path-allowlist root. If the user wants those included (they're NOT in the default _host_openclaw to avoid the no-workspace-set crash), add:

yamlCopy code
agents:
  _host_openclaw:
    workspace: /Users/<them>/projects/<repo>
    include:
      - sponsio:capability/shell
      - sponsio:capability/filesystem
      - sponsio:incident/openclaw

4.2 — environment profile

4.3 — known-false-positive customizations

Common cases:

4.4 — hand off to the user (don't write the file or invent YAML)

Per-plugin libraries live in a single file:

Copy code
~/.sponsio/plugins/<id>/sponsio.yaml

Inside, shipped contracts carry source: bundle:<id> (stamped at install). The user's customisations sit beside them: new contracts get appended (no source tag), and adjustments to shipped rules go into a customized: block (disabled: true, retuned args:, narrowed A:).

sponsio plugin install <id> (or sponsio host install <host>) is idempotent — re-run any time to pull a new bundle (e.g. after pip install -U sponsio) without losing customisations. Default contracts are wholesale replaced from the new bundle; every user-authored contract and the entire customized: block survive. Hand-editing a default contract's body in place is the one thing that doesn't survive — express changes as a customized: entry instead.

The agent must NOT use Edit, Write, MultiEdit, or shell redirects on this file — the runtime self-modify pack blocks those calls. The agent also must NOT hand the user a YAML snippet it composed from the conversation. Legitimate sources of contract content: bundle libraries (sponsio plugin install), CLI extraction (sponsio plugin scan / sponsio scan / sponsio onboard), and the user's own keystrokes. An LLM-composed snippet has none of those provenances.

For every customization the walkthrough produces:

1. Restate, in plain English, what the user wants and which shipped rule it affects. sponsio plugin show <id> prints the desc of every loaded rule; quote a desc verbatim from that output if you need to reference one — but do NOT compose YAML around it.

2. Tell the user the file path (~/.sponsio/plugins/<id>/sponsio.yaml) and describe the change in words ("add a customized: entry beside the agent's contracts: list whose match.desc is the rule you want to silence, with disabled: true"). Point them at the existing pack's syntax; let them write the YAML themselves.

3. When the user says they're done, run sponsio validate --config ~/.sponsio/plugins/<id>/sponsio.yaml and help them debug if it doesn't parse.

Step 5 — verify the deny path

Run a synthetic event through the hook:

bashCopy code
echo '{"hook_event_name":"PreToolUse","tool_name":"exec","tool_input":{"command":"rm -rf /"},"host":"openclaw"}' \
  | sponsio plugin guard --stdin

Expect: a JSON deny payload on stdout. If empty:

1. Library at ~/.sponsio/plugins/_host_openclaw/sponsio.yaml is missing or wrong — re-run sponsio plugin init --force.
2. Sponsio CLI version is older than the libraries' rule shapes — pip install -U sponsio.

For a per-plugin library you scanned in step 3, do the same with one of its tool names + a pattern you expect to block.

Step 6 — tell the user to reload the plugin

OpenClaw runtime needs to re-pick up the manifest. The exact reload mechanism depends on the OpenClaw version — typically restarting the OpenClaw runtime or running its plugin-reload command. Confirm the plugin is loaded before testing further.

Common configuration adjustments

Operator wants observe mode (log, don't block):

bashCopy code
export SPONSIO_GUARD_MODE=observe

This dial only affects this plugin; other Sponsio integrations in the same shell still respect SPONSIO_MODE independently.

Operator wants per-plugin overrides instead of editing the library:

yamlCopy code
agents:
  <plugin-id>:
    contracts: [...shipped...]
    customized:
      - match: { desc: "<rule desc>" }
        disabled: true

Troubleshooting

"My rule looks right but the deny doesn't fire."

Most common causes:

1. Wrong tool name shape. Did you use --target-host openclaw? With claude-code the contract gets mcp__<plugin>__<tool> — that won't match OpenClaw's flat names. Re-scan with the right target.
2. Wrong routing. Check the file lives at ~/.sponsio/plugins/<routed-id>/sponsio.yaml where the routed id matches what derive_plugin_id would return. For OpenClaw flat names that don't match a namespace, fallback is _host_openclaw, not _host.
3. Rate / count rules don't fire on the first call. The stateless hook gets a fresh empty trace per fire. Until daemon mode lands, only argument-level rules (arg_blacklist, arg_value_range, scope_limit, arg_length_limit, dangerous_*) reliably fire on a single call.

What you must not do

• Do not auto-apply scan results without showing the dry-run.
• Do not invent tool names. If introspection fails and the user can't list them, say so — don't fabricate.
• Do not use --force on a user-edited library without explicit consent.
• Do not set --target-host claude-code for an OpenClaw user — the rules won't match.
• Do not edit files under sponsio/contracts/*.yaml inside the installed Sponsio package. User-level adjustments go in ~/.sponsio/plugins/<plugin>/sponsio.yaml.
• Do not flip SPONSIO_GUARD_MODE=observe "to make the smoke test pass". A failing smoke test means something's broken; silencing it hides the bug.