메시지도구

컴퓨터 사용 도구

컴퓨터 사용 도구를 통해 Claude에게 데스크톱 환경의 스크린샷, 마우스, 키보드 제어 권한을 부여하세요.

Claude는 컴퓨터 사용 도구를 통해 컴퓨터 환경과 상호작용할 수 있으며, 이 도구는 자율적인 데스크톱 상호작용을 위한 스크린샷 기능과 마우스/키보드 제어를 제공합니다.

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

Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5의 경우 "computer-use-2025-11-24"
Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.1(지원 중단됨), Claude Sonnet 4(종료됨, Bedrock 및 Google Cloud 제외), Claude Opus 4(종료됨, Google Cloud 제외)의 경우 "computer-use-2025-01-24"

이 기능에 대한 피드백은 피드백 양식을 통해 공유해 주세요.

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

개요

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

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

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

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

보안 고려 사항

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

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

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

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

Anthropic은 이러한 프롬프트 주입에 저항하도록 모델을 학습시켰으며 추가 방어 계층을 더했습니다. 컴퓨터 사용 도구를 사용하면 분류기가 자동으로 프롬프트에서 실행되어 잠재적인 프롬프트 주입 사례를 표시합니다. 이러한 분류기가 스크린샷에서 잠재적인 프롬프트 주입을 식별하면, 다음 작업을 진행하기 전에 사용자 확인을 요청하도록 모델을 자동으로 유도합니다. 이 추가 보호 기능은 모든 사용 사례에 이상적이지는 않으므로(예: 사람이 개입하지 않는 사용 사례), 이를 거부하고 비활성화하려면 지원팀에 문의하세요.

분류기 방어 계층이 있더라도 이러한 예방 조치는 여전히 중요합니다.

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

컴퓨터 사용 참조 구현

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

빠른 시작

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",  # 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에게 컴퓨터 사용 도구와 사용자 프롬프트 제공
- API 요청에 컴퓨터 사용 도구(및 선택적으로 다른 도구)를 추가합니다.
- 데스크톱 상호작용이 필요한 사용자 프롬프트를 포함합니다. 예: "고양이 사진을 내 데스크톱에 저장해 줘."
Claude가 컴퓨터 사용 도구 선택
- Claude는 컴퓨터 사용 도구가 사용자의 질의에 도움이 될 수 있는지 평가합니다.
- 그렇다면 Claude는 적절한 형식의 도구 사용 요청을 구성합니다.
- API 응답의 stop_reason이 tool_use가 되어 도구 사용 요청임을 알립니다.
도구 입력 추출, 컴퓨터에서 도구 평가, 결과 반환
- 사용자 측에서 Claude의 요청으로부터 도구 이름과 입력을 추출합니다.
- 컨테이너 또는 가상 머신에서 도구를 사용합니다.
- tool_result 콘텐츠 블록이 포함된 새 user 메시지로 대화를 계속합니다.
Claude는 작업이 완료될 때까지 컴퓨터 사용 도구를 계속 호출
- Claude는 도구 결과를 분석하여 추가 도구 사용이 필요한지 또는 작업이 완료되었는지 판단합니다.
- Claude가 다른 도구가 필요하다고 판단하면 또 다른 tool_use stop_reason으로 응답하며, 3단계로 돌아가야 합니다.
- 그렇지 않으면 사용자에게 텍스트 응답을 작성합니다.

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

컴퓨팅 환경

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

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

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

Claude의 도구 사용 요청 수신
컴퓨팅 환경에서의 작업으로 변환
결과 캡처(스크린샷 및 명령 출력 등)
이러한 결과를 Claude에게 반환

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

컴퓨터 사용 구현 방법

참조 구현으로 시작하기

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

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

에이전트 루프 이해하기

컴퓨터 사용의 핵심은 "에이전트 루프"입니다. Claude가 도구 작업을 요청하고, 애플리케이션이 이를 실행하고, 결과를 Claude에게 반환하는 주기입니다. 이 루프는 빠른 시작에서 생성한 클라이언트, 빠른 시작의 tools 배열과 같은 형태의 도구 목록, Claude의 도구 호출 처리에 정의된 도구 호출 처리 헬퍼를 사용합니다. 다음은 간단한 예제입니다:

def sampling_loop(model, messages, max_iterations=10):
    """
    Run the computer-use agent loop until Claude stops requesting tools
    or the iteration limit is reached.
    """
    for _ in range(max_iterations):
        response = client.beta.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
            betas=["computer-use-2025-11-24"],
        )

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

        # Claude가 요청한 도구를 실행하고 결과를 수집합니다
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # 다음 반복을 위해 도구 결과를 Claude에 다시 보냅니다
        messages.append({"role": "user", "content": tool_results})

    return messages

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

