컴퓨터 사용 도구

Claude는 컴퓨터 사용 도구를 통해 컴퓨터 환경과 상호작용할 수 있으며, 이 도구는 스크린샷 기능과 자동화된 데스크톱 상호작용을 위한 마우스/키보드 제어를 제공합니다. 실제 웹사이트 전반에 걸친 자동화된 웹 네비게이션을 위한 벤치마크인 WebArena에서 Claude는 단일 에이전트 시스템 중 최첨단 결과를 달성하며, 다단계 브라우저 작업을 종단 간에 완료할 수 있는 강력한 능력을 보여줍니다.

컴퓨터 사용은 베타 버전이며 베타 헤더가 필요합니다:

Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5의 경우 "computer-use-2025-11-24"
Sonnet 4.5, Haiku 4.5, Opus 4.1, Sonnet 4, Opus 4, Sonnet 3.7의 경우 "computer-use-2025-01-24" (지원 중단됨)

이 기능에 대한 피드백을 공유하려면 피드백 양식을 통해 연락하세요.

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

개요

컴퓨터 사용은 Claude가 데스크톱 환경과 상호작용할 수 있게 해주는 베타 기능입니다. 이 도구는 다음을 제공합니다:

스크린샷 캡처: 현재 화면에 표시되는 내용 확인
마우스 제어: 클릭, 드래그, 커서 이동
키보드 입력: 텍스트 입력 및 키보드 단축키 사용
데스크톱 자동화: 모든 애플리케이션 또는 인터페이스와 상호작용

컴퓨터 사용은 더 포괄적인 자동화 워크플로우를 위해 bash 및 텍스트 편집기와 같은 다른 도구로 보강될 수 있지만, 컴퓨터 사용은 특히 데스크톱 환경을 보고 제어할 수 있는 컴퓨터 사용 도구의 기능을 의미합니다.

모델 지원의 경우 도구 참조를 참조하세요.

보안 고려사항

컴퓨터 사용은 표준 API 기능과 구별되는 고유한 위험이 있는 베타 기능입니다. 이러한 위험은 인터넷과 상호작용할 때 더욱 높아집니다.

위험을 최소화하려면 다음과 같은 예방 조치를 고려하세요:

직접 시스템 공격이나 사고를 방지하기 위해 최소 권한으로 전용 가상 머신 또는 컨테이너를 사용합니다.
정보 도용을 방지하기 위해 계정 로그인 정보와 같은 민감한 데이터에 대한 모델 접근을 피합니다.
악성 콘텐츠 노출을 줄이기 위해 인터넷 접근을 도메인 허용 목록으로 제한합니다.
의미 있는 실제 결과를 초래할 수 있는 결정 및 쿠키 수락, 금융 거래 실행, 서비스 약관 동의와 같이 명시적 동의가 필요한 모든 작업에 대해 인간이 확인하도록 요청합니다.

어떤 경우에는 Claude가 사용자의 지시와 충돌하더라도 콘텐츠에서 발견된 명령을 따를 수 있습니다. 예를 들어, 웹페이지나 이미지에 포함된 Claude 지시사항이 지시사항을 무시하거나 Claude가 실수하도록 할 수 있습니다. 프롬프트 주입과 관련된 위험을 피하기 위해 Claude를 민감한 데이터 및 작업으로부터 격리하기 위한 예방 조치를 취하세요.

모델은 이러한 프롬프트 주입에 저항하도록 훈련되었으며, 추가 방어 계층이 추가되었습니다. 컴퓨터 사용 도구를 사용하면 분류기가 자동으로 프롬프트에서 잠재적 프롬프트 주입 인스턴스를 플래그하기 위해 프롬프트에서 실행됩니다. 이러한 분류기가 스크린샷에서 잠재적 프롬프트 주입을 식별하면 모델을 자동으로 다음 작업을 진행하기 전에 사용자 확인을 요청하도록 유도합니다. 이 추가 보호는 모든 사용 사례에 이상적이지 않을 수 있습니다(예: 인간이 개입하지 않는 사용 사례). 따라서 옵트아웃하고 끄고 싶다면 지원팀에 문의하세요.

