Bash 도구

Claude가 지속적인 bash 세션에서 셸 명령을 실행할 수 있게 하는 bash 도구에 대해 알아보세요.

bash 도구는 Claude가 지속적인 bash 세션에서 셸 명령을 실행할 수 있게 하여 시스템 작업, 스크립트 실행, 명령줄 자동화를 가능하게 합니다.

개요

bash 도구는 Claude에게 다음을 제공합니다:

• 상태를 유지하는 지속적인 bash 세션
• 모든 셸 명령을 실행할 수 있는 능력
• 환경 변수 및 작업 디렉토리에 대한 접근
• 명령 체이닝 및 스크립팅 기능

도구 버전

모델	도구 버전
Claude 4 모델 및 Sonnet 3.7	bash_20250124
Claude Sonnet 3.5 (deprecated)	bash_20241022

Claude Sonnet 3.5 (deprecated)는 bash 도구를 사용할 때 computer-use-2024-10-22 베타 헤더가 필요합니다.

bash 도구는 Claude 4 모델과 Sonnet 3.7에서 일반적으로 사용 가능합니다.

사용 사례

• 개발 워크플로: 빌드 명령, 테스트, 개발 도구 실행
• 시스템 자동화: 스크립트 실행, 파일 관리, 작업 자동화
• 데이터 처리: 파일 처리, 분석 스크립트 실행, 데이터셋 관리
• 환경 설정: 패키지 설치, 환경 구성

빠른 시작

Python

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 셸에서 명령을 실행합니다
3. 출력(stdout 및 stderr)을 Claude에게 반환합니다
4. 세션 상태가 명령 간에 지속됩니다(환경 변수, 작업 디렉토리)

매개변수

매개변수	필수	설명
command	예*	실행할 bash 명령
restart	아니오	bash 세션을 재시작하려면 true로 설정

*restart를 사용하지 않는 경우 필수

사용 예시

// 명령 실행
{
  "command": "ls -la *.py"
}

// 세션 재시작
{
  "restart": true
}

예시: 다단계 자동화

Claude는 복잡한 작업을 완료하기 위해 명령을 연결할 수 있습니다:

# 사용자 요청
"requests 라이브러리를 설치하고 API에서 농담을 가져오는 간단한 Python 스크립트를 만든 다음 실행하세요."

# 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 도구를 구현할 때 다양한 오류 시나리오를 처리합니다:

명령 실행 타임아웃

명령 실행이 너무 오래 걸리는 경우:

{
  "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에 있기 때문에 작동합니다
]

큰 출력 처리

토큰 제한 문제를 방지하기 위해 매우 큰 출력을 자릅니다:

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로 텍스트 파일 보기 및 편집하기