이 문서의 나머지 부분을 읽기 전에 참조 구현을 사용해 보세요.

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

최고 품질의 출력을 얻는 방법에 대한 몇 가지 팁입니다:

간단하고 잘 정의된 작업을 지정하고 각 단계에 대한 명시적인 지침을 제공하세요.
Claude는 때때로 결과를 명시적으로 확인하지 않고 작업의 결과를 가정합니다. 이를 방지하기 위해 다음과 같이 Claude에게 프롬프트할 수 있습니다: After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. Explicitly show your thinking: "I have evaluated step X..." If not correct, try again. Only when you confirm a step was executed correctly should you move on to the next one.
일부 UI 요소(드롭다운 및 스크롤바 등)는 Claude가 마우스 움직임으로 조작하기 까다로울 수 있습니다. 이런 경우 모델에게 키보드 단축키를 사용하도록 프롬프트해 보세요.
반복 가능한 작업이나 UI 상호작용의 경우, 성공적인 결과의 예제 스크린샷과 도구 호출을 프롬프트에 포함하세요.
모델이 로그인해야 하는 경우, <robot_credentials>와 같은 XML 태그 안에 사용자 이름과 비밀번호를 프롬프트에 제공하세요. 로그인이 필요한 애플리케이션 내에서 컴퓨터 사용을 사용하면 프롬프트 주입으로 인한 나쁜 결과의 위험이 증가합니다. 모델에 로그인 자격 증명을 제공하기 전에 탈옥 및 프롬프트 주입 완화를 검토하세요.
사용자 턴의 content 배열을 구성할 때 지시 텍스트를 스크린샷 이미지 앞에 배치하세요. 이미지가 처리되기 전에 대상 설명을 제공하면 클릭 정확도가 향상됩니다.
enable_zoom: true가 설정된 computer_20251124를 사용할 때, Claude는 사이드바의 파일 이름, 탭 제목, 상태 표시줄 텍스트, 줄 번호, 버튼 레이블과 같이 스크린샷의 기본 해상도에서 읽을 수 없는 작은 텍스트나 특정 UI 요소에 대해 질문받으면 해당 영역을 확대합니다. Claude가 예상대로 확대하지 않는 경우, 화면 전체가 아닌 특정 영역이나 요소에 대해 질문하세요.

명확한 문제 집합을 반복적으로 겪거나 Claude가 완료해야 할 작업을 미리 알고 있는 경우, 시스템 프롬프트를 사용하여 작업을 성공적으로 수행하는 방법에 대한 명시적인 팁이나 지침을 Claude에게 제공하세요.

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

시스템 프롬프트

Claude API를 통해 Anthropic 스키마 도구 중 하나가 요청되면 컴퓨터 사용 전용 시스템 프롬프트가 생성됩니다. 이는 도구 사용 시스템 프롬프트와 유사하지만 다음과 같이 시작합니다:

You have access to a set of functions you can use to answer the user's question. This includes access to a sandboxed computing environment. You do NOT currently have the ability to inspect files or interact with external resources, except by invoking the below functions.

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

사용 가능한 작업

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

기본 작업(모든 버전)

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

향상된 작업(computer_20250124 이상) computer_20250124 및 computer_20251124에서 사용 가능:

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

