How to lock down which tools your agent can use and which it can’t

You gave your OpenClaw agent a lot of power when you set it up. That was the point. But after the ClawHub marketplace crisis in March 2026 (ClawHub is the main directory where people find and install add-ons for OpenClaw, called plugins), a lot of operators started asking the same question: what exactly can my agent do, and how do I tighten that? This article walks through the three config layers that control which tools your agent can call, in the order you should set them, starting with the one that matters most.

What “locking down tools” actually means

Your OpenClaw agent works by calling tools. Each tool is a specific action: read a file, send a message, run a shell command, open a browser, schedule a job. Every tool call is something your agent does on your machine or your accounts, on your behalf.

When you first set up OpenClaw, your agent has access to everything: reading files, sending messages, running shell commands, spawning processes. The config does not distinguish between low-risk and high-risk tools. Your agent calls whatever it decides the situation needs.

Locking down tools means telling OpenClaw exactly which tools your agent is allowed to call, and under what conditions. Three layers handle this, and they stack:

Layer 1: Exec security Controls specifically how the exec tool works. This layer implements the principle of least privilege at the command execution level. The exec tool lets your agent run shell commands. It is the highest-blast-radius tool in OpenClaw. A misconfigured exec policy is how malicious plugins do the most damage.

Layer 2: Tool allow and deny lists Controls which tools your agent can call at all. Allow lists restrict access to only named tools. Deny lists block specific tools completely. These apply across your whole setup.

Layer 3: Per-agent overrides If you run more than one agent (a main agent, a research agent, a cron worker), each one can have its own tool rules. Your research agent does not need exec. Your cron worker does not need browser. Per-agent rules let you give each agent exactly what it needs and nothing more.

Start with Layer 1 (exec security). That is where the risk is highest. If you want to first see what your agent currently has access to before restricting it, read the audit guide first. Add the others once it is stable.

Before you touch anything: run the audit

OpenClaw has a built-in security auditor that checks your current setup for common problems. Run it before making any changes. It checks exec policy exposure, tool surfaces, plugin registrations, and gateway auth problems. It does not make any changes. It only reports.

Run openclaw security audit and show me the output. I want to see every finding before I make any changes.

Your agent will run the audit and paste back the results. Read through them before continuing. The audit flags findings as critical, warn, or info. Critical findings are things that need fixing now. Warn findings are worth addressing. Info findings are notes about your current setup. A clean audit with no critical or warn findings means your setup is already in good shape. Most fresh installs from the default guide will have at least one critical finding (exec security set to full). If yours is clean, your previous setup work is the reason.

After reading the audit output, continue to Layer 1 below. The audit tells you where you stand. The rest of this guide tells you how to fix it. Note: the audit also has a --fix flag (openclaw security audit --fix) that can automatically apply some lower-risk findings. Read the audit output and decide what to fix manually before using this flag. Do not use --fix as a substitute for understanding the findings. Read the output first, then decide which fixes you want to apply manually versus automatically.

Layer 1: The exec tool and why it matters most

The exec tool is the one that lets your OpenClaw agent run shell commands. Shell commands are instructions that run directly on your machine or server, things like “install this package,” “delete this file,” “start this process.” When the exec tool is unrestricted, your agent can run any shell command it decides is appropriate.

Why this matters to you right now: if you installed any plugins before the ClawHub crisis in March 2026, and your exec policy is still set to “full” (the default), any of those plugins could be calling exec without restriction. That includes plugins you no longer use and may have forgotten about. The audit step above will tell you if this is your situation. Most operators who set up OpenClaw from a guide and never revisited the security config are in exactly this position.

That is a lot of power. Under normal operation with a trustworthy agent, it is fine. That power is why you set up OpenClaw. But if a malicious plugin has been installed (and in March 2026, 800+ ClawHub plugins were found to be malicious), the exec surface is the primary way that plugin can cause real damage. A plugin that exploits exec access can read your files, exfiltrate your credentials, install other software, or overwrite things you need. Restricting exec with an allowlist limits what your agent can call directly through the OpenClaw tool interface. Separately, a malicious plugin’s internal handler code can bypass this entirely by making subprocess calls inside its own handler. That distinction comes up in Layer 2 below. For now, the focus is on restricting your agent’s direct exec calls, which is the majority of exec risk in a non-malicious setup.

There are three settings that control exec behavior. Understanding all three matters:

tools.exec.security is the master switch. It has three possible values:

