클로드 코드 agent-desktop 설치법: 내 PC 앱 조작시키기

agent-desktop 공식 배너 위에 제목

클로드 코드에 일을 시키다 보면 꼭 막히는 데가 있어요. 터미널 안에서는 뭐든 잘하는데, 메모장이나 파인더처럼 창이 뜨는 앱 앞에서는 손이 없거든요.

오늘 깃허브에서 눈에 띈 agent-desktop은 그 손을 달아 주는 도구예요. 버셀 랩스 저장소에 올라와 있고, 지난 10월 27일에 1.0이 나왔습니다. 별은 11월 3일 기준 9,240개예요.

agent-desktop 공식 배너, 맥 윈도우 리눅스 지원 표시
공식 배너 · 출처: agent-desktop 깃허브

agent-desktop, 화면을 보지 않고 앱을 읽어요

AI가 PC를 조작한다고 하면 보통 화면을 찍어서 어디를 누를지 맞히는 방식을 떠올려요. 이 도구는 다릅니다. 운영체제가 원래 갖고 있는 접근성 트리(화면 낭독기 같은 보조 기능이 앱의 버튼과 입력칸을 읽는 구조)를 JSON으로 꺼내 줘요.

버튼마다 @s8f3k2p9:e8 같은 번호(ref)가 붙고, 에이전트는 그 번호를 눌러요. 누른 뒤에는 다시 읽어서 결과를 확인합니다. 픽셀을 맞히는 과정이 없어요.

vercel-labs/agent-desktop 깃허브 저장소 화면, 별 9.2k 포크 633
별 9.2천 · 포크 633 · 출처: agent-desktop 깃허브

다만 공식 문서가 먼저 선을 긋는 게 있어요. 이건 에이전트가 아니라 에이전트가 부르는 도구입니다. 안에 AI 모델이 없고, 창도 없고, 명령 하나에 JSON 하나를 찍고 끝나요. 판단은 클로드 코드나 코덱스, 또는 직접 짠 스크립트가 맡습니다.

agent-desktop 공식 문서의 무엇이고 무엇이 아닌지 설명
공식 문서가 직접 선을 긋는 부분 · 출처: agent-desktop 공식 문서

웹페이지도 대상이 아니에요. 그건 같은 쪽에서 내놓은 agent-browser 몫이고, 접근성 트리를 공개하지 않는 앱은 볼 수 없습니다. 게임처럼 화면을 직접 그리는 프로그램은 잘 안 맞을 수 있다는 뜻으로 읽었어요.

에이전트에서 CLI와 OS 접근성 API를 거쳐 앱으로 이어지는 공식 구조도
공식 구조도 · 출처: agent-desktop 공식 문서

설치는 한 줄, 권한은 OS마다 달라요

Node.js가 있으면 아래 두 줄이면 됩니다. x64와 ARM64 실행 파일이 패키지에 함께 들어 있고, 공식 Homebrew·Scoop 패키지는 아직 등록 신청 단계예요.

npm install -g agent-desktop
agent-desktop version
agent-desktop status

status를 치면 플랫폼, 권한, 지원 범위가 나와요. 여기서부터 OS별로 갈립니다.

  • 맥: macOS 13 이상. 손쉬운 사용 권한이 필요하고 agent-desktop permissions --guide가 설정 화면까지 안내해 줘요. 스크린샷을 쓰려면 화면 기록 권한도 필요합니다.
  • 윈도우: 윈도우 10 1809 이상. 터미널과 같은 권한으로 뜬 앱은 따로 허용할 게 없어요. 파일에 서명이 없어서 브라우저로 받으면 스마트스크린 경고가 뜰 수 있는데, npm 설치는 해당되지 않는다고 문서에 나와 있습니다.
  • 리눅스: 우분투 24.04 이상이 기준이고 at-spi2-core가 있어야 해요. 로그인한 사용자의 그래픽 세션 안에서 돌려야 하고, SSH로 들어간 셸에서는 앱이 안 보입니다.
agent-desktop README 설치 안내
npm 한 줄로 설치 · 출처: agent-desktop 깃허브

스냅샷, 누르기, 다시 스냅샷

사용법은 세 단계 반복이에요. 맥 파인더를 예로 든 공식 예시입니다. 앱 이름은 agent-desktop list-apps에 나오는 걸 쓰면 돼요.

agent-desktop snapshot --app Finder -i
agent-desktop click @s8f3k2p9:e8
agent-desktop snapshot --app Finder -i
agent-desktop 빠른 시작 명령과 스냅샷 JSON 예시
스냅샷 JSON 예시 · 출처: agent-desktop 깃허브

번호는 그 스냅샷에서만 유효해요. 화면이 바뀌면 STALE_REF 오류가 돌아오고, 새로 찍어서 다시 하면 됩니다. 오류마다 다시 시도해도 안전한지 알려 주는 값이 붙어 있어서 에이전트가 같은 동작을 두 번 하는 일을 줄여 줘요.

기본은 헤드리스예요. 마우스 커서를 움직이지 않고 포커스도 뺏지 않아서, 내가 PC를 쓰는 동안 뒤에서 돌 수 있습니다. 끌어 놓기처럼 진짜 입력이 필요한 동작만 --headed를 붙여요. 공식 안내는 실패했다고 --headed로 바꿔 재시도하지 말라고 합니다. 첫 시도가 이미 들어갔다면 두 번 실행될 수 있어서요.