향상된 작업(computer_20251124) Claude Sonnet 5, Claude Opus 4.8, 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`	아니요	확대 작업 활성화(`computer_20251124` 전용). Claude가 특정 화면 영역을 확대할 수 있도록 하려면 `true`로 설정하세요. 기본값: `false`

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

확장 사고와 결합하기

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

특히 컴퓨터 사용의 경우, 내부 벤치마킹에서는 다음과 같은 effort 설정을 권장합니다:

Claude Opus 4.7: 기본값으로 high를 사용하고, 높은 처리량 또는 비용에 민감한 워크로드에는 low를 사용하세요.
Claude Sonnet 4.6 및 Claude Opus 4.6: 기본값으로 medium을 사용하세요(최고의 정확도 대비 비용 비율). UI 작업에서 정확도를 향상시키지 않으면서 토큰 비용만 추가하는 max는 피하세요. 이러한 모델에서 low는 사고를 완전히 비활성화하는 것보다 더 적은 출력 토큰을 사용하므로(실수가 적으면 재시도가 적음), 비용에 민감한 루프에 좋은 옵션입니다.

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

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

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

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

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

컴퓨터 사용 도구 구현

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

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

작업 핸들러 구현

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

def capture_screenshot():
    return "<screenshot data>"


def click_at(x, y):
    return f"clicked at ({x}, {y})"


def type_text(text):
    return f"typed: {text}"


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"])
    # 필요에 따라 다른 작업을 처리합니다
    return f"unhandled action: {action_type}"

Claude의 도구 호출 처리

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

def process_tool_calls(response):
    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            action = block.input["action"]
            result = handle_computer_action(action, block.input)
            tool_results.append(
                {
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result,
                }
            )
    return tool_results

에이전트 루프 구현

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

def sampling_loop(model, messages, max_iterations=10):
    """
    Run the computer-use agent loop until Claude stops requesting tools
    or the iteration limit is reached.
    """
    for _ in range(max_iterations):
        response = client.beta.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
            betas=["computer-use-2025-11-24"],
        )

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

        # Claude가 요청한 도구를 실행하고 결과를 수집합니다
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # 다음 반복을 위해 도구 결과를 Claude에 다시 보냅니다
        messages.append({"role": "user", "content": tool_results})

    return messages

오류 처리

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

이미지 제한에 맞게 스크린샷 크기 조정

컴퓨터 도구로 전송되는 스크린샷은 Claude의 이미지 크기 제한 내에 있어야 합니다(이미지 크기 제한 참조). API는 Claude가 보기 전에 크기가 초과된 이미지를 축소하고, Claude는 자신이 보는 이미지에 대한 좌표를 반환하므로, 서버 측 축소에 의존하면 해당 좌표를 화면에 다시 매핑하는 데 필요한 배율을 알 수 없게 됩니다. API의 별도 요청 제한을 초과하는 이미지(예: 한 변이 8,000px 초과)만 축소되지 않고 유효성 검사 오류로 거부됩니다.

제한은 모델에 따라 다릅니다. Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7은 긴 변 기준 최대 2576픽셀을 허용합니다. 이전 모델은 긴 변 기준 최대 1568픽셀과 총 약 1.15메가픽셀을 허용합니다. 다음 예제는 이전 모델의 1568px / 1.15MP 제한을 사용합니다. 사용하는 모델의 제한으로 대체하세요.

화면이 제한보다 큰 경우, 전송하기 전에 스크린샷 크기를 조정하고, display_width_px/display_height_px를 조정된 크기로 설정하고, Claude가 반환한 좌표를 원래 화면 공간으로 다시 스케일링하세요:

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)


# 스크린샷을 캡처할 때
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Claude에 전송하기 전에 이미지를 조정된 크기로 리사이즈합니다
screenshot = capture_and_resize(scaled_width, scaled_height)


# Claude의 좌표를 처리할 때 다시 원래 크기로 확대합니다
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

macOS Retina 디스플레이는 장치 픽셀 비율 2로 스크린샷을 캡처하므로 이미지가 논리적 화면 좌표의 두 배 해상도입니다. 전송하기 전에 스크린샷을 2배 축소하거나, 클릭을 실행하기 전에 Claude가 반환한 좌표를 절반으로 줄이세요.

클릭 문제 진단

클릭이 대상을 놓치는 경우 원인은 일반적으로 다음 중 하나입니다:

증상	가능한 원인	시도할 방법
클릭이 일관되게 한 방향으로 치우침	`display_width_px`/`display_height_px`가 실제로 전송된 이미지 크기와 일치하지 않음	디스플레이 크기가 전송하는 스크린샷과 정확히 일치하는지 확인
클릭이 올바른 영역에 도달하지만 대상을 놓침	대상이 매우 작거나, 4K+ 소스를 축소하면서 세부 정보가 손실되었거나, 종횡비가 왜곡됨	`enable_zoom: true` 설정; 더 낮은 DPI로 캡처하거나 관련 영역으로 자르기; 크기 조정 시 종횡비 유지
Claude가 완전히 잘못된 요소를 클릭	모호한 지시 또는 근처에 시각적으로 유사한 요소 존재	위치 기반 프롬프트 사용("오른쪽 하단의 파란색 제출 버튼"); 상호작용을 더 작은 단계로 분할
정확도가 일관되게 낮음	해상도가 너무 낮음	기준으로 1280x720 시도

모델 선택은 클릭 정밀도에 영향을 미칩니다. Claude Sonnet 4.6은 Claude Opus 4.6보다 클릭에서 기계적으로 더 정밀하며 스크린샷에 큰 축소가 필요할 때 더 견고합니다. Claude Opus 4.7은 그 격차를 좁힙니다. 클릭 정밀도는 Sonnet 4.6과 거의 비슷하며, 더 높은 해상도 제한으로 인해 축소가 덜 필요합니다.

구현 모범 사례 따르기

컴퓨터 사용 제한 사항 이해

컴퓨터 사용은 베타 버전입니다. 다음 제한 사항을 염두에 두세요:

지연 시간: 현재 인간-AI 상호작용에 대한 컴퓨터 사용의 "latency"(지연 시간)는 일반적인 사람이 직접 수행하는 컴퓨터 작업에 비해 너무 느릴 수 있습니다. 신뢰할 수 있는 환경에서 속도가 중요하지 않은 사용 사례(예: 백그라운드 정보 수집, 자동화된 소프트웨어 테스트)에 집중하세요.
컴퓨터 비전 정확도 및 신뢰성: Claude는 작업을 생성하는 동안 특정 좌표를 출력할 때 실수하거나 환각을 일으킬 수 있습니다. 확장 사고는 모델의 추론을 이해하고 잠재적인 문제를 식별하는 데 도움이 될 수 있습니다.
도구 선택 정확도 및 신뢰성: Claude는 작업을 생성하는 동안 도구를 선택할 때 실수하거나 환각을 일으키거나 문제를 해결하기 위해 예상치 못한 작업을 수행할 수 있습니다. 또한 틈새 애플리케이션이나 여러 애플리케이션과 동시에 상호작용할 때 신뢰성이 낮아질 수 있습니다. 복잡한 작업을 요청할 때는 모델에 신중하게 프롬프트하세요.
스크롤 신뢰성: 스크롤 작업은 방향 제어(위, 아래, 왼쪽, 오른쪽)와 지정된 양을 지원합니다. 스크롤이 적용되지 않는 애플리케이션에서는 Page Down과 같은 키보드 대안이 도움이 될 수 있습니다.
스프레드시트 상호작용: 개별 셀을 선택하려면 세밀한 마우스 제어 작업(left_mouse_down, left_mouse_up)과 수정자 키 조합을 사용하세요. 복잡한 스프레드시트 작업은 여전히 여러 번의 시도가 필요할 수 있습니다.
소셜 및 커뮤니케이션 플랫폼에서의 계정 생성 및 콘텐츠 생성: Claude는 웹사이트를 방문하지만, 소셜 미디어 웹사이트 및 플랫폼에서 계정을 생성하거나 콘텐츠를 생성 및 공유하거나 기타 인간 사칭에 참여하는 Claude의 능력은 제한됩니다. 이 기능은 향후 업데이트될 수 있습니다.
취약점: 탈옥(jailbreaking) 또는 프롬프트 주입과 같은 취약점은 베타 컴퓨터 사용 API를 포함한 프론티어 AI 시스템 전반에 걸쳐 지속될 수 있습니다. 일부 상황에서 Claude는 사용자의 지시와 충돌하더라도 콘텐츠에서 발견된 명령을 따를 수 있습니다. 예를 들어, 웹페이지의 지시나 이미지에 포함된 지시가 사용자의 지시를 무시하게 하거나 Claude가 실수를 하게 만들 수 있습니다. 다음을 고려하세요:
- 컴퓨터 사용을 최소 권한을 가진 가상 머신 또는 컨테이너와 같은 신뢰할 수 있는 환경으로 제한
- 엄격한 감독 없이 민감한 계정이나 데이터에 대한 컴퓨터 사용 접근 권한 부여 피하기
- 애플리케이션에서 컴퓨터 사용 기능에 필요한 권한을 활성화하거나 요청하기 전에 최종 사용자에게 관련 위험을 알리고 동의 얻기
부적절하거나 불법적인 작업: Anthropic의 서비스 약관에 따라 법률이나 허용 가능한 사용 정책을 위반하기 위해 컴퓨터 사용을 사용해서는 안 됩니다.

항상 Claude의 컴퓨터 사용 작업과 로그를 신중하게 검토하고 확인하세요. 사람의 감독 없이 완벽한 정밀도나 민감한 사용자 정보가 필요한 작업에 Claude를 사용하지 마세요.

데이터 보존

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

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

가격

컴퓨터 사용은 표준 도구 사용 가격 책정을 따릅니다. 컴퓨터 사용 도구를 사용할 때:

시스템 프롬프트 오버헤드: 컴퓨터 사용 베타는 시스템 프롬프트에 466-499개의 토큰을 추가합니다

컴퓨터 사용 도구 토큰 사용량:

모델	도구 정의당 입력 토큰
Claude 4.x 모델	735 토큰

추가 토큰 소비:

스크린샷 이미지 (Vision 가격 책정 참조)
Claude에 반환되는 도구 실행 결과

컴퓨터 사용과 함께 bash 또는 텍스트 편집기 도구도 사용하는 경우, 해당 도구들은 각각의 페이지에 문서화된 자체 토큰 비용이 있습니다.

다음 단계

도구 사용 문제 해결

증상별 해결 진단 표를 통해 가장 일반적인 도구 사용 오류를 해결하세요.

참조 구현

완전한 Docker 기반 구현으로 시작하기

Claude와 함께하는 도구 사용

Claude를 외부 도구 및 API에 연결하세요. 도구가 실행되는 위치, Claude가 도구를 호출하는 시점, 작업에 적합한 도구를 확인하세요.

모범 사례 상세 안내

해상도, 사고 노력, 컨텍스트 관리에 대한 벤치마크 기반 권장 사항

Was this page helpful?

메시지도구

컴퓨터 사용 도구

컴퓨터 사용 도구를 통해 Claude에게 데스크톱 환경의 스크린샷, 마우스, 키보드 제어 권한을 부여하세요.

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

Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5의 경우 "computer-use-2025-11-24"
Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.1(지원 중단됨), Claude Sonnet 4(종료됨, Bedrock 및 Google Cloud 제외), Claude Opus 4(종료됨, Google Cloud 제외)의 경우 "computer-use-2025-01-24"

이 기능에 대한 피드백은 피드백 양식을 통해 공유해 주세요.

개요

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

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

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

보안 고려 사항

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

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

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

분류기 방어 계층이 있더라도 이러한 예방 조치는 여전히 중요합니다.

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

컴퓨터 사용 참조 구현

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

빠른 시작

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",  # 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에게 컴퓨터 사용 도구와 사용자 프롬프트 제공
- API 요청에 컴퓨터 사용 도구(및 선택적으로 다른 도구)를 추가합니다.
- 데스크톱 상호작용이 필요한 사용자 프롬프트를 포함합니다. 예: "고양이 사진을 내 데스크톱에 저장해 줘."
Claude가 컴퓨터 사용 도구 선택
- Claude는 컴퓨터 사용 도구가 사용자의 질의에 도움이 될 수 있는지 평가합니다.
- 그렇다면 Claude는 적절한 형식의 도구 사용 요청을 구성합니다.
- API 응답의 stop_reason이 tool_use가 되어 도구 사용 요청임을 알립니다.
도구 입력 추출, 컴퓨터에서 도구 평가, 결과 반환
- 사용자 측에서 Claude의 요청으로부터 도구 이름과 입력을 추출합니다.
- 컨테이너 또는 가상 머신에서 도구를 사용합니다.
- tool_result 콘텐츠 블록이 포함된 새 user 메시지로 대화를 계속합니다.
Claude는 작업이 완료될 때까지 컴퓨터 사용 도구를 계속 호출
- Claude는 도구 결과를 분석하여 추가 도구 사용이 필요한지 또는 작업이 완료되었는지 판단합니다.
- Claude가 다른 도구가 필요하다고 판단하면 또 다른 tool_use stop_reason으로 응답하며, 3단계로 돌아가야 합니다.
- 그렇지 않으면 사용자에게 텍스트 응답을 작성합니다.

컴퓨팅 환경

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

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

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

Claude의 도구 사용 요청 수신
컴퓨팅 환경에서의 작업으로 변환
결과 캡처(스크린샷 및 명령 출력 등)
이러한 결과를 Claude에게 반환

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

컴퓨터 사용 구현 방법

참조 구현으로 시작하기

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

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

에이전트 루프 이해하기

def sampling_loop(model, messages, max_iterations=10):
    """
    Run the computer-use agent loop until Claude stops requesting tools
    or the iteration limit is reached.
    """
    for _ in range(max_iterations):
        response = client.beta.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
            betas=["computer-use-2025-11-24"],
        )

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

        # Claude가 요청한 도구를 실행하고 결과를 수집합니다
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # 다음 반복을 위해 도구 결과를 Claude에 다시 보냅니다
        messages.append({"role": "user", "content": tool_results})

    return messages

이 문서의 나머지 부분을 읽기 전에 참조 구현을 사용해 보세요.

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

최고 품질의 출력을 얻는 방법에 대한 몇 가지 팁입니다:

간단하고 잘 정의된 작업을 지정하고 각 단계에 대한 명시적인 지침을 제공하세요.
Claude는 때때로 결과를 명시적으로 확인하지 않고 작업의 결과를 가정합니다. 이를 방지하기 위해 다음과 같이 Claude에게 프롬프트할 수 있습니다: After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. Explicitly show your thinking: "I have evaluated step X..." If not correct, try again. Only when you confirm a step was executed correctly should you move on to the next one.
일부 UI 요소(드롭다운 및 스크롤바 등)는 Claude가 마우스 움직임으로 조작하기 까다로울 수 있습니다. 이런 경우 모델에게 키보드 단축키를 사용하도록 프롬프트해 보세요.
반복 가능한 작업이나 UI 상호작용의 경우, 성공적인 결과의 예제 스크린샷과 도구 호출을 프롬프트에 포함하세요.
모델이 로그인해야 하는 경우, <robot_credentials>와 같은 XML 태그 안에 사용자 이름과 비밀번호를 프롬프트에 제공하세요. 로그인이 필요한 애플리케이션 내에서 컴퓨터 사용을 사용하면 프롬프트 주입으로 인한 나쁜 결과의 위험이 증가합니다. 모델에 로그인 자격 증명을 제공하기 전에 탈옥 및 프롬프트 주입 완화를 검토하세요.
사용자 턴의 content 배열을 구성할 때 지시 텍스트를 스크린샷 이미지 앞에 배치하세요. 이미지가 처리되기 전에 대상 설명을 제공하면 클릭 정확도가 향상됩니다.
enable_zoom: true가 설정된 computer_20251124를 사용할 때, Claude는 사이드바의 파일 이름, 탭 제목, 상태 표시줄 텍스트, 줄 번호, 버튼 레이블과 같이 스크린샷의 기본 해상도에서 읽을 수 없는 작은 텍스트나 특정 UI 요소에 대해 질문받으면 해당 영역을 확대합니다. Claude가 예상대로 확대하지 않는 경우, 화면 전체가 아닌 특정 영역이나 요소에 대해 질문하세요.

시스템 프롬프트

You have access to a set of functions you can use to answer the user's question. This includes access to a sandboxed computing environment. You do NOT currently have the ability to inspect files or interact with external resources, except by invoking the below functions.

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

사용 가능한 작업

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

기본 작업(모든 버전)

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

향상된 작업(computer_20250124 이상) computer_20250124 및 computer_20251124에서 사용 가능:

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

향상된 작업(computer_20251124) Claude Sonnet 5, Claude Opus 4.8, 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`	아니요	확대 작업 활성화(`computer_20251124` 전용). Claude가 특정 화면 영역을 확대할 수 있도록 하려면 `true`로 설정하세요. 기본값: `false`