이러한 예방 조치는 분류기 방어 계층이 있어도 계속 중요합니다.

최종 사용자에게 관련 위험을 알리고 자신의 제품에서 컴퓨터 사용을 활성화하기 전에 동의를 얻으세요.

컴퓨터 사용 참조 구현

웹 인터페이스, Docker 컨테이너, 예제 도구 구현 및 에이전트 루프를 포함하는 컴퓨터 사용 참조 구현으로 빠르게 시작하세요.

참고: 구현이 Claude 4 모델과 Claude Sonnet 3.7 모두에 대한 새로운 도구를 포함하도록 업데이트되었습니다. 이러한 새로운 기능에 접근하려면 리포지토리의 최신 버전을 가져와야 합니다.

빠른 시작

컴퓨터 사용을 시작하는 방법은 다음과 같습니다:

베타 헤더는 컴퓨터 사용 도구에만 필요합니다.

위의 예제는 세 가지 도구가 모두 함께 사용되는 것을 보여주며, 컴퓨터 사용 도구를 포함하기 때문에 베타 헤더가 필요합니다.

컴퓨터 사용 작동 방식

Claude에 컴퓨터 사용 도구 및 사용자 프롬프트 제공
- API 요청에 컴퓨터 사용 도구(및 선택적으로 다른 도구)를 추가합니다.
- 데스크톱 상호작용이 필요한 사용자 프롬프트를 포함합니다. 예를 들어, "내 데스크톱에 고양이 사진을 저장하세요."
Claude가 컴퓨터 사용 도구를 사용하기로 결정
- Claude는 컴퓨터 사용 도구가 사용자의 쿼리에 도움이 될 수 있는지 평가합니다.
- 그렇다면 Claude는 올바르게 형식화된 도구 사용 요청을 구성합니다.
- API 응답에는 Claude의 의도를 나타내는 tool_use의 stop_reason이 있습니다.
도구 입력을 추출하고, 컴퓨터에서 도구를 평가하고, 결과를 반환
- 귀사 측에서 Claude의 요청에서 도구 이름과 입력을 추출합니다.
- 컨테이너 또는 가상 머신에서 도구를 사용합니다.
- tool_result 콘텐츠 블록을 포함하는 새로운 user 메시지로 대화를 계속합니다.
Claude가 작업을 완료할 때까지 계속 컴퓨터 사용 도구를 호출

3단계와 4단계의 반복을 사용자 입력 없이 "에이전트 루프"라고 합니다(즉, Claude가 도구 사용 요청으로 응답하고 애플리케이션이 해당 요청을 평가한 결과로 Claude에 응답합니다).

컴퓨팅 환경

컴퓨터 사용은 Claude가 애플리케이션 및 웹과 안전하게 상호작용할 수 있는 샌드박스 컴퓨팅 환경이 필요합니다. 이 환경에는 다음이 포함됩니다:

가상 디스플레이: Claude가 스크린샷을 통해 볼 수 있고 마우스/키보드 작업으로 제어할 데스크톱 인터페이스를 렌더링하는 가상 X11 디스플레이 서버(Xvfb 사용).
데스크톱 환경: Claude가 상호작용할 수 있는 일관된 그래픽 인터페이스를 제공하는 Linux에서 실행되는 창 관리자(Mutter) 및 패널(Tint2)이 있는 경량 UI.
애플리케이션: Claude가 작업을 완료하는 데 사용할 수 있는 Firefox, LibreOffice, 텍스트 편집기, 파일 관리자와 같은 사전 설치된 Linux 애플리케이션.
도구 구현: Claude의 추상 도구 요청(예: "마우스 이동" 또는 "스크린샷 촬영")을 가상 환경의 실제 작업으로 변환하는 통합 코드.
에이전트 루프: Claude와 환경 간의 통신을 처리하고, Claude의 작업을 환경으로 보내고, 결과(스크린샷, 명령 출력)를 Claude로 반환하는 프로그램.

컴퓨터 사용을 사용할 때 Claude는 이 환경에 직접 연결되지 않습니다. 대신 애플리케이션은:

