<!-- source: https://deepwiki.com/openclaw/openclaw/3.4-tools-system -->

# Tools System

- docs/automation/tasks.md
- docs/tools/image-generation.md
- docs/tools/media-overview.md
- docs/tools/music-generation.md
- docs/tools/video-generation.md
- packages/gateway-protocol/src/schema/agents-models-skills.test.ts
- 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.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/model-fallback.run-embedded.e2e.test.ts
- src/agents/openclaw-tools.registration.ts
- src/agents/openclaw-tools.ts
- src/agents/openclaw-tools.update-plan.test.ts
- src/agents/subagent-announce-delivery.test.ts
- src/agents/subagent-announce-delivery.ts
- src/agents/subagent-announce-dispatch.test.ts
- src/agents/subagent-announce-dispatch.ts
- src/agents/tool-policy-audit.ts
- src/agents/tool-policy-pipeline.test.ts
- src/agents/tool-policy-pipeline.ts
- src/agents/tools-effective-inventory.test.ts
- src/agents/tools/image-generate-background.test.ts
- src/agents/tools/media-generate-background-shared.test.ts
- src/agents/tools/media-generate-background-shared.ts
- src/agents/tools/media-generate-background.test-support.ts
- src/agents/tools/music-generate-background.test.ts
- src/agents/tools/music-generate-tool.test.ts
- src/agents/tools/music-generate-tool.ts
- src/agents/tools/skill-workshop-tool.test.ts
- src/agents/tools/skill-workshop-tool.ts
- src/agents/tools/video-generate-background.test.ts
- src/auto-reply/reply/agent-runner-memory.test.ts
- src/auto-reply/reply/agent-runner-memory.ts
- src/channels/plugins/package-state-probes.test.ts
- src/channels/plugins/package-state-probes.ts
- src/cli/mcp-cli.test.ts
- src/cli/mcp-cli.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/flows/doctor-core-checks.runtime-errors.test.ts
- src/flows/doctor-core-checks.runtime.test.ts
- src/flows/doctor-core-checks.runtime.ts

