Vercel agent-desktop 사용법：Claude Code, Codex, Cursor로 데스크톱 앱 조작하기 (설치, 실측, 오류 해결)

결론부터：agent-desktop은 Vercel Labs의 오픈소스 CLI(Apache-2.0)로, 코딩 에이전트가 네이티브 데스크톱 앱을 "보고" 조작할 수 있게 합니다. 운영체제의 접근성 트리를 읽어 버튼과 입력란마다 ref를 붙입니다. 에이전트는 ref에 대해 동작을 실행한 뒤 화면을 다시 읽어 결과를 확인합니다. 스크린숏을 보고 픽셀 좌표를 추측하는 방식이 아닙니다.

• 에이전트가 아니며 모델도 들어 있지 않습니다. 각 명령은 JSON 하나를 출력하고 끝납니다. "관찰→동작→확인" 루프는 Claude Code, Codex, Cursor 쪽에서 돌기 때문에 세 가지 모두에서 쓸 수 있습니다.
• 설치는 한 줄：npm install -g agent-desktop. 이어서 npx skills add로 공식 skill을 프로젝트에 넣으면 Claude Code, Codex, Cursor가 각각 읽어 들입니다.
• 직접 끝까지 돌려 봤습니다：이 사이트의 API Key로 Claude Code는 약 28.6초, Codex는 약 35초 만에 데스크톱 계산기 버튼을 눌러 결과를 읽어 왔고, 두 답 모두 정확했습니다.
• 먼저 알아 둘 함정 두 가지：일부 앱(이번에 시험한 GTK4판 GNOME 계산기 등)은 컨트롤 위치 정보를 내주지 않아 ref 클릭이 bounds unavailable로 실패합니다. 또 Linux에서 Codex 기본 샌드박스 아래에서는 agent-desktop이 데스크톱 D-Bus에 연결하지 못해 Operation not permitted가 납니다. 해결법은 뒤쪽 오류 섹션에 있습니다.

API Key를 만들고 Claude Code, Codex, Cursor에 agent-desktop 연결하기 →

agent-desktop이 무엇이고 왜 화제인가

10월 31일 아침(베이징 시간) Vercel의 Chris Tate가 X에서 agent-desktop을 발표했습니다. 소개 문구는 "agent-browser, for your whole computer"로, 어떤 코딩 에이전트든 쓸 수 있는 Computer Use이며 macOS, Windows, Linux를 지원하고, 마우스를 뺏지 않고 백그라운드에서 돌며, 여러 에이전트가 동시에 조작할 수 있다는 내용입니다. 11월 1일 오후 기준 이 게시물은 약 64만 회 조회, 좋아요 7,700개 이상, 북마크 8,700개 이상을 기록했습니다. 작성자 Lahfir는 출시 게시물에서 에이전트로 데스크톱 앱 E2E 테스트하기, 접근성 트리로 앱 읽기, 창의 일부만 파고들어 토큰 아끼기, 한 앱을 여러 에이전트가 동시에 조작하기를 핵심으로 꼽았습니다.

GitHub 저장소는 스타 약 5,000개이며, 10월 30일 v1.0.2를 내면서 공식 문서도 함께 공개했습니다. 핵심 사실은 다음과 같습니다.

커뮤니티 반응을 보면, @decildmc에 따르면 그는 Mac의 Computer Use 환경을 cua-driver에서 agent-desktop으로 바꿨는데, 클릭 가능한 요소만 모델에 보내고 마우스를 움직이지 않고 버튼을 바로 누르기 때문이라고 합니다. @o_kwasniewski에 따르면 그는 주말 동안 이를 바탕으로 네이티브 데스크톱 앱 E2E 테스트 데모를 만들었습니다. X 트렌드 요약에 따르면 52단계 데모에서 스켈레톤과 부분 탐색을 써서 토큰을 약 198k에서 약 31k로 줄인 사례도 있습니다.

스크린숏 방식 Computer Use와 비교한 장점은 ref가 안정적이고 안전하게 재시도할 수 있다는 점입니다(오류마다 입력이 전달됐는지 적혀 있음). 한계는 접근성 정보를 공개하는 앱에서만 동작한다는 점입니다.

