qwen-audio-agent 딥다이브
— 말하는 동안에도 뒤에서 일이 돌아가는 음성 런타임

1한 줄 정체

qwen-audio-agent는 "이미 있는 코딩 에이전트(OpenCode·Codex·Claude Code 등)를 그대로 두고, 그 앞에 실시간 음성 대화라는 얼굴 하나를 붙여, 사용자가 말로 지시하고 · 대화가 끊기지 않고 · 무거운 작업은 뒤에서 병렬로 처리되게 하는 Node.js 음성 런타임"이다. 한마디로 에이전트의 "입과 귀"다. 두뇌(실제 코딩·툴 실행)는 기존 에이전트가 맡고, 이 프로젝트는 그 두뇌에 항상 켜져 있는 음성 채널을 연결해 준다.

사용자가 마이크에 대고 한 마디 하면 시스템 내부에서 벌어지는 일을 압축하면 이렇다:

여기서 핵심은 ④의 갈림길이다. Realtime 계층은 "지금 당장 입으로 답할 수 있는 것"(시간·날씨 같은 간단한 응답, 기억 조회)만 직접 처리하고, 조금이라도 무거운 것은 전부 기다리지 않고(non-blocking) 백엔드로 던진다. 이 "안 기다림"이 대화의 연속성을 만든다.

2왜 주목받는가 — "기다림 없는 음성"이라는 각도

첫째, 음성 AI의 고질병을 정면으로 건드린다. Siri든 ChatGPT 음성 모드든, "질문하면 → 처리하는 동안 어색한 침묵 → 답변"의 한 턴 왕복 구조다. 특히 에이전트가 실제 일(코드 수정, 자료 검색)을 하기 시작하면 그 침묵이 몇 초~몇 분으로 늘어난다. qwen-audio-agent는 "작업은 뒤로 넘기고 대화는 계속한다"는 발상으로 이 침묵을 없앤다. 음성 UX를 써 본 사람이라면 곧바로 가치를 체감하는 각도다.

둘째, 특정 에이전트에 묶이지 않는다(vendor-neutral). 이 프로젝트는 자기만의 에이전트를 새로 만들지 않았다. 대신 ACP(Agent Client Protocol)라는 표준 통로로 이미 존재하는 코딩 에이전트 9종(OpenCode·OpenClaw·Qoder·Kimi·Hermes·CodeBuddy·Codex·Claude Code·범용 ACP)에 붙는다. "음성은 우리가, 두뇌는 네가 쓰던 걸로" — 이 조합 자유도가 개발자에게 매력적이다.

셋째, 진입 장벽이 낮다. 음성 모델로 알리바바 Qwen Audio 3.0 Realtime을 쓰는데, 알리바바 클라우드 바이롄(百炼/Model Studio)이 무료 체험 크레딧을 준다. 설치는 npm install -g qwen-audio-agent 한 줄이면 되고, macOS에는 데스크톱 앱(플로팅 음성 오브)까지 있다. "무료로 지금 당장 말로 에이전트를 부려 본다"는 체험이 쉽게 손에 잡힌다.

3기술 스택 전체 지도

이 저장소는 npm 워크스페이스(workspaces) 모노레포다. 즉 package.json 하나가 여러 하위 패키지를 묶고, 서로를 로컬 의존으로 참조한다. 5개 워크스페이스가 각자 역할을 맡는다:

백엔드(server) — Express + ws + zod

Gateway 본체는 순수 Node ESM으로 짜였고, 웹 서버 프레임워크는 무겁지 않은 조합을 쓴다.

프론트엔드 — 세 갈래

핵심 외부 서비스 — Qwen Audio 3.0 Realtime (DashScope)

실제 음성 인식·생성은 알리바바 클라우드의 DashScope가 한다. Gateway는 이 클라우드에 WebSocket으로 접속해 오디오를 주고받는다. 접속 규격은 OpenAI Realtime API 호환(beta dialect)이라, OpenAI Realtime을 다뤄 본 사람에겐 메시지 구조가 익숙하다. 입력 16kHz·출력 24kHz PCM.

4아키텍처 심화 — 3계층·게이트웨이·오디오·ACP

축 1 — 3계층 아키텍처 (누가 무엇을 아는가)

사용자에게는 하나의 음성 비서로 보이지만, 내부는 아는 것과 할 일을 셋으로 나눈다(docs/architecture.md).

이 분리에는 엄격한 규칙이 있다. Realtime 계층은 백엔드 어댑터를 import하지 못하고, UI는 공개 이벤트만 소비한다. 즉 "입"은 "두뇌"의 내부를 모른 채 정해진 통로(6개 툴)로만 부탁하고, 화면은 결과 이벤트만 받는다. 계층 간 의존을 단방향으로 고정해 복잡도를 가둔 설계다.

축 2 — Gateway (모든 것이 만나는 허브)

qwenaudio를 실행하면 뜨는 것이 Gateway다. Express(HTTP) + ws(WebSocket) 서버가 기본 127.0.0.1:3101에서 돈다.

