Fix: Session File Path Must Be Within Sessions Directory (Migration Error)

If you're migrating from an older Clawdbot install to OpenClaw and hitting this frustrating crash loop:

...you're not alone. This is one of the most common migration gotchas, and the fix is simpler than you might think.

What's Actually Happening

This error isn't about a corrupted openclaw.json. It's about OpenClaw trying to load session entries whose sessionFile paths point outside the current sessions directory—a common side effect of migrating from older Clawdbot layouts where paths were structured differently.

The Confusion: sessions vs session

First, a common trap: there is no sessions (plural) config key. The correct key is session (singular):

// ~/.openclaw/openclaw.json
{
  "session": {
    "store": "~/.openclaw/agents/{agentId}/sessions/sessions.json"
  }
}

So if you tried openclaw config unset sessions and got "Config path not found"—that's why. The correct command would be openclaw config unset session.store (but you probably don't need it).

The Real Fix: Nuke the Session Store

The session store file lives at:

• Store: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Transcripts: ~/.openclaw/agents/<agentId>/sessions/*.jsonl

Here's the fix:

Step 1: Stop the Gateway

openclaw gateway stop
# Or kill the process however you run it

Step 2: Back Up and Remove the Session Store

mv ~/.openclaw/agents/main/sessions/sessions.json \
   ~/.openclaw/agents/main/sessions/sessions.json.bak

(Replace main with your agent ID if you're using a different one.)

Step 3: Restart the Gateway

openclaw gateway start

Send a test message—OpenClaw will recreate sessions.json cleanly with valid paths.

Alternative: Edit Instead of Delete

If you want to preserve session history, open sessions.json and look for any "sessionFile": "/some/absolute/path/..." entries. Either:

• Remove them entirely, or
• Change them to relative filenames like "sess-abc123.jsonl" (just the filename, same directory)

Nuclear Option: Full Reset

If nothing works and you want to start completely fresh:

openclaw onboard --reset

Or if even that fails due to invalid config:

mv ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
openclaw onboard

This regenerates all defaults from scratch.

Why This Happens

Older Clawdbot versions used different directory structures. When you upgrade, the session store may still reference old paths like /home/user/.clawdbot/sessions/... which don't match OpenClaw's expected layout. The path validation is strict—sessions must live within the configured sessions directory.

Related docs:

• Session Configuration Reference
• Session Concepts
• Setup Wizard

Originally discussed in the OpenClaw Discord #help channel. Thanks to the community for surfacing this common migration issue!