Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Um mecanismo de contexto controla como o OpenClaw cria o contexto do modelo para cada execução: quais mensagens incluir, como resumir o histórico mais antigo e como gerenciar o contexto nos limites de subagentes. O OpenClaw vem com um mecanismo legacy integrado e o usa por padrão - a maioria dos usuários nunca precisa mudar isso. Instale e selecione um mecanismo de Plugin apenas quando quiser um comportamento diferente de montagem, Compaction ou recuperação entre sessões.

​
Início rápido

1

Verifique qual mecanismo está ativo

openclaw doctor
# or inspect config directly:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'
2

Instale um mecanismo de Plugin

Plugins de mecanismo de contexto são instalados como qualquer outro Plugin do OpenClaw.
openclaw plugins install @martian-engineering/lossless-claw
3

Ative e selecione o mecanismo

// openclaw.json
{
  plugins: {
    slots: {
      contextEngine: "lossless-claw", // must match the plugin's registered engine id
    },
    entries: {
      "lossless-claw": {
        enabled: true,
        // Plugin-specific config goes here (see the plugin's docs)
      },
    },
  },
}
Reinicie o Gateway depois de instalar e configurar.
4

Volte para legacy (opcional)

Defina contextEngine como "legacy" (ou remova a chave por completo - "legacy" é o padrão).

​
Como funciona

Sempre que o OpenClaw executa um prompt de modelo, o mecanismo de contexto participa em quatro pontos do ciclo de vida:
Chamado quando uma nova mensagem é adicionada à sessão. O mecanismo pode armazenar ou indexar a mensagem em seu próprio armazenamento de dados.
Chamado antes de cada execução do modelo. O mecanismo retorna um conjunto ordenado de mensagens (e um systemPromptAddition opcional) que cabe no orçamento de tokens.
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.
Chamado depois que uma execução é concluída. O mecanismo pode persistir o estado, acionar Compaction em segundo plano ou atualizar índices.
Para o harness Codex não ACP incluído, o OpenClaw aplica o mesmo ciclo de vida projetando o contexto montado nas instruções de desenvolvedor do Codex e no prompt da rodada atual. O Codex ainda controla seu histórico de thread nativo e seu compactador nativo.

​
Ciclo de vida de subagente (opcional)

O OpenClaw chama dois hooks opcionais de ciclo de vida de subagente:
​
prepareSubagentSpawn
method
Prepare o estado de contexto compartilhado antes que uma execução filha comece. O hook recebe chaves de sessão pai/filha, contextMode (isolated ou fork), ids/arquivos de transcrição disponíveis e TTL opcional. Se ele retornar um identificador de rollback, o OpenClaw o chama quando a criação falha depois que a preparação é bem-sucedida.
​
onSubagentEnded
method
Limpe quando uma sessão de subagente for concluída ou varrida.

​
Adição ao prompt do sistema

O método assemble pode retornar uma string systemPromptAddition. O OpenClaw a prefixa ao prompt do sistema da execução. Isso permite que mecanismos injetem orientação dinâmica de recuperação, instruções de busca ou dicas sensíveis ao contexto sem exigir arquivos estáticos no workspace.

​
O mecanismo legacy

O mecanismo legacy integrado preserva o comportamento original do OpenClaw:
  • Ingestão: sem operação (o gerenciador de sessões lida diretamente com a persistência de mensagens).
  • Montagem: passagem direta (o pipeline existente de sanitização → validação → limite no runtime lida com a montagem de contexto).
  • Compactar: delega para a Compaction de sumarização integrada, que cria um único resumo das mensagens mais antigas e mantém as mensagens recentes intactas.
  • Após a rodada: sem operação.
O mecanismo legacy não registra ferramentas nem fornece um systemPromptAddition. Quando nenhum plugins.slots.contextEngine está definido (ou ele está definido como "legacy"), esse mecanismo é usado automaticamente.

​
Mecanismos de Plugin

Um Plugin pode registrar um mecanismo de contexto usando a API de Plugin: 
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function register(api) {
  api.registerContextEngine("my-engine", (ctx) => ({
    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 };
    },
  }));
}
A factory ctx inclui valores opcionais config, agentDir e workspaceDir para que Plugins possam inicializar estado por agente ou por workspace antes que o primeiro hook de ciclo de vida seja executado. Depois, ative-o na configuração: 
{
  plugins: {
    slots: {
      contextEngine: "my-engine",
    },
    entries: {
      "my-engine": {
        enabled: true,
      },
    },
  },
}

​
A interface ContextEngine