• “full”: Your agent can run any shell command without asking. This is the default and the riskiest setting.
• “allowlist”: Your agent can only run commands that appear on an approved list. Anything not on the list gets blocked.
• “deny”: The exec tool is completely disabled. Your agent cannot run any shell commands.

tools.exec.ask controls whether your agent asks for approval before running a command. It has three values:

• “off”: No approval required. Commands run immediately if they are on the allowlist (or if security is “full”).
• “on-miss”: Your agent asks for approval for any command not on the allowlist. Commands already on the allowlist run without asking.
• “always”: Every exec command requires approval, even ones on the allowlist.

tools.execAllowlist is the list of approved commands when security is set to “allowlist”. This is an array of exact command strings your agent is allowed to run.

What is my current exec security setting? Show me the values of tools.exec.security and tools.exec.ask in my config.

Your agent will read your config and report the current values. If tools.exec.security is “full” and you have any plugins installed (especially any installed from ClawHub before March 2026), you should change this.

The recommended starting setting for most operators is security: "allowlist" with ask: "on-miss". With this combination, commands on your allowlist run without any prompt. Commands your agent tries to run that are NOT on your allowlist will trigger an approval request. This is useful while you are building out your allowlist, because you see what your agent is trying to run before adding it. Once your allowlist is stable, consider switching to ask: "off", especially on headless setups (see the headless note in Step 3).

Set tools.exec.security to “allowlist” and tools.exec.ask to “on-miss” in my config, then restart OpenClaw.

After OpenClaw restarts, your agent will confirm the change is active. The next time your agent tries to run a command that is not on your allowlist (which you will build in Step 3), it will send you an approval prompt in your chat window instead of running it automatically. That is the expected behavior with “on-miss” while your allowlist is being built.

"exec": {
  "security": "allowlist",
  "ask": "on-miss"
}

Your exec allowlist is the list of shell commands your agent is approved to run without asking. If your agent runs scheduled tasks, maintenance scripts, or automation that uses exec, those commands need to be on this list.

Show me all the exec commands my cron jobs and scheduled tasks use. I want to build an allowlist from that.

Once you have the list of commands your agent legitimately needs, add them:

Add these commands to my tools.execAllowlist and restart after saving: git add -A, python3 /home/node/scripts/daily.py, ollama list. [Replace with your actual command list, one per line or comma-separated.]

If you run OpenClaw on a VPS (a virtual private server, a rented computer in a data center that is always on and accessible over the internet) or any server with no active chat channel most of the time, there is a problem with “on-miss” approval that will silently break your cron jobs: when exec needs approval and there is nobody connected to receive the approval prompt, it waits. Indefinitely. Your cron job stalls with no error message.

On headless setups (VPS with no always-on chat connection), the right setting once your allowlist is stable is ask: "off", not ask: "on-miss". That way, commands on your allowlist run without requiring a human to approve them, and commands not on your allowlist are simply blocked (which is what you want).

I run OpenClaw on a server. Set tools.exec.ask to “off” now that my allowlist is built. Restart after saving.

Layer 2: Tool allow and deny lists

Beyond the exec tool, OpenClaw lets you control which tools your agent can call at all. This is separate from exec security. It applies to every tool in your setup.

Skip this layer and your agent keeps access to everything registered: browser control, node commands (phone, camera, screen), session management, gateway config changes, and any plugin tools. On a single-user personal setup, that is manageable. In any setup where other people can message your agent (a shared Slack workspace, a Discord server, a group Telegram chat), it is not. Anyone who can send a message can trigger any of those tools.

There are two ways to restrict tools:

tools.allow is a list of tools your agent is allowed to call. If this list has anything in it, your agent can only call tools on this list. Everything else is blocked. This is called an allowlist (or whitelist). Start from zero and add what you need.

tools.deny is a list of tools your agent is blocked from calling. These are always blocked, even if they appear in the allow list. Deny always wins. This is called a denylist (or blacklist). Start from everything and remove what you want to allow.

Both work. Most operators start with deny: block what you know you do not need. The allow approach is more thorough. You list every tool explicitly, but it requires more upfront inventory work. Both are valid. Deny is faster to get right on day one.

What tools do I currently have available? List every tool name and what it does in one sentence each.

This gives you a full inventory of what your agent can call. Review it. Anything that surprises you is worth investigating.

OpenClaw supports group shorthand names you can use in allow and deny lists instead of listing individual tool names. These groups are:

