컴퓨터 사용 도구

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

컴퓨터 사용 도구는 Anthropic이 정의한 클라이언트 도구 세트입니다. tools에 {"type": "computer_toolset_20260801"} 항목 하나를 추가하면 Claude는 screenshot, left_click, type, zoom 같은 17개의 멤버 도구를 사용할 수 있으며, 애플리케이션은 모든 호출을 사용자가 제어하는 환경에서 실행합니다. 현재 Claude Managed Agents에서는 사용할 수 없습니다. Claude의 호출은 name이 멤버 이름이고 "toolset_name": "computer"를 포함하는 tool_use 블록이며, 한 턴에 여러 개가 포함되는 경우가 많습니다(배치 작업).

웹페이지 내에서만 이루어지는 작업에는 브라우저 사용 도구가 더 적합합니다. 이 도구의 멤버 도구는 페이지 자체를 읽고 조작하며, 완전한 데스크톱 환경이 필요하지 않습니다.

도구 세트를 지원하는 모델과 플랫폼은 API 지원을 참조하세요. 이전 도구 버전에는 각 이전 버전의 베타 헤더와 함께 사용할 모델이 나와 있습니다.

보안 고려 사항

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

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

Anthropic은 이러한 프롬프트 인젝션에 저항하도록 모델을 학습시켰으며, 추가적인 방어 계층을 더했습니다. 컴퓨터 사용 도구를 사용하면 분류기가 스크린샷과 같은 도구 반환 결과를 자동으로 검사하여 잠재적인 프롬프트 인젝션을 표시합니다. 이러한 분류기가 잠재적인 프롬프트 인젝션을 식별하면, 모델이 해당 지시에 따라 행동하기 전에 그 지시가 실제로 사용자로부터 온 것인지 확인하도록 유도합니다.

이 추가 보호 기능은 모든 사용 사례에 이상적이지는 않으므로(예: 사람이 개입하지 않는 사용 사례), 이를 선택 해제하고 끄려면 지원팀에 문의하세요. 이러한 분류기가 있더라도 앞서 나열한 예방 조치는 여전히 중요합니다.

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

빠른 시작

Messages APIAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 요청의 tools 배열에 컴퓨터 사용 도구 세트를 {"type": "computer_toolset_20260801"}로 추가하세요. 이 요청에는 베타 헤더가 필요하지 않습니다. 이 예제는 Claude가 일반적으로 컴퓨터 사용과 함께 사용하는 텍스트 편집기 도구와 bash 도구도 선언합니다:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {"type": "computer_toolset_20260801"},
        {"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."}],
)
print(response)

Claude가 데스크톱에서 작업을 수행할 때, 응답의 stop_reason은 tool_use이며 하나 이상의 멤버 tool_use 블록을 포함하고, 각 블록은 멤버 도구의 이름을 지정하고 "toolset_name": "computer"를 포함합니다. 이 작업 도중 Claude가 데스크톱 스크린샷을 받은 후의 응답은 다음과 같을 수 있습니다:

