Espacio de trabajo del agente

El espacio de trabajo es el hogar del agente: el directorio de trabajo utilizado para las herramientas de archivos y el contexto del espacio de trabajo. Manténgalo privado y trátelo como memoria. Esto es independiente de ~/.openclaw/, que almacena la configuración, las credenciales y las sesiones.

El espacio de trabajo es el cwd predeterminado, no un entorno aislado estricto. Las herramientas resuelven las rutas relativas con respecto al espacio de trabajo, pero las rutas absolutas aún pueden acceder a otras ubicaciones del host, salvo que el aislamiento esté habilitado. Si necesita aislamiento, use agents.defaults.sandbox (o la configuración de aislamiento por agente).Cuando el aislamiento está habilitado y workspaceAccess no es "rw", las herramientas funcionan dentro de un espacio de trabajo aislado en ~/.openclaw/sandboxes, no en el espacio de trabajo del host.

Ubicación predeterminada

Valor predeterminado: ~/.openclaw/workspace
Si OPENCLAW_PROFILE está establecido y no es "default", el valor predeterminado pasa a ser ~/.openclaw/workspace-<profile>.
OPENCLAW_WORKSPACE_DIR sustituye a ambos valores anteriores cuando está establecido.
Los agentes no predeterminados (agents.entries.*) sin un espacio de trabajo explícito se resuelven como <state-dir>/workspace-<agentId>, no como el espacio de trabajo compartido predeterminado.

Sustitúyalo en ~/.openclaw/openclaw.json:

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

Sustitución por agente: agents.entries.*.workspace. openclaw onboard, openclaw configure o openclaw setup crean el espacio de trabajo y generan los archivos de inicialización si faltan.

Las copias de inicialización del entorno aislado solo aceptan archivos normales dentro del espacio de trabajo; se ignoran los alias de enlaces simbólicos o físicos que se resuelvan fuera del espacio de trabajo de origen.

Si ya gestiona por su cuenta los archivos del espacio de trabajo, deshabilite la creación de archivos de inicialización:

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

Carpetas adicionales del espacio de trabajo

Es posible que instalaciones anteriores hayan creado ~/openclaw. Mantener varios directorios de espacio de trabajo puede provocar confusiones en la autenticación o divergencias de estado, ya que solo puede haber un espacio de trabajo activo a la vez.

Recomendación: mantenga un único espacio de trabajo activo. Si ya no utiliza las carpetas adicionales, archívelas o muévalas a la papelera (por ejemplo, trash ~/openclaw). Si mantiene intencionadamente varios espacios de trabajo, asegúrese de que agents.defaults.workspace (o la clave por agente workspace) apunte al espacio activo.

Mapa de archivos del espacio de trabajo

Archivos estándar que OpenClaw espera dentro del espacio de trabajo:

AGENTS.md: instrucciones de funcionamiento

Instrucciones de funcionamiento para el agente y sobre cómo debe utilizar la memoria. Se carga al inicio de cada sesión. Es un buen lugar para las reglas, las prioridades y los detalles sobre 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 y emoji

El nombre, el estilo y el emoji del agente. Se crea o actualiza durante el ritual de inicialización.

TOOLS.md: convenciones de herramientas locales

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

HEARTBEAT.md: lista de comprobación de Heartbeat

Pequeña lista de comprobación opcional para las ejecuciones de Heartbeat. Manténgala breve para evitar consumir 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 están habilitados los hooks internos). Manténgala breve; utilice la herramienta de mensajes para los envíos salientes.

BOOTSTRAP.md: ritual de primera ejecución

Ritual único de primera ejecución. Solo se crea para un espacio de trabajo completamente nuevo. Elimínelo cuando finalice el ritual.

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

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: memoria a largo plazo seleccionada (opcional)

Memoria a largo plazo seleccionada: hechos duraderos, preferencias, decisiones y resúmenes breves. Mantenga los registros detallados en memory/YYYY-MM-DD.md para que las herramientas de memoria puedan recuperarlos cuando sea necesario sin insertarlos en cada prompt. Cargue MEMORY.md únicamente en la sesión principal privada (no en contextos compartidos o grupales). Consulte Memoria para conocer el flujo de trabajo y el volcado automático de memoria.

skills/: Skills del espacio de trabajo (opcional)

Skills específicas del espacio de trabajo. Es la ubicación de Skills con mayor prioridad para ese espacio de trabajo, por delante de las Skills del agente del proyecto, las Skills personales del agente, las Skills administradas, las Skills incluidas y skills.load.extraDirs cuando coinciden los nombres.

canvas/: archivos de la interfaz Canvas (opcional)

Archivos de la interfaz Canvas para las pantallas de los Node (por ejemplo, canvas/index.html).

Si falta un archivo de inicialización, OpenClaw inserta un marcador de «archivo ausente» en la sesión y continúa. Los archivos de inicialización grandes se truncan al insertarse; ajuste los límites con agents.defaults.bootstrapMaxChars (valor predeterminado: 20000) y agents.defaults.bootstrapTotalMaxChars (valor predeterminado: 60000). openclaw setup puede volver a crear los archivos predeterminados que falten sin sobrescribir los existentes.

Lo que NO está en el espacio de trabajo