• group:runtime: exec, bash, process (shell commands and process management)
• group:fs: read, write, edit, apply_patch (file system access)
• group:messaging: message (send messages to channels)
• group:ui: browser, canvas (browser control and canvas)
• group:sessions: session management tools
• group:memory: memory search and retrieval tools
• group:automation: cron, gateway (scheduled tasks and gateway control)
• group:nodes: paired node actions (phone, camera, screen)
• group:openclaw: all built-in OpenClaw tools

If you know your agent does not need certain tools, deny them. A research agent that only reads web pages and writes summaries does not need browser control, exec, or node access.

Add “browser” and “nodes” to my tools.deny list. I do not want my agent to be able to control a browser or access paired devices. Restart after saving.

This is why the security audit matters, and why reviewing plugins before installing them matters. The full access audit guide covers how to review what plugins you have and what they registered.

Layer 3: Per-agent tool policies

If you only run one agent, Layer 2 covers everything. If you run multiple agents: a main interactive agent, a research agent, scheduled cron workers, or subagents for specific tasks. Each one can have its own tool rules.

Per-agent tool rules work the same way as global rules: each agent can have its own allow list, deny list, or both. The agent-level rules override the global rules for that specific agent. Deny still always wins, even at the agent level.

A cron worker that runs a nightly summary does not need browser access, node access, or the ability to send messages to arbitrary channels. Giving it those tools is unnecessary risk. A research agent that reads web pages and writes files does not need exec. Giving it exec is unnecessary risk.

The principle is: each agent should have exactly the tools it needs for its job, and nothing more. This is called least privilege, and it is the most effective thing you can do to limit blast radius if something goes wrong.

Show me all the agents configured in my setup. List each one by name and tell me what tools each currently has access to.

Once you know your agents, you can lock each one down individually. Tell your agent what you want for each one:

For my cron agent, deny exec, browser, nodes, and sessions tools. It only needs to read files and send messages. Apply that in the per-agent config for the cron agent and restart.

For my research agent, set an allow list that includes only: read, web_search, web_fetch, memory_recall, memory_store, and message. Nothing else. Apply the per-agent allow list and restart.

{
  "id": "cron",
  "tools": {
    "deny": ["exec", "browser", "nodes", "group:sessions"]
  }
}

{
  "id": "research",
  "tools": {
    "allow": ["read", "web_search", "web_fetch", "memory_recall", "memory_store", "message"]
  }
}

Verifying your changes

After any tool policy change, confirm it took effect. Do not assume the restart worked.

Run openclaw security audit again and show me the results. I want to see if any of the previous critical findings are still present.

Also confirm the tool list matches what you intended:

List every tool I currently have access to. For each one blocked by my deny list or allow list, say so explicitly.

OpenClaw includes a sandbox explain command that shows your effective tool policy for the current session:

Run “openclaw sandbox explain” and show me the output. I want to see my effective tool policy and sandbox mode.

What the ClawHub crisis means for your setup right now

In March 2026, over 800 plugins in the ClawHub marketplace were found to be malicious. This is roughly 20% of all listed plugins at the time. These plugins primarily exploited two surfaces: exec access and filesystem write access. A plugin with access to exec and no allowlist restrictions could run arbitrary shell commands the moment it was triggered.

If you installed any ClawHub plugins before March 2026, the right first step is not to configure tool policy. Audit what you have installed first. what you have installed. Tool policy helps, but as covered in Layer 2 above, it does not fully protect you against a malicious plugin that is already installed. The full audit guide at how to audit what your agent has access to covers the plugin audit process in detail.

After auditing and removing any suspicious plugins, then apply the tool policy layers in this guide. The order matters: remove the threat first, then harden the perimeter.

If you have never installed any ClawHub plugins, or if you installed them before the crisis and have already verified them, proceed directly with the tool policy hardening in this guide.

A realistic locked-down setup

Here is what a sensibly locked-down configuration looks like in practice. This is not a template to copy. It is an example to understand. Your actual setup depends on what your agents do.

Global exec policy (applies to all agents): Security set to “allowlist”. Ask set to “off” for headless/VPS setups, “on-miss” for interactive setups with an active chat connection. Allowlist contains only the specific commands your legitimate cron jobs and automation actually run.

Global tool deny: Any tool surface you know your main agent does not need. If you do not use paired devices, deny group:nodes. If you do not use browser automation, deny browser and canvas.

Per-agent rules for non-main agents: Each cron worker, research agent, or subagent has a restricted tool set. A cron worker that only reads files and posts summaries does not have exec, browser, or node access.

To see this applied to your setup specifically, ask your agent to map your current configuration against this pattern:

Compare my current tool configuration to a least-privilege setup. Tell me which tools each of my agents has that it probably does not need for its actual job. Show me the specific config changes you would recommend.