Claude의 도구 사용 요청을 받습니다.
이를 컴퓨팅 환경의 작업으로 변환합니다.
결과(스크린샷, 명령 출력 등)를 캡처합니다.
이러한 결과를 Claude로 반환합니다.

보안 및 격리를 위해 참조 구현은 환경을 보고 상호작용하기 위한 적절한 포트 매핑이 있는 Docker 컨테이너 내에서 모든 것을 실행합니다.

컴퓨터 사용을 구현하는 방법

참조 구현으로 시작

컴퓨터 사용을 빠르게 시작하는 데 필요한 모든 것을 포함하는 참조 구현을 사용할 수 있습니다:

Claude와 함께 컴퓨터 사용에 적합한 컨테이너화된 환경
컴퓨터 사용 도구의 구현
Claude API와 상호작용하고 컴퓨터 사용 도구를 실행하는 에이전트 루프
컨테이너, 에이전트 루프 및 도구와 상호작용할 수 있는 웹 인터페이스.

에이전트 루프 이해

컴퓨터 사용의 핵심은 "에이전트 루프"입니다. Claude가 도구 작업을 요청하고, 애플리케이션이 이를 실행하고, 결과를 Claude로 반환하는 주기입니다. 다음은 간단한 예제입니다:

async def sampling_loop(
    *,
    model: str,
    messages: list[dict],
    api_key: str,
    max_tokens: int = 4096,
    tool_version: str,
    thinking_budget: int | None = None,
    max_iterations: int = 10,  # Add iteration limit to prevent infinite loops
):
    """
    Claude 컴퓨터 사용 상호작용을 위한 간단한 에이전트 루프입니다.

    이 함수는 다음 간의 왕복을 처리합니다:
    1. Claude에 사용자 메시지 전송
    2. Claude가 도구 사용 요청
    3. 앱이 해당 도구 실행
    4. Claude로 도구 결과 전송
    """
    # 도구 및 API 매개변수 설정
    client = Anthropic(api_key=api_key)
    beta_flag = (
        "computer-use-2025-11-24"
        if "20251124" in tool_version
        else "computer-use-2025-01-24"
    )
    text_editor_type = (
        "text_editor_20250728"
        if "20251124" in tool_version
        else f"text_editor_{tool_version}"
    )

    # 도구 구성 - 이미 다른 곳에서 초기화되어 있어야 합니다.
    tools = [
        {
            "type": f"computer_{tool_version}",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
        },
        {"type": text_editor_type, "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "name": "bash"},
    ]

    # 주 에이전트 루프(무한 API 비용을 방지하기 위한 반복 제한)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # 선택적 thinking 매개변수 설정(Claude Sonnet 3.7용)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

        # Claude API 호출
        response = client.beta.messages.create(
            model=model,
            max_tokens=max_tokens,
            messages=messages,
            tools=tools,
            betas=[beta_flag],
            thinking=thinking,
        )

        # 대화 기록에 Claude의 응답 추가
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # Claude가 도구를 사용했는지 확인
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # 실제 앱에서는 여기서 도구를 실행합니다.
                # 예: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # Claude를 위해 결과 형식화
                tool_results.append(
                    {"type": "tool_result", "tool_use_id": block.id, "content": result}
                )

        # 도구가 사용되지 않으면 Claude가 완료됨 - 최종 메시지 반환
        if not tool_results:
            return messages

        # 다음 Claude 반복을 위해 메시지에 도구 결과 추가
        messages.append({"role": "user", "content": tool_results})

루프는 Claude가 도구를 요청하지 않고 응답할 때까지(작업 완료) 또는 최대 반복 제한에 도달할 때까지 계속됩니다. 이 보안 장치는 예상치 못한 API 비용을 초래할 수 있는 무한 루프를 방지합니다.

이 설명서의 나머지 부분을 읽기 전에 참조 구현을 시도해 보세요.

프롬프팅으로 모델 성능 최적화

최고 품질의 출력을 얻기 위한 몇 가지 팁은 다음과 같습니다:

간단하고 잘 정의된 작업을 지정하고 각 단계에 대한 명시적 지시사항을 제공합니다.
Claude는 때때로 결과를 명시적으로 확인하지 않고 작업의 결과를 가정합니다. 이를 방지하려면 Claude에 각 단계 후에 스크린샷을 촬영하고 올바른 결과를 달성했는지 신중하게 평가합니다. 명시적으로 생각을 보여주세요: "나는 단계 X를 평가했습니다..." 올바르지 않으면 다시 시도합니다. 단계가 올바르게 실행되었음을 확인한 후에만 다음 단계로 이동합니다.로 프롬프트합니다.
일부 UI 요소(드롭다운 및 스크롤바 등)는 Claude가 마우스 이동을 사용하여 조작하기 어려울 수 있습니다. 이 문제가 발생하면 모델에 키보드 단축키를 사용하도록 프롬프트해 보세요.
반복 가능한 작업이나 UI 상호작용의 경우 성공적인 결과의 예제 스크린샷 및 도구 호출을 프롬프트에 포함합니다.
모델이 로그인해야 하는 경우 프롬프트에서 <robot_credentials> xml 태그 내에 사용자 이름과 암호를 제공합니다. 로그인이 필요한 애플리케이션 내에서 컴퓨터 사용을 사용하면 프롬프트 주입으로 인한 나쁜 결과의 위험이 증가합니다. 모델에 로그인 자격증명을 제공하기 전에 프롬프트 주입 완화 가이드를 검토하세요.

반복적으로 명확한 문제 집합을 만나거나 Claude가 완료해야 할 작업을 미리 알고 있다면 시스템 프롬프트를 사용하여 Claude에 작업을 성공적으로 수행하는 방법에 대한 명시적 팁이나 지시사항을 제공합니다.

여러 세션에 걸친 에이전트의 경우 구현 후에만이 아니라 각 세션의 시작 부분에서 종단 간 검증을 실행합니다. 브라우저 기반 검사는 코드 수준 검토만으로는 놓칠 수 있는 이전 세션의 회귀를 포착합니다. 자세한 내용은 장기 실행 에이전트를 위한 효과적인 하네스를 참조하세요.

시스템 프롬프트

Anthropic 스키마 도구 중 하나가 Claude API를 통해 요청될 때 컴퓨터 사용 관련 시스템 프롬프트가 생성됩니다. 이는 도구 사용 시스템 프롬프트와 유사하지만 다음으로 시작합니다:

사용자의 질문에 답변하기 위해 사용할 수 있는 함수 집합에 접근할 수 있습니다. 여기에는 샌드박스 컴퓨팅 환경에 대한 접근이 포함됩니다. 현재 아래 함수를 호출하는 것을 제외하고는 파일을 검사하거나 외부 리소스와 상호작용할 수 있는 능력이 없습니다.

일반 도구 사용과 마찬가지로 사용자 제공 system_prompt 필드는 여전히 존중되며 결합된 시스템 프롬프트 구성에 사용됩니다.

사용 가능한 작업

컴퓨터 사용 도구는 다음 작업을 지원합니다:

기본 작업(모든 버전)

screenshot - 현재 디스플레이 캡처
left_click - 좌표 [x, y]에서 클릭
type - 텍스트 문자열 입력
key - 키 또는 키 조합 누르기(예: "ctrl+s")
mouse_move - 커서를 좌표로 이동

향상된 작업(computer_20250124) Claude 4 모델 및 Claude Sonnet 3.7에서 사용 가능:

scroll - 모든 방향으로 스크롤하고 양 제어
left_click_drag - 좌표 간 클릭 및 드래그
right_click, middle_click - 추가 마우스 버튼
double_click, triple_click - 여러 클릭
left_mouse_down, left_mouse_up - 세밀한 클릭 제어
hold_key - 지정된 기간(초) 동안 키 누르기
wait - 작업 간 일시 중지

향상된 작업(computer_20251124) Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5에서 사용 가능:

computer_20250124의 모든 작업
zoom - 화면의 특정 영역을 전체 해상도로 봅니다. 도구 정의에서 enable_zoom: true가 필요합니다. 검사할 영역의 왼쪽 위 및 오른쪽 아래 모서리를 정의하는 좌표 [x1, y1, x2, y2]가 있는 region 매개변수를 사용합니다.

도구 매개변수

매개변수	필수	설명
`type`	예	도구 버전(`computer_20251124` 또는 `computer_20250124`)
`name`	예	"computer"여야 함
`display_width_px`	예	픽셀 단위 디스플레이 너비
`display_height_px`	예	픽셀 단위 디스플레이 높이
`display_number`	아니오	X11 환경의 디스플레이 번호
`enable_zoom`	아니오

중요: 컴퓨터 사용 도구는 애플리케이션에서 명시적으로 실행해야 합니다. Claude는 직접 실행할 수 없습니다. 스크린샷 캡처, 마우스 이동, 키보드 입력 및 기타 작업을 Claude의 요청에 따라 구현할 책임이 있습니다.

확장된 사고와 결합

컴퓨터 사용을 확장된 사고와 결합하는 방법은 확장된 사고를 참조하세요.

다른 도구로 컴퓨터 사용 보강

컴퓨터 사용과 함께 다른 도구를 추가하려면 동일한 tools 배열에 포함합니다. 위의 빠른 시작은 bash 도구 및 텍스트 편집기 도구를 사용하는 이 패턴을 보여줍니다. 동일한 방식으로 자신의 사용자 정의 도구 정의를 추가할 수 있습니다.

사용자 정의 컴퓨터 사용 환경 구축

참조 구현은 컴퓨터 사용을 시작하는 데 도움이 되도록 설계되었습니다. Claude가 컴퓨터를 사용하는 데 필요한 모든 구성 요소를 포함하고 있습니다. 그러나 필요에 맞게 컴퓨터 사용을 위한 자신의 환경을 구축할 수 있습니다. 다음이 필요합니다:

Claude와 함께 컴퓨터 사용에 적합한 가상화되거나 컨테이너화된 환경
Anthropic 스키마 컴퓨터 사용 도구 중 최소 하나의 구현
Claude API와 상호 작용하고 도구 구현을 사용하여 tool_use 결과를 실행하는 에이전트 루프
에이전트 루프를 시작하기 위한 사용자 입력을 허용하는 API 또는 UI

컴퓨터 사용 도구 구현

컴퓨터 사용 도구는 스키마 없는 도구로 구현됩니다. 이 도구를 사용할 때 다른 도구와 달리 입력 스키마를 제공할 필요가 없습니다. 스키마는 Claude의 모델에 내장되어 있으며 수정할 수 없습니다.

오류 처리

컴퓨터 사용 도구를 구현할 때 다양한 오류가 발생할 수 있습니다. 이를 처리하는 방법은 다음과 같습니다:

더 높은 해상도에 대한 좌표 스케일링 처리

Claude Opus 4.7은 긴 모서리에서 최대 2576픽셀을 지원하며, 해당 좌표는 이미지 픽셀과 1

(스케일 팩터 변환이 필요하지 않음). 아래의 1568픽셀 지침은 이전 모델에 적용됩니다.

API는 이미지를 가장 긴 모서리에서 최대 1568픽셀로 제한하고 총 약 1.15메가픽셀입니다(이미지 크기 조정 참조). 예를 들어, 1512x982 화면은 약 1330x864로 다운샘플링됩니다. Claude는 이 더 작은 이미지를 분석하고 해당 공간에서 좌표를 반환하지만, 도구는 원본 화면 공간에서 클릭을 실행합니다.

좌표 변환을 처리하지 않으면 Claude의 클릭 좌표가 대상을 놓칠 수 있습니다.

이를 해결하려면 스크린샷을 직접 크기 조정하고 Claude의 좌표를 다시 확대합니다:

구현 모범 사례 따르기

컴퓨터 사용 제한 사항 이해

컴퓨터 사용 기능은 베타 버전입니다. Claude의 기능은 최첨단이지만, 개발자는 다음의 제한 사항을 알아야 합니다:

지연: 현재 컴퓨터 사용 지연은 인간-AI 상호 작용에서 일반적인 인간 지향 컴퓨터 작업과 비교하여 너무 느릴 수 있습니다. 속도가 중요하지 않은 사용 사례(예: 배경 정보 수집, 자동화된 소프트웨어 테스트)에 신뢰할 수 있는 환경에서 집중합니다.
컴퓨터 비전 정확도 및 신뢰성: Claude는 작업을 생성할 때 특정 좌표를 출력하거나 환각할 때 실수를 할 수 있습니다. Claude Sonnet 3.7은 모델의 추론을 이해하고 잠재적 문제를 식별하는 데 도움이 될 수 있는 사고 기능을 도입합니다.
도구 선택 정확도 및 신뢰성: Claude는 작업을 생성할 때 도구를 선택하거나 예상치 못한 작업을 수행하여 문제를 해결할 때 실수를 하거나 환각할 수 있습니다. 또한 틈새 애플리케이션이나 여러 애플리케이션과 상호 작용할 때 신뢰성이 낮을 수 있습니다. 복잡한 작업을 요청할 때 모델에 신중하게 프롬프트합니다.
스크롤 신뢰성: Claude Sonnet 3.7은 방향 제어가 있는 전용 스크롤 작업을 도입하여 신뢰성을 개선했습니다. 모델은 이제 지정된 양만큼 모든 방향(위/아래/왼쪽/오른쪽)으로 명시적으로 스크롤할 수 있습니다.
스프레드시트 상호 작용: Claude Sonnet 3.7에서 스프레드시트 상호 작용을 위한 마우스 클릭이 개선되었으며, left_mouse_down, left_mouse_up과 같은 더 정확한 마우스 제어 작업과 새로운 수정자 키 지원이 추가되었습니다. 이러한 세분화된 제어를 사용하고 수정자 키를 클릭과 결합하여 셀 선택을 더 신뢰할 수 있게 할 수 있습니다.
소셜 및 통신 플랫폼에서의 계정 생성 및 콘텐츠 생성: Claude는 웹사이트를 방문하지만, Claude의 계정을 생성하거나 소셜 미디어 웹사이트 및 플랫폼에서 콘텐츠를 생성 및 공유하거나 인간 사칭에 참여할 수 있는 능력은 제한적입니다. 이 기능은 향후 업데이트될 수 있습니다.
취약점: 탈옥 또는 프롬프트 주입과 같은 취약점은 베타 컴퓨터 사용 API를 포함한 최첨단 AI 시스템 전반에 걸쳐 지속될 수 있습니다. 어떤 경우에는 Claude가 콘텐츠에서 발견된 명령을 따르며, 때로는 사용자의 지시와 충돌하기도 합니다. 예를 들어, 웹페이지의 Claude 지시사항이나 이미지에 포함된 지시사항이 지시사항을 무시하거나 Claude가 실수하도록 할 수 있습니다. 다음을 고려합니다: a. 컴퓨터 사용을 최소 권한이 있는 가상 머신 또는 컨테이너와 같은 신뢰할 수 있는 환경으로 제한 b. 엄격한 감시 없이 민감한 계정이나 데이터에 대한 컴퓨터 사용 액세스 제공 회피 c. 애플리케이션에서 컴퓨터 사용 기능을 활성화하거나 요청하기 전에 최종 사용자에게 관련 위험을 알리고 동의 획득

항상 Claude의 컴퓨터 사용 작업 및 로그를 신중하게 검토하고 확인합니다. 완벽한 정확도가 필요하거나 인간의 감시 없이 민감한 사용자 정보를 다루는 작업에는 Claude를 사용하지 마십시오.

데이터 보존

컴퓨터 사용은 클라이언트 측 도구입니다. 모든 스크린샷, 마우스 작업, 키보드 입력 및 세션과 관련된 모든 파일은 Anthropic이 아닌 사용자의 환경에서 캡처되고 저장됩니다. Anthropic은 API 호출의 일부로 실시간으로 스크린샷 이미지 및 작업 요청을 처리하지만 응답이 반환된 후에는 보존하지 않습니다.

애플리케이션이 컴퓨터 사용 데이터가 저장되는 위치와 방법을 제어하므로 컴퓨터 사용은 ZDR 적격입니다. 모든 기능에 걸친 ZDR 적격성은 API 및 데이터 보존을 참조합니다.

가격 책정

Computer use follows the standard tool use pricing. When using the computer use tool:

System prompt overhead: The computer use beta adds 466-499 tokens to the system prompt

Computer use tool token usage:

Model	Input tokens per tool definition
Claude 4.x models	735 tokens
Claude Sonnet 3.7 (deprecated)	735 tokens

Additional token consumption:

Screenshot images (see Vision pricing)
Tool execution results returned to Claude

If you're also using bash or text editor tools alongside computer use, those tools have their own token costs as documented in their respective pages.

다음 단계

참조 구현

완전한 Docker 기반 구현으로 빠르게 시작합니다

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",  # or another compatible model
    max_tokens=1024,
    tools=[
        {
            "type": "computer_20251124",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
            "display_number": 1,
        },
        {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "name": "bash"},
    ],
    messages=[{"role": "user", "content": "Save a picture of a cat to my desktop."}],
    betas=["computer-use-2025-11-24"],
)
print(response)

