6. Introduction to OpenClaw Tools

Tools serve as the "capability interfaces" that OpenClaw exposes to agents, enabling models to perform real-world operations—such as reading and writing files, executing commands, managing sessions, accessing web pages, and performing UI automation—in a safer and more structured manner. Compared to the legacy openclaw-* Skills, Tools are strongly typed, controllable, and allow for precise configuration to define exactly "what is allowed" versus "what is forbidden."

1. Key Concepts

1.1 The Relationship Between Tools and Skills

• Tools: System-level "capability interfaces" that are strongly typed, configurable, and can be restricted based on the provider or specific model being used.
• Skills: Lean more towards being "reusable workflows" or "plugin capabilities"; many legacy skills will eventually be replaced or superseded by the new Tools framework.

If your goal is to have the agent "perform an action," prioritize using Tools. If, however, you wish to encapsulate a specific process into a reusable capability, then consider using Skills.

1.2 More Tools Do Not Necessarily Mean Better

The more tools you enable, the wider the range of actions the model can perform—but the greater the associated risks become. The best practice is to: enable only the tools you genuinely require by default, and specifically disable (or enable on an as-needed basis) any high-risk capabilities—particularly the ability to execute commands.

1.3 The Core of Tool Strategy: profile + allow/deny

The set of available tools is typically refined and filtered according to the following sequence:

1. tools.profile: Establishes an initial "baseline set of allowed tools."
2. tools.byProvider: If configured, this setting further restricts the toolset for specific providers or specific provider/model combinations (this step can only narrow down the available tools).
3. tools.allow / tools.deny: Finally, these settings are used to precisely fine-tune the toolset—either by further restricting it (deny) or by explicitly allowing specific additions (allow). (Note: deny rules take precedence over allow rules.)

2. Getting Started

The policies governing which OpenClaw tools are permitted are defined within the openclaw.json configuration file. In most cases, manual configuration is not required.

• deny takes precedence over allow.
• The * wildcard is supported, and matching is case-insensitive.

2.1 Selecting a Tool Profile

Common profiles (listed in order of increasing capability):

• minimal: session_status only.
• messaging: Primarily messaging-related capabilities + session capabilities.
• coding: Primarily development/engineering capabilities (files, runtime, sessions, memory, images, etc.).
• full: No restrictions (equivalent to leaving the setting unset).

Example: Enabling the coding profile.

{
  "tools": {
    "profile": "coding"
  }
}

2.2 Precise Control using allow/deny (Recommended: Start with deny)

Example: Globally disable the browser tool

xxxxxxxxxx
{
  "tools": {
    "deny": ["browser"]
  }
}

Example: Based on the 'coding' configuration, disable all runtime tools (exec / bash / process).

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

2.3 Restricting Tools for a Specific Provider/Model (byProvider)

You can keep the global defaults unchanged while further restricting the toolset for a specific provider—or a specific provider/model combination. (Note: This restriction can only narrow the scope of available tools; it cannot expand it.)

Example: Use the "coding" toolset globally, but apply the "minimal" toolset specifically to Google Antigravity.

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

Example: Further reduce tools for openai/gpt-5.2.

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

3. Tool Groups (group:*)

In tools.allow / tools.deny, you can use group:* to control a group of tools simultaneously:

Example: Allow only File Tools + Browser

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

4. High-Risk Tools: How to Configure Them Safely

4.1 Command Execution Tools (group:runtime)

The group:runtime category encompasses command execution capabilities (e.g., exec, bash, process). For these capabilities, the following guidelines are recommended:

• Disable by Default: Start by setting deny: ["group:runtime"], then gradually enable specific capabilities only when necessary.
• Enable for Specific Agents Only: Consolidate high-risk capabilities within dedicated agents.
• Enable for Specific Providers/Models Only: Grant access to a wider range of tools specifically for stable and trusted models.

4.2 Tips for apply_patch

apply_patch is classified as a file-editing tool. In some versions, it is an experimental feature that may require an additional toggle to enable (e.g., via tools.exec.applyPatch.enabled; note that support is limited to specific models). If you observe that a model is clearly attempting to modify files but fails to invoke apply_patch, your first step should be to verify the tool policies and the relevant configuration toggles.

4.3 Isolate Tools by Agent (Recommended Practice)

You can establish a global set of tool policies and then override them for specific agents individually, thereby centralizing "high-privilege capabilities" within a select few agents.

Example: Configure the global policy to allow coding tools, but restrict the support agent to messaging tools only, while additionally granting it access to Slack tools.

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

5. Recommended Configuration Templates (Ready-to-Use)

5.1 Casual Conversation (Safer)

Goal: Chat-only mode + Monitor conversation state only—without granting the ability to "tamper with the system."

xxxxxxxxxx
{
  "tools": {
    "profile": "minimal"
  }
}

5.2 Studying / Writing Documentation (Web browsing allowed; running commands is not permitted)

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

5.3 Development & Debugging (File Read/Write Enabled, but Execution Commands Treated as "Optional")

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

When you genuinely need to execute commands, temporarily lift the restriction on group:runtime; once you are finished, revert the setting.

6. Frequently Asked Questions

6.1 allow was configured but did not take effect

• Check whether a deny rule simultaneously matches the same tool (the deny rule takes precedence).
• Verify that the tool name is spelled correctly (matching is case-insensitive, but the name itself must exist).
• If tools.allow consists solely of unknown or currently unloaded plugin tools, the system may disregard the allow list to ensure that core tools remain available.

6.2 A specific model works with tools, but switching to a different model causes them to fail

• You may have configured tools.byProvider (specifying either the provider or provider/model) to impose additional restrictions on that specific model.
• Some provider endpoints offer inconsistent support for tools; it is recommended to utilize a smaller, more limited toolset when working with unstable endpoints.

6.3 Which profile should I actually choose?

• Just want to chat: minimal
• Daily messaging + session management: messaging
• File-based or project-related tasks: coding
• You know exactly what you are doing and are willing to accept the associated risks—"I want the full, powerful OpenClaw experience": full

7. Official Documentation

• OpenClaw Tool Documentation：Tools and Plugins - OpenClaw