Platform notes: what changes on Windows, Mac, and headless servers

Most of this guide applies the same way regardless of where you run OpenClaw. A few things work differently depending on your platform.

On Windows with WSL2: WSL2 (Windows Subsystem for Linux) is a feature built into Windows 10 and 11 that lets you run a full Linux environment alongside Windows. Many OpenClaw users on Windows run it inside WSL2 because OpenClaw is primarily designed for Linux. If your OpenClaw runs inside WSL2, your config file lives at a Linux path inside the WSL environment, not on your Windows filesystem. The path is still ~/.openclaw/openclaw.json, but “home” is your WSL2 user’s home directory. Your agent can read and update this file normally. If you want to find it from Windows Explorer, the WSL2 filesystem is accessible from the address bar as \\wsl$\Ubuntu\home\yourusername\.openclaw\openclaw.json.

Exec allowlist entries on WSL2 need to use Linux-style paths, not Windows paths. /usr/bin/python3 is correct. C:\Python311\python.exe is not : that is a Windows path and will not resolve inside WSL2.

On macOS: OpenClaw on macOS typically runs as a regular process (not a system service). The config file is at ~/.openclaw/openclaw.json in your user’s home directory. When you restart OpenClaw after making config changes, quit the app and reopen it, or use the system tray icon if available. If you run OpenClaw as a gateway process from the command line, stop the process (Ctrl+C in the terminal window where it is running) and start it again with the same command you used originally. There is no systemctl on macOS. If your agent says to run systemctl restart openclaw, that will not work on a Mac. The equivalent is stopping and starting the OpenClaw process manually.

Ollama on macOS sometimes installs to a non-standard path (/usr/local/bin/ollama instead of the default). If exec allowlist entries involving Ollama commands are failing, ask your agent to verify where Ollama is installed and update the allowlist entries to use the full path.

On a headless VPS (Linux server with no desktop): The headless setup has one important difference from interactive setups: there is no always-on chat connection. This matters specifically for exec approval. If you set ask: "on-miss", commands not on your allowlist will send an approval request. On an interactive setup, that request arrives in your chat window and you approve it in seconds. On a headless server with no connected chat session, that request waits. It does not time out. The exec call blocks. Your cron job stalls with no visible error.

The correct setting for headless VPS setups, once your allowlist is stable and tested, is ask: "off". Commands on the allowlist run. Commands not on the allowlist are blocked silently. No approval prompts. This is the right behavior for unattended operation.

The three most common audit findings and how to fix them

When you run openclaw security audit, the output groups findings by severity. Here are the three most common findings operators encounter and what to do with each one.

Finding: “exec security is set to full”

This is the most common critical finding. It means your agent can run any shell command without restrictions. The fix is Layer 1 in this guide: switch to allowlist mode. Before switching, build your allowlist from your current cron jobs and automation (ask your agent to list what exec commands it has run in the last 30 days). Then switch to allowlist mode. Do not switch first and build the allowlist after, or your existing automation will break.

What exec commands have you run in the last 30 days? I need to build an allowlist before switching to allowlist mode.

If your agent says it does not have access to that history, check your cron job list instead: ask “Show me all my configured cron jobs and what commands each one runs.” That gives you the same information from the config rather than the history.

Finding: “plugin tools reachable under permissive policy”

This finding means you have one or more plugins installed and your global tool policy is permissive enough that those plugins’ registered tools are reachable by your agent. The audit is flagging this because permissive plugin tool access was the primary attack vector in the ClawHub crisis.

The fix depends on whether the plugins are ones you want. If you want to keep a plugin, add its tool name to an explicit allow list so it is a deliberate choice rather than a default. If you do not recognize a plugin or did not intentionally install it, remove it before making any tool policy changes.

List all plugins currently installed and the tools each one has registered. I want to see every plugin tool name and what it does.

Finding: “open groups with runtime or filesystem tools enabled”

This finding means you have a group channel (a channel where multiple people can message your agent) and that channel’s agents have access to exec or filesystem write tools. This is high-risk because anyone who can send a message to that group channel can trigger those tools.

The fix is either: restrict the channel so only trusted senders can message your agent there, or restrict the tool access for sessions coming from that channel. The group policy controls in your channel config handle the first. Per-agent tool rules handle the second.

Show me which channels have open group access and which tools are available in those channels. I want to assess whether any of them have exec or file write access that they should not have.

After you lock down

Tool policy is not a one-time fix. It needs a check whenever something changes in your setup.

