클로드 코드 agent-desktop 설치법: 내 PC 앱 조작시키기
클로드 코드에 일을 시키다 보면 꼭 막히는 데가 있어요. 터미널 안에서는 뭐든 잘하는데, 메모장이나 파인더처럼 창이 뜨는 앱 앞에서는 손이 없거든요.
오늘 깃허브에서 눈에 띈 agent-desktop은 그 손을 달아 주는 도구예요. 버셀 랩스 저장소에 올라와 있고, 지난 10월 27일에 1.0이 나왔습니다. 별은 11월 3일 기준 9,240개예요.

agent-desktop, 화면을 보지 않고 앱을 읽어요
AI가 PC를 조작한다고 하면 보통 화면을 찍어서 어디를 누를지 맞히는 방식을 떠올려요. 이 도구는 다릅니다. 운영체제가 원래 갖고 있는 접근성 트리(화면 낭독기 같은 보조 기능이 앱의 버튼과 입력칸을 읽는 구조)를 JSON으로 꺼내 줘요.
버튼마다 @s8f3k2p9:e8 같은 번호(ref)가 붙고, 에이전트는 그 번호를 눌러요. 누른 뒤에는 다시 읽어서 결과를 확인합니다. 픽셀을 맞히는 과정이 없어요.

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

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

설치는 한 줄, 권한은 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 list-apps에 나오는 걸 쓰면 돼요.
agent-desktop snapshot --app Finder -i
agent-desktop click @s8f3k2p9:e8
agent-desktop snapshot --app Finder -i

번호는 그 스냅샷에서만 유효해요. 화면이 바뀌면 STALE_REF 오류가 돌아오고, 새로 찍어서 다시 하면 됩니다. 오류마다 다시 시도해도 안전한지 알려 주는 값이 붙어 있어서 에이전트가 같은 동작을 두 번 하는 일을 줄여 줘요.
기본은 헤드리스예요. 마우스 커서를 움직이지 않고 포커스도 뺏지 않아서, 내가 PC를 쓰는 동안 뒤에서 돌 수 있습니다. 끌어 놓기처럼 진짜 입력이 필요한 동작만 --headed를 붙여요. 공식 안내는 실패했다고 --headed로 바꿔 재시도하지 말라고 합니다. 첫 시도가 이미 들어갔다면 두 번 실행될 수 있어서요.


클로드 코드에 붙이는 법
실행 파일 안에 사용 설명서가 들어 있는 게 재밌어요. 버전에 맞는 안내를 에이전트가 직접 읽게 하는 구조입니다. 붙이는 방법은 둘이에요.
첫째는 스킬 설치예요. 버셀의 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.

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

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

하지만 앱 조작까지는 못 갔어요. 이 파이는 화면 없는 서버에 데비안 12라, 접근성 버스가 없어서 list-apps가 PLATFORM_NOT_SUPPORTED로 끝납니다. 문서에 적힌 조건 그대로죠. 그래서 이 글의 조작 설명은 공식 문서와 데모 영상 기준이고, 실제 앱을 눌러 본 후기는 아니에요.
리눅스라면 하나 더 봐야 해요. 웨이랜드에서는 앱 포인터 입력이 거부되고 창 제어도 안 됩니다. X11이 더 많이 돼요.

쓰기 전에 꼭 볼 것
화면 내용을 통째로 AI에게 읽어 주는 도구라는 점이 제일 커요. 공식 문서도 스냅샷, 클립보드, 스크린샷에 개인 정보가 담길 수 있으니 공개 로그나 업로드에 넣지 말라고 적어 뒀습니다.
skills.sh 보안 점검에서는 3곳 중 2곳이 통과, 스닉이 중간 등급 경고 1건을 냈어요. 내용은 간접 프롬프트 주입 위험입니다. 다른 창이나 알림에 들어온 글을 에이전트가 읽다가 그 안의 악성 지시를 따를 수 있다는 얘기예요. 이건 도구의 버그라기보다 화면을 읽는 방식 자체에 붙는 위험입니다.

제 생각엔 처음부터 메일이나 은행 앱이 열린 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일 확인)
컴퓨터가 고장 났다면 부산 컴퓨터수리 · 출장수리 부컴에 맡겨 주세요. 부산·울산·김해·양산 어디든 직접 방문합니다.
