import backup .md files | Friends of the Crustacean 🦞🤝 | Page 1

inner trail Apr 21, 2026, 6:28 AM

#

So I have backed up my .md files (SOUL.md, AGENTS.md etc) from a previous OpenClaw. I have hence removed the old OpenClaw and installed a new one. What is the best way to import the .md files into my new OpenClaw?

lament bayBOT Apr 21, 2026, 6:28 AM

#

west sleetBOT Apr 21, 2026, 6:28 AM

#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

lament bayBOT Apr 21, 2026, 6:28 AM

#

chrome walrusBOT Apr 21, 2026, 6:30 AM

#

Short version: there’s no special “import” command for those files, just put them back into the agent workspace.

openclaw config get agents.defaults.workspace

Default is usually:

~/.openclaw/workspace

Copy your backed-up files there on the machine running the gateway:

AGENTS.md
SOUL.md
IDENTITY.md

#

USER.md
TOOLS.md
MEMORY.md (or legacy memory.md)
memory/ if you backed that up too

Then restart:

openclaw gateway restart

A couple of important notes:

If you only restore the .md files, you get your persona/memory back, but not old sessions, auth, or channel state.
If you want the bot restored more completely, also copy the state dir ~/.openclaw, then run:

#

openclaw doctor
openclaw gateway restart

One warning: don’t restore an old BOOTSTRAP.md unless you intentionally want the first-run bootstrap again.

Docs:

If you want, I can also give you a copy/paste cp command for your exact backup folder.

inner trail Apr 21, 2026, 8:55 AM

#

How do I fix the below? from 'openclaw doctor'

#

◇ Memory search ────────────────────────────────────────────────────────────────────────────╮
│ │
│ Memory search is enabled, but no embedding provider is ready. │
│ Semantic recall needs at least one embedding provider. │
│ Gateway memory probe for default agent is not ready: No GitHub token available for │
│ Copilot embedding provider │
│ │
│ No API key found for provider "openai". You are authenticated with OpenAI Codex OAuth. │
│ Use openai-codex/gpt-5.4 (OAuth) or set OPENAI_API_KEY to use openai/gpt-5.4. │
│ │

#

│ No API key found for provider "google". Auth store: │
│ /home/openclaw-agent/.openclaw/agents/main/agent/auth-profiles.json (agentDir: │
│ /home/openclaw-agent/.openclaw/agents/main/agent). Configure auth for this agent │
│ (openclaw agents add <id>) or copy auth-profiles.json from the main agentDir. │
│ │
│ No API key found for provider "voyage". Auth store: │
│ /home/openclaw-agent/.openclaw/agents/main/agent/auth-profiles.json (agentDir: │
│ /home/openclaw-agent/.openclaw/agents/main/agent). Configure auth for this agent │
│ (openclaw agents add <id>) or copy auth-profiles.json from the main agentDir. │
│ │
│ No API key found for provider "mistral". Auth store: │
│ /home/openclaw-agent/.openclaw/agents/main/agent/auth-profiles.json (agentDir: │
│ /home/openclaw-agent/.openclaw/agents/main/agent). Configure auth for this agent │
│ (openclaw agents add <id>) or copy auth-profiles.json from the main agentDir. │

#

│ │
│ Fix (pick one): │
│ - Set OPENAI_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, VOYAGE_API_KEY, MISTRAL_API_KEY in │
│ your environment │
│ - Configure credentials: openclaw configure --section model │
│ - For local embeddings: configure agents.defaults.memorySearch.provider and local model │
│ path │
│ - To disable: openclaw config set agents.defaults.memorySearch.enabled false │

chrome walrusBOT Apr 21, 2026, 8:56 AM

#

I don’t see the actual openclaw doctor error in your message yet.

Please paste:

openclaw --version
openclaw doctor

If it’s long, openclaw status --all helps too.

You can redact tokens/secrets, but keep the exact error text. Once you paste that, I can tell you the fix.
Troubleshooting docs: https://docs.openclaw.ai/gateway/troubleshooting

#

Yep, that’s two separate config/auth issues, not a problem with your .md restore.

1) Your default model is on the wrong route

You’re signed in with Codex OAuth, but openai/gpt-5.4 needs an OpenAI API key.

If you want to use your Codex/ChatGPT login, switch to:

openclaw config set agents.defaults.model.primary openai-codex/gpt-5.4

If you want openai/gpt-5.4 instead, you need to set OPENAI_API_KEY.

2) Memory search has no embedding provider

Semantic memory search needs an embedding provider. Right now it looks like Copilot/OpenAI embeddings are not available.

You have 3 sane options:

#

A. Use GitHub Copilot for embeddings

openclaw models auth login-github-copilot
openclaw config set agents.defaults.memorySearch.provider github-copilot

