How OpenClaw Tool Policy Layers Interact—and How to Prove Which Policy Won

Published June 11, 2026 · OpenClawBlog Team · Sources checked September 13, 2026.

An OpenClaw operator sees a familiar symptom: one agent can call a tool, another cannot; an /elevated instruction changes nothing; a channel session behaves differently from a terminal session. It is tempting to search for one allow or deny setting.

The current documentation describes a chain instead. Profiles, provider rules, global policy, agent policy, sandbox policy, and subagent policy can all affect the tool catalog. A later layer can restrict an earlier result, but it cannot restore a tool that an earlier layer removed. The useful question is therefore not only “What did I configure?” It is “Which route, provider, session, and policy snapshot produced this turn?” The OpenClaw tools overview says that policy is applied before the model call, so a removed tool schema is not sent to the model.

The short answer is to collect four pieces of evidence: the exact routed session, the effective policy view, the relevant Gateway log entry, and a harmless runtime challenge. A configuration file alone proves intent. A failed call alone does not identify the cause.

What each control actually decides

OpenClaw separates three controls that are easy to collapse into one mental model. The official sandbox and tool policy guide describes them this way:

These controls meet at different points in the execution path. A sandboxed session can have a tool removed by the sandbox tool gate. An allowed exec tool can then be stopped by host policy. An approval can be required after the tool has already survived visibility checks. The exec approvals documentation describes approvals as a guardrail that stacks on top of tool policy and elevated gating.

That distinction matters for file safety. Tool policy matches tool names. If exec remains available, denying write, edit, or apply_patch does not make shell commands read-only. The sandbox and host execution policy must carry that boundary.

The tool filtering order

The multi-agent documentation gives a more precise order than the shorter conceptual guide. For a normal agent run, inspect these layers in sequence:

1. The base tool profile, such as tools.profile or an agent profile.
2. The provider tool profile for the selected provider or provider/model.
3. The global tools.allow and tools.deny policy.
4. The provider-specific allow and deny policy.
5. The agent-specific allow and deny policy.
6. The agent's provider-specific policy.
7. The sandbox tool policy, when the session is sandboxed.
8. The subagent policy, when the run is delegated.

This sequence comes from OpenClaw's multi-agent sandbox and tools reference. It is not a claim that every other access control in the product is absent. Channel permissions, sender identity, plugin availability, and runtime selection can prevent a request from reaching this catalog at all.

There are three rules to keep in view. First, deny wins. Second, a non-empty allowlist treats unlisted tools as blocked. Third, every later restrictive layer intersects with the result instead of granting back an earlier denial. An agent-level allow for exec cannot undo a global deny for exec.

Scope inheritance has its own trap. An agent-specific tool profile overrides the global profile. An agent-specific sandbox tool block replaces the global sandbox tool block for that agent; it is not simply a union of both objects. Group shorthands also expand into several tool names. For example, group:runtime includes exec, process, and code execution. A log may therefore refer to a group rule while the failed tool is a concrete name.

If an explicit allowlist leaves no callable tools, OpenClaw stops before submitting the prompt to the model. That is a useful fail-closed behavior, but it changes the evidence you should expect: there may be no tool-call refusal from the model because the model never received the tool catalog.

Why the same file can produce different results

Start with routing. A message can bind to a different agent than the one you inspected. The session key also matters. In non-main sandbox mode, OpenClaw checks whether the session key is the main session key, not whether the agent is called “main”. Group and channel sessions have their own keys and are treated as non-main. The sandbox guide calls this a common surprise.

Next check the selected provider and model. Provider policy keys can target a provider such as anthropic or a provider/model pair such as openai/gpt-5.4. Changing models can therefore change the effective tool catalog without changing the agent's visible configuration. The tool policy configuration reference also documents requester-scoped toolsBySender rules. These match verified channel or sender identities, not text supplied inside the message.

Finally, separate tool visibility from host execution. The tools.exec settings do not grant access to the exec tool. Once exec is visible, its host, security, ask, allowlist, sandbox, elevated, and approval state can still decide whether the command runs.

Before you test

Use a disposable workspace and a command or tool with no external side effect. Record the exact Gateway target, agent ID, session key, selected provider/model, and whether the run is a child session. Keep a clean log window and save configuration snapshots without credentials.

Remote diagnostics also need the right scope. The config validation and probes guide notes that a missing operator.read scope can allow connection while limiting detailed diagnostics. A connection is not proof that the CLI inspected the Gateway you intended.

A proof procedure for the winning layer

1. Resolve the route and session first

