PR #55053: feat(guardrails): pluggable GuardrailProvider interface for tool authorization

• Repository: openclaw/openclaw
• Author: nickkingu
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/55053

Description (problem / solution / changelog)

Summary

• Problem: OpenClaw has exec approvals for shell commands, but no general-purpose authorization for other tools -- file writes, browser actions, messaging, MCP tools, git operations. An agent can write to ~/.ssh/authorized_keys or send messages to arbitrary recipients with no policy check.
• Why it matters: this has been requested across 10+ issues spanning the past few months (listed below). Security-conscious deployments have no standard way to enforce tool-level authorization. Every solution is ad-hoc and incompatible.
• What changed: added a pluggable GuardrailProvider type as a core service (not a plugin). Ships with a built-in AllowlistProvider. Runs before plugin hooks -- cannot be bypassed. Zero impact when not configured.
• What did NOT change (scope boundary): no changes to the steerable agent loop, exec approvals, plugin system, or any existing tool. No bundled external providers.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #46441
• Related #22068 (tool:before/tool:after internal hooks -- this PR builds on that infrastructure)
• This PR fixes a bug or regression

Community issues this unblocks:

• #513 -- Path-based access control rules
• #1546 -- Per-group tool policies
• #6823 -- Execution guardrails (agent deleted OAuth credentials)
• #8081 -- Multi-user RBAC
• #12202 -- Per-agent file path access control
• #12617 -- Model output context to before_tool_call
• #23900 -- Self-preservation guardrails for agents
• #30504 -- Middleware hooks for agent protocol enforcement
• #48304 -- Tool-level authorization policy
• #48503 -- Enrich before_tool_call event
• #49183 -- Per-session tool policies
• #49342 -- Pre-tool execution hooks / middleware API
• #52845 -- Per-agent exec security mode

Root Cause / Regression History (if applicable)

N/A

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: test/guardrails/builtin.test.ts, test/guardrails/index.test.ts
• Scenario the test should lock in: AllowlistProvider allow/deny logic, evaluateGuardrail fail-closed/fail-open behavior, loadGuardrailProvider builtin and error paths.
• Why this is the smallest reliable guardrail: the interface is a new subsystem with no existing callers, so unit tests at the provider and evaluation boundary cover the contract without broader integration setup.
• Existing test that already covers this (if any): none -- this is a new subsystem.
• If no new test is added, why not: N/A -- new tests are included.

User-visible / Behavior Changes

When guardrails.enabled is true in config.yaml, every tool call is evaluated against the configured provider before execution. If the provider denies, the tool is blocked and the agent sees a denial reason. When not configured, behavior is identical to before this PR.

Security Impact (required)

• New permissions/capabilities? Yes
• Secrets/tokens handling changed? No
• New/changed network calls? No (AllowlistProvider is local-only; external providers may make calls but that is provider-specific)
• Command/tool execution surface changed? Yes
• Data access scope changed? No
• If any Yes, explain risk and mitigation: this adds a pre-execution authorization gate for all tool calls. The gate is opt-in (disabled by default). When enabled, it runs before plugin hooks as a core service, so it cannot be bypassed by disabling a plugin. failClosed defaults to true, meaning provider errors block tool calls rather than allowing them. The AllowlistProvider has zero external dependencies.

Repro and Verification

Environment

• OS: macOS
• Runtime/container: Node 22 + pnpm workspace

Steps to verify

1. Add to config.yaml:

guardrails:
  enabled: true
  provider:
    use: "builtin:allowlist"
    config:
      deniedTools:
        - "exec"

1. Start OpenClaw
2. Ask agent: "Run echo hello using exec"
3. Expected: agent sees "Guardrail (allowlist): 'exec' is in the denied list"
4. Remove "exec" from deniedTools, restart
5. Same request now executes normally

Tests

pnpm test test/guardrails/

Changed files

• docs/docs.json (modified, +1/-0)
• docs/tools/guardrails.md (added, +307/-0)
• src/agents/pi-tools.before-tool-call.ts (modified, +25/-0)
• src/config/types.openclaw.ts (modified, +2/-0)
• src/config/zod-schema.guardrails.ts (added, +21/-0)
• src/config/zod-schema.ts (modified, +2/-0)
• src/gateway/server-plugin-bootstrap.ts (modified, +2/-0)
• src/guardrails/builtin.ts (added, +39/-0)
• src/guardrails/index.ts (added, +88/-0)
• src/guardrails/init.ts (added, +53/-0)
• src/guardrails/types.ts (added, +59/-0)
• test/guardrails/builtin.test.ts (added, +59/-0)
• test/guardrails/index.test.ts (added, +105/-0)