macOS 앱: 메뉴 바 제어 및 음성 상호 작용

학습 후 할 수 있는 것

이 튜토리얼을 완료하면 다음을 할 수 있습니다:

✅ Clawdbot macOS 앱이 메뉴 바 제어 평면으로서의 핵심 기능 이해
✅ Voice Wake 음성 깨우기 및 Talk Mode 연속 대화 사용 마스터
✅ 노드 모드에서 system.run, Canvas, Camera 등의 기능 이해
✅ 다른 배포 시나리오에 맞게 로컬 vs 원격 모드 구성
✅ 명령 실행 권한을 제어하기 위한 Exec Approvals 승인 메커니즘 관리
✅ 딥 링크를 사용하여 AI 어시스턴트를 빠르게 트리거
✅ SSH/Tailscale을 통한 원격 액세스 및 Gateway 제어

현재 겪고 있는 문제점

다음과 같은 질문을 하고 있을 수 있습니다:

"macOS 앱은 정확히 무엇을 하나요? Gateway 자체인가요?"
"Voice Wake와 Talk Mode는 어떻게 사용하나요? 추가 하드웨어가 필요한가요?"
"노드 모드와 일반 모드의 차이는 무엇인가요? 언제 어떤 것을 사용해야 하나요?"
"macOS에서 권한 및 보안 설정을 어떻게 관리하나요?"
"다른 컴퓨터에서 Gateway를 실행할 수 있나요?"

좋은 소식은 Clawdbot macOS 앱은 Gateway의 그래픽 제어 평면입니다. Gateway 서비스를 실행하지 않고, 연결, 관리 및 모니터링합니다. 또한 노드로서 macOS 고유 기능(system.run, Canvas, Camera)을 원격 Gateway에 노출합니다.

언제 이 방법을 사용해야 하나요

다음과 같은 경우에 필요합니다:

🖥️ macOS 그래픽 관리 - 명령줄보다 더 직관적인 메뉴 바 상태 및 제어
🎙️ 음성 상호 작용 - Voice Wake 깨우기 + Talk Mode 연속 대화
💻 로컬 명령 실행 - macOS 노드에서 system.run 등의 명령 실행
🎨 Canvas 시각화 - macOS에서 AI 기반 시각화 인터페이스 렌더링
📷 장치 기능 - Camera 사진, 비디오 및 화면 녹화
🌐 원격 액세스 - SSH/Tailscale을 통한 원격 Gateway 제어

노드 vs Gateway의 차이점

Gateway: AI 모델 실행, 세션 관리, 메시지 처리 (어떤 컴퓨터에서든 실행 가능)
노드(Node): 장치 로컬 기능(Canvas, Camera, system.run)을 Gateway에 노출
macOS 앱: Gateway 클라이언트로도 사용할 수 있고, 노드로도 사용할 수 있음

핵심 개념

Clawdbot macOS 앱은 이중 역할 시스템입니다:

┌──────────────────────────────────────────┐
│     Clawdbot.app (macOS 앱)         │
│                                      │
│   ┌────────────────────────────┐      │
│   │  메뉴 바 제어 평면        │      │
│   │  • Gateway 연결 관리       │◄────► Gateway WebSocket
│   │  • WebChat 내장 창         │      │
│   │  • 설정 및 구성             │      │
│   │  • Voice Wake/Talk Mode    │      │
│   └────────────────────────────┘      │
│                                      │
│   ┌────────────────────────────┐      │
│   │  노드 서비스           │      │
│   │  • system.run              │◄────► Gateway 노드 프로토콜
│   │  • Canvas                 │      │
│   │  • Camera/Screen          │      │
│   └────────────────────────────┘      │
└──────────────────────────────────────────┘

두 가지 실행 모드:

모드	Gateway 위치	노드 서비스	적용 시나리오
로컬 모드(기본값)	로컬(launchd 데몬)	시작 안 함	Gateway가 이 Mac에서 실행 중
원격 모드	원격 컴퓨터(SSH/Tailscale 통해)	시작	Gateway가 다른 컴퓨터에서 실행 중

