데스크톱 앱도 Agent 제어 가능: agent-desktop 모델 연동 5단계 튜토리얼

작성자 주: 이 글은 agent-desktop의 설치, 권한 부여, snapshot/click 루프, MCP 연결 방법을 다루고, ‘루프 속의 두뇌’에 모델과 Base URL을 어떻게 설정하는지도 설명해요.

프로그래밍 에이전트나 직접 만든 에이전트가 Finder를 클릭하고, 시스템 설정을 채우고, 네이티브 클라이언트를 조작하게 하는 일은 지금까지 사실상 스크린샷과 비전 모델, 픽셀 좌표에 의존할 수밖에 없었어요. 과정도 길고 잘못 클릭하기도 쉬웠죠. Vercel Labs가 오픈소스로 공개한 agent-desktop은 다른 길을 택했어요. 운영체제의 접근성 트리(Accessibility Tree)를 읽어 데스크톱 화면을 ref가 붙은 JSON으로 바꾸고, 에이전트는 ref를 기준으로 클릭과 입력을 실행해요. 이것이 바로 이 도구가 말하는 ‘스크린샷 없는 computer use’예요.

이건 AI를 품은 또 하나의 데스크톱 로봇이 아니에요. 시작하기 전에 세 가지를 먼저 짚고 갈게요.

agent-desktop에는 모델이 없어요: 바이너리에 LLM이 내장되어 있지 않고, GUI도 없고, 대화형 프롬프트도 없어요. 각 명령은 JSON envelope를 출력하고 바로 종료돼요.
루프는 호출하는 쪽에 있어요: 관찰-행동-검증(observe-act-verify) 루프는 호출하는 에이전트, 예컨대 Claude Code, OpenCode, 또는 직접 작성한 스크립트가 담당해요.
웹은 건드리지 않아요: 웹 자동화는 같은 계열 프로젝트인 agent-browser에 맡기고, agent-desktop은 네이티브 데스크톱 앱만 다뤄요.

도구 자체에 모델이 없으니 ‘두뇌’는 호출하는 에이전트가 제공해야 하고, 이 단계에는 API 키와 토큰이 필요해요. 호출하는 에이전트의 Base URL을 APIYI apiyi.com으로 지정하면 하나의 키로 claude-opus-5-5, claude-sonnet-5-5 같은 모델을 호출할 수 있어요.

핵심 가치: 이 글을 다 읽고 나면 agent-desktop을 설치하고, 권한을 부여하고, snapshot → click → 다시 snapshot이라는 최소 루프를 끝까지 실행한 뒤, MCP로 자신의 에이전트에 연결하고, 모델 쪽 Base URL과 모델명까지 설정할 수 있게 돼요.

agent-desktop 핵심 요점

먼저 표 하나로 agent-desktop의 포지셔닝을 살펴볼게요. 아래 표 정보는 공식 README, FAQ, 문서 사이트를 바탕으로 했으며, 확인 날짜는 2026-11-13입니다.

요점	설명	개발자에게 주는 가치
데이터 소스	OS 접근성 트리를 읽음: macOS는 AX API, Windows는 UI Automation, Linux는 AT-SPI 사용	스크린샷과 픽셀 매칭에 의존하지 않아 구조화 수준이 높음
출력 형식	각 명령은 JSON envelope 하나를 출력한 뒤 종료하며, 요소에는 ref가 포함됨	LLM이 파싱하기 쉽고, 스크립트에서 검증하기도 편리함
기본 모드	headless, 접근성 API 사용, 포인터를 움직이지 않고 포커스를 빼앗지 않음	백그라운드에서 조작할 수 있어 사용자를 방해하지 않음
모델 포함 여부	포함하지 않음, 루프는 호출하는 쪽이 담당	모델은 직접 선택하고, 비용과 효과는 호출하는 쪽에서 제어
연결 방식	CLI, MCP(stdio), skills, C 라이브러리 FFI	Claude Code, OpenCode, 직접 만든 Agent에 연결 가능

2026-11-13 기준 GitHub 저장소 vercel-labs/agent-desktop는 약 22,900개의 스타를 받았고, Apache-2.0 라이선스를 사용합니다. npm 패키지 이름은 agent-desktop이며, 당일에도 새 커밋이 올라왔어요. 명령은 총 61개 이름, 그중 57개가 실행 가능하며, Observe, Act on ref, Keyboard mouse, Apps windows, Notifications, Clipboard, Wait, Sessions, Sandboxes, System 등의 그룹으로 나뉩니다.

