$~/geminiclaw/docs
Last synced from GitHub: Apr 22, 2026, 12:40 AM
Mirrored from the product repository.
GeminiClaw

GeminiClaw Docs

Local-First Multi-Agent AI Orchestrator for Telegram, Operations, and Autonomous Execution

node ≥20typescript 5.xsqlite local-firsttelegram

Mirrored from the main product repository

GeminiClaw

Telegram-first local AI agent platform for real operational work.

GeminiClaw roda no seu ambiente, usa ferramentas reais, persiste contexto localmente e pode atuar em fluxos de codigo, operacao e automacao assistida. O caminho publico inicial e intencionalmente simples: preparar o ambiente, conectar um bot do Telegram e ver a plataforma funcionando em poucos minutos.

![Telegram-first quickstart](Docs/assets/onboarding/onboarding-flow-marketing.png) ![Setup assistido (captura real)](Docs/assets/onboarding/setup-terminal-real.png) ![Mensagem /start (captura real)](Docs/assets/onboarding/telegram-start-real.png)

O que voce consegue ver funcionando primeiro

  • Um bot no Telegram respondendo no seu ambiente local.
  • O primeiro chat privado que mandar `/start` virando admin local automaticamente quando nenhum admin estiver configurado.
  • Execucao local com memoria, runtime, ferramentas e persistencia em `DATA_DIR`.
  • Um caso de uso concreto em um repositorio Git simples, com analise, diff e verificacao.
  • Self-repair com checkpoint, verificacao obrigatoria e recovery explicito quando o proprio GeminiClaw precisa alterar o proprio codigo.

Novidades recentes

  • **Confiabilidade do canal Telegram**: retry com backoff exponencial (3 tentativas) para envio de mensagens; timeout por ferramenta (60s padrao, ate 5min para midia) impedindo que uma ferramenta lenta bloqueie o run inteiro.
  • **ADK Runtime (sole runtime)**: migracao completa para Google ADK (`@google/adk`). O `autonomousLoop.ts` e o `intentClassifier.ts` foram deprecados. O LLM decide quais ferramentas usar nativamente, sem classificador de intencao. Politica unificada em `policyCallback.ts` com rate limiter, loop guard adaptativo, policy lattice e Google Ads playbook.
  • **Titans Surprise Metrics**: sistema de memoria inspirado no paper "Titans: Learning to Memorize at Test Time". Chunks redundantes sao filtrados antes de salvar no LanceDB (surprise-gated insertion). Memorias surpreendentes recebem prioridade no retrieval (surprise-boosted re-ranking).
  • **Google Ads completo**: 20 ferramentas cobrindo campanhas, RSAs, assets, audiences, bidding, PMax, experiments, shared sets. Health analyzer com score 0-100. Playbook estrategico embutido nas instrucoes. Safety gates para operacoes destrutivas.
  • **create_post / create_reel**: orquestrador para todos os tipos de post (reel, image, carousel, story, audio, veo_reel). O `veo_reel` agora suporta 15-90s, batches de clips e personagem consistente via foto do chat, imagens locais ou character pack interno.
  • **edit_image**: edicao de fotos com Gemini 3 Pro Image Preview, preservando identidade pela foto original + identity anchors no prompt.
  • **generate_video**: Veo 3.1 com texto→vídeo e imagem→vídeo. Pode usar a última foto do chat ou até 3 referências locais para consistência visual.
  • **FinOps**: rastreamento de custos da API Gemini por agente, ferramenta e modelo. Dashboard no Studio com KPIs, graficos e drill-down.
  • **Memoria hierarquica**: cada agente le apenas suas proprias memorias + subordinados diretos. Fatos de plataforma acessiveis a todos. Surprise metrics filtram ruido na insercao e priorizam memorias informativas no retrieval.
  • **3 modos de autonomia**: `trust_first` (executa livremente), `require_approval` (leitura livre, escrita com aprovacao), `supervised` (tudo com aprovacao). Loop guard adaptativo por modo.
  • **ADK Chat no Studio**: interface de chat com streaming SSE para conversar com agentes diretamente do painel.
  • **WhatsApp**: canal WhatsApp via Meta messaging (em adicao ao Telegram e CLI).
  • **Higiene de worktree**: `npm run check:worktree-hygiene` detecta duplicatas suspeitas com sufixo ` 2` e artefatos gerados que escaparam do `.gitignore`.

Quickstart de 10 a 15 minutos

Suporte publico inicial: macOS + Node.js 20+.

Passos externos obrigatorios:

1. Criar uma `GEMINI_API_KEY`. 2. Criar um bot no Telegram com o `@BotFather`.

Passos no repositorio:

npm install
npm run setup
npm run start:telegram

Se preferir preencher o ambiente manualmente antes do setup assistido, use `.env.example` como contrato publico minimo.

Depois:

1. Abra o bot no Telegram. 2. Envie `/start`. 3. Mande uma tarefa simples, por exemplo:

Analise a pasta examples/demo-repo, encontre o bug guiado, mostre o diff, rode npm test e sugira uma mensagem de commit.

Se precisar validar o ambiente antes de subir o runtime:

npm run doctor

Primeiro valor recomendado

O melhor demo publico hoje nao e Instagram nem LinkedIn. O melhor primeiro valor e um fluxo de codigo simples e observavel:

1. Pedir para o GeminiClaw analisar `examples/demo-repo`. 2. Encontrar um arquivo especifico. 3. Ajustar um texto ou bug pequeno. 4. Mostrar o diff. 5. Rodar uma verificacao. 6. Preparar um commit.

