<!-- source: https://deepwiki.com/openclaw/openclaw/3.4.1-tool-policies-and-filtering -->

# Tool Policies & Filtering

- docs/help/testing-live.md
- packages/gateway-protocol/src/schema/agents-models-skills.test.ts
- qa/scenarios/config/config-restart-capability-flip.md
- scripts/test-live-subagent-announce-docker.sh
- src/agents/agent-bundle-mcp-materialize.ts
- src/agents/agent-bundle-mcp-runtime.test.ts
- src/agents/agent-bundle-mcp-runtime.ts
- src/agents/agent-bundle-mcp-tools.materialize.test.ts
- src/agents/agent-bundle-mcp-types.ts
- src/agents/agent-tools-agent-config.exec.test.ts
- src/agents/agent-tools.before-tool-call.e2e.test.ts
- src/agents/agent-tools.before-tool-call.embedded-mode.test.ts
- src/agents/agent-tools.before-tool-call.ts
- src/agents/agent-tools.ts
- src/agents/embedded-agent-runner/compact.hooks.test.ts
- src/agents/embedded-agent-runner/compact.queued.ts
- src/agents/embedded-agent-runner/compaction-runtime-context.test.ts
- src/agents/embedded-agent-runner/compaction-runtime-context.ts
- src/agents/embedded-agent-runner/effective-tool-policy.ts
- src/agents/embedded-agent-runner/run/attempt.prompt-helpers.ts
- src/agents/embedded-agent-runner/run/attempt.spawn-workspace.context-engine.test.ts
- src/agents/live-cache-regression-runner.test.ts
- src/agents/live-cache-regression-runner.ts
- src/agents/live-cache-test-support.ts
- src/agents/live-model-filter.ts
- src/agents/live-test-helpers.test.ts
- src/agents/live-test-helpers.ts
- src/agents/live-test-provider-drift.test.ts
- src/agents/live-test-provider-drift.ts
- src/agents/model-compat.test.ts
- src/agents/models.profiles.live.test.ts
- src/agents/openai-reasoning-compat.live.test.ts
- src/agents/subagent-announce.live.test.ts
- src/agents/tool-policy-audit.ts
- src/agents/tool-policy-pipeline.test.ts
- src/agents/tool-policy-pipeline.ts
- src/agents/tool-replay-repair.live.test.ts
- src/agents/tools-effective-inventory.test.ts
- src/auto-reply/reply/agent-runner-memory.test.ts
- src/auto-reply/reply/agent-runner-memory.ts
- src/cli/mcp-cli.test.ts
- src/cli/mcp-cli.ts
- src/commands/doctor.runs-legacy-state-migrations-yes-mode-without.e2e.test.ts
- src/commands/doctor/shared/active-tool-schema-warnings.test.ts
- src/commands/doctor/shared/active-tool-schema-warnings.ts
- src/config/mcp-config.ts
- src/config/types.skills.ts
- src/flows/doctor-core-checks.runtime-errors.test.ts
- src/flows/doctor-core-checks.runtime.test.ts
- src/flows/doctor-core-checks.runtime.ts
- src/gateway/gateway-cli-backend.live.test.ts
- src/gateway/gateway-models.profiles.live.test.ts
- src/plugins/contracts/host-hooks.contract.test.ts
- src/plugins/trusted-tool-policy.ts
- src/skills/workshop/config.ts
- src/skills/workshop/policy.ts

This page documents the tool policy resolution workflow and filtering mechanisms in OpenClaw's agent runtime. Tool policies control which tools are permitted or denied according to global settings, agent configuration, profile/group rules, and ownership boundaries.

## Policy Resolution Hierarchy

OpenClaw employs a layered approach to tool policy resolution. The effective policy is resolved by merging global defaults with agent-specific overrides, profile-based restrictions, and sub-agent capability constraints.

### Implementation Details

The core logic for resolving tool availability resides in the `src/agents/agent-tools.policy.ts` and `src/agents/tool-policy.ts` modules. Key functions include:

- resolveEffectiveToolPolicy src/flows/doctor-core-checks.runtime.ts 14 computes the merged allow/deny policy by combining global and agent-level configurations.
- applyFinalEffectiveToolPolicy src/flows/doctor-core-checks.runtime.ts 16 applies the resolved policy to the runtime toolset during the execution phase.
- collectExplicitAllowlist src/flows/doctor-core-checks.runtime.ts 26 extracts the list of explicitly permitted tools from the configuration.
- normalizeToolName src/flows/doctor-core-checks.runtime.ts 26 ensures tool names are canonicalized to prevent bypasses via case sensitivity or whitespace.

