Managing Agent Tools in OpenClaw

I often find myself worrying about what an agent can actually do once I give it access to my system. It is hard to find that balance between giving an agent enough power to be useful and making sure it does not touch things it should not. Managing separate scripts for every small task usually leads to a configuration mess that is hard to track.

OpenClaw handles this by using first-class tools for the browser, canvas, nodes, and cron. These are typed and built-in, so you do not have to deal with external shells. I prefer this because I can control exactly what the model sees.

What You’ll Need

• OpenClaw installed and running
• An openclaw.json configuration file

Quick Start

You control tools globally or per-agent using tools.allow and tools.deny. If you put a tool in both, the deny rule always wins. Matching is case-insensitive and you can use * as a wildcard for everything.

I recommend starting with a tools.profile to set a base allowlist. Here are the options:

• minimal: Only session_status
• coding: Includes group:fs, group:runtime, group:sessions, group:memory, and image
• messaging: Includes group:messaging, sessions_list, sessions_history, sessions_send, and session_status
• full: No restrictions

Example: Global Coding Profile

If I want a coding setup but want to make sure the agent never touches the process or runtime tools, I use this:

{
  "tools": {
    "profile": "coding",
    "deny": ["group:runtime"]
  }
}

Example: Per-Agent Overrides

You can set a global default and then change it for specific agents. In this example, I have a global coding setup, but my support agent only gets messaging tools.

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": {
          "profile": "messaging",
          "allow": ["slack"]
        }
      }
    ]
  }
}

Troubleshooting

• Tools not appearing: If your tools.allow list only contains unknown or unloaded plugin tools, OpenClaw will log a warning. It will then ignore your allowlist and keep core tools available so the agent stays functional.
• Conflicts: If you are trying to allow a tool but it remains blocked, check your deny list. The deny list always takes priority over allow.

If you need help setting up specific tool permissions for your workflow, check out the AI Setup Assistant.

What’s Next

• Agent Configuration
• Browser Tool Deep Dive

I often find that while one model handles a massive toolset perfectly, another one might struggle or get confused. It’s frustrating when you have a global setup that works most of the time, but you need to dial it back for a specific provider to keep things stable.

Instead of changing your entire configuration, I recommend using provider-specific policies. This lets you keep your global defaults while narrowing down what specific models can do.

What You’ll Need

• A configuration file with tools or agents defined.
• The provider name (e.g., google-antigravity) or a provider/model string (e.g., openai/gpt-5.2).

Quick Start

I use tools.byProvider to restrict tools for specific providers without changing global defaults. You can apply this globally or per-agent via agents.list[].tools.byProvider.

This policy is applied after the base tool profile and before allow/deny lists. This means it can only narrow the tool set, not expand it.

Global Override Example

In this example, I keep the “coding” profile globally but switch to a “minimal” profile specifically for Google Antigravity.

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

Model-Specific Allowlist

If you have a flaky endpoint, you can restrict it to a smaller set of tools using the provider/model syntax.

