ツール: 概要

Tools はエージェントの手です。ツールは、モデルが会話の途中で呼び出せる機能であり、シェルコマンドの実行、HTTP URLの取得、ブラウザを開く、ファイルの書き込み、センサーの読み取りを行います。すべてのツール呼び出しは セキュリティポリシー の対象となります。成功した実行には、レシートが有効な場合に ツールレシート を含めることができます。

ツールは zeroclaw CLI のサブコマンドと混同しないでください。CLI コマンドは運用者向けであり、ツールはエージェント向けです。

エージェントは、参照するスキル、ナレッジ、および MCP バンドルを通じてツールを取得します。バンドルがエージェントにどのようにアタッチされるかについては、Agents を参照してください。プロバイダーのツール呼び出しから承認、ディスパッチ、レシート、オブザーバーイベント、および履歴エントリまでのターンレベルのパスについては、Tool execution lifecycle を参照してください。

組み込みツールを追加する前、または組み込みツールを外部連携に置き換える前には、組み込みツール一覧を使って、最も小さく永続的な配置先を選んでください。動作している組み込み連携は、置き換えが実際に存在し、文書化され、独立してレビューされるまで利用可能なままにします。この「置き換えを先に行う」ルールは、承認済みの RFC #6165 ポリシーであり、一覧の 置き換え優先ポリシー セクションに記録されています。

ミニマルおよびフルツール

設定では、minimal を選択しない限り full が使われます。full は、このバイナリに含まれ、既存の設定、前提条件、権限ルールで許可されているすべての組み込みツールを指します。セットアップと設定生成では optional = ["*"] が書き込まれます。[tools] がないファイル、または optional を含まない [tools] セクションも full として読み込まれるため、v0.8.6 にアップグレードしても既存のツールの利用可否は維持されます。既存の明示的な選択は保持されます。

[tools]
optional = ["*"] # すべて; デフォルト

Minimal はオプトインです。Chat では組み込みツールが 11 個、Code/ACP では 8 個になり、Code/ACP では永続メモリツールを引き続き除外します。Chat の 11 個は shell、file_read、file_write、file_edit、glob_search、content_search、memory_recall、memory_store、memory_forget、web_fetch、git_operations です。既存のポリシーは、どちらのカタログも絞り込めます。

[tools]
optional = [] # minimal

最小構成と選択したエクストラでは、呼び出し可能な名前を使用してください:

[tools]
optional = ["calculator", "cron_list", "sessions_history"]

ワイルドカードは名前付きエントリとの和集合です。["*", "calculator"] は ["*"] と同じ選択になり、ツールが重複することはありません。Full で使われるツール数は固定ではなく、設定済みの連携、実行時の機能、ポリシーによって実際のカタログが決まります。すべての連携を有効にするわけではありません。ツールを選択しても、ブラウザやベンダーのCLIがインストールされたり、認証情報が提供されたり、無効化された連携が有効になったり、権限が付与されたりするわけではありません。Full でも、Code/ACP で既存のメモリ除外が維持されます。

選択はコンストラクタが実行される前に行われます。選択されなかったツールは、スキーマやツールカタログのプロンプトテキストを一切追加しません。リスクプロファイル、呼び出し元による絞り込み、承認、パス／ネットワークポリシー、記録は引き続き適用されます。明示的に指定された MCP サーバー、スキル、プラグイン、周辺機器は、既存のアクティベーションおよび権限の経路を維持します。段階的なスキーマ開示は別機能であり、これらの設定には含まれません。

To select minimal, set optional = [] in [tools], or run:

zeroclaw config set tools.optional [] --no-interactive

デーモンは選択内容を変更した後に再読み込みしてください。設定スキーマはバージョン3のままです。既存の[tools]がないファイルに対してzeroclaw config migrateを実行するとoptional = ["*"]が記録されます。通常の保存でも、セレクターの意図は保持されます。

ビルドとアップグレードの手順

リリースマトリクスには10個のターゲットレグがあり、アーカイブ名は変更されていません。Androidは実験的なものであり、失敗が許容されます。公開には残りの9つのターゲットが必要です。2つ目の互換性アーカイブマトリクスや、専用のcompat-toolsイメージはありません。従来のall-features Dockerイメージは、追加のチャネルやハードウェア機能を含め、依然としてdistより広い範囲を対象としています。

dist には tools-compat（tools-saas、tools-coding-cli、tools-external）が含まれます。dist-compat は同じビルドに対する互換性のためのエイリアスです。通常の Cargo デフォルトでは、より小さいままです。カスタムソースビルドではアダプターを省略できます。optional に指定されたコンパイル時に除外された外部アダプターには、明確な診断が出力されます。full は、このバイナリに含まれるアダプターのみを選択し、残りについては何も報告しません。有効化されたベンダー/CLI セクションは、既存の機能不足に関する診断を引き続き保持します。実行時の設定によって、コンパイル時に除外されたコードを追加することはできません。それを復元するには、標準の選択でビルドしてください：

