​

Motor de contexto

​

Início rápido

openclaw doctor
# ou inspecione a configuração diretamente:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

​

Instalando um plugin de motor de contexto

# Instalar a partir do npm
openclaw plugins install @martian-engineering/lossless-claw

# Ou instalar a partir de um caminho local (para desenvolvimento)
openclaw plugins install -l ./my-context-engine

// openclaw.json
{
  plugins: {
    slots: {
      contextEngine: "lossless-claw", // deve corresponder ao id de motor registrado do plugin
    },
    entries: {
      "lossless-claw": {
        enabled: true,
        // A configuração específica do plugin vai aqui (consulte a documentação do plugin)
      },
    },
  },
}

​

Como funciona

1. Ingestão — chamada quando uma nova mensagem é adicionada à sessão. O motor pode armazenar ou indexar a mensagem em seu próprio armazenamento de dados.
2. Montagem — chamada antes de cada execução do modelo. O motor retorna um conjunto ordenado de mensagens (e um systemPromptAddition opcional) que cabe dentro do orçamento de tokens.
3. Compactação — chamada quando a janela de contexto está cheia, ou quando o usuário executa /compact. O motor resume o histórico antigo para liberar espaço.
4. Após o turno — chamada depois que uma execução é concluída. O motor pode persistir o estado, disparar compactação em segundo plano ou atualizar índices.

​

Ciclo de vida do subagente (opcional)

• onSubagentEnded — limpa quando uma sessão de subagente é concluída ou removida.

​

Adição ao prompt do sistema

​

O motor legado

• Ingestão: no-op (o gerenciador de sessão lida diretamente com a persistência de mensagens).
• Montagem: passagem direta (o pipeline existente sanitize → validate → limit no runtime lida com a montagem do contexto).
• Compactação: delega para a compactação de sumarização integrada, que cria um único resumo de mensagens antigas e mantém as mensagens recentes intactas.
• Após o turno: no-op.

​

Motores de plugin

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function register(api) {
  api.registerContextEngine("my-engine", () => ({
    info: {
      id: "my-engine",
      name: "My Context Engine",
      ownsCompaction: true,
    },

    async ingest({ sessionId, message, isHeartbeat }) {
      // Store the message in your data store
      return { ingested: true };
    },

    async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) {
      // Return messages that fit the budget
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },

    async compact({ sessionId, force }) {
      // Summarize older context
      return { ok: true, compacted: true };
    },
  }));
}

{
  plugins: {
    slots: {
      contextEngine: "my-engine",
    },
    entries: {
      "my-engine": {
        enabled: true,
      },
    },
  },
}

​

A interface ContextEngine

• messages — as mensagens ordenadas a serem enviadas ao modelo.
• estimatedTokens (obrigatório, number) — a estimativa do motor para o total de tokens no contexto montado. O OpenClaw usa isso para decisões de limite de compactação e relatórios de diagnóstico.
• systemPromptAddition (opcional, string) — anteposto ao prompt do sistema.

​

ownsCompaction

• true — o motor é responsável pelo comportamento de compactação. O OpenClaw desativa a auto-compactação integrada do Pi para essa execução, e a implementação de compact() do motor é responsável por /compact, compactação de recuperação por overflow e qualquer compactação proativa que ele queira fazer em afterTurn().
• false ou não definido — a auto-compactação integrada do Pi ainda pode ser executada durante a execução do prompt, mas o método compact() do motor ativo ainda é chamado para /compact e recuperação por overflow.

• Modo proprietário — implemente seu próprio algoritmo de compactação e defina ownsCompaction: true.
• Modo de delegação — defina ownsCompaction: false e faça compact() chamar delegateCompactionToRuntime(...) de openclaw/plugin-sdk/core para usar o comportamento de compactação integrado do OpenClaw.

​

Referência de configuração

{
  plugins: {
    slots: {
      // Selecione o motor de contexto ativo. Padrão: "legacy".
      // Defina um id de plugin para usar um motor de plugin.
      contextEngine: "legacy",
    },
  },
}

​

Relação com compactação e memória

• Compactação é uma das responsabilidades do motor de contexto. O motor legado delega para a sumarização integrada do OpenClaw. Motores de plugin podem implementar qualquer estratégia de compactação (resumos DAG, recuperação vetorial etc.).
• Plugins de memória (plugins.slots.memory) são separados dos motores de contexto. Plugins de memória fornecem busca/recuperação; motores de contexto controlam o que o modelo vê. Eles podem trabalhar juntos — um motor de contexto pode usar dados do plugin de memória durante a montagem. Motores de plugin que quiserem o caminho de prompt de memória ativo devem preferir buildMemorySystemPromptAddition(...) de openclaw/plugin-sdk/core, que converte as seções do prompt de memória ativo em um systemPromptAddition pronto para ser anteposto. Se um motor precisar de controle de nível mais baixo, ele ainda pode extrair linhas brutas de openclaw/plugin-sdk/memory-host-core via buildActiveMemoryPromptSection(...).
• Poda de sessão (remoção de resultados antigos de ferramentas da memória) ainda é executada independentemente de qual motor de contexto está ativo.

​

Dicas

• Use openclaw doctor para verificar se seu motor está sendo carregado corretamente.
• Se estiver alternando motores, as sessões existentes continuam com seu histórico atual. O novo motor assume para execuções futuras.
• Erros do motor são registrados em logs e exibidos em diagnósticos. Se um motor de plugin falhar ao registrar ou se o id de motor selecionado não puder ser resolvido, o OpenClaw não faz fallback automático; as execuções falham até que você corrija o plugin ou altere plugins.slots.contextEngine de volta para "legacy".
• Para desenvolvimento, use openclaw plugins install -l ./my-engine para vincular um diretório de plugin local sem copiar.

​

Relacionado

• Contexto — como o contexto é criado para os turnos do agente
• Arquitetura de plugins — registrando plugins de motor de contexto
• Compactação — resumindo conversas longas