Tools Configuration

PicoClaw's tools configuration is located in the tools field of config.json.

Directory Structure

{
  "tools": {
    "web": {
      ...
    },
    "mcp": {
      ...
    },
    "exec": {
      ...
    },
    "cron": {
      ...
    },
    "skills": {
      ...
    }
  }
}

Sensitive Data Filtering

Before tool results are sent to the LLM, PicoClaw can filter sensitive values (API keys, tokens, secrets) from the output. This prevents the LLM from seeing its own credentials.

See Sensitive Data Filtering for full documentation.

Web Tools

Web tools are used for web search and fetching.

Web Fetcher

General settings for fetching and processing webpage content.

Brave

DuckDuckGo

Baidu Search

Baidu Search uses the Qianfan AI Search API, which is AI-powered and optimized for Chinese-language queries.

{
  "tools": {
    "web": {
      "baidu_search": {
        "enabled": true,
        "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
        "max_results": 10
      }
    }
  }
}

Perplexity

Tavily

SearXNG

GLM Search

Additional Web Settings

web_search Tool Parameters

At runtime, the web_search tool accepts the following parameters:

If range is omitted, PicoClaw performs an unrestricted search.

Example web_search Call

{
  "query": "ai agent news",
  "count": 10,
  "range": "w"
}

Exec Tool

The exec tool is used to execute shell commands.

Disabling the Exec Tool

To completely disable the exec tool, set enabled to false:

Via config file:

{
  "tools": {
    "exec": {
      "enabled": false
    }
  }
}

Via environment variable:

PICOCLAW_TOOLS_EXEC_ENABLED=false

Note: When disabled, the agent will not be able to execute shell commands. This also affects the Cron tool's ability to run scheduled shell commands.

Functionality

• enable_deny_patterns: Set to false to completely disable the default dangerous command blocking patterns
• custom_deny_patterns: Add custom deny regex patterns; commands matching these will be blocked

Default Blocked Command Patterns

By default, PicoClaw blocks the following dangerous commands:

• Delete commands: rm -rf, del /f/q, rmdir /s
• Disk operations: format, mkfs, diskpart, dd if=, writing to /dev/sd*
• System operations: shutdown, reboot, poweroff
• Command substitution: $(), ${}, backticks
• Pipe to shell: | sh, | bash
• Privilege escalation: sudo, chmod, chown
• Process control: pkill, killall, kill -9
• Remote operations: curl | sh, wget | sh, ssh
• Package management: apt, yum, dnf, npm install -g, pip install --user
• Containers: docker run, docker exec
• Git: git push, git force
• Other: eval, source *.sh

Known Architectural Limitation

The exec guard only validates the top-level command sent to PicoClaw. It does not recursively inspect child processes spawned by build tools or scripts after that command starts running.

Examples of workflows that can bypass the direct command guard once the initial command is allowed:

• make run
• go run ./cmd/...
• cargo run
• npm run build

This means the guard is useful for blocking obviously dangerous direct commands, but it is not a full sandbox for unreviewed build pipelines. If your threat model includes untrusted code in the workspace, use stronger isolation such as containers, VMs, or an approval flow around build-and-run commands.

Configuration Example

{
  "tools": {
    "exec": {
      "enable_deny_patterns": true,
      "custom_deny_patterns": [
        "\\brm\\s+-r\\b",
        "\\bkillall\\s+python"
      ]
    }
  }
}

Cron Tool

The cron tool is used for scheduling periodic tasks.

For schedule types, execution modes (deliver, agent turn, and command jobs), persistence, and the current command-security gates, see Scheduled Tasks and Cron Jobs.

MCP Tool

The MCP tool enables integration with external Model Context Protocol servers.

If you prefer not to edit JSON manually, PicoClaw also provides an MCP configuration manager CLI:

• picoclaw mcp add — add or update a server (supports --deferred / --no-deferred)
• picoclaw mcp list — list all configured servers with status and deferred state
• picoclaw mcp show <name> — show full details and the tool list for one server
• picoclaw mcp test <name> — connectivity check for one server
• picoclaw mcp remove <name> — remove a server entry
• picoclaw mcp edit — open config.json in $EDITOR for advanced edits

These commands manage the same tools.mcp.servers section documented below. See MCP Server CLI for command syntax, examples, and behavior details.

Tool Discovery (Lazy Loading)

When connecting to multiple MCP servers, exposing hundreds of tools simultaneously can exhaust the LLM's context window and increase API costs. The Discovery feature solves this by keeping MCP tools hidden by default.

Instead of loading all tools, the LLM is provided with a lightweight search tool (using BM25 keyword matching or Regex). When the LLM needs a specific capability, it searches the hidden library. Matching tools are then temporarily "unlocked" and injected into the context for a configured number of turns (ttl).