{
  "id": "msg_01UZ3bXcQH8mTqNhVfL9eK2p",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the web browser to find a picture of a cat."
    },
    {
      "type": "tool_use",
      "id": "toolu_01WkoTUvSHDzTBu2xnGk8Ep8",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [512, 742] }
    },
    {
      "type": "tool_use",
      "id": "toolu_017nJn3RgSCkTMwuZDb4uUov",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

애플리케이션은 각 호출을 자체 환경에서 순서대로 실행하고, 각 tool_use 블록마다 하나의 tool_result 블록을 반환한 다음 API를 다시 호출합니다. 컴퓨터 사용의 작동 방식에서 이 루프를 설명하며, 이 페이지의 나머지 부분에서 이를 구현하는 방법을 보여줍니다.

컴퓨터 사용의 작동 방식

1. 1

   Claude에게 컴퓨터 사용 도구와 사용자 프롬프트 제공

   • API 요청의 tools 배열에 컴퓨터 사용 도구 세트(및 선택적으로 다른 도구)를 추가합니다.
   • 데스크톱 상호작용이 필요한 사용자 프롬프트를 포함합니다. 예: "고양이 사진을 내 데스크톱에 저장해 줘."
2. 2

   Claude가 멤버 도구 호출로 응답

   • Claude는 데스크톱에서 작업을 수행하는 것이 사용자의 질의에 도움이 되는지 평가합니다.
   • 그렇다면 Claude는 screenshot, left_click, type 같은 하나 이상의 멤버 tool_use 블록으로 응답하며, 각 블록은 "toolset_name": "computer"를 포함합니다. 이러한 블록이 여러 개 포함된 응답이 배치 작업입니다.
   • API 응답의 stop_reason은 tool_use이며, 이는 도구 사용 요청을 나타냅니다.
3. 3

   호출을 순서대로 실행하고 결과 반환

   • 응답의 모든 tool_use 블록을 순서대로 순회합니다. 각 블록에 대해 멤버 name과 toolset_name을 함께 기준으로 분기하고, 블록의 input으로 컨테이너나 가상 머신에서 해당 작업을 수행합니다.
   • 각 tool_use 블록마다 하나의 tool_result 블록을 포함하는 새 user 메시지로 대화를 이어갑니다. 각 결과는 tool_use_id로 매칭되며 "toolset_name": "computer"를 그대로 포함합니다. screenshot과 zoom에는 이미지를 반환하고, 다른 작업에는 OK 같은 짧은 텍스트로 충분합니다.
   • 작업이 실패하면 해당 블록에 is_error: true를 반환하고, 배치의 나머지 블록에는 배치 작업에 설명된 대로 응답합니다.
4. 4

   작업이 완료될 때까지 Claude가 계속 진행

   • Claude는 도구 결과를 분석하여 추가 작업이 필요한지 또는 작업이 완료되었는지 판단합니다.
   • 추가 작업이 필요하다고 판단하면 Claude는 다시 tool_use stop_reason으로 응답합니다. 3단계로 돌아가세요.
   • 그렇지 않으면 사용자에게 텍스트 응답을 반환합니다.

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

배치 작업

Claude는 클릭, 입력, 스크린샷 촬영과 같은 짧은 작업 시퀀스를 계획하여 하나의 응답에 함께 반환할 수 있습니다. 이를 “batch action”(배치 작업)이라고 합니다. 이는 병렬 도구 사용과 동일한 응답 형태를 사용하지만 한 가지 차이가 있습니다. 블록을 동시에 실행하는 대신 순서대로 실행합니다.

세 가지 작업으로 구성된 배치가 포함된 응답은 다음과 같습니다:

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [640, 60] }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "name": "type",
      "toolset_name": "computer",
      "input": { "text": "pictures of cats" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ]
}

각 tool_use 블록마다 tool_use_id로 매칭되는 tool_result 블록 하나를 모두 다음 user 메시지에 담아 반환하세요. 멤버 도구에 대한 모든 결과는 "toolset_name": "computer"를 포함해야 합니다. 이를 생략하거나 해당 tool_use 블록과 다른 도구 세트를 지정한 결과는 거부됩니다. screenshot과 zoom 결과에만 이미지가 필요하며, 다른 멤버에는 OK 같은 짧은 텍스트 확인으로 충분합니다(cursor_position은 좌표를 텍스트로 반환합니다):

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "toolset_name": "computer",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}

블록을 순서대로 실행하고 첫 번째 실패에서 중단하세요. 배치의 이후 작업은 보통 이전 작업에 의존합니다. 이 예제의 type은 앞선 클릭이 포커스한 곳에 텍스트를 입력합니다. 블록을 content에 나타나는 순서대로 순차 실행하고, 하나가 실패하면 나머지는 실행하지 마세요. 모든 tool_use 블록에는 여전히 tool_result가 필요하므로 배치에 다음과 같이 응답하세요:

• 성공한 각 작업에는 일반 결과를 반환합니다.
• 실패한 작업에는 무엇이 잘못되었는지 설명하는 텍스트와 함께 is_error: true를 반환합니다.
• 배치의 이후 모든 작업에는 정확히 다음 텍스트와 함께 is_error: true를 반환합니다(브라우저 사용 도구는 자체 중단 텍스트를 사용합니다):

{
  "type": "tool_result",
  "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
  "toolset_name": "computer",
  "is_error": true,
  "content": "Not executed: an earlier computer action in this turn failed."
}

그러면 Claude는 어떤 작업이 성공했고, 어떤 작업이 실패했으며, 어떤 작업이 건너뛰어졌는지 읽고 다음 턴에서 다시 계획합니다. 배치의 tool_use 블록 중 하나라도 응답하지 않은 요청은 invalid_request_error로 거부되므로, 첫 번째 블록만 읽는 에이전트 루프는 다음 호출에서 실패합니다. 애플리케이션이 중요한 작업에 대해 사람에게 확인을 요청한다면, 배치가 한 턴 안에 여러 단계의 작업을 완료할 수 있으므로 각 블록이 실행되기 전에 그 확인을 수행하세요.

Claude는 일반적으로 다음에 무엇을 할지 결정하기 전에 결과를 관찰할 수 있도록 배치를 screenshot으로 마칩니다. 배치가 스크린샷으로 끝나지 않는 경우, 애플리케이션은 배치의 마지막 결과에 추가 image 블록으로 스크린샷을 첨부하여 Claude가 항상 현재 화면 상태를 받도록 할 수 있으며, 이는 Claude가 요청할 때까지 기다리는 것에 비해 한 번의 왕복을 절약합니다. Claude에게 모든 배치를 스크린샷으로 마치도록 프롬프트할 수도 있습니다(프롬프트로 모델 성능 최적화 참조).