Estos elementos se encuentran en ~/.openclaw/ y NO deben confirmarse en el repositorio del espacio de trabajo:

~/.openclaw/openclaw.json (configuración)
~/.openclaw/state/openclaw.sqlite (estado y certificaciones de la configuración del espacio de trabajo compartido)
~/.openclaw/agents/<agentId>/agent/auth-profiles.json (perfiles de autenticación de modelos: OAuth y claves de API)
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite (filas de sesiones, transcripciones y estado de ejecución por agente)
~/.openclaw/agents/<agentId>/agent/codex-home/ (cuenta de ejecución de Codex por agente, configuración, Skills, plugins y estado nativo de los hilos)
~/.openclaw/credentials/ (estado del canal o proveedor, además de datos heredados de importación de OAuth)
~/.openclaw/agents/<agentId>/sessions/ (orígenes de migración heredados y artefactos de archivo o soporte)
~/.openclaw/skills/ (Skills administradas)

Si necesita migrar sesiones o la configuración, cópielas por separado y manténgalas fuera del control de versiones. Las versiones anteriores de OpenClaw escribían los archivos auxiliares del espacio de trabajo openclaw-workspace-state.json, .openclaw/workspace-state.json y .attested. El entorno de ejecución actual solo utiliza la base de datos SQLite compartida para ese estado. Si Doctor informa sobre uno de estos archivos, ejecute openclaw doctor --fix; Doctor importa el estado heredado válido y elimina un origen únicamente después de verificar las filas de la base de datos.

Copia de seguridad con Git (recomendada y privada)

Trate el espacio de trabajo como memoria privada. Guárdelo en un repositorio Git privado para disponer de una copia de seguridad y poder recuperarlo. Ejecute estos pasos en la máquina donde se ejecuta el Gateway (allí es donde reside el espacio de trabajo).

Inicializar el repositorio

Si Git está instalado, los espacios de trabajo completamente nuevos se inicializan automáticamente. Si este espacio de trabajo todavía no es un repositorio, ejecute:

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 repositorio remoto privado

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

Cree un repositorio privado nuevo en GitHub.
No lo inicialice con un archivo README (para evitar conflictos de fusión).
Copie la URL HTTPS del repositorio remoto.
Añada el repositorio remoto y envíe los cambios:

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

Cree un repositorio privado nuevo en GitLab.
No lo inicialice con un archivo README (para evitar conflictos de fusión).
Copie la URL HTTPS del repositorio remoto.
Añada el repositorio remoto y envíe los cambios:

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

Actualizaciones posteriores

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

No confirme secretos

Incluso en un repositorio privado, evite almacenar secretos en el espacio de trabajo:

Claves de API, tokens de OAuth, contraseñas o credenciales privadas.
Cualquier elemento dentro de ~/.openclaw/.
Volcados sin procesar de chats o archivos adjuntos confidenciales.

Si debe almacenar referencias confidenciales, utilice marcadores de posición y mantenga el secreto real en otro lugar (un gestor de contraseñas, variables de entorno o ~/.openclaw/).

Plantilla inicial sugerida para .gitignore:

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

Trasladar el espacio de trabajo a una máquina nueva

Clonar el repositorio

Clone el repositorio en la ruta deseada (de forma predeterminada, ~/.openclaw/workspace).

Actualizar la configuración

Establezca agents.defaults.workspace en esa ruta dentro de ~/.openclaw/openclaw.json.

Generar los archivos que falten

Ejecute openclaw setup --workspace <path> para generar los archivos que falten.

Copiar las sesiones (opcional)

Si necesita las sesiones, copie ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite por separado desde la máquina anterior. Copie ~/.openclaw/agents/<agentId>/sessions/ únicamente cuando también necesite entradas de migración heredadas o artefactos de archivo o soporte.

Notas avanzadas

El enrutamiento multiagente puede utilizar distintos espacios de trabajo por agente mediante agents.entries.*.workspace. Consulte Enrutamiento de canales para conocer la configuración del enrutamiento.
Si agents.defaults.sandbox está habilitado, las sesiones que no sean la principal pueden utilizar espacios de trabajo aislados por sesión dentro de agents.defaults.sandbox.workspaceRoot.

Temas relacionados

Heartbeat: archivo HEARTBEAT.md del espacio de trabajo
Aislamiento: acceso al espacio de trabajo en entornos aislados
Sesión: rutas de almacenamiento de sesiones
Órdenes permanentes: instrucciones persistentes en los 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

Lo que NO está en el espacio de trabajo

Copia de seguridad con Git (recomendada y privada)

No confirme secretos

Trasladar el espacio de trabajo a una máquina nueva

Notas avanzadas

Temas relacionados

​Ubicación predeterminada

​Carpetas adicionales del espacio de trabajo

​Mapa de archivos del espacio de trabajo

​Lo que NO está en el espacio de trabajo

​Copia de seguridad con Git (recomendada y privada)

​No confirme secretos

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

​Notas avanzadas

​Temas relacionados

Ubicación predeterminada

Carpetas adicionales del espacio de trabajo

Mapa de archivos del espacio de trabajo

Lo que NO está en el espacio de trabajo

Copia de seguridad con Git (recomendada y privada)

No confirme secretos

Trasladar el espacio de trabajo a una máquina nueva

Notas avanzadas

Temas relacionados