Membros obrigatórios:
MembroTipoFinalidade
infoPropriedadeId, nome, versão do mecanismo e se ele controla Compaction
ingest(params)MétodoArmazenar uma única mensagem
assemble(params)MétodoCriar contexto para uma execução de modelo (retorna AssembleResult)
compact(params)MétodoResumir/reduzir contexto
assemble retorna um AssembleResult com:
​
messages
Message[]
obrigatório
As mensagens ordenadas a enviar ao modelo.
​
estimatedTokens
number
obrigatório
A estimativa do mecanismo para o total de tokens no contexto montado. O OpenClaw usa isso para decisões de limiar de Compaction e relatórios de diagnóstico.
​
systemPromptAddition
string
Prefixado ao prompt do sistema.
​
promptAuthority
"assembled" | "preassembly_may_overflow"
Controla qual estimativa de tokens o executor usa para pré-verificações preventivas de overflow. O padrão é "assembled", o que significa que apenas a estimativa do prompt montado é verificada - apropriado para mecanismos que retornam um contexto em janela e autocontido. Defina como "preassembly_may_overflow" apenas quando sua visão montada puder ocultar risco de overflow na transcrição subjacente; então o executor usa o máximo entre a estimativa montada e a estimativa do histórico da sessão pré-montagem (sem janela) ao decidir se deve compactar preventivamente. De qualquer forma, as mensagens que você retorna ainda são o que o modelo vê - promptAuthority afeta apenas a pré-verificação.
compact retorna um CompactResult. Quando a Compaction rotaciona a transcrição ativa, result.sessionId e result.sessionFile identificam a sessão sucessora que a próxima nova tentativa ou rodada deve usar. Membros opcionais:
MembroTipoFinalidade
bootstrap(params)MétodoInicializar o estado do mecanismo para uma sessão. Chamado uma vez quando o mecanismo vê uma sessão pela primeira vez (por exemplo, importar histórico).
ingestBatch(params)MétodoIngerir uma rodada concluída como um lote. Chamado depois que uma execução é concluída, com todas as mensagens daquela rodada de uma só vez.
afterTurn(params)MétodoTrabalho de ciclo de vida pós-execução (persistir estado, acionar Compaction em segundo plano).
prepareSubagentSpawn(params)MétodoConfigurar estado compartilhado para uma sessão filha antes que ela comece.
onSubagentEnded(params)MétodoLimpar depois que um subagente termina.
dispose()MétodoLiberar recursos. Chamado durante o desligamento do Gateway ou recarregamento de Plugin - não por sessão.

​
ownsCompaction

ownsCompaction controla se a Compaction automática em tentativa integrada do Pi permanece ativada para a execução:
O mecanismo controla o comportamento de Compaction. O OpenClaw desativa a Compaction automática integrada do Pi para essa execução, e a implementação compact() do mecanismo é responsável por /compact, Compaction de recuperação de overflow e qualquer Compaction proativa que ele queira fazer em afterTurn(). O OpenClaw ainda pode executar a proteção de overflow pré-prompt; quando ela prevê que a transcrição completa excederá o limite, o caminho de recuperação chama o compact() do mecanismo ativo antes de enviar outro prompt.
A Compaction 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 de overflow.
ownsCompaction: false não significa que o OpenClaw volta automaticamente para o caminho de Compaction do mecanismo legacy.
Isso significa que há dois padrões válidos de Plugin:
Implemente seu próprio algoritmo de Compaction e defina ownsCompaction: true.
Um compact() sem operação é inseguro para um mecanismo ativo sem controle próprio porque desativa o caminho normal de Compaction de /compact e recuperação de overflow para esse slot de mecanismo.

​
Referência de configuração

{
  plugins: {
    slots: {
      // Select the active context engine. Default: "legacy".
      // Set to a plugin id to use a plugin engine.
      contextEngine: "legacy",
    },
  },
}
O slot é exclusivo em tempo de execução - apenas um mecanismo de contexto registrado é resolvido para uma determinada execução ou operação de Compaction. Outros Plugins kind: "context-engine" ativados ainda podem carregar e executar seu código de registro; plugins.slots.contextEngine apenas seleciona qual id de mecanismo registrado o OpenClaw resolve quando precisa de um mecanismo de contexto.
Desinstalação de Plugin: quando você desinstala o Plugin selecionado no momento como plugins.slots.contextEngine, o OpenClaw redefine o slot de volta para o padrão (legacy). O mesmo comportamento de redefinição se aplica a plugins.slots.memory. Nenhuma edição manual de configuração é necessária.

​
Relação com Compaction e memória

Compaction é uma responsabilidade do mecanismo de contexto. O mecanismo legado delega para a sumarização integrada do OpenClaw. Mecanismos de Plugin podem implementar qualquer estratégia de Compaction (sumarizações 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 trabalhar juntos - um mecanismo de contexto pode usar dados de Plugin de memória durante a montagem. Mecanismos de Plugin que desejam o caminho de prompt da memória ativa devem preferir buildMemorySystemPromptAddition(...) de openclaw/plugin-sdk/core, que converte as seções de prompt da memória ativa em um systemPromptAddition pronto para ser prefixado. Se um mecanismo precisar de controle de nível mais baixo, ele ainda pode extrair linhas brutas de openclaw/plugin-sdk/memory-host-core via buildActiveMemoryPromptSection(...).
O corte de resultados antigos de ferramentas em memória continua sendo executado independentemente de qual mecanismo de contexto esteja ativo.

​
Dicas

  • Use openclaw doctor para verificar se seu mecanismo está carregando corretamente.
  • Se alternar mecanismos, as sessões existentes continuam com o histórico atual delas. O novo mecanismo assume as execuções futuras.
  • Erros de mecanismo são registrados e exibidos nos diagnósticos. Se um mecanismo de Plugin não conseguir se registrar ou o id do mecanismo selecionado não puder ser resolvido, o OpenClaw não faz fallback automaticamente; as execuções falham até você corrigir o Plugin ou alterar plugins.slots.contextEngine de volta para "legacy".
  • Para desenvolvimento, use openclaw plugins install -l ./my-engine para vincular um diretório local de Plugin sem copiar.

​
Relacionados