Claude 가이드 #16: Computer Use — Claude에게 화면을 보여주고 마우스를 맡겨봐요

이 글은 Claude API 공식 문서의 Computer Use(컴퓨터 사용 도구) 페이지를 정리한 글입니다. 원문: https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool 마지막 확인: 2026-05-26

1. 한 줄 요약
#

Computer Use는 Claude에게 화면을 보여주고 마우스·키보드를 맡기는 기능입니다. 글로 부탁만 하면, Claude가 직접 클릭하고 입력해서 일을 끝냅니다.

2. 무엇이고 왜 좋을까
#

옆자리에 앉은 친구에게 “이것 좀 대신 해줘"라고 부탁하고 화면을 잠깐 빌려주는 것과 같습니다.

지금까지 Claude는 글로만 대화했지만, Computer Use를 켜면 이야기가 달라집니다. Claude가 직접 화면을 캡처(스크린샷, 화면 사진을 찍는 것) 해서 무엇이 보이는지 확인하고, 마우스를 움직여 버튼을 누르고, 키보드로 글자를 칩니다. “고양이 사진을 찾아서 바탕화면에 저장해줘” 같은 부탁을 사람처럼 해냅니다.

핵심 수치 하나만 기억하세요. 이 기능은 아직 베타(beta, 시험 단계) 단계이며, 사용하려면 요청에 특별한 헤더(computer-use-2025-11-24)를 한 줄 추가해야 합니다. 즉, 정식 출시 전 단계라 천천히 둘러보는 마음으로 시작하면 좋습니다.

3. 이런 상황에서 써요
#

상황 1: “강의 사이트 자료 모으기가 너무 귀찮아요” (학생)
#

학기말에 강의 사이트 다섯 군데에 흩어진 PDF를 한 번에 내려받아 폴더에 정리하고 싶을 때가 있죠. 사이트마다 로그인하고, 자료실 들어가고, 하나씩 내려받는 일을 반복하다 보면 30분이 훌쩍 지나갑니다. Computer Use에게 “강의 사이트 목록을 열어 자료실의 PDF들을 다운로드 폴더에 받아둬"라고 부탁하면, 옆에서 화면이 움직이는 모습을 지켜보는 동안 일이 끝납니다. 단, 로그인 정보는 신중히 다뤄야 한다는 점만 꼭 기억해두세요.

상황 2: “직원들이 매번 같은 화면 캡처를 요청해요” (직장인)
#

회사에서 매주 같은 사내 시스템에 들어가 보고서를 캡처해서 메일로 보내는 일이 반복된다면, Computer Use가 그 자리를 대신할 수 있습니다. “사내 대시보드에 들어가 이번 주 매출 화면을 캡처해서 폴더에 저장해줘” 같은 단순 반복 업무가 잘 맞습니다. 사람이 직접 하던 단순 클릭 작업을 옆에 맡겨두고, 그동안 사람은 더 머리 쓸 일에 집중할 수 있어요.

상황 3: “긴 문서를 다른 프로그램에 옮기고 싶어요” (일반인)
#

내려받은 PDF의 글 일부를 메모장 앱이나 워드프로세서에 붙여 넣고, 일정한 형식으로 정리하고 싶을 때가 있습니다. 평소엔 직접 PDF를 열고, 글자를 드래그하고, 다른 앱으로 옮겨 다듬어야 했죠. Computer Use에게 “이 PDF의 1~3페이지 글을 새 문서에 옮겨 적고 제목을 굵게 표시해줘"라고 부탁하면, 사람 손이 가던 단순한 작업을 대신해줍니다. 결과가 마음에 들지 않으면 도중에 멈추고 다시 요청하면 됩니다.

4. 가볍게 시작하기
#

💻 개발 경험이 있으신가요? 아래 코드는 Python 기준 가장 짧은 예시입니다. 비개발자라면 “이런 식으로 쓰는구나” 정도로 보고 넘어가셔도 좋습니다. 코드를 직접 돌리지 않아도 이 글의 흐름을 이해하는 데 전혀 지장이 없습니다.

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[
        {
            "type": "computer_20251124",          # 컴퓨터 사용 도구
            "name": "computer",
            "display_width_px": 1024,             # 화면 가로 크기
            "display_height_px": 768,             # 화면 세로 크기
            "display_number": 1,
        },
    ],
    messages=[{
        "role": "user",
        "content": "바탕화면에 고양이 사진을 한 장 저장해줘."
    }],
    betas=["computer-use-2025-11-24"],            # 베타 사용 선언 (필수)
)
print(response)