agent-desktop의 작동 원리: 접근성 트리와 ref

agent-desktop의 핵심 개념은 snapshot과 ref예요. snapshot을 실행하면 대상 앱의 접근성 트리를 순회해서 버튼, 텍스트 상자, 메뉴 항목 같은 요소를 JSON으로 출력하고, 각 요소에 ref를 할당해요. 완전한 ref는 @s8f3k2p9:e8 같은 형태인데, 앞부분은 이번 snapshot의 식별자이고 뒷부분은 요소 번호예요.

ref는 그것을 만들어 낸 그 snapshot에만 속해요. 맨 @e8만 넘기면 INVALID_ARGS가 돌아와요. 화면이 바뀌면 이전 ref가 무효가 될 수 있고, 그러면 STALE_REF나 AMBIGUOUS_TARGET이 반환되니 다시 snapshot을 떠야 해요. 이 설계는 호출하는 쪽이 매번 행동한 뒤에 다시 관찰하도록 강제하는데, 바로 observe-act-verify에서 “검증” 단계에 해당해요.

위 그림에서 “Agent가 ref 선택” 단계는 모델이 판단을 내리는 부분이에요. agent-desktop은 인터페이스를 구조화해서 넘겨줄 뿐이고, JSON을 읽고 어떤 요소를 클릭할지 결정하는 건 호출하는 쪽 모델의 몫이에요.

agent-desktop과 agent-browser의 역할 분담

두 프로젝트는 모두 Vercel Labs 소속이고 문서 사이트도 함께 운영하지만, 책임 경계는 아주 명확해요:

비교 항목	agent-desktop	agent-browser
목표	네이티브 데스크톱 앱(Finder, 시스템 설정, 네이티브 클라이언트)	웹페이지 및 브라우저 페이지
관찰 방식	OS 접근성 트리	브라우저 측 페이지 구조
Chromium / Electron 앱	DevTools 포트를 통해 agent-browser에 넘길 수 있음	이런 앱의 웹 콘텐츠를 인계받기에 적합
모델 포함 여부	포함하지 않음	마찬가지로 Agent가 호출하는 도구로 제공
대표 명령	`snapshot`, `click`, `clipboard-set`	페이지 중심의 탐색과 상호작용

실용적인 분담 방식 하나는 이래요. 네이티브 창, 메뉴 막대, Dock, 알림은 agent-desktop에 맡기고, 웹페이지나 Electron 앱 안의 웹 콘텐츠를 만나면 DevTools 포트를 통해 agent-browser로 전환하는 거예요.

agent-desktop 버전 이정표와 사실 출처

agent-desktop은 빠르게 업데이트되고 있으며, 몇몇 핵심 버전에서는 동작 변화가 있었고 일부는 파괴적 변경(breaking change)이었어요. 아래 표에는 사실 출처를 함께 표시했으며, ‘알 수 없음’은 공식 자료에서 아직 명확하지 않다는 뜻이에요.

버전 / 날짜	주요 변화	출처
1.0.0(2026-10-27)	Linux 지원이 정식으로 1.0 버전에 포함됨	공식 Changelog
1.1.0(2026-11-02)	envelope가 2.6으로 업그레이드됨; macOS Dock 및 menu-bar-extras 지원; 신원 증명 관련 파괴적 변경	공식 Changelog
1.2.0(2026-11-05)	MCP 추가(`agent-desktop mcp`); type / set-value / clipboard-set에서 `--stdin` 지원	공식 Changelog
1.3.0(2026-11-11)	`agent-desktop sandbox`와 macOS sandbox provider 추가; menu/menubar snapshot에서 더 이상 data.window를 포함하지 않음(파괴적)	공식 Changelog
Windows / Linux 샌드박스	해당 provider가 제공될지 여부	알 수 없음

agent-desktop 빠른 시작

아래에서는 ‘설치 → 권한 부여 → 최소 동작 흐름 → MCP 연동’ 순서로 한 번 따라가 볼게요.

1단계: agent-desktop 설치

플랫폼 요구 사항은 macOS 13 이상; Windows 10 1809 이상(x64 / ARM64); Linux는 Ubuntu 24.04 이상(x86_64 / aarch64)이며, X11이나 Wayland 모두 괜찮아요. 설치 방법은 다음 중 하나를 선택하면 됩니다:

npm(Node 18 이상 필요, 패키지에 각 플랫폼 네이티브 바이너리 포함): npm install -g agent-desktop
Homebrew(macOS / Linux, 이미 homebrew-core에 등록됨): brew install agent-desktop
네이티브 아카이브: GitHub Releases에서 다운로드하고, helper는 실행 파일 옆에 두어야 해요

설치가 끝나면 먼저 agent-desktop status를 실행해서 바이너리와 현재 플랫폼 환경이 정상인지 확인하세요.

2단계: agent-desktop 권한 승인

macOS에서는 터미널이나 호스트 프로세스에 ‘손쉬운 사용’ 권한을 부여해야 해요. 그렇지 않으면 접근성 트리를 읽을 수 없어요. 공식에서 안내 명령을 제공하니 참고하세요:

agent-desktop permissions --guide: 안내에 따라 시스템 설정에서 손쉬운 사용 권한을 부여하세요
권한 부여를 마친 뒤 agent-desktop status를 한 번 더 실행해 확인하세요

주의할 점은 권한 부여 대상이 ‘agent-desktop을 실행하는 그 프로세스’라는 거예요. Claude Code, 특정 IDE, 또는 MCP 클라이언트를 통해 간접적으로 호출한다면 해당 호스트 애플리케이션에 권한을 부여해야 할 수도 있어요.

3단계: snapshot → click → snapshot 최소 루프 완성하기

Finder를 예로 들면, 세 개의 명령만으로 한 번의 완전한 관찰-행동-검증을 구성할 수 있어요:

agent-desktop snapshot --app Finder -i: Finder의 접근성 트리를 가져오고, -i는 상호작용 가능한 요소에 포커스를 맞추는 옵션이에요. 출력 JSON에는 @s8f3k2p9:e8 같은 ref가 포함돼요
agent-desktop click @s8f3k2p9:e8: 이전 snapshot에서 얻은 대상 요소를 클릭해요. 반드시 ref 전체를 작성해야 해요
agent-desktop snapshot --app Finder -i: 다시 관찰해서 인터페이스가 예상대로 변했는지 검증해요

2단계에서 STALE_REF 또는 AMBIGUOUS_TARGET 오류가 발생하면 인터페이스가 이미 바뀐 것이니, 1단계로 돌아가 다시 snapshot을 찍으면 돼요. 실제 포인터나 키보드 이벤트가 필요한 애플리케이션을 만나면 전역 파라미터 --headed를 추가해서 물리 입력 모드로 전환할 수 있어요.

요소가 많은 인터페이스에서 한 번에 전체 snapshot을 찍으면 출력이 매우 길어지고 모델 토큰도 낭비돼요. 두 단계로 나눠 가져올 수 있어요:

agent-desktop snapshot --skeleton --app Finder: 먼저 뼈대를 가져와 대략적인 영역을 파악해요
agent-desktop snapshot --app Finder --root @<뼈대 속 ref>: 그다음 특정 하위 트리로 내려가요

이 기법은 모델에 전달되는 컨텍스트를 눈에 띄게 줄여줘요. 호출하는 쪽 입장에서는 컨텍스트가 짧을수록 토큰 기반 과금 비용이 낮아져요.

4단계: MCP와 skills로 에이전트 연결하기

1.2.0부터 agent-desktop에는 MCP 서비스가 내장되어 있고, stdio 방식으로 동작하며 desktop_snapshot, desktop_click 같은 도구를 노출해요. 클라이언트마다 설정 형식이 조금씩 다릅니다. 아래는 예시예요:

실행 명령: agent-desktop mcp
일반적인 JSON 설정 예시: {"mcpServers": {"agent-desktop": {"command": "agent-desktop", "args": ["mcp"]}}}
Claude Code 예시: claude mcp add agent-desktop -- agent-desktop mcp

사용하는 에이전트가 skills를 지원한다면 공식 사용 설명을 직접 불러와 모델이 어떻게 호출해야 하는지 알게 할 수도 있어요:

agent-desktop skills get desktop, agent-desktop skills get platform: 스킬 설명을 출력합니다
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop: skills.sh를 통해 설치합니다

같은 프로세스에서 호출해야 하는 경우라면 C 라이브러리 libagent_desktop_ffi를 사용할 수도 있어요.