Global Config

Discovery Config (discovery)

Note: If discovery.enabled is true, you MUST enable at least one search engine (use_bm25 or use_regex), otherwise the application will fail to start.

Per-Server Config

Transport Behavior

• If type is omitted, transport is auto-detected:
  • url is set → sse
  • command is set → stdio
• http and sse both use url + optional headers.
• env and env_file are only applied to stdio servers.

Configuration Examples

1) Stdio MCP server

{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "filesystem": {
          "enabled": true,
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-filesystem",
            "/tmp"
          ]
        }
      }
    }
  }
}

2) Remote SSE/HTTP MCP server

{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "remote-mcp": {
          "enabled": true,
          "type": "sse",
          "url": "https://example.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN"
          }
        }
      }
    }
  }
}

3) Massive MCP setup with Tool Discovery enabled

In this example, the LLM will only see the tool_search_tool_bm25. It will search and unlock Github or Postgres tools dynamically only when requested by the user.

{
  "tools": {
    "mcp": {
      "enabled": true,
      "discovery": {
        "enabled": true,
        "ttl": 5,
        "max_search_results": 5,
        "use_bm25": true,
        "use_regex": false
      },
      "servers": {
        "github": {
          "enabled": true,
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-github"
          ],
          "env": {
            "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
          }
        },
        "postgres": {
          "enabled": true,
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-postgres",
            "postgresql://user:password@localhost/dbname"
          ]
        },
        "slack": {
          "enabled": true,
          "type": "slack",
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-slack"
          ],
          "env": {
            "SLACK_BOT_TOKEN": "YOUR_SLACK_BOT_TOKEN",
            "SLACK_TEAM_ID": "YOUR_SLACK_TEAM_ID"
          }
        }
      }
    }
  }
}

4) Mixed setup: per-server deferred override

Discovery is enabled globally, but filesystem is pinned as always-visible while context7 follows the global default (deferred). aws explicitly opts in to deferred mode even though it is the same as the global default.

{
  "tools": {
    "mcp": {
      "enabled": true,
      "discovery": {
        "enabled": true,
        "ttl": 5,
        "max_search_results": 5,
        "use_bm25": true
      },
      "servers": {
        "filesystem": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
          "deferred": false
        },
        "context7": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@upstash/context7-mcp"]
        },
        "aws": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "aws-mcp-server"],
          "deferred": true
        }
      }
    }
  }
}

Tip: deferred on a per-server basis is independent of discovery.enabled. You can keep discovery.enabled: false globally (all tools visible by default) and still mark individual high-volume servers as "deferred": true to avoid polluting the context with their tools.

Skills Tool

The skills tool configures skill discovery and installation via registries like ClawHub and GitHub.

Registries

Legacy GitHub Config

github.* is deprecated. Use registries.github.* instead. The legacy fields are still supported for compatibility and will be removed later.

Search Settings

Configuration Example

{
  "tools": {
    "skills": {
      "registries": {
        "clawhub": {
          "enabled": true,
          "base_url": "https://clawhub.ai",
          "auth_token": "",
	          "search_path": "",
	          "skills_path": "",
	          "download_path": "",
	          "timeout": 0,
	          "max_zip_size": 0,
	          "max_response_size": 0
        },
        "github": {
          "enabled": true,
          "base_url": "https://github.com",
	          "auth_token": "",
	          "proxy": ""
        }
      },
      "github": {
	        "base_url": "https://github.com",
        "proxy": "",
        "token": ""
      },
      "max_concurrent_searches": 2,
      "search_cache": {
        "max_size": 50,
        "ttl_seconds": 300
      }
    }
  }
}

Environment Variables

All configuration options can be overridden via environment variables with the format PICOCLAW_TOOLS_<SECTION>_<KEY>:

For example:

• PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true
• PICOCLAW_TOOLS_EXEC_ENABLED=false
• PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false
• PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10
• PICOCLAW_TOOLS_MCP_ENABLED=true
• PICOCLAW_TOOLS_MCP_MAX_INLINE_TEXT_CHARS=16384

Note: Nested map-style config (for example tools.mcp.servers.<name>.*) is configured in config.json rather than environment variables.

For MCP tools, tools.mcp.max_inline_text_chars controls how much text result is kept inline in model context. The threshold is counted in Unicode characters (Go runes), not bytes. For example, 16384 means up to 16,384 characters inline, which may occupy more than 16 KB for multibyte text such as CJK. Above this threshold, PicoClaw saves the MCP text result as a local artifact in the agent workspace and gives the model a short note plus a structured [file:...] artifact path instead of injecting the full payload into context.