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 工具与文本编辑器和其他工具结合使用时最为强大。

下一步