- Image understanding: resolve configured image models such as local LM Studio

vision entries before reporting `Unknown model` when the discovery registry

has not registered that provider. Fixes #66486. Thanks @zhanggpcsu.

- Sessions: separate reset freshness from session-store `updatedAt`, so

heartbeat, cron, exec, and gateway bookkeeping no longer prevent configured

daily/idle resets from rolling long-running channel sessions. Fixes #68315,

#63732, #63820, and #69083. Thanks @maxatv, @longhairedsi, @bradfreels,

and @akessel56.

- CLI/agents: keep `agents bind`, `agents unbind`, and `agents bindings` on

setup-safe channel metadata paths so they do not preload bundled plugin

runtimes or stage runtime dependencies. Fixes #71743.

| Current session | `current` | Bound at creation time | Context-aware recurring work |

| Custom session | `session:custom-id` | Persistent named session | Workflows that build on history |

**Main session** jobs enqueue a system event and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). **Isolated** jobs run a dedicated agent turn with a fresh session. **Custom sessions** (`session:xxx`) persist context across runs, enabling workflows like daily standups that build on previous summaries.

**Main session** jobs enqueue a system event and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). Those system events do not extend daily/idle reset freshness for the target session. **Isolated** jobs run a dedicated agent turn with a fresh session. **Custom sessions** (`session:xxx`) persist context across runs, enabling workflows like daily standups that build on previous summaries.

For isolated jobs, “fresh session” means a new transcript/session id for each run. OpenClaw may carry safe preferences such as thinking/fast/verbose settings, labels, and explicit user-selected model/auth overrides, but it does not inherit ambient conversation context from an older cron row: channel/group routing, send or queue policy, elevation, origin, or ACP runtime binding. Use `current` or `session:<id>` when a recurring job should deliberately build on the same conversation context.

- If the agent should message the user itself, check that the job has a usable

route (`channel: "last"` with a previous chat, or an explicit channel/target).

### Cron or heartbeat appears to prevent `/new`-style rollover

- Daily and idle reset freshness is not based on `updatedAt`; see

