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:

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:

• For each rule, score by the signals above.
• Route unambiguously-Layer-1 rules to this skill's flow.
• 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.

• 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:

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:

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:

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

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

Output has two parts:

• Heuristic library yaml (one per routed group) — name-pattern

rules covering destructive verbs, rate-limit / loop-detection

caps. Deterministic floor.

• 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.

• Get the prompt:

   sponsio plugin prompt openclaw

• Apply it to the JSON tool inventory from Step 3.4. Output a

JSON object:

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

• 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:

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

3.7 — Apply

Once the user is happy with the dry-run:

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:

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:

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

4.2 — environment profile

| Profile | Adjustment |

|---|---|

| Local dev | leave defaults |

| Staging | enable audit_after on destructive tools |

| Production | move delete_* from rate_limit 0 to assumption-gated (require explicit confirm_reconfirmed) |

| Regulated / PII | tighten the deterministic PII / dangerous-arg rules and lower their thresholds |

4.3 — known-false-positive customizations

Common cases:

| Rule | When false-positives | Customization |

|---|---|---|

| _host_openclaw "Block reads of dotenv secrets" | dotenv rotators, secret-rotation agents | disabled: true for read only (keep write) |

| incident/openclaw "navigation must not target internal hosts" | testing one's own internal app | replace with allowlist of actual internal hostnames |

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

Per-plugin libraries live in a single file:

~/.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:

• 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.

• 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.

• 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:

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:

• Library at ~/.sponsio/plugins/_host_openclaw/sponsio.yaml is

missing or wrong — re-run sponsio plugin init --force.

• 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):

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:

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:

• 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.

• 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.

• 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.