Configura el workspace de OpenClaw: Guía paso a paso

¿Alguna vez has sentido que tu agente pierde el hilo o que sus archivos están esparcidos por todo el sistema? Gestionar el contexto es uno de los mayores retos cuando trabajas con agentes autónomos, y es frustrante cuando el agente “olvida” reglas importantes porque no tiene un lugar claro donde guardar su memoria de trabajo.

El workspace es el hogar del agente. Es el único directorio de trabajo que utiliza para las herramientas de archivos y para el contexto del espacio de trabajo. Manténlo privado y trátalo como si fuera su propia memoria.

Este directorio es independiente de ~/.openclaw/, donde se guardan la configuración, las credenciales y las sesiones.

Importante: el workspace es el cwd predeterminado, no un sandbox estricto. Las herramientas resuelven rutas relativas respecto al workspace, pero las rutas absolutas pueden alcanzar otros lugares del host a menos que actives el sandboxing. Si necesitas aislamiento, usa agents.defaults.sandbox (o la configuración de sandbox por agente). Cuando el sandboxing está activo y workspaceAccess no es "rw", las herramientas operan dentro de un workspace de sandbox en ~/.openclaw/sandboxes, no en tu workspace local.

Ubicación predeterminada

• Por defecto: ~/.openclaw/workspace
• Si OPENCLAW_PROFILE está configurado y no es "default", la ruta será ~/.openclaw/workspace-<profile>.
• Puedes sobrescribirlo en ~/.openclaw/openclaw.json:

{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

Los comandos openclaw onboard, openclaw configure o openclaw setup crearán el workspace y generarán los archivos de bootstrap iniciales si faltan. Las copias de semillas para el sandbox solo aceptan archivos regulares del workspace; los alias de symlinks o hardlinks que apunten fuera del workspace de origen serán ignorados.

Si prefieres gestionar los archivos del workspace tú mismo, puedes desactivar la creación del bootstrap:

{ agent: { skipBootstrap: true } }

Carpetas de workspace adicionales

Es posible que instalaciones antiguas hayan creado la carpeta ~/openclaw. Tener varios directorios de workspace puede causar problemas de autenticación o derivas de estado, ya que solo puede haber un workspace activo a la vez.

Recomendación: mantén un único workspace activo. Si ya no usas las carpetas extra, archívalas o muévelas a la papelera (por ejemplo, trash ~/openclaw). Si decides mantener varios workspaces a propósito, asegúrate de que agents.defaults.workspace apunte al que esté activo.

El comando openclaw doctor te avisará si detecta directorios de workspace adicionales.

Mapa de archivos del workspace (qué significa cada archivo)

Estos son los archivos estándar que OpenClaw espera encontrar en el workspace:

• AGENTS.md

  • Instrucciones operativas para el agente y cómo debe usar su memoria.
  • Se carga al inicio de cada sesión.
  • Es el lugar ideal para reglas, prioridades, comportamientos y detalles de ejecución.

• SOUL.md

  • Persona, tono, límites y estilo.
  • Se carga en cada sesión.

• USER.md

  • Quién es el usuario y cómo debe dirigirse el agente a él.
  • Se carga en cada sesión.

• IDENTITY.md

  • El nombre del agente, su estilo, emoji y esencia.
  • Se crea o actualiza durante el ritual de bootstrap.

• TOOLS.md

  • Notas sobre tus herramientas locales, convenciones y flujos.
  • No controla la disponibilidad de las herramientas; es solo una guía.

• HEARTBEAT.md

  • Lista de verificación opcional para ejecuciones de heartbeat.
  • Mantenlo corto para no quemar tokens innecesariamente.

• BOOT.md

  • Lista de verificación de inicio opcional que se ejecuta al reiniciar el Gateway si los hooks internos están activos.
  • Mantenlo breve; usa la herramienta de mensajes para envíos externos.

• BOOTSTRAP.md

  • Ritual de primera ejecución única.
  • Solo se crea para un workspace totalmente nuevo.
  • Debes borrarlo después de completar el ritual.

• memory/YYYY-MM-DD.md

  • Registro diario de memoria (un archivo por día).
  • Se recomienda leer el de hoy y el de ayer al iniciar la sesión.

• MEMORY.md (opcional)

  • Memoria a largo plazo curada.
  • Solo se carga en la sesión principal y privada (no en contextos compartidos o de grupo).

Consulta Memory para entender el flujo de trabajo y el vaciado automático de memoria.

• skills/ (opcional)

  • Skills específicas del workspace.
  • Sobrescriben a las skills gestionadas o empaquetadas si los nombres coinciden.

• canvas/ (opcional)

  • Archivos de la UI de Canvas para visualizaciones de Node (por ejemplo, canvas/index.html).

Si falta algún archivo de bootstrap, OpenClaw inserta un marcador de “archivo faltante” en la sesión y continúa. Los archivos de bootstrap muy grandes se truncan al insertarse; puedes ajustar los límites con agents.defaults.bootstrapMaxChars (por defecto: 20000) y agents.defaults.bootstrapTotalMaxChars (por defecto: 150000). El comando openclaw setup puede recrear los valores por defecto que falten sin sobrescribir tus archivos actuales.

Qué NO está en el workspace

Estos elementos viven en ~/.openclaw/ y NO deben subirse al repositorio del workspace:

• ~/.openclaw/openclaw.json (configuración)
• ~/.openclaw/credentials/ (tokens de OAuth, API keys y secretos)
• ~/.openclaw/agents/<agentId>/sessions/ (transcripciones de sesiones, metadatos y logs)
• ~/.openclaw/skills/ (skills gestionadas)

Si necesitas migrar sesiones o configuraciones, cópialas por separado y mantenlas fuera del control de versiones.

Backup con Git (recomendado, privado)

Trata el workspace como memoria privada. Guárdalo en un repositorio de Git privado para que tenga respaldo y sea recuperable.

Ejecuta estos pasos en la máquina donde corre el Gateway (ahí es donde vive el workspace).

1) Inicializa el repositorio