선택 사항: 1.3.0의 agent-desktop sandbox

1.3.0에는 agent-desktop sandbox 하위 명령과 macOS sandbox provider가 새로 추가됐어요. 로컬에서 서명된 macOS 가상 머신에서 자동화를 실행해 에이전트의 작업을 실제 데스크톱과 격리할 수 있어요. 필수 단계는 아니고, 최소 동작 흐름도 여기에 의존하지 않아요. 에이전트가 실제 파일을 잘못 건드릴까 걱정되거나 탐색적 작업을 대량으로 돌리고 싶다면 먼저 고려해 보세요.

🚀 빠른 시작: MCP를 설정한 뒤에는 호출하는 에이전트에 사용할 수 있는 모델이 필요해요. 공식 권장 방식은 APIYI apiyi.com 콘솔에서 토큰을 만들고 에이전트의 Base URL을 그쪽으로 지정하는 거예요. 키 하나로 Claude, GPT, Gemini 등 모델 사이를 전환하며 비교할 수 있어요.

agent-desktop 루프에 모델 “두뇌” 연결하기

agent-desktop은 “눈과 손”만 담당해요. 어느 ref를 클릭할지, 작업이 끝났는지 판단하는 “두뇌”는 호출하는 쪽에 있죠. 이 단계에는 Base URL과 모델명, 두 가지 핵심 설정이 있어요.

Base URL: /v1 포함 여부를 확실히

호출하는 Agent는 보통 두 가지 프로토콜을 쓰는데, Base URL 표기법이 달라요. 잘못 쓰면 404가 나는 가장 흔한 원인이에요.

OpenAI 호환 프로토콜 (대부분의 자작 스크립트, OpenCode의 OpenAI 호환 provider): https://api.apiyi.com/v1, /v1 포함
Anthropic 네이티브 프로토콜 (Claude Code처럼 messages 인터페이스를 직접 쓰는 클라이언트): https://api.apiyi.com, /v1 미포함

Claude Code를 예로 들면, 환경 변수로 설정을示意할 수 있어요. (설정 예시는 다음과 같아요.)

export ANTHROPIC_BASE_URL=https://api.apiyi.com
export ANTHROPIC_AUTH_TOKEN=你的令牌

Python이나 Node로 직접 만든 스크립트에서 OpenAI SDK를 쓸 때는 base_url을 https://api.apiyi.com/v1로, model은 claude-opus-5-5로 채우면 돼요. 토큰은 api.apiyi.com/token에서 만들고, 자세한 설정은 docs.apiyi.com/faq/base-url-config.md를 참고하세요.

자작 Agent 루프는 어떻게 작성할까

기성 Agent에 의존하고 싶지 않다면, 직접 루프를 작성하는 것도 어렵지 않아요. 핵심 단계는 다음과 같아요.

agent-desktop snapshot --app 目标应用 -i를 실행하고, stdout의 JSON envelope 읽기
작업 목표와 snapshot JSON을 함께 모델에 보내고, 다음 단계 동작과 전체 ref만 반환하도록 요청
모델이 준 명령 실행, 예: agent-desktop click @sxxxx:eN
다시 snapshot하고 새 결과를 모델에 넘겨 완료 여부 판단; STALE_REF를 받으면 바로 다시 관찰
최대 스텝 수와 사람 확인 지점을 설정해 무한 루프나 권한 밖의 조작 방지

여기서 2단계와 4단계는 모두 Token을 소모해요. 앞서 언급한 --skeleton과 --root 하위 탐색 방식은 여기서 비용에 직접 영향을 줘요.

선택: claude-opus-5-5와 claude-sonnet-5-5

두 Claude 모델 모두 APIYI 모델 총목록에 등록되어 있고, chat과 messages 엔드포인트를 동시에 지원해요. 아래 표의 가격 데이터 기준일은 2026-11-13이고, 단위는 1M Tokens당이에요. 모델과 가격은 플랫폼 모델 목록을 기준으로 해요.

모델	입력	출력	캐시 읽기	적합한 agent-desktop 시나리오	사용 가능 플랫폼
`claude-opus-5-5`	$4	$20	$0.2	다단계, 복잡한 UI, 강한 계획이 필요한 작업	APIYI apiyi.com
`claude-sonnet-5-5`	$2	$10	$0.1	단계가 명확하고 반복성이 강한 일상 작업	APIYI apiyi.com

