Computer Use

Qwen Code에는 모델이 데스크톱 애플리케이션을 조작하는 방법을 가르치는 computer-use skill이 있으며, 별도로 설치되는 두 패키지를 통해 동작합니다:

bundled computer-use skill
  -> @qwen-code/node-repl-mcp
  -> @qwen-code/cua-sdk/computer-use
  -> native cua-driver accessibility backend

Qwen Code는 MCP 서버, SDK 또는 네이티브 드라이버를 번들하지 않습니다. skill은 외부 패키지가 누락되어 있을 때 자동으로 설치합니다.

자동 설정

Node.js 22 이상이 필요하며 npm도 필요합니다.

처음 사용 시 skill이 다음 명령을 직접 실행합니다:

qwen mcp add --scope user node-repl npx -y @qwen-code/node-repl-mcp@0.1.6
npm install --no-save --package-lock=false @qwen-code/cua-sdk@0.20.9

MCP 서버가 처음 추가된 후 Qwen Code를 재시작하세요. 그런 다음 skill이 node_repl을 통해 데스크톱 작업을 계속합니다.

SDK 설치는 package.json과 lockfile을 변경하지 않지만, 워크스페이스의 node_modules에는 씁니다. postinstall 스크립트가 현재 플랫폼의 네이티브 페이로드를 다운로드하고 검증합니다.

MCP 구성이나 워크스페이스 SDK 설치를 제거하면 실행 경로가 비활성화됩니다. 레거시 폴백은 없습니다.

사용

Qwen Code에게 데스크톱 작업에 $computer-use를 사용하도록 요청하세요. 부트스트랩 후 macOS에서 앱 워크플로를 사용합니다:

1. computer.getApp(nameOrIdentifierOrPath)로 애플리케이션을 바인딩합니다;
2. 간결한 접근성 텍스트를 위해 app.getState()를 읽고, 이후 자동 증분 업데이트를 수행합니다;
3. 해당 텍스트의 짧은 요소 ID를 사용하여 하나 이상의 동작을 수행합니다;
4. 다음 동작을 결정하기 전에 최신 상태를 가져옵니다.
5. 다른 영구 상태가 필요하지 않을 때만 SDK 클라이언트를 닫고 REPL을 초기화합니다.

드라이버만이 관찰 diff를 계산하는 유일한 구성 요소입니다. 모델 코드는 타입화된 SDK 메서드를 사용하며 임의의 드라이버 도구 이름을 디스패치하지 않습니다. 앱 핸들은 현재 창과 대화 상자를 추적하고, 내부적으로 네이티브 요소 ID를 유지하며, 입력을 네이티브 드라이버에 위임합니다. 모델 코드는 포그라운드/백그라운드 모드를 선택하지 않습니다. 확인되지 않은 동작은 리플레이되지 않습니다. getState()는 발견된 중지된 앱을 열 수 있으며, 동작은 앱을 재시작하지 않습니다. 기존 정확 창 API는 Windows와 Linux에서 계속 사용 가능합니다.

const app = await computer.getApp('Microsoft Excel');
nodeRepl.write((await app.getState()).text);
// Use an element ID from the returned state.
await app.click(37);
await app.typeText('hello');
nodeRepl.write((await app.getState()).text);

요소 ID를 재사용하기 전에 대화 상자를 열거나 닫은 후 상태를 새로고침하세요. 각 App 상태 새로고침은 내부적으로 현재 스크린샷을 캡처합니다. 기본 반환은 숨겨진 상태로 유지하며, 모델이 이미지가 필요할 때 app.getState({ includeScreenshot: true })로 명시적으로 요청하세요.

권한

Node REPL은 일반적인 Node.js 권한으로 모델이 작성한 JavaScript를 실행하는 MCP 서버입니다. 호출은 Qwen Code의 일반 MCP 승인 흐름을 따릅니다. SDK는 네이티브 인증도 강제합니다.

macOS에서 접근성 관찰과 입력에는 Accessibility 권한이 필요합니다. 스크린샷은 추가로 Screen Recording 권한이 필요합니다. macOS는 권한 부여를 Qwen Code를 실행한 터미널이나 IDE에 귀속시킬 수 있습니다. Windows와 Linux는 플랫폼별 접근성 및 입력 기능을 사용합니다.

문제 해결

• 자동 설정 후에도 node_repl을 사용할 수 없으면, Qwen Code를 재시작하고 qwen mcp list로 서버를 확인하세요.
• 자동 설정 후에도 SDK 가져오기가 실패하면, Qwen Code가 패키지가 설치된 워크스페이스에서 실행 중인지 확인하세요.
• 타임아웃, 취소, 초기화 또는 커널 크래시 후, SDK 클라이언트를 다시 부트스트랩하고 새 상태를 요청하세요.

참고 자료

• Skills
• MCP servers
• 승인 모드
• 샌드박싱