여기서 핵심은 세 가지입니다. 첫째, tools에 computer 도구를 등록해 Claude에게 “너 이제 화면을 볼 수 있어"라고 알려줍니다. 둘째, display_width_px·display_height_px로 보여줄 화면 크기를 정해줍니다. 셋째, betas 한 줄을 넣어야 베타 기능이 활성화됩니다. 단, 이 코드만으로는 마우스가 실제로 움직이지 않습니다 — 별도의 가상 화면 환경(예: 도커 컨테이너)이 필요하며, Anthropic이 제공하는 참고 구현체(reference implementation) 를 그대로 가져다 쓰는 것이 가장 빠른 출발점입니다.

5. 흔한 오해와 함정
#

⚠️ 함정 1: “코드만 넣으면 바로 마우스가 움직이나요?”
#

아닙니다. Claude는 “이 자리에 클릭해줘"라고 요청할 뿐, 실제로 마우스를 움직이는 건 여러분의 컴퓨터(또는 가상 컴퓨터)입니다. 그래서 별도의 가상 화면 환경이 꼭 있어야 합니다. 처음에는 Anthropic이 제공하는 도커(Docker, 격리된 가상 환경) 기반 참고 구현체부터 그대로 가져와 돌려보는 게 가장 편합니다. “왜 안 움직이지?” 싶다면 보통 환경 설정이 빠진 경우예요.

⚠️ 함정 2: “내 노트북에서 직접 돌려도 안전하겠죠?”
#

위험합니다. Claude가 실수로 중요한 파일을 옮기거나 지울 수도 있고, 웹사이트에 숨어 있는 악의적인 글에 속아 엉뚱한 일을 할 수도 있어요(이를 프롬프트 인젝션이라 합니다). 그래서 공식 문서도 가상 머신이나 도커 컨테이너처럼 격리된 환경에서만 쓰라고 권장합니다. 그리고 은행 로그인이나 개인 메일처럼 민감한 곳에는 절대 접근시키지 마세요.

⚠️ 함정 3: “클릭이 자꾸 살짝 빗나가요”
#

화면 크기 때문일 가능성이 높습니다. 코드에 적은 display_width_px·display_height_px 값과 실제로 보여주는 화면 크기가 다르면, Claude가 계산한 좌표가 어긋납니다. 특히 맥북의 레티나 화면은 실제보다 두 배 큰 사진을 찍기 때문에, 화면 사진을 절반 크기로 줄이거나 좌표를 절반으로 나눠야 합니다. “❌ 큰 화면 그대로 보내기 → ✅ 약속된 크기로 줄여서 보내기"를 기억하세요.

6. 한 단계 더 (관심 있는 분만)
#

🎯 여기까지 오신 분 환영합니다. 이 섹션은 더 깊이 알고 싶은 분을 위한 보너스입니다. 본문만 읽으셔도 충분합니다.

Computer Use는 단독으로도 쓰지만, 보통은 다른 도구와 함께 써야 일이 더 매끄러워집니다. 화면 클릭은 Computer Use가, 파일 편집은 텍스트 편집기 도구가, 명령어 실행은 배시(Bash) 도구가 맡는 식이죠. 세 도구를 동시에 켜는 모습은 이렇게 생겼습니다.

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

그리고 작은 팁 하나 더. 공식 문서는 “한 단계마다 화면 사진을 다시 찍고 결과를 확인한 다음 다음 단계로 넘어가“라고 Claude에게 미리 일러두라고 권합니다. 사람도 클릭한 뒤에 화면을 한 번 더 보잖아요? 그 습관을 글로 가르쳐주면 실수가 눈에 띄게 줄어듭니다. 토큰 비용 측면에서는 시스템 안내문에 약 466~499 토큰, 도구 정의에 735 토큰이 추가되므로, 화면 사진 한 장 한 장이 모여 비용이 쌓인다는 점도 알아두시면 좋아요.

7. 한 마디
#

Computer Use는 지금까지 만난 Claude 기능 중 가장 신기하면서도 가장 조심스러운 기능입니다. 처음엔 “내 컴퓨터를 누가 만지는 게 무섭다"는 마음이 들 수도 있어요. 그래서 공식 참고 구현체를 도커 환경에서 돌려 분리된 가상 컴퓨터 안에서 먼저 놀아보는 걸 권합니다. 클릭이 빗나가거나 멈춰도 괜찮습니다 — 함정 1~3 중 하나일 가능성이 가장 커요.

다음 글에서는 Claude 가이드 #17 — 텍스트 편집기 도구(Text Editor Tool) 를 만나보겠습니다. Computer Use가 화면을 보고 클릭한다면, 텍스트 편집기 도구는 파일 내용을 직접 정밀하게 고치는 친구예요. 둘이 짝이 잘 맞는답니다.

Claude API 공식 문서를 한국어로 풀어쓴 시리즈입니다. 원문 정확성이 가장 우선, 의역과 친근함은 그 위에서.