このソースチェックアウトから実行します。実行したいターゲットを指定してください。
TARGET=x86_64-unknown-linux-gnu
FEATURES="$(cargo run --quiet --locked -p xtask --bin generate -- features --selection dist --target "$TARGET")"
cargo build --release --locked --bin zeroclaw --target $TARGET --no-default-features --features "$FEATURES"
Linuxローカルイメージの場合、そのビルドターゲットの機能を解決します。
docker build -t zeroclaw-dist-local .

Homebrew でインストールしていて、その formula に adapters が含まれない場合は、パッケージ管理されたバイナリと並べて標準のソースビルドのバイナリを実行し、それ専用の config、data、service のパスを使用してください。設定項目によって bottle のコンパイル済み機能を変更することはできません。ソースからビルドするユーザーは、既存の tool-* 機能を個別に、または tools-compat を選択することもできますが、実行時の選択は引き続き必要です。

標準のdistには、サポートされている7つのネイティブ64ビットターゲットでプラグインホストとplugins-wasm-craneliftが含まれます。対象はx86_64およびaarch64のGNU・musl Linux、両macOSアーキテクチャ、x86_64 Windows MSVCです。ARMv6/ARMv7ではCraneliftとPrometheusが除外され、実験的なAndroidではCraneliftとWhatsApp Webが除外されます。Cargoのデフォルト設定にはプラグインホストは含まれません。ホストをコンパイルしてもplugins.enabledとplugins.auto_discoverはfalseのままです。同意、信頼、権限付与、および設定によるアクティベーションは引き続き適用されます。実行時専用の事前コンパイル済み.cwasmサポートおよびPulleyは、ポータブルなレジストリ.wasmのコンパイルを代替するものではありません。ターゲットポリシーはCargo.toml内のpackage.metadata.zeroclawから取得されます。

Minimalは実行時のカタログ選択です。標準のdistには依然としてコンパイル済みのネイティブアダプターが含まれるため、minimalだけではバイナリサイズの根拠としてツール抽出作業を示すことはできません。Container、Kubernetes、Nixのデフォルトでは[tools]が省略され、通常の設定と同様にフルで読み込まれます。minimalにするには、これらでoptional = []を設定してください。

組み込みツール

コンパイルされ、選択されている場合に利用可能な組み込み機能は次のとおりです。full を選択すると、これらすべてが有効になります。上記の11ツールの最小セットは別扱いです。このリストはコアセットではありません。コアセットと、ランタイムレジストリが構築する各ツールのティアについては、ティアと保持されるコアセットを参照してください。

AnySearch provider AnySearch プロバイダー

AnySearchはweb_search_toolの明示的にオプトインするバックエンドです:

[web_search]
search_provider = "anysearch"
# 任意。省略すると、AnySearch のより低いレート制限付きの匿名クォータを使用します。
anysearch_api_key = "..."

検索クエリと設定された結果件数の上限は https://api.anysearch.com/v1/search に送信されます。anysearch_api_key が設定されている場合、ZeroClaw はこれを Bearer 認証ヘッダーとしてのみ送信します。キーが設定されていない場合は、Authorization ヘッダーは送信されません。したがって、このプロバイダーを選択すると、匿名モードであっても検索クエリはサードパーティのサービスに送信されます。このプロバイダーはデフォルトのプロバイダーを変更せず、自動フォールバックとしても使用されません。

Additional first-party built-ins, included in full but not in minimal:

選択されたツールには、以下の前提条件も引き続き適用されます:

組み込みのスキーマ検出

Agentのランタイムプロファイルでdeferred_builtin_toolsを有効にすると、ZeroCode Configエディタを通じてモデルに送信される組み込みツールのカタログを削減できます。デフォルトはfalseで、これはスキーマを事前にすべて読み込む動作(eager schema loading)を維持します。この設定はMCPのdeferred_loadingオプションとは独立しています。

有効にすると、許可された shell、file_read、file_write、file_edit、memory_recall、memory_store のスキーマは引き続き表示されます。その他の有効な組み込みツールは、コンパクトな検索リストに表示されます。モデルは tool_search をキーワード付きで使用するか、select:<tool_name> を使用して、完全な定義を取得します。選択されたスキーマは後続のネイティブツールリクエストに表示されます。テキストプロバイダーは、定義を検索結果の中で受け取ります。

探索によって権限が付与されたり、ツールの承認が変更されたりすることは決してありません。セッションがツールを絞り込んだ後も、エージェントポリシー、プリンシパルの制限、呼び出し元の許可リストは引き続き適用されます。組み込み実行ファイルは既存のスコープ付きレジストリに残るため、メモリルーティングが古いツールインスタンスを別途保持することはありません。ポリシーでtool_searchが許可されていない場合、残りの組み込みスキーマは引き続き即時読み込みのままです。ツール一覧エンドポイントは、引き続き許可された完全なレジストリを一覧表示します。

拡張プロトコル

組み込みツールに加えて、ZeroClawは**MCP**（Model Context Protocol）拡張インターフェースをサポートしています。任意のMCPサーバー（Claude Codeのファイルシステム、Playwright、または独自のもの）に接続すると、エージェントは起動時にそのツールを自動的に取得します。