컴퓨팅 환경

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

1. 가상 디스플레이: Claude가 스크린샷으로 받고 마우스/키보드 작업으로 제어하는 데스크톱 인터페이스를 렌더링하는 가상 X11 디스플레이 서버(Xvfb 사용).

2. 데스크톱 환경: Linux에서 실행되는 윈도우 매니저(Mutter)와 패널(Tint2)을 갖춘 경량 UI로, Claude가 상호작용할 일관된 그래픽 인터페이스를 제공합니다.

3. 애플리케이션: Firefox, LibreOffice, 텍스트 편집기, 파일 관리자 등 Claude가 작업을 완료하는 데 사용할 수 있는 사전 설치된 Linux 애플리케이션.

4. 도구 구현: Claude의 추상적인 도구 요청(예: "마우스 이동" 또는 "스크린샷 촬영")을 가상 환경의 실제 작업으로 변환하는 통합 코드.

5. 에이전트 루프: Claude와 환경 간의 통신을 처리하는 프로그램으로, Claude의 작업을 환경에 보내고 결과(스크린샷, 명령 출력)를 Claude에게 다시 반환합니다.

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

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

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

컴퓨터 사용 구현 방법

기존 computer_20251124 통합을 업그레이드하시나요? computer_20251124에서 마이그레이션부터 시작하세요. 이 섹션의 나머지 내용은 새 통합과 마이그레이션된 통합 모두에 적용됩니다.

에이전트 루프 이해하기

컴퓨터 사용의 핵심은 "에이전트 루프"입니다. 이는 Claude가 도구 작업을 요청하고, 애플리케이션이 이를 실행하여 결과를 Claude에게 반환하는 주기입니다. 이 루프는 빠른 시작에서 만든 클라이언트, 컴퓨터 사용 도구 세트만 선언하는 tools 배열, 그리고 컴퓨터 사용 도구 구현에 있는 도구 호출 처리 헬퍼를 사용합니다. 빠른 시작의 bash 및 텍스트 편집기 도구처럼 다른 도구도 선언한다면, 같은 처리 과정에서 해당 tool_use 블록도 분기하여 처리하세요. 헬퍼는 컴퓨터 사용 멤버 호출에만 응답하며, 루프는 응답한 호출이 없는 턴을 완료된 것으로 간주합니다. 다음은 간단한 예제입니다:

def sampling_loop(model: str, messages: list[MessageParam], max_iterations: int = 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.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
        )

        # 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

        # 모든 결과를 단일 user 메시지로 Claude에게 다시 보냅니다
        messages.append({"role": "user", "content": tool_results})

    return messages

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

프롬프트로 모델 성능 최적화

1. 간단하고 명확하게 정의된 작업을 지정하고 각 단계에 대해 명시적인 지시를 제공하세요.
2. Claude는 때때로 결과를 명시적으로 확인하지 않고 작업이 성공한 것처럼 행동합니다. 이를 방지하려면 Claude에게 After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. State in one sentence what the screenshot shows and whether the step succeeded. If it didn't, try again. Only when you confirm a step was executed correctly should you move on to the next one.라고 프롬프트할 수 있습니다.
3. 일부 UI 요소(예: 드롭다운 및 스크롤바)는 Claude가 마우스 움직임으로 조작하기 까다로울 수 있습니다. 이런 경우 모델에게 키보드 단축키를 사용하도록 프롬프트해 보세요.
4. 반복 가능한 작업이나 UI 상호작용의 경우, 성공적인 결과의 예시 스크린샷과 도구 호출을 프롬프트에 포함하세요.
5. 모델이 로그인해야 한다면 <robot_credentials> 같은 XML 태그 안에 사용자 이름과 비밀번호를 넣어 프롬프트에 제공하세요. 로그인이 필요한 애플리케이션 내에서 컴퓨터 사용을 사용하면 프롬프트 인젝션으로 인한 나쁜 결과의 위험이 커집니다. 모델에 로그인 자격 증명을 제공하기 전에 탈옥 및 프롬프트 인젝션 완화를 검토하세요.
6. 사용자 턴의 content 배열을 구성할 때 지시 텍스트를 스크린샷 이미지 앞에 배치하세요. 이미지가 처리되기 전에 대상 설명을 제공하면 클릭 정확도가 향상됩니다.
7. Claude는 사이드바의 파일 이름, 탭 제목, 상태 표시줄 텍스트, 줄 번호, 버튼 레이블처럼 스크린샷의 기본 해상도에서 읽을 수 없는 작은 텍스트나 특정 UI 요소에 대해 질문을 받으면 zoom 작업을 사용하여 해당 영역을 전체 해상도로 검사합니다. Claude가 예상대로 확대하지 않는다면, 화면 전체가 아니라 특정 영역이나 요소에 대해 질문하세요.
8. 모든 배치 작업이 스크린샷으로 끝나기를 원한다면 시스템 프롬프트에 그렇게 명시하세요. 예: End each group of actions with a screenshot so you can verify the result before continuing.

