🔧 Configuração de Ferramentas

Voltar ao README

A configuração de ferramentas do PicoClaw está localizada no campo tools do config.json.

Estrutura de diretórios

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

Ferramentas Web

As ferramentas web são usadas para pesquisa e busca de páginas web.

Web Fetcher

Configurações gerais para busca e processamento de conteúdo de páginas web.

DuckDuckGo

Baidu Search

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

Perplexity

Brave

Tavily

SearXNG

GLM Search

Ferramenta Exec

A ferramenta exec é usada para executar comandos shell.

Desabilitando a Ferramenta Exec

Para desabilitar completamente a ferramenta exec, defina enabled como false:

Via arquivo de configuração:

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

Via variável de ambiente:

PICOCLAW_TOOLS_EXEC_ENABLED=false

Nota: Quando desabilitada, o agent não poderá executar comandos shell. Isso também afeta a capacidade da ferramenta Cron de executar comandos shell agendados.

Funcionalidade

• enable_deny_patterns: Defina como false para desabilitar completamente os padrões de bloqueio de comandos perigosos padrão
• custom_deny_patterns: Adicione padrões regex de negação personalizados; comandos correspondentes serão bloqueados

Padrões de comandos bloqueados por padrão

Por padrão, o PicoClaw bloqueia os seguintes comandos perigosos:

• Comandos de exclusão: rm -rf, del /f/q, rmdir /s
• Operações de disco: format, mkfs, diskpart, dd if=, escrita em /dev/sd*
• Operações do sistema: shutdown, reboot, poweroff
• Substituição de comandos: $(), ${}, crases
• Pipe para shell: | sh, | bash
• Escalação de privilégios: sudo, chmod, chown
• Controle de processos: pkill, killall, kill -9
• Operações remotas: curl | sh, wget | sh, ssh
• Gerenciamento de pacotes: apt, yum, dnf, npm install -g, pip install --user
• Contêineres: docker run, docker exec
• Git: git push, git force
• Outros: eval, source *.sh

Limitação arquitetural conhecida

O guarda exec apenas valida o comando de nível superior enviado ao PicoClaw. Ele não inspeciona recursivamente processos filhos gerados por ferramentas de build ou scripts após o início desse comando.

Exemplos de fluxos de trabalho que podem contornar o guarda de comando direto uma vez que o comando inicial é permitido:

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

Isso significa que o guarda é útil para bloquear comandos diretos obviamente perigosos, mas não é um sandbox completo para pipelines de build não revisados. Se seu modelo de ameaça inclui código não confiável no workspace, use isolamento mais forte, como contêineres, VMs ou um fluxo de aprovação em torno de comandos de build e execução.

Exemplo de configuração

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

Ferramenta Cron

A ferramenta cron é usada para agendar tarefas periódicas.

<a id="mcp-tool"></a>

Ferramenta MCP

A ferramenta MCP permite a integração com servidores Model Context Protocol externos.

Descoberta de ferramentas (carregamento preguiçoso)

Ao conectar a vários servidores MCP, expor centenas de ferramentas simultaneamente pode esgotar a janela de contexto do LLM e aumentar os custos de API. O recurso Discovery resolve isso mantendo as ferramentas MCP ocultas por padrão.

Em vez de carregar todas as ferramentas, o LLM recebe uma ferramenta de pesquisa leve (usando correspondência de palavras-chave BM25 ou Regex). Quando o LLM precisa de uma capacidade específica, ele pesquisa a biblioteca oculta. As ferramentas correspondentes são então temporariamente "desbloqueadas" e injetadas no contexto por um número configurado de turnos (ttl).

Configuração global

Configuração Discovery (discovery)

Nota: Se discovery.enabled for true, você deve habilitar pelo menos um mecanismo de pesquisa (use_bm25 ou use_regex), caso contrário a aplicação falhará ao iniciar.

Configuração por servidor

Comportamento do transporte

• Se type for omitido, o transporte é detectado automaticamente:
  • url está definido → sse
  • command está definido → stdio
• http e sse ambos usam url + headers opcionais.
• env e env_file são aplicados apenas a servidores stdio.

Exemplos de configuração

1) Servidor MCP Stdio

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

2) Servidor MCP remoto SSE/HTTP

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

3) Configuração MCP massiva com descoberta de ferramentas habilitada

Neste exemplo, o LLM verá apenas o tool_search_tool_bm25. Ele pesquisará e desbloqueará ferramentas do Github ou Postgres dinamicamente apenas quando solicitado pelo usuário.

{
  "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"
          }
        }
      }
    }
  }
}

<a id="skills-tool"></a>

Ferramenta Skills

A ferramenta skills configura a descoberta e instalação de habilidades via registros como o ClawHub.

Registros

Exemplo de configuração

{
  "tools": {
    "skills": {
      "registries": {
        "clawhub": {
          "enabled": true,
          "base_url": "https://clawhub.ai",
          "auth_token": "",
          "search_path": "/api/v1/search",
          "skills_path": "/api/v1/skills",
          "download_path": "/api/v1/download"
        }
      }
    }
  }
}

Variáveis de ambiente

Todas as opções de configuração podem ser substituídas via variáveis de ambiente com o formato PICOCLAW_TOOLS_<SECTION>_<KEY>:

Por exemplo:

• 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

Nota: Configuração de tipo mapa aninhado (por exemplo tools.mcp.servers.<name>.*) é configurada no config.json em vez de variáveis de ambiente.