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 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

openclaw doctor
# or inspect config directly:
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", // must match the plugin's registered engine id
    },
    entries: {
      "lossless-claw": {
        enabled: true,
        // Plugin-specific config goes here (see the plugin's docs)
      },
    },
  },
}

# Como funciona

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

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:

# 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:

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:

assemble retorna um AssembleResult com:

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:

# ownsCompaction

ownsCompaction controla se a Compaction automática em tentativa integrada do Pi permanece ativada para a execução:

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

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",
    },
  },
}

# Relação com Compaction e memória

# 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

• Compaction - sumarização de conversas longas
• Contexto - como o contexto é criado para turnos de agente
• Arquitetura de Plugin - registro de Plugins de mecanismo de contexto
• Manifesto de Plugin - campos do manifesto de Plugin
• Plugins - visão geral de Plugins