Bash 工具

此功能符合「Zero Data Retention」（零資料保留），即 ZDR 的資格。當您的組織具有 ZDR 安排時，透過此功能傳送的資料在 API 回應返回後不會被儲存。

Bash 工具讓 Claude 能夠在持久性的 bash 工作階段中執行 shell 命令，從而實現系統操作、腳本執行和命令列自動化。Shell 存取是一項基礎的代理能力。在 Terminal-Bench 2.0（一個使用純 shell 驗證來評估真實世界終端機任務的基準測試）中，Claude 在具備持久性 bash 工作階段存取權限時展現出顯著的效能提升。

概述

Bash 工具為 Claude 提供：

可維持狀態的持久性 bash 工作階段
執行任何 shell 命令的能力
存取環境變數和工作目錄
命令串接和腳本編寫功能

如需模型支援資訊，請參閱工具參考。

使用案例

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

快速入門

運作方式

Bash 工具維持一個持久性工作階段：

Claude 決定要執行的命令
您在 bash shell 中執行該命令
將輸出（stdout 和 stderr）回傳給 Claude
工作階段狀態在命令之間持續保留（環境變數、工作目錄）

參數

參數	必填	說明
`command`	是*	要執行的 bash 命令
`restart`	否	設為 `true` 以重新啟動 bash 工作階段

*除非使用 restart，否則為必填

範例：多步驟自動化

Claude 可以串接命令來完成複雜的任務：

User request:
"Install the requests library and create a simple Python script that
fetches a joke from an API, then run it."

Claude's tool uses:
1. Install package
   {"command": "pip install requests"}

2. Create script
   {"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. Run script
   {"command": "python fetch_joke.py"}

工作階段會在命令之間維持狀態，因此在步驟 2 中建立的檔案可在步驟 3 中使用。

實作 bash 工具

Bash 工具是以無結構描述（schema-less）工具的形式實作。使用此工具時，您不需要像其他工具一樣提供輸入結構描述；該結構描述已內建於 Claude 的模型中，且無法修改。

處理錯誤

實作 bash 工具時，請處理各種錯誤情境：

遵循實作最佳實務

安全性

Bash 工具提供直接的系統存取權限。請實作以下基本安全措施：

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

主要建議

使用 ulimit 設定資源限制
過濾危險命令（sudo、rm -rf 等）
以最低使用者權限執行
監控並記錄所有命令執行

定價

bash 工具會為您的 API 呼叫增加 245 個輸入 token。

以下項目會消耗額外的 token：

命令輸出（stdout/stderr）
錯誤訊息
大型檔案內容

如需完整的定價詳情，請參閱工具使用定價。

常見模式

開發工作流程

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

基於 Git 的檢查點

在長時間執行的代理工作流程中，Git 可作為結構化的復原機制，而不僅僅是儲存變更的方式：

擷取基準： 在任何代理工作開始之前，提交目前的狀態。這是已知良好的起始點。
每個功能一次提交： 每個完成的功能都有自己的提交。如果之後出現問題，這些提交可作為回復點。
在工作階段開始時重建狀態： 讀取 git log 並搭配進度檔案，以了解已完成的工作和接下來的步驟。
失敗時還原： 如果工作出錯，使用 git checkout 還原到最後一個良好的提交，而不是嘗試除錯損壞的狀態。

檔案操作

處理資料：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 應用程式： 僅限命令列
工作階段範圍： Bash 工作階段狀態位於用戶端。API 是無狀態的。您的應用程式負責在回合之間維持 shell 工作階段。
輸出限制： 大型輸出可能會被截斷
不支援串流： 結果在完成後才回傳

與其他工具結合使用

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

如果您同時使用程式碼執行工具，Claude 將可存取兩個獨立的執行環境：您的本機 bash 工作階段和 Anthropic 的沙箱容器。兩者之間不共用狀態。如需提示 Claude 區分不同環境的指引，請參閱將程式碼執行與其他執行工具搭配使用。

後續步驟

工具使用概述

了解如何搭配 Claude 使用工具

文字編輯器工具

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "bash_20250124", "name": "bash"}],
    messages=[
        {"role": "user", "content": "List all Python files in the current directory."}
    ],
)

print(response)

設定 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 session restarted"
        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,
        }

實作安全措施

新增驗證和限制。使用允許清單（allowlist）而非封鎖清單（blocklist），因為封鎖清單容易被繞過。拒絕 shell 運算子，以防止串接命令繞過允許清單：

import shlex

ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}


def validate_command(command):
    # 僅允許明確允許清單中的指令
    try:
        tokens = shlex.split(command)
    except ValueError:
        return False, "Could not parse command"

    if not tokens:
        return False, "Empty command"

    executable = tokens[0]
    if executable not in ALLOWED_COMMANDS:
        return False, f"Command '{executable}' is not in the allowlist"

    # 拒絕會串接額外指令的 shell 運算子
    for token in tokens[1:]:
        if token in SHELL_OPERATORS or token.startswith(("$", "`")):
            return False, f"Shell operator '{token}' is not allowed"

    return True, None

此檢查是第一道防線。若要更強的隔離，請使用 shell=False 執行已驗證的命令，並將 shlex.split(command) 作為引數清單傳入，如此 shell 就不會解譯該字串。

概述

使用案例

快速入門

運作方式

參數

使用範例

範例：多步驟自動化

實作 bash 工具

處理錯誤

命令執行逾時

找不到命令

遵循實作最佳實務

使用命令逾時

安全性

主要建議

定價

常見模式

開發工作流程

基於 Git 的檢查點

檔案操作

系統任務

限制

與其他工具結合使用

後續步驟

權限遭拒

維持工作階段狀態

處理大型輸出

記錄所有命令

清理輸出

概述

使用案例

快速入門

運作方式

參數

範例：多步驟自動化

實作 bash 工具

處理錯誤

遵循實作最佳實務

安全性

主要建議

定價

常見模式

開發工作流程

基於 Git 的檢查點

檔案操作

系統任務

限制

與其他工具結合使用

後續步驟