lzh/picoclaw
1
0
Fork 0
mirror of https://github.com/sipeed/picoclaw.git synced 2026-06-12 18:08:54 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
f82fe5a2ec2ee4be4e262d44b32236bb032b487c
picoclaw/docs/ja/tools_configuration.md
T
Cytown 667fc85d54 refactor(config): make config.Channel to multiple instance support 
add new field type to Channel struct
config.channels refactor to channel_list
update config version to 3
update the docs
2026-04-13 22:21:21 +08:00

414 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 🔧 ツール設定
> [README](../../README.ja.md) に戻る
PicoClaw のツール設定は `config.json` の `tools` フィールドにあります。
## ディレクトリ構造
```json
{
"tools": {
"web": {
...
},
"mcp": {
...
},
"exec": {
...
},
"cron": {
...
},
"skills": {
...
}
}
}
```
## Web ツール
Web ツールはウェブ検索とフェッチに使用されます。
### Web Fetcher
ウェブページコンテンツの取得と処理に関する一般設定。
| 設定項目 | 型 | デフォルト | 説明 |
|---------------------|--------|---------------|----------------------------------------------------------------------------------------|
| `enabled` | bool | true | ウェブページ取得機能を有効にする。 |
| `fetch_limit_bytes` | int | 10485760 | 取得するウェブページペイロードの最大サイズ（バイト単位、デフォルトは10MB）。 |
| `format` | string | "plaintext" | 取得コンテンツの出力形式。オプション：`plaintext` または `markdown`（推奨）。 |
### DuckDuckGo
| 設定項目 | 型 | デフォルト | 説明 |
|---------------|------|------------|---------------------------|
| `enabled` | bool | true | DuckDuckGo 検索を有効にする |
| `max_results` | int | 5 | 最大結果数 |
### Baidu Search
| 設定項目 | 型 | デフォルト | 説明 |
|---------------|--------|-----------------------------------------------------------------|-------------------------------|
| `enabled` | bool | false | Baidu 検索を有効にする |
| `api_key` | string | - | Qianfan API キー |
| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | Baidu Search API URL |
| `max_results` | int | 10 | 最大結果数 |
```json
{
"tools": {
"web": {
"baidu_search": {
"enabled": true,
"api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
"max_results": 10
}
}
}
}
```
### Perplexity
| 設定項目 | 型 | デフォルト | 説明 |
|---------------|--------|------------|---------------------------|
| `enabled` | bool | false | Perplexity 検索を有効にする |
| `api_key` | string | - | Perplexity API キー |
| `api_keys` | string[] | - | 複数の Perplexity API キー（ローテーション用、`api_key` より優先） |
| `max_results` | int | 5 | 最大結果数 |
### Brave
| 設定項目 | 型 | デフォルト | 説明 |
|---------------|--------|------------|-----------------------|
| `enabled` | bool | false | Brave 検索を有効にする |
| `api_key` | string | - | Brave Search API キー |
| `api_keys` | string[] | - | 複数の Brave Search API キー（ローテーション用、`api_key` より優先） |
| `max_results` | int | 5 | 最大結果数 |
### Tavily
| 設定項目 | 型 | デフォルト | 説明 |
|---------------|--------|------------|-----------------------------------|
| `enabled` | bool | false | Tavily 検索を有効にする |
| `api_key` | string | - | Tavily API キー |
| `base_url` | string | - | カスタム Tavily API ベース URL |
| `max_results` | int | 0 | 最大結果数（0 = デフォルト） |
### SearXNG
| 設定項目 | 型 | デフォルト | 説明 |
|---------------|--------|--------------------------|---------------------------|
| `enabled` | bool | false | SearXNG 検索を有効にする |
| `base_url` | string | `http://localhost:8888` | SearXNG インスタンス URL |
| `max_results` | int | 5 | 最大結果数 |
### GLM Search
| 設定項目 | 型 | デフォルト | 説明 |
|-----------------|--------|------------------------------------------------------|---------------------------|
| `enabled` | bool | false | GLM Search を有効にする |
| `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 | 最大結果数 |
## Exec ツール
Exec ツールはシェルコマンドの実行に使用されます。
| 設定項目 | 型 | デフォルト | 説明 |
|------------------------|-------|------------|------------------------------------|
| `enabled` | bool | true | Exec ツールを有効にする |
| `enable_deny_patterns` | bool | true | デフォルトの危険コマンドブロックを有効にする |
| `custom_deny_patterns` | array | [] | カスタム拒否パターン（正規表現） |
### 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_minutes` | int | 5 | 実行タイムアウト（分）、0 は無制限 |
## 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` の場合、少なくとも1つの検索エンジン（`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 サーバー
```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"
}
}
}
}
}
}
```
## 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/v1/search` | 検索 API パス |
| `registries.clawhub.skills_path` | string | `/api/v1/skills` | Skills API パス |
| `registries.clawhub.download_path` | string | `/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` で設定します。
Reference in New Issue View Git Blame Copy Permalink