확장 사고와 결합하기

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

특히 컴퓨터 사용의 경우, 내부 벤치마킹에서는 다음과 같은 effort 설정을 권장합니다:

Claude Opus 4.7: 기본값으로 high를 사용하고, 높은 처리량 또는 비용에 민감한 워크로드에는 low를 사용하세요.
Claude Sonnet 4.6 및 Claude Opus 4.6: 기본값으로 medium을 사용하세요(최고의 정확도 대비 비용 비율). UI 작업에서 정확도를 향상시키지 않으면서 토큰 비용만 추가하는 max는 피하세요. 이러한 모델에서 low는 사고를 완전히 비활성화하는 것보다 더 적은 출력 토큰을 사용하므로(실수가 적으면 재시도가 적음), 비용에 민감한 루프에 좋은 옵션입니다.

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

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

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

컴퓨터 사용 도구 구현

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

작업 핸들러 구현

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

def capture_screenshot():
    return "<screenshot data>"


def click_at(x, y):
    return f"clicked at ({x}, {y})"


def type_text(text):
    return f"typed: {text}"


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"])
    # 필요에 따라 다른 작업을 처리합니다
    return f"unhandled action: {action_type}"

Claude의 도구 호출 처리

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

def process_tool_calls(response):
    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            action = block.input["action"]
            result = handle_computer_action(action, block.input)
            tool_results.append(
                {
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result,
                }
            )
    return tool_results

