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

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