Como o ClawAI é construído

Dezoito serviços implantáveis de forma independente, cada um com seu próprio banco de dados, coordenados por uma arquitetura orientada a eventos. As respostas são transmitidas conforme são geradas e cada camada é protegida separadamente.

Última revisão 2026-07-25

Como o ClawAI é construído

O ClawAI é composto por dezoito serviços implantáveis de forma independente, atrás de um único proxy reverso. Autenticação, chat, roteamento, conectores, memória, arquivos, pesquisa, espaço de trabalho, geração de imagens, exportação de documentos, faturamento, auditoria e registro de logs rodam, cada um, como seu próprio processo com seu próprio banco de dados. O aplicativo web acessa todos eles por meio de uma única superfície de API.

O motivo é a contenção. Um provedor lento, uma conversão de arquivo travada ou uma exportação com falha não conseguem derrubar o chat junto, porque eles não compartilham processo, pool de conexões nem banco de dados. Cada serviço é implantado, escalado e revertido de forma independente.

18: Serviços implantáveis de forma independente
Um por serviço: Nunca um banco de dados compartilhado
HTTP + eventos: Chamadas síncronas mais um barramento de eventos assíncrono
Um único ponto de entrada: Um único proxy reverso na frente de tudo

Os serviços

Nem todo serviço é interessante visto de fora. Estes são os que uma única solicitação costuma tocar, aproximadamente na ordem em que os toca.

AutenticaçãoPostgreSQL: Contas, sessões, emissão de tokens e rotação de atualização, funções e conjuntos de permissões.
ChatPostgreSQL: Conversas e mensagens, montagem de contexto, execução em streaming e orquestração multimodelo.
RoteamentoPostgreSQL: Classifica cada mensagem, aplica o modo ativo e quaisquer políticas, e registra a decisão com sua cadeia de fallback.
ConectoresPostgreSQL: Credenciais de provedores, catálogos de modelos, indicadores de capacidade e verificações contínuas de saúde.
Memória e contextoPostgreSQL + pgvector: Registros de memória, a fila de sugestões, pacotes de contexto e suas versões, e recuperação semântica.
ArquivosPostgreSQL: Envios, verificação de segurança, extração de texto, OCR, fragmentação e retenção.
PesquisaPostgreSQL: Pesquisa na web, busca de páginas e montagem de evidências para respostas com fontes.
Espaço de trabalhoPostgreSQL: Conexões OAuth com doze ferramentas de terceiros, webhooks, sincronização agendada e pesquisa entre ferramentas.
Geração de imagensPostgreSQL: Solicitações de imagem, adaptadores de provedores e progresso por etapa enquanto uma imagem é renderizada.
Geração de documentosPostgreSQL: Transformação de respostas em PDF, DOCX, CSV, HTML, Markdown, TXT e JSON.
FaturamentoPostgreSQL: Planos, assinaturas, preços versionados, faturas e aplicação de cotas.
AuditoriaMongoDB: O registro imutável de quem fez o quê, além do livro-razão de uso do qual todo número de cota é derivado.
Registro de logsMongoDB: Logs estruturados de todos os serviços e do navegador, mantidos em uma janela rotativa de retenção.

Cada serviço nomeia o banco de dados que possui. Nada mais se conecta a ele — um serviço que precisa dos dados de outro os solicita via HTTP ou reage a um evento.

Um banco de dados por serviço

Cada serviço possui exatamente um banco de dados e é a única coisa que se conecta a ele. Não há schema compartilhado, nenhum join entre serviços, e nenhum banco de dados de relatórios lendo silenciosamente as tabelas de todos.

O custo é que algumas perguntas exigem duas chamadas em vez de um join. O benefício é que uma mudança de schema no faturamento não consegue quebrar o chat, e uma consulta descontrolada no registro de logs não consegue esgotar o pool de conexões do qual sua conversa depende.

Sem consultas entre bancos de dados: Um serviço lê apenas suas próprias tabelas, e as de mais ninguém. Dados de outros lugares chegam por uma chamada de API ou um evento.
Os schemas são privados: Um serviço pode alterar suas próprias tabelas sem coordenar com ninguém, porque nenhum consumidor externo depende do formato delas.
As migrações rodam por serviço: Cada serviço migra seu próprio banco de dados na inicialização. Não existe uma migração global que todos precisem esperar.
As falhas ficam localizadas: Um banco de dados lento ou indisponível degrada uma única funcionalidade, e não o produto inteiro.

O ciclo de vida de uma solicitação

O que acontece entre apertar enviar e ler a resposta.

