OpenClaw Android 흐름 분석: sequence diagram으로 보는 Gateway, node.invoke, Voice

앞글에서는 OpenClaw Android 앱을 component 관점에서 봤다. 이번 글은 같은 코드를 sequence 관점에서 본다.

핵심은 세 가지다.

1. Gateway 연결은 단순 WebSocket 접속이 아니라 TLS trust, device identity, auth, capability 광고가 묶인 handshake다.
2. Android 기능 호출은 node.invoke라는 agent tool boundary를 통과한다.
3. Voice는 Android capture/playback과 Gateway transcription/chat/speech synthesis를 조합한다.

1. Gateway 연결과 인증 흐름

연결 흐름에서 가장 먼저 볼 것은 operatorSession과 nodeSession이 분리되어 있다는 점이다.

operatorSession은 사용자 UI가 Gateway를 조작하는 경로다. chat.send, chat.history, models.list, usage.status, skills.status, exec.approval.* 같은 RPC가 이 경로를 탄다.

nodeSession은 Android 기기가 Gateway에 자신을 node로 등록하는 경로다. 이 세션이 현재 가능한 capability와 command를 광고하고, 이후 node.invoke.request를 받는다.

연결 단계는 대략 이렇게 읽을 수 있다.

1. 사용자가 host, port, token, bootstrap token, password를 입력한다.
2. NodeRuntime이 endpoint TLS 상태를 확인한다.
3. TLS fingerprint가 없거나 바뀌었으면 trust prompt를 띄운다.
4. 사용자가 승인하면 fingerprint를 저장하고 다시 연결한다.
5. GatewaySession이 WebSocket을 열고 connect.challenge nonce를 받는다.
6. 앱은 device identity signature, auth payload, role, scopes, capabilities, commands를 담아 connect를 보낸다.
7. Gateway가 승인하면 role별 device token을 저장하고 event 구독을 시작한다.

여기서 Android 앱은 단순 클라이언트가 아니다. Gateway가 나중에 Android 기능을 호출할 수 있도록 자기 능력을 선언하는 등록 절차까지 수행한다.

2. node.invoke 실행 흐름

node.invoke는 OpenClaw Android 앱의 가장 중요한 차별점이다. 일반적인 AI 앱은 사용자가 앱 안에서 질문하고 답을 받는 구조에 가깝다. OpenClaw Android는 반대로 agent가 Android 기기의 기능을 tool처럼 호출할 수 있다.

흐름은 이렇다.

1. Android 앱이 connect 단계에서 현재 가능한 capability와 command를 Gateway에 광고한다.
2. agent가 필요한 기능을 고른다. 예를 들어 camera.snap, location.get, contacts.search 같은 command다.
3. Gateway가 Android의 nodeSession으로 node.invoke.request를 보낸다.
4. GatewaySession이 requestId, command, params, timeout을 파싱한다.
5. InvokeDispatcher가 command registry를 확인한다.
6. command가 foreground를 요구하는지, 현재 앱이 foreground인지, 권한과 feature flag가 맞는지 다시 검사한다.
7. 통과하면 각 Android handler가 OS API를 호출한다.
8. 결과는 node.invoke.result로 Gateway에 돌아가고, agent는 그 결과를 보고 다음 행동을 정한다.

중요한 점은 capability 광고만으로 실행이 보장되지 않는다는 것이다.

실행 시점의 gate가 한 번 더 있다. Canvas와 camera는 foreground가 필요하다. location은 위치 권한과 location mode가 필요하다. SMS, call log, photos는 product flavor와 manifest merge의 영향을 받는다. installed apps 목록도 사용자가 sharing을 켜야 한다.

즉 권한 표면은 세 단계로 좁혀진다.

1. Manifest와 product flavor
2. Gateway connect 때의 capability/command 광고
3. InvokeDispatcher의 실행 시점 gate

3. Voice와 TalkMode 흐름

Voice 흐름은 local model이 아니라 capture, relay, synthesis 조합이다.

수동 microphone 모드에서는 MicCaptureManager가 Android AudioRecord에서 8kHz PCM16 frame을 읽는다. 이 frame은 PCMU로 변환되어 talk.session.appendAudio로 Gateway에 전송된다. transcription event가 돌아오면 partial은 live transcript로 표시되고, 최종 transcript는 chat.send로 이어진다.

TalkMode는 realtime 흐름이다. TalkModeManager가 talk.session.create에 mode: realtime, transport: gateway-relay, brain: agent-consult를 보내고 24kHz PCM16 audio frame을 relay한다. Gateway가 audio chunk를 보내면 Android는 AudioTrack으로 재생한다.

assistant 음성 출력은 먼저 Gateway의 talk.speak를 사용한다. remote provider가 PCM, mp3, opus, wav, webm 같은 재생 가능한 audio를 반환하면 Android 앱이 재생한다. provider가 없거나 method가 없으면 Android 시스템 TextToSpeech로 fallback한다.

이 흐름을 보면 Android 앱 안에서 LLM inference를 하는 부분은 없다. Android 쪽 local 요소는 microphone capture, Android SpeechRecognizer, audio playback, system TTS fallback이다. 모델 선택, transcription, agent orchestration, remote speech synthesis는 Gateway/provider 쪽이다.

기존 AI 앱과 구조적으로 다른 점

ChatGPT나 Gemini 같은 일반 모바일 AI 앱은 대체로 “모바일 UI → 서버 모델 → 답변” 구조다. 앱은 카메라나 파일 입력을 받을 수 있지만, 서버 agent가 앱 자체를 지속적인 node로 보고 Android 기능을 command surface로 호출하는 구조는 아니다.

OpenClaw Android는 다르다.

사용자는 앱에서 채팅과 음성을 사용한다. 동시에 앱은 Gateway에 Android device node로 등록된다. agent는 node.invoke를 통해 카메라, 위치, 알림, 연락처, 캘린더, device status 같은 기능을 호출할 수 있다.

그래서 이 앱을 볼 때 핵심 질문은 “모바일 LLM 앱인가?”가 아니다. 더 정확한 질문은 이것이다.

이 Android 기기는 Gateway agent에게 어떤 capability를 어떤 조건으로 열어주는가?

OpenClaw Android의 아키텍처는 이 질문에 맞춰 설계되어 있다. session 분리, TLS trust prompt, device identity, capability 광고, foreground gate, product flavor gate가 모두 같은 방향을 본다.

정리

sequence로 보면 OpenClaw Android의 성격은 더 분명하다.

이 앱은 local model 앱이 아니다. 일반적인 채팅 앱만도 아니다.

Gateway에 붙는 operator UI이면서, Android 기능을 agent tool로 제공하는 mobile node다.

따라서 분석의 중심은 화면 구성보다 흐름에 있다. 연결 시 어떤 identity와 auth로 들어가는지, 어떤 capability를 광고하는지, agent 호출이 어떤 gate를 통과하는지, voice가 어디까지 local이고 어디부터 Gateway인지가 이 앱의 진짜 architecture다.