ContextQMD
Back to Picoclaw

🔧 ツール設定

docs/reference/tools_configuration.ja.md

0.2.817.7 KB
Original Source

🔧 ツール設定

README に戻る

PicoClaw のツール設定は config.json の tools フィールドにあります。

ディレクトリ構造

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

Web ツール

Web ツールはウェブ検索とフェッチに使用されます。

Web Fetcher

ウェブページコンテンツの取得と処理に関する一般設定。

設定項目型デフォルト説明
enabledbooltrueウェブページ取得機能を有効にする。
fetch_limit_bytesint10485760取得するウェブページペイロードの最大サイズ（バイト単位、デフォルトは10MB）。
formatstring"plaintext"取得コンテンツの出力形式。オプション：plaintext または markdown（推奨）。

DuckDuckGo

設定項目型デフォルト説明
enabledbooltrueDuckDuckGo 検索を有効にする
max_resultsint5最大結果数
設定項目型デフォルト説明
enabledboolfalseBaidu 検索を有効にする
api_keystring-Qianfan API キー
base_urlstringhttps://qianfan.baidubce.com/v2/ai_search/web_searchBaidu Search API URL
max_resultsint10最大結果数
json
{
  "tools": {
    "web": {
      "baidu_search": {
        "enabled": true,
        "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
        "max_results": 10
      }
    }
  }
}

Perplexity

設定項目型デフォルト説明
enabledboolfalsePerplexity 検索を有効にする
api_keystring-Perplexity API キー
api_keysstring[]-複数の Perplexity API キー（ローテーション用、api_key より優先）
max_resultsint5最大結果数

Brave

設定項目型デフォルト説明
enabledboolfalseBrave 検索を有効にする
api_keystring-Brave Search API キー
api_keysstring[]-複数の Brave Search API キー（ローテーション用、api_key より優先）
max_resultsint5最大結果数

Tavily

設定項目型デフォルト説明
enabledboolfalseTavily 検索を有効にする
api_keystring-Tavily API キー
base_urlstring-カスタム Tavily API ベース URL
max_resultsint0最大結果数（0 = デフォルト）

SearXNG

設定項目型デフォルト説明
enabledboolfalseSearXNG 検索を有効にする
base_urlstringhttp://localhost:8888SearXNG インスタンス URL
max_resultsint5最大結果数
設定項目型デフォルト説明
enabledboolfalseGLM Search を有効にする
api_keystring-GLM API キー
base_urlstringhttps://open.bigmodel.cn/api/paas/v4/web_searchGLM Search API URL
search_enginestringsearch_std検索エンジンタイプ
max_resultsint5最大結果数

Exec ツール

Exec ツールはシェルコマンドの実行に使用されます。

設定項目型デフォルト説明
enabledbooltrueExec ツールを有効にする
enable_deny_patternsbooltrueデフォルトの危険コマンドブロックを有効にする
custom_deny_patternsarray[]カスタム拒否パターン（正規表現）

Exec ツールの無効化

exec ツールを完全に無効にするには、enabled を false に設定します：

設定ファイル経由：

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

環境変数経由：

bash
PICOCLAW_TOOLS_EXEC_ENABLED=false

注意： 無効にすると、エージェントはシェルコマンドを実行できなくなります。これは Cron ツールがスケジュールされたシェルコマンドを実行する能力にも影響します。

機能

  • 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
  • コマンド置換：$()、${}、バッククォート
  • シェルへのパイプ：| 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

これは、明らかに危険な直接コマンドのブロックには有用ですが、未レビューのビルドパイプラインに対する完全なサンドボックスではありません。脅威モデルにワークスペース内の信頼できないコードが含まれる場合は、コンテナ、VM、またはビルド・実行コマンドに対する承認フローなど、より強力な分離を使用してください。

設定例

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

Cron ツール

Cron ツールは定期タスクのスケジューリングに使用されます。

設定項目型デフォルト説明
exec_timeout_minutesint5実行タイムアウト（分）、0 は無制限

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

MCP ツール

MCP ツールは外部の Model Context Protocol サーバーとの統合を可能にします。

ツールディスカバリ（遅延読み込み）

複数の MCP サーバーに接続する場合、数百のツールを同時に公開すると LLM のコンテキストウィンドウを使い果たし、API コストが増加する可能性があります。Discovery 機能は、MCP ツールをデフォルトで非表示にすることでこの問題を解決します。

すべてのツールを読み込む代わりに、LLM には軽量な検索ツール（BM25 キーワードマッチングまたは正規表現を使用）が提供されます。LLM が特定の機能を必要とする場合、非表示のライブラリを検索します。一致するツールは一時的に「アンロック」され、設定されたターン数（ttl）の間コンテキストに注入されます。

グローバル設定

設定項目型デフォルト説明
enabledboolfalseMCP 統合をグローバルに有効にする
discoveryobject{}ツールディスカバリ設定（下記参照）
serversobject{}サーバー名からサーバー設定へのマップ

Discovery 設定（discovery）

設定項目型デフォルト説明
enabledboolfalsetrue の場合、MCP ツールは非表示になり、検索を通じてオンデマンドで読み込まれます。false の場合、すべてのツールが読み込まれます
ttlint5発見されたツールがアンロック状態を維持する会話ターン数
max_search_resultsint5検索クエリごとに返されるツールの最大数
use_bm25booltrue自然言語/キーワード検索ツール（tool_search_tool_bm25）を有効にする。警告：正規表現検索よりリソースを消費します
use_regexboolfalse正規表現パターン検索ツール（tool_search_tool_regex）を有効にする

注意： discovery.enabled が true の場合、少なくとも1つの検索エンジン（use_bm25 または use_regex）を有効にする必要があります。 そうしないとアプリケーションの起動に失敗します。

サーバーごとの設定

設定項目型必須説明
enabledboolはいこの MCP サーバーを有効にする
typestringいいえトランスポートタイプ：stdio、sse、http
commandstringstdiostdio トランスポートの実行コマンド
argsarrayいいえstdio トランスポートのコマンド引数
envobjectいいえstdio プロセスの環境変数
env_filestringいいえstdio プロセスの環境ファイルパス
urlstringsse/httpsse/http トランスポートのエンドポイント URL
headersobjectいいえsse/http トランスポートの HTTP ヘッダー

トランスポートの動作

  • type を省略した場合、トランスポートは自動検出されます：
    • url が設定されている → sse
    • command が設定されている → stdio
  • http と sse はどちらも url + オプションの headers を使用します。
  • env と env_file は stdio サーバーにのみ適用されます。

設定例

1) Stdio MCP サーバー

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

2) リモート SSE/HTTP MCP サーバー

json
{
  "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 のツールを動的に検索してアンロックします。

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

Skills ツール

Skills ツールは ClawHub などのレジストリを通じたスキルの発見とインストールを設定します。

レジストリ

設定項目型デフォルト説明
registries.clawhub.enabledbooltrueClawHub レジストリを有効にする
registries.clawhub.base_urlstringhttps://clawhub.aiClawHub ベース URL
registries.clawhub.auth_tokenstring""より高いレート制限のためのオプションの Bearer トークン
registries.clawhub.search_pathstring/api/v1/search検索 API パス
registries.clawhub.skills_pathstring/api/v1/skillsSkills API パス
registries.clawhub.download_pathstring/api/v1/downloadダウンロード API パス

設定例

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

環境変数

すべての設定オプションは 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 で設定します。