Este documento fornece uma análise detalhada da estrutura completa do System Prompt enviado pelo OpenClaw Agent para o LLM.
Versão:
v2.1
Data de Atualização:
2026-03-05
Diagrama Geral da Arquitetura
Navegação Rápida (TL;DR)
Leitura obrigatória para iniciantes:
- Camada 7 (Arquivos do Workspace) - Arquivos de configuração que você pode editar diretamente.
- Camada 8 (Bootstrap Hook) - Onde você pode escrever scripts para injetar conteúdo dinamicamente.
- As outras camadas são geradas automaticamente pelo framework; apenas entenda-as.
Necessidades comuns:
- Quer definir a identidade do Agent? → Edite o IDENTITY.md na Camada 7.
- Quer adicionar documentação do projeto? → Use o Hook bootstrap-extra-files na Camada 8.
- Quer injetar contexto em tempo real? → Use o Hook before_prompt_build na Camada 8.
- Quer controlar o tamanho do arquivo? → Ajuste a configuração bootstrapMaxChars.
Camada 1: Núcleo do Framework OpenClaw
Analogia
Como a seção "Instruções de Uso" de um manual de operação—dizendo ao LLM quem você é, o que pode fazer e como deve responder.
Componentes
Exemplo Prático
Você está atuando como um "Parceiro Criativo", um Agent especialista em criação de conteúdo de IA.
Hora Atual: 2026-03-05 14:37:00 CST
=== Especificação de Chamada de Ferramenta ===
- Use o formato de chamada de ferramenta XML.
- Cada chamada de ferramenta deve incluir um tool_call_id único.
- Os resultados das ferramentas são retornados por meio de tags <tool_result>.
- Considere AbortSignal ao executar ferramentas para suportar cancelamento.
=== Limites de Segurança ===
- Proibido estritamente executar operações destrutivas (rm -rf, formatação, etc.).
- Informações sensíveis do usuário devem ser criptografadas ao serem manipuladas.
- Proibido enviar mensagens para canais não autorizados.
Compensações de Design
Por que projetar assim?
- Compensação: Flexibilidade vs. Consistência
- Decisão: Geração unificada na camada do framework garante comportamento básico consistente para todos os Agents.
- Benefícios: Os usuários não precisam repetir regras básicas para cada Agent. Todos os Agents ganham automaticamente novas capacidades quando o framework é atualizado. Reduz o risco de erros de configuração.
- Custo: Os usuários não podem modificar essas regras centrais. Comportamentos especiais devem ser implementados indiretamente por meio das Camadas 7/8.
Camada 2: Definições de Ferramentas
Analogia
Como a lista de ferramentas de um canivete suíço—dizendo ao LLM quais ferramentas você tem, o que cada uma faz e como usá-las.
Componentes
Exemplo de Definição de Ferramenta
{
"name": "read",
"description": "Ler conteúdo de arquivo. Suporta arquivos de texto e imagens (jpg/png/gif/webp). Imagens são enviadas como anexos. A saída de texto é limitada a 2000 linhas ou 50KB.",
"parameters": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Caminho do arquivo (relativo ou absoluto)"
},
"offset": {
"type": "number",
"description": "Número da linha inicial (baseado em 1)"
},
"limit": {
"type": "number",
"description": "Máximo de linhas para ler"
}
},
"required": ["path"]
}
}
Compensações de Design
Por que usar JSON Schema?
- Compensação: Flexibilidade vs. Segurança de Tipos
- Decisão: Usar JSON Schema estrito para definir parâmetros de ferramentas.
- Benefícios: O LLM entende o uso da ferramenta com mais precisão. O framework pode validar parâmetros antes da chamada. Gera automaticamente documentação e definições de tipos.
- Custo: Adicionar novas ferramentas requer escrever um Schema completo. Não é possível suportar estruturas de parâmetros completamente dinâmicas.
Camada 3: Registro de Habilidades
Analogia
Como o "Cardápio de Especialidades" de um restaurante—dizendo ao LLM quais "receitas" profissionais estão disponíveis para chamar.
Compensações de Design
Por que usar varredura de diretório em vez de registro manual?
- Compensação: Flexibilidade vs. Custo de Manutenção
- Decisão: Escanear automaticamente o diretório ~/development/openclaw/skills/.
- Benefícios: Adicionar uma nova Habilidade requer apenas colocá-la no diretório; sem necessidade de alterações na configuração. Todos os Agents obtêm automaticamente a nova Habilidade. Reduz riscos de erro de configuração.
- Custo: Não é possível controlar precisamente quais Habilidades estão disponíveis para cada Agent. Todas as Habilidades são injetadas no System Prompt (aumentando o consumo de tokens).
Componentes
Camada 4: Apelidos de Modelo
Analogia
Como "Atalhos"—dando caminhos de modelo complexos com apelidos curtos para facilitar a chamada.
Compensações de Design
Por que são necessários apelidos de modelo?
- Compensação: Flexibilidade vs. Legibilidade
- Decisão: Permitir que os usuários definam apelidos curtos para modelos comumente usados.
- Benefícios: Simplifica as chamadas de modelo (glm-5 em vez de zhipu/glm-5). Suporta alternância entre vários Provedores (o mesmo apelido pode mapear para Provedores diferentes). Facilita testes A/B e migração de modelo.
- Custo: Requer manter um arquivo de configuração de apelidos. Pode causar confusão (o mesmo apelido pode apontar para modelos diferentes para Agents diferentes).
Componentes
Exemplo Prático
No System Prompt, os apelidos de modelo são exibidos como:
Apelidos de Modelo
- GLM-5: zhipu/glm-5
- Opus 4.6: xiaowang886/claude-opus-4-6-thinking
- Sonnet 4.5: xiaowang886/claude-sonnet-4-5
Os LLMs podem usar apelidos para alternar modelos: /model glm-5
Camada 5: Especificações de Protocolo
Analogia
Como "Regras de Trânsito"—definindo protocolos padrão para a interação do Agent com o sistema.
Compensações de Design
Por que são necessárias especificações de protocolo?
- Compensação: Liberdade vs. Consistência
- Decisão: Definir protocolos de interação padronizados (Respostas Silenciosas, Heartbeats, Tags de Resposta, etc.).
- Benefícios: Garante comportamento consistente em todos os Agents. Suporta monitoramento automatizado e verificações de saúde. Simplifica a colaboração multi-Agent.
- Custo: Limita a liberdade de expressão do Agent. Requer que o LLM siga estritamente os protocolos (o que pode ser ignorado).
Componentes
Exemplo Prático
Exemplo de Resposta Silenciosa:
Usuário: Recebido
Agent: NO_REPLY
Exemplo de Heartbeat:
Sistema: [Heartbeat Poll]
Agent: HEARTBEAT_OK
Exemplo de Tags de Resposta:
Agent: [[reply_to_current]] Tarefa concluída ✓
Camada 6: Informações de Runtime
Analogia
Como um "Painel de Controle"—dizendo ao LLM o status em tempo real do ambiente de execução atual.
Compensações de Design
Por que injetar informações de runtime toda vez?
- Compensação: Consumo de Tokens vs. Precisão de Contexto
- Decisão: Injetar o status de runtime mais recente a cada requisição.
- Benefícios: O LLM sabe a hora atual (evita confusão de tempo). O LLM sabe o modelo atual (evita erro de julgamento de capacidade). O LLM sabe o ambiente atual (evita erros de caminho).
- Custo: Consome ~2KB de tokens por requisição. A informação pode conter redundância.
Componentes
Exemplo Prático
Runtime
Camada 7: Arquivos do Workspace ★ Controlável pelo Usuário
Analogia
Como "Suas Notas de Trabalho"—são arquivos de configuração estáticos que você pode editar diretamente.
Compensações de Design
Por que apenas esta camada é editável estaticamente?
- Compensação: Estabilidade do Framework vs. Liberdade do Usuário
- Decisão: Separar o "mutável" do "imutável"; a camada do framework garante consistência enquanto a camada do usuário permite personalização.
- Benefícios: Os usuários podem definir identidade do Agent, especificações de trabalho e memória. Atualizações do framework não quebram as configurações do usuário. Arquivos de configuração podem ser versionados, copiados e compartilhados.
- Custo: Os usuários não podem modificar o comportamento central do framework. Requer aprender o framework TELOS e a estrutura de arquivos.
Arquivos Principais
Camada 8: Sistema de Bootstrap Hook ★ Controlável pelo Usuário
Analogia
Como uma "Seringa Programável"—você pode escrever scripts para injetar conteúdo dinamicamente no System Prompt em tempo de execução.
Compensações de Design
Por que um sistema de Hook é necessário?
- Compensação: Simplicidade da Configuração Estática vs. Flexibilidade da Injeção Dinâmica
- Decisão: Fornecer um mecanismo de Hook dinâmico juntamente com os Arquivos do Workspace estáticos.
- Benefícios: Pode ajustar dinamicamente o conteúdo injetado com base no contexto (canal, remetente, hora). Pode executar comandos shell e injetar saída (ex.: clima atual, status do Git). Pode ler arquivos externos e injetá-los (ex.: documentos do projeto, documentação de API). Suporta lógica condicional (if/else).
- Custo: Requer aprender a sintaxe do sistema de Hook e os mecanismos de gatilho. Erros de script de Hook podem causar anomalias no System Prompt. Aumenta a complexidade do sistema.
Quatro Mecanismos de Hook
- Hook agent:bootstrap (Sistema de Hook Interno)
Local do Gatilho: applyBootstrapHookOverrides() em bootstrap-hooks.ts
Capacidades:
- Controle total sobre o array bootstrapFiles.
- Pode adicionar, excluir ou modificar arquivos.
- Pode reordenar arquivos.
- Pode modificar o conteúdo do arquivo.
Quem pode registrar:
- Plugins do OpenClaw.
- Hooks do Workspace (~/.openclaw/workspace-*/hooks/ diretório).
- Módulos internos.
Exemplo de Código:
registerInternalHook("agent:bootstrap", (event) => {
const context = event.context as AgentBootstrapHookContext;
// Controle total sobre o array bootstrapFiles
context.bootstrapFiles = [
{ path: "CUSTOM.md", content: "Conteúdo Personalizado" }
];
});
- Hook bootstrap-extra-files (Hook Empacotado)
Local do Gatilho: handler.ts em hooks/bundled/bootstrap-extra-files/
Capacidades:
- Apenas anexa arquivos; não modifica os existentes.
- Especifica arquivos extras por meio de arquivo de configuração.
Exemplo de Configuração:
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["extra/*.md", "docs/CONTEXT.md"]
}
}
}
Cenários Aplicáveis:
- Precisa injetar arquivos de contexto específicos do projeto.
- Não quer modificar os 8 arquivos Bootstrap padrão.
- Precisa carregar dinamicamente documentação extra.
- Hook before_prompt_build (Hook de Plugin)
Local do Gatilho: runBeforePromptBuild() em attempt.ts
Capacidades:
- Modifica o prompt final (após a construção do system prompt, antes de enviar para o LLM).
- Pode prepender contexto (adicionar conteúdo antes do prompt).
- Pode sobrescrever systemPrompt.
Dados do Evento:
{
prompt: string; // Entrada do usuário
messages: unknown[]; // Histórico de mensagens da sessão
}
Valor de Retorno:
{
prependContext?: string; // Conteúdo adicionado antes do prompt
systemPrompt?: string; // Sobrescreve o system prompt
}
Cenários Aplicáveis:
- Precisa ajustar dinamicamente o prompt com base no histórico da sessão.
- Precisa injetar contexto em tempo real (ex.: hora atual, clima).
- Precisa substituir completamente o system prompt.
- bootstrapMaxChars / bootstrapTotalMaxChars (Item de Configuração)
Tipo: Item de configuração (não é um hook)
Capacidades:
- Controla o orçamento de caracteres.
- Padrão de arquivo único: 20K.
- Padrão total: 150K.
- Excesso é truncado pegando os primeiros 70% + últimos 20%.
Local da Configuração:
{
"agents": {
"defaults": {
"bootstrapMaxChars": 20000,
"bootstrapTotalMaxChars": 150000
}
}
}
Conselho Prático
Cenário 1: Quero adicionar documentação do projeto
Solução Recomendada: bootstrap-extra-files
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["docs/API.md", "docs/ARCHITECTURE.md"]
}
}
}
Cenário 2: Quero carregar arquivos dinamicamente com base no tipo de tarefa
Solução Recomendada: Hook agent:bootstrap personalizado
registerInternalHook("agent:bootstrap", (event) => {
const context = event.context as AgentBootstrapHookContext;
const sessionKey = context.sessionKey;
// Carregar arquivos diferentes com base no tipo de sessão
if (sessionKey.includes("coding")) {
context.bootstrapFiles.push({
path: "CODING_GUIDELINES.md",
content: fs.readFileSync("...").toString()
});
}
});
Cenário 3: Quero injetar contexto em tempo real (como hora atual)
Solução Recomendada: Hook before_prompt_build
on("before_prompt_build", (event, ctx) => {
return {
prependContext: Hora Atual: ${new Date().toISOString()}
};
});
Camada 9: Contexto de Entrada
Analogia
Como "Informações de Trânsito em Tempo Real"—injeta dinamicamente informações de contexto da conversa atual a cada requisição.
Compensações de Design
Por que injetar contexto toda vez?
- Compensação: Consumo de Tokens vs. Coerência da Conversa
- Decisão: Injetar os metadados da mensagem mais recente, informações do remetente e histórico da conversa a cada requisição.
- Benefícios: O LLM sabe quem está falando atualmente (evita confusão de remetente). O LLM sabe o histórico da conversa (mantém a coerência do contexto). O LLM sabe se foi @mencionado (decide se deve responder).
- Custo: Consome ~3KB de tokens por requisição. O histórico da conversa pode conter ruído.
Componentes
Processo Completo de Montagem do System Prompt
Resumo das Camadas Controláveis pelo Usuário
O OpenClaw fornece 3 tipos de mecanismos controláveis pelo usuário:
- Camada 7 (Arquivos do Workspace) - Arquivos de configuração estáticos. Cenário: Definir identidade do Agent, especificações de trabalho, memória. Prós: Simples, intuitivo, fácil controle de versão. Contras: Não pode ajustar dinamicamente.
- Camada 8 (Sistema de Bootstrap Hook) - Scripts de injeção dinâmica. Cenário: Injetar conteúdo com base no contexto, executar comandos, ler arquivos externos. Prós: Flexível, poderoso, suporta lógica e comandos. Contras: Requer aprender o sistema de Hook; erros de script causam problemas.
- Controle Indireto da Camada 9 (Contexto de Entrada) - Influenciar o contexto ao enviar mensagens. Cenário: Influenciar o comportamento do LLM por meio do histórico do chat ou mensagens citadas. Prós: Sem necessidade de configuração, interação natural. Contras: Não é possível controlar precisamente.
Tabela Comparativa de Tamanhos
⚠️
Nota: Os dados a seguir são estimativas; os tamanhos reais variam conforme a configuração e o contexto de execução. As camadas do framework (Camada 1-6 + 9) devem ser teoricamente as mesmas, mas podem variar ligeiramente devido a definições de ferramentas, Habilidades carregadas, etc.
Notas:
- A Camada 7 e a Camada 8 são controláveis pelo usuário; os tamanhos variam conforme a configuração do Agent.
- As outras camadas são geradas automaticamente e teoricamente idênticas entre Agents.
- Medições reais podem diferir devido à disponibilidade de ferramentas, carregamento de Habilidades e contexto de execução.
Sugestões de Otimização
- Otimização da Parte Controlável pelo Usuário (Camada 7 + 8)
Como as Camadas 7 e 8 são controladas pelo usuário, aqui estão as estratégias de otimização:
Otimização da Camada 7 (Arquivos Estáticos):
✅ Estratégias Enxutas Recomendadas:
- IDENTITY.md: Mantenha o framework TELOS central, remova descrições redundantes, use tabelas em vez de parágrafos.
- AGENTS.md: Use listas de verificação em vez de parágrafos longos, mostre comandos em blocos de código, remova explicações de regras duplicadas.
- MEMORY.md: Confie na exportação automática do MemOS; não adicione conteúdo manualmente—deixe o sistema mantê-lo.
❌ Práticas a Evitar:
- Não repita descrições que o framework OpenClaw já conhece.
- Não copie descrições detalhadas de Habilidades nos Arquivos do Workspace.
- Não use retórica excessiva ou linguagem decorativa.
Otimização da Camada 8 (Sistema de Hook):
✅ Estratégias de Uso Recomendadas:
- Priorize bootstrap-extra-files (cenários simples).
- Use agent:bootstrap quando a lógica condicional for necessária (cenários complexos).
- Use before_prompt_build para contexto em tempo real (cenários dinâmicos).
❌ Práticas a Evitar:
- Não execute operações demoradas nos Hooks (bloqueia a geração do System Prompt).
- Não injete muito conteúdo nos Hooks (excede os limites de token).
- Não use dependências externas instáveis nos Hooks (causa falha na inicialização).
- Estratégia de Poda do Prompt
Se o System Prompt estiver muito grande, considere:
Conclusão
O System Prompt do OpenClaw não é um único arquivo, mas uma arquitetura de 9 camadas cuidadosamente orquestrada:
- Camada 1-6: Geradas automaticamente pelo framework, garantindo consistência e estabilidade.
- Camada 7: Arquivos de configuração estáticos editáveis pelo usuário (IDENTITY.md, AGENTS.md, etc.).
- Camada 8: Scripts de injeção dinâmica programáveis pelo usuário (Sistema de Bootstrap Hook).
- Camada 9: Contexto em tempo real injetado automaticamente pelo framework (Contexto de Entrada).
Existem 2 camadas controláveis pelo usuário (Camada 7 + 8), não apenas a Camada 7 como foi dito anteriormente incorretamente.
Entender as diferenças e conexões entre essas camadas é a chave para dominar a configuração do OpenClaw.