시스템 프롬프트

요청에 컴퓨터 사용 도구를 포함하면 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 매개변수는 여전히 존중되며 결합된 시스템 프롬프트를 구성하는 데 사용됩니다.

사용 가능한 작업

각 작업은 컴퓨터 사용 도구 세트의 멤버 도구입니다. Claude는 "toolset_name": "computer"를 포함하는 tool_use 블록에서 멤버 이름을 지정하며, 블록의 input에는 action 필드 없이 해당 멤버의 매개변수만 포함됩니다. 이 도구 세트에는 17개의 멤버 도구가 있습니다:

멤버를 구현할 때 다음 사항에 유의하세요:

• 좌표는 스크린샷 픽셀 단위입니다. 모든 coordinate, start_coordinate, region 값과 cursor_position이 보고하는 위치는 반환하는 전체 디스플레이 스크린샷의 픽셀 공간에 있으며, 원점은 왼쪽 위입니다. 확대 이미지는 이를 바꾸지 않습니다. zoom 이후에도 Claude는 확대된 이미지 기준이 아니라 항상 전체 스크린샷 공간에서 좌표를 표현합니다. 스크린샷을 반환하기 전에 축소한다면, 실제 디스플레이에 적용하기 전에 Claude의 좌표를 다시 확대하세요(이미지 제한에 맞게 스크린샷 크기 조정 참조).
• zoom을 포함한 모든 멤버가 기본적으로 활성화되어 있습니다. 환경에서 확대 이미지를 생성할 수 없다면, 활성화된 상태로 두고 오류를 반환하는 대신 configs로 해당 멤버를 제외하세요(도구 매개변수 참조). Claude가 여러분이 제외했거나 구현하지 않은 멤버를 호출하면 해당 블록에 is_error: true가 포함된 tool_result를 반환하세요.
• (toolset_name, name) 쌍을 기준으로 분기하세요. toolset_name은 블록을 컴퓨터 작업으로 표시하는 요소입니다. 같은 요청의 커스텀 도구가 멤버와 같은 이름을 가질 수 있으며, 이후 도구 세트 버전에서 멤버가 추가될 수 있습니다(클라이언트 도구 세트 참조).

{
  "type": "tool_use",
  "id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300], "text": "shift" }
}

{
  "type": "tool_use",
  "id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
  "name": "left_click_drag",
  "toolset_name": "computer",
  "input": {
    "start_coordinate": [200, 300],
    "coordinate": [600, 300]
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
  "name": "scroll",
  "toolset_name": "computer",
  "input": {
    "coordinate": [500, 400],
    "scroll_direction": "down",
    "scroll_amount": 3
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
  "name": "key",
  "toolset_name": "computer",
  "input": { "text": "Tab", "repeat": 4 }
}

{
  "type": "tool_use",
  "id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
  "name": "zoom",
  "toolset_name": "computer",
  "input": { "region": [100, 200, 400, 350] }
}

{
  "type": "tool_use",
  "id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
  "name": "cursor_position",
  "toolset_name": "computer",
  "input": {}
}

도구 매개변수

tools 배열의 도구 세트 항목은 네 가지 매개변수를 허용합니다. 브라우저 사용 도구 세트와 공유하는 규칙은 클라이언트 도구 세트에 나와 있습니다.

예를 들어, 다음 항목은 zoom을 구현하지 않는 환경을 위해 이를 제외하고 도구 세트 정의 지점에 캐시 중단점을 설정합니다:

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  },
  "cache_control": { "type": "ephemeral" }
}

에이전트 루프가 왕복마다 하나의 작업만 실행할 수 있다면 tool_choice에서 disable_parallel_tool_use를 true로 설정하세요. 그러면 Claude는 턴마다 최대 하나의 멤버 tool_use 블록을 반환합니다(병렬 도구 사용 비활성화 참조).

이 항목은 이전 도구 버전의 다음 매개변수를 거부하며, 이 중 하나라도 포함된 요청은 invalid_request_error를 반환합니다:

• name: 멤버 이름은 도구 세트 버전에 의해 고정됩니다.
• display_width_px, display_height_px, display_number: 좌표는 항상 반환하는 스크린샷의 픽셀 공간에 있습니다.
• enable_zoom: 확대는 configs를 통해 제어하는 멤버 도구입니다.

또한 이 항목은 computer_20251124 항목이나 computer라는 이름의 다른 도구와 같은 요청에서 선언할 수 없습니다. strict, input_examples, defer_loading 배치, tool_choice, 스트리밍, 호출자 제한에 대해서는 클라이언트 도구 세트를 참조하세요.