1단계：agent-desktop 설치하고 권한 확인하기

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

status의 supported_surfaces가 비어 있지 않고 accessibility가 granted면 준비된 것입니다. Linux에서 얻은 정상 출력은 다음과 같습니다.

{"ok":true,"command":"status","data":{"permissions":{"accessibility":{"state":"granted"}},
 "platform":"linux","supported_surfaces":["window","sheet","alert","menu"],"version":"1.0.2"}}

운영체제별 권한：

• macOS：agent-desktop을 실행하는 앱(터미널, iTerm2, VS Code, 에이전트 호스트 앱)에 "손쉬운 사용" 권한을 줍니다. agent-desktop permissions --guide를 실행하면 시스템 설정의 해당 페이지가 열립니다. 스크린숏에는 "화면 기록" 권한도 필요합니다. 자세한 내용은 macOS 문서.
• Windows：별도 권한은 필요 없지만, 관리자 권한으로 실행 중인 앱은 같은 수준으로 권한을 올린 터미널에서 실행하지 않으면 읽기만 되고 조작은 안 됩니다. 바이너리에 서명이 없어 SmartScreen이나 백신이 막을 수 있습니다. 자세한 내용은 Windows 문서.
• Linux：사용자의 그래픽 세션 안에서 실행하고 at-spi2-core를 설치해 둡니다. 자세한 내용은 Linux 문서.

2단계：Claude Code, Codex, Cursor에 연결하기

agent-desktop에는 버전에 맞는 설명서가 들어 있습니다(agent-desktop skills get desktop과 skills get platform). 연결한다는 것은 처음 쓰기 전에 에이전트가 이 두 가지를 읽게 하는 것입니다. 방법은 두 가지이며 하나만 하면 됩니다.

방법 A：skills로 공식 skill 설치(추천)

# in your project root
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop

# non-interactive, pick the clients explicitly
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop \
  -a claude-code -a codex -a cursor -y

프로젝트에서 실행했더니 설치 프로그램 출력은 다음과 같았습니다.

✓ ./.agents/skills/agent-desktop
  universal: Codex, Cursor
  symlinked: Claude Code

즉 skill은 프로젝트의 .agents/skills/agent-desktop에 설치되고, Codex와 Cursor는 이 폴더를 직접 읽으며, Claude Code는 .claude/skills/agent-desktop 심볼릭 링크를 통해 같은 파일을 읽습니다. -g를 붙이면 사용자 단위로 설치되어 모든 프로젝트에서 쓸 수 있습니다. skills 기본 사용법은 AI 에이전트에서 Skills 쓰는 법을 참고하세요.

설치 프로그램은 보안 스캔 결과도 보여 줍니다(이번에는 Gen이 Safe, Socket이 0 alerts, Snyk가 Med Risk). skill은 에이전트의 모든 권한으로 실행된다는 안내도 나오니 설치 전에 SKILL.md를 한 번 읽어 보세요.

방법 B：AGENTS.md / CLAUDE.md에 두 줄 추가

skill을 설치하고 싶지 않다면 공식 문구를 프로젝트의 AGENTS.md(Codex와 Cursor가 읽음)에, Claude Code용으로는 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.

Claude Code와 Codex가 지시 파일 하나를 같이 쓰게 하려면 Claude Code와 Codex가 AGENTS.md 하나를 공유하는 법을 참고하세요.

3단계：이 사이트의 API Key로 클라이언트 설정하기

1. aicodewith.ai에 가입하고 로그인한 뒤 키 관리에서 Key를 만들고, 표시된 문자열 전체를 복사합니다.
2. 사용하는 클라이언트를 설정합니다.

Claude Code：

export ANTHROPIC_BASE_URL="https://api.aicodewith.ai"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"

영구 설정이나 Windows 설정은 Claude Code를 서드파티 API에 연결하는 법을 참고하세요. Cursor에서 모델을 고르는 방법도 같은 글에 있습니다.

Codex：전역 ~/.codex/config.toml에 씁니다.

# ~/.codex/config.toml
model_provider = "aicodewith"
model = "gpt-6.1-sol"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "YOUR_API_KEY"

