도구

컴퓨터 사용 도구

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

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

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

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

개요

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

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

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

모델 호환성

컴퓨터 사용은 다음 Claude 모델에서 사용할 수 있습니다:

모델	도구 버전	베타 플래그
Claude Opus 4.6, Claude Opus 4.5	`computer_20251124`	`computer-use-2025-11-24`
기타 모든 지원 모델	`computer_20250124`	`computer-use-2025-01-24`

Claude Opus 4.6과 Claude Opus 4.5는 상세한 화면 영역 검사를 위한 zoom 액션을 포함한 새로운 기능이 있는 computer_20251124 도구 버전을 도입합니다. 다른 모든 모델(Sonnet 4.5, Haiku 4.5, Sonnet 4, Opus 4, Opus 4.1, Sonnet 3.7)은 computer_20250124 도구 버전을 사용합니다.

이전 도구 버전은 새로운 모델과의 하위 호환성이 보장되지 않습니다. 항상 모델 버전에 해당하는 도구 버전을 사용하세요.

보안 고려사항

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

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

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

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

우리는 이러한 프롬프트 인젝션에 저항하도록 모델을 훈련시켰으며 추가적인 방어 계층을 추가했습니다. 컴퓨터 사용 도구를 사용하면 프롬프트 인젝션의 잠재적 사례를 표시하기 위해 프롬프트에 대해 자동으로 분류기를 실행합니다. 이러한 분류기가 스크린샷에서 잠재적인 프롬프트 인젝션을 식별하면 다음 작업을 진행하기 전에 사용자 확인을 요청하도록 모델을 자동으로 유도합니다. 이 추가 보호가 모든 사용 사례에 이상적이지 않을 수 있다는 것을 인식하고 있으므로(예: 사람이 개입하지 않는 사용 사례), 옵트아웃하여 끄고 싶으시면 문의해 주세요.

프롬프트 인젝션과 관련된 위험을 피하기 위해 Claude를 민감한 데이터와 작업으로부터 격리하는 예방 조치를 취하는 것을 여전히 권장합니다.

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

컴퓨터 사용 참조 구현

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

참고: 이 구현은 Claude 4 모델과 Claude Sonnet 3.7 모두를 위한 새로운 도구를 포함하도록 업데이트되었습니다. 이러한 새 기능에 접근하려면 최신 버전의 저장소를 가져오세요.

모델 응답의 품질, API 자체 또는 문서의 품질에 대한 피드백을 제공하려면 이 양식을 사용해 주세요 - 여러분의 의견을 기다리고 있습니다!

빠른 시작

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

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-6",  # 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 응답에는 Claude의 의도를 나타내는 tool_use의 stop_reason이 포함됩니다.
도구 입력 추출, 컴퓨터에서 도구 실행 및 결과 반환
- 사용자 측에서 Claude의 요청에서 도구 이름과 입력을 추출합니다.
- 컨테이너 또는 가상 머신에서 도구를 사용합니다.
- tool_result 콘텐츠 블록을 포함하는 새로운 user 메시지로 대화를 계속합니다.
Claude가 작업을 완료할 때까지 컴퓨터 사용 도구를 계속 호출
- Claude는 도구 결과를 분석하여 추가 도구 사용이 필요한지 또는 작업이 완료되었는지 판단합니다.
- Claude가 다른 도구가 필요하다고 판단하면 다른 tool_use stop_reason으로 응답하며, 3단계로 돌아가야 합니다.
- 그렇지 않으면 사용자에게 텍스트 응답을 작성합니다.

사용자 입력 없이 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
):
    """
    A simple agent loop for Claude computer use interactions.

    This function handles the back-and-forth between:
    1. Sending user messages to Claude
    2. Claude requesting to use tools
    3. Your app executing those tools
    4. Sending tool results back to Claude
    """
    # Set up tools and API parameters
    client = Anthropic(api_key=api_key)
    beta_flag = "computer-use-2025-01-24" if "20250124" in tool_version else "computer-use-2024-10-22"

    # Configure tools - you should already have these initialized elsewhere
    tools = [
        {"type": f"computer_{tool_version}", "name": "computer", "display_width_px": 1024, "display_height_px": 768},
        {"type": f"text_editor_{tool_version}", "name": "str_replace_editor"},
        {"type": f"bash_{tool_version}", "name": "bash"}
    ]

    # Main agent loop (with iteration limit to prevent runaway API costs)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Set up optional thinking parameter (for Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

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

        # Add Claude's response to the conversation history
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # Check if Claude used any tools
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # In a real app, you would execute the tool here
                # For example: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # Format the result for Claude
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        # If no tools were used, Claude is done - return the final messages
        if not tool_results:
            return messages

        # Add tool results to messages for the next iteration with Claude
        messages.append({"role": "user", "content": tool_results})

