Saltar al contenido principal
El espacio de trabajo es el hogar del agente: el directorio de trabajo usado para las herramientas de archivos y 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 estricto. Las herramientas resuelven las rutas relativas respecto del espacio de trabajo, pero las rutas absolutas aún pueden llegar a otros lugares 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 espacio de trabajo de sandbox bajo ~/.openclaw/sandboxes, no en tu espacio de trabajo del host.

​
Ubicación predeterminada

  • Predeterminada: ~/.openclaw/workspace
  • Si OPENCLAW_PROFILE está configurado y no es "default", el valor predeterminado pasa a ser ~/.openclaw/workspace-<profile>.
  • OPENCLAW_WORKSPACE_DIR anula ambos valores anteriores cuando está configurado.
  • Los agentes no predeterminados (agents.list[]) sin un espacio de trabajo explícito se resuelven a <state-dir>/workspace-<agentId>, no al espacio de trabajo compartido predeterminado.
Anula en ~/.openclaw/openclaw.json: 
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}
Anulación por agente: agents.list[].workspace. openclaw onboard, openclaw configure u openclaw setup crean el espacio de trabajo y siembran los archivos de arranque si faltan.
Las copias de siembra de sandbox solo aceptan archivos regulares dentro del espacio de trabajo; se ignoran los alias de symlink/hardlink que resuelven fuera del espacio de trabajo de origen.
Si ya administras tú mismo los archivos del espacio de trabajo, deshabilita 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 derivaciones confusas de autenticación o estado, ya que 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 (o la clave workspace por agente) apunte al activo.

​
Mapa de archivos del espacio de trabajo

Archivos estándar que OpenClaw espera dentro del espacio de trabajo:
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”.
Persona, tono y límites. Se carga en cada sesión. Guía: guía de personalidad de SOUL.md.
Quién es el usuario y cómo dirigirse a él. Se carga en cada sesión.
El nombre, la vibra y el emoji del agente. Se crea/actualiza durante el ritual de arranque.
Notas sobre tus herramientas locales y convenciones. No controla la disponibilidad de herramientas; solo es orientación.
Lista de verificación pequeña opcional para ejecuciones de Heartbeat. Mantenla breve para evitar consumo de tokens.
Lista de verificación de inicio opcional que se ejecuta automáticamente al reiniciar el Gateway (cuando los hooks internos están habilitados). Mantenla breve; usa la herramienta de mensajes para envíos salientes.
Ritual único de primera ejecución. Solo se crea para un espacio de trabajo completamente nuevo. Elimínalo después de completar el ritual.
Registro diario de memoria (un archivo por día). Se recomienda leer hoy + ayer al iniciar la sesión.
Memoria a largo plazo curada: hechos duraderos, preferencias, decisiones y resúmenes breves. Mantén 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/de grupo). Consulta Memoria para ver el flujo de trabajo y el vaciado automático de memoria.
Skills específicas del espacio de trabajo. Ubicación de Skills de mayor precedencia para ese espacio de trabajo, por delante de las Skills de agente del proyecto, Skills personales de agente, Skills administradas, Skills incluidas y skills.load.extraDirs cuando los nombres colisionan.
Archivos de interfaz de Canvas para pantallas de nodos (por ejemplo canvas/index.html).
Si falta un 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: 20000) y agents.defaults.bootstrapTotalMaxChars (predeterminado: 60000). openclaw setup puede recrear 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 modelo: OAuth + claves de API)
  • ~/.openclaw/agents/<agentId>/agent/codex-home/ (cuenta, configuración, Skills, plugins y estado nativo de hilos del runtime Codex por agente)
  • ~/.openclaw/credentials/ (estado de canales/proveedores más datos heredados de importación OAuth)
  • ~/.openclaw/agents/<agentId>/sessions/ (transcripciones de sesión + metadatos)
  • ~/.openclaw/skills/ (Skills administradas)
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. Ponlo 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).
1

Initialize the repo

Si git está instalado, los espacios de trabajo completamente 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"
2

Add a private remote

  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
3

Ongoing updates

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 marcadores de posición y mantén 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

1

Clone the repo

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

Update config

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

Seed missing files

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

Copy sessions (optional)

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

​
Notas avanzadas

  • El enrutamiento multiagente puede usar diferentes espacios de trabajo por agente mediante agents.list[].workspace. Consulta Enrutamiento de canales para ver 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 sandbox
  • Sesión - rutas de almacenamiento de sesiones
  • Órdenes permanentes - instrucciones persistentes en archivos del espacio de trabajo