bash ツールは、Claude にシェルコマンドの実行を要求させ、その結果を返せるようにするツールです。Claude 自身がコマンドを実行するのではなく、あなたのアプリが持つ永続的な bash セッションで実行し、出力を返します。この記事は Anthropic 公式ドキュメントの非公式日本語訳・要約です。
bashツールとは
bash ツールは「クライアントツール」です。Claude はコマンドを自分で実行しません。リクエストにこのツールを含めると、Claude は実行すべきコマンドを名指しした tool_use ブロックを返します。あなたのアプリケーションがそのコマンドを自前の bash セッションで実行し、出力を tool_result ブロックで返します。主な用途は次のとおりです。
- 開発ワークフロー: ビルド・テスト・開発ツールの実行。
- システム自動化: スクリプト実行、ファイル管理、作業の自動化。
- データ処理: ファイル処理、分析スクリプトの実行、データセットの管理。
- 環境構築: パッケージのインストール、環境設定。
ツールの指定方法
bash ツールは Messages API のリクエストに tools として渡します。ツール名は bash、現行バージョンの type は bash_20250124 です。
{
"model": "claude-opus-5",
"max_tokens": 1024,
"tools": [
{
"type": "bash_20250124",
"name": "bash"
}
],
"messages": [
{ "role": "user", "content": "カレントディレクトリの Python ファイルを一覧して" }
]
}対応モデルやベータヘッダ、旧バージョンの識別子については、公式のツールバージョン一覧を確認してください。バージョンによって対応モデルが異なります。
実行の仕組み
bash ツールはクライアントツールなので、実行の主体はあなたのアプリケーションです。典型的な往復は次のようになります。
- ツールを渡してリクエストする: bash ツールを含めて Messages API を呼び出します。
- Claude がコマンドを返す: Claude は実行したいコマンドを
commandパラメータに入れたtool_useブロックを返します。 - アプリがコマンドを実行する: あなたのアプリが自分の管理する bash セッションでそのコマンドを実行します。
- 結果を返す: 標準出力・標準エラーなどの出力を
tool_resultブロックとして返します。Claude はそれを踏まえて次の応答や次のコマンドを返します。
セッションをやり直したい場合は、restart パラメータを使って bash セッションをリセットできます。
セッションの永続性
bash ツールの特徴は、あなたのアプリが1つの bash プロセスをツール呼び出しをまたいで生かし続ける点です。これにより、状態がコマンド間で保持されます。
- 作業ディレクトリ:
cdで移動した場所は、次のコマンドでもそのままです。 - 環境変数: 一度設定した変数は後続のコマンドから参照できます。
- 作成したファイル: あるコマンドが作ったファイルは、次のコマンドからも見えます。
この永続性のおかげで、Claude は「依存関係をインストールしてから、テストを実行する」といった複数段階の作業を、実際のシェルと同じ感覚で進められます。逆に、前のコマンドの副作用が残る点は意識しておく必要があります。
利用時の注意点
- 任意コマンドの実行はリスクがある: Claude が返したコマンドをそのまま実行するため、サンドボックス化、権限の制限、危険なコマンドの遮断など、安全策を実装側で用意します。信頼できない入力をそのまま流さないでください。
- 状態が持ち越される: セッションが永続するため、前のコマンドの副作用（変更したディレクトリや変数）が残ります。必要に応じて
restartでリセットします。 - 実行環境はあなたの責任: どんな環境でコマンドが動くか（利用可能なコマンド、ネットワーク、ファイル）を決めるのはアプリ側です。
- バージョンとモデル:
bash_20250124の対応モデルは決まっています。使用するモデルに合わせて公式リファレンスで確認します。
ファイルを行単位で精密に編集させたい場合はテキストエディタツールも併せて検討してください。正確な仕様・対応モデルは必ず公式ドキュメントで確認してください。