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—informando ao LLM quem você é, o que pode fazer e como deve responder.
Componentes
Exemplo Prático
Você está operando como "Creative Partner", um Agent especialista em criação de conteúdo de IA.
Horário Atual: 2026-03-05 14:37:00 BRT
=== Especificação de Chamada de Ferramentas ===
- Use o formato de chamada de ferramentas no estilo XML.
- Cada chamada de ferramenta deve incluir um tool_call_id único.
- Os resultados das ferramentas são retornados através de tags <tool_result>.
- Considere o 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 desta forma?
- Compensação: Flexibilidade vs. Consistência
- Decisão: A geração unificada na camada do framework garante um 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 principais. Comportamentos especiais devem ser implementados indiretamente através da Camada 7/8.
Camada 2: Definições de Ferramentas
Analogia
Como a lista de ferramentas de um canivete suíço—informando 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": "Lê o conteúdo do 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 Tipo
- Decisão: Usar JSON Schema estrito para definir os parâmetros das ferramentas.
- Benefícios: O LLM entende o uso das ferramentas com mais precisão. O framework pode validar os parâmetros antes de chamar. Gera automaticamente documentação e definições de tipo.
- 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 "Menu de Especialidades" de um restaurante—informando 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 Skill requer apenas colocá-la no diretório; nenhuma alteração de configuração é necessária. Todos os Agents obtêm automaticamente a nova Skill. Reduz os riscos de erro de configuração.
- Custo: Não é possível controlar precisamente quais Skills estão disponíveis para cada Agent. Todas as Skills são injetadas no System Prompt (aumentando o consumo de tokens).
Componentes
Camada 4: Apelidos de Modelo
Analogia
Como "Atalhos"—dando caminhos complexos de modelo apelidos curtos para facilitar a chamada.
Compensações de Design
Por que os apelidos de modelo são necessários?
- 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 múltiplos Providers (o mesmo apelido pode mapear para diferentes Providers). 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:
Model Aliases
- GLM-5: zhipu/glm-5
- Opus 4.6: xiaowang886/claude-opus-4-6-thinking
- Sonnet 4.5: xiaowang886/claude-sonnet-4-5
LLMs podem usar apelidos para trocar de modelo: /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 as especificações de protocolo são necessárias?
- 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"—informando 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 julgamento incorreto 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 Anotações 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. Os arquivos de configuração podem ter controle de versão, backup e ser compartilhados.
- Custo: Os usuários não podem modificar o comportamento principal do framework. Requer aprender a estrutura TELOS e a estrutura de arquivos.
Arquivos Principais
Camada 8: Sistema 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 Hook é necessário?
- Compensação: Simplicidade da Configuração Estática vs. Flexibilidade da Injeção Dinâmica
- Decisão: Fornecer um mecanismo 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 a saída (ex.: clima atual, status do Git). Pode ler arquivos externos e injetá-los (ex.: documentos do projeto, APIs de documentação). Suporta lógica condicional (if/else).
- Custo: Requer aprender a sintaxe do sistema Hook e os mecanismos de disparo. Erros no script Hook podem causar anomalias no System Prompt. Aumenta a complexidade do sistema.
Quatro Mecanismos Hook
- Hook agent:bootstrap (Sistema Hook Interno)
Local de Disparo: 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.
- Workspace Hooks (diretório ~/.openclaw/workspace-*/hooks/).
- 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 Integrado)
Local de Disparo: handler.ts em hooks/bundled/bootstrap-extra-files/
Capacidades:
- Apenas anexa arquivos; não modifica os existentes.
- Especifica arquivos extras via 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 documentação extra dinamicamente.
- Hook before_prompt_build (Hook de Plugin)
Local de Disparo: runBeforePromptBuild() em attempt.ts
Capacidades:
- Modifica o prompt final (após a construção do system prompt, antes de enviar ao LLM).
- Pode antepor 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; // Substitui 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 para arquivo único: 20K.
- Padrão total: 150K.
- O excesso é truncado pegando os primeiros 70% + os últimos 20%.
Local da Configuração:
{
"agents": {
"defaults": {
"bootstrapMaxChars": 20000,
"bootstrapTotalMaxChars": 150000
}
}
}
Conselhos Práticos
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;
// Carrega diferentes arquivos 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 com @ (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 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 Hook; erros de script causam problemas.
- Controle Indireto da Camada 9 (Contexto de Entrada) - Influenciando o contexto enviando mensagens. Cenário: Influenciar o comportamento do LLM via histórico de chat ou mensagens citadas. Prós: Sem configuração necessária, 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 de acordo com a configuração e o contexto de execução. As camadas do framework (Camada 1-6 + 9) teoricamente devem ser as mesmas, mas podem variar ligeiramente devido a definições de ferramentas, Skills carregadas, etc.
Notas:
- A Camada 7 e a Camada 8 são controláveis pelo usuário; os tamanhos variam de acordo com a configuração do Agent.
- As outras camadas são geradas automaticamente e teoricamente idênticas em todos os Agents.
- As medições reais podem diferir devido à disponibilidade de ferramentas, carregamento de Skills e contexto de execução.
Sugestões de Otimização
- Otimização da Parte Controlável pelo Usuário (Camada 7 + 8)
Como a Camada 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 Recomendadas de Enxugamento:
- IDENTITY.md: Mantenha o framework TELOS principal, 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 Skills para os Arquivos do Workspace.
- Não use retórica excessiva ou linguagem decorativa.
Otimização da Camada 8 (Sistema Hook):
✅ Estratégias Recomendadas de Uso:
- 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 for muito grande, considere:
Conclusão
O System Prompt do OpenClaw não é um arquivo único, 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 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.
Entender as diferenças e conexões entre essas camadas é a chave para dominar a configuração do OpenClaw.
