Conceitos principais para entender a arquitetura do assistente de IA Clawdbot, sessões, roteamento multi-agente e manipulação de mensagens.

Visão Geral dos Conceitos do Clawdbot

Entender os conceitos principais do Clawdbot ajuda você a configurar e usar seu assistente de IA de forma eficaz. Esta seção cobre os blocos fundamentais do Clawdbot.

Conceitos Chave

Arquitetura do Gateway

O Gateway é o daemon central que:

Mantém todas as conexões de provedores de mensagens
Expõe uma API WebSocket tipada
Gerencia o runtime de agentes e sessões
Lida com o roteamento de mensagens

Saiba mais sobre a Arquitetura do Gateway

Sessões

O Clawdbot trata uma sessão de chat direto por agente como principal:

Chats diretos são colapsados para agent:<agentId>:<mainKey>
Chats de grupo/canal obtêm suas próprias chaves
O estado da sessão é de propriedade do Gateway

Roteamento Multi-Agente

Execute múltiplos agentes isolados com:

Workspaces separados (arquivos, regras de persona)
Diretórios de estado
Armazenamentos de sessão
Perfis de autenticação

Runtime do Agente

O runtime do agente lida com:

Processamento de mensagens
Execução de ferramentas
Gerenciamento de contexto
Geração de respostas

Gerenciamento de Sessões

Opções de Escopo de DM

Escopo	Descrição
`main` (padrão)	Todas as DMs compartilham a sessão principal
`per-peer`	Isolar por ID do remetente entre canais
`per-channel-peer`	Isolar por canal + remetente
`per-account-channel-peer`	Isolar por conta + canal + remetente

Chaves de Sessão

Fonte	Formato da Chave
Chats diretos	`agent:<agentId>:<mainKey>`
Chats de grupo	`agent:<agentId>:<channel>:group:<id>`
Jobs cron	`cron:<job.id>`
Webhooks	`hook:<uuid>`

Ciclo de Vida da Sessão

Sessões são reutilizadas até expirarem
Reset diário padrão às 4:00 AM hora local
Reset opcional por inatividade via idleMinutes

Configuração Multi-Agente

O que é um Agente?

Um agente é um cérebro com escopo completo que possui:

Workspace: Arquivos, AGENTS.md, SOUL.md, regras de persona
Diretório de estado: Perfis de autenticação, registro de modelos
Armazenamento de sessão: Histórico de chat + estado de roteamento
Habilidades: Por agente via pasta skills/ do workspace

Modo de Agente Único (Padrão)

agentId é padrão main
Sessões identificadas como agent:main:<mainKey>
Workspace em ~/.clawdbot/workspace

Adicionando Agentes

# Adicionar um novo agente
clawdbot agents add work

# Listar agentes com bindings
clawdbot agents list --bindings

Regras de Roteamento

Mensagens são roteadas para agentes via bindings:

{
  "bindings": [
    {
      "agentId": "alex",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "dm", "id": "+15551230001" }
      }
    }
  ]
}

Manipulação de Mensagens

Streaming e Chunking

O Clawdbot suporta respostas em streaming:

Atualizações parciais de mensagens
Indicadores de digitação
Entrega em chunks para respostas longas

Política de Retry

Mensagens com falha são retentadas com:

Backoff exponencial
Limites de retry configuráveis
Tratamento de erros

Onde o Estado Reside

Item	Localização
Configuração	`~/.clawdbot/clawdbot.json`
Sessões	`~/.clawdbot/agents/<agentId>/sessions/`
Transcrições	`~/.clawdbot/agents/<agentId>/sessions/<SessionId>.jsonl`
Perfis de autenticação	`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`

Próximos Passos

Gateway do Clawdbot - Configuração do Gateway
Ferramentas do Clawdbot - Configuração de ferramentas
Canais do Clawdbot - Configuração de canais

Conceitos do Clawdbot

On this page