Tool Calls

The tool system enables the AI Agent to perform real actions -- running commands, reading and writing files, calling APIs, controlling browsers, and more. OpenClaw supports both built-in tools and plugin-contributed tools.

Tool Definition

Source: src/agents/pi-tools.ts

Tools are registered through a factory pattern. Each time an Agent session is created, the factory functions are called to instantiate the available tools:

// src/agents/pi-tools.ts (simplified)
// OpenClaw built-in tools
// - exec: Execute shell commands
// - read: Read files
// - write: Write files
// - bash: Run bash scripts
// - node-invoke: Invoke remote node capabilities

// Plugin-contributed tools
// via ChannelAgentToolFactory

Built-in Tools

Tool	Description	Security Level
exec	Execute shell commands	Requires approval (non-main sessions)
read	Read files	Path restrictions apply
write	Write files	Path restrictions apply
bash	Run Bash scripts	Requires approval
node-invoke	Invoke remote node capabilities	Node policy restrictions

Plugin Tools

Plugins register tools through PluginToolRegistration:

// Plugin tool registration
interface PluginToolRegistration {
  factory: OpenClawPluginToolFactory;  // Tool factory function
  names: string[];                     // Tool names provided
  optional?: boolean;                  // Can be disabled
}

// Tool factory receives context
type OpenClawPluginToolFactory = (
  ctx: OpenClawPluginToolContext
) => AnyAgentTool | AnyAgentTool[] | null;

The tool factory receives context information:

interface OpenClawPluginToolContext {
  config: PluginConfig;
  workspaceDir: string;       // Agent workspace directory
  agentDir: string;           // Agent-specific directory
  agentId: string;            // Current agent ID
  sessionKey: string;         // Current session key
  messageChannel: string;     // Message source channel
  sandboxed: boolean;         // Is sandbox mode active
}

Tool Policy

Source: src/agents/pi-tool-policy.ts

Tool policies control tool availability and permissions across different contexts:

Security Boundaries

Context	Execution Environment	Description
main session	Host machine	1:1 direct message, fully trusted
group (no sandbox)	Host machine + tool policy	Restricted by tool policy
group (sandbox)	Docker container	Isolated execution, no host filesystem access

Tool Call Handling

Source: src/agents/pi-embedded-subscribe.handlers.tools.ts

When the model requests a tool call, the handling flow is:

Duplicate Detection

// Duplicate detection
function isMessagingToolDuplicateNormalized(
  toolName: string,
  args: unknown,
  previousCalls: ToolMeta[]
): boolean {
  // Normalize arguments
  // Compare with previous calls
  // Return true if duplicate found
}

Tool call duplicate detection prevents the model from repeatedly calling the same tool in a loop.

Result Formatting

Tool results can be formatted in two ways:

Format	Description	Use Case
markdown	Markdown-formatted output	Default, suitable for text replies
plain	Plain text output	Simple data returns

Pending Tool Tracking

The runtime tracks all pending and completed tool calls through the toolMetas array:

// Tool tracking metadata
interface ToolMeta {
  toolCallId: string;
  toolName: string;
  args: unknown;
  status: "pending" | "executing" | "completed" | "failed";
  result?: unknown;
}

Summary

• Tools are registered using a factory pattern, instantiated per session
• Built-in tools (exec, read, write, bash) coexist with plugin tools
• Tool policy controls permissions based on session type and sandbox mode
• Duplicate detection prevents the model from looping on the same tool call
• Tool results support markdown and plain formatting

Next: Streaming