Run the documented binding and sandbox inspectors against the exact agent or session:

openclaw agents list --bindings
openclaw sandbox explain --agent AGENT_ID --json
openclaw sandbox explain --session SESSION_KEY --json

The inspector reports effective sandbox mode, scope, workspace access, whether the session is currently sandboxed, sandbox tool allow and deny state, the source of that state, and elevated gates with fix-it paths. Use the session form for a channel or group conversation. Do not infer the session from the agent name.

This output proves runtime sandbox resolution, not every global and provider rule. Pair it with narrow configuration reads such as openclaw config get agents.entries.AGENT_ID and openclaw config validate. Treat those as authored configuration evidence, not as proof that a stale or rejected edit is active.

2. Walk the policy chain for the missing tool

Pick one concrete tool, such as exec, and check each layer in the published order. Expand group entries before comparing them. Note whether the selected provider matches a provider/model rule. Then record the first layer that removes the tool.

Calling that first removal the “winning policy” is an operational convention, not a separate OpenClaw term. It is useful because it tells the operator which boundary must change. If a global deny removed exec, do not spend time changing /exec, elevated mode, or host approvals. Those stages are later and cannot restore the tool.

3. Inspect host decisions only when the tool survived

For a visible exec tool, inspect the Gateway or node host policy:

openclaw approvals get --gateway
openclaw approvals get --node NODE_ID
openclaw exec-policy show

The approvals command shows requested policy, host policy sources, and the effective result. The merged view is local to the machine. Per-session /exec overrides are not included, so inspect /exec inside the relevant session as well. Outside documented full-permission exceptions, the stricter result of OpenClaw configuration and the host approvals file applies. If no approval UI is reachable, the default fallback is deny.

This is where an operator can distinguish “the tool was invisible” from “the tool was visible but the host rejected the command”. The two failures may look similar in chat, but they require different fixes.

4. Correlate the decision with Gateway logs

Use a bounded log capture:

openclaw logs --json --limit 500
openclaw logs --follow

The sandbox and tool policy guide documents agents/tool-policy entries when a policy step removes tools or a sandbox policy blocks a call. Those entries can include the rule label, configuration key, sandbox mode, and affected tool names. The logs reference documents JSON line output and bounded line and byte limits.

Do not treat every audit record as a full explanation. The policy-as-code documentation says routine policy-filter diagnostics can name the matched rule, while the durable audit ledger records blocked outcomes separately without necessarily retaining that matched rule. Preserve both the debug event and the effective-policy output when the distinction matters.

5. Run the same harmless challenge

Repeat one no-side-effect request with the same agent, provider, and session route. Change only one policy layer between runs. The expected result is not a benchmark; it is a boundary check. If the tool disappears, the model should not receive its schema. If the tool remains visible but execution fails, inspect sandbox placement and host approvals. Mark the result as passed, unverified, or blocked.

A small test matrix

The following matrix is a proposed test plan, not a report of a local OpenClaw run.

Failure paths and limits

A valid configuration is not the same as an active configuration. OpenClaw can skip an invalid hot-reload edit and keep the previous runtime configuration. Run openclaw config validate, inspect Gateway logs, then restart and repeat the effective-policy check when a change does not appear.

A clean openclaw policy check is useful for conformance. The Policy plugin reference says it can emit policy, evidence, findings, and attestation hashes. It also says the check is configuration-level: it does not inspect runtime approval state, credentials, or secret values. It cannot prove which host policy answered a particular call.

Do not use a successful connection as proof of the correct target. With multiple reachable Gateways, run openclaw gateway probe --json and inspect the reported target identity and diagnostic status. The probes guide describes separate cases for a reachable Gateway with limited scope and a reachable Gateway whose follow-up diagnostics failed.

There is also a security limit to the whole exercise. Tool policy can prove that a named tool was removed. It cannot prove that an allowed tool is harmless. An allowed shell command may still write files, reach a network, or invoke another program. Exec approvals reduce accidental execution risk, but the official documentation does not present them as user isolation or a read-only boundary.

For the audit record, write the result precisely: “exec was removed by the agent policy for AGENT_ID” is stronger than “exec failed”. If it remained visible and the node rejected the command, record that later decision instead. If the route, effective output, or matching log is missing, leave the cause unverified.

Sources

All sources were accessed on September 13, 2026. The documentation pages did not expose publication dates when checked.

• OpenClaw tools overview
• Sandbox vs tool policy vs elevated
• Multi-agent sandbox and tools
• Configuration: tool policy
• Exec approvals
• Logs CLI reference
• Config validation and probes
• Policy plugin reference