Mecanismo de contexto

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 entre limites de subagentes.

O OpenClaw inclui um mecanismo legacy integrado e o utiliza por padrão. Instale e selecione um mecanismo de Plugin somente quando quiser um comportamento diferente de montagem, Compaction ou recuperação entre sessões.

Início rápido

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

openclaw plugins install @martian-engineering/lossless-claw

openclaw plugins install -l ./my-context-engine

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

Como funciona

Sempre que o OpenClaw executa um prompt de modelo, o mecanismo de contexto participa em quatro pontos do ciclo de vida:

Os mecanismos também podem implementar um método maintain() opcional para manutenção da transcrição (reescritas seguras por meio de runtimeContext.rewriteTranscriptEntries()) após a inicialização, um turno bem-sucedido ou a Compaction. Defina info.turnMaintenanceMode: "background" para executá-lo como trabalho adiado em vez de bloquear a resposta.

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 do turno atual. O Codex continua controlando seu histórico de thread nativo e seu compactador nativo.

Ciclo de vida do subagente (opcional)

O OpenClaw chama dois hooks opcionais do ciclo de vida de subagentes:

Adição ao prompt do sistema

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

O mecanismo legado

O mecanismo legacy integrado preserva o comportamento original do OpenClaw:

• Ingestão: nenhuma operação (o gerenciador de sessões cuida diretamente da persistência das mensagens).
• Montagem: passagem direta (o pipeline existente de sanitização → validação → limitação no runtime cuida da montagem do contexto).
• Compaction: delega para a Compaction de sumarização integrada, que cria um único resumo das mensagens mais antigas e mantém intactas as mensagens recentes.
• Após o turno: nenhuma operação.

O mecanismo legado não registra ferramentas nem fornece um systemPromptAddition.

Quando nenhum plugins.slots.contextEngine está definido (ou está definido como "legacy"), esse mecanismo é usado automaticamente.

Mecanismos de Plugin

Um Plugin pode registrar um mecanismo de contexto usando a API de Plugin:

  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 }) {      // Armazene a mensagem em seu repositório de dados      return { ingested: true };    },     async assemble({      sessionId,      sessionKey,      messages,      tokenBudget,      availableTools,      citationsMode,    }) {      // Retorne mensagens que caibam no orçamento      return {        messages: buildContext(messages, tokenBudget),        estimatedTokens: countTokens(messages),        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // Resuma o contexto mais antigo      return { ok: true, compacted: true };    },  }));}

O ctx da fábrica inclui valores opcionais config, agentDir e workspaceDir para que os Plugins possam inicializar o estado por agente ou por espaço de trabalho antes da execução do primeiro hook do ciclo de vida.

Em seguida, ative-o na configuração:

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

A interface ContextEngine

Membros obrigatórios:

assemble retorna um AssembleResult com:

compact retorna um CompactResult. Quando a Compaction altera a identidade da sessão ativa, result.sessionTarget (um ContextEngineSessionTarget tipado que contém a identidade da sessão e o escopo do repositório) identifica a sessão sucessora que a próxima repetição ou o próximo turno deve usar; result.sessionId espelha o id sucessor.

Membros opcionais:

Configurações de runtime

Os hooks do ciclo de vida executados dentro do OpenClaw recebem um objeto runtimeSettings opcional. Ele é uma superfície de API interna versionada e somente leitura entre produtor e consumidor: o OpenClaw o produz para o mecanismo de contexto selecionado, e o mecanismo de contexto o consome dentro dos hooks do ciclo de vida. Ele não é renderizado diretamente para os usuários e não cria uma superfície dedicada de relatórios.

• schemaVersion: atualmente 1
• runtime: host do OpenClaw, modo do runtime (normal, fallback ou degraded) e ids opcionais do harness/runtime
• contextEngineSelection: id do mecanismo de contexto selecionado e origem da seleção
• executionHost: id e rótulo do host para a superfície que invoca o hook
• model: modelo solicitado, modelo resolvido, provedor e família de modelos opcional
• limits: orçamento de tokens do prompt e máximo de tokens de saída, quando conhecidos
• diagnostics: códigos fechados de motivo de fallback e de degradação, quando conhecidos

Os campos que podem ser desconhecidos são representados como null; campos discriminadores, como modo de runtime e origem da seleção, permanecem não anuláveis. Mecanismos mais antigos continuam compatíveis: se um mecanismo legado estrito rejeitar runtimeSettings como uma propriedade desconhecida, o OpenClaw repetirá a chamada de ciclo de vida sem ela, em vez de colocar o mecanismo em quarentena.

Requisitos do host

Os mecanismos de contexto podem declarar requisitos de capacidade do host em info.hostRequirements. O OpenClaw verifica esses requisitos antes de iniciar a operação e adota uma postura de falha fechada, com um erro descritivo, quando o runtime selecionado não consegue atendê-los.

Para execuções de agente, declare assemble-before-prompt quando o mecanismo precisar controlar o prompt efetivo do modelo por meio de assemble():

info: {  id: "my-context-engine",  name: "My Context Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "Use o runtime nativo do Codex ou o runtime incorporado do OpenClaw, ou selecione o mecanismo de contexto legado.",    },  },}

As execuções de agente do Codex nativo e do OpenClaw incorporado atendem a assemble-before-prompt. Backends de CLI genéricos não atendem, portanto, mecanismos que exigem essa capacidade são rejeitados antes que o processo da CLI seja iniciado.

Isolamento de falhas

O OpenClaw isola o mecanismo do plugin selecionado do fluxo principal de respostas. Se um mecanismo não legado estiver ausente, falhar na validação de contrato, lançar uma exceção durante a criação da fábrica ou lançar uma exceção em um método de ciclo de vida, o OpenClaw colocará esse mecanismo em quarentena no processo atual do Gateway e rebaixará o trabalho do mecanismo de contexto para o mecanismo legacy integrado. O erro é registrado com a operação que falhou, para que o operador possa reparar, atualizar ou desativar o plugin sem que o agente deixe de responder.

As falhas de requisitos do host são diferentes: quando um mecanismo declara que um runtime não possui uma capacidade obrigatória, o OpenClaw adota uma postura de falha fechada antes de iniciar a execução. Isso protege mecanismos que corromperiam o estado se fossem executados em um host sem suporte.

ownsCompaction

ownsCompaction controla se a compactação automática integrada durante a tentativa do runtime do OpenClaw permanece habilitada para a execução:

Isso significa que há dois padrões válidos de plugin:

Um compact() que não realiza nenhuma operação é inseguro para um mecanismo ativo não proprietário, pois desabilita o fluxo normal de compactação de /compact e de recuperação de estouro para o slot desse mecanismo.

Referência de configuração

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

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

Dicas

• Use openclaw doctor para verificar se seu mecanismo está sendo carregado corretamente.
• Ao trocar de mecanismo, as sessões existentes continuam com o histórico atual. O novo mecanismo assume as execuções futuras.
• Os erros do mecanismo são registrados, e o mecanismo do plugin selecionado é colocado em quarentena no processo atual do Gateway. O OpenClaw retorna a legacy para os turnos do usuário, permitindo que as respostas continuem, mas você ainda deve reparar, atualizar, desativar ou desinstalar o plugin com defeito.
• Para desenvolvimento, use openclaw plugins install -l ./my-engine para vincular um diretório de plugin local sem copiá-lo.

Relacionados

• Compaction — sumarização de conversas longas
• Contexto — como o contexto é criado para os turnos do agente
• Arquitetura de plugins — registro de plugins de mecanismo de contexto
• Manifesto do plugin — campos do manifesto do plugin
• Plugins — visão geral dos plugins