{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

Per-Agent Override

You can also apply these restrictions to a single agent. This is useful when an agent needs to behave differently depending on which model it is using.

{
  agents: {
    list: [
      {
        id: "support",
        tools: {
          byProvider: {
            "google-antigravity": { allow: ["message", "sessions_list"] },
          },
        },
      },
    ],
  },
}

Troubleshooting

Tools are not appearing even though they are in the byProvider list Remember that byProvider is applied after the base profile. It can only narrow the tool set. If a tool is not in your global base profile or global allow list, you cannot add it back using byProvider.

The policy isn’t triggering for my model Check your keys. Provider keys must accept either the provider (e.g., google-antigravity) or the exact provider/model string (e.g., openai/gpt-5.2).

If you run into other issues, I suggest asking the AI Setup Assistant.

What’s Next

• Tool Profiles
• Agent Configuration

I’ve spent too much time manually listing every single tool permission in configuration files. It is tedious to track every file-read or shell-exec command individually when you just want to give an agent a logical set of capabilities. Dealing with long lists of individual tools often leads to configuration errors or missing permissions that break your workflow.

To make this easier, I recommend using tool groups. These shorthands allow you to manage groups of related tools with a single entry in your policy.

What You’ll Need

• Access to tool policies (global, agent, or sandbox).
• The tools.allow or tools.deny configuration fields.

Quick Start

You can use group:* entries in your tools.allow or tools.deny lists. These entries expand automatically to include multiple tools.

Here are the groups you can use right now:

• group:runtime: Includes exec, bash, and process.
• group:fs: Includes read, write, edit, and apply_patch.
• group:sessions: Includes sessions_list, sessions_history, sessions_send, sessions_spawn, and session_status.
• group:memory: Includes memory_search and memory_get.
• group:web: Includes web_search and web_fetch.
• group:ui: Includes browser and canvas.
• group:automation: Includes cron and gateway.
• group:messaging: Includes message.
• group:nodes: Includes nodes.
• group:openclaw: Includes all built-in OpenClaw tools (note that this excludes provider plugins).

If you want to allow only file system tools and the browser, your configuration would look like this:

{
  tools: {
    allow: ["group:fs", "browser"],
  },
}

Plugins and Optional Tools

Plugins can register additional tools and CLI commands beyond the core set. I suggest checking Plugins for installation and configuration details. You should also look at Skills to see how tool usage guidance is injected into prompts.

There are also optional plugin tools available:

• Lobster: A typed workflow runtime with resumable approvals. This requires the Lobster CLI on the gateway host.
• LLM Task: A JSON-only LLM step for structured workflow output with optional schema validation.

Troubleshooting

• Missing tools in group:openclaw: If you find that a tool from a plugin isn’t working while using this group, remember that group:openclaw excludes provider plugins. You must list plugin tools separately.
• Lobster tool failures: If the Lobster tool fails to run, verify that the Lobster CLI is correctly installed on your gateway host.

If you need help with your specific configuration, try the AI Setup Assistant.

What’s Next

• Plugins Documentation
• Skills and Prompt Injection
• Lobster Workflow Runtime
• LLM Task Tool

I often find myself jumping between a dozen different terminal tabs and browser windows just to finish one task. It is a common headache to manually copy-paste logs or search for API documentation while trying to stay in the flow. I want my tools to work together without me acting as the manual bridge between them.

In this post, I will show you the tool inventory. These are the built-in capabilities you can give your agents to help them interact with the real world.

What You’ll Need

• Brave API Key: Required for the web_search tool.
• Playwright: Needed if you want the browser tool to use ai snapshots.
• Image Model Config: An agents.defaults.imageModel must be set to use the image tool.
• Enabled Flags: Some tools like apply_patch or web_fetch require specific config flags to be true.

Quick Start

You can get up and running with these tools in about five minutes.

1. Enable Search: Run openclaw configure --section web and add your Brave API key.
2. Test Execution: Try a simple shell command using exec with command: "ls".
3. Check Background Jobs: If a command takes too long, use process with action: "list" to see what is running.
4. Fetch a Page: Use web_fetch with a url to grab content as markdown.

---

The Tool Inventory

apply_patch

I use this for multi-hunk edits across one or more files. It applies structured patches and is currently experimental. You need to enable it via tools.exec.applyPatch.enabled. Note that this only works with OpenAI models for now.

exec

This is the core tool for running shell commands in your workspace.

Core parameters:

• command (required)
• yieldMs: Auto-backgrounds after this timeout (default 10000).
• background: Immediate background execution.
• timeout: Kills the process if it exceeds this limit (default 1800 seconds).
• elevated: Runs on the host if allowed. This is an alias for host=gateway + security=full.
• host: Choose between sandbox, gateway, or node.
• security: Options are deny, allowlist, or full.
• ask: Set to off, on-miss, or always.
• node: Specify the node id/name when host=node.
• pty: Set to true if you need a real TTY.

If process is disallowed, exec runs synchronously and ignores background settings. When backgrounded, it returns a sessionId.

process

I use this to manage those background exec sessions. You can perform these actions:

• list, poll, log, write, kill, clear, remove

The poll action gives you new output and the exit status. If you use log, you can use offset and limit for line-based reading. These sessions are scoped per agent.

web_search

This tool uses the Brave Search API. You need to enable it via tools.web.search.enabled and provide a key.

• query (required)
• count: Results between 1 and 10.

web_fetch

This turns a URL into readable markdown or text.

• url (required)
• extractMode: markdown or text.
• maxChars: Truncates long pages.

It is cached for 15 minutes by default. For sites heavy on JavaScript, I recommend using the browser tool instead.

browser

This controls a dedicated browser instance. It is enabled by default via browser.enabled.

Core actions:

• status, start, stop, tabs, open, focus, close
• snapshot: Use aria for the tree or ai (requires Playwright).
• screenshot: Returns an image block.
• act: UI actions like click, type, fill, or evaluate.
• navigate, console, pdf, upload, dialog

You can manage multiple profiles with create-profile and delete-profile. Profiles use ports in the 18800-18899 range. When using act, I use the ref provided by the snapshot tool.

canvas

This drives the node Canvas for presentations or UI.

• present, hide, navigate, eval
• snapshot: Returns an image.
• a2ui_push, a2ui_reset: For A2UI interactions.

nodes

This helps discover paired nodes and capture media.

• status, describe
• pending, approve, reject: For pairing.
• notify, run: System commands.
• camera_snap, camera_clip, screen_record, location_get

Example for the run action:

{
  "action": "run",
  "node": "office-mac",
  "command": ["echo", "Hello"],
  "env": ["FOO=bar"],
  "commandTimeoutMs": 12000,
  "invokeTimeoutMs": 45000,
  "needsScreenRecording": false
}

image

I use this to analyze images with a specific model.

• image: The path or URL.
• prompt: Defaults to “Describe the image.”
• model: Optional override.

message

This handles communications across platforms like Discord, Slack, and WhatsApp.

• send: Text and media.
• poll: Create polls on WhatsApp, Discord, or MS Teams.
• react, thread-create, search, channel-list, and more.

cron

Manage Gateway cron jobs.

• status, list, add, update, remove, run, runs, wake

gateway

This allows you to restart or update the Gateway.

• restart, config.get, config.apply, config.patch, update.run

Session Management

There are several tools for session interaction:

• sessions_list: Filter by kinds or activeMinutes.
• sessions_history: Inspect transcripts.
• sessions_send: Send a message to another session.
• sessions_spawn: Start a sub-agent task.
• session_status: Check or override the model for a session.

agents_list

This lists the agent IDs your current session is allowed to target. It respects the subagents.allowAgents configuration.

---

Troubleshooting

• Exec runs synchronously: This happens if process is disallowed in your configuration. Check your security settings.
• Camera or Screen tools fail: These actions require the node app to be in the foreground on the target device.
• Browser act timing out: Avoid using wait by default. Only use it if there is no reliable UI state to detect.
• Apply Patch fails: Ensure you are using an OpenAI model and that the experimental flag is set to true.

If you hit a wall, I recommend checking the AI Setup Assistant for specific configuration help.

What’s Next

• Exec approvals
• Web tools setup
• Browser profiles
• Firecrawl fallback

I’ve found that one of the most common hurdles when building agents is getting the configuration right across different tools. It is annoying when a tool fails because it didn’t pick up the credentials you thought were already there, or when an agent tries to perform an action without the right context.

I want to walk you through how these parameters work and the specific patterns I recommend for different automation tasks.

What You’ll Need

• Access to Gateway-backed tools (canvas, nodes, or cron).
• A browser environment if you are using browser automation.
• Explicit credentials (if your gateway has authentication enabled).

Quick Start

Setting up your tools correctly from the start saves a lot of debugging time. Here is the breakdown of the parameters you will use most often.

1. Gateway-backed Tools

For tools like canvas, nodes, and cron, you have three main parameters:

• gatewayUrl: This defaults to ws://127.0.0.1:18789.
• gatewayToken: Required if authentication is enabled.
• timeoutMs: To control how long the tool waits before timing out.

Important Note: When you set a custom gatewayUrl, you must include the gatewayToken explicitly. Tools do not inherit configuration or environment credentials for overrides. If you miss these explicit credentials, you will run into errors.

2. Browser Tool Configuration

When you are working with the browser tool, you have these options:

• profile: This is optional and defaults to browser.defaultProfile.
• target: You can choose between sandbox, host, or node.
• node: This is an optional parameter to pin the tool to a specific node ID or name.

3. Recommended Agent Flows

I suggest following these sequences to ensure your agent has the context it needs before acting.

Browser Automation Flow:

1. Call browser → status or start.
2. Use snapshot (ai or aria).
3. Perform an act (click, type, or press).
4. Use screenshot if you need visual confirmation.

Canvas Render Flow:

1. Call canvas → present.
2. Use a2ui_push (this is optional).
3. Use snapshot.

Node Targeting Flow:

1. Call nodes → status.
2. Use describe on your chosen node.
3. Call notify, run, camera_snap, or screen_record.

Safety First

I always recommend being careful with execution commands. Avoid using system.run directly. Instead, use nodes → run and only do so with explicit user consent.

You should also respect user consent for any camera or screen capture. I find it best to use status or describe to verify permissions before you try to invoke any media commands.

How Tools are Presented

The agent understands tools through two parallel channels:

1. System prompt text: This is a human-readable list and guidance for the agent.
2. Tool schema: These are the structured function definitions sent to the model API.

The agent needs to see both “what tools exist” and “how to call them.” If a tool is missing from the system prompt or the schema, the model simply cannot call it.

Troubleshooting

Error: Missing Credentials This usually happens when you override the gatewayUrl but forget to provide the gatewayToken. Remember that tools do not inherit credentials from the environment when you use overrides. You must provide them explicitly in the tool configuration.

Issue: Agent Cannot Call a Tool If an agent seems unaware of a tool, check both the system prompt and the tool schema. If the tool does not appear in both places, the model will not be able to use it.

For more help setting up your environment, check out the AI Setup Assistant.

What’s Next

• Browser Tool Documentation
• Canvas API Reference
• Node Management Guide
• Cron Job Configuration