사고와 결합하기

컴퓨터 사용을 사고와 결합하려면 사고를 참조하세요.

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

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

웹페이지 내에서만 이루어지는 작업의 경우 같은 요청에서 브라우저 사용 도구를 선언할 수도 있습니다. 두 도구 세트는 각자의 좌표계에서 독립적으로 작동합니다. toolset_name 값은 screenshot이나 key처럼 이름이 같은 멤버에 대한 호출을 구분합니다.

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

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

• Claude와의 컴퓨터 사용에 적합한 가상화 또는 컨테이너화된 환경
• 컴퓨터 사용 도구 작업의 구현
• Claude API와 상호작용하고 도구 구현을 사용하여 tool_use 결과를 실행하는 에이전트 루프
• 사용자 입력으로 에이전트 루프를 시작할 수 있는 API 또는 UI

컴퓨터 사용 도구 구현

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

1. 1

   컴퓨팅 환경 설정

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

2. 2

   작업 핸들러 구현

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

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   # 플레이스홀더 이미지 데이터; 실제 실행기는 화면을 캡처하여 PNG 바이트를 반환합니다
   PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
   
   
   def capture_screenshot() -> list[ImageBlockParam]:
       # screenshot은 텍스트 대신 이미지 블록으로 응답합니다: 결과 콘텐츠 목록을 반환합니다
       return [
           {
               "type": "image",
               "source": {
                   "type": "base64",
                   "media_type": "image/png",
                   "data": PLACEHOLDER_PNG,
               },
           }
       ]
   
   
   def click(coordinate=None):
       if coordinate is None:
           return "clicked at current cursor"
       x, y = coordinate
       return f"clicked at ({x}, {y})"
   
   
   def type_text(text):
       return f"typed: {text}"
   
   
   def handle_computer_action(name, tool_input):
       match name:
           case "screenshot":
               return capture_screenshot()
           case "left_click":
               # coordinate는 선택 사항이며, 없으면 커서가 현재 있는 위치를 클릭합니다
               return click(tool_input.get("coordinate"))
           case "type":
               return type_text(tool_input["text"])
       # 필요에 따라 다른 액션을 처리합니다
       raise ValueError(f"Unknown or unimplemented member: {name}")

3. 3

   Claude의 도구 호출 처리

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

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."
   
   
   def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
       """
       Run the computer actions in Claude's response in order and answer each
       one. After the first failure the rest are skipped, because Claude planned
       them assuming the earlier actions succeeded.
       """
       tool_results: list[ToolResultBlockParam] = []
       failed = False
       for block in response.content:
           # computer 도구 세트만 선언되어 있습니다; 다른 도구를 추가하면 여기로 라우팅하세요
           if block.type != "tool_use" or block.toolset_name != "computer":
               continue
           result: ToolResultBlockParam = {
               "type": "tool_result",
               "tool_use_id": block.id,
               "toolset_name": "computer",
           }
           if failed:
               result["content"] = NOT_EXECUTED
               result["is_error"] = True
           else:
               try:
                   # 문자열 또는 스크린샷 이미지와 같은 콘텐츠 블록 목록
                   result["content"] = handle_computer_action(block.name, block.input)
               except Exception as err:
                   result["content"] = f"Error: {err}"
                   result["is_error"] = True
                   failed = True
           tool_results.append(result)
       return tool_results

4. 4

   에이전트 루프 구현

   이전 두 단계를 결과를 다시 보내고 Claude가 더 이상 멤버 도구 호출을 반환하지 않을 때까지 반복하는 루프로 감쌉니다. 에이전트 루프 이해하기에서 이 루프를 보여줍니다.

오류 처리

실패한 작업은 is_error: true와 짧은 설명이 포함된 tool_result로 Claude에게 보고하고, 다른 멤버 결과와 마찬가지로 "toolset_name": "computer"를 포함하세요. 실패한 작업이 배치 작업의 일부였다면, 배치의 나머지 블록은 실행하지 말고 해당 섹션에 나온 중단 텍스트로 응답하세요.

예를 들어, 스크린샷 캡처가 실패한 경우:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "toolset_name": "computer",
      "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
      "is_error": true
    }
  ]
}

디스플레이 범위를 벗어난 좌표나 실행에 실패한 작업에도 무엇이 잘못되었는지 설명하는 메시지와 함께 같은 형태를 사용하세요.

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

컴퓨터 사용 도구 세트에 반환하는 스크린샷과 확대 이미지는 이미 모델의 이미지 크기 제한 내에 맞아야 합니다. 도구 세트는 디스플레이 크기를 받지 않고 API가 대신 축소해 주지 않으므로, 크기가 초과된 tool_result 이미지는 유효성 검사 오류와 함께 거부됩니다. Claude는 전달받은 이미지의 픽셀 공간 기준으로 좌표를 반환하므로, 해당 좌표를 화면에 다시 매핑할 수 있도록 사용한 배율을 보관하세요.

