Tool Access Control & Profiles

+15 Mana ✨
OpenClaw Access Control Documentation(DOCUMENTATION)

Introduction

Not every agent should have access to every tool. OpenClaw implements a three-tier access control model that lets administrators define precisely which tools an agent may use. This lesson explains base profiles, allow/deny lists, and provider-specific policies.

Key Concepts

  • Base Profile: A preset level of tool access — minimal, coding, messaging, or full.
  • Allow List: An explicit list of tools or patterns the agent is permitted to use, layered on top of the base profile.
  • Deny List: An explicit list of tools or patterns the agent is forbidden from using, which always overrides the allow list.
  • Tool Groups: Named collections like group:runtime, group:fs, group:web that bundle related tools for easier access management.
  • Provider-Specific Policy: The third tier of control that restricts tools based on the underlying model provider.
  • Case-Insensitive Matching: Tool names in allow/deny lists are matched without regard to case.
  • Wildcard Patterns: Use * in allow/deny entries to match multiple tools with a single rule.

Real World Context

A company deploys two agents: one for code review and one for customer support. The code review agent uses the coding base profile with group:fs and group:runtime allowed. The support agent uses messaging with only group:web allowed and exec explicitly denied. This ensures neither agent exceeds its intended capabilities.

Deep Dive

The Three-Tier Model

Access control flows through three layers, evaluated in order:

Base Profile → Allow/Deny Lists → Provider-Specific Policy

Each tier narrows the set of available tools. A tool must pass all three tiers to be available to the agent.

Base Profiles

The base profile sets the starting point:

json
{
  "profile": "coding"
}

This selects the coding profile, which includes file operations and execution tools by default. The four profiles offer increasing levels of access:

  • minimal: Only basic read-only tools. Suitable for agents that only need to observe.
  • coding: File ops and execution tools. For agents that write and run code.
  • messaging: Adds cross-platform messaging capabilities on top of coding tools.
  • full: All tools enabled. Use sparingly and only for trusted agents.

Allow and Deny Lists

After the base profile, allow and deny lists refine access:

json
{
  "profile": "minimal",
  "allow": ["web_search", "web_fetch", "memory_*"],
  "deny": ["exec", "bash", "process"]
}

This configuration starts with the minimal profile, explicitly allows web and memory tools via the allow list (using a wildcard for all memory tools), and explicitly denies all execution tools. Note that memory_* matches both memory_search and memory_get because wildcards expand to any suffix.

The critical rule: when a tool appears in both the allow and deny lists, deny always wins. This is a security-first design.

json
{
  "allow": ["exec"],
  "deny": ["exec"]
}

In the above configuration, exec is denied even though it appears in the allow list. The deny list takes absolute precedence.

Tool Groups

Instead of listing individual tools, you can reference groups:

json
{
  "allow": ["group:runtime", "group:fs"]
}

This allows all tools in the runtime group (exec, bash, process) and the fs group (read, write, edit, apply_patch) with a single entry. Available groups include:

  • group:runtime — exec, bash, process
  • group:fs — read, write, edit, apply_patch
  • group:sessions — session management tools
  • group:web — web_search, web_fetch
  • group:ui — browser-related tools
  • group:messaging — cross-platform messaging
  • group:automation — cron, gateway
  • group:openclaw — OpenClaw platform tools

Provider-Specific Policy

The final tier restricts tools based on the AI provider:

json
{
  "providers": {
    "openai": {
      "deny": ["group:automation"]
    }
  }
}

This denies automation tools specifically when the agent runs on an OpenAI provider, while allowing them for other providers. This tier is evaluated last and can further restrict but never expand access.

Common Pitfalls

  • Assuming allow overrides deny: It never does. If a tool is in both lists, it is denied. This is the most common source of confusion.
  • Forgetting case-insensitivity: Adding Exec to the deny list blocks exec, EXEC, and any other casing. This is intentional but can surprise developers.
  • Using full profile in production: The full profile grants access to every tool. Always start with the most restrictive profile and expand via allow lists.

Best Practices

  • Start with minimal and add what you need: This follows the principle of least privilege and prevents accidental exposure.
  • Use tool groups over individual tools: Groups are maintained by the platform and automatically include new tools added to a category.
  • Document your deny list rationale: When denying tools, add comments in your configuration explaining why, so future maintainers understand the security intent.

Summary

  • Access control uses three tiers: Base Profile, Allow/Deny Lists, and Provider-Specific Policy.
  • Four base profiles (minimal, coding, messaging, full) set the starting level of tool access.
  • Deny lists always override allow lists, ensuring security-first behavior.
  • Tool groups like group:runtime and group:fs simplify access management.
  • Wildcards and case-insensitive matching make allow/deny lists flexible.
✓ Completed