Espacio de trabajo del agente

El espacio de trabajo es el hogar del agente. Es el único directorio de trabajo usado para las herramientas de archivos y para el contexto del espacio de trabajo. Mantenlo privado y trátalo como memoria. Esto está separado de ~/.openclaw/, que almacena configuración, credenciales y sesiones.

El espacio de trabajo es el cwd predeterminado, no un sandbox rígido. Las herramientas resuelven las rutas relativas con respecto al espacio de trabajo, pero las rutas absolutas aún pueden llegar a otros lugares del host salvo 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 espacio de trabajo de sandbox en ~/.openclaw/sandboxes, no en tu espacio de trabajo del host.

Ubicación predeterminada

Predeterminado: ~/.openclaw/workspace
Si OPENCLAW_PROFILE está definido y no es "default", el valor predeterminado pasa a ser ~/.openclaw/workspace-<profile>.
Sobrescríbelo en ~/.openclaw/openclaw.json:

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}

openclaw onboard, openclaw configure u openclaw setup crearán el espacio de trabajo y sembrarán los archivos de arranque si faltan.

Las copias semilla de sandbox solo aceptan archivos normales dentro del espacio de trabajo; se ignoran los alias de symlink/hardlink que resuelven fuera del espacio de trabajo de origen.

Si ya gestionas tú mismo los archivos del espacio de trabajo, puedes deshabilitar la creación de archivos de arranque:

{ agents: { defaults: { skipBootstrap: true } } }

Carpetas adicionales del espacio de trabajo

Las instalaciones antiguas pueden haber creado ~/openclaw. Mantener varios directorios de espacio de trabajo puede causar deriva confusa de autenticación o estado, porque solo un espacio de trabajo está activo a la vez.

Recomendación: mantén un único espacio de trabajo activo. Si ya no usas las carpetas adicionales, archívalas o muévelas a la Papelera (por ejemplo, trash ~/openclaw). Si mantienes varios espacios de trabajo intencionalmente, asegúrate de que agents.defaults.workspace apunte al activo.openclaw doctor advierte cuando detecta directorios adicionales de espacio de trabajo.

Mapa de archivos del espacio de trabajo

Estos son los archivos estándar que OpenClaw espera dentro del espacio de trabajo:

AGENTS.md - instrucciones operativas

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

SOUL.md - personalidad y tono

Personalidad, tono y límites. Se carga en cada sesión. Guía: guía de personalidad de SOUL.md.

USER.md - quién es el usuario

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

IDENTITY.md - nombre, estilo, emoji

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

TOOLS.md - convenciones de herramientas locales

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

HEARTBEAT.md - lista de comprobación de heartbeat

Lista de comprobación diminuta opcional para ejecuciones de heartbeat. Mantenla corta para evitar consumo de tokens.

BOOT.md - lista de comprobación de inicio

Lista de comprobación de inicio opcional que se ejecuta automáticamente al reiniciar el Gateway (cuando los hooks internos están habilitados). Mantenla corta; usa la herramienta de mensajes para envíos salientes.

BOOTSTRAP.md - ritual de primera ejecución

Ritual único de primera ejecución. Solo se crea para un espacio de trabajo totalmente nuevo. Elimínalo después de completar el ritual.

memory/YYYY-MM-DD.md - registro diario de memoria

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

MEMORY.md - memoria a largo plazo curada (opcional)

Memoria a largo plazo curada: hechos duraderos, preferencias, decisiones y resúmenes breves. Mantén los registros detallados en memory/YYYY-MM-DD.md para que las herramientas de memoria puedan recuperarlos bajo demanda sin inyectarlos en cada prompt. Carga MEMORY.md solo en la sesión principal y privada (no en contextos compartidos/grupales). Consulta Memoria para ver el flujo de trabajo y el vaciado automático de memoria.

skills/ - skills del espacio de trabajo (opcional)

Skills específicas del espacio de trabajo. Ubicación de Skills de mayor precedencia para ese espacio de trabajo. Sobrescribe las Skills de agente de proyecto, Skills de agente personales, Skills gestionadas, Skills incluidas y skills.load.extraDirs cuando los nombres colisionan.

canvas/ - archivos de Canvas UI (opcional)

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

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

Qué NO está en el espacio de trabajo

Estos viven bajo ~/.openclaw/ y NO deben confirmarse en el repo del espacio de trabajo:

~/.openclaw/openclaw.json (configuración)
~/.openclaw/agents/<agentId>/agent/auth-profiles.json (perfiles de autenticación de modelos: OAuth + claves de API)
~/.openclaw/agents/<agentId>/agent/codex-home/ (cuenta de runtime de Codex por agente, configuración, Skills, plugins y estado nativo de hilos)
~/.openclaw/credentials/ (estado de canal/proveedor más datos de importación OAuth heredados)
~/.openclaw/agents/<agentId>/sessions/ (transcripciones de sesiones + metadatos)
~/.openclaw/skills/ (Skills gestionadas)

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

Copia de seguridad con git (recomendada, privada)

Trata el espacio de trabajo como memoria privada. Colócalo en un repo git privado para que tenga copia de seguridad y sea recuperable. Ejecuta estos pasos en la máquina donde se ejecuta el Gateway (ahí es donde vive el espacio de trabajo).

Inicializar el repo

Si git está instalado, los espacios de trabajo totalmente nuevos se inicializan automáticamente. Si este espacio de trabajo 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"

Añadir un remoto privado

Interfaz web de GitHub
GitHub CLI (gh)
Interfaz web de GitLab

Crea un nuevo repositorio privado en GitHub.
No lo inicialices con un README (evita conflictos de merge).
Copia la URL remota HTTPS.
Añade el remoto y haz push:

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

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

Crea un nuevo repositorio privado en GitLab.
No lo inicialices con un README (evita conflictos de merge).
Copia la URL remota HTTPS.
Añade el remoto y haz push:

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

Actualizaciones continuas

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

No confirmes secretos

Incluso en un repo privado, evita almacenar secretos en el espacio de trabajo:

Claves de API, tokens OAuth, contraseñas o credenciales privadas.
Cualquier cosa bajo ~/.openclaw/.
Volcados sin procesar de chats o adjuntos sensibles.

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

Plantilla inicial sugerida de .gitignore:

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

Mover el espacio de trabajo a una máquina nueva

Clonar el repo

Clona el repo en la ruta deseada (predeterminada ~/.openclaw/workspace).

Actualizar la configuración

Establece agents.defaults.workspace en esa ruta en ~/.openclaw/openclaw.json.

Sembrar archivos faltantes

Ejecuta openclaw setup --workspace <path> para sembrar cualquier archivo faltante.

Copiar sesiones (opcional)

Si necesitas sesiones, copia ~/.openclaw/agents/<agentId>/sessions/ desde la máquina antigua por separado.

Notas avanzadas

El enrutamiento multiagente puede usar espacios de trabajo diferentes por agente. Consulta enrutamiento de canales para la configuración de enrutamiento.
Si agents.defaults.sandbox está habilitado, las sesiones no principales pueden usar espacios de trabajo de sandbox por sesión bajo agents.defaults.sandbox.workspaceRoot.

Relacionado

Heartbeat - archivo de espacio de trabajo HEARTBEAT.md
Sandboxing - acceso al espacio de trabajo en entornos con sandboxing
Sesión - rutas de almacenamiento de sesiones
Órdenes permanentes - instrucciones persistentes en archivos del espacio de trabajo

Fundamentals

Sessions and memory

Multi-agent

Messages and delivery

Espacio de trabajo del agente

Ubicación predeterminada

Carpetas adicionales del espacio de trabajo

Mapa de archivos del espacio de trabajo

Qué NO está en el espacio de trabajo

Copia de seguridad con git (recomendada, privada)

No confirmes secretos

Mover el espacio de trabajo a una máquina nueva

Notas avanzadas

Relacionado

Fundamentals

Sessions and memory

Multi-agent

Messages and delivery

Documentation Index

​Ubicación predeterminada

​Carpetas adicionales del espacio de trabajo

​Mapa de archivos del espacio de trabajo

​Qué NO está en el espacio de trabajo

​Copia de seguridad con git (recomendada, privada)

​No confirmes secretos

​Mover el espacio de trabajo a una máquina nueva

​Notas avanzadas

​Relacionado

Ubicación predeterminada

Carpetas adicionales del espacio de trabajo

Mapa de archivos del espacio de trabajo

Qué NO está en el espacio de trabajo

Copia de seguridad con git (recomendada, privada)

No confirmes secretos

Mover el espacio de trabajo a una máquina nueva

Notas avanzadas

Relacionado