화면이 제한보다 크다면 각 스크린샷을 반환하기 전에 크기를 조정하고, Claude가 반환한 좌표를 원래 화면 공간으로 다시 변환하세요. 도구 세트는 디스플레이 크기를 받지 않으므로, 애플리케이션 코드에서의 크기 조정과 좌표 변환만 있으면 됩니다.

import math

screen_width, screen_height = 1512, 982


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)

디스플레이 해상도를 선택하고 스크린샷을 반환할 때는 다음을 따르세요.

• 일반적인 데스크톱 작업에는 1024x768 또는 1280x720을, 웹 애플리케이션에는 1280x800 또는 1366x768을 사용하세요.
• 성능 문제를 방지하려면 1920x1080보다 높은 해상도는 피하세요.
• 스크린샷은 base64 PNG 또는 JPEG로 인코딩하고, 성능 향상을 위해 큰 스크린샷은 압축하는 것을 고려하세요.
• 타임스탬프나 디스플레이 상태 같은 관련 메타데이터를 포함하세요.
• 더 높은 해상도를 사용하는 경우 좌표가 정확하게 변환되는지 확인하세요.

스크린샷 기록 관리

긴 에이전트 루프에서는 스크린샷이 빠르게 누적됩니다(각각 약 1,000–1,800 입력 토큰). API의 요청 제한도 적용됩니다. 단일 요청에 20개를 초과하는 이미지가 포함되면, 그 안의 모든 이미지에 더 엄격한 변당 제한이 적용됩니다. 스크린샷 기록을 유지하는 루프는 수십 턴 이내에 그 개수에 도달하므로, 각 스크린샷의 크기를 조정하여 해당 제한 이하로 유지하거나, 이전 스크린샷을 정리하여 요청에 20개 이하로 유지하세요.

컨텍스트를 제한하면서 프롬프트 캐싱의 효과를 유지하려면 다음을 따르세요.

• 시스템 프롬프트와 도구 정의 뒤에 cache_control 중단점 하나를 두고, 가장 최근 턴들의 마지막 tool_result 블록에 최대 세 개를 더 두되, 매 턴마다 이를 앞으로 이동시키세요. 배치 작업 내에서는 여러 블록의 마커가 하나의 중단점으로 작동하지만, 각각이 여전히 네 개 제한에 포함되므로 한 턴에는 최대 하나만 사용하세요.
• 이전 스크린샷은 매 턴 하나씩이 아니라 일괄로 정리하세요. 매 턴 스크린샷을 제거하면 매 턴 접두사가 바뀌어 캐시가 무효화됩니다. 합리적인 기본값은 마지막 스크린샷 세 개를 유지하고 25턴마다 정리하는 것으로, 이렇게 하면 정리 시점 사이에 접두사가 바이트 단위로 동일하게 유지됩니다. 스크린샷이 더 엄격한 제한을 초과한다면, 각 요청이 20개 이하의 이미지를 유지하도록 간격을 선택하세요.
• Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 및 Claude Haiku 5.5에서는 클라이언트에서 정리하지 마세요. 요청에서 이전 스크린샷을 제거하면 해당 요청과 이후의 모든 요청에서 그 이후의 모든 사고 블록이 무효화됩니다. 대신 스크린샷의 크기를 조정하여 더 엄격한 제한 이하로 유지하고, 서버 측 도구 결과 정리를 사용하여 컨텍스트에서 오래된 스크린샷을 제거하세요. 반드시 정리해야 하는 경우, 그 시점부터 prefix_mismatch_behavior: "drop_block"을 계속 설정해 두세요. 각 정리 후에 Claude는 해당 요청과 이후의 모든 요청에서 정리된 스크린샷 이후에 생성된 사고 없이 계속 진행합니다. Claude Sonnet 5.5와 Claude Haiku 5.5에서 block_binding은 thinking: {"type": "adaptive"}에서만 작동합니다. 해당 모델에서 다른 사고 설정을 사용하는 경우, 기록을 추가 전용(append-only)으로 유지하거나 정리된 스크린샷 이후의 모든 thinking 및 redacted_thinking 블록을 제거하세요.

클릭 문제 진단

클릭이 대상을 빗나간다면 원인은 보통 다음 중 하나입니다.

구현 모범 사례 따르기

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Allow UI to update

display_width, display_height = 1024, 768


def validate_action(action_type, params):
    if action_type == "left_click" and "coordinate" in params:
        x, y = params["coordinate"]
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "Coordinates out of bounds"
    return True, None

import logging


def log_action(action_type, params, result):
    logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")

computer_20251124에서 마이그레이션

