Entendendo a Context Window no OpenClaw

Introdução

Imagine que você tem um assistente que só consegue se lembrar das últimas N páginas de uma conversa. Tudo antes disso — instruções anteriores, contexto que você deu, decisões tomadas — simplesmente desaparece. Isso é exatamente o que acontece quando você atinge o limite da context window de um modelo de linguagem.

A context window (ou janela de contexto) é uma das características mais importantes dos LLMs, mas também uma das menos compreendidas por usuários iniciantes. Ela define quanto texto o modelo pode considerar de uma vez: quanto maior, mais “memória de curto prazo” o assistente tem durante uma conversa. Entender esse conceito é fundamental para configurar o OpenClaw corretamente, gerenciar custos e garantir que o assistente tenha sempre as informações certas disponíveis.

O OpenClaw foi projetado com gerenciamento de contexto em mente. Com compactação automática, arquivos de memória persistentes e configurações granulares de context size, a plataforma resolve muitos dos problemas que context windows limitadas causariam de outra forma. Este guia explica como tudo isso funciona e como você pode ajustá-lo para suas necessidades.

Pré-requisitos

Para aproveitar este guia, é útil ter:

• OpenClaw instalado com pelo menos uma semana de uso
• Familiaridade básica com o arquivo config.yaml
• Noção de que custos de API são cobrados por tokens (veja guia de custos)
• O conceito de tokens — a unidade de medida que os LLMs usam para texto

O Que É a Context Window

A context window é o conjunto de textos que um modelo de linguagem pode “ver” ao mesmo tempo quando gera uma resposta. Inclui:

• As instruções do sistema (SOUL.md, USER.md, MEMORY.md)
• O histórico da conversa atual
• Qualquer documento ou contexto adicional fornecido
• A pergunta ou comando que você acabou de enviar

Pense como uma mesa de trabalho: tudo que está na mesa está disponível para consulta imediata. O que está em gavetas (memória de longo prazo em arquivos) precisa ser trazido explicitamente para a mesa antes de ser usado.

Tamanhos Típicos por Modelo

Calculando tokens em português:

• 1 palavra em português ≈ 1.3 tokens
• 1 página (500 palavras) ≈ 650 tokens
• 200k tokens ≈ 307 páginas ≈ 153.000 palavras

Para a maioria das conversas do dia a dia, nem 5% da context window é usada. Os problemas aparecem quando você trabalha com documentos longos, conversas extensas ou muitos arquivos de contexto simultaneamente.

Como o OpenClaw Gerencia Contexto

Arquitetura de Memória em Camadas

O OpenClaw usa uma abordagem em camadas para lidar com a limitação de context window:

Camada 1: Context Ativo (até 200k tokens)
├── SOUL.md (personalidade) — sempre presente
├── USER.md (sobre você) — sempre presente
├── MEMORY.md (memória resumida) — sempre presente
└── Histórico da conversa atual

Camada 2: Memória de Longo Prazo (ilimitada)
├── ~/clawd/memory/2026-01-15.md
├── ~/clawd/memory/2026-01-16.md
└── ... (logs diários)

Camada 3: Documentos e Contexto Externo
├── Arquivos enviados na conversa
└── Resultados de ferramentas (web search, etc.)

O agente decide o que trazer da Camada 2 e 3 para o context ativo conforme necessário, como um humano que vai até a gaveta buscar documentos relevantes para a conversa atual.

Compactação Automática

Quando o histórico da conversa fica longo, o OpenClaw compacta automaticamente as partes mais antigas:

agents:
  defaults:
    compaction:
      mode: "auto"           # auto, manual, aggressive
      threshold: 0.8         # Compacta quando 80% do contexto está cheio
      summaryLength: "short" # short, medium, detailed

No modo auto, o processo é:

1. Conversa atinge 80% do limite de contexto
2. Partes mais antigas são resumidas em um bloco compacto
3. O resumo substitui o histórico detalhado
4. Espaço é liberado para novas mensagens