[Session management](/concepts/session#session-lifecycle).

- Cron wakeups, heartbeat runs, exec notifications, and gateway bookkeeping may

update the session row for routing/status, but they do not extend

`sessionStartedAt` or `lastInteractionAt`.

- For legacy rows created before those fields existed, OpenClaw can recover

`sessionStartedAt` from the transcript JSONL session header when the file is

still available. Legacy idle rows without `lastInteractionAt` use that

recovered start time as their idle baseline.

### Timezone gotchas

- Cron without `--tz` uses the gateway host timezone.

### Heartbeat

Heartbeat is a periodic main-session turn (default every 30 minutes). It batches multiple checks (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records. Use `HEARTBEAT.md` for a small checklist, or a `tasks:` block when you want due-only periodic checks inside heartbeat itself. Empty heartbeat files skip as `empty-heartbeat-file`; due-only task mode skips as `no-tasks-due`.

Heartbeat is a periodic main-session turn (default every 30 minutes). It batches multiple checks (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records and do not extend daily/idle session reset freshness. Use `HEARTBEAT.md` for a small checklist, or a `tasks:` block when you want due-only periodic checks inside heartbeat itself. Empty heartbeat files skip as `empty-heartbeat-file`; due-only task mode skips as `no-tasks-due`.

See [Heartbeat](/gateway/heartbeat).

read_when:

- You want to understand session routing and isolation

- You want to configure DM scope for multi-user setups

- You are debugging daily or idle session resets

title: "Session management"

---

Sessions are reused until they expire:

- **Daily reset** (default) -- new session at 4:00 AM local time on the gateway

host.

host. Daily freshness is based on when the current `sessionId` started, not

on later metadata writes.

- **Idle reset** (optional) -- new session after a period of inactivity. Set

`session.reset.idleMinutes`.

`session.reset.idleMinutes`. Idle freshness is based on the last real

user/channel interaction, so heartbeat, cron, and exec system events do not

keep the session alive.

- **Manual reset** -- type `/new` or `/reset` in chat. `/new <model>` also

switches the model.

When both daily and idle resets are configured, whichever expires first wins.

Heartbeat, cron, exec, and other system-event turns may write session metadata,

but those writes do not extend daily or idle reset freshness.

Sessions with an active provider-owned CLI session are not cut by the implicit

daily default. Use `/reset` or configure `session.reset` explicitly when those

- **Store:** `~/.openclaw/agents/<agentId>/sessions/sessions.json`

- **Transcripts:** `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`

`sessions.json` keeps separate lifecycle timestamps:

- `sessionStartedAt`: when the current `sessionId` began; daily reset uses this.

- `lastInteractionAt`: last user/channel interaction that extends idle lifetime.

- `updatedAt`: last store-row mutation; useful for listing and pruning, but not

authoritative for daily/idle reset freshness.

Older rows without `sessionStartedAt` are resolved from the transcript JSONL

session header when available. If an older row also lacks `lastInteractionAt`,

idle freshness falls back to that session start time, not to later bookkeeping

writes.

## Session maintenance

OpenClaw automatically bounds session storage over time. By default, it runs

- `per-channel-peer`: isolate per channel + sender (recommended for multi-user inboxes).

- `per-account-channel-peer`: isolate per account + channel + sender (recommended for multi-account).

- **`identityLinks`**: map canonical ids to provider-prefixed peers for cross-channel session sharing.

- **`reset`**: primary reset policy. `daily` resets at `atHour` local time; `idle` resets after `idleMinutes`. When both configured, whichever expires first wins.

- **`reset`**: primary reset policy. `daily` resets at `atHour` local time; `idle` resets after `idleMinutes`. When both configured, whichever expires first wins. Daily reset freshness uses the session row's `sessionStartedAt`; idle reset freshness uses `lastInteractionAt`. Background/system-event writes such as heartbeat, cron wakeups, exec notifications, and gateway bookkeeping can update `updatedAt`, but they do not keep daily/idle sessions fresh.

- **`resetByType`**: per-type overrides (`direct`, `group`, `thread`). Legacy `dm` accepted as alias for `direct`.

- **`parentForkMaxTokens`**: max parent-session `totalTokens` allowed when creating a forked thread session (default `100000`).

- If parent `totalTokens` is above this value, OpenClaw starts a fresh thread session instead of inheriting parent transcript history.

- If the resolved heartbeat target supports typing, OpenClaw shows typing while

the heartbeat run is active. This uses the same target the heartbeat would

send chat output to, and it is disabled by `typingMode: "never"`.

- Heartbeat-only replies do **not** keep the session alive; the last `updatedAt`

is restored so idle expiry behaves normally.

- Heartbeat-only replies do **not** keep the session alive. Heartbeat metadata

may update the session row, but idle expiry uses `lastInteractionAt` from the

last real user/channel message, and daily expiry uses `sessionStartedAt`.

- Control UI and WebChat history hide heartbeat prompts and OK-only

acknowledgments. The underlying session transcript can still contain those

turns for audit/replay.

- **Reset** (`/new`, `/reset`) creates a new `sessionId` for that `sessionKey`.

- **Daily reset** (default 4:00 AM local time on the gateway host) creates a new `sessionId` on the next message after the reset boundary.

- **Idle expiry** (`session.reset.idleMinutes` or legacy `session.idleMinutes`) creates a new `sessionId` when a message arrives after the idle window. When daily + idle are both configured, whichever expires first wins.

- **System events** (heartbeat, cron wakeups, exec notifications, gateway bookkeeping) may mutate the session row but do not extend daily/idle reset freshness.

- **Thread parent fork guard** (`session.parentForkMaxTokens`, default `100000`) skips parent transcript forking when the parent session is already too large; the new thread starts fresh. Set `0` to disable.

Implementation detail: the decision happens in `initSessionState()` in `src/auto-reply/reply/session.ts`.

Key fields (not exhaustive):

- `sessionId`: current transcript id (filename is derived from this unless `sessionFile` is set)

- `updatedAt`: last activity timestamp

- `sessionStartedAt`: start timestamp for the current `sessionId`; daily reset

freshness uses this. Legacy rows may derive it from the JSONL session header.

- `lastInteractionAt`: last real user/channel interaction timestamp; idle reset

freshness uses this so heartbeat, cron, and exec events do not keep sessions

alive. Legacy rows without this field fall back to the recovered session start

time for idle freshness.

- `updatedAt`: last store-row mutation timestamp, used for listing, pruning, and

bookkeeping. It is not the authority for daily/idle reset freshness.

- `sessionFile`: optional explicit transcript path override

- `chatType`: `direct | group | room` (helps UIs and send policy)

- `provider`, `subject`, `room`, `space`, `displayName`: metadata for group/channel labeling

: currentSkillsSnapshot;

if (skillsSnapshot && sessionStore && sessionKey && needsSkillsSnapshot) {

const now = Date.now();

const current = sessionEntry ?? {

sessionId,

updatedAt: Date.now(),

updatedAt: now,

sessionStartedAt: now,

};

const next: SessionEntry = {

...current,

sessionId,

updatedAt: Date.now(),

updatedAt: now,

sessionStartedAt: current.sessionStartedAt ?? now,

skillsSnapshot,

};

await persistSessionEntry({

// Persist explicit /command overrides to the session store when we have a key.

if (sessionStore && sessionKey) {

const now = Date.now();

const entry = sessionStore[sessionKey] ??

sessionEntry ?? { sessionId, updatedAt: Date.now() };

const next: SessionEntry = { ...entry, sessionId, updatedAt: Date.now() };

sessionEntry ?? { sessionId, updatedAt: now, sessionStartedAt: now };

const next: SessionEntry = {

...entry,

sessionId,

updatedAt: now,

sessionStartedAt: entry.sessionStartedAt ?? now,

lastInteractionAt: now,

};

if (thinkOverride) {

next.thinkingLevel = thinkOverride;

}

fallbackProvider,

fallbackModel,

result,

touchInteraction:

opts.bootstrapContextRunKind !== "cron" &&

opts.bootstrapContextRunKind !== "heartbeat" &&

!opts.internalEvents?.length,

});

sessionEntry = sessionStore[sessionKey] ?? sessionEntry;

}

expect(persisted[sessionKey]?.estimatedCostUsd).toBeCloseTo(0.25, 4);

});

});

