OpenClaw Tool Allow and Deny Lists: Build Each Agent's List From a Week of Logs

Most agents I see have access to every tool on the gateway, because nobody wrote a list. The morning briefing agent can run shell commands. The research agent can push to GitHub. Nothing bad has happened yet, which is the whole argument for leaving it.

OpenClaw lets you scope tools per agent with an allow list and a deny list inside each entry of agents.list in openclaw.json. The guides that rank for this explain the keys well. They walk through how the lists combine, show a read-only agent and a messaging agent, and then leave you to decide what goes in the list for your own agents, which is the only part that takes any thought. I build mine from evidence: one week of the tool calls each agent actually made. Then I test the result with a call that should fail.

The Shape

This is the block from the context budget guide, trimmed. Key names have moved between releases, so check yours before pasting.

{
  "agents": {
    "list": [
      {
        "id": "briefing",
        "tools": {
          "allow": ["calendar_list_events", "gmail_search", "weather_*"]
        }
      },
      {
        "id": "repo-janitor",
        "tools": {
          "allow": ["github_*", "exec", "read", "write"],
          "deny": ["github_delete_*"]
        }
      }
    ]
  }
}

Two habits matter more than precedence rules. First, an allow list is a whitelist, so a tool that is not named is a tool the agent cannot call. Second, write the deny list so it never depends on precedence at all: if a pattern appears in deny, no entry in allow for the same agent should match it except through a wildcard you meant to narrow. github_* plus github_delete_* is the intended use. An exact name in both lists is a bug waiting for a release note.

Why Bother

Two reasons, and they are not equal. The smaller one is money. Every tool the agent can see ships its description and full JSON schema on every turn, and in the context budget guide an idle Notion server cost about 3,000 tokens a turn for six months before anyone noticed. An allow list stops schemas you never use from riding along.

The bigger reason is blast radius. A prompt injection in a scraped web page can only ask for tools the agent has. If the research agent has no exec, a hostile README cannot talk it into running anything, no matter how persuasive the README is.

Build the List From What the Agent Did

Guessing produces lists that are either too generous (you add everything that sounds useful) or so tight the agent breaks on day two and you widen it to a wildcard in frustration. Logs fix both.

OpenClaw records every message, tool call and tool result, and the sessions_history tool reads them back, as the security best practices guide notes. Let each agent run normally for a week, then ask it, in a main session, for a plain inventory:

Use sessions_history to review your sessions from the last 7 days.
List every tool you called, one per line, with the number of calls.
Do not summarize. Do not group. Include tools that failed.

"Include tools that failed" is there for a reason. A tool that failed every time is still a tool the agent reached for, and you want to know whether to grant it or rewrite the instruction that made the agent try.

Then sort the output into three piles.

1. Called often, and you are fine with it. Into allow by exact name.
2. Called once or twice for something odd. Find the session and read it. Half the time the agent improvised around a missing skill, and the fix is a skill, not a permission.
3. Called, and it should never have been. Into deny, and go find the instruction that made it seem reasonable.

A week is the minimum because a lot of agent work is weekly. Monday reports, Friday cleanups. Start the window on a Monday and end it on a Sunday, or you will cut a tool the agent needs once every seven days and find out about it the next time that job runs, probably from a cron failure you only notice later.

Prefer exact names over wildcards wherever the list stays readable. On a full GitHub MCP server, github_* can still pull in forty-odd tools when the agent used six. If the server can pick toolsets at launch, filter there too. The GitHub MCP server guide covers that setup.

The Canary Test

A policy you have not watched fail is a hypothesis. Hand-edit the JSON, nest the tools block one level off, and unless your version validates the config on load, nothing about the agent's behavior will tell you. It just keeps every tool it had before.

After any change, restart the gateway, open a fresh session with the agent you changed, and ask for something only a denied tool could do. For the briefing agent:

Run `uname -a` with the exec tool and paste the output.

The pass condition is the agent telling you it has no such tool. A refusal on moral grounds is a fail, because it means the tool is there and the model chose not to use it this time. Output from uname is a loud fail. If your build has /context, run it in the same session and confirm the denied tool's schema is gone from the tool list; that is the cheaper confirmation and it shows the token saving at the same time.

Run one canary per agent, and run each through every path that reaches that agent: the main session, a heartbeat and, if you have one, the Telegram or Slack channel. Tools that come from MCP servers deserve their own canary, separate from built-in tools, since they arrive through a different route and I would not assume a policy reaches both until I had seen it.

Keep the canaries in a file next to openclaw.json. Rerun them after every upgrade. The upgrade guide has a post-upgrade checklist, and the canaries belong on it.

Sub-Agents Get Their Own List

A spawned sub-agent is a separate permission question. sessions_spawn accepts a toolsAllow parameter, a whitelist of tool IDs for that run, and an attachAs parameter that mounts only the directories the task needs. Pass both every time. A parent with exec that spawns a helper to summarize three PDFs has no reason to hand exec down, and the multi-agent orchestration guide shows where spawns sit in a larger pipeline.

Deny Is Not Approve

Some tools should be available but never silent. Setting a tool to ask: always in the tool policy keeps it on the list and puts you in the loop for each call. That is the right setting for exec, write and gateway on any agent that has them at all.

Deny the tools an agent has no use for. Gate the ones it needs and could hurt you with.

TOOLS.md Grants Nothing

Writing "you may use the GitHub tools" in TOOLS.md does not give the agent GitHub, and writing "never run shell commands" in AGENTS.md does not take exec away. Markdown shapes what the model chooses to do. The allow list decides what it can do. The workspace files guide covers which file a rule belongs in; this page covers the part that is enforced.

The Agent You Trust Most

It gets a list too, and its list will be the longest one you write, which is fine, because long and explicit is still a list.

Common Failure Modes

Final Verdict

Write an allow list for every agent and build it from a full week of that agent's own calls. Then make it fail on purpose, once per agent and once per channel, and keep those canaries for every upgrade after. The config is ten minutes of work. The canary is the part almost nobody does, and it is the only proof the list is doing anything.