핵심 기능 모듈:

메뉴 바 제어 - Gateway 연결 상태, WebChat, 구성, 세션 관리
Voice Wake - 전역 음성 깨우기 단어 리스닝
Talk Mode - 연속 음성 대화 루프(음성 입력 → AI 응답 → TTS 재생)
노드 모드 - macOS 고유 명령(system.run, canvas.*, camera.*) 노출
Exec Approvals - system.run 명령 실행 승인 및 보안 제어
딥 링크 - clawdbot:// 프로토콜을 통한 빠른 기능 트리거

따라 하기

1단계: macOS 앱 설치 및 시작

이유 메뉴 바 제어 및 음성 기능을 사용하려면 Clawdbot macOS 앱을 설치해야 합니다.

설치 방법:

Homebrew 사용하여 설치수동으로 .dmg 다운로드

bash

brew install --cask clawdbot

bash

# https://github.com/moltbot/moltbot/releases 에서 최신 Clawdbot.app.dmg 다운로드
# Applications 폴더로 드래그

첫 번째 시작:

bash

open /Applications/Clawdbot.app

다음을 볼 수 있어야 합니다:

macOS 상단 메뉴 바에 🦞 아이콘이 나타남
아이콘을 클릭하면 드롭다운 메뉴가 펼쳐짐
시스템에서 TCC 권한 요청 대화 상자가 나타남

첫 번째 시작 시 권한 요청

macOS 앱에는 다음 권한이 필요합니다(시스템이 자동으로 메시지를 표시함):

알림 권한 - 시스템 알림 표시
접근성 권한 - Voice Wake 및 시스템 작업에 사용
마이크 권한 - Voice Wake 및 Talk Mode에 필요
화면 녹화 권한 - Canvas 및 화면 녹화 기능
음성 인식 권한 - Voice Wake의 음성 입력
자동화 권한 - AppleScript 제어(필요한 경우)

이 모든 권한은 완전히 로컬로 사용되며 어떤 서버에도 업로드되지 않습니다.

2단계: 연결 모드 구성(로컬 vs 원격)

이유 배포 요구 사항에 따라 로컬 또는 원격 모드를 선택합니다.

모드 A: 로컬 모드(기본값)

적용 시나리오: Gateway와 macOS 앱이 동일한 컴퓨터에서 실행 중인 경우.

구성 단계:

메뉴 바 앱에 Local 모드가 표시되는지 확인
Gateway가 실행 중이지 않으면 앱이 자동으로 com.clawdbot.gateway launchd 서비스를 시작
앱이 ws://127.0.0.1:18789에 연결

다음을 볼 수 있어야 합니다:

메뉴 바 아이콘이 녹색으로 표시(연결됨 상태)
Gateway 상태 카드에 "Local"이 표시
노드 서비스 시작되지 않음(노드 모드는 원격 모드에서만 필요)

모드 B: 원격 모드

적용 시나리오: Gateway가 다른 컴퓨터(예: 서버 또는 Linux VPS)에서 실행 중이고, Mac에서 제어하려는 경우.

구성 단계:

메뉴 바 앱에서 Remote 모드로 전환
원격 Gateway의 WebSocket 주소 입력(예: ws://your-server:18789)
인증 방법 선택(Token 또는 Password)
앱이 자동으로 SSH 터널을 통해 원격 Gateway에 연결

다음을 볼 수 있어야 합니다:

메뉴 바 아이콘이 연결 상태 표시(노란색/녹색/빨간색)
Gateway 상태 카드에 원격 서버 주소 표시
노드 서비스 자동 시작(원격 Gateway가 로컬 기능을 호출할 수 있도록)

원격 모드의 터널 메커니즘:

macOS 앱                     원격 Gateway
    │                                  │
    ├── SSH 터널 ───────────────────► ws://remote:18789
    │                                  │
    └── 노드 서비스 ◄───────────────────── node.invoke

원격 모드의 장점

중앙 집중식 관리: 강력한 컴퓨터 한 대에서 Gateway를 실행하고 여러 클라이언트에서 액세스
리소스 최적화: Mac은 가볍게 유지하고 Gateway는 고성능 서버에서 실행
장치 로컬화: Canvas, Camera 등의 기능은 여전히 Mac에서 로컬로 실행

3단계: 메뉴 바 제어 평면 사용

이유 메뉴 바 앱은 모든 핵심 기능에 빠르게 액세스할 수 있는 인터페이스를 제공합니다.

핵심 메뉴 항목:

메뉴 바 아이콘을 클릭하면 다음을 볼 수 있습니다:

상태 카드
- Gateway 연결 상태(연결됨/연결 끊김/연결 중)
- 현재 모드(Local/Remote)
- 실행 중인 채널 목록(WhatsApp, Telegram 등)
빠른 작업
- Agent - AI 대화 창 열기(Gateway 호출)
- WebChat - 내장 WebChat 인터페이스 열기
- Canvas - Canvas 시각화 창 열기
- Settings - 구성 인터페이스 열기
기능 스위치
- Talk - Talk Mode 사용/사용 안 함
- Voice Wake - Voice Wake 사용/사용 안 함
정보 메뉴
- Usage - 사용 통계 및 비용 보기
- Sessions - 세션 목록 관리
- Channels - 채널 상태 보기
- Skills - 스킬 패키지 관리

다음을 볼 수 있어야 합니다:

실시간으로 업데이트되는 상태 표시기(녹색 = 정상, 빨간색 = 연결 끊김)
마우스를 올리면 자세한 연결 정보 표시
모든 메뉴 항목을 클릭하면 해당 기능이 빠르게 열림

4단계: Voice Wake 구성 및 사용

이유 Voice Wake를 사용하면 클릭하거나 입력하지 않고 음성 깨우기 단어로 AI 어시스턴트를 트리거할 수 있습니다.

Voice Wake 작동 원리:

┌──────────────────────────────────┐
│   Voice Wake 런타임          │
│                              │
│   마이크 리스닝 ──► 깨우기 단어 감지 │
│                              │
│   깨우기 단어 일치?               │
│       │                       │
│       ├─ 예 ──► Agent 트리거  │
│       │                       │
│       └─ 아니요 ──► 리스닝 계속  │
└──────────────────────────────────┘

Voice Wake 구성:

Settings → Voice Wake 열기
깨우기 단어 입력(기본값: clawd, claude, computer)
여러 깨우기 단어 추가 가능(쉼표로 구분)
Enable Voice Wake 스위치 사용

깨우기 단어 규칙:

깨우기 단어는 Gateway에 저장됨: ~/.clawdbot/settings/voicewake.json
모든 노드가 동일한 전역 깨우기 단어 목록을 공유
변경 후 연결된 모든 기기(macOS, iOS, Android)로 브로드캐스트

사용 흐름:

마이크 권한이 부여되었는지 확인
메뉴 바에서 Voice Wake 사용
마이크에 깨우기 단어 말하기(예: "Hey clawd")
"띵" 알림음을 들을 때까지 대기(깨우기 성공을 나타냄)
지시 사항 또는 질문 말하기

다음을 볼 수 있어야 합니다:

화면 중앙에 Voice Wake 오버레이가 나타남
마이크 볼륨 파형 표시
"Listening" 상태 텍스트 표시
AI가 음성 입력 처리 시작

Voice Wake의 전역 특성

깨우기 단어는 Gateway 수준의 전역 구성이며 단일 장치로 제한되지 않습니다. 이것은 다음을 의미합니다:

macOS에서 깨우기 단어를 수정하면 iOS 및 Android 기기도 동기화
모든 기기가 동일한 깨우기 단어 그룹을 사용
하지만 각 기기는 개별적으로 Voice Wake를 사용/사용 안 함 할 수 있음(권한 및 사용자 선호도 기반)

5단계: Talk Mode 연속 대화 사용

이유 Talk Mode는 Siri/Alexa와 유사한 연속 음성 대화 경험을 제공하며 매번 깨울 필요가 없습니다.

Talk Mode 작업 루프:

리스닝 ──► AI 처리 ──► TTS 재생 ──► 리스닝
  │                                              │
  └────────────────────────────────────────┘

Talk Mode 사용:

메뉴 바에서 Talk 버튼 클릭
또는 단축키 사용(기본값: 없음, Settings에서 설정 가능)
Talk Mode 오버레이 나타남

Talk Mode 인터페이스 상태:

상태	표시	설명
Listening	구름 펄스 애니메이션 + 마이크 볼륨	말하기를 기다림
Thinking	싱크 애니메이션	AI가 생각 중
Speaking	방사 링 애니메이션 + 파동	AI가 응답 중(TTS 재생 중)

상호 작용 제어:

말하기 중지: 구름 아이콘을 클릭하여 TTS 재생 중지
Talk Mode 종료: 오른쪽 상단 X 버튼 클릭
음성 중단: AI가 말할 때 사용자가 말하기 시작하면 자동으로 재생 중지

TTS 구성:

Talk Mode는 ElevenLabs를 사용하여 텍스트를 음성으로 변환합니다. 구성 위치: ~/.clawdbot/clawdbot.json

yaml

talk:
  voiceId: "elevenlabs_voice_id"  # ElevenLabs 음성 ID
  modelId: "eleven_v3"            # 모델 버전
  apiKey: "elevenlabs_api_key"     # API 키(또는 환경 변수 사용)
  interruptOnSpeech: true           # 음성 시 중단
  outputFormat: "mp3_44100_128"   # 출력 형식

ElevenLabs 구성

API 키를 구성하지 않은 경우 Talk Mode는 다음을 시도합니다:

ELEVENLABS_API_KEY 환경 변수
Gateway shell 프로필의 키
사용 가능한 첫 번째 ElevenLabs 음성을 기본값으로 사용

6단계: 노드 모드 사용

이유 노드 모드를 사용하면 macOS 앱이 원격 Gateway에 로컬 기능을 노출하여 진정한 크로스 장치 협업을 실현할 수 있습니다.

노드 모드에서 사용 가능한 명령:

명령 카테고리	명령 예시	기능 설명
Canvas	`canvas.present`, `canvas.navigate`, `canvas.eval`	macOS에서 시각화 인터페이스 렌더링
Camera	`camera.snap`, `camera.clip`	사진 또는 비디오 촬영
Screen	`screen.record`	화면 녹화
System	`system.run`, `system.notify`	Shell 명령 실행 또는 알림 보내기

노드 모드 사용:

노드 모드는 원격 모드에서 자동으로 시작됩니다. 원격 Gateway가 로컬 기능을 호출해야 하기 때문입니다.

노드 서비스를 수동으로 시작할 수도 있습니다:

bash

clawdbot node run --display-name "My Mac"

노드 권한 관리:

macOS 앱은 권한 시스템을 통해 어떤 기능을 사용할 수 있는지 보고합니다:

json

{
  "canvas": true,
  "camera": true,
  "screen": true,
  "system": {
    "run": true,
    "notify": true
  }
}

AI는 권한에 따라 사용 가능한 도구를 자동으로 선택합니다.

7단계: Exec Approvals 구성(`system.run` 보안 제어)

이유system.run은 임의의 Shell 명령을 실행할 수 있으므로 오작동 또는 남용을 방지하기 위해 승인 메커니즘이 필요합니다.

Exec Approvals 3계층 보안 모델:

json

{
  "version": 1,
  "defaults": {
    "security": "deny",          // 기본 정책: 거부
    "ask": "on-miss"           // 명령이 화이트리스트에 없으면 묻기
  },
  "agents": {
    "main": {
      "security": "allowlist",    // 메인 세션: 화이트리스트만 허용
      "ask": "on-miss",
      "allowlist": [
        { "pattern": "/usr/bin/git" },
        { "pattern": "/opt/homebrew/*/rg" }
      ]
    }
  }
}

보안 정책 유형:

정책	동작	적용 시나리오
`deny`	모든 `system.run` 호출 거부	고도 보안, 모든 명령 비활성화
`allowlist`	화이트리스트의 명령만 허용	보안과 편의성 균형
`ask`	화이트리스트에 없으면 사용자 승인 요청	유연하지만 확인 필요

승인 흐름:

AI가 승인되지 않은 명령을 실행하려고 할 때:

macOS 앱이 승인 대화 상자를 팝업
전체 명령 경로 및 매개 변수 표시
세 가지 옵션 제공:
- Allow Once - 이번만 허용
- Always Allow - 화이트리스트에 추가
- Deny - 실행 거부

다음을 볼 수 있어야 합니다:

승인 대화 상자에 명령 세부 정보 표시(예: /usr/bin/ls -la ~)
"Always Allow"를 선택하면 다음부터 묻지 않음
"Deny"를 선택하면 명령 실행이 실패하고 AI에 오류 반환

구성 위치:

Exec Approvals는 macOS 로컬에 저장됩니다:

파일: ~/.clawdbot/exec-approvals.json
승인 기록: 앱에서 승인/거부된 모든 명령 보기

8단계: 딥 링크 사용

이유 딥 링크는 다른 앱에서 Clawdbot 기능을 빠르게 트리거할 수 있는 능력을 제공합니다.

지원되는 딥 링크 프로토콜: clawdbot://

`clawdbot://agent`

Gateway agent 요청을 트리거합니다. 터미널에서 clawdbot agent를 실행하는 것과 같습니다.

매개 변수:

매개 변수	설명	예시
`message`(필수)	AI에 보낼 메시지	`message=Hello%20from%20deep%20link`
`sessionKey`(선택)	대상 세션 키, 기본값 `main`	`sessionKey=main`
`thinking`(선택)	생각 수준: off\|minimal\|low\|medium\|high\|xhigh	`thinking=high`
`deliver`/`to`/`channel`(선택)	전달 채널	`channel=telegram`
`timeoutSeconds`(선택)	시간 초과	`timeoutSeconds=30`
`key`(선택)	확인 건너뛰기 키, 자동화용	`key=your-secret-key`

예시:

bash

# 기본: 메시지 보내기
open 'clawdbot://agent?message=Hello%20from%20deep%20link'

# 고급: Telegram으로 보내기, 높은 생각 수준, 30초 시간 초과
open 'clawdbot://agent?message=Summarize%20my%20day&to=telegram&thinking=high&timeoutSeconds=30'

# 자동화: 키를 사용하여 확인 건너뛰기(스크립트에서만 안전하게 사용)
open 'clawdbot://agent?message=Automated%20task&key=secure-random-string'

다음을 볼 수 있어야 합니다:

Clawdbot macOS 앱이 자동으로 열림(실행 중이 아닌 경우)
Agent 창이 나타나고 메시지 표시
AI가 처리를 시작하고 응답 반환

딥 링크의 보안성

key 매개 변수가 없으면 앱이 확인 대화 상자를 팝업
유효한 key가 있으면 요청이 자동으로 실행됨(자동화 스크립트용)
신뢰할 수 없는 소스에서 딥 링크를 절대 사용하지 마십시오

검사점 ✅

위 단계를 완료한 후 다음을 확인하십시오:

설치 및 연결

[ ] macOS 앱이 성공적으로 설치되고 Applications 폴더에 나타남
[ ] 첫 번째 시작 시 모든 필수 권한이 부여됨
[ ] 메뉴 바 아이콘이 정상적으로 표시됨
[ ] 로컬 모드(Local)에서 Gateway에 연결할 수 있음
[ ] 원격 모드(Remote)에서 Gateway에 연결할 수 있음

Voice Wake 및 Talk Mode

[ ] Voice Wake 깨우기 단어가 성공적으로 구성됨(예: "clawd", "claude")
[ ] 깨우기 단어를 말하면 AI 어시스턴트가 트리거됨
[ ] Talk Mode 오버레이가 정상적으로 열리고 닫힘
[ ] TTS 재생이 명확함(ElevenLabs API 키 필요)
[ ] 음성 중단 기능이 정상 작동함(말할 때 재생 중지)

노드 모드 및 Exec Approvals

[ ] 노드 서비스가 원격 모드에서 자동으로 시작됨
[ ] system.run 명령을 실행하고 결과를 반환할 수 있음
[ ] Exec Approvals 대화 상자가 정상적으로 팝업됨
[ ] "Always Allow"가 화이트리스트에 올바르게 추가됨
[ ] "Deny"가 명령 실행을 올바르게 거부함

고급 기능

[ ] 딥 링크가 터미널 또는 다른 앱에서 트리거될 수 있음
[ ] 설정 인터페이스가 구성을 올바르게 저장함
[ ] WebChat 내장 창이 정상적으로 열림
[ ] Canvas 창이 AI가 생성한 시각화 콘텐츠를 표시할 수 있음

문제 해결 팁

❌ 권한 거부 또는 부여되지 않음

문제점:

Voice Wake가 마이크를 리스닝할 수 없음
Canvas가 콘텐츠를 표시할 수 없음
system.run 명령 실행 실패

해결 방법:

시스템 설정 → 개인 정보 및 보안 열기
Clawdbot 또는 Clawdbot.app 찾기
마이크, 접근성, 화면 녹화, 자동화 등 모든 권한이 켜져 있는지 확인
Clawdbot 앱 다시 시작

TCC 권한 문제 해결

권한 스위치를 켤 수 없거나 즉시 꺼지는 경우:

보안 도구(예: Little Snitch)가 활성화되어 있는지 확인
앱을 완전히 제거한 후 다시 설치 시도
Console.app에서 TCC 거부 로그 확인

❌ Gateway 연결 실패

문제점:

메뉴 바 아이콘이 빨간색으로 표시(연결 끊김 상태)
상태 카드에 "Connection Failed" 표시
WebChat을 열 수 없음

가능한 원인 및 해결 방법:

원인	확인 방법	해결 방법
Gateway가 시작되지 않음	`clawdbot gateway status` 실행	Gateway 서비스 시작
주소 오류	WebSocket URL 확인	`ws://127.0.0.1:18789` 또는 원격 주소가 올바른지 확인
포트 사용 중	`lsof -i :18789` 실행	포트를 사용 중인 프로세스 종료
인증 실패	Token/Password 확인	인증 자격 증명이 올바른지 확인

❌ Talk Mode를 사용할 수 없음

문제점:

Talk Mode를 사용해도 반응이 없음
TTS를 재생할 수 없음
마이크 입력할 수 없음

해결 방법:

ElevenLabs 구성 확인:
- API 키가 설정되었는지 확인
- 키가 유효한지 테스트: ElevenLabs 콘솔 방문
네트워크 연결 확인:
- TTS에 인터넷 연결 필요
- 방화벽이 API 요청을 차단하는지 확인
오디오 출력 확인:
- 시스템 볼륨이 켜져 있는지 확인
- 기본 출력 장치가 올바른지 확인

❌ 원격 모드에서 노드 연결 실패

문제점:

원격 Gateway가 macOS의 system.run 등 명령을 호출할 수 없음
오류 로그에 "Node not found" 또는 "Node offline" 표시

해결 방법:

노드 서비스 실행 확인:

bash

clawdbot nodes list
# macOS 노드가 "paired"로 표시되어야 함

SSH 터널 확인:
- macOS 앱 설정에서 SSH 연결 상태 확인
- 원격 Gateway에 수동으로 SSH로 연결할 수 있는지 확인
노드 서비스 다시 시작:
bash
```
# macOS에서
clawdbot node restart
```

수업 요약

이 수업에서 다음을 학습했습니다:

✅ macOS 앱 아키텍처 - Gateway 제어 평면 및 노드로서의 이중 역할
✅ 로컬 vs 원격 모드 - 다른 배포 시나리오에 맞게 구성하는 방법
✅ 메뉴 바 기능 - 상태 관리, WebChat, Canvas, 설정 등 빠른 액세스
✅ Voice Wake - 깨우기 단어로 AI 어시스턴트 트리거
✅ Talk Mode - 연속 음성 대화 경험
✅ 노드 모드 - macOS 고유 기능 노출(system.run, Canvas, Camera)
✅ Exec Approvals - system.run의 3계층 보안 제어 메커니즘
✅ 딥 링크 - clawdbot:// 프로토콜을 통한 빠른 기능 트리거

모범 사례:

🚀 로컬 배포: 기본 Local 모드 사용
🌐 원격 배포: SSH/Tailscale 중앙 집중식 관리 구성
🔐 보안 우선: system.run에 적절한 화이트리스트 정책 구성
🎙️ 음성 상호 작용: ElevenLabs와 함께 최상의 TTS 경험 얻기

다음 수업 예고

다음 수업에서는 **iOS 노드**를 학습합니다.
다음을 학습하게 됩니다:
iOS 노드를 Gateway에 연결하는 방법
iOS 노드의 기능(Canvas, Camera, Location, Voice Wake)
Gateway를 통해 iOS 장치를 페어링하는 방법
iOS 노드의 권한 관리 및 보안 제어
Bonjour 발견 및 Tailscale 원격 연결

부록: 소스 코드 참조

클릭하여 소스 코드 위치 보기

업데이트 시간: 2026-01-27

기능	파일 경로	행号
앱 진입점	`apps/macos/Sources/Clawdbot/ClawdbotApp.swift`	전체 파일
Gateway 연결	`apps/macos/Sources/Clawdbot/GatewayConnection.swift`	1-500
Voice Wake 런타임	`apps/macos/Sources/Clawdbot/VoiceWakeRuntime.swift`	전체 파일
Talk Mode 타입	`apps/macos/Sources/Clawdbot/TalkModeTypes.swift`	전체 파일
Voice Wake 오버레이	`apps/macos/Sources/Clawdbot/VoiceWakeOverlayView.swift`	전체 파일
노드 모드 코디네이터	`apps/macos/Sources/Clawdbot/NodeMode/MacNodeModeCoordinator.swift`	전체 파일
노드 런타임	`apps/macos/Sources/Clawdbot/NodeMode/MacNodeRuntime.swift`	전체 파일
권한 관리자	`apps/macos/Sources/Clawdbot/PermissionManager.swift`	전체 파일
Exec Approvals	`apps/macos/Sources/Clawdbot/ExecApprovalsGatewayPrompter.swift`	전체 파일
메뉴 바	`apps/macos/Sources/Clawdbot/MenuBar.swift`	전체 파일
메뉴 인젝터	`apps/macos/Sources/Clawdbot/MenuSessionsInjector.swift`	전체 파일

핵심 상수:

GatewayConnection.shared - 싱글톤 Gateway 연결 관리자(GatewayConnection.swift:48)
VoiceWakeRuntime - Voice Wake 핵심 런타임(싱글톤)
MacNodeModeCoordinator - 노드 모드 코디네이터, 로컬 서비스 시작 관리

핵심 타입:

GatewayAgentChannel - Gateway 에이전트 채널 열거형(GatewayConnection.swift:9-30)
GatewayAgentInvocation - Gateway Agent 호출 구조(GatewayConnection.swift:32-41)
ExecApprovalsConfig - Exec Approvals 구성 구조(JSON Schema)
VoiceWakeSettings - Voice Wake 구성 구조

핵심 함수:

GatewayConnection.sendAgent() - agent 요청을 Gateway로 보내기
GatewayConnection.setVoiceWakeTriggers() - 전역 깨우기 단어 목록 업데이트
PermissionManager.checkPermission() - TCC 권한 상태 확인
ExecApprovalsGatewayPrompter.prompt() - 승인 대화 상자 표시

문서 위치:

처음부터 사용하기

일반적으로 사용되는 채팅 도구 연결

AI 초능력 잠금 해제

문제가 발생하면

macOS 앱: 메뉴 바 제어 및 음성 상호 작용

학습 후 할 수 있는 것

현재 겪고 있는 문제점

언제 이 방법을 사용해야 하나요

핵심 개념

따라 하기

1단계: macOS 앱 설치 및 시작

2단계: 연결 모드 구성(로컬 vs 원격)

모드 A: 로컬 모드(기본값)

모드 B: 원격 모드

3단계: 메뉴 바 제어 평면 사용

4단계: Voice Wake 구성 및 사용

5단계: Talk Mode 연속 대화 사용

6단계: 노드 모드 사용

7단계: Exec Approvals 구성(`system.run` 보안 제어)

8단계: 딥 링크 사용

`clawdbot://agent`

검사점 ✅

설치 및 연결

Voice Wake 및 Talk Mode

노드 모드 및 Exec Approvals

고급 기능

문제 해결 팁

❌ 권한 거부 또는 부여되지 않음

❌ Gateway 연결 실패

❌ Talk Mode를 사용할 수 없음

❌ 원격 모드에서 노드 연결 실패

수업 요약

다음 수업 예고

부록: 소스 코드 참조

macOS 앱: 메뉴 바 제어 및 음성 상호 작용 ​

학습 후 할 수 있는 것 ​

현재 겪고 있는 문제점 ​

언제 이 방법을 사용해야 하나요 ​

핵심 개념 ​

따라 하기 ​

1단계: macOS 앱 설치 및 시작 ​

2단계: 연결 모드 구성(로컬 vs 원격) ​

모드 A: 로컬 모드(기본값) ​

모드 B: 원격 모드 ​

3단계: 메뉴 바 제어 평면 사용 ​

4단계: Voice Wake 구성 및 사용 ​

5단계: Talk Mode 연속 대화 사용 ​

6단계: 노드 모드 사용 ​

7단계: Exec Approvals 구성(system.run 보안 제어) ​

8단계: 딥 링크 사용 ​

clawdbot://agent ​

검사점 ✅ ​

설치 및 연결 ​

Voice Wake 및 Talk Mode ​

노드 모드 및 Exec Approvals ​

고급 기능 ​

문제 해결 팁 ​

❌ 권한 거부 또는 부여되지 않음 ​

❌ Gateway 연결 실패 ​

❌ Talk Mode를 사용할 수 없음 ​

❌ 원격 모드에서 노드 연결 실패 ​

수업 요약 ​

다음 수업 예고 ​

부록: 소스 코드 참조 ​

macOS 앱: 메뉴 바 제어 및 음성 상호 작용

학습 후 할 수 있는 것

현재 겪고 있는 문제점

언제 이 방법을 사용해야 하나요

핵심 개념

따라 하기

1단계: macOS 앱 설치 및 시작

2단계: 연결 모드 구성(로컬 vs 원격)

모드 A: 로컬 모드(기본값)

모드 B: 원격 모드

3단계: 메뉴 바 제어 평면 사용

4단계: Voice Wake 구성 및 사용

5단계: Talk Mode 연속 대화 사용

6단계: 노드 모드 사용

7단계: Exec Approvals 구성(`system.run` 보안 제어)

8단계: 딥 링크 사용

`clawdbot://agent`

검사점 ✅

설치 및 연결

Voice Wake 및 Talk Mode

노드 모드 및 Exec Approvals

고급 기능

문제 해결 팁

❌ 권한 거부 또는 부여되지 않음

❌ Gateway 연결 실패

❌ Talk Mode를 사용할 수 없음

❌ 원격 모드에서 노드 연결 실패

수업 요약

다음 수업 예고

부록: 소스 코드 참조