B. Use OpenAI embeddings
Set OPENAI_API_KEY, then:

openclaw config set agents.defaults.memorySearch.provider openai

C. Disable semantic memory search for now
If you just want things working and don’t care about semantic recall yet:

#

openclaw config set agents.defaults.memorySearch.enabled false

Then restart and re-check:

openclaw gateway restart
openclaw memory status --deep
openclaw doctor

One important gotcha: if OpenClaw is running as a service, the API key must be available to the gateway service, not just your current shell.

Docs:

#

https://docs.openclaw.ai/gateway/doctor

If you want, paste:

openclaw --version
openclaw config get agents.defaults.model.primary
openclaw config get agents.defaults.memorySearch.provider

and I’ll tell you the exact best fix from there.

inner trail Apr 21, 2026, 10:05 AM

#

Let's move on to a more urgent question first:

Hey Krill — OpenClaw 2026.4.15 on atmt, main agent runs in sandbox mode (agents.defaults.sandbox.mode = "all", tools.fs.workspaceOnly = true).

I hit something surprising: there are two workspace directories that don't sync.

Host: /home/openclaw-agent/.openclaw/workspace/ (what I see, what the Control UI Core Files panel shows)
Sandbox: /home/openclaw-agent/.openclaw/sandboxes/agent-main-<hash>/ (what the agent actually reads, bind-mounted into the container as /workspace, ro,z)

The sandbox was seeded once from ~/.nvm/versions/node/v24.15.0/lib/node_modules/openclaw/docs/reference/templates/ and never synced again. Edits I made to the host workspace didn't reach the agent. I had to cp the files across manually.

Four questions:

What events trigger a sandbox workspace re-seed? My agent reports bootstrapSeededAt predates the current session, so new-session and gateway restart don't seem to do it. Upgrade? Rebuild? Manual?
Is there a supported command to sync host → sandbox?
Why two copies at all, when the sandbox mount is already read-only inside the container? A direct RO bind of ~/.openclaw/workspace/ into /workspace would preserve isolation (container still can't write) AND eliminate drift. Is there a reason the current design copies?
What's the recommended upgrade-safe workflow for preserving workspace customizations across OpenClaw version bumps?

chrome walrusBOT Apr 21, 2026, 10:11 AM

#

Let me check the actual sandbox/workspace code path so I don't guess.

#

I found the container lifecycle path too. I’m checking whether sandbox recreate actually clears the copied workspace or just the container, because that changes the answer a lot.

#

Yep, what you’re seeing is real. In 2026.4.15, Docker sandboxing with workspaceAccess: "none" or "ro" can absolutely drift from the host workspace.

What triggers a re-seed?
For Docker copy mode, the sandbox workspace is created per scope, not per chat. Your path sandboxes/agent-main-... means scope: "agent", so new session and gateway restart reuse the same sandbox workspace.
Also, the seed is not a full resync. Code path is basically:
- create sandbox workspace if needed
- copy a small bootstrap file set from host only if each dest file is missing
- fill any still-missing files from templates
So host edits later do not propagate automatically. bootstrapSeededAt is just workspace bootstrap state, not a host→sandbox sync timestamp.
Supported host → sandbox sync command?
I don’t see a dedicated supported sync command for this in 2026.4.15.
openclaw sandbox recreate --agent main is the closest reset command, but for Docker it removes the container, not the copied workspace under ~/.openclaw/sandboxes/..., so it does not guarantee a fresh copy of host workspace changes.
Why two copies at all?
This is the current design:

#

workspaceAccess: "none" → sandbox-local /workspace
- workspaceAccess: "ro" → sandbox-local /workspace, plus host workspace mounted read-only at /agent
- workspaceAccess: "rw" → host workspace mounted directly at /workspace
So a direct RO bind of host workspace to /workspace is not the current ro behavior.
The likely reason is to keep a sandbox-local canonical /workspace for staged files, synced skills, media, and backend consistency. But yes, the downside is drift.

Recommended upgrade-safe workflow
Best practice:
- Treat host workspace as the source of truth
- Keep it in a private git repo / backup
- Treat ~/.openclaw/sandboxes/* as disposable runtime state
- After workspace changes or upgrades, refresh the sandbox copy manually if you stay on none/ro
If you want no drift, use:

#

   agents: {
     defaults: {
       sandbox: {
         workspaceAccess: "rw"
       }
     }
   }

But that is a real tradeoff, because the sandbox can then write the real host workspace.

One extra nuance: if you saw files in the sandbox seeded from docs/reference/templates, that usually means those files were missing in the host workspace when that sandbox scope was first created. It does not prefer templates over your host files, it only template-fills missing ones.

Docs:

#import backup .md files

1) Your default model is on the wrong route

2) Memory search has no embedding provider