O resumo tenta preservar informações importantes (decisões tomadas, informações fornecidas, tarefas concluídas) enquanto descarta detalhes menos relevantes.

Configurando a Context Window

Configuração Básica

No config.yaml:

agents:
  defaults:
    contextTokens: 50000      # Máximo de tokens no contexto ativo
    reservedForResponse: 4000 # Reservado para a resposta do modelo
    compaction:
      mode: "auto"
      threshold: 0.75

Configurações por Caso de Uso

Para conversas casuais (econômico):

agents:
  defaults:
    contextTokens: 20000
    compaction:
      mode: "aggressive"  # Compacta mais agressivamente
      threshold: 0.6

Para análise de documentos longos:

agents:
  defaults:
    contextTokens: 150000  # Usa mais contexto
    compaction:
      mode: "manual"       # Você controla quando compactar

Para tarefas de código (precisa lembrar muito contexto):

agents:
  defaults:
    contextTokens: 100000
    compaction:
      mode: "auto"
      threshold: 0.85
      summaryLength: "detailed"  # Preserva mais detalhes no resumo

Verificando Uso de Contexto

# Ver uso atual de tokens
openclaw status --context

# Saída exemplo:
# Context Window: 47,823 / 50,000 tokens (95.6%)
# SOUL.md: 1,250 tokens
# USER.md: 890 tokens
# MEMORY.md: 2,100 tokens
# Conversation: 43,583 tokens
# Available: 2,177 tokens

# Forçar compactação manual
openclaw context compact

# Ver histórico de compactações
openclaw context history

Impacto no Custo e Performance

A Equação de Custo

Cada token no contexto custa dinheiro — tanto os que você envia (input) quanto os da resposta (output):

Custo por mensagem = (tokens no contexto + tokens da pergunta) × preço input
                   + tokens da resposta × preço output

Exemplo com Claude Sonnet:

• 50.000 tokens no contexto
• Pergunta de 100 tokens
• Resposta de 500 tokens

Custo = (50.100 tokens × $3/1M) + (500 tokens × $15/1M)
      = $0.15 + $0.0075
      = ~$0.16 por mensagem

Com contexto de 5.000 tokens:

Custo = (5.100 × $3/1M) + (500 × $15/1M)
      = $0.015 + $0.0075
      = ~$0.02 por mensagem

Diferença: 8x mais barato com contexto menor. Por isso, limitar o contexto ao necessário é uma das formas mais eficazes de controlar custos.

Latência vs. Qualidade

Estratégias para Gerenciar Contexto Eficientemente

Arquivos de Memória como Extensão

Em vez de depender apenas do histórico da conversa, use arquivos de memória permanentes:

# ~/clawd/MEMORY.md — Memória sempre disponível

## Projetos Ativos
- Projeto Alpha: landing page para cliente X, prazo 30/03
- Projeto Beta: análise de dados para relatório Q1

## Decisões Importantes
- 2026-01-15: Decidimos usar React ao invés de Vue para o frontend
- 2026-02-01: Nova política: todos PRs precisam de 2 aprovações

## Contexto de Longo Prazo
- Cliente X prefere comunicação formal, sem emojis
- Sistema de pagamento usa Stripe, não PagSeguro

Tudo no MEMORY.md está sempre disponível sem ocupar espaço do histórico de conversa.

Compactação Manual Proativa

Quando perceber que a conversa está ficando longa, compacte antes de atingir o limite:

# Compactar e continuar
openclaw context compact --keep-last 10

# Iniciar nova sessão preservando contexto importante
openclaw context save --name "projeto-alpha-contexto"
openclaw context new
openclaw context load "projeto-alpha-contexto"

Uso Eficiente em Conversas Longas

Para projetos extensos que evoluem ao longo de semanas:

1. Final de cada sessão: Peça ao assistente para resumir o que foi discutido e salvar no MEMORY.md
2. Início de nova sessão: Mencione explicitamente o projeto para o assistente buscar o contexto relevante
3. Documentação de decisões: Configure o heartbeat para extrair decisões importantes da memória diária e consolidar no MEMORY.md

