Workspace del agente

El workspace es el hogar del agente. Es el único directorio de trabajo utilizado para herramientas de archivos y para el contexto del workspace. Mantenlo privado y trátalo como memoria.

Esto es independiente de ~/.openclaw/, que almacena configuración, credenciales y sesiones.

Importante: el workspace es el cwd por defecto, no un sandbox estricto. Las herramientas resuelven rutas relativas contra el workspace, pero las rutas absolutas pueden acceder a otras ubicaciones del host a menos que el sandboxing esté habilitado. Si necesitas aislamiento, usa agents.defaults.sandbox (y/o configuración de sandbox por agente). Cuando el sandboxing está habilitado y workspaceAccess no es "rw", las herramientas operan dentro de un workspace sandbox en ~/.openclaw/sandboxes, no en tu workspace del host.

Ubicación por defecto

  • Por defecto: ~/.openclaw/workspace
  • Si OPENCLAW_PROFILE está definido y no es "default", el valor por defecto se convierte en ~/.openclaw/workspace-<profile>.
  • Sobrescribir en ~/.openclaw/openclaw.json:
{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

openclaw onboard, openclaw configure u openclaw setup crearán el workspace y sembrarán los archivos de bootstrap si faltan. Las copias de semilla del sandbox solo aceptan archivos regulares dentro del workspace; los alias de symlink/hardlink que resuelven fuera del workspace origen se ignoran.

Si ya gestionas los archivos del workspace por tu cuenta, puedes desactivar la creación de archivos de bootstrap:

{ agent: { skipBootstrap: true } }

Carpetas de workspace adicionales

Instalaciones anteriores pueden haber creado ~/openclaw. Mantener múltiples directorios de workspace puede causar confusión con la autenticación o desfase de estado, porque solo un workspace está activo a la vez.

Recomendación: mantén un único workspace activo. Si ya no usas las carpetas adicionales, archívalas o muévelas a la papelera (por ejemplo trash ~/openclaw). Si mantienes múltiples workspaces intencionalmente, asegúrate de que agents.defaults.workspace apunte al activo.

openclaw doctor te avisa cuando detecta directorios de workspace adicionales.

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

Estos son los archivos estándar que OpenClaw espera dentro del workspace:

  • AGENTS.md

    • Instrucciones operativas para el agente y cómo debe usar la memoria.
    • Se carga al inicio de cada sesión.
    • Buen lugar para reglas, prioridades y detalles de “cómo comportarse”.

  • SOUL.md

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

  • USER.md

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

  • IDENTITY.md

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

  • TOOLS.md

    • Notas sobre tus herramientas locales y convenciones.
    • No controla la disponibilidad de herramientas; es solo orientación.

  • HEARTBEAT.md

    • Checklist opcional breve para ejecuciones de heartbeat.
    • Mantenlo corto para evitar consumo de tokens.

  • BOOT.md

    • Checklist opcional de inicio que se ejecuta al reiniciar el gateway cuando los hooks internos están habilitados.
    • Mantenlo corto; usa la herramienta de mensaje para envíos salientes.

  • BOOTSTRAP.md

    • Ritual de primera ejecución.
    • Solo se crea para un workspace completamente nuevo.
    • Elimínalo después de completar el ritual.

  • memory/YYYY-MM-DD.md

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

  • MEMORY.md (opcional)

    • Memoria curada a largo plazo.
    • Solo cargar en la sesión principal y privada (no en contextos compartidos/grupales).

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

  • skills/ (opcional)

    • Skills específicos del workspace.
    • Sobrescriben skills gestionados/incluidos cuando hay conflicto de nombres.

  • canvas/ (opcional)

    • Archivos de UI Canvas para visualización de nodos (por ejemplo canvas/index.html).

Si falta algún archivo de bootstrap, OpenClaw inyecta un marcador de “archivo faltante” en la sesión y continúa. Los archivos de bootstrap grandes se truncan al inyectarlos; ajusta los límites con agents.defaults.bootstrapMaxChars (por defecto: 20000) y agents.defaults.bootstrapTotalMaxChars (por defecto: 150000). openclaw setup puede recrear los valores por defecto faltantes sin sobrescribir archivos existentes.

Qué NO está en el workspace

Esto reside en ~/.openclaw/ y NO debe incluirse en el repositorio del workspace:

  • ~/.openclaw/openclaw.json (configuración)
  • ~/.openclaw/credentials/ (tokens OAuth, claves API)
  • ~/.openclaw/agents/<agentId>/sessions/ (transcripciones de sesión + metadatos)
  • ~/.openclaw/skills/ (skills gestionados)

Si necesitas migrar sesiones o configuración, cópialos por separado y mantenlos fuera del control de versiones.

Respaldo con Git (recomendado, privado)

Trata el workspace como memoria privada. Ponlo en un repositorio Git privado para que esté respaldado y sea recuperable.

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

1) Inicializar el repositorio

Si git está instalado, los workspaces nuevos se inicializan automáticamente. Si este workspace aún no es un repositorio, 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) Agregar un remoto privado (opciones para principiantes)

Opción A: Interfaz web de GitHub

  1. Crea un nuevo repositorio privado en GitHub.
  2. No lo inicialices con un README (evita conflictos de merge).
  3. Copia la URL remota HTTPS.
  4. Agrega el remoto y haz push:
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: Interfaz web de GitLab

  1. Crea un nuevo repositorio privado en GitLab.
  2. No lo inicialices con un README (evita conflictos de merge).
  3. Copia la URL remota HTTPS.
  4. Agrega el remoto y haz push:
git branch -M main
git remote add origin <https-url>
git push -u origin main

3) Actualizaciones continuas

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

No incluyas secretos en los commits

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

  • Claves API, tokens OAuth, contraseñas o credenciales privadas.
  • Cualquier cosa bajo ~/.openclaw/.
  • Volcados en crudo de chats o archivos adjuntos sensibles.

Si necesitas almacenar referencias sensibles, usa marcadores de posición y guarda el secreto real en otro lugar (gestor de contraseñas, variables de entorno o ~/.openclaw/).

.gitignore sugerido como punto de partida:

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

Mover el workspace a otra máquina

  1. Clona el repositorio en la ruta deseada (por defecto ~/.openclaw/workspace).
  2. Configura agents.defaults.workspace a esa ruta en ~/.openclaw/openclaw.json.
  3. Ejecuta openclaw setup --workspace <ruta> para sembrar archivos faltantes.
  4. Si necesitas las sesiones, copia ~/.openclaw/agents/<agentId>/sessions/ de la máquina anterior por separado.

Notas avanzadas

  • El enrutamiento multi-agente puede usar diferentes workspaces por agente. Consulta Enrutamiento de canales para la configuración de enrutamiento.
  • Si agents.defaults.sandbox está habilitado, las sesiones no principales pueden usar workspaces sandbox por sesión bajo agents.defaults.sandbox.workspaceRoot.
arrow_back
Anterior
Context
Siguiente
OAuth
arrow_forward