에이전트 루프 구현

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

def sampling_loop(model, messages, max_iterations=10):
    """
    Run the computer-use agent loop until Claude stops requesting tools
    or the iteration limit is reached.
    """
    for _ in range(max_iterations):
        response = client.beta.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
            betas=["computer-use-2025-11-24"],
        )

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

        # Claude가 요청한 도구를 실행하고 결과를 수집합니다
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # 다음 반복을 위해 도구 결과를 Claude에 다시 보냅니다
        messages.append({"role": "user", "content": tool_results})

    return messages

오류 처리

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

이미지 제한에 맞게 스크린샷 크기 조정

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)


# 스크린샷을 캡처할 때
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Claude에 전송하기 전에 이미지를 조정된 크기로 리사이즈합니다
screenshot = capture_and_resize(scaled_width, scaled_height)


# Claude의 좌표를 처리할 때 다시 원래 크기로 확대합니다
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

클릭 문제 진단

클릭이 대상을 놓치는 경우 원인은 일반적으로 다음 중 하나입니다:

증상	가능한 원인	시도할 방법
클릭이 일관되게 한 방향으로 치우침	`display_width_px`/`display_height_px`가 실제로 전송된 이미지 크기와 일치하지 않음	디스플레이 크기가 전송하는 스크린샷과 정확히 일치하는지 확인
클릭이 올바른 영역에 도달하지만 대상을 놓침	대상이 매우 작거나, 4K+ 소스를 축소하면서 세부 정보가 손실되었거나, 종횡비가 왜곡됨	`enable_zoom: true` 설정; 더 낮은 DPI로 캡처하거나 관련 영역으로 자르기; 크기 조정 시 종횡비 유지
Claude가 완전히 잘못된 요소를 클릭	모호한 지시 또는 근처에 시각적으로 유사한 요소 존재	위치 기반 프롬프트 사용("오른쪽 하단의 파란색 제출 버튼"); 상호작용을 더 작은 단계로 분할
정확도가 일관되게 낮음	해상도가 너무 낮음	기준으로 1280x720 시도

