Keural Duo
Agente sempre ativo no seu computador, com instalação, conversa, rotinas, Telegram, uso do computador e Mate & Morph.
O Duo é um agente sempre ativo instalado pelo app de desktop neste computador (ou em um DGX Spark conectado). Ele funciona em um sandbox isolado, você conversa com ele pelo Duo na barra lateral ou pelo Telegram, e ele executa as rotinas cadastradas. É baseado no NVIDIA NemoClaw e no OpenClaw.
O Duo está disponível somente no app de desktop.
Instalar
Em Configurações → Duo → Ambiente de execução, escolha um modelo e clique em Instalar na linha do local onde deseja executá-lo. O botão Instalar fica desativado se nenhum modelo tiver sido escolhido ou se o espaço em disco for insuficiente.
Onde executa e requisitos
| Onde executa | Requisitos |
|---|---|
| Este dispositivo (macOS) | Mac com chip Apple e 16 GB de memória ou mais. O ambiente de contêineres é instalado pelo próprio app, por isso Docker Desktop, Homebrew e senha de administrador não são necessários. |
| Este dispositivo (Windows) | WSL 2. Na primeira vez, clique em Preparar o Windows para instalar os componentes necessários. Pode ser solicitado reiniciar o PC ou permitir o acesso de administrador. Se a virtualização estiver desativada, ative-a na BIOS. |
| Dispositivo remoto (DGX Spark) | Conecte um Spark e execute um modelo nele primeiro. Se o firewall do Spark estiver ativado, informe uma vez a senha da conta do Spark para abrir duas portas (a senha não é salva). |
O Duo precisa de pelo menos 20 GB de espaço em disco, e recomenda-se 40 GB ou mais. Se o espaço for insuficiente, o botão Instalar fica bloqueado e aparece "São necessários {need} GB · {free} GB livres".
Modelo
| Opção | Descrição |
|---|---|
| Modelo deste dispositivo | Usa o modelo local baixado que estiver em execução. Aparece como "{name} · mesmo modelo do chat". |
| DGX Spark | O modelo em execução no Spark conectado. |
| Nuvem | O modelo do Duo incluído no seu plano. A lista é exibida somente quando você está conectado. |
| Gateway | Usa um modelo de um servidor conectado em Configurações → Modelos → Gateways. É preciso o endereço e a chave de API desse servidor. |
Após a instalação, troque o modelo na linha Modelo. Dentro do mesmo tipo, a troca é imediata, com "Trocar". Ao trocar entre local, nuvem e gateway, é preciso reinstalar. Reinstalar mantém as rotinas. Para mover o Duo para outro local, exclua-o e depois instale no novo local.
Etapas da instalação
As etapas seguem esta ordem: verificar este dispositivo → preparar o ambiente de contêineres → instalar o NemoClaw → iniciar o modelo (na nuvem e no gateway, preparar o acesso ao modelo) → criar o sandbox → configurar o Duo → verificar o funcionamento. A etapa atual aparece no botão e no card de progresso. Se a mensagem "Está demorando um pouco mais que o normal, mas continua. Mantenha o app aberto." aparecer, não feche o app.
Se a instalação parar, identifique a causa pela mensagem na tela em Quando a instalação falha.
Duo de outra conta ou workspace
Há apenas um Duo por dispositivo, e ele pertence à conta e ao workspace em que foi instalado. Se você entrar com outra conta ou mudar para outro workspace, o Duo em Configurações aparece como "Não instalado", e o Duo da barra lateral e o Mate & Morph ficam ocultos. Nesse estado, ao clicar em Instalar, aparece uma confirmação: "Há um Duo de outra conta ou workspace neste dispositivo. Instalar um novo apaga esse Duo, as conversas e as rotinas dele." Ao clicar em Instalar novo, o Duo existente é apagado e um novo é criado. Ao voltar para a conta ou o workspace original, o Duo existente aparece novamente.
Se houver um Duo instalado anteriormente, ele é limpo e a instalação continua. Se a limpeza falhar, aparece "Não foi possível apagar o Duo anterior. Instale novamente."
Quando a instalação falha
Se a instalação parar, Configurações → Duo exibe uma mensagem de erro. Confira também o código entre parênteses no fim da mensagem. Depois de resolver a causa, clique em Instalar novamente.
| Mensagem na tela | Causa | Solução |
|---|---|---|
Instalação interrompida: espaço em disco insuficiente. Garanta pelo menos {need} GB livres e tente novamente | O disco que contém sua pasta pessoal tem menos de 20 GB livres. | Libere 20 GB ou mais (40 GB recomendados). |
| Não foi possível preparar o ambiente de contêineres. Verifique sua conexão e tente novamente | Não foi possível baixar os arquivos da instalação. Em geral, o firewall ou o proxy da empresa é a causa. | Verifique a conexão com a internet. Em rede corporativa, peça à TI a liberação dos endereços em Downloads. |
| Não foi possível remover o Duo anterior. Instale novamente. | Não foi possível limpar um Duo anterior que ficou neste dispositivo. | Feche o app por completo, abra-o de novo e clique em Instalar. Se continuar falhando, confira a mesma mensagem na aba macOS. |
| Há um Duo de outra conta ou workspace neste dispositivo. | O Duo deste dispositivo pertence a outra conta ou workspace. | Clique em Instalar novo para remover esse Duo e instalar. Para continuar usando o Duo existente, mude para a conta ou o workspace original. |
| Seu plano não inclui modelos na nuvem para o Duo. | O plano do workspace atual não inclui o Duo na nuvem. | Troque o modelo para Modelo deste dispositivo, DGX Spark ou gateway, ou confira seu plano. |
| Entre para usar os modelos na nuvem. | Você está desconectado. | Entre e instale novamente. |
| O modelo do Duo não está em execução. Inicie-o e aplique novamente. | O modelo deste dispositivo não está em execução. | Execute o modelo em Configurações → Modelos e depois instale. |
| Está demorando mais que o normal, mas continua trabalhando. Mantenha o app aberto. | A primeira instalação baixa muitos arquivos. | Mantenha o app aberto e aguarde. Em notebook, impeça que ele entre em suspensão. |
Se o problema persistir, entre em contato com o suporte em Configurações → Suporte. Informe a mensagem na tela, o código entre parênteses e o tipo de dispositivo (macOS, Windows ou Spark).
Tela Configurações → Duo
| Seção | Conteúdo |
|---|---|
| Status | "Executando em {onde}" · Parado · Iniciando · Não instalado · Sem servidor (quando a conexão com o Spark está ausente) |
| Ambiente de execução | Seleção de modelo; Instalar, Iniciar, Parar e Excluir nas linhas Este dispositivo / Dispositivo remoto; ID do sandbox e versão do NemoClaw |
| Apps de chat | Conexão com o Telegram |
| Conexões | GitHub, pesquisa na web |
| Uso do computador | Permissões, pastas legíveis, regras antes de agir, apps sempre permitidos, Mate & Morph |
| Memória da conversa | Uso de contexto, compactação da conversa, nova conversa |
| Recursos novos (Windows) | Conexão do computador Windows, pastas compartilhadas, verificação de acesso a apps, tarefas recentes |
Durante operações longas (instalação, troca de modelo, aplicação de mudanças nos apps de chat ou exclusão), as demais seções ficam bloqueadas. Ao ativar o uso do computador ou ampliar as regras, aparece uma caixa de confirmação do sistema operacional.
Conversa
Clique em Duo na barra lateral. (Não é exibido no modo Código.) As mensagens enviadas enquanto a conexão está fora ficam como "{n} aguardando envio" e são entregues quando a conexão voltar. Ao enviar /new, o app pergunta se deseja iniciar uma nova conversa.
Ao ativar Info do Duo no topo, os cards a seguir são exibidos no painel lateral.
| Card | Conteúdo |
|---|---|
| Agora | A tarefa atual ou em espera, o tempo decorrido e as ferramentas usadas |
| As configurações do Duo mudaram | Exibido somente quando as configurações do sandbox são diferentes da última verificação do Keural. Mostra as áreas alteradas (apps de chat e quem pode conversar com o Duo · ferramentas e permissões · serviços conectados · conexão do modelo · outros). Se a mudança foi feita por você, clique em Aceitar alterações. |
| Sandbox | Pronto ou erro, resposta do modelo normal ou sem resposta, GPU (CUDA) em uso ou não, capacidade |
| Modelo | Nome do modelo, local (Este dispositivo · DGX Spark · Nuvem), uso de contexto |
| Rotinas | Veja Rotinas abaixo |
| Conexões · Telegram | Resumo da conexão. Clique para ir às configurações. |
| Arquivos do workspace | Arquivos que o Duo criou na pasta de trabalho do sandbox |
Clique em Tarefas em segundo plano para ver a lista de subagentes que o Duo está executando.
Memória da conversa
Em Configurações → Duo → Memória da conversa, veja o "Contexto em uso" em número de tokens e percentual. Use Compactar para reduzir a conversa, ou Nova para abrir uma nova conversa. A conversa atual é mantida. Se o Duo estiver trabalhando, faça isso depois que ele terminar. Quando aparecer "A conversa ficou longa demais para o modelo processar, e o Duo não conseguiu responder.", compacte a conversa ou inicie uma nova.
Rotinas
Ao dizer ao Duo algo como "Todo dia às 9h, faça …", o card Criar esta rotina? (Tarefa · Horário · Onde) é exibido. Clique em Criar rotina para registrá-la. Alterações e exclusões também são confirmadas com o mesmo tipo de card.
| Item | Descrição |
|---|---|
| Frequência | Uma vez (até 365 dias depois) · todo dia · dias úteis · semanal · a cada N minutos (de 5 a 1.440 minutos) |
| Onde | A conversa do Duo no app do Keural, ou Enviar pelo Telegram |
| Limites | 10 ativas, 50 no total |
| Validade | 7 dias por padrão, no máximo 30 dias. Depois, "Expirada" |
| Perdida | Se o app estava fechado e a rotina atrasou mais de 10 minutos em relação ao horário previsto, ela não é executada e fica como "Perdida" |
| Falha | Após 3 falhas seguidas, aparece "Pausada após falhas" |
No card Rotinas do painel de informações do Duo, ative ou desative as rotinas e, em Mais, escolha Executar agora ou Excluir. Cada linha mostra a próxima execução e o status (Enviada · Perdida · Com falha · Pausada · Expirada). Os resultados são entregues à conversa do Duo ou ao Telegram, e também é exibida uma notificação do desktop (Executar agora não exibe notificação). As rotinas são executadas somente enquanto o app está aberto.
Apps de chat (Telegram)
Siga as etapas em Configurações → Duo → Apps de chat → Telegram → Conectar.
- No Telegram, abra o @BotFather, envie
/newbote defina o nome e o nome de usuário do seu bot. - Cole o token do bot enviado pelo BotFather e clique em Verificar. Não divulgue o token, pois quem o tiver pode controlar o bot.
- Leia o QR code com o celular para abrir o bot e clique em Iniciar. Se não houver resposta, envie ao bot o código exibido na tela.
- Quando aparecer "Somente
{name}pode conversar com o Duo por mensagem direta.", clique em Adicionar e depois em Aplicar.
Ao aplicar, o Duo é reiniciado (as conversas e os arquivos são mantidos). Depois disso, as mensagens enviadas pelo celular aparecem na conversa do Duo com a indicação "Enviado pelo Telegram". Somente a pessoa conectada pode conversar com o Duo por mensagem direta. Para desconectar, clique em Desconectar e depois em Aplicar. Com o Telegram conectado, as aprovações de rotinas também são recebidas pelo Telegram.
Um token de bot só pode ser usado em um dispositivo (Duo) por conta. Para conectar outro dispositivo, desconecte o dispositivo atual e registre o token novamente.
As aprovações de ações em apps são feitas somente na janela do app do Keural, mesmo nas conversas iniciadas pelo Telegram.
Conexões
Fica em Configurações → Duo → Conexões.
| Serviço | Como |
|---|---|
| GitHub | Cole um Token de acesso pessoal e verifique, ou clique em Continuar com a GitHub CLI para usar o login gh deste computador. Se a CLI não estiver instalada, aparece um link de instalação; se você não estiver logado, abre-se a janela de login. Ao conectar ou trocar, o Duo é reiniciado. |
| Pesquisa na web | O Duo usa o método escolhido em Configurações → Geral → Pesquisa na web (Pesquisa rápida · Pesquisa Keural · Tavily, Brave ou SearXNG do seu próprio serviço de busca). É preciso que o Uso do computador esteja ativado. |
Tokens e chaves são enviados ao app somente uma vez, na verificação, e são apagados da tela imediatamente.
Uso do computador
Ative Configurações → Duo → Uso do computador → Permitir que o Duo use este computador para que o Duo use apps deste computador, leia as pastas indicadas e crie rotinas. Ao ativar, o Duo é reiniciado por cerca de 1 minuto.
| Item | Descrição |
|---|---|
| Permissões do macOS | Acessibilidade (clicar e digitar) e Gravação de tela (ver a tela). Se alguma não estiver concedida, clique em Abrir Ajustes do Sistema. |
| Pastas que o Duo pode ler | O Duo lê somente as pastas indicadas com Adicionar pasta. Não é possível adicionar pastas amplas, como a pasta pessoal inteira ou pastas do sistema. |
| Antes de o Duo agir | Perguntar sempre (padrão) · Agir sem perguntar · Eu mesmo faço. Ao mudar para Agir sem perguntar, é pedida uma confirmação adicional. |
| Apps sempre permitidos | Lista dos apps que você liberou com Sempre permitir na janela de aprovação. Pressione × para remover. |
Mesmo com Agir sem perguntar ou Sempre permitir, etapas sensíveis como enviar, excluir, sobrescrever, pagar, enviar formulário, fazer login, publicar e cancelar, além de teclas como Enter, Backspace e ⌘Q, sempre pedem confirmação antes.
Quando o Duo aguardar sua permissão, "O Duo está aguardando sua aprovação" aparece acima da caixa de entrada. Clique em Revisar para abrir a janela de aprovação. As opções da janela são Recusar · Permitir uma vez · Sempre permitir. O Mate & Morph também exibe "Aguardando aprovação". As aprovações só podem ser feitas nesta janela.
O Duo abre sem aprovação somente os resultados de busca e os endereços de links retornados pelo app. Para endereços que o próprio Duo digitou ou alterou, a janela de aprovação mostra o endereço completo e pede confirmação.
Mate & Morph
O Mate & Morph é o personagem de desktop do Duo. Ative Configurações → Duo → Uso do computador → Mate & Morph → Mostrar na área de trabalho e escolha o Personagem (Mate · Morph · Ambos) e o Tamanho (Pequeno · Médio · Grande).
- Ele é exibido somente enquanto o Duo estiver em execução e a conversa estiver pronta. Fica oculto se você mudar de conta ou de workspace, ou se o seu plano não permitir o Duo.
- Um clique no personagem abre o campo de entrada, e um clique duplo abre o app. Ao lado do personagem são exibidos o status (Aguardando · Trabalhando · Concluído · Bloqueado · Precisa de você · Aguardando aprovação) e o motivo da última falha de resposta.
- Menu de contexto (clique com o botão direito): Ocultar · Marcar como lido · Abrir o Duo · Configurações do Duo. O menu da barra de menus (bandeja) também tem Mostrar/Ocultar Mate & Morph.
Windows
No Windows, o Duo roda em uma distribuição WSL e oferece suporte a conversas, rotinas, Telegram, aprovações, Mate & Morph e uso do computador, da mesma forma que no macOS. Alguns apps e janelas de segurança, como campos de senha, UAC e terminais, são deixados para você fazer diretamente, sem que o Duo os acesse.
Em Configurações → Duo → Recursos novos (em um computador Windows), verifique a conexão do Duo, as Pastas compartilhadas (o Duo lê somente as pastas escolhidas), o Acesso a apps e as Tarefas recentes. No Windows, também é possível usar a Instalação de software (somente com ID de pacote exato) e a Conexão Wi‑Fi (somente perfis salvos). Enviar, excluir, sobrescrever, instalar e alterar a rede sempre pedem confirmação antes.
Excluir
Em Configurações → Duo → Ambiente de execução, clique em Excluir na linha do local onde o Duo está instalado e confirme em "Excluir o Keural Duo deste dispositivo?" com Excluir. O sandbox é excluído junto com o histórico de conversas, as rotinas e os arquivos de trabalho. No macOS, a máquina virtual de contêineres exclusiva do Duo também é excluída. O Duo em um DGX Spark só pode ser excluído enquanto o Spark estiver conectado.
Mensagens comuns
| Mensagem | Significado |
|---|---|
| O Duo não está em execução | Em Configurações → Duo, clique em Iniciar. |
| É necessário o app de desktop mais recente | Atualize o app. |
| O modelo não está em execução. Inicie-o e aplique novamente. | O modelo local ou o do Spark está desligado. Inicie o modelo primeiro. |
| A conexão com o modelo foi perdida. Verifique se você está conectado. | O acesso ao modelo do Duo na nuvem foi perdido. Entre novamente. |
| O plano deste workspace não permite usar o Duo. | O plano não permite o Duo com modelo na nuvem. Troque para um modelo local ou verifique o seu plano. |
| Há um Duo de outra conta ou workspace neste dispositivo. | Instalar apagará esse Duo. Ao voltar para a conta ou o workspace original, você poderá usá-lo novamente. |
| Não foi possível apagar o Duo anterior. Instale novamente. | Não foi possível limpar o Duo instalado antes. Clique em Instalar novamente. |
Detalhes técnicos para a equipe de TI
Requisitos
| Onde executa | Critério |
|---|---|
| macOS | Chip Apple (arm64), 16 GB de memória ou mais. A máquina virtual do Duo (Colima, vz) usa 4 CPUs, 9 GiB de memória e 40 GiB de disco (ocupando apenas o necessário). |
| Windows | WSL 2 (kernel 5.15 ou posterior), x64 ou ARM64. Instala a distribuição Ubuntu 24.04 com o nome Keural-Duo e usa Podman rootless dentro dela. Não é necessário Docker Desktop. |
| DGX Spark | Docker em execução, 20 GB de disco livre e 8 GB de memória disponível ou mais |
| Comum | 20 GB ou mais livres no disco que contém a pasta pessoal (40 GB recomendados) |
No Windows, a instalação grava networkingMode=nat na seção [wsl2] de %USERPROFILE%\.wslconfig. Em PCs que usam rede espelhada (mirrored), o Duo não é instalado.
Locais de instalação
| Onde executa | Caminho |
|---|---|
| Ambiente de execução no macOS | ~/.keural-runtime/ (Colima, Lima, CLI do Docker, logs) |
| Inicialização automática no macOS | ~/Library/LaunchAgents/kr.mkd.keural-duo-colima.plist, kr.mkd.keural-duo-gateway.plist, kr.mkd.keural-duo-sweeper.plist |
| CLI do NemoClaw | ~/.local/bin/nemoclaw |
| Windows | Distribuição WSL Keural-Duo |
| Registros do app | Na pasta de dados do app: keural-duo@<servidor>.json, keural-duo-routines@<servidor>.json, keural-duo-rules@<servidor>.json |
| Logs | ~/.keural/logs/, ~/.keural-runtime/colima.log e gateway.log, e keural-duo-install.log na pasta de dados do app |
Downloads
Libere no firewall ou no proxy os endereços abaixo. Os arquivos baixados têm versão fixa e são verificados com SHA-256.
| Endereço | O que é baixado |
|---|---|
github.com | Colima v0.10.3, Lima v2.2.1, buildx v0.38.2 (macOS), ferramentas Podman (Windows) |
download.docker.com | CLI do Docker 29.9.3 (macOS) |
www.nvidia.com | Script de instalação do NemoClaw (v0.0.134) |
ghcr.io | Imagem do sandbox do OpenClaw |
api.telegram.org | Conexão com o Telegram |
Servidores do Keural (api.keural.ai etc.) | Modelos na nuvem, login |
Se você usar a pesquisa na web ou a conexão com o GitHub, também libere api.tavily.com, api.search.brave.com, api.github.com e api.githubcopilot.com.
Rede e portas
| Onde | Porta | Uso |
|---|---|---|
| macOS | 127.0.0.1:8080 | Gateway do OpenShell |
| macOS · Windows | 127.0.0.1:8766 | Servidor do modelo deste dispositivo (no Windows, um relé dentro do WSL). Se estiver ocupada, usa-se a 8768 |
| DGX Spark | Uma porta livre entre 18080 e 18099 | Gateway exclusivo do Spark |
| DGX Spark | 18081 | Relé do sandbox para o modelo do Spark (8000) |
| DGX Spark | 22 | Acesso SSH do app |
Se o firewall ufw estiver ativo no Spark, a instalação abre duas portas (a do gateway e a do relé). Nesse momento, a senha da conta do Spark é solicitada uma vez.
O sandbox não acessa a internet diretamente. A pesquisa na web e a leitura de páginas são feitas pelo app em nome dele, e o GitHub é conectado somente para leitura.
Endereços dos modelos
| Modelo | Endereço chamado pelo sandbox |
|---|---|
| Modelo deste dispositivo | http://localhost:<porta>/v1. Modelo padrão qwen3-8-27b, contexto de 262.144 |
| Modelo do DGX Spark | Pelo relé do Spark, até 127.0.0.1:8000/v1 no Spark |
| Modelo na nuvem | /core/v1/bot/v1 do servidor do Keural. Usa um token emitido para cada Duo. |
| Gateway | Endereço do servidor conectado em Configurações → Modelos → Gateways |
O endereço do gateway pode ser qualquer um se usar https. Com http, são aceitos somente IPs privados ou nomes internos (.local, .lan, .internal, .intranet, .home.arpa e nomes sem ponto). Não são aceitos localhost nem endereços com user:pass@.
Telegram
- O token do bot é obtido com
/newbotno BotFather. O formato énúmero:alfanumérico. - Quando o código de conexão é gerado, você tem 10 minutos para abrir o bot no celular e 5 minutos para enviar a primeira mensagem. A conta que enviar a primeira mensagem fica autorizada.
- Em conversas de grupo, o Duo não responde.
Rotinas
| Item | Valor |
|---|---|
| Verificação | Procura as rotinas a executar a cada 30 segundos. |
| Perdida | Se o horário previsto estiver atrasado em mais de 10 minutos, a rotina não é executada e fica registrada como perdida. |
| Pausa | Para após 3 falhas consecutivas. |
| Intervalo de repetição | De 5 a 1.440 minutos |
| Execução única | Até 365 dias depois |
| Validade | 7 dias por padrão, no máximo 30 dias |
| Limite | 10 rotinas ativas, 50 no total |
| Fuso horário | O do computador em que a rotina foi criada |
Regras para adicionar pastas
As pastas abaixo não podem ser adicionadas.
| Tipo | Pastas |
|---|---|
| Comum | Raiz do disco, a própria pasta pessoal e as pastas acima dela |
| Dentro da pasta pessoal | .ssh, .aws, .gnupg, .kube, .docker, .config, Library, .Trash, AppData |
| macOS | /System, /Library, /usr, /bin, /sbin, /etc, /var, /private, /dev, /Volumes, /Applications, /opt, /cores |
| Windows | Windows, Program Files, Program Files (x86), ProgramData |
Permissões do uso do computador
| SO | Permissões necessárias |
|---|---|
| macOS | Em Ajustes do Sistema → Privacidade e Segurança: Acessibilidade e Gravação de Tela |
| Windows | Não requer permissões adicionais; usa o Windows UI Automation. |
Botões como enviar, excluir, pagar, comprar, enviar formulário, fazer login, transferir, publicar e cancelar, e teclas como Enter, Delete, fechar janela ou sair do app, são tratados como etapas sensíveis e sempre pedem confirmação.
O que é removido na exclusão
Ao clicar em Excluir, são removidos o sandbox, o histórico de conversas do Duo, as rotinas, as conexões com Telegram, GitHub e pesquisa, e o token do modelo na nuvem. Se não houver outro Duo neste dispositivo, o macOS também remove ~/.keural-runtime/ e os itens de inicialização automática. As configurações do Mate & Morph e os registros de conexão com o Spark permanecem.