picoclaw/docs/zh/tools_configuration.md

🔧 工具配置

返回 README

PicoClaw 的工具配置位于 config.json 的 tools 字段中。

目录结构

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

敏感数据过滤

在将工具结果发送给 LLM 之前，PicoClaw 可以从输出中过滤敏感值（API 密钥、令牌、密码）。这可以防止 LLM 看到自己的凭据。

详细说明请参阅敏感数据过滤。

配置项	类型	默认值	描述
filter_sensitive_data	bool	true	启用/禁用过滤
filter_min_length	int	8	触发过滤的最小内容长度

Web 工具

Web 工具用于网页搜索和抓取。

Web Fetcher

用于抓取和处理网页内容的通用设置。

配置项	类型	默认值	描述
enabled	bool	true	启用网页抓取功能。
fetch_limit_bytes	int	10485760	抓取网页负载的最大大小，单位为字节（默认 10MB）。
format	string	"plaintext"	抓取内容的输出格式。选项：plaintext 或 markdown（推荐）。

百度搜索

使用千帆 AI 搜索 API，国内访问稳定，中文搜索效果好。

配置项	类型	默认值	描述
enabled	bool	false	启用百度搜索
api_key	string	-	千帆 API 密钥
base_url	string	https://qianfan.baidubce.com/v2/ai_search/web_search	百度搜索 API URL
max_results	int	10	最大结果数

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

Tavily

配置项	类型	默认值	描述
enabled	bool	false	启用 Tavily 搜索
api_key	string	-	Tavily API 密钥
base_url	string	-	自定义 Tavily API 基础 URL
max_results	int	0	最大结果数（0 = 默认）

GLM Search

配置项	类型	默认值	描述
enabled	bool	false	启用 GLM 搜索
api_key	string	-	GLM API 密钥
base_url	string	https://open.bigmodel.cn/api/paas/v4/web_search	GLM Search API URL
search_engine	string	search_std	搜索引擎类型
max_results	int	5	最大结果数

DuckDuckGo

⚠️ 国内访问困难，建议搭配代理使用。

配置项	类型	默认值	描述
enabled	bool	true	启用 DuckDuckGo 搜索
max_results	int	5	最大结果数

Perplexity

⚠️ 国内访问困难，建议搭配代理使用。

配置项	类型	默认值	描述
enabled	bool	false	启用 Perplexity 搜索
api_key	string	-	Perplexity API 密钥
api_keys	string[]	-	多个 API 密钥轮换（优先于 api_key）
max_results	int	5	最大结果数

Brave

⚠️ 国内访问困难，建议搭配代理使用。

配置项	类型	默认值	描述
enabled	bool	false	启用 Brave 搜索
api_key	string	-	Brave Search API 密钥
api_keys	string[]	-	多个 API 密钥轮换（优先于 api_key）
max_results	int	5	最大结果数

SearXNG

配置项	类型	默认值	描述
enabled	bool	false	启用 SearXNG 搜索
base_url	string	http://localhost:8888	SearXNG 实例 URL
max_results	int	5	最大结果数

其他 Web 设置

配置项	类型	默认值	描述
prefer_native	bool	true	优先使用 provider 原生搜索而非配置的搜索引擎
private_host_whitelist	string[]	[]	允许 Web 抓取的私有/内部主机白名单

Exec 工具

Exec 工具用于执行 shell 命令。

配置项	类型	默认值	描述
enabled	bool	true	启用 exec 工具
enable_deny_patterns	bool	true	启用默认的危险命令拦截
custom_deny_patterns	array	[]	自定义拒绝模式（正则表达式）

禁用 Exec 工具

要完全禁用 exec 工具，请将 enabled 设置为 false：

通过配置文件：

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

通过环境变量：

PICOCLAW_TOOLS_EXEC_ENABLED=false

注意： 禁用后，代理将无法执行 shell 命令。这也会影响 Cron 工具运行计划 shell 命令的能力。

功能说明

• enable_deny_patterns：设为 false 可完全禁用默认的危险命令拦截模式
• custom_deny_patterns：添加自定义拒绝正则模式；匹配的命令将被拦截

默认拦截的命令模式

默认情况下，PicoClaw 会拦截以下危险命令：

• 删除命令：rm -rf、del /f/q、rmdir /s
• 磁盘操作：format、mkfs、diskpart、dd if=、写入 /dev/sd*
• 系统操作：shutdown、reboot、poweroff
• 命令替换：$()、${}、反引号
• 管道到 shell：| sh、| bash
• 权限提升：sudo、chmod、chown
• 进程控制：pkill、killall、kill -9
• 远程操作：curl | sh、wget | sh、ssh
• 包管理：apt、yum、dnf、npm install -g、pip install --user
• 容器：docker run、docker exec
• Git：git push、git force
• 其他：eval、source *.sh

已知架构限制

exec 守卫仅验证发送给 PicoClaw 的顶层命令。它不会递归检查该命令启动后由构建工具或脚本生成的子进程。

以下工作流在初始命令被允许后可以绕过直接命令守卫：

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

