diff --git a/docs/configuration/tools.md b/docs/configuration/tools.md index 256acf8..8982c8e 100644 --- a/docs/configuration/tools.md +++ b/docs/configuration/tools.md @@ -25,48 +25,58 @@ Web tools are used for web search and fetching. ### Brave Search -| Config | Type | Default | Description | -| --- | --- | --- | --- | -| `enabled` | bool | false | Enable Brave search | -| `api_key` | string | — | Brave Search API key | -| `max_results` | int | 5 | Maximum number of results | +| Config | Type | Default | Description | +| ------------- | ------ | ------- | ------------------------- | +| `enabled` | bool | false | Enable Brave search | +| `api_key` | string | — | Brave Search API key | +| `max_results` | int | 5 | Maximum number of results | Get a free API key at [brave.com/search/api](https://brave.com/search/api) (2000 free queries/month). ### DuckDuckGo -| Config | Type | Default | Description | -| --- | --- | --- | --- | -| `enabled` | bool | true | Enable DuckDuckGo search | -| `max_results` | int | 5 | Maximum number of results | +| Config | Type | Default | Description | +| ------------- | ---- | ------- | ------------------------- | +| `enabled` | bool | true | Enable DuckDuckGo search | +| `max_results` | int | 5 | Maximum number of results | DuckDuckGo is enabled by default and requires no API key. ### Perplexity -| Config | Type | Default | Description | -| --- | --- | --- | --- | -| `enabled` | bool | false | Enable Perplexity search | -| `api_key` | string | — | Perplexity API key | -| `max_results` | int | 5 | Maximum number of results | +| Config | Type | Default | Description | +| ------------- | ------ | ------- | ------------------------- | +| `enabled` | bool | false | Enable Perplexity search | +| `api_key` | string | — | Perplexity API key | +| `max_results` | int | 5 | Maximum number of results | ### Tavily -| Config | Type | Default | Description | -| --- | --- | --- | --- | -| `enabled` | bool | false | Enable Tavily search | -| `api_key` | string | — | Tavily API key | -| `base_url` | string | — | Custom Tavily API base URL | -| `max_results` | int | 5 | Maximum number of results | +| Config | Type | Default | Description | +| ------------- | ------ | ------- | -------------------------- | +| `enabled` | bool | false | Enable Tavily search | +| `api_key` | string | — | Tavily API key | +| `base_url` | string | — | Custom Tavily API base URL | +| `max_results` | int | 5 | Maximum number of results | + +### GLM (智谱) + +| Config | Type | Default | Description | +| --------------- | ------ | ------------ | ----------------------------------------------------------------------------- | +| `enabled` | bool | false | Enable GLM search | +| `api_key` | string | — | GLM API key | +| `base_url` | string | — | Custom GLM API base URL | +| `search_engine` | string | search_std | Search backend type (search_pro, search_pro_sogou, or search_pro_quark) | +| `max_results` | int | 5 | Maximum number of results | ### Web Proxy All web tools (search and fetch) can use a shared proxy: -| Config | Type | Default | Description | -| --- | --- | --- | --- | -| `proxy` | string | — | Proxy URL for all web tools (http, https, socks5) | -| `fetch_limit_bytes` | int64 | 10485760 | Maximum bytes to fetch per URL (default 10MB) | +| Config | Type | Default | Description | +| ------------------- | ------ | -------- | ------------------------------------------------- | +| `proxy` | string | — | Proxy URL for all web tools (http, https, socks5) | +| `fetch_limit_bytes` | int64 | 10485760 | Maximum bytes to fetch per URL (default 10MB) | ### Web Tools Configuration Example @@ -98,30 +108,30 @@ All web tools (search and fetch) can use a shared proxy: PicoClaw supports MCP servers for extending agent capabilities with external tools. -| Config | Type | Default | Description | -| --- | --- | --- | --- | -| `enabled` | bool | false | Enable MCP integration | -| `servers` | object | {} | Named MCP server configurations | +| Config | Type | Default | Description | +| --------- | ------ | ------- | ------------------------------- | +| `enabled` | bool | false | Enable MCP integration | +| `servers` | object | {} | Named MCP server configurations | Each MCP server supports two connection modes: **stdio mode** (local process): -| Config | Type | Description | -| --- | --- | --- | -| `enabled` | bool | Enable this server | -| `command` | string | Command to run (e.g., `npx`) | -| `args` | array | Command arguments | -| `env` | object | Environment variables | -| `env_file` | string | Path to env file | +| Config | Type | Description | +| ---------- | ------ | ---------------------------- | +| `enabled` | bool | Enable this server | +| `command` | string | Command to run (e.g., `npx`) | +| `args` | array | Command arguments | +| `env` | object | Environment variables | +| `env_file` | string | Path to env file | **HTTP/SSE mode** (remote server): -| Config | Type | Description | -| --- | --- | --- | -| `enabled` | bool | Enable this server | -| `type` | string | `"http"` or `"sse"` | -| `url` | string | Server URL | +| Config | Type | Description | +| --------- | ------ | ----------------------------- | +| `enabled` | bool | Enable this server | +| `type` | string | `"http"` or `"sse"` | +| `url` | string | Server URL | | `headers` | object | HTTP headers (e.g., API keys) | ### MCP Configuration Example @@ -160,11 +170,11 @@ MCP tools are registered with the naming convention `mcp__` and ap The exec tool executes shell commands on behalf of the agent. -| Config | Type | Default | Description | -| --- | --- | --- | --- | -| `enable_deny_patterns` | bool | true | Enable default dangerous command blocking | -| `custom_deny_patterns` | array | [] | Custom deny patterns (regular expressions) | -| `custom_allow_patterns` | array | [] | Custom allow patterns — matching commands bypass deny checks | +| Config | Type | Default | Description | +| ----------------------- | ----- | ------- | ------------------------------------------------------------ | +| `enable_deny_patterns` | bool | true | Enable default dangerous command blocking | +| `custom_deny_patterns` | array | [] | Custom deny patterns (regular expressions) | +| `custom_allow_patterns` | array | [] | Custom allow patterns — matching commands bypass deny checks | ### Default Blocked Command Patterns @@ -192,9 +202,7 @@ Use `custom_allow_patterns` to explicitly permit commands that would otherwise b "tools": { "exec": { "enable_deny_patterns": true, - "custom_allow_patterns": [ - "^git push origin main$" - ] + "custom_allow_patterns": ["^git push origin main$"] } } } @@ -207,10 +215,7 @@ Use `custom_allow_patterns` to explicitly permit commands that would otherwise b "tools": { "exec": { "enable_deny_patterns": true, - "custom_deny_patterns": [ - "\\brm\\s+-r\\b", - "\\bkillall\\s+python" - ], + "custom_deny_patterns": ["\\brm\\s+-r\\b", "\\bkillall\\s+python"], "custom_allow_patterns": [] } } @@ -221,21 +226,21 @@ Use `custom_allow_patterns` to explicitly permit commands that would otherwise b The cron tool schedules periodic tasks. -| Config | Type | Default | Description | -| --- | --- | --- | --- | -| `exec_timeout_minutes` | int | 5 | Execution timeout in minutes (0 = no limit) | +| Config | Type | Default | Description | +| ---------------------- | ---- | ------- | ------------------------------------------- | +| `exec_timeout_minutes` | int | 5 | Execution timeout in minutes (0 = no limit) | ## Skills Tool The skills tool manages skill discovery and installation via registries like ClawHub. -| Config | Type | Default | Description | -| --- | --- | --- | --- | -| `registries.clawhub.enabled` | bool | true | Enable ClawHub registry | -| `registries.clawhub.base_url` | string | `https://clawhub.ai` | ClawHub base URL | -| `registries.clawhub.search_path` | string | `/api/v1/search` | Search API path | -| `registries.clawhub.skills_path` | string | `/api/v1/skills` | Skills API path | -| `registries.clawhub.download_path` | string | `/api/v1/download` | Download API path | +| Config | Type | Default | Description | +| ---------------------------------- | ------ | -------------------- | ----------------------- | +| `registries.clawhub.enabled` | bool | true | Enable ClawHub registry | +| `registries.clawhub.base_url` | string | `https://clawhub.ai` | ClawHub base URL | +| `registries.clawhub.search_path` | string | `/api/v1/search` | Search API path | +| `registries.clawhub.skills_path` | string | `/api/v1/skills` | Skills API path | +| `registries.clawhub.download_path` | string | `/api/v1/download` | Download API path | ```json { diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/tools.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/tools.md index 4984e60..53f2fbe 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/tools.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/tools.md @@ -25,48 +25,58 @@ title: 工具配置 ### Brave Search -| 配置项 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `enabled` | bool | false | 启用 Brave 搜索 | -| `api_key` | string | — | Brave Search API Key | -| `max_results` | int | 5 | 最大返回结果数 | +| 配置项 | 类型 | 默认值 | 说明 | +| ------------- | ------ | ------ | -------------------- | +| `enabled` | bool | false | 启用 Brave 搜索 | +| `api_key` | string | — | Brave Search API Key | +| `max_results` | int | 5 | 最大返回结果数 | 在 [brave.com/search/api](https://brave.com/search/api) 免费获取 API Key(每月 2000 次查询)。 ### DuckDuckGo -| 配置项 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `enabled` | bool | true | 启用 DuckDuckGo 搜索 | -| `max_results` | int | 5 | 最大返回结果数 | +| 配置项 | 类型 | 默认值 | 说明 | +| ------------- | ---- | ------ | -------------------- | +| `enabled` | bool | true | 启用 DuckDuckGo 搜索 | +| `max_results` | int | 5 | 最大返回结果数 | DuckDuckGo 默认启用,无需 API Key。 ### Perplexity -| 配置项 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `enabled` | bool | false | 启用 Perplexity 搜索 | -| `api_key` | string | — | Perplexity API Key | -| `max_results` | int | 5 | 最大返回结果数 | +| 配置项 | 类型 | 默认值 | 说明 | +| ------------- | ------ | ------ | -------------------- | +| `enabled` | bool | false | 启用 Perplexity 搜索 | +| `api_key` | string | — | Perplexity API Key | +| `max_results` | int | 5 | 最大返回结果数 | ### Tavily -| 配置项 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `enabled` | bool | false | 启用 Tavily 搜索 | -| `api_key` | string | — | Tavily API Key | -| `base_url` | string | — | 自定义 Tavily API 地址 | -| `max_results` | int | 5 | 最大返回结果数 | +| 配置项 | 类型 | 默认值 | 说明 | +| ------------- | ------ | ------ | ---------------------- | +| `enabled` | bool | false | 启用 Tavily 搜索 | +| `api_key` | string | — | Tavily API Key | +| `base_url` | string | — | 自定义 Tavily API 地址 | +| `max_results` | int | 5 | 最大返回结果数 | + +### GLM (智谱) + +| 配置项 | 类型 | 默认值 | 说明 | +| --------------- | ------ | ------------ | ------------------------------------------------------------------ | +| `enabled` | bool | false | 启用 GLM 搜索 | +| `api_key` | string | — | GLM API key | +| `base_url` | string | — | 自定义 GLM API 地址 | +| `search_engine` | string | search_std | 搜索后端 (search_pro, search_pro_sogou, or search_pro_quark) | +| `max_results` | int | 5 | 最大返回结果数 | ### 网络代理 所有网络工具(搜索和抓取)可共享同一个代理: -| 配置项 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `proxy` | string | — | 所有网络工具的代理地址(支持 http、https、socks5) | -| `fetch_limit_bytes` | int64 | 10485760 | 每次 URL 抓取的最大字节数(默认 10MB) | +| 配置项 | 类型 | 默认值 | 说明 | +| ------------------- | ------ | -------- | -------------------------------------------------- | +| `proxy` | string | — | 所有网络工具的代理地址(支持 http、https、socks5) | +| `fetch_limit_bytes` | int64 | 10485760 | 每次 URL 抓取的最大字节数(默认 10MB) | ### 网络搜索配置示例 @@ -98,30 +108,30 @@ DuckDuckGo 默认启用,无需 API Key。 PicoClaw 支持 MCP 服务器,通过外部工具扩展 Agent 能力。 -| 配置项 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `enabled` | bool | false | 启用 MCP 集成 | -| `servers` | object | {} | 命名的 MCP 服务器配置 | +| 配置项 | 类型 | 默认值 | 说明 | +| --------- | ------ | ------ | --------------------- | +| `enabled` | bool | false | 启用 MCP 集成 | +| `servers` | object | {} | 命名的 MCP 服务器配置 | 每个 MCP 服务器支持两种连接模式: **stdio 模式**(本地进程): -| 配置项 | 类型 | 说明 | -| --- | --- | --- | -| `enabled` | bool | 启用此服务器 | -| `command` | string | 要运行的命令(如 `npx`) | -| `args` | array | 命令参数 | -| `env` | object | 环境变量 | -| `env_file` | string | 环境变量文件路径 | +| 配置项 | 类型 | 说明 | +| ---------- | ------ | ------------------------ | +| `enabled` | bool | 启用此服务器 | +| `command` | string | 要运行的命令(如 `npx`) | +| `args` | array | 命令参数 | +| `env` | object | 环境变量 | +| `env_file` | string | 环境变量文件路径 | **HTTP/SSE 模式**(远程服务器): -| 配置项 | 类型 | 说明 | -| --- | --- | --- | -| `enabled` | bool | 启用此服务器 | -| `type` | string | `"http"` 或 `"sse"` | -| `url` | string | 服务器 URL | +| 配置项 | 类型 | 说明 | +| --------- | ------ | --------------------- | +| `enabled` | bool | 启用此服务器 | +| `type` | string | `"http"` 或 `"sse"` | +| `url` | string | 服务器 URL | | `headers` | object | HTTP 头(如 API Key) | ### MCP 配置示例 @@ -160,11 +170,11 @@ MCP 工具以 `mcp_<服务器名>_<工具名>` 的命名格式注册,与内置 Exec 工具代替 Agent 在系统上执行 Shell 命令。 -| 配置项 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `enable_deny_patterns` | bool | true | 启用默认危险命令拦截 | -| `custom_deny_patterns` | array | [] | 自定义拦截正则表达式 | -| `custom_allow_patterns` | array | [] | 自定义允许规则 — 匹配的命令可绕过拦截检查 | +| 配置项 | 类型 | 默认值 | 说明 | +| ----------------------- | ----- | ------ | ----------------------------------------- | +| `enable_deny_patterns` | bool | true | 启用默认危险命令拦截 | +| `custom_deny_patterns` | array | [] | 自定义拦截正则表达式 | +| `custom_allow_patterns` | array | [] | 自定义允许规则 — 匹配的命令可绕过拦截检查 | ### 默认拦截的危险命令 @@ -192,9 +202,7 @@ PicoClaw 默认拦截以下命令: "tools": { "exec": { "enable_deny_patterns": true, - "custom_allow_patterns": [ - "^git push origin main$" - ] + "custom_allow_patterns": ["^git push origin main$"] } } } @@ -207,10 +215,7 @@ PicoClaw 默认拦截以下命令: "tools": { "exec": { "enable_deny_patterns": true, - "custom_deny_patterns": [ - "\\brm\\s+-r\\b", - "\\bkillall\\s+python" - ], + "custom_deny_patterns": ["\\brm\\s+-r\\b", "\\bkillall\\s+python"], "custom_allow_patterns": [] } } @@ -219,21 +224,21 @@ PicoClaw 默认拦截以下命令: ## Cron 工具(定时任务) -| 配置项 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `exec_timeout_minutes` | int | 5 | 任务执行超时时间(分钟),0 表示不限制 | +| 配置项 | 类型 | 默认值 | 说明 | +| ---------------------- | ---- | ------ | -------------------------------------- | +| `exec_timeout_minutes` | int | 5 | 任务执行超时时间(分钟),0 表示不限制 | ## Skills 工具(技能商店) Skills 工具管理通过注册表(如 ClawHub)发现和安装技能。 -| 配置项 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `registries.clawhub.enabled` | bool | true | 启用 ClawHub 注册表 | -| `registries.clawhub.base_url` | string | `https://clawhub.ai` | ClawHub 地址 | -| `registries.clawhub.search_path` | string | `/api/v1/search` | 搜索 API 路径 | -| `registries.clawhub.skills_path` | string | `/api/v1/skills` | 技能 API 路径 | -| `registries.clawhub.download_path` | string | `/api/v1/download` | 下载 API 路径 | +| 配置项 | 类型 | 默认值 | 说明 | +| ---------------------------------- | ------ | -------------------- | ------------------- | +| `registries.clawhub.enabled` | bool | true | 启用 ClawHub 注册表 | +| `registries.clawhub.base_url` | string | `https://clawhub.ai` | ClawHub 地址 | +| `registries.clawhub.search_path` | string | `/api/v1/search` | 搜索 API 路径 | +| `registries.clawhub.skills_path` | string | `/api/v1/skills` | 技能 API 路径 | +| `registries.clawhub.download_path` | string | `/api/v1/download` | 下载 API 路径 | ```json {