다른 항목은 Codex config.toml 설정 가이드에 정리했습니다.

Cursor：위 글대로 모델을 설정하면 Cursor 에이전트가 프로젝트의 .agents/skills와 AGENTS.md를 Codex와 같은 방식으로 읽습니다.

4단계：에이전트에게 "관찰→동작→확인" 맡기기

기본 루프는 세 단계입니다. snapshot으로 ref가 붙은 컨트롤 트리를 받고, ref에 click, type 등을 실행한 뒤, 다시 snapshot이나 get으로 확인합니다. ref에는 그것을 만든 snapshot ID가 들어 있으므로(예: @s2jrj9msmdpdlw:e46) 화면이 바뀌면 snapshot을 다시 찍어야 합니다.

agent-desktop list-apps                                # app names agent-desktop can see
agent-desktop snapshot --app galculator -i --compact   # interactive elements, each with a ref
agent-desktop click @s2jrj9msmdpdlw:e46                # act on a ref from that snapshot
agent-desktop snapshot --app galculator -i --compact   # observe again to verify

# dense apps (Electron, IDEs): map a skeleton first, then drill into one region
agent-desktop snapshot --app "Visual Studio Code" --skeleton -i --compact
agent-desktop snapshot --root @sXXXX:e1 -i --compact

요소가 많은 앱(Electron 클라이언트, IDE)은 먼저 얕은 --skeleton을 받은 뒤 --root로 필요한 부분만 펼치라고 공식 문서는 권합니다. 그러면 토큰 사용량이 작업하는 영역에만 비례합니다. 자세한 내용은 스켈레톤과 부분 탐색.

평소에는 이 명령을 직접 칠 필요가 없습니다. 에이전트에게 "agent-desktop으로 X 앱을 열고 Y를 한 다음 결과를 확인해"라고 말하면 됩니다.

실측：이 사이트의 API Key로 Claude Code와 Codex에게 계산기 조작시키기

테스트 날짜는 2026년 11월 1일, 환경은 Linux(Debian 13, X11과 창 관리자 xfwm4), agent-desktop 1.0.2, 대상 앱은 GTK3 계산기 galculator입니다. 과제는 "버튼 클릭만으로 계산하고 수식은 입력하지 말 것, 계산 후 앱에서 결과를 읽어 올 것"입니다. 두 클라이언트 모두 방법 B의 CLAUDE.md / AGENTS.md만 두었습니다.

Claude Code 2.1.316

claude -p "Use agent-desktop to operate the galculator app that is already open: calculate 12 × 34 by clicking its buttons, then read the result back (Edit > Copy Display Value, then agent-desktop clipboard-get). Reply with RESULT=<number>." \
  --model claude-sonnet-4-6 \
  --allowedTools "Bash(agent-desktop:*)"

Claude Code가 실제로 실행한 명령(발췌)：

agent-desktop skills get desktop
agent-desktop skills get platform
agent-desktop snapshot --app "galculator" -i --compact
agent-desktop click @s2jrj9msmdpdlw:e40        # AC
agent-desktop click @s2jrj9msmdpdlw:e46        # 1  (then 2, *, 3, 4, =)
agent-desktop click @s2jrj9msmdpdlw:e6         # "Copy Display Value" -> ACTION_FAILED, menu not open
agent-desktop click @s2jrj9msmdpdlw:e4         # open the Edit menu
agent-desktop snapshot --surface menu --app "galculator" -i --compact
agent-desktop click @s1muxufwf6hxgz:e3         # Copy Display Value
agent-desktop clipboard-get                    # -> 408

CLAUDE.md 지시대로 설명서 두 개를 읽고 snapshot을 찍은 뒤 ref로 버튼을 차례로 눌렀습니다. 처음 "Copy Display Value"를 눌렀을 때는 메뉴가 아직 열리지 않아 아래 오류로 실패했습니다. 그러자 Edit 메뉴를 열고 --surface menu로 snapshot을 다시 찍은 뒤 다시 눌렀고, 마지막에 clipboard-get으로 408을 읽었습니다.

{"ok":false,"command":"click","error":{"code":"ACTION_FAILED",
 "message":"Target is not actionable: visible (live offscreen state is true)"}}