A solicitação é autenticada
o proxy reverso a encaminha ao chat, que verifica seu token de acesso e as permissões associadas à sua função.
A cota é verificada
o faturamento confirma que seu plano permite o modelo solicitado e que sua cota diária e mensal ainda tem espaço.
A mensagem é armazenada e anunciada
o chat grava a mensagem em seu próprio banco de dados e publica um evento. O roteamento está ouvindo por ele.
O roteamento escolhe um modelo
a mensagem é classificada, o modo ativo e as políticas são aplicados, a saúde dos conectores é consultada, e uma decisão com uma cadeia de fallback é registrada.
O contexto é montado
o chat pede à memória os registros e itens de pacote relevantes, e aos arquivos os trechos relevantes, e então os mescla ao prompt dentro de um orçamento de tokens.
O modelo é chamado e transmitido
o chat chama o provedor e encaminha estágios, texto, raciocínio e métricas ao seu navegador via Server-Sent Events, à medida que chegam.
O resultado é persistido
a resposta, sua decisão de roteamento, sua contagem de tokens e seu recibo de contexto são gravados juntos.
Uso e auditoria são registrados
o faturamento mede o custo em relação à sua cota e a auditoria registra o evento. A extração de memória também acontece aqui.

As etapas de 1 a 7 são síncronas — você espera por elas. A etapa 8 e a extração de memória acontecem depois que a resposta já está na sua tela, então não acrescentam latência à sua experiência.

O barramento de eventos

O trabalho que não precisa terminar antes de você ver uma resposta é publicado como um evento em um exchange de tópicos do RabbitMQ e tratado por quaisquer serviços interessados nele. A medição de uso, os registros de auditoria e a extração de memória funcionam todos dessa forma.

Os eventos são o motivo pelo qual o chat não precisa saber que a auditoria existe. O chat declara o que aconteceu; qualquer coisa que precise reagir se inscreve. Adicionar um consumidor não exige nenhuma alteração no publicador.

Exchange de tópicos: Os publicadores nomeiam o que aconteceu, não quem deve ouvir. Os consumidores se vinculam aos padrões que lhes interessam.
Novas tentativas com backoff: Um handler com falha é tentado novamente três vezes com atraso crescente, o que absorve as falhas transitórias que compõem a maioria delas.
Fila de mensagens mortas: Uma mensagem que ainda falha depois de suas tentativas vai para uma fila de mensagens mortas, em vez de ser descartada ou bloquear tudo que vem atrás dela.
Handlers idempotentes: Os handlers toleram o mesmo evento chegando duas vezes, porque a garantia de entrega pelo menos uma vez assegura que, eventualmente, isso vai acontecer.
Tudo é auditável: A auditoria se inscreve em todo evento de domínio, então o registro do que aconteceu não depende de cada serviço se lembrar de escrever um.

Streaming

As respostas chegam via Server-Sent Events, não por polling. A conexão se abre quando você envia uma mensagem e transporta tudo até a resposta terminar ou ser cancelada.

O buffering é desativado de ponta a ponta — no proxy e em todo serviço no caminho — porque um stream com buffer é apenas uma resposta lenta com etapas extras.

O mesmo canal transporta a geração de texto, o progresso da geração de imagens e pesquisas de longa duração, para que a interface tenha uma única forma de mostrar trabalho em andamento, em vez de três.

Mudanças de estágio: Na fila, roteando, montando contexto, chamando o modelo, finalizando — para que uma pausa sempre tenha um motivo visível.
Deltas de conteúdo: O texto da resposta conforme o modelo o produz, token por token.
Deltas de raciocínio: Para modelos que expõem seu raciocínio, o stream de raciocínio é entregue separadamente da resposta e também é exibido separadamente.
Atualizações de métricas: Tokens até o momento, tokens por segundo, tempo até o primeiro token, e para onde o tempo realmente foi — carregamento do modelo, avaliação do prompt ou geração.
Eventos finais: Um resumo final de uso, ou um erro explícito, ou um cancelamento. O stream nunca simplesmente para.

O que armazena o quê

Quatro tipos de armazenamento, cada um usado para o que faz de melhor.

PostgreSQL: O sistema de registro para contas, conversas, decisões de roteamento, memória, arquivos, conexões e faturamento — um banco de dados por serviço.
pgvector: Busca de similaridade vetorial dentro do PostgreSQL, usada para recuperar memórias e itens de pacote de contexto relevantes sem precisar de um banco de dados vetorial separado.
MongoDB: Eventos de auditoria, o livro-razão de uso e logs estruturados: dados de alto volume, somente de inserção, com uma janela rotativa de retenção.
Redis: Cache, contadores de limitação de taxa e estado de coordenação de curta duração. Nada que importa é armazenado apenas aqui.

