​

Mecanismo 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 mecanismo de contexto

# Instalar pelo npm
openclaw plugins install @martian-engineering/lossless-claw

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

// openclaw.json
{
  plugins: {
    slots: {
      contextEngine: "lossless-claw", // deve corresponder ao id do mecanismo registrado pelo 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 — chamado quando uma nova mensagem é adicionada à sessão. O mecanismo pode armazenar ou indexar a mensagem em seu próprio armazenamento de dados.
2. Assemble — chamado antes de cada execução do modelo. O mecanismo retorna um conjunto ordenado de mensagens (e um systemPromptAddition opcional) que cabe dentro do orçamento de tokens.
3. Compact — chamado quando a janela de contexto está cheia, ou quando o usuário executa /compact. O mecanismo resume o histórico mais antigo para liberar espaço.
4. After turn — chamado após a conclusão de uma execução. O mecanismo pode persistir estado, disparar compactação em segundo plano ou atualizar índices.

​

Ciclo de vida de subagentes (opcional)

• onSubagentEnded — faz limpeza quando uma sessão de subagente é concluída ou varrida.

​

Adição ao prompt do sistema

​

O mecanismo legado

• Ingest: no-op (o gerenciador de sessão lida diretamente com a persistência de mensagens).
• Assemble: pass-through (o pipeline existente sanitize → validate → limit no runtime cuida da montagem do contexto).
• Compact: delega para a compactação integrada baseada em resumo, que cria um único resumo das mensagens mais antigas e mantém intactas as mensagens recentes.
• After turn: no-op.

​

Mecanismos de plugin

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

    async ingest({ sessionId, message, isHeartbeat }) {
      // Armazene a mensagem no seu armazenamento de dados
      return { ingested: true };
    },

    async assemble({ sessionId, messages, tokenBudget }) {
      // Retorne mensagens que cabem no orçamento
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: "Use lcm_grep to search history...",
      };
    },

    async compact({ sessionId, force }) {
      // Resuma o contexto mais antigo
      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 mecanismo do total de tokens no contexto montado. O OpenClaw usa isso para decisões de limiar de compactação e relatórios de diagnóstico.
• systemPromptAddition (opcional, string) — prefixado ao prompt do sistema.

​

ownsCompaction

• true — o mecanismo controla o comportamento de compactação. O OpenClaw desativa a compactação automática integrada do Pi para essa execução, e a implementação compact() do mecanismo é 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 compactação automática integrada do Pi ainda pode ser executada durante a execução do prompt, mas o método compact() do mecanismo 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 delegante — 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: {
      // Seleciona o mecanismo de contexto ativo. Padrão: "legacy".
      // Defina como um id de plugin para usar um mecanismo de plugin.
      contextEngine: "legacy",
    },
  },
}

​

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

• Compactação é uma das responsabilidades do mecanismo de contexto. O mecanismo legado delega para o resumo integrado do OpenClaw. Mecanismos de plugin podem implementar qualquer estratégia de compactação (resumos em DAG, recuperação vetorial etc.).
• Plugins de memória (plugins.slots.memory) são separados dos mecanismos de contexto. Plugins de memória fornecem busca/recuperação; mecanismos de contexto controlam o que o modelo vê. Eles podem funcionar juntos — um mecanismo de contexto pode usar dados de plugin de memória durante a montagem.
• Poda de sessão (remover resultados antigos de ferramentas da memória) ainda é executada independentemente de qual mecanismo de contexto esteja ativo.

​

Dicas

• Use openclaw doctor para verificar se o seu mecanismo está sendo carregado corretamente.
• Ao alternar de mecanismo, sessões existentes continuam com o histórico atual. O novo mecanismo assume para execuções futuras.
• Erros do mecanismo são registrados e exibidos em diagnósticos. Se um mecanismo de plugin falhar ao registrar ou se o id de mecanismo selecionado não puder ser resolvido, o OpenClaw não faz fallback automaticamente; 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 é construído para turnos do agente
• Arquitetura de Plugins — registro de plugins de mecanismo de contexto
• Compactação — resumindo conversas longas