这意味着守卫对于拦截明显危险的直接命令很有用，但它不是未审查构建管道的完整沙箱。如果你的威胁模型包括工作区中的不受信任代码，请使用更强的隔离措施，如容器、虚拟机或围绕构建和运行命令的审批流程。

配置示例

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

Cron 工具

Cron 工具用于调度周期性任务。

配置项	类型	默认值	描述
exec_timeout_minutes	int	5	执行超时时间（分钟），0 表示无限制
allow_command	bool	false	允许 cron 任务执行 shell 命令

MCP 工具

MCP 工具支持与外部 Model Context Protocol 服务器集成。

工具发现（延迟加载）

当连接多个 MCP 服务器时，同时暴露数百个工具可能会耗尽 LLM 的上下文窗口并增加 API 成本。Discovery 功能通过默认隐藏 MCP 工具来解决此问题。

LLM 不会加载所有工具，而是获得一个轻量级搜索工具（使用 BM25 关键词匹配或正则表达式）。当 LLM 需要特定功能时，它会搜索隐藏的工具库。匹配的工具随后被临时"解锁"并注入上下文中，持续配置的轮数（ttl）。

全局配置

配置项	类型	默认值	描述
enabled	bool	false	全局启用 MCP 集成
discovery	object	{}	工具发现配置（见下文）
servers	object	{}	服务器名称到服务器配置的映射

Discovery 配置（discovery）

配置项	类型	默认值	描述
enabled	bool	false	如果为 true，MCP 工具将被隐藏并按需通过搜索加载。如果为 false，所有工具都会被加载
ttl	int	5	已发现工具保持解锁状态的对话轮数
max_search_results	int	5	每次搜索查询返回的最大工具数
use_bm25	bool	true	启用自然语言/关键词搜索工具（tool_search_tool_bm25）。警告：比正则搜索消耗更多资源
use_regex	bool	false	启用正则模式搜索工具（tool_search_tool_regex）

注意： 如果 discovery.enabled 为 true，你必须启用至少一个搜索引擎（use_bm25 或 use_regex）， 否则应用程序将无法启动。

单服务器配置

配置项	类型	必需	描述
enabled	bool	是	启用此 MCP 服务器
type	string	否	传输类型：stdio、sse、http
command	string	stdio	stdio 传输的可执行命令
args	array	否	stdio 传输的命令参数
env	object	否	stdio 进程的环境变量
env_file	string	否	stdio 进程的环境文件路径
url	string	sse/http	sse/http 传输的端点 URL
headers	object	否	sse/http 传输的 HTTP 头

传输行为

• 如果省略 type，传输方式将自动检测：
  • 设置了 url → sse
  • 设置了 command → stdio
• http 和 sse 都使用 url + 可选的 headers。
• env 和 env_file 仅应用于 stdio 服务器。

配置示例

1) Stdio MCP 服务器

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

2) 远程 SSE/HTTP MCP 服务器

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

3) 启用工具发现的大规模 MCP 设置

在此示例中，LLM 只会看到 tool_search_tool_bm25。它将仅在用户请求时动态搜索并解锁 Github 或 Postgres 工具。

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

Skills 工具

Skills 工具配置通过 ClawHub 等注册表进行技能发现和安装。

注册表

配置项	类型	默认值	描述
registries.clawhub.enabled	bool	true	启用 ClawHub 注册表
registries.clawhub.base_url	string	https://clawhub.ai	ClawHub 基础 URL
registries.clawhub.auth_token	string	""	可选的 Bearer 令牌，用于更高速率限制
registries.clawhub.search_path	string	""	搜索 API 路径
registries.clawhub.skills_path	string	""	Skills API 路径
registries.clawhub.download_path	string	""	下载 API 路径
registries.clawhub.timeout	int	0	请求超时时间（秒），0 = 默认
registries.clawhub.max_zip_size	int	0	技能 zip 最大大小（字节），0 = 默认
registries.clawhub.max_response_size	int	0	API 响应最大大小（字节），0 = 默认

GitHub 集成

配置项	类型	默认值	描述
github.proxy	string	""	GitHub API 请求的 HTTP 代理
github.token	string	""	GitHub 个人访问令牌

搜索设置

配置项	类型	默认值	描述
max_concurrent_searches	int	2	最大并发技能搜索请求数
search_cache.max_size	int	50	最大缓存搜索结果数
search_cache.ttl_seconds	int	300	缓存 TTL（秒）

配置示例

{
  "tools": {
    "skills": {
      "registries": {
        "clawhub": {
          "enabled": true,
          "base_url": "https://clawhub.ai",
          "auth_token": ""
        }
      },
      "github": {
        "proxy": "",
        "token": ""
      },
      "max_concurrent_searches": 2,
      "search_cache": {
        "max_size": 50,
        "ttl_seconds": 300
      }
    }
  }
}

环境变量

所有配置选项都可以通过格式为 PICOCLAW_TOOLS_<SECTION>_<KEY> 的环境变量覆盖：

例如：

• 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

注意：嵌套的映射式配置（例如 tools.mcp.servers.<name>.*）在 config.json 中配置，而非通过环境变量。