한 가지 실용적인 방법은 먼저 claude-opus-5-5로 흐름을 끝까지 돌려 보고, 프롬프트와 단계를 확정한 뒤 안정된 구간을 claude-sonnet-5-5로 옮길 수 있는지 평가하는 거예요. snapshot JSON에는 반복되는 시스템 프롬프트와 도구 설명이 많고, 캐시 읽기 가격이 입력 가격보다 확실히 낮아서 긴 루프에서는 프롬프트 캐시를 켜는 게 유리해요. 최신 가격은 docs.apiyi.com/models를 기준으로 하세요.

agent-desktop 문제 해결: 권한 문제일까, 모델 문제일까

agent-desktop과 모델은 서로 독립된 두 개의 연결 경로예요. 오류가 났을 때 어느 쪽에서 문제가 생겼는지 먼저 판단하면 시행착오를 크게 줄일 수 있어요.

현상	해당 경로	가능한 원인	처리 방법
snapshot이 비어 있거나 앱을 읽을 수 없음	도구 측	보조 기능 접근 권한이 부여되지 않았거나, 앱 자체가 접근성 트리를 노출하지 않음	`agent-desktop permissions --guide`를 실행해 호스트 프로세스 권한 확인
`INVALID_ARGS`	도구 측	맨 ref만 적음, 예: `@e8`	전체 ref 사용, 예: `@s8f3k2p9:e8`
`STALE_REF` / `AMBIGUOUS_TARGET`	도구 측	화면이 바뀌어 ref가 무효화됨	snapshot 다시 실행
모델 요청 401	모델 측	토큰 오류, 만료, 또는 환경 변수가 적용되지 않음	`api.apiyi.com/token`에서 토큰을 확인하고 다시 export
모델 요청 404	모델 측	Base URL의 `/v1`을 잘못 적었거나 모델명 철자가 틀림	OpenAI 호환은 `/v1` 포함, Anthropic 네이티브는 미포함; 모델 대조표 확인

간단히 판단하는 방법은 이래요. agent-desktop 명령이 터미널에서 단독으로 JSON을 출력할 수 있다면 도구 측에는 문제가 없다는 뜻이고, 남은 오류는 대부분 모델 측에 있어요. 모델 측 401/404는 APIYI apiyi.com 문서 센터의 Base URL 설정 안내와 대조해 항목별로 확인하면 돼요.

agent-desktop 권한 및 개인정보 리스크

이 섹션에서는 데스크톱 자동화 자체의 리스크를 다룹니다. 계정과는 무관하지만, 사용을 시작하기 전에 한 번쯤 꼼꼼히 살펴볼 만한 내용이에요.

접근성 권한의 무게. macOS에서 접근성을 켜면, 권한을 부여받은 프로세스가 다른 앱의 UI를 읽고 조작할 수 있게 됩니다. 터미널이나 특정 Agent 호스트에 권한을 주면, 그 프로세스 안에서 실행되는 모든 프로그램이 동일한 능력을 얻을 수 있어요. 필요한 호스트에만 권한을 주고, 사용이 끝나면 시스템 설정에서 꺼두는 걸 권장합니다.

snapshot, 클립보드, 스크린샷에는 모두 개인정보가 담길 수 있어요. 공식 문서에서도 snapshot, 클립보드 내용, 스크린샷, 알림, 디버그 HTML에 채팅 내용, 메일 제목, 파일 이름, 비밀번호 관리자 화면 같은 데스크톱의 민감 정보가 포함될 수 있다고 명확히 경고합니다. 이런 데이터는 호출하는 쪽에서 모델로 보내지기 때문에, 디버그 로그를 공개 업로드하거나 이슈에 전체 snapshot을 그대로 붙여 넣는 일은 피해야 해요.

선택적 헬퍼는 네트워크에 연결돼요. 네이티브 CLI 자체는 원격 모델 서비스를 요구하지 않지만, 선택적 JEV 헬퍼를 활성화하면 대상과 화면 설명을 설정한 모델 공급자에게 전송합니다. 켤지 말지, 누구에게 보낼지, 모두 스스로 판단해야 해요.

