agent-desktop 사용법, AI가 데스크톱 앱을 직접 쓰게 하는 오픈소스
agent-desktop 사용법을 설치, 권한 설정, 첫 명령, 코딩 에이전트 연결, 주의할 점 순서로 정리했습니다. agent-desktop은 Vercel Labs가 공개한 오픈소스 도구로, 화면을 스크린샷으로 추측하는 대신 운영체제의 접근성 트리(앱 화면의 버튼과 입력칸을 구조로 알려 주는 정보)를 읽어서 AI 에이전트가 데스크톱 앱을 조작하게 합니다.

agent-desktop은 어떤 도구인가
agent-desktop은 Rust로 만든 명령줄 도구(CLI)이자 다른 언어에서 부를 수 있는 라이브러리입니다. 앱의 현재 화면을 스냅샷으로 찍으면 눌러 볼 수 있는 요소마다 ref(참조 번호)가 붙은 JSON이 나옵니다. 에이전트는 픽셀 위치를 짐작해 클릭하는 대신 "이 ref를 클릭해"라고 명령합니다.
- 스크린샷이 아니라 접근성 트리를 읽습니다. 픽셀 위치를 맞추는 방식이 아니라 요소를 직접 가리키는 방식입니다.
- ref 기반 동작은 접근성 API를 통해 실행되고 기본이 헤드리스(화면을 가져가지 않는 방식)입니다.
--headed옵션을 주지 않으면 마우스 포인터를 움직이거나 앱에 포커스를 가져가지 않아서, 사용자는 하던 작업을 계속할 수 있습니다. - 복잡한 앱은 스켈레톤 스냅샷으로 구조부터 훑고, 필요한 영역만 골라 자세히 읽을 수 있습니다. 화면 전체를 한 번에 읽지 않고 필요한 부분만 파고드는 방식입니다.
- 라이선스는 Apache-2.0이라 개인과 상업 용도로 무료로 쓸 수 있습니다.
웹사이트 작업은 ego lite나 Aside 같은 AI 브라우저가 맡고, 이 도구는 브라우저 밖의 데스크톱 앱(파인더, 메모장, 슬랙 같은 프로그램)을 다룹니다. 비교가 필요하면 AI 브라우저 비교, Aside·
시작 전에 알아 둘 것
- 운영체제: macOS, Windows, Linux를 지원합니다. 지원 범위는 운영체제마다 조금씩 다릅니다. 예를 들어 맥의 시스템 셸 화면 열기(open-system-surface)는 계획 단계이고 윈도우는 지원합니다. 내 운영체제에서 되는 기능은 설치 뒤
agent-desktop skills get platform으로 확인합니다. - 필요한 것: npm을 쓸 수 있는 환경(Node.js)과 클로드 코드, 커서 같은 코딩 에이전트.
- 비용: 오픈소스라 도구 자체는 무료입니다. 에이전트와 모델 이용료는 따로 듭니다.
- 완성도: 일부 기능은 아직 열려 있지 않습니다.
key-down,key-up,mouse-down,mouse-up네 명령은 눌린 키나 버튼을 풀어 줄 장치가 갖춰질 때까지 실행을 거부합니다. 중요한 업무에 쓰기 전에 작은 앱으로 먼저 시험합니다.
1. 설치하기
- 터미널을 엽니다. 맥은 터미널 앱, 윈도우는 PowerShell을 씁니다.
- 확인: 명령을 입력할 수 있는 창이 열립니다.
- 아래 명령으로 설치합니다. bun, yarn, pnpm으로도 설치할 수 있습니다.
- 확인: 설치가 오류 없이 끝납니다.
npm install -g agent-desktop
- 아래 명령으로 설치를 확인합니다.
agent-desktop version
- 확인: 버전이 출력됩니다. 명령을 못 찾으면 터미널을 껐다 켜고, 윈도우에서는
Get-Command agent-desktop, 맥과 리눅스에서는command -v agent-desktop으로 어느 파일이 실행되는지 봅니다.
윈도우에서 설치 파일을 직접 받아 쓸 때는 서명이 없는 실행 파일이라 SmartScreen이 경고하거나 백신이 격리할 수 있습니다. 공식 설치 안내에 따르면 npm으로 설치하면 이 경고가 뜨지 않습니다.
2. 권한 설정하기
맥: 손쉬운 사용 권한
맥에서는 손쉬운 사용(Accessibility) 권한이 있어야 앱 화면을 읽을 수 있습니다.
- 터미널에서 아래 명령을 실행합니다.
- 확인: 시스템 설정이 부족한 권한 항목으로 열리고 화면 안내가 나옵니다.
agent-desktop permissions --guide
- 안내에 따라 손쉬운 사용 목록에서 허용합니다.
- 확인:
agent-desktop permissions를 다시 실행했을 때 권한 상태가 허용으로 나옵니다.
- 확인:
스크린샷을 찍으려면 화면 기록 권한이, 알림 센터를 열려면 시스템 이벤트에 대한 자동화 권한이 따로 필요합니다. 쓰지 않을 기능이라면 허용하지 않습니다.
윈도우와 리눅스
윈도우는 터미널과 같은 권한 수준으로 실행 중인 앱에는 별도 허용이 필요 없습니다. 관리자 권한으로 실행 중인 앱은 읽을 수는 있지만 입력은 관리자 권한의 에이전트만 보낼 수 있습니다. 리눅스는 그래픽 세션과 at-spi2-core
3. 직접 명령 해 보기
에이전트에 연결하기 전에 터미널에서 직접 몇 줄 실행해 보면 동작 방식이 눈에 들어옵니다. 맥의 파인더를 예로 듭니다. 파인더 창을 하나 열어 둔 상태에서 진행합니다.
- 눌러 볼 수 있는 요소의 목록을 ref와 함께 받습니다.
- 확인: 요소마다
@s8f3k2p9:e8같은 ref가 붙은 JSON이 나옵니다.
- 확인: 요소마다
agent-desktop snapshot --app Finder -i
- 목록에서 누르고 싶은 요소의 ref로 클릭합니다. ref는 방금 받은 스냅샷에서 고릅니다.
- 확인: 해당 요소가 눌립니다.
agent-desktop click @s8f3k2p9:e8
- 결과를 확인하려고 스냅샷을 다시 받습니다.
- 확인: 화면이 바뀐 상태가 목록에 반영됩니다.
agent-desktop snapshot --app Finder -i
ref는 스냅샷 한 번에 묶여 있습니다. 화면이 바뀐 뒤 옛 ref를 쓰면 오류가 나므로 새 스냅샷을 받아 다시 시도합니다. 창이 여러 개 열린 앱에서는 대상이 모호하다는 오류(AMBIGUOUS_TARGET)가 나오는데, 이때는 --window-id
agent-desktop snapshot --skeleton --app Slack -i --compact
4. 코딩 에이전트에 연결하기
에이전트가 이 도구 사용법을 알게 하는 방법은 두 가지입니다.
- 스킬로 설치합니다.
- 확인: 설치한 에이전트의 스킬 목록에 agent-desktop이 보입니다. 클로드 코드는 세션에서
/skills로 확인합니다.
- 확인: 설치한 에이전트의 스킬 목록에 agent-desktop이 보입니다. 클로드 코드는 세션에서
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop
- 스킬 대신 에이전트의 지침 파일(AGENTS.md 등)에 "처음 쓰기 전에
agent-desktop skills get desktop과 agent-desktop skills get platform을 실행해 사용법을 읽어라"고 적어도 됩니다. - 확인: 에이전트가 첫 작업 전에 두 명령을 실행합니다.
연결한 뒤에는 데스크톱 앱의 테스트나 반복 작업을 말로 시킵니다. 처음에는 쓰기 동작이 없는 요청부터 시작합니다.
agent-desktop으로 파인더 창의 사이드바 항목 이름을 모두 읽어서 목록으로 알려 줘. 클릭이나 삭제는 하지 마.
쓰기 전에 알아둘 주의점
- 스냅샷, 창 제목, 클립보드, 알림, 스크린샷에는 내 화면의 개인 내용이 담길 수 있습니다. 공식 문서도 이런 내용을 공개 로그에 남기지 말라고 경고합니다. 에이전트가 찍은 화면이나 디버그 기록을 글이나 이슈에 올리기 전에 한 번 확인합니다.
- 디버그용 HTML과 세션 기록에는 스크린샷이 남을 수 있고, 가림 처리를 했다고 해서 공유해도 안전해지는 것은 아닙니다.
- 에이전트에게 데스크톱 앱 조작을 맡기면 앱에서 할 수 있는 일을 모두 할 수 있습니다. 파일 삭제, 메시지 전송, 결제 같은 되돌리기 어려운 동작은 맡기지 않거나 마지막 단계를 내가 누릅니다.
- 클로드 코드의 권한 확인을 모두 건너뛰는 모드는 격리된 환경에서만 쓰라고 앤트로픽이 안내하는 모드입니다. 내 PC의 앱을 다루는 용도로는 켜지 않습니다.
설치 확인과 지우기
- 확인:
agent-desktop version이 버전을 출력하고, 맥에서는 agent-desktop permissions의 상태가 허용입니다. - 지우기: npm으로 설치했다면
npm uninstall -g agent-desktop으로 제거합니다. 스킬은 에이전트의 스킬 폴더(클로드 코드 개인용은 ~/.claude/skills/아래)에서 해당 폴더를 지웁니다. 맥에서는 시스템 설정의 손쉬운 사용 목록에서 허용해 준 항목도 함께 끕니다.
자주 묻는 질문
agent-desktop은 무엇을 하는 도구인가요?
AI 에이전트가 데스크톱 앱을 읽고 조작하게 해 주는 오픈소스 CLI입니다. 스크린샷 대신 접근성 트리를 읽어 요소마다 ref를 붙이고, 에이전트가 ref로 클릭과 입력을 합니다.
agent-desktop 설치는 어떻게 하나요?
npm install -g agent-desktop 한 줄로 설치하고 agent-desktop versionagent-desktop permissions --guide
윈도우와 리눅스에서도 쓸 수 있나요?
쓸 수 있습니다. macOS, Windows, Linux를 지원하지만 운영체제마다 되는 기능이 다릅니다. 리눅스는 그래픽 세션과 at-spi2-core가 필요하고, 일부 기능은 X11이나 Wayland에 따라 달라집니다.
agent-desktop과 AI 브라우저는 어떻게 다른가요?
AI 브라우저는 웹사이트를 다루고, agent-desktop은 브라우저 밖의 데스크톱 앱을 다룹니다. 웹 작업만 필요하면 ego lite나 Aside가 더 맞고, 파인더나 설치형 프로그램까지 조작해야 할 때 이 도구를 씁니다.
안전하게 쓰려면 무엇을 조심해야 하나요?
화면에 담긴 개인 내용이 스냅샷과 기록에 남을 수 있으니 공개 장소에 올리지 않습니다. 쓰기 동작이 없는 요청부터 시작하고, 삭제와 전송 같은 되돌리기 어려운 일은 마지막 버튼을 직접 누릅니다.
이 글의 본문은 아래 원본 유튜브 영상의 내용을 바탕으로 쓸모연구소가 다시 정리해 쓴 것입니다. 세부 내용과 최신 정보는 원본 영상과 공식 안내에서 확인해 주세요.
원본 영상 보러가기 ↗