구현 모범 사례 따르기

컴퓨터 사용 제한 사항 이해

컴퓨터 사용은 베타 버전입니다. 다음 제한 사항을 염두에 두세요:

지연 시간: 현재 인간-AI 상호작용에 대한 컴퓨터 사용의 "latency"(지연 시간)는 일반적인 사람이 직접 수행하는 컴퓨터 작업에 비해 너무 느릴 수 있습니다. 신뢰할 수 있는 환경에서 속도가 중요하지 않은 사용 사례(예: 백그라운드 정보 수집, 자동화된 소프트웨어 테스트)에 집중하세요.
컴퓨터 비전 정확도 및 신뢰성: Claude는 작업을 생성하는 동안 특정 좌표를 출력할 때 실수하거나 환각을 일으킬 수 있습니다. 확장 사고는 모델의 추론을 이해하고 잠재적인 문제를 식별하는 데 도움이 될 수 있습니다.
도구 선택 정확도 및 신뢰성: Claude는 작업을 생성하는 동안 도구를 선택할 때 실수하거나 환각을 일으키거나 문제를 해결하기 위해 예상치 못한 작업을 수행할 수 있습니다. 또한 틈새 애플리케이션이나 여러 애플리케이션과 동시에 상호작용할 때 신뢰성이 낮아질 수 있습니다. 복잡한 작업을 요청할 때는 모델에 신중하게 프롬프트하세요.
스크롤 신뢰성: 스크롤 작업은 방향 제어(위, 아래, 왼쪽, 오른쪽)와 지정된 양을 지원합니다. 스크롤이 적용되지 않는 애플리케이션에서는 Page Down과 같은 키보드 대안이 도움이 될 수 있습니다.
스프레드시트 상호작용: 개별 셀을 선택하려면 세밀한 마우스 제어 작업(left_mouse_down, left_mouse_up)과 수정자 키 조합을 사용하세요. 복잡한 스프레드시트 작업은 여전히 여러 번의 시도가 필요할 수 있습니다.
소셜 및 커뮤니케이션 플랫폼에서의 계정 생성 및 콘텐츠 생성: Claude는 웹사이트를 방문하지만, 소셜 미디어 웹사이트 및 플랫폼에서 계정을 생성하거나 콘텐츠를 생성 및 공유하거나 기타 인간 사칭에 참여하는 Claude의 능력은 제한됩니다. 이 기능은 향후 업데이트될 수 있습니다.
취약점: 탈옥(jailbreaking) 또는 프롬프트 주입과 같은 취약점은 베타 컴퓨터 사용 API를 포함한 프론티어 AI 시스템 전반에 걸쳐 지속될 수 있습니다. 일부 상황에서 Claude는 사용자의 지시와 충돌하더라도 콘텐츠에서 발견된 명령을 따를 수 있습니다. 예를 들어, 웹페이지의 지시나 이미지에 포함된 지시가 사용자의 지시를 무시하게 하거나 Claude가 실수를 하게 만들 수 있습니다. 다음을 고려하세요:
- 컴퓨터 사용을 최소 권한을 가진 가상 머신 또는 컨테이너와 같은 신뢰할 수 있는 환경으로 제한
- 엄격한 감독 없이 민감한 계정이나 데이터에 대한 컴퓨터 사용 접근 권한 부여 피하기
- 애플리케이션에서 컴퓨터 사용 기능에 필요한 권한을 활성화하거나 요청하기 전에 최종 사용자에게 관련 위험을 알리고 동의 얻기
부적절하거나 불법적인 작업: Anthropic의 서비스 약관에 따라 법률이나 허용 가능한 사용 정책을 위반하기 위해 컴퓨터 사용을 사용해서는 안 됩니다.