조작의 결과는 사용자가 감당해야 해요. Agent가 잘못된 버튼을 누르거나, 엉뚱한 파일을 삭제하거나, 보내면 안 되는 메시지를 보낼 수 있습니다. 이런 리스크를 줄이려면 1.3.0의 샌드박스에서 시험 실행하고, --app 범위를 제한하며, 삭제·전송·결제 같은 고위험 작업에는 사람이 확인하는 절차를 추가하면 좋아요. 또한 접근성 트리에서 읽히지 않는 앱은 agent-desktop에게 보이지 않는다는 점도 기억해 두세요. 이건 능력의 경계예요. 모든 소프트웨어를 반드시 조작할 수 있다고 기대하면 안 됩니다.

서드파티 Agent를 게이트웨이에 연결하는 것은 또 다른 리스크예요. Claude Code, OpenCode 같은 서드파티 Agent를 어떤 API 게이트웨이에 연결하든, 토큰 보관, 할당량 상한, 로그에 민감한 내용이 기록되는지 여부를 반드시 살펴야 합니다. 이건 데스크톱 자동화 리스크와 별도로 평가해야 하는 부분이에요. Agent 전용 토큰을 따로 만들고 할당량을 설정해 두면, 문제가 생겼을 때 해당 토큰만 폐기할 수 있습니다.

자주 묻는 질문 FAQ

Q1: agent-desktop이란 무엇인가요?

agent-desktop은 Vercel Labs에서 오픈소스로 공개한 computer use CLI입니다. OS 접근성 트리를 통해 AI Agent가 macOS, Windows, Linux의 데스크톱 앱을 보고 조작할 수 있게 해 줍니다. 스크린샷이나 픽셀 매칭에 의존하지 않아요. Agent를 위한 도구일 뿐, 그 자체에 모델이 포함되어 있지는 않습니다.

Q2: agent-desktop과 스크린샷 기반 computer use의 차이는 무엇인가요?

스크린샷 기반 방식은 비전 모델이 픽셀을 이해한 뒤 좌표를 내놓는 구조라 처리 경로가 길고 해상도에도 영향을 받기 쉽습니다. agent-desktop은 구조화된 JSON과 ref를 직접 출력하고, 모델은 ref에 따라 조작합니다. 기본적으로 헤드리스 모드로 실행되며 포인터와 포커스를 빼앗지 않아요. 대신 접근성 정보를 노출한 앱만 볼 수 있다는 제약이 있습니다.

Q3: agent-desktop은 현재 어떤 버전인가요?

2026-11-13 기준으로 확인되는 최신 버전 노드는 1.3.0(2026-11-11)이며, 샌드박스 기능이 추가되었습니다. MCP는 1.2.0(2026-11-05)부터 제공되고, Linux는 1.0.0(2026-10-27)에서 정식 1.0에 들어섰어요. 버전 업데이트가 빠른 편이라 GitHub Releases를 기준으로 확인해 주세요.

Q4: agent-desktop은 어떤 상황에 적합한가요?

– **네이티브 앱 테스트**: 설정 패널을 자동으로 클릭하고 UI 상태 검증
– **코딩 Agent 확장**: Claude Code가 코드 작성 후 데스크톱 앱을 열어 결과를 확인하도록 확장
– **반복적인 데스크톱 작업**: Finder 파일 정리, 알림 읽기, 클립보드 읽기/쓰기

웹 관련 작업은 agent-browser에 맡기세요.

Q5: agent-desktop을 호출하는 Agent는 모델을 어떻게 빠르게 연결하나요?

1. APIYI apiyi.com에서 가입하고 토큰 페이지에서 API Key를 만드세요. 신규 사용자에게는 무료 테스트 한도가 있습니다.
2. OpenAI 호환 클라이언트는 Base URL을 `https://api.apiyi.com/v1`로, Anthropic 네이티브 클라이언트는 `https://api.apiyi.com`으로 설정하세요.
3. 모델은 `claude-opus-5-5` 또는 `claude-sonnet-5-5`를 선택한 뒤, 이 글에서 설명한 snapshot 흐름을 실행하세요.

Q6: MCP를 설정했는데 Agent가 401이나 404를 보고한다면 agent-desktop 문제인가요?

보통 아닙니다. agent-desktop은 모델 서비스에 연결하지 않아요. 401은 대개 토큰 문제이고, 404는 `/v1`을 잘못 적었거나 모델명 철자가 틀린 경우가 많습니다. 먼저 터미널에서 `agent-desktop snapshot`을 단독 실행해 도구가 정상인지 확인한 다음, APIYI apiyi.com의 Base URL 설정 문서와 대조해 모델 쪽을 점검하세요.

