Sessions

A session is OpenClaw's unit of conversation isolation. When a message arrives on any connected channel, the Gateway routes it to a session — creating a new one if none exists, or resuming an existing one if the channel already has an active session assigned.

Each session maintains its own context window — a rolling transcript of the conversation up to the model's token limit. This means two users on two different channels cannot see each other's messages, and tool calls in one session do not affect another.

Sessions are persisted to disk as transcript files (JSON). If the Gateway restarts, the session file is intact and the next message automatically resumes from where it left off. You can also resume sessions manually by session key, or hand a session key to a different channel to continue the conversation from another platform.

Sessions support sub-agents: a session can spawn child sessions to handle parallel subtasks (for example, researching two things at once), then merge results back into the parent. Child sessions are visible in openclaw session list with a parent reference.

Each session loads workspace files on start — SOUL.md, USER.md, MEMORY.md, and AGENTS.md — giving the agent its identity, persona, and user context before the first message is processed.