이 머신에서 click 한 번은 약 0.07초였고, 대부분의 시간은 모델이 생각하는 데 쓰였습니다.

Codex 0.164.0

codex exec "Use agent-desktop to operate the galculator app that is already open: calculate 56 × 78 by clicking its buttons, then read the result back from the app. Reply with RESULT=<number>."

실패한 두 번은 모두 처음에 나온 agent-desktop: command not found입니다. 테스트를 위해 agent-desktop을 전역이 아닌 프로젝트 폴더에 설치했는데, Codex가 명령을 실행하는 로그인 셸의 PATH에 들어 있지 않았습니다. Codex는 실행 파일 경로를 스스로 찾아 과제를 마쳤습니다. 실제로 쓸 때는 npm install -g로 전역 설치하세요.

잘 안 된 비교：GTK4판 GNOME 계산기

처음에는 GNOME 계산기(GTK4)로 시험했습니다. agent-desktop은 버튼을 모두 나열했지만 클릭은 매번 bounds unavailable로 실패했습니다. 우리 X11 환경에서 이 앱은 컨트롤 위치 정보를 내주지 않아 가시성 사전 점검을 통과하지 못했고, agent-desktop이 클릭을 거부한 것입니다(delivery: not_delivered이므로 잘못 클릭된 것은 없습니다). 그러자 Claude Code는 mouse-click --headed로 화면 좌표를 추측하기 시작했고, 10분이 지나도 끝나지 않아 직접 중단했습니다. 키보드 입력인 agent-desktop press는 이 앱에서도 동작했습니다.

교훈：bounds unavailable이 계속되면 에이전트에게 좌표를 추측하게 하지 말고 키보드 조작이나 다른 앱으로 바꾸세요. 프롬프트에 "클릭이 실패하면 press로 키를 보내"라고 적어 두는 것도 방법입니다.

API Key를 만들고 내 컴퓨터에서 직접 해 보기 →

자주 나오는 오류와 해결법

agent-desktop 오류는 모두 JSON입니다. error.code와 disposition.retry로 판단하면 됩니다. safe면 입력이 전달되지 않았으니 다시 시도해도 되고, unsafe나 unknown이면 중복 실행을 피하기 위해 먼저 화면을 확인합니다. 전체 목록은 공식 오류 문서에 있습니다. 아래는 실제로 만난 오류입니다.

status가 accessibility denied, supported_surfaces가 비어 있음(Linux)

{"ok":true,"command":"status","data":{"permissions":{"accessibility":{"state":"denied",
 "suggestion":"AT-SPI is not installed or not visible to this process. Install the at-spi2-core package, then retry."}},
 "supported_surfaces":[]}}

AT-SPI가 없거나 프로세스에서 보이지 않는 상태입니다. at-spi2-core를 설치하고 그래픽 세션 안에서 실행하는지 확인하세요(세션 변수가 없는 SSH 셸에서는 앱이 하나도 보이지 않습니다). Flatpak이나 snap 앱은 해당 인터페이스를 열어 줘야 합니다.

list-apps에서 native window type could not be proven

{"ok":false,"command":"list-apps","error":{"code":"ACTION_NOT_SUPPORTED",
 "message":"The native window type of accessibility frame owned by pid 3857714 could not be proven"}}

창 관리자가 없는 가상 디스플레이에서 나왔습니다. 창 관리자(xfwm4)를 띄우자 바로 list-apps가 정상 동작했습니다. 일반 데스크톱 환경에서는 거의 만나지 않습니다.

click이 bounds unavailable로 시간 초과

{"ok":false,"command":"click","error":{"code":"TIMEOUT",
 "message":"Target did not become actionable within the wait budget",
 "details":{"kind":"actionability_timeout","last_report":{"report":{"checks":[
   {"check":"visible","reason":"bounds unavailable","status":"unknown"}]}}},
 "disposition":{"delivery":"not_delivered","retry":"safe"}}}

앱이 위치 정보를 내주지 않는 경우로, --headed를 붙여도 소용없습니다. press로 키보드를 보내거나 접근성 지원이 더 충실한 다른 앱을 쓰세요. 위의 GTK4 사례를 참고하세요.