Q7: agent-desktop에는 어떤 알려진 제한이 있나요?

– 접근성 트리에서 읽히지 않는 앱은 보이지 않습니다
– 일부 버전(예: 1.1.0, 1.3.0)에 호환성을 깨는 변경이 있으므로 업그레이드 전에 Changelog를 읽어 주세요
– 샌드박스 프로바이더는 현재 macOS 대상이며, 다른 플랫폼의 지원 여부는 아직 알려지지 않았습니다
– 웹 자동화는 지원하지 않으므로 agent-browser와 함께 사용해야 합니다

agent-desktop 핵심 요약 Key Takeaways

도구에 모델이 없음: agent-desktop은 JSON envelope만 출력하고, 루프와 의사결정은 호출하는 쪽이 담당해요
스크린샷 없는 computer use: AX, UI Automation, AT-SPI 접근성 트리를 기반으로 ref에 따라 동작해요
ref는 반드시 완전해야 함: @s8f3k2p9:e8 형태이며, 화면이 바뀌면 snapshot을 다시 떠야 해요
세 플랫폼 지원: macOS 13+, Windows 10 1809+, Ubuntu 24.04+
MCP 한 줄로 연결: 1.2.0부터 agent-desktop mcp가 stdio로 동작해요
웹페이지는 agent-browser에 맡김: Electron 앱은 DevTools 포트를 통해 넘길 수 있어요
두뇌 연결: 호출하는 쪽의 Base URL을 APIYI apiyi.com으로 지정하고 claude-opus-5-5를 선택하세요

요약

agent-desktop의 핵심 요점은 다음과 같아요.

역할이 분명해요: 데스크톱 앱의 “눈과 손” 역할이며, 모델을 포함하지 않고 웹도 다루지 않아요
시작이 간단해요: 설치 → permissions --guide → snapshot → click → 다시 snapshot, --skeleton으로 컨텍스트 길이를 조절해요
연결이 유연해요: CLI, MCP, skills, FFI 모두 가능하고, 1.3.0의 sandbox는 격리 테스트 실행에 적합해요
리스크는 관리해야 해요: 접근성 권한 부여와 snapshot에 담기는 프라이빗 정보는 데스크톱 자동화 기준에 맞춰 관리해야 해요

도구 쪽이 잘 돌아가면, 남은 일은 루프에 알맞은 두뇌를 붙이는 거예요. APIYI apiyi.com에서 토큰을 만들어 Claude Code, OpenCode 또는 직접 만든 스크립트의 Base URL을 그쪽으로 지정하고, 먼저 claude-opus-5-5로 흐름을 검증한 뒤 작업 복잡도에 따라 claude-sonnet-5-5로 전환할지 평가하는 걸 권장해요.

📚 참고 자료

GitHub – agent-desktop: 공식 오픈소스 저장소로 README, FAQ, Changelog를 포함해요.
링크: github.com/vercel-labs/agent-desktop
설명: 버전 변경 사항, 명령어 목록, 개인정보 관련 안내는 이 저장소를 기준으로 해요.
agent-desktop 공식 문서: 개념과 빠른 시작
링크: agent-browser.dev/desktop, agent-browser.dev/desktop/quick-start
설명: 설치, 권한 부여, 최소 동작 흐름 예시를 다뤄요.
npm – agent-desktop: npm 패키지 페이지
링크: npmjs.com/package/agent-desktop
설명: 현재 배포된 버전을 확인할 수 있어요.
Vercel – What is computer use: computer use 개념 소개
링크: vercel.com/i/what-is-computer-use
설명: 접근성 트리 방식과 스크린샷 방식의 차이를 이해하는 데 도움이 돼요.
APIYI 문서 센터: 모델 전체 목록, Base URL 설정, Claude 기능 설명
링크: docs.apiyi.com/models.md, docs.apiyi.com/faq/base-url-config.md, docs.apiyi.com/api-capabilities/claude.md
설명: 모델과 가격은 플랫폼의 모델 목록을 기준으로 해요.

작성자: APIYI 기술 팀
기술 문의: APIYI apiyi.com 웹사이트 홈페이지에서 문의해 주세요. 더 많은 자료는 docs.apiyi.com 문서 센터에서 확인할 수 있어요.

데스크톱 앱도 Agent 제어 가능: agent-desktop 모델 연동 5단계 튜토리얼