컴퓨팅 환경 설정
Claude가 상호 작용할 가상 디스플레이를 만들거나 기존 디스플레이에 연결합니다. 이는 일반적으로 Xvfb(X Virtual Framebuffer) 또는 유사한 기술을 설정하는 것을 포함합니다.

작업 핸들러 구현

Claude가 요청할 수 있는 각 작업 유형을 처리하는 함수를 만듭니다:

def handle_computer_action(action_type, params):
    if action_type == "screenshot":
        return capture_screenshot()
    elif action_type == "left_click":
        x, y = params["coordinate"]
        return click_at(x, y)
    elif action_type == "type":
        return type_text(params["text"])
    # ... handle other actions

Claude의 도구 호출 처리

Claude의 응답에서 도구 호출을 추출하고 실행합니다:

for content in response.content:
    if content.type == "tool_use":
        action = content.input["action"]
        result = handle_computer_action(action, content.input)

        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

에이전트 루프 구현

Claude가 작업을 완료할 때까지 계속되는 루프를 만듭니다:

while True:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        max_tokens=4096,
        messages=messages,
        tools=tools,
        betas=["computer-use-2025-11-24"],
    )

    # Check if Claude used any tools
    tool_results = process_tool_calls(response)

    if not tool_results:
        # No more tool use, task complete
        break

    # Continue conversation with tool results
    messages.append({"role": "user", "content": tool_results})