The tools system in OpenClaw enables agents to extend their capabilities beyond generating text by invoking structured, typed functions. These tools allow the agent to interact with the local filesystem, execute shell commands, manage background processes, automate browsers, and perform web searches [src/agents/openclaw-tools.ts37-66](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/openclaw-tools.ts#L37-L66) Tool usage is governed by a policy pipeline that ensures security and contextual appropriateness through explicit approvals, session-scoped restrictions, and sandboxing [src/agents/agent-tools.policy.ts1-14](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/agent-tools.policy.ts#L1-L14)

This page provides a high-level overview of the tool system, covering assembly, normalization, execution handlers, and the integration of plugin-based capabilities.

**Related pages:**

- Tool Policies & Filtering - Document tool policy resolution (global/agent/profile/group), owner-only restrictions, sandbox vs host tools, and plugin tool integration.
- Exec & Background Processes - Explain exec/process tools, foreground vs background execution, process registry, session management, and output buffering.
- Memory & Search - Document memory system including MemoryIndexManager, hybrid search (vector + FTS), and memory tools.
- Browser Automation - Document integrated browser control, CDP-based tab control, and agent browser actions.
- Web Search & Fetch - Document web search tool integration (Brave, Perplexity, Tavily, etc.) and SSRF protection.
- Image & Media Tools - Document image generation, PDF processing, and media understanding pipeline.

## Tool Assembly & Lifecycle

OpenClaw assembles available tools for an agent turn by constructing an inventory based on the agent's configuration, active plugins, and available skills. The `createOpenClawTools` function (and specialized factories like `createOpenClawCodingTools`) serves as the core factory for gathering specialized media, messaging, and plugin-contributed tools [src/agents/openclaw-tools.ts80-143](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/openclaw-tools.ts#L80-L143)

The lifecycle of a tool call involves:

1. Inventory Resolution : Determining which tools the agent is allowed to see based on policy, tool profiles (e.g., coding , minimal ), and explicit allowlists src/agents/tool-policy.ts 26 src/agents/agent-tools.policy.ts 1-14
2. Schema Normalization : Adapting tool definitions for specific model providers, including strict type handling for JSON schemas using TypeBox src/agents/tools/music-generate-tool.ts 2 src/agents/tool-schema-projection.ts 27-30
3. Execution Handling : Routing the model's tool call to the appropriate internal handler, such as the execute method of a AnyAgentTool implementation src/agents/tools/music-generate-tool.ts 150-158
4. Result Processing : Capturing output, handling errors, and returning structured data via jsonResult src/agents/tools/common.js 38

### Tool Execution Flow

This diagram bridges the "Natural Language Space" of agent intent to the "Code Entity Space" of the tool execution pipeline.

```

```

Sources: [src/agents/openclaw-tools.ts80-143](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/openclaw-tools.ts#L80-L143) [src/agents/tools/music-generate-tool.ts95-158](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/tools/music-generate-tool.ts#L95-L158) [src/agents/tools/media-generate-background-shared.ts118-163](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/tools/media-generate-background-shared.ts#L118-L163) [src/auto-reply/reply/agent-runner-memory.ts34](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/agent-runner-memory.ts#L34-L34)

## Tool Categories & Discovery

OpenClaw tools are organized into categories that balance local system access with cloud-based capabilities.

### 1. Messaging & Communication

The `message` tool is the primary interface for agents to communicate across platforms like Telegram, Slack, or Discord [src/agents/openclaw-tools.ts50](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/openclaw-tools.ts#L50-L50)

- Subagent Delivery : The deliverSubagentAnnouncement function handles routing results from background tools (like media generation) back to the originating channel src/agents/subagent-announce-delivery.ts 204-213
- Context Preservation : Delivery logic ensures that user-facing session state is preserved for input provenance src/agents/subagent-announce-delivery.ts 135-137

### 2. Media Generation & Background Tasks

OpenClaw supports long-running background tasks for media generation (music, image, video) to avoid blocking the main agent loop [src/agents/tools/media-generate-background-shared.ts31](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/tools/media-generate-background-shared.ts#L31-L31)

- Task Lifecycle : Tools use MediaGenerationTaskLifecycle to manage state from createTaskRun through completeTaskRun src/agents/tools/media-generate-background-shared.ts 103-109
- Detached Execution : Tasks can be detached from the active session, allowing the agent to continue while the media is generated src/agents/tools/media-generate-background-shared.ts 45

### 3. MCP (Model Context Protocol) Integration

OpenClaw integrates with MCP servers to dynamically expand the toolset available to agents [src/agents/agent-bundle-mcp-tools.ts11-14](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/agent-bundle-mcp-tools.ts#L11-L14)

- Runtime Materialization : MCP tools are materialized for a specific run using materializeBundleMcpToolsForRun src/agents/agent-bundle-mcp-tools.ts 11
- Catalog Management : The SessionMcpRuntime tracks tool catalogs and ensures server availability during execution src/agents/agent-bundle-mcp-types.ts 15

Sources: [src/agents/openclaw-tools.ts37-66](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/openclaw-tools.ts#L37-L66) [src/agents/tools/media-generate-background-shared.ts1-109](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/tools/media-generate-background-shared.ts#L1-L109) [src/agents/agent-bundle-mcp-tools.ts1-15](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/agent-bundle-mcp-tools.ts#L1-L15) [src/agents/subagent-announce-delivery.ts1-213](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-announce-delivery.ts#L1-L213)

## Policy & Schema Normalization

OpenClaw ensures that tool definitions are compatible with various LLM providers while maintaining security boundaries.

### Schema Adaptation

The system adapts tool schemas to match provider constraints. The `inspectRuntimeToolInputSchemas` function validates that tools meet the required structure for the target model [src/flows/doctor-core-checks.runtime.ts28-30](https://github.com/openclaw/openclaw/blob/fbdf5937/src/flows/doctor-core-checks.runtime.ts#L28-L30)

### The Policy Pipeline

Tool visibility and execution are governed by a multi-stage pipeline:

1. Effective Policy : resolveEffectiveToolPolicy calculates the final set of allowed tools based on global, agent, and profile settings src/flows/doctor-core-checks.runtime.ts 14
2. Explicit Allowlist : The collectExplicitAllowlist function extracts specific tool names that have been granted execution permission src/flows/doctor-core-checks.runtime.ts 26
3. Media Factory Plan : Media tools (image, music, video) use a specialized factory plan to check availability based on provider capabilities src/agents/openclaw-tools.ts 22-27

### Tool Policy Normalization

This diagram shows how a tool request is processed into a model-ready payload.

```

```

Sources: [src/flows/doctor-core-checks.runtime.ts14-30](https://github.com/openclaw/openclaw/blob/fbdf5937/src/flows/doctor-core-checks.runtime.ts#L14-L30) [src/agents/runtime-plan/tools.ts25](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/runtime-plan/tools.ts#L25-L25)

## Summary of Key Code Entities

Sources: [src/agents/openclaw-tools.ts1-143](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/openclaw-tools.ts#L1-L143) [src/agents/subagent-announce-delivery.ts1-213](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-announce-delivery.ts#L1-L213) [src/agents/tools/media-generate-background-shared.ts1-218](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/tools/media-generate-background-shared.ts#L1-L218) [src/flows/doctor-core-checks.runtime.ts1-40](https://github.com/openclaw/openclaw/blob/fbdf5937/src/flows/doctor-core-checks.runtime.ts#L1-L40)