Guia detalhado: [Docs/getting-started/first-value-code-edit.md](Docs/getting-started/first-value-code-edit.md)

Documentacao publica

Quickstart publico

  • Setup detalhado do Telegram: [Docs/getting-started/telegram-quickstart.md](Docs/getting-started/telegram-quickstart.md)
  • Troubleshooting do primeiro setup: [Docs/getting-started/telegram-troubleshooting.md](Docs/getting-started/telegram-troubleshooting.md)
  • Primeiro caso de uso com edicao de codigo: [Docs/getting-started/first-value-code-edit.md](Docs/getting-started/first-value-code-edit.md)
  • Como abrir o Studio local: [Docs/operate/studio.md](Docs/operate/studio.md) (inclui o novo card de Self-repair attention)
  • Checklist manual de release do onboarding: [Docs/release/onboarding-release-checklist.md](Docs/release/onboarding-release-checklist.md)
  • Checklist de release publica: [Docs/release/public-release-checklist.md](Docs/release/public-release-checklist.md)
  • Arquitetura atual: [ARCHITECT.md](ARCHITECT.md)

Integracoes avancadas opcionais

  • Instagram (fluxo separado): [Docs/setup/instagram.md](Docs/setup/instagram.md)
  • LinkedIn (fluxo separado): [Docs/setup/linkedin.md](Docs/setup/linkedin.md)
  • Google Workspace (Gmail, Calendar, Drive, Chat): [Docs/setup/workspace.md](Docs/setup/workspace.md)

Workspace no Telegram (multi-conta)

  • O Modo Secretária funciona por conta Workspace (não global).
  • Alertas agora mostram identificacao amigavel da conta (alias + provider + email), mantendo `accountId` para rastreio.
  • Quando um agente tem mais de uma conta, comandos da Secretária exibem selecao por botao para escolher a conta-alvo.
  • A ativacao de realtime do onboarding nao falha mais se o runtime ainda nao estiver inicializado; o sistema aplica configuracao e segue com degradacao controlada.

Comandos publicos

npm run setup              # Setup inicial interativo
npm run doctor             # Valida ambiente
npm run config:migrate     # Migra configuracao
npm run config:audit       # Audita configuracao
npm run start:telegram     # Inicia bot Telegram (producao)
npm run start:server       # Inicia API do control plane (porta 3001)
npm run start:dashboard    # Inicia GeminiClaw Studio
npm run tg:dev             # Telegram com hot-reload (desenvolvimento)
npm run cli                # REPL local
npm run wa:auth            # Autenticacao WhatsApp (opcional; requer install manual do Baileys)
npm run wa:dev             # WhatsApp (opcional; requer install manual do Baileys)
npm run watchdog           # Monitor de saude do runtime
npm run hooks:install      # Instala git hooks (post-commit auto-index)

Para habilitar o canal WhatsApp no build publico:

npm install @whiskeysockets/baileys

Comandos de qualidade:

npm run typecheck
npm run test:ci
npm run public:audit
npm run config:audit
npm run check:worktree-hygiene
npm run check:docs-sync
npm --prefix dashboard run build

O que fica salvo localmente

Por padrao, GeminiClaw grava dados em `./data`:

  • SQLite: `DATA_DIR/database.sqlite`
  • Logs: `DATA_DIR/logs/YYYY-MM-DD.log` (JSON estruturado, com redaction automatica de segredos). O caminho exato aparece no banner `📂 [LOG] Gravando em:` a cada boot do watchdog/telegram. Para acompanhar ao vivo: `tail -f data/logs/$(date -u +%Y-%m-%d).log | jq -r '"[\(.level)] \(.msg)"'`.
  • Runtime state: `DATA_DIR/runtime`
  • LanceDB: `DATA_DIR/lancedb`

Conversas do Telegram, memoria estruturada, memoria semantica e estado de runtime ficam locais no seu ambiente.

Integracoes avancadas

Instagram e LinkedIn continuam importantes, mas nao fazem parte do onboarding inicial. O fluxo publico recomendado e:

1. Telegram funcionando de primeira. 2. Primeiro caso de uso em `examples/demo-repo`. 3. Studio local opcional, ja preparado pelo `npm run setup`. 4. Integracoes avancadas em docs dedicadas.

Variaveis avancadas de ambiente: [config-examples/advanced-integrations.env.example](config-examples/advanced-integrations.env.example)

Resiliencia: quando o Telegram retorna 409 Conflict ("terminated by other getUpdates"), o bot desiste imediatamente em vez de ficar retentando (evita instancias duplicadas que corrompem respostas).

Documentos de texto (.md, .txt, .ts, .json, etc.) enviados via Telegram sao salvos em `tmp/` e o conteudo e passado inline ao modelo — sem base64 pesado. O path do arquivo e incluido na mensagem para que turnos futuros possam relê-lo com `read_file`.

Arquivos gerados por tools (audio, video, imagens) sao automaticamente entregues no chat do Telegram como anexo, mesmo quando o modelo tambem produz texto descritivo. O runtime inclui um mecanismo de rescue que detecta e entrega artefatos pendentes ao final de cada run, garantindo zero perda de mídia mesmo em caso de falha do modelo.

Boas praticas do projeto

  • Contribuicao: [CONTRIBUTING.md](CONTRIBUTING.md)
  • Codigo de conduta: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
  • Seguranca: [SECURITY.md](SECURITY.md)
  • Suporte: [SUPPORT.md](SUPPORT.md)