"Resumo de hoje: Decidimos que [X], próximos passos são [Y].
Por favor, salve isso no MEMORY.md sob o projeto Alpha."

Configuração Avançada

Context Window Dinâmico

Ajuste o contexto automaticamente baseado no tipo de tarefa:

agents:
  defaults:
    contextTokens: 30000

  profiles:
    document-analysis:
      contextTokens: 180000
      compaction:
        mode: "manual"

    code-review:
      contextTokens: 100000
      compaction:
        mode: "auto"
        threshold: 0.9

    quick-chat:
      contextTokens: 10000
      compaction:
        mode: "aggressive"

Ative um perfil por comando:

openclaw context profile document-analysis

Erros Comuns e Soluções

Boas Práticas

• Separe memória persistente do histórico: O MEMORY.md é para informações que você quer disponíveis em qualquer sessão. O histórico da conversa é para o contexto imediato de uma sessão específica. Cuide para não misturar os dois.

• Monitore o uso de context antes de tarefas longas: Antes de processar um documento grande, verifique openclaw status --context. Se o contexto já está 70%+ cheio, compacte ou inicie nova sessão.

• Use compactação como feature, não limitação: A compactação bem configurada permite conversas virtualmente ilimitadas. Configure um summaryLength adequado para preservar as informações que importam.

• Documente decisões em tempo real: Não espere o fim de uma conversa longa para salvar contexto. Peça ao assistente para registrar decisões importantes no MEMORY.md à medida que forem tomadas.

• Calibre o contextTokens para seu caso de uso: Não existe valor certo para todos. Comece com 50.000, monitore o comportamento por uma semana e ajuste. Menos não é sempre melhor se causar perda de contexto importante.

• Considere o SOUL.md no orçamento de contexto: O SOUL.md é carregado em todas as sessões. Um SOUL.md de 10.000 tokens ocupa sempre 10.000 tokens do seu budget de contexto. Seja conciso onde puder.

Perguntas Frequentes

Por que o assistente “esqueceu” algo que eu disse 2 horas atrás? Provavelmente a compactação automática resumiu essa parte da conversa. Se a informação era importante, ela deveria estar no MEMORY.md. Configure o assistente para salvar automaticamente informações importantes: “Sempre que eu mencionar uma decisão de projeto, salve no MEMORY.md.”

Usar contexto maior sempre dá resultados melhores? Não necessariamente. Com contexto muito grande, o modelo pode ter dificuldade em identificar o que é mais relevante para a pergunta atual. Para perguntas simples, contexto menor pode dar respostas mais diretas e focadas. Para análise de documentos complexos, contexto maior é claramente melhor.

Como saber se a compactação está me custando informações importantes? Use openclaw context history para ver os resumos gerados. Se você perceber que decisões ou contexto importante foi perdido, mude para summaryLength: "detailed" ou configure o assistente para salvar informações críticas explicitamente antes da compactação.

Qual o impacto de contextos enormes (100k+) na velocidade? Significativo. Com 100k tokens de contexto, a latência pode ser 5-10x maior que com 10k tokens. O modelo precisa processar cada token do contexto para cada resposta. Para o uso diário, 30-50k tokens é geralmente o equilíbrio certo entre memória e velocidade.

Posso ter context windows diferentes para canais diferentes? Sim! Configure por canal:

channels:
  whatsapp:
    agent:
      contextTokens: 20000  # Mobile, respostas rápidas
  telegram:
    agent:
      contextTokens: 80000  # Pode ser mais detalhado

Próximos Passos

• Guia de Custos — Entenda como tokens impactam sua fatura
• Guia de Performance — Otimize velocidade além do contexto
• Glossário: Tokens — Entenda a fundo como tokens funcionam
• Glossário: LLM — Como os modelos de linguagem processam texto
• Automação Avançada — Gerencie contexto em pipelines automatizados