click이 ACTION_FAILED：visible (live offscreen state is true)로 실패

대상이 지금 화면에 보이지 않는 경우입니다. 예를 들어 닫힌 메뉴 안의 항목입니다. 먼저 메뉴를 열고 snapshot --surface menu로 새 ref를 받으세요.

Codex에서 INTERNAL：Operation not permitted

{"ok":false,"command":"list-apps","error":{"code":"INTERNAL",
 "message":"The accessibility bus returned an unexpected error",
 "platform_detail":"Failed to connect to address `unix:path=/tmp/dbus-...`: Operation not permitted (os error 1)"}}

Linux에서 codex exec -s workspace-write로 실행했을 때 나왔습니다. Codex 샌드박스가 데스크톱 D-Bus 연결을 막아 agent-desktop이 접근성 버스에 닿지 못합니다. agent-desktop 명령은 샌드박스 밖에서 실행되게 하세요. 대화형 모드라면 Codex가 물을 때 그 명령을 승인하고, --dangerously-bypass-approvals-and-sandbox는 전용 테스트 머신이나 VM에서만 쓰세요. 이번 실측은 별도의 테스트용 데스크톱에서 후자로 돌렸습니다.

command not found

/bin/bash: line 1: agent-desktop: command not found

에이전트가 명령을 실행할 때의 PATH에 agent-desktop이 없습니다. npm install -g agent-desktop으로 전역 설치하거나 AGENTS.md에 전체 경로를 적어 두세요.

Windows PowerShell에서 ref가 먹히지 않음

PowerShell은 맨 @xxx를 스플래팅 연산자로 해석하므로 ref를 작은따옴표로 감싸야 합니다.

agent-desktop click '@s8f3k2p9:e8'

보안 주의사항

• snapshot에는 화면에 보이는 내용이 담깁니다. @mikawuf에 따르면 snapshot에는 화면에 표시된 정보가 포함되니 공개 로그에 남기지 말아야 합니다. 비밀번호 관리자나 메신저는 닫은 뒤 에이전트에게 조작을 맡기세요.
• 권한은 필요한 만큼만. Claude Code에서는 --allowedTools "Bash(agent-desktop:*)"로 agent-desktop만 허용할 수 있습니다. Codex 샌드박스는 격리된 환경에서만 끄세요.
• skill과 AGENTS.md는 에이전트가 따르는 지시입니다. 믿을 수 있는 출처만 쓰세요. AGENTS.md 탈취 위험도 참고하세요.
• 클라우드에서 돌리고 싶다면, 작성자 Lahfir에 따르면 Vercel Sandbox에서 띄운 Linux 데스크톱에서도 agent-desktop을 실행할 수 있습니다.

자주 묻는 질문

agent-desktop과 agent-browser는 무엇이 다른가요

agent-browser는 웹 페이지를, agent-desktop은 네이티브 데스크톱 앱을 조작합니다. Chromium이나 Electron 앱 안의 웹 콘텐츠는 agent-desktop이 launch "App" --cdp로 DevTools 포트를 열어 agent-browser에 넘길 수 있습니다.

Computer Use 전용 모델이 필요한가요

필요 없습니다. agent-desktop은 텍스트(JSON)만 출력하므로 셸 명령을 실행할 수 있는 코딩 에이전트라면 무엇이든 쓸 수 있습니다. 이번 실측에서는 Claude Sonnet 4.6과 GPT-6.1 Sol을 썼습니다.

내가 만든 데스크톱 앱의 E2E 테스트에 쓸 수 있나요

쓸 수 있습니다. 작성자가 꼽은 주요 용도 중 하나입니다. 코드 변경이 실제 앱에서 제대로 동작하는지 확인하는 방법은 verification skill로 실제 앱을 돌려 검증하기도 참고하세요.

함께 읽기

• Claude Code를 서드파티 API에 연결하는 법
• Codex config.toml 설정 가이드
• AI 에이전트에서 Skills 쓰는 법
• Claude Code와 Codex가 AGENTS.md 하나를 공유하는 법
• verification skill로 실제 앱을 돌려 검증하기

API Key를 만들고 Claude Code, Codex, Cursor로 시작하기 →