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): Aquí puedes escribir scripts para inyectar contenido de forma dinámica.
- Las demás capas son generadas automáticamente por el framework; solo necesitas entenderlas.
Necesidades comunes:
- ¿Quieres definir la identidad del Agent? → 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 "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 operando como un "Socio Creativo", un Agent 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 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é está diseñado así?
- Compensación: Flexibilidad vs. Consistencia
- Decisión: Generación unificada en la capa del framework para asegurar un comportamiento básico consistente en todos los Agents.
- Beneficios: Los usuarios no necesitan repetir reglas básicas para cada Agent. Todos los Agents obtienen automáticamente nuevas capacidades cuando el framework se actualiza. Reduce el riesgo de errores de configuración.
- Costo: Los usuarios no pueden modificar estas reglas principales. Los comportamientos especiales deben implementarse indirectamente mediante las Capas 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
<code-segment id="0" lang="json">
{
"name": "leer",
"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 50 KB.",
"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": "Número máximo de líneas a leer"
}
},
"required": ["path"]
}
}
</code-segment>
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 llamar. Genera automáticamente documentación y definiciones de tipos.
- Costo: Agregar nuevas herramientas requiere escribir un Schema completo. No se pueden admitir 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 llamar.
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 Skill solo requiere colocarla en el directorio; no se necesitan cambios de configuración. Todos los Agents obtienen automáticamente la nueva Skill. Reduce los riesgos de errores de configuración.
- Costo: No se puede controlar con precisión qué Skills están disponibles para cada Agent. Todas las Skills 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 complejas de modelos para facilitar su llamada.
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 cambiar entre varios Providers (el mismo alias puede asignarse a diferentes Providers). 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 Agents).
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 LLMs pueden usar alias para cambiar de modelo: /model glm-5
Capa 5: Especificaciones de protocolo
Analogía
Como las "Reglas de tráfico": definen protocolos estándar para la interacción del Agent 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, Latidos, Etiquetas de Respuesta, etc.).
- Beneficios: Asegura un comportamiento consistente en todos los Agents. Soporta monitoreo automatizado y verificaciones de salud. Simplifica la colaboración entre múltiples Agents.
- Costo: Limita la libertad de expresión del Agent. Requiere que el LLM siga estrictamente los protocolos (lo que podría ignorarse).
Componentes
Ejemplo práctico
Ejemplo de Respuesta Silenciosa:
Usuario: Recibido
Agent: NO_REPLY
Ejemplo de Latido:
Sistema: [Heartbeat Poll]
Agent: HEARTBEAT_OK
Ejemplo de Etiqueta de Respuesta:
Agent: [[reply_to_current]] Tarea completada ✓
Capa 6: Información de ejecución
Analogía
Como un "Tablero": 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 último estado de ejecución con cada solicitud.
- Beneficios: El LLM conoce la hora actual (evita confusiones temporales). El LLM conoce el modelo actual (evita juicios erróneos de capacidad). El LLM conoce el entorno actual (evita errores de ruta).
- Costo: Consume aproximadamente 2 KB de tokens por solicitud. La información puede contener redundancia.
Componentes
Ejemplo práctico
Entorno 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 estáticamente editable?
- Compensación: Estabilidad del framework vs. Libertad del usuario
- Decisión: Separar lo "cambiante" de lo "invariable"; la capa del framework asegura consistencia mientras que la capa del usuario permite personalización.
- Beneficios: Los usuarios pueden definir la identidad del Agent, 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, respaldo y compartirse.
- Costo: Los usuarios no pueden modificar el comportamiento principal 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 estáticos del espacio de trabajo.
- Beneficios: Puede ajustar dinámicamente el contenido inyectado según el contexto (canal, remitente, hora). Puede ejecutar comandos de shell e inyectar 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:
<code-segment id="1" lang="javascript">
registerInternalHook("agent:bootstrap", (event) => {
const context = event.context as AgentBootstrapHookContext;
// Control total sobre el array bootstrapFiles
context.bootstrapFiles = [
{ path: "CUSTOM.md", content: "Contenido personalizado" }
];
});
</code-segment>
- 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 archivo de configuración.
Ejemplo de configuración:
<code-segment id="2" lang="json">
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["extra/*.md", "docs/CONTEXT.md"]
}
}
}
</code-segment>
Escenarios aplicables:
- Necesidad de inyectar archivos de contexto específicos del proyecto.
- No se desea modificar los 8 archivos Bootstrap predeterminados.
- Necesidad de cargar dinámicamente documentación adicional.
- 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:
<code-segment id="3" lang="json">
{
"prompt": "string", // Entrada del usuario
"messages": "unknown[]" // Historial de mensajes de la sesión
}
</code-segment>
Valor de retorno:
<code-segment id="4" lang="json">
{
"prependContext": "string", // Contenido agregado antes del prompt
"systemPrompt": "string" // Sobrescribe el system prompt
}
</code-segment>
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 es un hook)
Capacidades:
- Controla el presupuesto de caracteres.
- Archivo único predeterminado: 20K.
- Total predeterminado: 150K.
- El exceso se trunca tomando el primer 70% + el último 20%.
Ubicación de configuración:
<code-segment id="5" lang="json">
{
"agents": {
"defaults": {
"bootstrapMaxChars": 20000,
"bootstrapTotalMaxChars": 150000
}
}
}
</code-segment>
Consejos prácticos
Escenario 1: Quiero agregar documentación del proyecto
Solución recomendada: bootstrap-extra-files
<code-segment id="6" lang="json">
{
"hooks": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["docs/API.md", "docs/ARCHITECTURE.md"]
}
}
}
</code-segment>
Escenario 2: Quiero cargar archivos dinámicamente según el tipo de tarea
Solución recomendada: Hook agent:bootstrap personalizado
<code-segment id="7" lang="javascript">
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("codificacion")) {
context.bootstrapFiles.push({
path: "CODING_GUIDELINES.md",
content: fs.readFileSync("...").toString()
});
}
});
</code-segment>
Escenario 3: Quiero inyectar contexto en tiempo real (como la hora actual)
Solución recomendada: Hook before_prompt_build
<code-segment id="8" lang="javascript">
on("before_prompt_build", (event, ctx) => {
return {
prependContext: Hora actual: ${new Date().toISOString()}
};
});
</code-segment>
Capa 9: Contexto entrante
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 confusiones 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 aproximadamente 3 KB 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 la identidad del Agent, 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; los errores de script causan problemas.
- Control indirecto de la Capa 9 (Contexto entrante) - Influir en el contexto mediante el envío de mensajes. Escenario: Influir en el comportamiento del LLM a través del historial de chat o mensajes citados. Ventajas: No se necesita 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, Skills cargadas, etc.
Notas:
- Las Capas 7 y 8 son controlables por el usuario; los tamaños varían según la configuración del Agent.
- Las demás capas se generan automáticamente y son teóricamente idénticas en todos los Agents.
- Las mediciones reales pueden diferir debido a la disponibilidad de herramientas, carga de Skills y contexto de ejecución.
Sugerencias de optimización
- Optimización de la parte controlable por el usuario (Capa 7 + 8)
Dado que las Capas 7 y 8 están controladas por el usuario, aquí hay estrategias de optimización:
Optimización de la Capa 7 (Archivos estáticos):
✅ Estrategias recomendadas para ser eficiente:
- IDENTITY.md: Mantén el framework TELOS principal, 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 Skills en los Archivos del espacio de trabajo.
- No uses retórica excesiva ni 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 (bloquea 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: Generada automáticamente por el framework, asegurando 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 entrante).
Hay 2 capas controlables por el usuario (Capa 7 + 8), no solo la Capa 7 como se indicó anteriormente de forma incorrecta.
Comprender las diferencias y conexiones entre estas capas es clave para dominar la configuración de OpenClaw.