Your tool policy config lives in openclaw.json and survives OpenClaw updates. Updating the app does not reset your exec security, allow lists, or deny lists. You do still need to re-run the audit after updates because new versions can introduce new tool surfaces or change how existing tools behave.

Run the security audit after any of the following:

• Installing a new plugin or skill
• Changing your OpenClaw version
• Adding a new agent or cron job
• Adding a new chat channel or group
• Rotating credentials or API keys
• Updating OpenClaw to a new version

Each of these can introduce new tool surfaces or change which tools are reachable. A plugin update can register new tools. A new channel with open group access can expose tools to senders you did not intend to have that access. Catching these on install is much easier than diagnosing them after something goes wrong.

Run openclaw security audit –deep and show me the full output. I want to check if anything has changed since I last hardened my setup.

The --deep flag runs additional checks that the standard audit skips because they take longer. It is worth running monthly, or after any significant setup change.

Frequently asked questions

No. Tool deny lists control what your agent can call by name through the OpenClaw tool interface. A plugin’s handler code runs when the tool is triggered. What that code does internally is not controlled by tool policy. If a plugin’s handler makes subprocess calls or network requests inside its own code, deny lists do not stop that. The only way to block a plugin’s internal behavior is to not have the plugin installed. This is the most important limitation of tool policy to understand.

tools.deny keeps the tool registered in your setup but prevents your agent from calling it. The tool still exists. It is just blocked at the policy level. Removing a tool (uninstalling a plugin) removes it entirely. Deny is useful for temporarily restricting access or for applying different rules per agent. Uninstalling is more thorough and removes the plugin’s handler code from your system entirely.

Plugin tools are registered under specific names when the plugin is installed. If you set tools.allow and do not include those plugin tool names, your agent cannot call them. They are blocked by the allow list. This can silently break skill and plugin functionality. After setting an allow list, ask your agent to list available tools and confirm the ones you need are still present.

An empty allow list ("allow": []) means your agent has no tools at all. It cannot read files, send messages, call exec, or do anything. This will break everything immediately. If you set an allow list, it must include every tool your agent needs. If you accidentally set an empty allow list and your agent stops responding, revert the config by opening openclaw.json manually, removing the allow field, and restarting. Your agent will regain its full tool access.

Yes. If both are set, allow establishes the permitted set and deny removes specific tools from that set. Deny always wins. A tool that is in both allow and deny is blocked. In practice, most operators use one or the other at each level, not both.

The cron job is trying to run a command that is not on your execAllowlist. Ask your agent: “What exec command is my cron job trying to run? Is it blocked by my current allowlist?” Once you have the command, add it to your allowlist and the job will run. If you set ask to “on-miss” and the job is running on a headless VPS with no active chat channel, the approval prompt is queuing silently. Switch ask to “off” once your allowlist is stable.

Global tool policy (tools.allow and tools.deny) applies to all sessions by default. Per-agent rules apply to sessions running under that agent. If you have sandbox.mode set to “non-main,” non-main sessions (group channels, secondary agents) run in a sandboxed environment which has its own tool policy layer on top of the global one. Use “openclaw sandbox explain” to see the effective policy for any specific session.

Global deny blocks the tool for all agents, including those with a per-agent allow list. If you put “exec” in tools.deny at the global level, no agent can call exec. Not even agents that have “exec” in their per-agent allow list. If you want to deny exec for most agents but allow it for one specific agent, the approach is: do not put exec in the global deny. Instead, put exec in the deny list for each individual agent that should not have it, and leave it available for the one that should.

OpenClaw’s built-in features (heartbeat, compaction, cron jobs) use some tools internally. If you deny a tool that a core feature depends on, that feature will stop working, often without a clear error message. Before making broad deny changes, ask your agent which tools your current cron jobs, skills, and automation actually call, skills, and automation. The security audit also flags cases where your current tool policy conflicts with configured features.

Only if your agent genuinely does not need to run shell commands at all. If you have any automation, cron jobs, or skills that use exec, setting security to “deny” breaks them immediately. “Allowlist” is the right setting for most operators. It restricts exec to approved commands rather than removing it entirely. Use “deny” for agents that should never run commands (a read-only research agent, a messaging-only bot).

Audit them before tightening tool policy. Tool policy helps limit what your agent can call directly. It does not protect you against a malicious plugin’s internal code. The correct order is: audit installed plugins first (remove any you cannot verify), then apply the tool policy hardening in this guide. Doing it in the wrong order gives you a false sense of security. The full plugin audit process is in the access audit guide.