Enable Tools and Plugins (Advanced)

Mental model: plugins vs tools vs sandbox

People often mix these up. In OpenClaw they are separate levers:

• Plugins add capabilities (some plugins register tools).
• Tools are the callable “functions” the agent can use during runs.
• Sandboxing decides where tools run (host vs Docker sandbox), not which tools exist.

Official reference (recommended reading):

• Tool policy vs sandbox vs elevated: https://docs.openclaw.ai/gateway/sandbox-vs-tool-policy-vs-elevated
• Plugin tools (optional allowlists): https://docs.openclaw.ai/plugins/agent-tools

If you are debugging this on native Windows rather than Linux/WSL2, also read:

• OpenClaw on Native Windows: PATH, Scheduled Tasks, Node Host, and the Real Failure Modes
• Windows: tools.exec cannot find docker, rg, or gh even though they work in PowerShell
• Windows: Exec tool returns empty output unless pty: true

June 2026 Skill Workshop and tools routing note

The OpenClaw v2026.6.1 release, published June 3, 2026, routes Skill Workshop to official OpenClaw docs as the governed path for workspace skill creation and review. Use the official Skill Workshop docs for current upstream behavior.

CoClaw keeps this page focused on operator enablement: turning tools/plugins on deliberately, keeping allowlists narrow, verifying tool cards, and troubleshooting blocked calls. For plugin discovery and install discipline, start with /plugins and ClawHub usage; for supply-chain review and prompt-injection boundaries, use Skill safety and prompt injection defense. If a tool is visible but blocked, use the debugging section below before broadening permissions.

1) Enable an optional plugin (example: llm-task)

Edit your config (default: ~/.openclaw/openclaw.json) and enable the plugin:

{
  plugins: {
    entries: {
      "llm-task": { enabled: true },
    },
  },
}

Optional: set a restrictive config so it can only run the models you expect:

{
  plugins: {
    entries: {
      "llm-task": {
        enabled: true,
        config: {
          // Example values; adjust to your providers/models
          allowedModels: ["openai-codex/gpt-5.2"],
          maxTokens: 800,
          timeoutMs: 30000,
        },
      },
    },
  },
}

2) Allowlist the tool (per-agent is recommended)

Most optional plugin tools are opt-in. Add them to the agent allowlist:

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          allow: [
            "llm-task",
            // You can also allow an entire plugin id, or a group like:
            // "group:plugins"
          ],
        },
      },
    ],
  },
}

Rules of thumb:

• Start conservative: only allow what you need.
• Prefer per-agent allowlists over a global allowlist, so you can run a “safe” agent alongside a “power” agent.
• Remember: deny wins. If a tool is denied anywhere in policy, it stays denied.

3) Restart and verify

If your gateway is installed as a service:

openclaw gateway restart

Then verify:

• Open the dashboard (openclaw dashboard)
• Confirm the tool is visible/available
• Run a controlled test prompt that should call the tool once (no side effects)

Debugging: “why is my tool blocked?”

If a tool is present but not callable, the fastest way to see what’s happening is:

openclaw sandbox explain

It will show:

• whether your session is sandboxed
• the effective tool allow/deny policy
• which config keys are responsible

Common failure patterns:

• Plugin enabled but tool not allowlisted (optional tools)
• Tool allowlist exists but does not include the tool (everything else becomes blocked)
• Tool is allowed globally, but denied in sandbox policy (when sandboxed)
• On native Windows, the service runtime may see a different PATH than your interactive shell
• On Windows, exec can also fail for PTY/runtime reasons even when the tool policy itself is correct

Related Windows pages:

• Windows: tools.exec cannot find docker, rg, or gh even though they work in PowerShell
• Windows: Exec tool returns empty output unless pty: true