Este documento proporciona un desglose detallado de la estructura completa del System Prompt que OpenClaw Agent envía al LLM.
Versión:
v2.1
Fecha de actualización:
2026-03-05
Diagrama de Arquitectura General
Navegación Rápida (TL;DR)
Lectura obligada para principiantes:
- Capa 7 (Archivos del Espacio de Trabajo) — Archivos de configuración que puedes editar directamente.
- Capa 8 (Hook de Arranque) — Donde puedes escribir scripts para inyectar contenido dinámicamente.
- Las demás capas son generadas automáticamente por el framework; solo necesitas comprenderlas.
Necesidades comunes:
- ¿Quieres definir la identidad del Agente? → Edita IDENTITY.md en la Capa 7.
- ¿Quieres agregar documentación del proyecto? → Usa el Hook bootstrap-extra-files en la Capa 8.
- ¿Quieres inyectar contexto en tiempo real? → Usa el Hook before_prompt_build en la Capa 8.
- ¿Quieres controlar el tamaño de los archivos? → Ajusta la configuración bootstrapMaxChars.
Capa 1: Núcleo del Framework OpenClaw
Analogía
Como la "sección de Instrucciones de Uso" de un manual de operaciones: le dice al LLM quién eres, qué puedes hacer y cómo debes responder.
Componentes
Ejemplo Práctico
Estás ejecutando como "Socio Creativo", un Agente experto en creación de contenido con IA.
Hora Actual: 2026-03-05 14:37:00 CST
=== Especificación de Llamada a Herramientas ===
- Usa el formato de llamada a herramientas estilo XML.
- Cada llamada a herramienta debe incluir un tool_call_id único.
- Los resultados de las herramientas se devuelven mediante etiquetas <tool_result>.
- Considera AbortSignal al ejecutar herramientas para soportar la cancelación.
=== Límites de Seguridad ===
- Prohibido estrictamente ejecutar operaciones destructivas (rm -rf, formateo, etc.).
- La información sensible del usuario debe cifrarse al ser manejada.
- Prohibido enviar mensajes a canales no autorizados.
Compensaciones de Diseño
¿Por qué diseñarlo así?
- Compensación: Flexibilidad vs. Consistencia
- Decisión: La generación unificada en la capa del framework asegura un comportamiento básico consistente para todos los Agentes.
- Beneficios: Los usuarios no necesitan repetir reglas básicas para cada Agente. Todos los Agentes obtienen nuevas capacidades automáticamente cuando el framework se actualiza. Reduce el riesgo de errores de configuración.
- Costo: Los usuarios no pueden modificar estas reglas base. Los comportamientos especiales deben implementarse indirectamente a través de la Capa 7/8.
Capa 2: Definiciones de Herramientas
Analogía
Como la lista de herramientas de una navaja suiza: le dice al LLM qué herramientas tienes, qué hace cada una y cómo usarlas.
Componentes
Ejemplo de Definición de Herramienta
{
"name": "read",
"description": "Lee el contenido de un archivo. Soporta archivos de texto e imágenes (jpg/png/gif/webp). Las imágenes se envían como adjuntos. La salida de texto está limitada a 2000 líneas o 50KB.",
"parameters": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Ruta del archivo (relativa o absoluta)"
},
"offset": {
"type": "number",
"description": "Número de línea inicial (basado en 1)"
},
"limit": {
"type": "number",
"description": "Máximo de líneas a leer"
}
},
"required": ["path"]
}
}
Compensaciones de Diseño
¿Por qué usar JSON Schema?
- Compensación: Flexibilidad vs. Seguridad de Tipos
- Decisión: Usar JSON Schema estricto para definir los parámetros de las herramientas.
- Beneficios: El LLM entiende el uso de las herramientas con mayor precisión. El framework puede validar los parámetros antes de llamarlas. Genera documentación y definiciones de tipo automáticamente.
- Costo: Agregar nuevas herramientas requiere escribir un Schema completo. No se pueden soportar estructuras de parámetros completamente dinámicas.
Capa 3: Registro de Habilidades
Analogía
Como el "Menú de Especialidades" de un restaurante: le dice al LLM qué "recetas" profesionales están disponibles para usar.
Compensaciones de Diseño
¿Por qué usar escaneo de directorios en lugar de registro manual?
- Compensación: Flexibilidad vs. Costo de Mantenimiento
- Decisión: Escanear automáticamente el directorio ~/development/openclaw/skills/.
- Beneficios: Agregar una nueva Habilidad solo requiere colocarla en el directorio; no se necesitan cambios de configuración. Todos los Agentes obtienen la nueva Habilidad automáticamente. Reduce los riesgos de errores de configuración.
- Costo: No se puede controlar con precisión qué Habilidades están disponibles para cada Agente. Todas las Habilidades se inyectan en el System Prompt (aumentando el consumo de tokens).
Componentes
Capa 4: Alias de Modelos
Analogía
Como "Atajos": asignan alias cortos a rutas de modelos complejas para facilitar su uso.
Compensaciones de Diseño
¿Por qué se necesitan alias de modelos?
- Compensación: Flexibilidad vs. Legibilidad
- Decisión: Permitir que los usuarios definan alias cortos para los modelos de uso común.
- Beneficios: Simplifica las llamadas a modelos (glm-5 en lugar de zhipu/glm-5). Soporta el cambio entre múltiples Proveedores (el mismo alias puede asignarse a diferentes Proveedores). Facilita las pruebas A/B y la migración de modelos.
- Costo: Requiere mantener un archivo de configuración de alias. Puede causar confusión (el mismo alias podría apuntar a diferentes modelos para distintos Agentes).
Componentes
Ejemplo Práctico
En el System Prompt, los alias de modelos se muestran como:
Alias de Modelos
- GLM-5: zhipu/glm-5
- Opus 4.6: xiaowang886/claude-opus-4-6-thinking
- Sonnet 4.5: xiaowang886/claude-sonnet-4-5
Los LLM pueden usar alias para cambiar de modelo: /model glm-5
Capa 5: Especificaciones de Protocolo
Analogía
Como las "Reglas de Tránsito": definen los protocolos estándar para la interacción del Agente con el sistema.
Compensaciones de Diseño
¿Por qué se necesitan especificaciones de protocolo?
- Compensación: Libertad vs. Consistencia
- Decisión: Definir protocolos de interacción estandarizados (Respuestas Silenciosas, Heartbeats, Etiquetas de Respuesta, etc.).
- Beneficios: Asegura un comportamiento coherente en todos los Agentes. Soporta monitoreo automatizado y verificaciones de estado. Simplifica la colaboración entre múltiples Agentes.
- Costo: Limita la libertad de expresión del Agente. Requiere que el LLM siga estrictamente los protocolos (que podrían ser ignorados).
Componentes
Ejemplo Práctico
Ejemplo de Respuesta Silenciosa:
Usuario: Recibido
Agente: NO_REPLY
Ejemplo de Heartbeats:
Sistema: [Heartbeat Poll]
Agente: HEARTBEAT_OK
Ejemplo de Etiquetas de Respuesta:
Agente: [[reply_to_current]] Tarea completada ✓
Capa 6: Información de Ejecución
Analogía
Como un "Tablero de Instrumentos": le dice al LLM el estado en tiempo real del entorno de ejecución actual.
Compensaciones de Diseño
¿Por qué inyectar información de ejecución cada vez?
- Compensación: Consumo de Tokens vs. Precisión del Contexto
- Decisión: Inyectar el estado de ejecución más reciente con cada solicitud.
- Beneficios: El LLM sabe la hora actual (evita confusión temporal). El LLM sabe el modelo actual (evita errores de capacidad). El LLM sabe el entorno actual (evita errores de ruta).
- Costo: Consume ~2KB de tokens por solicitud. La información puede contener redundancia.
Componentes
Ejemplo Práctico
Tiempo de Ejecución
Capa 7: Archivos del Espacio de Trabajo ★ Controlable por el Usuario
Analogía
Como "Tus Notas de Trabajo": son archivos de configuración estáticos que puedes editar directamente.
Compensaciones de Diseño
¿Por qué solo esta capa es editable estáticamente?
- Compensación: Estabilidad del Framework vs. Libertad del Usuario
- Decisión: Separar lo "cambiante" de lo "inmutable"; la capa del framework garantiza consistencia mientras que la capa del usuario permite la personalización.
- Beneficios: Los usuarios pueden definir la identidad del Agente, especificaciones de trabajo y memoria. Las actualizaciones del framework no rompen las configuraciones del usuario. Los archivos de configuración pueden tener control de versiones, respaldarse y compartirse.
- Costo: Los usuarios no pueden modificar el comportamiento base del framework. Requiere aprender el framework TELOS y la estructura de archivos.
Archivos Principales
Capa 8: Sistema de Hooks de Arranque ★ Controlable por el Usuario
Analogía
Como una "Jeringa Programable": puedes escribir scripts para inyectar contenido dinámicamente en el System Prompt en tiempo de ejecución.
Compensaciones de Diseño
¿Por qué se necesita un sistema de Hooks?
- Compensación: Simplicidad de la Configuración Estática vs. Flexibilidad de la Inyección Dinámica
- Decisión: Proporcionar un mecanismo de Hook dinámico junto con los Archivos del Espacio de Trabajo estáticos.
- Beneficios: Puede ajustar dinámicamente el contenido inyectado según el contexto (canal, remitente, hora). Puede ejecutar comandos de shell e inyectar su salida (por ejemplo, clima actual, estado de Git). Puede leer archivos externos e inyectarlos (por ejemplo, documentación del proyecto, documentación de API). Soporta lógica condicional (if/else).
- Costo: Requiere aprender la sintaxis del sistema de Hooks y los mecanismos de activación. Los errores en los scripts de Hook pueden causar anomalías en el System Prompt. Aumenta la complejidad del sistema.
Cuatro Mecanismos de Hook
- Hook agent:bootstrap (Sistema de Hook Interno)
Ubicación de activación: applyBootstrapHookOverrides() en bootstrap-hooks.ts
Capacidades:
- Control total sobre el array bootstrapFiles.
- Puede agregar, eliminar o modificar archivos.
- Puede reordenar archivos.
- Puede modificar el contenido de los archivos.
Quién puede registrarse:
- Plugins de OpenClaw.
- Hooks del Espacio de Trabajo (directorio ~/.openclaw/workspace-*/hooks/).
- Módulos internos.
Ejemplo de Código:
registerInternalHook("agent:bootstrap", (event) => {
const context = event.context as AgentBootstrapHookContext;
// Control total sobre el array bootstrapFiles
context.bootstrapFiles = [
{ path: "CUSTOM.md", content: "Contenido Personalizado" }
];
});
- Hook bootstrap-extra-files (Hook Empaquetado)
Ubicación de activación: handler.ts en hooks/bundled/bootstrap-extra-files/
Capacidades:
- Solo agrega archivos; no modifica los existentes.
- Especifica archivos adicionales mediante un archivo de configuración.
Ejemplo de Configuración:
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["extra/*.md", "docs/CONTEXT.md"]
}
}
}
Escenarios Aplicables:
- Necesidad de inyectar archivos de contexto específicos del proyecto.
- No se desea modificar los 8 archivos Bootstrap por defecto.
- Necesidad de cargar documentación adicional de forma dinámica.
- Hook before_prompt_build (Hook de Plugin)
Ubicación de activación: runBeforePromptBuild() en attempt.ts
Capacidades:
- Modifica el prompt final (después de construir el system prompt, antes de enviarlo al LLM).
- Puede anteponer contexto (agregar contenido antes del prompt).
- Puede sobrescribir systemPrompt.
Datos del Evento:
{
prompt: string; // Entrada del usuario
messages: unknown[]; // Historial de mensajes de la sesión
}
Valor de Retorno:
{
prependContext?: string; // Contenido agregado antes del prompt
systemPrompt?: string; // Sobrescribe el system prompt
}
Escenarios Aplicables:
- Necesidad de ajustar dinámicamente el prompt según el historial de la sesión.
- Necesidad de inyectar contexto en tiempo real (por ejemplo, hora actual, clima).
- Necesidad de reemplazar completamente el system prompt.
- bootstrapMaxChars / bootstrapTotalMaxChars (Elemento de Configuración)
Tipo: Elemento de configuración (no un hook)
Capacidades:
- Controla el presupuesto de caracteres.
- Archivo único por defecto: 20K.
- Total por defecto: 150K.
- El exceso se trunca tomando el primer 70% + el último 20%.
Ubicación de Configuración:
{
"agents": {
"defaults": {
"bootstrapMaxChars": 20000,
"bootstrapTotalMaxChars": 150000
}
}
}
Consejos Prácticos
Escenario 1: Quiero agregar documentación del proyecto
Solución Recomendada: bootstrap-extra-files
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["docs/API.md", "docs/ARCHITECTURE.md"]
}
}
}
Escenario 2: Quiero cargar archivos dinámicamente según el tipo de tarea
Solución Recomendada: Hook agent:bootstrap personalizado
registerInternalHook("agent:bootstrap", (event) => {
const context = event.context as AgentBootstrapHookContext;
const sessionKey = context.sessionKey;
// Cargar diferentes archivos según el tipo de sesión
if (sessionKey.includes("coding")) {
context.bootstrapFiles.push({
path: "CODING_GUIDELINES.md",
content: fs.readFileSync("...").toString()
});
}
});
Escenario 3: Quiero inyectar contexto en tiempo real (como la hora actual)
Solución Recomendada: Hook before_prompt_build
on("before_prompt_build", (event, ctx) => {
return {
prependContext: Hora Actual: ${new Date().toISOString()}
};
});
Capa 9: Contexto de Entrada
Analogía
Como "Información de Tráfico en Tiempo Real": inyecta dinámicamente información de contexto de la conversación actual con cada solicitud.
Compensaciones de Diseño
¿Por qué inyectar contexto cada vez?
- Compensación: Consumo de Tokens vs. Coherencia de la Conversación
- Decisión: Inyectar los metadatos del mensaje más reciente, información del remitente e historial de la conversación con cada solicitud.
- Beneficios: El LLM sabe quién está hablando actualmente (evita confusión de remitente). El LLM conoce el historial de la conversación (mantiene la coherencia del contexto). El LLM sabe si fue mencionado con @ (decide si responder).
- Costo: Consume ~3KB de tokens por solicitud. El historial de la conversación puede contener ruido.
Componentes
Proceso Completo de Ensamblaje del System Prompt
Resumen de las Capas Controlables por el Usuario
OpenClaw proporciona 3 tipos de mecanismos controlables por el usuario:
- Capa 7 (Archivos del Espacio de Trabajo) - Archivos de configuración estáticos. Escenario: Definir identidad del Agente, especificaciones de trabajo, memoria. Ventajas: Simple, intuitivo, fácil control de versiones. Desventajas: No se puede ajustar dinámicamente.
- Capa 8 (Sistema de Hooks de Arranque) - Scripts de inyección dinámica. Escenario: Inyectar contenido según el contexto, ejecutar comandos, leer archivos externos. Ventajas: Flexible, potente, soporta lógica y comandos. Desventajas: Requiere aprender el sistema de Hooks; errores de script causan problemas.
- Control Indirecto de la Capa 9 (Contexto de Entrada) - Influir en el contexto enviando mensajes. Escenario: Influir en el comportamiento del LLM a través del historial de chat o mensajes citados. Ventajas: No requiere configuración, interacción natural. Desventajas: No se puede controlar con precisión.
Tabla Comparativa de Tamaños
⚠️
Nota: Los siguientes datos son estimados; los tamaños reales varían según la configuración y el contexto de ejecución. Las capas del framework (Capa 1-6 + 9) deberían ser teóricamente iguales, pero pueden variar ligeramente debido a las definiciones de herramientas, las Habilidades cargadas, etc.
Notas:
- La Capa 7 y la Capa 8 son controlables por el usuario; los tamaños varían según la configuración del Agente.
- Las demás capas se generan automáticamente y son teóricamente idénticas entre Agentes.
- Las mediciones reales pueden diferir debido a la disponibilidad de herramientas, la carga de Habilidades y el contexto de ejecución.
Sugerencias de Optimización
- Optimización de la Parte Controlable por el Usuario (Capa 7 + 8)
Dado que la Capa 7 y 8 son controladas por el usuario, aquí hay estrategias de optimización:
Optimización de la Capa 7 (Archivos Estáticos):
✅ Estrategias Recomendadas para Mantenerlo Ligero:
- IDENTITY.md: Mantén el framework TELOS central, elimina descripciones redundantes, usa tablas en lugar de párrafos.
- AGENTS.md: Usa listas de verificación en lugar de párrafos largos, muestra comandos en bloques de código, elimina explicaciones de reglas duplicadas.
- MEMORY.md: Confía en la exportación automática de MemOS; no agregues contenido manualmente—deja que el sistema lo mantenga.
❌ Prácticas a Evitar:
- No repitas descripciones que el framework OpenClaw ya conoce.
- No copies descripciones detalladas de Habilidades en los Archivos del Espacio de Trabajo.
- No uses retórica excesiva o lenguaje decorativo.
Optimización de la Capa 8 (Sistema de Hooks):
✅ Estrategias de Uso Recomendadas:
- Prioriza bootstrap-extra-files (escenarios simples).
- Usa agent:bootstrap cuando se necesite lógica condicional (escenarios complejos).
- Usa before_prompt_build para contexto en tiempo real (escenarios dinámicos).
❌ Prácticas a Evitar:
- No ejecutes operaciones que consuman mucho tiempo en los Hooks (bloquean la generación del System Prompt).
- No inyectes demasiado contenido en los Hooks (supera los límites de tokens).
- No uses dependencias externas inestables en los Hooks (provoca fallos de inicio).
- Estrategia de Poda del Prompt
Si el System Prompt es demasiado grande, considera:
Conclusión
El System Prompt de OpenClaw no es un solo archivo, sino una arquitectura de 9 capas cuidadosamente orquestada:
- Capa 1-6: Generadas automáticamente por el framework, garantizando consistencia y estabilidad.
- Capa 7: Archivos de configuración estáticos editables por el usuario (IDENTITY.md, AGENTS.md, etc.).
- Capa 8: Scripts de inyección dinámica programables por el usuario (Sistema de Hooks de Arranque).
- Capa 9: Contexto en tiempo real inyectado automáticamente por el framework (Contexto de Entrada).
Hay 2 capas controlables por el usuario (Capa 7 + 8), no solo la Capa 7 como se había indicado anteriormente.
Comprender las diferencias y conexiones entre estas capas es clave para dominar la configuración de OpenClaw.