computer_20251124 통합은 이전 도구 버전에서 해당 버전에 대해 나열된 모델에서 변경 없이 작동합니다. Claude API의 Claude 5.5 모델처럼 computer_20251124를 허용하지 않는 모델로 통합을 옮기기 전에 통합을 업그레이드하세요.

업그레이드하려면 다음 변경 사항을 함께 적용하세요:

1. 베타 헤더를 제거하세요. 요청에서 anthropic-beta: computer-use-2025-11-24를 삭제하세요. SDK를 사용하는 경우 betas를 제거하고, 베타 네임스페이스가 아닌 표준 클라이언트를 통해 Messages API를 호출하세요.
2. tools 항목을 변경하세요. type을 computer_toolset_20260801로 설정하고 name, display_width_px, display_height_px, display_number, enable_zoom을 삭제하세요. 도구 세트는 이러한 각 필드를 거부합니다.
3. 확대 기능을 활성화된 상태로 유지할지 선택하세요. 도구 세트에서는 확대 기능이 기본적으로 활성화되어 있는 반면, enable_zoom의 기본값은 false입니다. 환경에서 확대 기능을 구현하지 않는다면 이전 동작을 유지하기 위해 "configs": {"zoom": {"enabled": false}}를 추가하고, 그렇지 않다면 이를 구현하세요(사용 가능한 작업 참조).
4. 한 턴의 모든 블록을 처리하세요. 응답에서 첫 번째 블록만 읽는 대신 모든 tool_use 블록을 순회하도록 에이전트 루프를 업데이트하고, input.action 대신 블록의 name과 toolset_name을 함께 기준으로 디스패치하세요. 멤버 입력에는 더 이상 action 필드가 포함되지 않으며, 나머지 필드는 변경되지 않습니다.
5. 블록을 순서대로 실행하고 중단 텍스트를 사용하세요. 배치 작업에 설명된 대로 블록을 순차적으로 실행하고, 첫 번째 실패에서 멈추며, 나머지 블록에는 Not executed: an earlier computer action in this turn failed.로 응답하세요. 루프가 아직 배치 작업을 실행할 수 없다면, 도구 매개변수에서 Claude를 턴당 하나의 작업으로 제한하는 방법을 설명합니다.
6. 결과에 toolset_name을 그대로 포함하세요. 멤버 호출에 응답하는 모든 tool_result에 "toolset_name": "computer"를 추가하세요. 결과에는 text 및 image 콘텐츠만 포함될 수 있습니다.
7. key에서 repeat를 지원하세요. key 멤버는 1에서 100 사이의 선택적 repeat 횟수를 허용합니다. 인식하지 못하는 필드를 무시하는 핸들러는 키를 한 번만 누르게 되므로, key 핸들러가 repeat를 따르도록 하세요.
8. 스크린샷 크기를 직접 조정하세요. 도구 세트는 모델의 이미지 제한을 초과하는 스크린샷이나 확대 이미지를 축소하는 대신 거부합니다. 이미지를 반환하기 전에 크기를 조정하고, 이미지 제한에 맞게 스크린샷 크기 조정에 설명된 대로 좌표 변환을 계속하세요.
9. 지원되지 않는 옵션을 제거하세요. defer_loading이 있다면 항목에서 configs로 옮기고, 활성화된 모든 멤버에 동일한 값을 지정하세요. 도구 세트 항목에서 지원되지 않는 다른 옵션은 클라이언트 도구 세트에 나열되어 있습니다.

다음은 anthropic-beta: computer-use-2025-11-24 헤더와 함께 전송되는 변경 전 tools 항목입니다.

{
  "type": "computer_20251124",
  "name": "computer",
  "display_width_px": 1024,
  "display_height_px": 768,
  "display_number": 1
}

다음은 베타 헤더 없이 전송되는 변경 후 tools 항목입니다. enable_zoom을 설정하지 않은 이전 항목과 일치하도록 configs 객체가 확대 기능을 끈 상태로 유지합니다. 기본값을 받아들여 Claude가 확대할 수 있게 하려면 configs를 완전히 생략하세요.

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  }
}

다음 쌍은 변경 전후의 tool_use 블록을 보여 줍니다. 작업 이름이 input.action에서 name으로 옮겨지고, 블록에 toolset_name이 추가됩니다.

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "computer",
  "input": { "action": "left_click", "coordinate": [500, 300] }
}

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300] }
}

이전 도구 버전

컴퓨터 사용 도구의 이전 버전 두 가지가 베타로 제공됩니다. 각 버전은 모든 요청에 해당 베타 헤더가 필요하며, 매개변수는 베타 Messages API 레퍼런스API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.에 문서화되어 있습니다. SDK를 사용하는 경우 betas를 통해 헤더를 전달하고 베타 네임스페이스를 사용하세요. 헤더가 필요한 것은 컴퓨터 사용 도구뿐이며, 같은 요청에 있는 bash 또는 텍스트 편집기 도구에는 필요하지 않습니다.