Mecanismos de segurança

Controles concretos que existem no produto. Nenhuma alegação de certificação — veja a observação no final.

Tokens de acesso e atualização: Tokens de acesso de curta duração com rotação de atualização. A reutilização de um token já rotacionado invalida a sessão.
Hash de senhas: Argon2 com salts por usuário. As senhas nunca são armazenadas ou registradas em nenhuma forma recuperável.
Controle de acesso baseado em função: As funções carregam conjuntos explícitos de permissões, aplicados por guards em cada endpoint de cada serviço — não apenas na interface.
Credenciais criptografadas: Os segredos de provedores e conectores são criptografados em repouso com AES-256-GCM e nunca são retornados por uma API.
Validação de schema: Todo corpo de solicitação é validado contra um schema Zod com limites explícitos de tamanho e comprimento antes de alcançar qualquer lógica.
Limitação de taxa: Limitação por conta em cada serviço, para que um cliente não consiga esgotar a capacidade para todos os outros.
Cabeçalhos de segurança: Uma política estrita de segurança de conteúdo com nonces por solicitação, HSTS, e os cabeçalhos de reforço padrão em toda resposta.
TLS em todo lugar: TLS do navegador até a borda e novamente em cada conexão interna, com verificação de certificado entre serviços.
Censura de logs: Tokens, senhas, chaves de API e cabeçalhos de autorização são removidos antes que qualquer coisa seja gravada em um log.

O ClawAI não possui certificações de segurança de terceiros atualmente — nem SOC 2, nem ISO 27001, nem HIPAA. Descrevemos os mecanismos acima em vez de sugerir garantias que não obtivemos. Empresas com requisitos formais devem nos procurar para que possamos dimensioná-los como parte de um projeto.

Observabilidade

Todo serviço emite os mesmos sinais no mesmo formato, e todos eles chegam a algum lugar consultável. Um operador respondendo "o que aconteceu com esta solicitação" não deveria precisar abrir dezoito arquivos de log.

Logs estruturados: Logs em JSON de todos os serviços e do navegador, enviados pelo barramento de eventos e mantidos em uma janela rotativa de retenção.
Correlação de solicitações: Um ID de solicitação é gerado no navegador e carregado por cada conexão entre serviços, de forma que um único identificador reconstrói todo o caminho.
Eventos de auditoria: Um registro separado e imutável de ações relevantes para segurança e negócios, mantido à parte dos logs operacionais.
Livro-razão de uso: Toda chamada medida é gravada como um lançamento no livro-razão. Os números de cota são derivados do livro-razão, não de um contador que poderia se dessincronizar.
Agregação de saúde: Um serviço dedicado consulta todos os outros serviços e reporta uma visão consolidada do que está no ar.

Quando algo falha

Os provedores de modelos têm interrupções, limites de taxa e dias lentos. A plataforma é construída para absorver isso, em vez de repassar a você como um indicador de carregamento que nunca se resolve.

Cadeias de fallback: Toda decisão de roteamento carrega uma lista ordenada de alternativas. Se o modelo escolhido falha, o próximo é tentado automaticamente e a substituição é registrada.
Desvio baseado em saúde: Os conectores têm a saúde verificada continuamente, e um provedor com falhas é evitado pelo roteador até que se recupere.
Novas tentativas seguras: Os handlers de eventos toleram entregas duplicadas, então uma nova tentativa corrige uma falha em vez de cobrar sua cota duas vezes.
Os erros são visíveis: Quando todas as opções falham, um erro explícito é gravado na conversa e enviado pelo stream. Não existe falha silenciosa que deixe a interface esperando.
Raio de impacto: Processos separados e bancos de dados separados significam que uma falha degrada uma única funcionalidade. A geração de imagens ficar fora do ar não impede você de conversar.

A mesma arquitetura, dentro da sua rede

Tudo nesta página descreve o serviço hospedado, mas a arquitetura não está presa a ele. Os mesmos dezoito serviços, o mesmo barramento de eventos e o mesmo modelo de dados podem ser implantados dentro da própria rede de uma empresa.

Nessa configuração, os provedores de modelos externos são substituídos por modelos de peso aberto executados nas suas próprias GPUs, de forma que nenhum prompt, documento ou conversa saia da sua infraestrutura. É um projeto sob medida, não um plano que se compra — nós o dimensionamos com a sua equipe.

Fale conosco sobre uma implantação privada

Veja funcionando

A forma mais rápida de julgar uma arquitetura é usar o que ela produz. O plano gratuito leva um minuto para ser configurado.

Crie sua conta Fale conosco sobre uma implantação privada