Si tienes Git instalado, los workspaces nuevos se inicializan automáticamente. Si este workspace aún no es un repo, ejecuta:

cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"

2) Añade un remoto privado (opciones sencillas)

Opción A: Web de GitHub

1. Crea un nuevo repositorio privado en GitHub.
2. No lo inicialices con un README (para evitar conflictos de merge).
3. Copia la URL HTTPS del remoto.
4. Añade el remoto y sube los cambios:

git branch -M main
git remote add origin <https-url>
git push -u origin main

Opción B: GitHub CLI (gh)

gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push

Opción C: Web de GitLab

1. Crea un nuevo repositorio privado en GitLab.
2. No lo inicialices con un README.
3. Copia la URL HTTPS del remoto.
4. Añade el remoto y sube los cambios:

git branch -M main
git remote add origin <https-url>
git push -u origin main

3) Actualizaciones constantes

git status
git add .
git commit -m "Update memory"
git push

No subas secretos

Incluso en un repositorio privado, evita guardar secretos en el workspace:

• API keys, tokens de OAuth, contraseñas o credenciales privadas.
• Cualquier cosa dentro de ~/.openclaw/.
• Volcados de chats sin procesar o archivos adjuntos sensibles.

Si tienes que guardar referencias sensibles, usa marcadores de posición (placeholders) y mantén el secreto real en otro lugar (gestor de contraseñas, variables de entorno o en ~/.openclaw/).

Sugerencia de inicio para tu .gitignore:

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

Mover el workspace a una máquina nueva

1. Clona el repositorio en la ruta deseada (por defecto ~/.openclaw/workspace).
2. Configura agents.defaults.workspace con esa ruta en ~/.openclaw/openclaw.json.
3. Ejecuta openclaw setup --workspace <path> para generar los archivos que falten.
4. Si necesitas las sesiones, copia ~/.openclaw/agents/<agentId>/sessions/ desde la máquina antigua por separado.

Notas avanzadas

• El enrutamiento multi-agente puede usar diferentes workspaces por agente. Revisa Channel routing para configurar el enrutamiento.
• Si agents.defaults.sandbox está activo, las sesiones que no sean la principal pueden usar workspaces de sandbox por sesión bajo agents.defaults.sandbox.workspaceRoot.

Relacionado

• Standing Orders — instrucciones persistentes en archivos del workspace
• Heartbeat — archivo de workspace HEARTBEAT.md
• Session — rutas de almacenamiento de sesiones
• Sandboxing — acceso al workspace en entornos aislados

Pasos siguientes

• Configura tus instrucciones persistentes para personalizar el comportamiento.
• Aprende cómo el agente gestiona su memoria diaria.

¿Necesitas ayuda para configurar tu entorno? Prueba nuestro AI Setup Assistant.