공식 데모 영상에서 개러지밴드 건반을 누르는 커서
공식 데모 영상 장면 · 출처: agent-desktop 깃허브
공식 데모 영상에서 파인더 파일을 끌어 놓는 장면
공식 데모 영상 장면 · 출처: agent-desktop 깃허브

클로드 코드에 붙이는 법

실행 파일 안에 사용 설명서가 들어 있는 게 재밌어요. 버전에 맞는 안내를 에이전트가 직접 읽게 하는 구조입니다. 붙이는 방법은 둘이에요.

첫째는 스킬 설치예요. 버셀의 skills 도구는 클로드 코드를 -a claude-code로 지정할 수 있습니다.

npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop -a claude-code

둘째는 지침 파일에 한 문단 넣는 방법이에요. 공식 예시는 코덱스 등이 읽는 AGENTS.md 기준인데, 클로드 코드라면 CLAUDE.md에 같은 문장을 넣으면 됩니다. 비슷한 지침 파일 활용은 카파시 스킬 글에서도 다뤘어요.

Use `agent-desktop` to see and operate desktop apps. Before the first use, run
`agent-desktop skills get desktop` and `agent-desktop skills get platform`, and follow them.
agent-desktop 스킬 설치와 AGENTS.md 추가 안내
에이전트에 붙이는 두 가지 방법 · 출처: agent-desktop 깃허브

명령은 이름 기준 60개이고, 그중 key-down처럼 키를 누른 채 유지하는 4개는 지금 막혀 있어 실제로 동작하는 건 56개예요. 앱 실행, 창 옮기기, 알림, 클립보드까지 들어 있습니다.

agent-desktop 명령 그룹표
명령 그룹표 · 출처: agent-desktop 깃허브

라즈베리파이에서 돌려 보니 여기서 멈췄어요

저도 이 블로그가 돌아가는 라즈베리파이 5의 임시 폴더에 넣어 봤어요. 설치 스크립트는 끈 상태로요. 용량은 29MB, ARM64 리눅스용 1.0.2가 바로 응답했습니다.

라즈베리파이 5에서 agent-desktop을 실행한 터미널 결과
라즈베리파이 5 실제 출력 · 출처: 직접 실행

하지만 앱 조작까지는 못 갔어요. 이 파이는 화면 없는 서버에 데비안 12라, 접근성 버스가 없어서 list-apps가 PLATFORM_NOT_SUPPORTED로 끝납니다. 문서에 적힌 조건 그대로죠. 그래서 이 글의 조작 설명은 공식 문서와 데모 영상 기준이고, 실제 앱을 눌러 본 후기는 아니에요.

리눅스라면 하나 더 봐야 해요. 웨이랜드에서는 앱 포인터 입력이 거부되고 창 제어도 안 됩니다. X11이 더 많이 돼요.

맥 윈도우 리눅스별 agent-desktop 지원 범위 표
OS별 지원 범위 · 출처: agent-desktop 깃허브

쓰기 전에 꼭 볼 것

화면 내용을 통째로 AI에게 읽어 주는 도구라는 점이 제일 커요. 공식 문서도 스냅샷, 클립보드, 스크린샷에 개인 정보가 담길 수 있으니 공개 로그나 업로드에 넣지 말라고 적어 뒀습니다.

skills.sh 보안 점검에서는 3곳 중 2곳이 통과, 스닉이 중간 등급 경고 1건을 냈어요. 내용은 간접 프롬프트 주입 위험입니다. 다른 창이나 알림에 들어온 글을 에이전트가 읽다가 그 안의 악성 지시를 따를 수 있다는 얘기예요. 이건 도구의 버그라기보다 화면을 읽는 방식 자체에 붙는 위험입니다.

skills.sh의 agent-desktop 등록 페이지와 보안 점검 결과
스닉 경고 1건 · 출처: skills.sh

제 생각엔 처음부터 메일이나 은행 앱이 열린 PC에서 쓸 도구는 아니에요. 테스트용 계정이나 별도 PC에서, 계산기 같은 작은 앱부터 돌려 보는 게 순서입니다. 공식 문서도 gnome-calculator를 예로 들고 있어요.

개인적으로는 화면 찍고 좌표 맞히는 방식보다 훨씬 믿음이 가요. 앱마다 접근성을 얼마나 잘 만들었느냐에 달린 건 아쉽지만요. 저는 화면 있는 우분투 PC에서 직접 돌려 보고 후기로 정리해 볼 생각입니다. 여러분이라면 어떤 앱부터 맡겨 보고 싶으세요? 클로드 코드로 할 수 있는 다른 도구는 클로드 코드 글 모음과 T3 Code 설치법에 있어요.


출처
· vercel-labs/agent-desktop 깃허브 README
· agent-desktop 공식 문서
· 공식 문서: Headed mode
· 설치·권한 문서
· FAQ(개인 정보 항목)
· 변경 기록
· skills.sh 등록 페이지·보안 점검
· vercel-labs/skills
(2026년 11월 3일 확인)

컴퓨터가 고장 났다면 부산 컴퓨터수리 · 출장수리 부컴에 맡겨 주세요. 부산·울산·김해·양산 어디든 직접 방문합니다.

함께 보면 좋은 글

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다