루프는 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 태그 안에 사용자 이름과 비밀번호를 프롬프트에 제공하세요. 로그인이 필요한 애플리케이션 내에서 컴퓨터 사용을 하면 프롬프트 인젝션으로 인한 나쁜 결과의 위험이 증가합니다. 모델에 로그인 자격 증명을 제공하기 전에 프롬프트 인젝션 완화 가이드를 검토하세요.

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

시스템 프롬프트

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

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_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.6 및 Claude Opus 4.5에서 사용 가능:

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

도구 매개변수

매개변수	필수	설명
`type`	예	도구 버전 (`computer_20251124`, `computer_20250124`, 또는 `computer_20241022`)
`name`	예	"computer"여야 함
`display_width_px`	예	디스플레이 너비(픽셀)
`display_height_px`	예	디스플레이 높이(픽셀)
`display_number`	아니오	X11 환경의 디스플레이 번호
`enable_zoom`	아니오	zoom 액션 활성화 (`computer_20251124` 전용). Claude가 특정 화면 영역을 확대할 수 있도록 `true`로 설정. 기본값: `false`

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

Claude 4 모델 및 Claude Sonnet 3.7에서 사고 기능 활성화

Claude Sonnet 3.7은 복잡한 작업을 처리할 때 모델의 추론 과정을 볼 수 있는 새로운 "사고" 기능을 도입했습니다. 이 기능은 Claude가 문제에 어떻게 접근하는지 이해하는 데 도움이 되며 디버깅이나 교육 목적에 특히 유용할 수 있습니다.

사고를 활성화하려면 API 요청에 thinking 매개변수를 추가하세요:

"thinking": {
  "type": "enabled",
  "budget_tokens": 1024
}

budget_tokens 매개변수는 Claude가 사고에 사용할 수 있는 토큰 수를 지정합니다. 이는 전체 max_tokens 예산에서 차감됩니다.

사고가 활성화되면 Claude는 응답의 일부로 추론 과정을 반환하며, 이를 통해 다음을 수행할 수 있습니다:

모델의 의사 결정 과정 이해
잠재적인 문제나 오해 식별
Claude의 문제 해결 접근 방식에서 학습
복잡한 다단계 작업에 대한 더 많은 가시성 확보

사고 출력의 예시는 다음과 같습니다:

[Thinking]
I need to save a picture of a cat to the desktop. Let me break this down into steps:

1. First, I'll take a screenshot to see what's on the desktop
2. Then I'll look for a web browser to search for cat images
3. After finding a suitable image, I'll need to save it to the desktop

Let me start by taking a screenshot to see what's available...

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

컴퓨터 사용 도구는 다른 도구와 결합하여 더 강력한 자동화 워크플로를 만들 수 있습니다. 이는 다음이 필요할 때 특히 유용합니다:

시스템 명령 실행 (bash 도구)
구성 파일 또는 스크립트 편집 (텍스트 편집기 도구)
사용자 정의 API 또는 서비스와 통합 (사용자 정의 도구)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: computer-use-2025-01-24" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 2000,
    "tools": [
      {
        "type": "computer_20250124",
        "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"
      },
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Find flights from San Francisco to a place with warmer weather."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

커스텀 컴퓨터 사용 환경 구축

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

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

컴퓨터 사용 도구 구현

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

컴퓨팅 환경 설정
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(...)
    
    # 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})

오류 처리

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

고해상도를 위한 좌표 스케일링 처리

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

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

이를 해결하려면 스크린샷을 직접 리사이즈하고 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)

# 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)

구현 모범 사례 따르기

컴퓨터 사용 제한 사항 이해

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

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

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

가격

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 기반 구현으로 빠르게 시작하세요

도구 문서

도구 사용 및 커스텀 도구 생성에 대해 자세히 알아보세요

Was this page helpful?

도구

컴퓨터 사용 도구

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

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

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

개요

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

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

모델 호환성

컴퓨터 사용은 다음 Claude 모델에서 사용할 수 있습니다:

