Implementation:Openclaw Openclaw ResolveEffectiveToolPolicy

Knowledge Sources	OpenClaw
Domains	Agent_Runtime, Security
Last Updated	2026-02-06 12:00 GMT

Overview

Concrete functions for resolving and evaluating tool execution policies, provided by the OpenClaw agent runtime. Wraps the policy resolution logic that assembles global, agent, provider, and group policy layers into a unified access control decision.

Description

The pi-tools.policy.ts module provides the tool policy resolution and enforcement functions used throughout the agent runtime. The two primary exports are:

resolveEffectiveToolPolicy -- Resolves the complete set of policy layers for a given agent session and model. It returns an object containing the global policy, global provider-specific policy, agent policy, agent provider-specific policy, tool profiles, and additive alsoAllow lists. This is the main entry point for the inference pipeline to understand what tool restrictions apply before building the tool set.

isToolAllowedByPolicies -- Evaluates whether a specific tool name is permitted by an array of policy layers. It requires the tool to pass every active policy (intersection semantics), implementing the multi-layer ACL described in the principle.

Supporting functions include:

• filterToolsByPolicy -- Filters an array of tool objects by a single policy, returning only those that pass the deny/allow evaluation.
• isToolAllowedByPolicyName -- Evaluates a single tool name against a single policy layer.
• resolveSubagentToolPolicy -- Returns the hardcoded + configured deny list for subagent contexts.
• resolveGroupToolPolicy -- Resolves group-specific tool restrictions by consulting channel dock configurations and channel-group policy resolution.

The pattern matching engine compiles allow/deny entries into CompiledPattern objects (exact, wildcard-to-regex, or universal) for efficient repeated evaluation. Tool group names are expanded via expandToolGroups before compilation.

Usage

Call resolveEffectiveToolPolicy during inference setup to determine which policy layers apply, then use filterToolsByPolicy or isToolAllowedByPolicies to filter the tool set before presenting it to the LLM.

Code Reference

Source Location

• Repository: openclaw
• File: src/agents/pi-tools.policy.ts
• Lines: 230-273 (resolveEffectiveToolPolicy), 334-339 (isToolAllowedByPolicies)

Signature

export function resolveEffectiveToolPolicy(params: {
  config?: OpenClawConfig;
  sessionKey?: string;
  modelProvider?: string;
  modelId?: string;
}): {
  agentId: string | undefined;
  globalPolicy: SandboxToolPolicy | undefined;
  globalProviderPolicy: SandboxToolPolicy | undefined;
  agentPolicy: SandboxToolPolicy | undefined;
  agentProviderPolicy: SandboxToolPolicy | undefined;
  profile: string | undefined;
  providerProfile: string | undefined;
  profileAlsoAllow: string[] | undefined;
  providerProfileAlsoAllow: string[] | undefined;
}

export function isToolAllowedByPolicies(
  name: string,
  policies: Array<SandboxToolPolicy | undefined>,
): boolean

Import

import {
  resolveEffectiveToolPolicy,
  isToolAllowedByPolicies,
  filterToolsByPolicy,
  resolveGroupToolPolicy,
  resolveSubagentToolPolicy,
} from "../agents/pi-tools.policy.js";

I/O Contract

Inputs (resolveEffectiveToolPolicy)

Name	Type	Required	Description
config	OpenClawConfig	No	The runtime configuration containing tool policy definitions.
sessionKey	string	No	Session key used to derive the agent ID and resolve agent-specific policies.
modelProvider	string	No	The LLM provider identifier for provider-specific policy resolution.
modelId	string	No	The model identifier for model-specific policy resolution (checked as provider/model).

Inputs (isToolAllowedByPolicies)

Name	Type	Required	Description
name	string	Yes	The tool name to evaluate.
policies	undefined>	Yes	Array of policy layers to check. undefined entries are treated as permissive (no restriction).

Outputs (resolveEffectiveToolPolicy)

Name	Type	Description
agentId	undefined	The derived agent ID from the session key.
globalPolicy	undefined	The global-level allow/deny policy.
globalProviderPolicy	undefined	Provider-specific policy from global tools.byProvider.
agentPolicy	undefined	Agent-level allow/deny policy.
agentProviderPolicy	undefined	Provider-specific policy from agent tools.byProvider.
profile	undefined	Named tool profile (e.g., "safe").
providerProfile	undefined	Provider-specific tool profile override.
profileAlsoAllow	undefined	Additive allow entries applied at the profile stage.
providerProfileAlsoAllow	undefined	Provider-specific additive allow entries.

Outputs (isToolAllowedByPolicies)

Name	Type	Description
(return)	boolean	true if the tool is allowed by all policy layers; false if any layer denies it.

Usage Examples

Basic Usage

import {
  resolveEffectiveToolPolicy,
  isToolAllowedByPolicies,
  filterToolsByPolicy,
} from "../agents/pi-tools.policy.js";

// Resolve all policy layers for the current session
const policies = resolveEffectiveToolPolicy({
  config: cfg,
  sessionKey: "agent:default:telegram:dm:12345",
  modelProvider: "anthropic",
  modelId: "claude-sonnet-4-20250514",
});

// Check if a specific tool is allowed across all layers
const allowed = isToolAllowedByPolicies("exec", [
  policies.globalPolicy,
  policies.globalProviderPolicy,
  policies.agentPolicy,
  policies.agentProviderPolicy,
]);
console.log(`exec allowed: ${allowed}`);

// Filter the full tool set by the agent policy
const filteredTools = filterToolsByPolicy(allTools, policies.agentPolicy);

Related Pages

Implements Principle

• Principle:Openclaw_Openclaw_Tool_Execution_Policy

Uses Heuristic

• Heuristic:Openclaw_Openclaw_Config_Cascade_Resolution