Bash Tool（バッシュツール）とは？読み方・AnthropicのClaudeでシェルコマンドを実行する公式ツールの使い方・Computer Useとの違いを完全解説

Bash Toolとは

Bash Tool（読み方：バッシュツール）とは、Anthropic Claude APIに標準搭載されたシェル実行ツールのこと。Claudeがツール定義を自分で呼び出して、Pythonスクリプトの起動・ファイル操作・パッケージインストールなどbashコマンドを実行できる仕組みです。type: "bash_20250124"のような型指定でtoolsに含めるだけで使え、独自にツールを設計しなくても安全な永続セッションが手に入ります。

身近な例えで言うと、Bash Toolは「Claudeに与える専用ターミナル」です。会話のたびに別のターミナルが立ち上がるのではなく、同じセッションが維持されたままcdで移動した先や設定した環境変数が次のコマンドに引き継がれます。Anthropicは数千の成功軌跡でこのツールに最適化された訓練を施しているため、自作ツールよりエラー回復が滑らかな点が実務では重要なポイントです。

Bash Toolの読み方

Bash Toolの仕組み

Bash Toolは「Claudeがコマンドを決定する → アプリ側がそれを実行 → 出力をtool_resultとして返す → Claudeがstop_reasonがend_turnになるまでループ」というツール使用の標準フローに乗ります。覚えておきましょう。

主要パラメータ

「セッションが永続する」点はBash Toolの最大の特徴です。重要です。1つ目のコマンドで export PYTHONPATH=... を設定すると、2つ目のコマンドでもその値が有効になります。アプリ側ではDockerコンテナや専用VMを1セッション分立ち上げて、終了時にtearDownするのが標準的な実装パターンです。

tool_use と tool_result の往復

Claudeが stop_reason: "tool_use" を返したら、tool_useブロックのinputにあるコマンドをアプリ側で実行し、その結果をtool_resultブロックに包んで次のmessages.createに含めます。Anthropicの公式SDKを使うとこのループは数行で書けます。実務ではDockerでサンドボックスを切る、stdout/stderrのサイズ上限を設けるなど、安全対策を入れておく必要があります。

Bash Toolの使い方・実例

基本的な使い方（Quick Start）

# Python公式SDKでBash Toolを使う最小例
from anthropic import Anthropic
import subprocess

client = Anthropic()
messages = [{"role": "user", "content": "現在のディレクトリのファイル数を教えて"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=[{"type": "bash_20250124", "name": "bash"}],
        messages=messages,
    )
    if resp.stop_reason == "end_turn":
        print(resp.content[-1].text)
        break
    # tool_useブロックを取り出してコマンドを実行
    tool_use = next(b for b in resp.content if b.type == "tool_use")
    cmd = tool_use.input["command"]
    out = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=10)
    messages.append({"role": "assistant", "content": resp.content})
    messages.append({"role": "user", "content": [{
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": out.stdout + out.stderr
    }]})

よくある実装パターン

パターンA: Dockerサンドボックス内で実行

# dockerコンテナ内でコマンドを実行（推奨）
import docker
container = docker.from_env().containers.run(
    "python:3.12-slim", "sleep infinity",
    detach=True, network_disabled=True, mem_limit="512m"
)
def exec_cmd(cmd):
    res = container.exec_run(["bash", "-c", cmd])
    return res.output.decode()

向いているケース: 本番環境、ユーザーから受けたタスクの自動化、データ分析パイプラインの実行。

避けるべきケース: ホストマシンに直接コマンドを流すこと（重要：絶対NG）。

パターンB: Computer Use・Text Editorと組み合わせる

# 3ツールを同時に渡してフルエージェント化
tools = [
    {"type": "bash_20250124", "name": "bash"},
    {"type": "computer_20250124", "name": "computer", "display_width_px": 1280, "display_height_px": 800},
    {"type": "text_editor_20250124", "name": "str_replace_editor"},
]
resp = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    tools=tools,
    extra_headers={"anthropic-beta": "computer-use-2025-11-24"},
    messages=messages,
)

向いているケース: ブラウザ操作とローカル処理を交互に行うエージェント、Claude Code相当の自律開発タスク。

アンチパターン: ツール結果のサイズを無制限に返す

# NG: 大量出力をそのまま返すとトークンコストが爆発
out = subprocess.run("find /", shell=True, capture_output=True)
return out.stdout  # 数MBになる可能性

