OpenClaw Tool Policy: Prove What an Agent Cannot Do

A policy that denies write, edit, and apply_patch can still permit an agent to change files. Leave exec available and the shell remains another writing interface. The configuration looks restrictive; the side effect is still possible.

That mismatch is the central problem in an OpenClaw tool policy. Tool names are filtered, but operators care about effects: changing a repository, sending a message, reaching a production API, or escaping a container. A defensible policy starts with the effect and removes every route to it. Then it proves the denied route against the exact agent and session that will run.

The decision passes through eight filters

OpenClaw resolves tool access in a defined order. The base profile establishes the initial surface. Provider, global, agent, sandbox, and subagent rules then narrow it. This matters during both design and debugging: changing the last rule in the chain cannot repair a denial introduced near the beginning.

Two rules make the pipeline easier to reason about. A deny always wins. A non-empty allowlist blocks everything it does not name. An explicit allowlist that resolves to no callable tools stops the run before the prompt is sent; OpenClaw does not quietly fall back to a text-only agent.

This is also why policy ownership should be deliberate. A deployment-wide deny belongs at the global layer. A worker-specific restriction belongs on that agent. Provider rules are useful when a model route has a different risk or compatibility profile, but they are a poor place to hide a general security invariant.

Three controls that look related but answer different questions

Confusing these controls creates fragile configurations. Denying browser removes the browser tool, but it does not stop an allowed shell from making HTTP requests. Denying filesystem helpers removes OpenClaw's direct write interfaces, but it does not make exec read-only. A writable bind mount can pierce an otherwise isolated filesystem. Mounting the Docker socket effectively hands host control to the container.

The inverse mistake is common too: an operator sees a sandbox deny list and assumes it protects every turn. Sandbox tool policy only applies when the session is actually sandboxed. General agent and global policy remains the right place for rules that must hold in direct and sandboxed runtimes.

What the inspector proved on a real host

The useful inspection command is concrete about its target:

openclaw --version
openclaw sandbox explain --agent main

On the refreshed test host, OpenClaw 2026.7.1-2 resolved agent main to the main session key, a direct runtime, sandbox mode off, and read-write workspace access. The report still printed the default sandbox allow and deny sets, plus elevated status and the relevant fix-it key paths.

That output exposes a subtle but important distinction: configured sandbox policy can exist while the inspected session runs directly. Reading the allow and deny lists without the resolved runtime line would produce the wrong security conclusion.

Run the inspector for the actual production route, not only the default agent:

openclaw sandbox explain --agent support
openclaw sandbox explain --session agent:support:telegram:group:example
openclaw sandbox explain --json

Group and channel sessions deserve special attention under non-main. The check uses the session key, not the agent ID. A group route has its own key and is treated as non-main even when it belongs to the default agent. This behavior is useful for isolating public routes, but surprising if policy was tested only in a direct main conversation.

Design from the side effect backwards

Begin with a sentence that can be tested: “this agent must not modify files,” “this agent may send only into the current conversation,” or “this worker may run tests but cannot deploy.” Tool lists come afterward.

A genuinely read-only agent

A read-only policy cannot leave a general shell available unless the operating-system or sandbox boundary makes that shell read-only. The simple version removes both filesystem mutation tools and runtime execution:

{
  tools: {
    allow: ["read", "memory_search", "memory_get", "web_search", "web_fetch"],
    deny: ["exec", "process", "write", "edit", "apply_patch"]
  }
}

If the worker needs command-line readers such as rg or a compiler, policy by tool name is no longer sufficient. Run that shell as an unprivileged identity inside a sandbox with workspaceAccess: "ro", remove dangerous binds, restrict network egress where needed, and assume any readable secret may be copied.

A communication worker

“Messaging-only” should name the allowed route and cross-context behavior, not grant every provider plugin. Start with the messaging profile or an explicit tool list, deny runtime and filesystem primitives, and disable cross-provider or cross-context sends unless the job requires them. For a public support route, pair that policy with a dedicated agent and workspace rather than sharing the operator's main identity.

A coding worker that must not deploy

This boundary is harder because test commands and deployment commands may share exec. An allowlist of shell binaries can reduce risk, but wrappers, interpreters, package scripts, credentials, and network access can reopen the route. Stronger separation uses a worker without production credentials, a non-production network boundary, protected branch rules, and a deployment action that exists only behind a separate approval-bearing agent.

Testing the refusal against the production route

A successful allowed action proves only the happy path. Every important boundary needs one harmless denied-path test. Ask a read-only worker to create a disposable marker file. Ask a support worker to attempt a cross-context send into a controlled test destination. Ask a non-deploying coder to invoke a harmless stub named like the protected operation. The expected outcome is refusal before the external effect occurs.

Capture four pieces of evidence: the exact agent and session key, the resolved inspector output, the denied request, and the policy audit event. Gateway logs include agents/tool-policy entries when a policy step removes tools or a sandbox policy blocks a call. Those entries identify the rule label, configuration key, and affected names. They are far more useful than repeatedly adding tools to whichever allowlist is closest.

After a sandbox configuration change, remember the runtime lifecycle. Existing containers keep their old settings. A frequently used agent can keep a stale runtime alive until it is explicitly recreated or pruned. Use the OpenClaw-managed command rather than deleting backend resources manually:

openclaw sandbox recreate --agent support
openclaw sandbox explain --agent support

The first command is a controlled mutation and should be planned for an idle worker. The second establishes what the next run will actually use. General tool-policy changes may reload differently from sandbox-runtime changes; verify the resolved result instead of assuming a config write changed a live container.

Failure modes that survive tidy JSON

The shell-shaped hole

write is denied, but exec is allowed with a writable workspace and useful credentials. The agent can still use shell redirection, an interpreter, Git, or an HTTP client. Fix the effect boundary, not the cosmetic list.

The inactive sandbox rule

The desired deny lives under tools.sandbox.tools, while the inspected production route resolves to direct execution. Move invariant restrictions to global or per-agent policy, then use sandbox policy as an additional gate for sandboxed turns.

The late allowlist

A per-agent rule allows a tool, but an earlier profile, provider rule, or global deny already removed it. Follow the documented filter order and the inspector's fix-it paths. Do not broaden the global surface just to make one worker pass.

The stale container

The config is correct on disk, yet a long-lived sandbox still uses its old image, mounts, or workspace mode. Recreate the scoped runtime and retest both an allowed and a denied action.

A policy is credible when the refused action is boring

The best OpenClaw tool policy is not the longest one. It gives a worker enough capability to complete one job, makes alternate routes expensive or impossible, and produces an unremarkable refusal when the agent crosses the boundary. Design from side effects, inspect the resolved route, and keep the denied-path test beside the configuration that claims to enforce it.

For the surrounding architecture, the OpenClaw multi-agent setup guide covers agent and workspace separation, while the OpenClaw security audit places tool policy inside a broader hardening process. The OpenClaw HTTP API guide explains the additional exposure gate on remote tool invocation. If operating these boundaries is work you would rather not own, GolemWorkers provides persistent hosted agents with the runtime managed for you.

The source record behind this policy model

• OpenClaw multi-agent sandbox and tools — policy precedence, per-agent overrides, empty allowlists, examples, and testing.
• Sandbox vs tool policy vs elevated — enforcement boundaries, tool groups, shell side effects, and debugging guidance.
• OpenClaw sandbox CLI — effective-policy inspection and runtime recreation behavior.
• OpenClaw policy documentation source — upstream precedence and test contract.