데이터 보존

가격

컴퓨터 사용은 표준 도구 사용 가격 책정을 따릅니다. 컴퓨터 사용 도구를 사용할 때:

시스템 프롬프트 오버헤드: 컴퓨터 사용 베타는 시스템 프롬프트에 466-499개의 토큰을 추가합니다

컴퓨터 사용 도구 토큰 사용량:

모델	도구 정의당 입력 토큰
Claude 4.x 모델	735 토큰

추가 토큰 소비:

스크린샷 이미지 (Vision 가격 책정 참조)
Claude에 반환되는 도구 실행 결과

컴퓨터 사용과 함께 bash 또는 텍스트 편집기 도구도 사용하는 경우, 해당 도구들은 각각의 페이지에 문서화된 자체 토큰 비용이 있습니다.

다음 단계

도구 사용 문제 해결

증상별 해결 진단 표를 통해 가장 일반적인 도구 사용 오류를 해결하세요.

참조 구현

완전한 Docker 기반 구현으로 시작하기

Claude와 함께하는 도구 사용

Claude를 외부 도구 및 API에 연결하세요. 도구가 실행되는 위치, Claude가 도구를 호출하는 시점, 작업에 적합한 도구를 확인하세요.

모범 사례 상세 안내

해상도, 사고 노력, 컨텍스트 관리에 대한 벤치마크 기반 권장 사항