모델	도구 버전	베타 플래그
Claude Opus 4.6, Claude Opus 4.5	`computer_20251124`	`computer-use-2025-11-24`
기타 모든 지원 모델	`computer_20250124`	`computer-use-2025-01-24`

이전 도구 버전은 새로운 모델과의 하위 호환성이 보장되지 않습니다. 항상 모델 버전에 해당하는 도구 버전을 사용하세요.

보안 고려사항

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

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

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

프롬프트 인젝션과 관련된 위험을 피하기 위해 Claude를 민감한 데이터와 작업으로부터 격리하는 예방 조치를 취하는 것을 여전히 권장합니다.

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

컴퓨터 사용 참조 구현

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

모델 응답의 품질, API 자체 또는 문서의 품질에 대한 피드백을 제공하려면 이 양식을 사용해 주세요 - 여러분의 의견을 기다리고 있습니다!

빠른 시작

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

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-6",  # 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 응답에는 Claude의 의도를 나타내는 tool_use의 stop_reason이 포함됩니다.
도구 입력 추출, 컴퓨터에서 도구 실행 및 결과 반환
- 사용자 측에서 Claude의 요청에서 도구 이름과 입력을 추출합니다.
- 컨테이너 또는 가상 머신에서 도구를 사용합니다.
- tool_result 콘텐츠 블록을 포함하는 새로운 user 메시지로 대화를 계속합니다.
Claude가 작업을 완료할 때까지 컴퓨터 사용 도구를 계속 호출
- Claude는 도구 결과를 분석하여 추가 도구 사용이 필요한지 또는 작업이 완료되었는지 판단합니다.
- Claude가 다른 도구가 필요하다고 판단하면 다른 tool_use stop_reason으로 응답하며, 3단계로 돌아가야 합니다.
- 그렇지 않으면 사용자에게 텍스트 응답을 작성합니다.

컴퓨팅 환경

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

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

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

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

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

컴퓨터 사용 구현 방법

참조 구현으로 시작하기

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

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

멀티 에이전트 루프 이해하기

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
):
    """
    A simple agent loop for Claude computer use interactions.

    This function handles the back-and-forth between:
    1. Sending user messages to Claude
    2. Claude requesting to use tools
    3. Your app executing those tools
    4. Sending tool results back to Claude
    """
    # Set up tools and API parameters
    client = Anthropic(api_key=api_key)
    beta_flag = "computer-use-2025-01-24" if "20250124" in tool_version else "computer-use-2024-10-22"

    # Configure tools - you should already have these initialized elsewhere
    tools = [
        {"type": f"computer_{tool_version}", "name": "computer", "display_width_px": 1024, "display_height_px": 768},
        {"type": f"text_editor_{tool_version}", "name": "str_replace_editor"},
        {"type": f"bash_{tool_version}", "name": "bash"}
    ]

    # Main agent loop (with iteration limit to prevent runaway API costs)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Set up optional thinking parameter (for Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

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

        # Add Claude's response to the conversation history
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # Check if Claude used any tools
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # In a real app, you would execute the tool here
                # For example: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # Format the result for Claude
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        # If no tools were used, Claude is done - return the final messages
        if not tool_results:
            return messages

        # Add tool results to messages for the next iteration with Claude
        messages.append({"role": "user", "content": tool_results})

이 문서의 나머지 부분을 읽기 전에 참조 구현을 먼저 시도해 보는 것을 권장합니다.

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

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

간단하고 잘 정의된 작업을 지정하고 각 단계에 대한 명시적인 지침을 제공하세요.
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 태그 안에 사용자 이름과 비밀번호를 프롬프트에 제공하세요. 로그인이 필요한 애플리케이션 내에서 컴퓨터 사용을 하면 프롬프트 인젝션으로 인한 나쁜 결과의 위험이 증가합니다. 모델에 로그인 자격 증명을 제공하기 전에 프롬프트 인젝션 완화 가이드를 검토하세요.

시스템 프롬프트

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_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.6 및 Claude Opus 4.5에서 사용 가능:

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

도구 매개변수

매개변수	필수	설명
`type`	예	도구 버전 (`computer_20251124`, `computer_20250124`, 또는 `computer_20241022`)
`name`	예	"computer"여야 함
`display_width_px`	예	디스플레이 너비(픽셀)
`display_height_px`	예	디스플레이 높이(픽셀)
`display_number`	아니오	X11 환경의 디스플레이 번호
`enable_zoom`	아니오	zoom 액션 활성화 (`computer_20251124` 전용). Claude가 특정 화면 영역을 확대할 수 있도록 `true`로 설정. 기본값: `false`

