before_tool_call -- Calls POST /governance/verify for high-risk tools. Returns ALLOW, CLAMP, or DENY with a cryptographic release token.
after_tool_call -- Calls POST /governance/attest after execution, building a hash-chained provenance record for the agent.

The plugin also registers two callable tools:

kevros_verify -- Verify any action against governance policy on demand.
kevros_passport -- Look up an agent's trust passport (score, tier, badges).

Installation

npm install @kevros/openclaw-plugin

Configuration

Add to your OpenClaw configuration:

{
  "plugins": [
    {
      "name": "kevros-governance",
      "config": {
        "gatewayUrl": "https://governance.taskhawktech.com",
        "apiKey": "your-api-key",
        "agentId": "my-agent",
        "mode": "enforce",
        "highRiskTools": ["bash", "computer", "terminal", "exec", "write_file", "edit_file"],
        "autoAttest": true
      }
    }
  ]
}

Configuration options

Option	Type	Default	Description
`gatewayUrl`	`string`	`https://governance.taskhawktech.com`	Kevros gateway base URL
`apiKey`	`string`	(auto-provisions)	API key. If not set, the plugin auto-signs up for a free tier key (1,000 calls/month)
`agentId`	`string`	hostname	Agent identifier for governance tracking
`mode`	`string`	`enforce`	`enforce` (fail-closed), `advisory` (log-only), or `deny` (block all)
`highRiskTools`	`string[]`	`["bash", "computer", ...]`	Tool names requiring governance verification
`autoAttest`	`boolean`	`true`	Automatically attest tool executions after completion

Enforcement modes

`enforce` (default)

Fail-closed. If the gateway returns DENY, the tool call is blocked. If the gateway is unreachable, the tool call is blocked. This is the recommended mode for production.

`advisory`

Fail-open. All decisions are logged but never enforced. Use this to evaluate governance impact before switching to enforce.

`deny`

Hard block. All high-risk tool calls are unconditionally blocked regardless of gateway state. Use this as a kill-switch.

Auto-provisioning

If no apiKey is configured, the plugin automatically calls POST /signup on first use to provision a free-tier API key:

1,000 governance calls per month
10 requests per minute rate limit
No credit card or email required

The key is cached in memory for the duration of the session. For persistent usage, set the apiKey in your configuration after signup.

How verification works

When a high-risk tool is called:

Agent calls bash("rm -rf /tmp/data")
    |
    v
before_tool_call hook fires
    |
    v
POST /governance/verify
  action_type: "tool:bash"
  action_payload: { tool: "bash", input: { command: "rm -rf /tmp/data" } }
    |
    v
Gateway returns: { decision: "ALLOW", release_token: "abc123...", epoch: 42 }
    |
    v
Tool executes
    |
    v
after_tool_call hook fires
    |
    v
POST /governance/attest
  action_description: "Executed tool: bash"
  action_payload: { tool: "bash", input: {...}, output_summary: "...", release_token: "abc123..." }
    |
    v
Hash-chained provenance record created (epoch 43)

Using the tools

The plugin registers two tools that agents can call directly:

kevros_verify

kevros_verify({
  action_type: "api_call",
  action_payload: { endpoint: "/users", method: "DELETE", user_id: "123" }
})

Returns the verification decision, reason, and release token.

kevros_passport

kevros_passport({ agent_id: "some-agent" })

Returns trust score, tier, badges, verification/attestation counts, and chain integrity status.

Requirements

Node.js 18+ (uses native fetch)
Zero runtime dependencies

Building from source

npm install
npm run build

License

MIT

README.md

@kevros/openclaw-plugin

What it does