Messages도구

Bash 도구

이 기능은 Zero Data Retention (ZDR)의 적용 대상입니다. 조직에 ZDR 계약이 체결되어 있는 경우, 이 기능을 통해 전송된 데이터는 API 응답이 반환된 후 저장되지 않습니다.

Bash 도구는 Claude가 지속적인 bash 세션에서 셸 명령어를 실행할 수 있게 하여 시스템 작업, 스크립트 실행 및 명령줄 자동화를 가능하게 합니다. 셸 접근은 기본적인 에이전트 기능입니다. 셸 전용 검증을 사용하여 실제 터미널 작업을 평가하는 벤치마크인 Terminal-Bench 2.0에서 Claude는 지속적인 bash 세션에 접근할 때 강력한 성능 향상을 보여줍니다.

개요

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

상태를 유지하는 지속적인 bash 세션
모든 셸 명령어 실행 기능
환경 변수 및 작업 디렉터리 접근
명령어 체이닝 및 스크립팅 기능

모델 지원에 대해서는 도구 참조를 참조하세요.

사용 사례

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

빠른 시작

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

매개변수

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

*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 도구는 스키마가 없는 도구로 구현됩니다. 이 도구를 사용할 때는 다른 도구와 달리 입력 스키마를 제공할 필요가 없습니다. 스키마는 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 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,
        }

안전 조치 구현

검증 및 제한을 추가하세요. 차단 목록은 우회하기 쉬우므로 차단 목록 대신 허용 목록을 사용하세요. 연결된 명령어가 허용 목록을 통과하지 못하도록 셸 연산자를 거부하세요:

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"

    # 추가 명령어를 연결하는 셸 연산자 거부
    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

오류 처리

Bash 도구를 구현할 때 다양한 오류 시나리오를 처리하세요:

구현 모범 사례 따르기

보안

Bash 도구는 직접적인 시스템 접근을 제공합니다. 다음과 같은 필수 안전 조치를 구현하세요:

격리된 환경(Docker/VM)에서 실행
명령어 필터링 및 허용 목록 구현
리소스 제한 설정(CPU, 메모리, 디스크)
실행된 모든 명령어 로깅

주요 권장 사항

ulimit를 사용하여 리소스 제약 설정
위험한 명령어 필터링(sudo, rm -rf 등)
최소 사용자 권한으로 실행
모든 명령어 실행 모니터링 및 로깅

가격

bash 도구는 API 호출에 245개의 입력 토큰을 추가합니다.

다음 항목에 의해 추가 토큰이 소비됩니다:

명령어 출력(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는 상태를 유지하지 않습니다. 턴 간에 셸 세션을 유지하는 것은 애플리케이션의 책임입니다.
출력 제한: 대용량 출력은 잘릴 수 있습니다
스트리밍 없음: 완료 후 결과가 반환됩니다

다른 도구와 결합

Bash 도구는 텍스트 편집기 및 기타 도구와 결합할 때 가장 강력합니다.

코드 실행 도구도 사용하는 경우, Claude는 두 개의 별도 실행 환경에 접근할 수 있습니다: 로컬 bash 세션과 Anthropic의 샌드박스 컨테이너입니다. 상태는 이들 간에 공유되지 않습니다. Claude가 환경을 구분하도록 프롬프트하는 방법에 대한 지침은 다른 실행 도구와 함께 코드 실행 사용하기를 참조하세요.

다음 단계

도구 사용 개요

Claude와 함께 도구 사용에 대해 알아보기

텍스트 편집기 도구

Claude로 텍스트 파일 보기 및 편집하기

Was this page helpful?

Messages도구

Bash 도구

개요

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

상태를 유지하는 지속적인 bash 세션
모든 셸 명령어 실행 기능
환경 변수 및 작업 디렉터리 접근
명령어 체이닝 및 스크립팅 기능

모델 지원에 대해서는 도구 참조를 참조하세요.

사용 사례

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

빠른 시작

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

매개변수

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

*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 환경 설정

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,
        }

안전 조치 구현

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"

    # 추가 명령어를 연결하는 셸 연산자 거부
    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

오류 처리

Bash 도구를 구현할 때 다양한 오류 시나리오를 처리하세요:

구현 모범 사례 따르기

보안

Bash 도구는 직접적인 시스템 접근을 제공합니다. 다음과 같은 필수 안전 조치를 구현하세요:

격리된 환경(Docker/VM)에서 실행
명령어 필터링 및 허용 목록 구현
리소스 제한 설정(CPU, 메모리, 디스크)
실행된 모든 명령어 로깅

주요 권장 사항

ulimit를 사용하여 리소스 제약 설정
위험한 명령어 필터링(sudo, rm -rf 등)
최소 사용자 권한으로 실행
모든 명령어 실행 모니터링 및 로깅

가격

bash 도구는 API 호출에 245개의 입력 토큰을 추가합니다.

다음 항목에 의해 추가 토큰이 소비됩니다:

명령어 출력(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는 상태를 유지하지 않습니다. 턴 간에 셸 세션을 유지하는 것은 애플리케이션의 책임입니다.
출력 제한: 대용량 출력은 잘릴 수 있습니다
스트리밍 없음: 완료 후 결과가 반환됩니다

다른 도구와 결합

Bash 도구는 텍스트 편집기 및 기타 도구와 결합할 때 가장 강력합니다.

다음 단계

도구 사용 개요

Claude와 함께 도구 사용에 대해 알아보기

텍스트 편집기 도구

Claude로 텍스트 파일 보기 및 편집하기

Was this page helpful?

개요

사용 사례

빠른 시작

작동 방식

매개변수

사용 예시

예시: 다단계 자동화

Bash 도구 구현

오류 처리

명령어 실행 시간 초과

명령어를 찾을 수 없음

권한 거부됨

구현 모범 사례 따르기

명령어 시간 제한 사용

세션 상태 유지

대용량 출력 처리

모든 명령어 로깅

출력 정리

보안

주요 권장 사항

가격

일반적인 패턴

개발 워크플로

Git 기반 체크포인트

파일 작업

시스템 작업

제한 사항

다른 도구와 결합

다음 단계

개요

사용 사례

빠른 시작

작동 방식

매개변수

사용 예시

예시: 다단계 자동화

Bash 도구 구현

오류 처리

명령어 실행 시간 초과

명령어를 찾을 수 없음

권한 거부됨

구현 모범 사례 따르기

명령어 시간 제한 사용

세션 상태 유지

대용량 출력 처리

모든 명령어 로깅

출력 정리

보안

주요 권장 사항

가격

일반적인 패턴

개발 워크플로

Git 기반 체크포인트

파일 작업

시스템 작업

제한 사항

다른 도구와 결합

다음 단계

개요

사용 사례

빠른 시작

작동 방식

매개변수

예시: 다단계 자동화

Bash 도구 구현

오류 처리

구현 모범 사례 따르기

보안

주요 권장 사항

가격

일반적인 패턴

개발 워크플로

Git 기반 체크포인트

파일 작업

시스템 작업

제한 사항

다른 도구와 결합

다음 단계

개요

사용 사례

빠른 시작

작동 방식

매개변수

예시: 다단계 자동화

Bash 도구 구현

오류 처리

구현 모범 사례 따르기

보안

주요 권장 사항

가격

일반적인 패턴

개발 워크플로

Git 기반 체크포인트

파일 작업

시스템 작업

제한 사항

다른 도구와 결합

다음 단계