エディターがサブプロセスとして ZeroClaw を駆動する IDE 側の統合については、ACP を参照してください。Agent Client Protocol は、エージェントが呼び出すツールではなく、受信側のセッション管理面であるため、channels 配下に配置されています。

ツールを作成する

zeroclaw-api で Tool トレイトを実装する:

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Tool: Send + Sync + Attributable {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;   // 引数用の JSON スキーマ
    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult>;
}
}

すべての Tool は Attributable でもあるため、ツール呼び出しのログ出力や監査トレースには、ランタイムの他の部分で使用されているものと同じ <kind>.<alias> の帰属情報が付与されます。

ランタイムのツールファクトリ経由で登録します。完全なパターンについては、開発 → プラグインプロトコル を参照してください。

ツールをモデルに説明する

ツールの説明は Mozilla Fluent 文字列です。ツールごとに1つで、ロケールごとにローカライズされます。これにより、モデルのコンテキストウィンドウ内ではツールの説明を簡潔に保ちつつ、UIのローカライズを可能にします。

信頼できる情報源: crates/zeroclaw-runtime/locales/en/tools.ftl。翻訳は cargo fluent fill --locale <code> を介して生成・管理されます（Maintainers → Docs & Translations を参照）。

リスクと承認

すべてのツール呼び出しはリスクによって分類されます：

• 低 (読み取り専用、副作用なし): file_read、memory_recall、許可されたドメインへの http_request GET
• Medium（ローカル状態を変更）: file_write、既知の安全なコマンドを使用する shell
• 高 (破壊的またはリモートの副作用): 不明なコマンドを伴う shell、制約のない URL への http_request POST

自律レベル は、各リスクティアがオペレーターの承認なしに実行できる内容を決定します。デフォルト（Supervised）: 低リスクは実行、中リスクは確認要求、高リスクはブロックします。

レシートが有効な場合、実行に成功するとツールレシートが発行されます。拒否、ブロック、置換、失敗、または中断された呼び出しにはレシートは発行されません。

非CLIチャネルでのツールの無効化

スキーマにはチャネルごとの tools_allow / tools_deny フィールドはありません。ツールのゲーティングはエージェントのリスクプロファイル（[risk_profiles.<alias>]）に存在します。

• excluded_tools は、ローカルの CLI はそのままにしつつ、リストに記載されたツールをすべての非 CLI チャネル（Discord、Telegram、Bluesky、Matrix、Slack など）から削除します。粒度はバイナリ（CLI と非 CLI）であり、チャネルごとではありません。また、実行時に解決されるエージェント委任の許可リストからも差し引かれます。これは、下記のルールによって自動的に許可されてしまう個々の <server>__<tool> MCP 名をブロックする唯一の方法です。
• allowed_tools は許可リストです。省略された場合と、明示的な空リスト（allowed_tools = []）は、同じレガシー状態を意味します。つまり、認可による制約はありません。空でないリストは、組み込みツールに対して閉じた集合となり、（後述のMCP例外により）名前空間付きのMCPツールは自動的に許可されます。空リストは全拒否を意味しません。全拒否にするには、兄弟設定の deny_all_tools = true を設定してください。これは組み込みツール、MCPツール、スキル定義のツールのすべてを拒否します。deny_all_tools = true と空でない allowed_tools の両方を設定することは設定エラーであり、読み込み時に拒否されます。
• MCP 例外: allowed_tools が空でない場合、実行時に検出された MCP ツール（名前に __ を含むもの、<server>__<tool> 規約）は、個別にリストする必要なく、有効な許可リストに自動的に受け入れられます。これにより、#7464 以降の eager-MCP デフォルトが、既に明示的な許可リストを固定しているエージェントでも利用可能になります。個々の MCP ツールをブロックするには、それらを excluded_tools にリストしてください。
• MCP の例外は、リスクプロファイルの allowed_tools にのみ適用されます。呼び出し元が指定する実行ごとの許可リスト（cron ジョブの allowed_tools、絞り込まれた委任呼び出しなど）は、依然として厳密な明示リストの積集合として扱われます。allowed_tools = ["cron_add"] に自身を絞り込んだジョブは、たとえエージェントのリスクプロファイルによって自動的に許可される場合であっても、指定していない実行時検出の MCP ラッパーを表に出しません。

finer-grained gating を行いたい場合は、level = "full" の下でも、機密性の高いツールをプロファイルごとの always_ask リストに登録してください。これらのツールは level = "full" でも引き続き確認を求め（または安全側に倒れて失敗し）ます。プロファイルを read_only や supervised に変更する必要があるのは、リスクティア全体のマトリクスを適用したい場合だけです。一部の例外を設定するだけであれば、その必要はありません。

プロファイルごとのフィールドの完全な一覧については、自律性レベルを参照してください。

関連項目も参照してください

• MCP
• ツール実行のライフサイクル
• ACP
• ブラウザ自動化
• セキュリティ → 概要