Bash 工具

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

概述

Bash 工具為 Claude 提供：

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

工具版本

模型	工具版本
Claude 4 模型和 Sonnet 3.7	`bash_20250124`
Claude Sonnet 3.5 (已棄用)	`bash_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 工具維持持續會話：

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

參數

參數	必需	描述
`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 的模型中且無法修改。

設定 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()

處理命令執行

建立執行命令和捕獲輸出的函數：

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

處理 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
        }

實作安全措施

新增驗證和限制：

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 工具時，處理各種錯誤情況：

命令執行超時

如果命令執行時間過長：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "錯誤：命令在 30 秒後超時",
      "is_error": true
    }
  ]
}

找不到命令

如果命令不存在：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "bash: nonexistentcommand: command not found",
      "is_error": true
    }
  ]
}

權限被拒

如果有權限問題：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "bash: /root/sensitive-file: Permission denied",
      "is_error": true
    }
  ]
}

遵循實作最佳實務

使用命令超時

實作超時以防止命令掛起：

def execute_with_timeout(command, timeout=30):
    try:
        result = subprocess.run(
            command, 
            shell=True, 
            capture_output=True, 
            text=True, 
            timeout=timeout
        )
        return result.stdout + result.stderr
    except subprocess.TimeoutExpired:
        return f"命令在 {timeout} 秒後超時"

維持會話狀態

保持 bash 會話持續以維持環境變數和工作目錄：

# 在同一會話中執行的命令維持狀態
commands = [
    "cd /tmp",
    "echo 'Hello' > test.txt",
    "cat test.txt"  # 這有效，因為我們仍在 /tmp 中
]

處理大型輸出

截斷非常大的輸出以防止 token 限制問題：

def truncate_output(output, max_lines=100):
    lines = output.split('\n')
    if len(lines) > max_lines:
        truncated = '\n'.join(lines[:max_lines])
        return f"{truncated}\n\n... 輸出已截斷（總共 {len(lines)} 行）..."
    return output

記錄所有命令

保留已執行命令的稽核軌跡：

import logging

def log_command(command, output, user_id):
    logging.info(f"使用者 {user_id} 執行：{command}")
    logging.info(f"輸出：{output[:200]}...")  # 記錄前 200 個字元

清理輸出

從命令輸出中移除敏感資訊：

def sanitize_output(output):
    # 移除潛在的機密或憑證
    import re
    # 範例：移除 AWS 憑證
    output = re.sub(r'aws_access_key_id\s*=\s*\S+', 'aws_access_key_id=***', output)
    output = re.sub(r'aws_secret_access_key\s*=\s*\S+', 'aws_secret_access_key=***', output)
    return output

安全性

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

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

主要建議

使用 ulimit 設定資源約束
過濾危險命令（sudo、rm -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

限制

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

與其他工具結合

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

下一步

工具使用概述

了解 Claude 的工具使用

文字編輯器工具

使用 Claude 檢視和編輯文字檔案

第一步

模型與定價

了解 Claude

功能

工具

模型上下文協定 (MCP)

使用案例

提示工程

測試與評估

加強防護機制

法律中心

概述

工具版本

使用案例

快速開始

運作方式

參數

範例：多步驟自動化

實作 bash 工具

處理錯誤

遵循實作最佳實務

安全性

主要建議

定價

常見模式

開發工作流程

檔案操作

系統任務

限制

與其他工具結合

下一步

工具使用概述

文字編輯器工具

第一步

模型與定價

了解 Claude

功能

工具

模型上下文協定 (MCP)

使用案例

提示工程

測試與評估

加強防護機制

法律中心

​概述

​工具版本

​使用案例

​快速開始

​運作方式

​參數

​範例：多步驟自動化

​實作 bash 工具

​處理錯誤

​遵循實作最佳實務

​安全性

​主要建議

​定價

​常見模式

​開發工作流程

​檔案操作

​系統任務

​限制

​與其他工具結合

​下一步

工具使用概述

文字編輯器工具

概述

工具版本

使用案例

快速開始

運作方式

參數

範例：多步驟自動化

實作 bash 工具

處理錯誤

遵循實作最佳實務

安全性

主要建議

定價

常見模式

開發工作流程

檔案操作

系統任務

限制

與其他工具結合

下一步