tool_resultはClaudeが次のターンで読むため、巨大なログをそのまま返すと入力トークンが急増します。実務では head -c 10000 で切る、grepで絞るなどの実装が必要です。

Bash Toolのメリット・デメリット

メリット

• 独自ツール不要：標準型なのでAnthropicの最適化された軌跡が即使える
• セッション永続：cdや環境変数が引き継がれ、複雑な作業が自然に書ける
• Computer Use・Text Editorとシームレス連携：3点セットでフルエージェント
• 追加トークンが小さい：1呼び出しあたり約245トークンのみ

デメリット

• サンドボックス自前実装が必須：実行環境はアプリ側責任で、ホスト直接実行は危険
• 長時間処理に弱い：1呼び出しあたりのタイムアウトを自分で設計する必要
• 出力サイズ管理が必要：tool_resultが大きいとトークン爆発
• Computer Use併用時はbetaヘッダーが必要：コンピュータ操作と組み合わせると安定度はやや変動

Bash ToolとComputer Use・自作ツールの違い

Bash Toolと混同されやすいのが、Computer Useや自作カスタムツールです。違いを比較表で整理します。

つまり「Bash ToolはCLI操作専用の最適化済みツール、Computer UseはGUI画面操作、独自定義はドメイン特化」と覚えておけば混乱しません。実務ではまずBash Toolを試し、画面が必要ならComputer Use、特殊APIなら独自ツール、というレイヤード戦略が有効です。

Bash Toolに関するよくある誤解

誤解1：「Bash ToolはClaude Codeのbashコマンドと同じ」

なぜそう誤解されるのか：名前と機能が似ているため混同されますが、レイヤーが違います。背景には「Anthropic製品で名前が同じものは中身も同じ」という思い込みがあります。

正しい理解：Claude CodeのbashツールはCLIアプリ内蔵の専用実装で、ローカルマシンに直接アクセスします。一方APIのBash ToolはAPI利用者が用意したサンドボックスで動きます。Anthropicは仕様を共有していますが実装は別です。

誤解2：「Bash Toolはセッション間でも状態が引き継がれる」

なぜそう誤解されるのか：「永続セッション」という説明から、複数のmessages.create呼び出しを跨いでも状態が残ると勘違いされやすい背景があります。

正しい理解：永続するのは1回のmessages.create内のツールループです。新しいmessages.create（=新会話）を始めたらサンドボックスは別になります。長期間状態を保ちたい場合はFiles APIや外部ストレージにファイルを書き出してください。

誤解3：「Bash Toolを使えば自動的に安全」

なぜそう誤解されるのか：Anthropic公式ツールであることから、サンドボックス内蔵だと混同されがちです。理由として「公式提供＝丸ごと安全」のイメージが先行することが挙げられます。

正しい理解：Bash ToolはAPI契約だけを提供し、コマンド実行サンドボックスはAPI利用者が用意します。Dockerコンテナ・gVisor・Firecracker VMなどでホストから隔離するのは利用者の責任です。プロンプトインジェクション対策も自前です。

実務での活用シーン

実務でBash Toolが活躍する代表的な場面を挙げます。

• データ加工パイプライン：CSVのクリーニング、JSONLの抽出、簡易ETLをClaudeに委譲
• ビルド・テスト自動化：「pytest通して」「型チェック走らせて」を自然文で指示
• 運用調査：ログのgrep・集計、Kubernetes podの状態確認、原因特定
• ファイル変換：ffmpeg、ImageMagick、pandocなどCLIツールの組み合わせ
• Computer Use併用：Webアプリ操作とローカルファイル処理を交互に

Bash Toolに関するよくある質問（FAQ）

まとめ

• Bash Tool（バッシュツール）はClaude API標準搭載のシェル実行ツール
• Anthropicが訓練済みなので独自ツールより信頼性・回復力が高い
• セッションは「同一messages.createのループ内で永続」する点を理解する
• サンドボックスは利用者責任。Docker/VM隔離・出力サイズ制限・プロンプトインジェクション対策が必須
• Computer Use・Text Editorと組み合わせるとフルエージェントになる（要betaヘッダー）
• 追加トークンは約245／呼び出しと小さく、コスト面の影響は限定的

参考文献・出典