Amazon Bedrock에서는 Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 및 Claude Haiku 5.5도 computer-use-2025-11-24 베타 헤더와 함께 computer_20251124 도구를 허용합니다.

제한 사항

1. “Latency”(지연 시간): 인간-AI 상호작용에서 컴퓨터 사용의 지연 시간은 사람이 직접 수행하는 일반적인 컴퓨터 작업에 비해 너무 느릴 수 있습니다. 신뢰할 수 있는 환경에서 속도가 중요하지 않은 사용 사례(예: 백그라운드 정보 수집, 자동화된 소프트웨어 테스트)에 집중하세요.
2. 컴퓨터 비전 정확도 및 신뢰성: Claude는 작업을 생성하면서 특정 좌표를 출력할 때 실수하거나 환각을 일으킬 수 있습니다. Claude의 요약된 사고 출력은 모델의 추론을 이해하고 잠재적인 문제를 식별하는 데 도움이 될 수 있습니다. 도구 세트를 지원하는 모델은 기본적으로 사고 텍스트를 생략하므로, 사고 구성에서 display: "summarized"를 설정하세요.
3. 도구 선택 정확도 및 신뢰성: Claude는 작업을 생성하면서 도구를 선택할 때 실수하거나 환각을 일으킬 수 있으며, 문제를 해결하기 위해 예상치 못한 작업을 수행할 수 있습니다. 또한 특수한 애플리케이션이나 여러 애플리케이션과 동시에 상호작용할 때 신뢰성이 낮아질 수 있습니다. 복잡한 작업을 요청할 때는 모델에 신중하게 프롬프트를 작성하세요.
4. 스크롤 신뢰성: 스크롤 작업은 방향 제어(위, 아래, 왼쪽, 오른쪽)와 지정된 양을 지원합니다. 스크롤이 적용되지 않는 애플리케이션에서는 Page Down 같은 키보드 대안이 도움이 될 수 있습니다.
5. 스프레드시트 상호작용: 개별 셀을 선택하려면 세밀한 마우스 제어 작업(left_mouse_down, left_mouse_up)과 수정자 키 조합을 사용하세요. 복잡한 스프레드시트 작업은 여전히 여러 번의 시도가 필요할 수 있습니다.
6. 소셜 및 커뮤니케이션 플랫폼에서의 계정 생성 및 콘텐츠 생성: Claude는 웹사이트를 방문하지만, 소셜 미디어 웹사이트와 플랫폼 전반에서 계정을 생성하거나, 콘텐츠를 생성 및 공유하거나, 기타 방식으로 사람을 사칭하는 능력은 제한되어 있습니다.
7. 취약점: 탈옥(jailbreak)과 프롬프트 인젝션은 다른 모든 최첨단 AI 시스템과 마찬가지로 컴퓨터 사용에 영향을 줄 수 있으며, 여기에는 웹페이지나 이미지에 포함된 지시를 통한 경우도 포함됩니다. 보안 고려 사항의 예방 조치를 적용하세요.
8. 부적절하거나 불법적인 작업: Anthropic의 서비스 약관에 따라, 컴퓨터 사용을 이용하여 법률이나 허용 사용 정책을 위반해서는 안 됩니다.

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

데이터 보존

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

애플리케이션이 컴퓨터 사용 데이터의 저장 위치와 방식을 제어하므로, 컴퓨터 사용은 ZDR 적용 대상입니다.

가격

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

도구 세트 정의 오버헤드: 기본 멤버와 함께 computer_toolset_20260801을 선언하면 요청에 약 4,500개의 입력 토큰이 추가되며(Claude Sonnet 5에서는 약 4,590개, 기타 지원 모델에서는 약 4,520개), 여기에는 멤버 도구 정의와 도구 사용 시스템 프롬프트가 포함됩니다. configs로 zoom을 비활성화하면 이 중 약 410개의 토큰이 제거됩니다. 요청의 정확한 토큰 수는 응답의 usage에 보고되며, 토큰 카운팅 엔드포인트를 사용하여 미리 추정할 수 있습니다.

이전 도구 버전: 다음 수치는 computer_toolset_20260801이 아닌 computer_20251124 및 computer_20250124 도구 버전에 적용됩니다:

• 시스템 프롬프트 오버헤드: 시스템 프롬프트에 466–499개의 토큰 추가
• 도구 정의: 도구 정의당 약 735개의 입력 토큰(computer_20250124로 측정)

추가 토큰 소비:

• 도구 결과로 반환되는 스크린샷 및 확대 이미지는 이미지 입력으로 청구됩니다(비전 가격 참조)
• Claude에 반환되는 도구 실행 결과

다음 단계

제공 여부