Bash 工具讓 Claude 能夠在持續的 bash 會話中執行 shell 命令,允許系統操作、腳本執行和命令列自動化。

概述

Bash 工具為 Claude 提供:

  • 維持狀態的持續 bash 會話
  • 執行任何 shell 命令的能力
  • 存取環境變數和工作目錄
  • 命令鏈接和腳本編寫功能

工具版本

模型工具版本
Claude 4 & Sonnet 3.7bash_20250124
Claude Sonnet 3.5bash_20241022

Claude Sonnet 3.5 在使用 bash 工具時需要 computer-use-2024-10-22 beta 標頭。

Bash 工具在 Claude 4 和 Sonnet 3.7 中普遍可用。

使用案例

  • 開發工作流程:執行建置命令、測試和開發工具
  • 系統自動化:執行腳本、管理檔案、自動化任務
  • 資料處理:處理檔案、執行分析腳本、管理資料集
  • 環境設定:安裝套件、配置環境

快速開始

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[
        {
            "type": "bash_20250124",
            "name": "bash"
        }
    ],
    messages=[
        {"role": "user", "content": "列出當前目錄中的所有 Python 檔案。"}
    ]
)

運作方式

Bash 工具維持一個持續的會話:

  1. Claude 決定要執行什麼命令
  2. 您在 bash shell 中執行命令
  3. 將輸出(stdout 和 stderr)返回給 Claude
  4. 會話狀態在命令之間持續存在(環境變數、工作目錄)

參數

參數必需描述
command是*要執行的 bash 命令
restart設為 true 以重新啟動 bash 會話

*除非使用 restart,否則為必需

範例:多步驟自動化

Claude 可以鏈接命令來完成複雜任務:

# 使用者請求
"安裝 requests 函式庫並建立一個簡單的 Python 腳本,從 API 獲取笑話,然後執行它。"

# Claude 的工具使用:
# 1. 安裝套件
{"command": "pip install requests"}

# 2. 建立腳本
{"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"}

# 3. 執行腳本
{"command": "python fetch_joke.py"}

會話在命令之間維持狀態,因此在步驟 2 中建立的檔案在步驟 3 中可用。


實作 bash 工具

Bash 工具實作為無模式工具。使用此工具時,您不需要像其他工具一樣提供輸入模式;模式內建於 Claude 的模型中且無法修改。

1

設定 bash 環境

建立一個 Claude 可以互動的持續 bash 會話:

import subprocess
import threading
import queue

class BashSession:
    def __init__(self):
        self.process = subprocess.Popen(
            ['/bin/bash'],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            bufsize=0
        )
        self.output_queue = queue.Queue()
        self.error_queue = queue.Queue()
        self._start_readers()
2

處理命令執行

建立一個函數來執行命令並捕獲輸出:

def execute_command(self, command):
    # 將命令發送到 bash
    self.process.stdin.write(command + '\n')
    self.process.stdin.flush()
    
    # 使用超時捕獲輸出
    output = self._read_output(timeout=10)
    return output
3

處理 Claude 的工具呼叫

從 Claude 的回應中提取並執行命令:

for content in response.content:
    if content.type == "tool_use" and content.name == "bash":
        if content.input.get("restart"):
            bash_session.restart()
            result = "Bash 會話已重新啟動"
        else:
            command = content.input.get("command")
            result = bash_session.execute_command(command)
        
        # 將結果返回給 Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }
4

實作安全措施

新增驗證和限制:

def validate_command(command):
    # 阻止危險命令
    dangerous_patterns = ['rm -rf /', 'format', ':(){:|:&};:']
    for pattern in dangerous_patterns:
        if pattern in command:
            return False, f"命令包含危險模式:{pattern}"
    
    # 根據需要新增更多驗證
    return True, None

處理錯誤

實作 bash 工具時,處理各種錯誤情況:

遵循實作最佳實務

安全性

Bash 工具提供直接的系統存取。實作這些基本安全措施:

  • 在隔離環境中執行(Docker/VM)
  • 實作命令過濾和允許清單
  • 設定資源限制(CPU、記憶體、磁碟)
  • 記錄所有已執行的命令

主要建議

  • 使用 ulimit 設定資源約束
  • 過濾危險命令(sudorm -rf 等)
  • 以最小使用者權限執行
  • 監控並記錄所有命令執行

定價

The bash tool adds 245 input tokens to your API calls.

Additional tokens are consumed by:

  • Command outputs (stdout/stderr)
  • Error messages
  • Large file contents

請參閱工具使用定價以獲取完整的定價詳情。

常見模式

開發工作流程

  • 執行測試:pytest && coverage report
  • 建置專案:npm install && npm run build
  • Git 操作:git status && git add . && git commit -m "message"

檔案操作

  • 處理資料:wc -l *.csv && ls -lh *.csv
  • 搜尋檔案:find . -name "*.py" | xargs grep "pattern"
  • 建立備份:tar -czf backup.tar.gz ./data

系統任務

  • 檢查資源:df -h && free -m
  • 程序管理:ps aux | grep python
  • 環境設定:export PATH=$PATH:/new/path && echo $PATH

限制

  • 無互動式命令:無法處理 vimless 或密碼提示
  • 無 GUI 應用程式:僅限命令列
  • 會話範圍:在對話中持續存在,在 API 呼叫之間遺失
  • 輸出限制:大型輸出可能被截斷
  • 無串流:完成後返回結果

與其他工具結合

Bash 工具與文字編輯器和其他工具結合時最為強大。

後續步驟