Claude 4 모델 및 Claude Sonnet 3.7에서 사고 기능 활성화

사고를 활성화하려면 API 요청에 thinking 매개변수를 추가하세요:

"thinking": {
  "type": "enabled",
  "budget_tokens": 1024
}

budget_tokens 매개변수는 Claude가 사고에 사용할 수 있는 토큰 수를 지정합니다. 이는 전체 max_tokens 예산에서 차감됩니다.

사고가 활성화되면 Claude는 응답의 일부로 추론 과정을 반환하며, 이를 통해 다음을 수행할 수 있습니다:

모델의 의사 결정 과정 이해
잠재적인 문제나 오해 식별
Claude의 문제 해결 접근 방식에서 학습
복잡한 다단계 작업에 대한 더 많은 가시성 확보

사고 출력의 예시는 다음과 같습니다:

[Thinking]
I need to save a picture of a cat to the desktop. Let me break this down into steps:

1. First, I'll take a screenshot to see what's on the desktop
2. Then I'll look for a web browser to search for cat images
3. After finding a suitable image, I'll need to save it to the desktop

Let me start by taking a screenshot to see what's available...

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

컴퓨터 사용 도구는 다른 도구와 결합하여 더 강력한 자동화 워크플로를 만들 수 있습니다. 이는 다음이 필요할 때 특히 유용합니다:

시스템 명령 실행 (bash 도구)
구성 파일 또는 스크립트 편집 (텍스트 편집기 도구)
사용자 정의 API 또는 서비스와 통합 (사용자 정의 도구)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: computer-use-2025-01-24" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 2000,
    "tools": [
      {
        "type": "computer_20250124",
        "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"
      },
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Find flights from San Francisco to a place with warmer weather."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

커스텀 컴퓨터 사용 환경 구축

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

컴퓨터 사용 도구 구현

컴퓨팅 환경 설정
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(...)
    
    # 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})

오류 처리

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

고해상도를 위한 좌표 스케일링 처리

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

이를 해결하려면 스크린샷을 직접 리사이즈하고 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)

# 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)

구현 모범 사례 따르기

컴퓨터 사용 제한 사항 이해

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

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

가격

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 기반 구현으로 빠르게 시작하세요

도구 문서

도구 사용 및 커스텀 도구 생성에 대해 자세히 알아보세요

Was this page helpful?

개요

모델 호환성

보안 고려사항

빠른 시작

컴퓨터 사용 작동 방식

컴퓨팅 환경

컴퓨터 사용 구현 방법

참조 구현으로 시작하기

멀티 에이전트 루프 이해하기

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

시스템 프롬프트

사용 가능한 액션

액션 예제

클릭 및 스크롤 액션에서의 수정자 키

도구 매개변수

Claude 4 모델 및 Claude Sonnet 3.7에서 사고 기능 활성화

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

커스텀 컴퓨터 사용 환경 구축

컴퓨터 사용 도구 구현

오류 처리

스크린샷 캡처 실패

잘못된 좌표

액션 실행 실패

고해상도를 위한 좌표 스케일링 처리

구현 모범 사례 따르기

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

적절한 스크린샷 처리 구현

액션 지연 추가

실행 전 액션 검증

디버깅을 위한 액션 로깅

컴퓨터 사용 제한 사항 이해

가격

다음 단계

개요

모델 호환성

보안 고려사항

빠른 시작

컴퓨터 사용 작동 방식

컴퓨팅 환경

컴퓨터 사용 구현 방법

참조 구현으로 시작하기

멀티 에이전트 루프 이해하기

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

시스템 프롬프트

사용 가능한 액션

액션 예제

클릭 및 스크롤 액션에서의 수정자 키

도구 매개변수

Claude 4 모델 및 Claude Sonnet 3.7에서 사고 기능 활성화

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

커스텀 컴퓨터 사용 환경 구축

컴퓨터 사용 도구 구현

오류 처리

스크린샷 캡처 실패

잘못된 좌표

액션 실행 실패

고해상도를 위한 좌표 스케일링 처리

구현 모범 사례 따르기

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

적절한 스크린샷 처리 구현

액션 지연 추가

실행 전 액션 검증

디버깅을 위한 액션 로깅

컴퓨터 사용 제한 사항 이해

가격

다음 단계