import math


def get_scale_factor(width, height):
    """Calculate scale factor to meet API constraints."""
    long_edge = max(width, height)
    total_pixels = width * height

    long_edge_scale = 1568 / long_edge
    total_pixels_scale = math.sqrt(1_150_000 / total_pixels)

    return min(1.0, long_edge_scale, total_pixels_scale)


# When capturing screenshot
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Resize image to scaled dimensions before sending to Claude
screenshot = capture_and_resize(scaled_width, scaled_height)


# When handling Claude's coordinates, scale them back up
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

개요

보안 고려사항

빠른 시작

컴퓨터 사용 작동 방식

컴퓨팅 환경

컴퓨터 사용을 구현하는 방법

참조 구현으로 시작

에이전트 루프 이해

프롬프팅으로 모델 성능 최적화

시스템 프롬프트

사용 가능한 작업

예제 작업

클릭 및 스크롤 작업과 함께 수정자 키

도구 매개변수

확장된 사고와 결합

다른 도구로 컴퓨터 사용 보강

사용자 정의 컴퓨터 사용 환경 구축

컴퓨터 사용 도구 구현

오류 처리

스크린샷 캡처 실패

잘못된 좌표

더 높은 해상도에 대한 좌표 스케일링 처리

구현 모범 사례 따르기

적절한 디스플레이 해상도 사용

적절한 스크린샷 처리 구현

작업 지연 추가

컴퓨터 사용 제한 사항 이해

데이터 보존

가격 책정

다음 단계

작업 실행 실패

실행 전 작업 검증

디버깅을 위한 작업 로깅