it("preserves lastInteractionAt for non-interactive system runs", async () => {

await withTempSessionStore(async ({ storePath }) => {

const cfg = {} as OpenClawConfig;

const sessionKey = "agent:main:explicit:test-system-run";

const sessionId = "test-system-run-session";

const lastInteractionAt = Date.now() - 60 * 60_000;

const sessionStartedAt = Date.now() - 2 * 60 * 60_000;

const sessionStore: Record<string, SessionEntry> = {

[sessionKey]: {

sessionId,

updatedAt: Date.now() - 10_000,

sessionStartedAt,

lastInteractionAt,

},

};

await fs.writeFile(storePath, JSON.stringify(sessionStore, null, 2));

await updateSessionStoreAfterAgentRun({

cfg,

sessionId,

sessionKey,

storePath,

sessionStore,

defaultProvider: "openai",

defaultModel: "gpt-5.4",

result: {

meta: {

durationMs: 1,

agentMeta: {

sessionId,

provider: "openai",

model: "gpt-5.4",

},

},

},

touchInteraction: false,

});

expect(sessionStore[sessionKey]?.lastInteractionAt).toBe(lastInteractionAt);

expect(sessionStore[sessionKey]?.sessionStartedAt).toBe(sessionStartedAt);

expect(sessionStore[sessionKey]?.updatedAt).toBeGreaterThan(lastInteractionAt);

});

});

it("advances lastInteractionAt for interactive runs", async () => {

await withTempSessionStore(async ({ storePath }) => {

const cfg = {} as OpenClawConfig;

const sessionKey = "agent:main:explicit:test-user-run";

const sessionId = "test-user-run-session";

const lastInteractionAt = Date.now() - 60 * 60_000;

const sessionStore: Record<string, SessionEntry> = {

[sessionKey]: {

sessionId,

updatedAt: Date.now() - 10_000,

lastInteractionAt,

},

};

await fs.writeFile(storePath, JSON.stringify(sessionStore, null, 2));

await updateSessionStoreAfterAgentRun({

cfg,

sessionId,

sessionKey,

storePath,

sessionStore,

defaultProvider: "openai",

defaultModel: "gpt-5.4",

result: {

meta: {

durationMs: 1,

agentMeta: {

sessionId,

provider: "openai",

model: "gpt-5.4",

},

},

},

});

expect(sessionStore[sessionKey]?.lastInteractionAt).toBeGreaterThan(lastInteractionAt);

});

});

});

describe("clearCliSessionInStore", () => {

fallbackProvider?: string;

fallbackModel?: string;

result: RunResult;

touchInteraction?: boolean;

}) {

const {

cfg,

fallbackModel,

result,

} = params;

const now = Date.now();

const touchInteraction = params.touchInteraction !== false;

const usage = result.meta.agentMeta?.usage;

const promptTokens = result.meta.agentMeta?.promptTokens;

const entry = sessionStore[sessionKey] ?? {

sessionId,

updatedAt: Date.now(),

updatedAt: now,

sessionStartedAt: now,

};

const next: SessionEntry = {

...entry,

sessionId,

updatedAt: Date.now(),

updatedAt: now,

sessionStartedAt: entry.sessionId === sessionId ? (entry.sessionStartedAt ?? now) : now,

lastInteractionAt: touchInteraction ? now : entry.lastInteractionAt,

contextTokens,

};

setSessionRuntimeModel(next, {