Was this page helpful?

개요

보안 고려 사항

빠른 시작

컴퓨터 사용 작동 방식

컴퓨팅 환경

컴퓨터 사용 구현 방법

참조 구현으로 시작하기

에이전트 루프 이해하기

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

시스템 프롬프트

사용 가능한 작업

예제 작업

클릭 및 스크롤 작업과 함께 사용하는 수정자 키

도구 매개변수

확장 사고와 결합하기

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

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

컴퓨터 사용 도구 구현

오류 처리

스크린샷 캡처 실패

잘못된 좌표

작업 실행 실패

이미지 제한에 맞게 스크린샷 크기 조정

클릭 문제 진단

구현 모범 사례 따르기

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

적절한 스크린샷 처리 구현

프롬프트 캐싱을 위한 스크린샷 기록 관리

작업 지연 추가

실행 전 작업 유효성 검사

디버깅을 위한 작업 로깅

컴퓨터 사용 제한 사항 이해

데이터 보존

가격

다음 단계

개요

보안 고려 사항

빠른 시작

컴퓨터 사용 작동 방식

컴퓨팅 환경

컴퓨터 사용 구현 방법

참조 구현으로 시작하기

에이전트 루프 이해하기

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

시스템 프롬프트

사용 가능한 작업

예제 작업

클릭 및 스크롤 작업과 함께 사용하는 수정자 키

도구 매개변수

확장 사고와 결합하기

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

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

컴퓨터 사용 도구 구현

오류 처리

스크린샷 캡처 실패

잘못된 좌표

작업 실행 실패

이미지 제한에 맞게 스크린샷 크기 조정

클릭 문제 진단

구현 모범 사례 따르기

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

적절한 스크린샷 처리 구현

프롬프트 캐싱을 위한 스크린샷 기록 관리

작업 지연 추가

실행 전 작업 유효성 검사

디버깅을 위한 작업 로깅

컴퓨터 사용 제한 사항 이해

데이터 보존

가격

다음 단계

개요

보안 고려 사항

빠른 시작

컴퓨터 사용 작동 방식

컴퓨팅 환경

컴퓨터 사용 구현 방법

참조 구현으로 시작하기

에이전트 루프 이해하기

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

시스템 프롬프트

사용 가능한 작업

도구 매개변수

확장 사고와 결합하기

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

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

컴퓨터 사용 도구 구현

오류 처리

이미지 제한에 맞게 스크린샷 크기 조정

클릭 문제 진단

구현 모범 사례 따르기

컴퓨터 사용 제한 사항 이해

데이터 보존

가격

다음 단계

개요

보안 고려 사항

빠른 시작

컴퓨터 사용 작동 방식

컴퓨팅 환경

컴퓨터 사용 구현 방법

참조 구현으로 시작하기

에이전트 루프 이해하기

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

시스템 프롬프트

사용 가능한 작업

도구 매개변수

확장 사고와 결합하기

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

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

컴퓨터 사용 도구 구현

오류 처리

이미지 제한에 맞게 스크린샷 크기 조정

클릭 문제 진단

구현 모범 사례 따르기

컴퓨터 사용 제한 사항 이해

데이터 보존

가격

다음 단계