0a8e3604ba
* refactor(sessions): migrate runtime storage to sqlite * test(sessions): fix sqlite CI regressions * test(sessions): align remaining sqlite fixtures * fix(codex): require sqlite trajectory recorder * test(sessions): align orphan recovery sqlite fixture * test(sessions): align sqlite rebase fixtures * fix(sessions): finish current-main integration of the sqlite flip Resolve the whole-store SDK removal across its owner boundary: drop the loadSessionStore re-export and the registry whole-store wrappers, wire hasTrackedActiveSessionRun into gateway chat, complete the preserveLockedHarnessIds cleanup contract, flip the codex thread-history import to storePath targets, and port remaining main-side tests from file-store helpers to session accessor reads. * chore: drop committed pebbles log, revert plugin-inspector bump, refresh generated docs Remove the 1.8k-line .pebbles/events.jsonl work log from the branch, restore the plugin-inspector advisory lane to main's pinned 0.3.10 so the supply-chain bump gets its own review, and regenerate docs_map, the plugin SDK API baseline, and the export-surface ratchet for the merged tree. * feat(sessions): keep archived transcripts by default with zstd cold storage Codex-style retention: deleting or resetting a session archives its transcript as a zstd-compressed JSONL artifact (plain when the runtime lacks node:zlib zstd) and keeps it until the disk budget evicts oldest first. resetArchiveRetention now governs both deleted and reset archives and defaults to keep; maxDiskBytes defaults to 2gb so retention stays bounded, with archives evicted before live sessions. The cron reaper follows the same knob instead of deleting archives on its own timer. * fix(state): converge agent DB migration lineages and bound database growth Merge coherence: run both structure-gated legacy memory-schema repairs (flip-lineage drop, main-lineage identity rebuild) before the flip migration so pre-flip v1/v2 and pre-merge flip v1/v4 databases all converge, and hoist foreign_keys=OFF outside the schema transaction where the pragma was silently ignored and the v1 sessions rebuild cascade-deleted session_entries. Growth guards: fresh agent DBs enable auto_vacuum=INCREMENTAL, WAL maintenance releases freed pages in bounded passes (never a blocking full VACUUM), and doctor reports state/agent DB bloat from freelist stats. * fix(codex): resolve the store path for thread-history import via the SDK The supervision catalog passed the legacy sessionFile locator to the storePath-targeted transcript mirror; resolve the agent store path with the session-store SDK helper instead of a runtime-object seam so test fakes and headless callers need no extra surface. Drop the obsolete missing-session-id preprocessing case: sessions rows are NOT NULL on session_id and upsert repairs id-less patches at write time. * fix(sessions): fail safe on malformed disk-budget config and doctor stat errors A malformed explicit maxDiskBytes disables the budget instead of falling back to the destructive 2gb default the user never chose, and the doctor bloat check skips databases whose paths stat-fail instead of aborting doctor. * fix(sessions): complete sqlite conflict translations * test(sqlite): align hardening checks with maintenance * test(sessions): inspect compressed transcript archives * fix(tests): await session seeds and drop unused helpers flagged by CI lint The five unawaited writeSessionStoreSeed calls raced their SQLite seeds against the assertions, failing compact shards; the bloat probe drops a useless initializer and the merged tests drop now-unused helpers. * test(sessions): type legacy proof events directly * test(sessions): align hardening contracts * perf(sessions): read usage transcript sizes from SQL aggregates Usage/cost scans walked every session and materialized every transcript event just to re-stringify it for a byte estimate — the #86718 stall class reborn on the DB. readTranscriptStatsSync sums stored JSON bytes in SQLite without loading a single row. * fix(sessions): re-root foreign-root transcript paths onto the current sessions dir Restored backups, moved OPENCLAW_STATE_DIR, and rehearsal copies carry absolute sessionFile paths from the old root; the containment fallback kept those foreign paths, so migration read (and would archive) files in the original root and reported local copies missing. Re-root the canonical agents/<id>/sessions suffix onto the current dir when the file exists there; genuine cross-root layouts still fall through unchanged. * test(agents): seed harness admission through sqlite * fix(sqlite): close agent db on pragma setup failure * fix(doctor): compact and retrofit incremental auto-vacuum after session import The migration is the sanctioned offline window: post-import compact reclaims import churn and applies auto_vacuum=INCREMENTAL to databases created before the fresh-DB pragma existed, so runtime maintenance can release pages in bounded passes on every install. --------- Co-authored-by: Peter Steinberger <steipete@gmail.com>
7.3 KiB
summary, read_when, title
| summary | read_when | title | |
|---|---|---|---|
| Agent runtime, workspace contract, and session bootstrap |
|
Agent runtime |
OpenClaw ships one embedded agent runtime: a built-in agent loop, tool wiring, and prompt assembly, distinct from delegating turns to an external harness process. Each configured agent (see Multi-agent routing for running several) has its own workspace, bootstrap files, and session store. This page covers that runtime contract: what the workspace must contain, which files get injected, and how sessions bootstrap against it.
Workspace (required)
Each agent uses a single workspace directory (agents.defaults.workspace, or
agents.list[].workspace per agent) as its only working directory (cwd)
for tools and context.
Recommended: use openclaw setup to create ~/.openclaw/openclaw.json if missing and initialize the workspace files.
Full workspace layout + backup guide: Agent workspace
If agents.defaults.sandbox is enabled, non-main sessions can override this with
per-session workspaces under agents.defaults.sandbox.workspaceRoot (see
Gateway configuration).
Bootstrap files (injected)
Inside the workspace, OpenClaw expects these user-editable files:
| File | Purpose |
|---|---|
AGENTS.md |
Operating instructions + "memory" |
SOUL.md |
Persona, boundaries, tone |
TOOLS.md |
User-maintained tool notes and conventions |
IDENTITY.md |
Agent name/vibe/emoji |
USER.md |
User profile + preferred address |
HEARTBEAT.md |
Heartbeat-specific instructions |
BOOTSTRAP.md |
One-time first-run ritual (deleted after completion) |
MEMORY.md |
Root long-term memory file, if present |
On the first turn of a new session, OpenClaw injects the contents of these files into the system prompt's Project Context. MEMORY.md is only injected when it exists at the workspace root.
Blank files are skipped. Large files are trimmed and truncated with a marker so prompts stay lean (read the file for full content). A missing file (other than MEMORY.md) injects a single "missing file" marker line instead; openclaw setup creates a safe default template for it.
BOOTSTRAP.md is only created for a brand new workspace (no other bootstrap files present). While it is pending, OpenClaw keeps it in Project Context and adds system-prompt bootstrap guidance for the initial ritual instead of copying it into the user message. If you delete it after completing the ritual, it is not recreated on later restarts.
After a workspace has been observed, OpenClaw also keeps a state-dir attestation marker for the workspace path. If a recently attested workspace disappears or is wiped, startup refuses to silently reseed BOOTSTRAP.md; restore the workspace or use a full onboard reset so the workspace and marker are cleared together.
To disable bootstrap file creation entirely (for pre-seeded workspaces), set:
{ agents: { defaults: { skipBootstrap: true } } }
Built-in tools
Core tools (read/exec/edit/write and related system tools) are always available,
subject to tool policy. apply_patch is on by default for OpenAI models and gated by
tools.exec.applyPatch (enabled, workspaceOnly, allowModels). TOOLS.md does not control which tools exist; it's
guidance for how you want them used.
Skills
OpenClaw loads skills from these locations (highest precedence first):
- Workspace:
<workspace>/skills - Project agent skills:
<workspace>/.agents/skills - Personal agent skills:
~/.agents/skills - Managed/local:
~/.openclaw/skills - Bundled (shipped with the install)
- Extra skill folders:
skills.load.extraDirs
Skill roots can contain grouped folders such as
<workspace>/skills/personal/foo/SKILL.md; the skill is still exposed by its
flat frontmatter name, for example foo.
Skills can be gated by config/env (see skills in Gateway configuration).
Runtime boundaries
The embedded agent runtime is OpenClaw-owned: model discovery, tool wiring, prompt assembly, session management, and channel delivery share one integrated runtime surface.
Sessions
Session rows are stored in the per-agent SQLite database:
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
Transcript JSONL files can still live under
~/.openclaw/agents/<agentId>/sessions/ as legacy migration inputs, deleted or
reset archives, imports, exports, and support artifacts. Active agent history is
stored in SQLite with the session rows. The session ID is stable and chosen by
OpenClaw. OpenClaw does not read session folders from other tools.
Steering while streaming
Inbound prompts that arrive mid-run are steered into the current run by default. Steering is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call, and no longer skips remaining tool calls from the current assistant message.
/queue steer is the default active-run behavior. /queue followup and
/queue collect make messages wait for a later turn instead of steering.
/queue interrupt aborts the active run instead. See Queue
and Steering queue for queue and boundary behavior.
Block streaming sends completed assistant blocks as soon as they finish; it is
off by default (agents.defaults.blockStreamingDefault: "off").
Tune the boundary via agents.defaults.blockStreamingBreak (text_end vs message_end; defaults to text_end).
Control soft block chunking with agents.defaults.blockStreamingChunk (defaults to
800-1200 chars; prefers paragraph breaks, then newlines; sentences last).
Coalesce streamed chunks with agents.defaults.blockStreamingCoalesce to reduce
single-line spam (idle-based merging before send). Non-Telegram channels require
explicit *.blockStreaming: true to enable block replies.
Verbose tool summaries are emitted at tool start (no debounce); Control UI
streams tool output via agent events when available.
More details: Streaming + chunking.
Model refs
Model refs in config (for example agents.defaults.model and agents.defaults.models) are parsed by splitting on the first /.
- Use
provider/modelwhen configuring models. - If the model ID itself contains
/(OpenRouter-style), include the provider prefix (example:openrouter/moonshotai/kimi-k2). - If you omit the provider, OpenClaw tries an alias first, then a unique configured-provider match for that exact model id, and only then falls back to the configured default provider. If that provider no longer exposes the configured default model, OpenClaw falls back to the first configured provider/model instead of surfacing a stale removed-provider default.
Configuration (minimal)
At minimum, set:
agents.defaults.workspacechannels.whatsapp.allowFrom(strongly recommended)