### Data Flow and Normalization

Before policies are applied, tool names are normalized to prevent bypasses:

- normalizeLowercaseStringOrEmpty src/auto-reply/reply/agent-runner-memory.ts 5 and other coercion utilities ensure configuration keys are canonicalized.
- normalizeAgentRuntimeTools src/flows/doctor-core-checks.runtime.ts 25 prepares the toolset for the agent runtime by applying normalization and filtering logic.

### Tool Policy Resolution Workflow

Title: Tool Policy Resolution Pipeline

```

```

Sources: [src/flows/doctor-core-checks.runtime.ts13-26](https://github.com/openclaw/openclaw/blob/fbdf5937/src/flows/doctor-core-checks.runtime.ts#L13-L26) [src/auto-reply/reply/agent-runner-memory.ts4-7](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L4-L7)

## Tool Execution Hooks & Approvals

Before a tool is executed, it passes through a hook system that can veto, adjust parameters, or require human approval.

- Before Tool Call Hooks: hasBeforeToolCallPolicy src/agents/agent-tools.before-tool-call.ts 175-178 checks if any active hooks or trusted policies are registered.
- Trusted Tool Policies: runTrustedToolPolicies src/agents/agent-tools.before-tool-call.ts 32 executes plugin-defined security policies that can block execution.
- Human-in-the-loop (HITL): If a tool requires approval, a DeferredPluginToolApproval src/agents/agent-tools.before-tool-call.ts 145-152 is created, pausing execution until the gateway receives a resolution.
- Parameter Adjustment: Hooks can modify tool arguments via recordAdjustedParamsForToolCall src/agents/agent-tools.before-tool-call.ts 201-205 allowing for transparent path remapping or security sanitization.

Sources: [src/agents/agent-tools.before-tool-call.ts130-152](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/agent-tools.before-tool-call.ts#L130-L152) [src/agents/agent-tools.before-tool-call.ts168-186](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/agent-tools.before-tool-call.ts#L168-L186) [src/agents/agent-tools.before-tool-call.ts201-209](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/agent-tools.before-tool-call.ts#L201-L209)

## Sandbox vs Host Tools

The system enforces boundaries between sandboxed and host execution. Configuration for these boundaries is validated to ensure isolation.

- Sandbox Resolution: resolveSandboxConfigForAgent src/auto-reply/reply/agent-runner-memory.ts 17 determines whether an agent should run tools in a Docker container or on the host.
- Workspace Isolation: ensureMemoryFlushTargetFile src/auto-reply/reply/agent-runner-memory.ts 93-115 validates that tool outputs (like memory flushes) remain within the resolved workspaceDir and prevents path traversal.
- Status Monitoring: resolveSandboxRuntimeStatus src/auto-reply/reply/agent-runner-memory.ts 17 provides the runtime with the current health and connectivity of the sandbox environment.

### Sandbox Security Validation

Title: Sandbox Execution Boundary

```

```

Sources: [src/auto-reply/reply/agent-runner-memory.ts17](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L17-L17) [src/auto-reply/reply/agent-runner-memory.ts93-115](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L93-L115) [src/agents/agent-tools.before-tool-call.ts194-200](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/agent-tools.before-tool-call.ts#L194-L200)

## Plugin Tool Integration & MCP

OpenClaw integrates external tools via a plugin system and the Model Context Protocol (MCP).

- MCP Runtime: createBundleMcpToolRuntime src/flows/doctor-core-checks.runtime.ts 4 initializes the environment for MCP-based tools.
- Dynamic Tool Loading: materializeBundleMcpToolsForRun src/agents/agent-bundle-mcp-tools.ts 11 resolves and prepares MCP tools for a specific agent execution turn.
- Schema Validation: createBundleMcpJsonSchemaValidator src/agents/agent-bundle-mcp-runtime.test.ts 6 ensures that tool inputs from the LLM match the expected JSON schema of the plugin or MCP server.
- Tool Metadata: getPluginToolMeta src/flows/doctor-core-checks.runtime.ts 36 retrieves extended metadata for tools provided by plugins, such as icons or specialized UI hints.

### Code Entity Association

Sources: [src/flows/doctor-core-checks.runtime.ts4-36](https://github.com/openclaw/openclaw/blob/fbdf5937/src/flows/doctor-core-checks.runtime.ts#L4-L36) [src/agents/agent-tools.before-tool-call.ts175-200](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/agent-tools.before-tool-call.ts#L175-L200) [src/auto-reply/reply/agent-runner-memory.ts93-115](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L93-L115)
