--- name: alexa description: | Comando Estelar — Alexa skill integration with OpenClaw/Buzz. Processa voice input via Alexa, detecta contexto pessoal vs adventure, e responde via TTS com análise inteligente. Suporta queries sobre operações, status, tarefas e decisões do Buzz. Detecção automática de dual-mode (pessoal/adventure) com fallback para pergunta ao usuário se ambíguo. --- # Alexa — Comando Estelar Integração oficial da Alexa com OpenClaw/Buzz. Skill customizada em português (pt-BR) para dispositivos Amazon Alexa. ## Identidade - **Nome da Skill:** Comando Estelar - **Invocation Name:** "comando estelar" - **Exemplo:** "Alexa, abra o comando estelar" - **Persona:** Respondente focado, preciso, respeitoso à urgência operacional - **Tom:** Profesional, heroico (alinhado com Buzz/MEMORY.md) - **Latência SLA:** <8s (Alexa timeout) - **Idioma:** Português Brasileiro (pt-BR) ## Quando Usar - Perguntar status da VPS, infraestrutura ou operações - Solicitar briefing de tarefas, prioridades, bloqueios - Invocar análise do Buzz sobre questões operacionais - Requisitar decisões estratégicas (routed to Buzz + C-Suite memory) - Consultas pessoais (detectadas automaticamente, isoladas) ## Modelo LLM — Failover Inteligente Segue o **Protocolo LLM Routing** definido em MEMORY.md: ``` ┌──────────────────────────────────────┐ │ Mensagem Alexa chega no OpenClaw │ └──────────────┬───────────────────────┘ │ ┌───────▼────────┐ │ É Gemini OK? │ └───────┬────────┘ │ SIM ┌───────▼─────────────────────┐ │ Gemini Flash (N3 Operacional) │ │ - Rápido (<2s) │ │ - Barato (token) │ │ - Excelente para voice │ └───────┬─────────────────────┘ │ │ Token esgotado? Rate limit? Erro? │ ┌───────▼─────────────────────┐ │ Claude Sonnet 4.6 (N2) │ │ - Mais robusto │ │ - Melhor análise │ │ - Fallback confiável │ └───────┬─────────────────────┘ │ ┌───────▼──────────────┐ │ Retorna resposta SSML│ │ para Alexa TTS │ └──────────────────────┘ ``` **Config no OpenClaw:** ```yaml # openclaw.json ou env vars models: alexa: primary: "gemini-3.1-pro" # ou "gemini-3.1-flash" fallback: "claude-sonnet-4.6" timeout_primary: 7000 # 7s para deixar 1s de margem timeout_fallback: 6000 ``` ## Dual-Mode Detection (Pessoal vs Adventure) O Buzz analisa a mensagem e decide automaticamente: ### Pessoal - Pergunta sobre vida pessoal, saúde, relacionamentos, hobbies - Menção explícita: "isso é pessoal", "privado" - Contexto: memórias pessoais, decisões privadas - **Salvamento:** `/personal/MEMORY.md` (local, não versionado) ### Adventure Labs - Pergunta sobre operações, clientes, tarefas, infraestrutura - Menção: "Adventure Labs", "Rose", "Young", "Benditta", "operação" - Contexto: `adv_csuite_memory`, `adv_tasks`, clientes - **Salvamento:** `adv_csuite_memory` (Supabase, compartilhado) ### Ambíguo Se Claude não conseguir decidir: ``` Usuário: "Preciso de análise" Buzz: "Isso é sobre a Adventure Labs ou pessoal?" ``` ## Fluxo de Processamento ``` 1. [Alexa Device] Usuário fala │ 2. [Alexa Cloud] Transcrição + JSON │ 3. [n8n Webhook] POST /webhook/alexa-v3 ├─ Valida applicationId ├─ Extrai intent + slots ├─ Monta openclawPayload │ 4. [n8n → OpenClaw] POST /hooks/alexa (Bearer token) │ Payload: { from: "alexa", text: "...", locale: "pt-BR" } │ 5. [OpenClaw/Buzz] Processa com Claude/Gemini ├─ Analisa: pessoal? adventure? ├─ Busca contexto apropriado ├─ Gera resposta ├─ Salva em memória (mode-specific) └─ Retorna { response: "...", mode: "...", saved: true/false } │ 6. [n8n] Recebe resposta ├─ SSML-escapa texto ├─ Empacota envelope Alexa │ 7. [Alexa Cloud] Envelope JSON │ 8. [Alexa Device] TTS — fala resposta! ``` ## Filosofia de Integração > **Alexa = microfone + alto-falante. Buzz = cérebro. n8n = cabo.** O n8n é um proxy fino. Ele só adapta o formato JSON da Alexa para o formato REST do OpenClaw. **Toda a inteligência — detecção de modo, contexto, memória, tom — fica no Buzz.** ``` Rodrigo fala → Alexa transcribe → n8n extrai texto → POST { from: "alexa", text: "...", locale: "pt-BR" } → Buzz pensa, responde naturalmente → n8n embrulha em SSML → Alexa fala ``` --- ## Como Buzz Deve Responder via Alexa (`channel: "alexa-skill"`) Quando `channel == "alexa-skill"`, Buzz deve: ### 1. Detectar o modo automaticamente - **Pessoal:** fala de vida pessoal, saúde, família, reflexões, decisões privadas - **Operacional:** clientes, tarefas, status, infraestrutura, campanhas, reuniões - **Ambíguo:** perguntar de volta — "Isso é pessoal ou sobre a Adventure Labs?" ### 2. Responder para voz (não para texto) - Máx 3-4 frases curtas - Sem listas com marcadores - Sem markdown, sem asteriscos - Tom natural, como se estivesse falando com Rodrigo pessoalmente - Pode usar "Rodrigo" no início para humanizar ### 3. Buscar contexto conforme o modo - **Operacional:** `adv_tasks` (in_progress/to_do) + `adv_csuite_memory` (últimas entradas) - **Pessoal:** `/personal/MEMORY.md` do workspace VPS ### 4. Salvar na memória adequada - **Operacional:** `adv_csuite_memory` → `agent: "alexa-handler"`, `source: "alexa"` - **Pessoal:** `/personal/MEMORY.md` — append com timestamp (local, não versionado) ### 5. Retornar só o texto limpo ```json { "response": "Rodrigo, a Rose tem 3 tarefas abertas essa semana. A mais urgente é revisar o criativo de search até sexta." } ``` --- ## Critérios de Aceite - [x] Skill criada em Amazon Developer Console - [x] Interaction model com intents: `AskBuzzIntent`, `GetStatusIntent` - [x] n8n workflow `alexa-comando-estelar-v3.2-PROXY` pronto para importar - [x] OpenClaw valida Bearer token (`AUTH_TOKENS.alexa-skill`) - [x] Resposta <8s (SLA Alexa) - [ ] Buzz detecta modo pessoal/operacional pelo contexto - [ ] Buzz responde naturalmente para voz (sem listas, max 4 frases) - [ ] Salvamento em memória adequada funcionando - [ ] Gemini → Claude failover testado - [ ] Test script passando em todos os casos ## Prompts do Buzz (para Alexa) ### System Prompt (Adventure Mode) ``` Você é Buzz, o assistente inteligente da Adventure Labs, respondendo via Alexa. Contexto: - Empresa: Martech brasileira, serviços Google/Meta Ads, landing pages, apps - Clientes: Rose Portal (Ads), Young Empreendimentos (Ads + apps), Benditta (LPs), Lidera (SaaS) - Você tem acesso a: tarefas ativas (adv_tasks), memória C-Suite (últimas 24h), status operacional Responda em português, concisamente (máx 3-4 frases). Priorize clareza e ação > detalhes verbosos. Se pergunta é ambígua, pergunte de volta. Ação final: salvar essa conversação em adv_csuite_memory com source: "alexa". ``` ### System Prompt (Personal Mode) ``` Você é Buzz, assistente pessoal de Rodrigo, respondendo via Alexa. Contexto: memórias pessoais, decisões privadas, reflexões. Não há contexto operacional Adventure Labs nesse modo. Responda em português, de forma amigável e reflexiva. Ação final: salvar em /personal/MEMORY.md (local, não sincronizado). ``` ## Configuração na VPS ### 1. Bearer Token (igual em 2 lugares) ```bash # Gerar ALEXA_TOKEN=$(openssl rand -hex 32) # ex: abc123def456... # Salvar em Vaultwarden (entry "alexa-command-estelar-bearer") # Salvar em Infisical → /admin → OPENCLAW_ALEXA_TOKEN # OpenClaw (docker-compose ou systemd) AUTH_TOKENS='{"alexa-skill":"'$ALEXA_TOKEN'"}' # n8n (docker-compose environment only) OPENCLAW_ALEXA_TOKEN=$ALEXA_TOKEN ``` ### 2. n8n Workflow Importar: `tools/n8n/workflows/alexa-comando-estelar-v3.2-PROXY.json` Variáveis obrigatórias: - `OPENCLAW_GATEWAY_URL`: `http://host.docker.internal:18789` (loopback VPS) - `OPENCLAW_ALEXA_TOKEN`: (same as AUTH_TOKENS.alexa-skill) - `ALEXA_SKILL_APPLICATION_ID`: (from Amazon Developer Console) ### 3. Amazon Developer Console - Endpoint: `https://flow.adventurelabs.com.br/webhook/alexa-v3` - Certificate: Wildcard (já existe em flow.adventurelabs.com.br) - Test: ativado ## Testing ```bash # Testar contra VPS real (com bearer token) ALEXA_SKILL_APPLICATION_ID=amzn1.ask.skill.XXXX-XXXX \ node apps/labs/alexa-buzz-skill/test-alexa-payload.mjs \ https://flow.adventurelabs.com.br/webhook/alexa-v3 all # Esperado: 4/4 PASS, latência <8s # [PASS] LaunchRequest status=200 412ms # [PASS] IntentRequest (GetStatusIntent) status=200 1834ms # [PASS] IntentRequest (AMAZON.StopIntent) status=200 203ms # [PASS] SessionEndedRequest status=200 187ms ``` ## Troubleshooting | Erro | Causa | Fix | |------|-------|-----| | `401 Unauthorized` | Bearer token mismatch | Re-sync `OPENCLAW_ALEXA_TOKEN` e `AUTH_TOKENS.alexa-skill` | | `>8s latência` | Gemini timeout ou sobrecarga | Força fallback Claude; reduz contexto fetch | | Alexa responde genérico | OpenClaw error | Checar logs: `journalctl -u openclaw-gateway -n 50 \| grep alexa` | | Não salva em memória | Skill não tem acesso Supabase | Confirmar service_role_key no OpenClaw env | | Dual-mode não detecta | Prompt ambíguo | Testar prompt com Claude direto | ## Próximos Passos - [ ] Gerar bearer token + configurar n8n e OpenClaw na VPS - [ ] Importar `v3.2-PROXY.json` no n8n e ativar - [ ] Configurar Buzz para responder naturalmente via Alexa (channel: alexa-skill) - [ ] Testar com Alexa device real: launch + query operacional + query pessoal - [ ] Validar que memória está sendo salva no lugar certo ## Referências - Amazon Alexa Request/Response JSON: https://developer.amazon.com/en-US/docs/alexa/custom-skills/request-and-response-json-reference.html - SSML support: https://developer.amazon.com/en-US/docs/alexa/custom-skills/speech-synthesis-markup-language-ssml-reference.html - Workflow n8n: `tools/n8n/workflows/alexa-comando-estelar-v3.json` - Test script: `apps/labs/alexa-buzz-skill/test-alexa-payload.mjs` - Skill manifest: `apps/labs/alexa-buzz-skill/skill.json` - Interaction model: `apps/labs/alexa-buzz-skill/interaction-model.json`