• REST: /api/health, /api/tasks(+/:id, /:id/events SSE), /api/timeline, /api/permissions/:id
• WebSocket 업그레이드는 /api/realtime 경로만 수락 — Origin/loopback 검증 + 신원(identity) 필수
• 백그라운드 상주: qwenaudio gateway install이 macOS launchd(~/Library/LaunchAgents/*.plist) 또는 Linux systemd --user 유닛을 만들어 개인 비서를 24시간 켜 둔다. 로그는 ~/.config/qwaudio/logs/gateway.log

축 3 — 오디오 스트리밍 (WebRTC가 아니다)

흔히 실시간 음성이라면 WebRTC를 떠올리지만, 이 프로젝트는 전 구간 raw PCM을 WebSocket에 실어 보낸다. WebSocket 홉이 두 번 있다:

DashScope 세션을 여는 협상 코드(server/src/voice/providers/dashscope.mjs). 여기서 smart_turn이 서버측 VAD(음성 구간 감지)로, "사용자가 말을 끝냈다"를 클라우드가 판단하게 한다:

session.modalities = textOnly ? ['text'] : ['text', 'audio']
session.voice = config.audioVoice          // 기본 'longanqian' 음색
session.input_audio_format = 'pcm'       // 입력 16kHz
session.output_audio_format = 'pcm'      // 출력 24kHz
session.turn_detection = textOnly ? null : { type: 'smart_turn' }  // 서버측 VAD

축 3-b — 끼어들기(barge-in)는 어떻게 즉시 멈추나

비서가 한창 말하는 중에 사용자가 입을 열면, 위 VAD가 input_audio_buffer.speech_started를 보낸다. Gateway는 이걸 받는 즉시 재생을 끊고 상태를 "듣는 중"으로 되돌린다(server/src/voice/realtime-gateway.mjs):

if (event.type === 'input_audio_buffer.speech_started') {
  userSpeaking = true
  clearResponseCandidate()
  announcements.dismissActive()
  send(ws, { type: 'playback.clear', reason: 'user_interruption' })  // 클라 재생 즉시 중단
  send(ws, { type: 'turn.started', turnId })
  send(ws, { type: 'voice.state', state: 'listening', turnId })
  frontend?.cancel()   // 업스트림(DashScope)에 response.cancel
}

반이중(TUI에서 x 키)에서는 VAD 대신 사용자가 보낸 명시적 interrupt 이벤트가 같은 경로를 탄다. 즉 "자동 감지"든 "수동 키"든 끼어들기 로직은 하나로 통일돼 있다.

축 4 — ACP로 이기종 에이전트를 하나로 묶기

백엔드 접속의 심장은 ACP 핸드셰이크다(server/src/agent/acp-process-client.mjs). 에이전트를 자식으로 spawn하고, 그 stdin/stdout을 줄바꿈 구분 JSON 스트림으로 감싼 뒤 프로토콜 버전을 맞춘다:

const child = this.spawn(this.command, this.args, { cwd, env, stdio: ['pipe','pipe','pipe'] })
const stream = acp.ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout))
const app = acp.client({ name: 'qwen-audio-agent' })
  .onRequest(acp.methods.client.session.requestPermission, ctx => this.handlePermission(ctx))
  .onNotification(acp.methods.client.session.update, ctx => this.handleUpdate(ctx.params))
const connection = app.connect(stream)
this.initializeResult = await this.context.request(acp.methods.agent.initialize, {
  protocolVersion: acp.PROTOCOL_VERSION,
  clientInfo: { name: 'qwen-audio-agent', version: PACKAGE_VERSION },
}, { signal: AbortSignal.timeout(15_000) })   // 버전 불일치·무응답이면 즉시 에러

어떤 에이전트에 붙을지는 AGENT_PROTOCOL 환경변수로 고른다(9종). 접속 방식은 조금씩 다르다:

축 4-b — 백그라운드 작업은 대화와 어떻게 병렬로 도나

Realtime의 spawn_thinking(목표) 툴은 결과를 기다리지 않는다. 즉시 "접수됨"만 반환하고 사용자는 계속 말할 수 있다. 실제 실행은 Task 계층이 맡는다(server/src/task/):

• 동시성 제한: 전역 maxConcurrent=4, owner당 2. 단 한 owner의 백엔드 세션엔 한 번에 하나의 Work만 직렬 투입(FIFO)
• Work 상태 흐름: queued → running → (delegated → finalizing) → completed (+ cancelling/failed)
• 결과 회수 = "안전 삽입 창": 작업이 끝나면 결과를 사용자가 말하는 중이 아니고 응답 대기도 없는 조용한 순간에만 자연 발화로 끼워 넣는다(배치 120ms, quiet 350ms)
• 영속화: tasks.json에 원자적 기록(temp→rename) — Gateway가 재시작해도 진행 중이던 작업을 복구

5디렉토리 구조 해부

구조가 알려주는 힌트 둘. 첫째, 가장 큰 두 파일이 realtime-gateway.mjs(1,566줄)와 acp-backend-adapter.mjs(1,506줄)다 — 이 프로젝트의 무게중심이 "음성 파이프라인"과 "백엔드 연결" 딱 두 곳에 실려 있음을 그대로 보여 준다. 둘째, voice/·agent/·task/·conversation/로 폴더가 책임별로 갈려 있어, 관심사(음성/에이전트/작업/기억)가 코드 트리에 1:1로 대응된다. 새 기여자가 "어디를 봐야 하나"를 폴더 이름만으로 찾게 한 배려다.

6학습 포인트 — 기술별 배울 것

① 실시간 음성 프로토콜 (가장 값진 배움)

OpenAI Realtime 호환 규격으로 WebSocket 위에 오디오를 스트리밍하는 실제 코드를 볼 수 있다. session.update로 modality·VAD·음색을 협상하고, audio.append/audio.delta로 PCM을 주고받고, speech_started로 끼어들기를 감지하는 흐름 — 실시간 음성 앱을 만들 때 반드시 마주치는 개념들을 동작하는 참조 구현으로 익힌다. "왜 WebRTC 대신 WS+PCM인가"를 두고 트레이드오프를 생각해 보는 것도 좋은 공부다.

② ACP / stdio JSON-RPC 에이전트 통합

요즘 뜨는 Agent Client Protocol을 실전으로 배운다. 자식 프로세스를 띄우고 stdin/stdout으로 JSON-RPC를 나누는 패턴, initialize 핸드셰이크, 세션 라이프사이클(new/prompt/cancel/close), 권한 요청 콜백까지. 이걸 알면 Codex·Claude Code 같은 CLI 에이전트를 내 프로그램에 붙이는 법이 손에 잡힌다.

③ 논블로킹 대화 UX 설계

"작업을 기다리지 않고 던진다(spawn_thinking) → Work 큐로 병렬 실행 → 조용한 틈에 결과를 자연 발화"라는 비동기 UX 설계. FIFO 큐, 동시성 상한, "안전 삽입 창" 타이밍 로직은 채팅·알림·음성 어디에나 응용된다. 사용자를 기다리게 하지 않는 인터페이스를 코드로 어떻게 만드는지의 표본.

④ 프로바이더·프로토콜·능력의 3분리 추상화

음성 백엔드를 provider(DashScope/로컬 s2s) × protocol(beta/GA dialect) × capabilities(미지원 항목만 선언)로 나눠, provider 이름으로 if 분기하지 않고도 규격 편차를 흡수한다. "차이가 나는 부분만 데이터로 선언"하는 이 설계는 여러 외부 API를 하나로 감쌀 때 두고두고 쓰는 패턴이다.

⑤ 로컬 우선 보안

기본 loopback 전용, DNS rebinding 방어(request-security.mjs), 시크릿 파일 0600 권한, 저장소에 키를 안 남기는 습관, 원격 노출 시 인증 리버스 프록시 + 명시적 허용 Origin 강제. "개인 비서를 내 기기에서 안전하게 돌린다"는 요구를 어떻게 코드로 방어하는지 배운다.

⑥ 크로스 플랫폼 오디오 (JS + 네이티브)

같은 앱이 macOS는 Swift CoreAudio(AEC 전이중), Linux/Windows는 Python PortAudio(반이중), 브라우저는 Web Audio로 갈라지는 실물. 저지연 오디오에서 JS의 한계를 네이티브 브리지로 보완하는 현실적 타협을 볼 수 있다.

7시스템 / 실행 요구사항

• GPU·로컬 모델 불필요 — 음성 추론은 DashScope 클라우드가 한다(다운로드할 가중치 없음). 단 v1.3.0의 로컬 speech-to-speech 프론트는 별도 로컬 파이프라인을 요구
• 네트워크 필요 — 마이크 오디오가 DashScope로 전송된다. Gateway 자체는 기본 loopback 전용이라 외부에 노출되지 않는다
• 사용자 데이터는 로컬 — ~/.config/qwaudio/의 USER.md·frontend-memory.json·tasks.json은 기기에만 저장되고 저장소로 커밋되지 않는다

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 로드맵 (주차별)

10핵심 키워드 사전

11참고 링크

• GitHub 저장소: github.com/QwenAudio/qwen-audio-agent
• npm 패키지: npmjs.com/package/qwen-audio-agent (npm i -g qwen-audio-agent)
• 1차 소스: docs/architecture.md(3계층·의존 규칙) · docs/configuration.md(환경변수 전체) · server/src/voice/realtime-gateway.mjs(음성 파이프라인) · server/src/agent/acp-process-client.mjs(ACP 핸드셰이크)
• 음성 모델: 알리바바 바이롄(Model Studio) / DashScope 문서 — Qwen Audio Realtime API 키·규격
• 프로토콜 표준: Agent Client Protocol (ACP) · Model Context Protocol (MCP)
• 비교/참고: OpenAI Realtime API(호환 규격의 원형) · LiveKit Agents · pipecat(음성 에이전트 프레임워크) · Zed의 claude-code-acp(어댑터 예)
• 관련 개념: WebSocket PCM 스트리밍, VAD, 에코 제거(AEC), CoreAudio/PortAudio/Web Audio, stdio JSON-RPC, Electron 투명 창