#Session restart
1 messages · Page 1 of 1 (latest)
True
No â a Gateway restart (hot reload or manual restart) does not automatically mint a new session.
Sessions are persisted on disk (~/.openclaw/agents/<agentId>/sessions/sessions.json + JSONL transcripts), so after a restart the Gateway will continue the same session for that chat unless your normal reset policy says itâs stale (idle timeout / daily reset) or you explicitly reset it with /new or /reset. Source: https://docs.openclaw.ai/concepts/session and https://docs.openclaw.ai/help/faq#do-sessions-reset-automatically-if-i-never-send-new
One important caveat: if the Gateway restarts mid-run, that in-flight run is interrupted/lost â you may need to resend the last message, but itâll still be in the same session context.
Yep â restart by itself doesnât rotate the session.
A new session only happens if:
- you hit the reset policy (idle/daily), or
- you explicitly
/new//reset.
If youâre debugging, /status will also tell you which session youâre currently in + last update timing.
is there a way to start the gateway AND initiate a new session at the same time? Reason: if the agent changes configuration and fails, you have to manually fix that and restart the gateway. But that means that the agent thinks its changes are persitedâŠ
There isnât (currently) a single built-in âgateway restart and /new this chatâ one-liner, but youâve got a couple solid ways to get the effect you want:
Option A (simplest): restart, then send /new in the chat
After you fix config + restart the Gateway, send /new (or /reset) as a standalone message in the same Discord thread/channel/DM. That guarantees the agent wonât keep the old âI already changed Xâ narrative in-context.
Docs (session reset triggers): https://docs.openclaw.ai/concepts/session
Option B (scriptable): restart, then RPC-reset the session from the CLI
Thereâs a low-level Gateway RPC for this: sessions.reset.
- Restart:
openclaw gateway restart
- Find the session key you want to reset (pick one):
- In the chat:
/status(usually shows the session key), or
- From shell:
openclaw sessions --active 120 --json
# or:
openclaw gateway call sessions.list --params '{}'
- Reset it:
openclaw gateway call sessions.reset --params '{"key":"<PASTE_SESSION_KEY>","reason":"reset"}'
The reason can be "reset" or "new". Source: the Gateway method exists as sessions.reset and is the same mechanism the TUI uses. (CLI âgateway callâ doc: https://docs.openclaw.ai/cli/gateway)
Why this helps your specific problem
Youâre right: if a run thought it persisted changes, but the Gateway died before the write actually happened (or you reverted manually), the chat transcript can leave the model with a false belief.
Resetting the session fixes the modelâs context.
Separately, a good habit is to have the agent verify after any config mutation (e.g. re-read the file / run openclaw config get ...) so it canât hallucinate âpersistedâ state even without a reset.
If you tell me which surface youâre talking about (Discord thread vs DM vs TUI), I can point you at the most reliable way to identify the exact session key to reset.
probably either discord or telegramâŠ
If itâs Discord or Telegram, you can usually avoid guessing the key entirely:
Easiest (works on both): restart â then send /new in that same chat/thread
That guarantees a fresh session for that conversation, no CLI needed.
If you want to do it from the Gateway host (scriptable): sessions.reset
- Restart gateway:
openclaw gateway restart
- Find the session key (pick one):
- In the chat: send
/status(it typically shows the session key), or - From shell:
openclaw sessions --active 120 --json
# or:
openclaw gateway call sessions.list --params '{}'
- Reset it:
openclaw gateway call sessions.reset --params '{"key":"<PASTE_KEY_HERE>","reason":"reset"}'
Docs for gateway call: https://docs.openclaw.ai/cli/gateway
Session key semantics: https://docs.openclaw.ai/concepts/session
What the keys usually look like
Discord
- Server channel:
agent:<agentId>:discord:channel:<channelId> - Thread (common in forum/help threads):
agent:<agentId>:discord:channel:<parentChannelId>:thread:<threadId>
(Discord doc mentions the channel form explicitly.) Source: https://docs.openclaw.ai/channels/discord
Telegram
- Group:
agent:<agentId>:telegram:group:<chatId> - Forum topic:
agent:<agentId>:telegram:group:<chatId>:topic:<threadId>
Source: https://docs.openclaw.ai/channels/telegram (forum topics section)
If you tell me which one youâre actually using right now (Discord thread vs Discord channel vs Telegram DM/topic), I can give you the exact âget the key â reset itâ commands without any ambiguity.
I can't tell. I want to script it! So I need to know the Session which changed the configâŠ
Youâre thinking about it the right way, but one key constraint:
OpenClaw doesnât keep a durable âthis config change came from session Xâ pointer. Config is global; sessions are just conversation state. So if you truly âcanât tell which chat you usedâ, thereâs no perfect way for a script to know the exact one.
That said, you can script this reliably with either (A) an explicit target (chat id / label), or (B) âmost recently active sessionâ.
A) Deterministic: reset the session by chat id (Discord channel/thread id or Telegram chat id)
1) List sessions and search for the id
sessions.list supports a search field, and session keys/labels usually include the channel + id.
ID="1481706020995596478" # discord channel/thread id OR telegram chat id
openclaw gateway call sessions.list --params "{\"search\":\"$ID\",\"limit\":20}" --json
2) Pick the matching .sessions[].key and reset it
If you have jq:
KEY=$(
openclaw gateway call sessions.list --params "{\"search\":\"$ID\",\"limit\":20}" --json \
| jq -r '.sessions | sort_by(.updatedAt // 0) | last | .key'
)
openclaw gateway call sessions.reset --params "{\"key\":\"$KEY\",\"reason\":\"reset\"}" --json
This works whether itâs Discord or Telegram, as long as you know the numeric ID.
Discord key shapes (for reference):
- Channel:
agent:<agentId>:discord:channel:<channelId> - Thread often:
agent:<agentId>:discord:channel:<parentChannelId>:thread:<threadId>
Source: https://docs.openclaw.ai/channels/discord
Telegram topics:
agent:<agentId>:telegram:group:<chatId>:topic:<threadId>
Source: https://docs.openclaw.ai/channels/telegram
B) Pragmatic: âreset the most recently active sessionâ
If your setup is basically single-user and you just want âwhatever I was talking to right before the crashâ:
KEY=$(
openclaw gateway call sessions.list --params '{"limit":50}' --json \
| jq -r '.sessions | map(select(.kind!="global")) | sort_by(.updatedAt // 0) | last | .key'
)
openclaw gateway call sessions.reset --params "{\"key\":\"$KEY\",\"reason\":\"reset\"}" --json
If your real goal is âdonât let the agent believe config changes persistedâ
A reset helps, but the robust fix is: after any restart, have your workflow re-read the config from disk (or run openclaw config get âŠ) before continuing. Otherwise even a fresh session can still make incorrect assumptions.
If you tell me what youâre using to âchange configâ (agent editing openclaw.json vs config.apply vs openclaw config set), I can suggest the cleanest pattern to log/record the session key at change time so your script is 100% deterministic.
The problem is when the agent decides to change the config. I like pragmatic b), but is there a way to exclude Cron-sessions? That would be pretty sound, I thinkâŠ
Yep â you can exclude cron cleanly.
A couple nuances from the implementation:
sessions.listalready drops cron run sessions shaped like:
agent:<agentId>:cron:<jobId>:run:<runId>(those wonât show up)- But you can still have cron âjobâ sessions shaped like:
agent:<agentId>:cron:<jobId>
If you want to exclude those too, filter by:cron:.
Pragmatic âreset most recent human chat session, excluding cronâ
KEY=$(
openclaw gateway call sessions.list --params '{"limit":200}' --json \
| jq -r '
.sessions
| map(select(.kind != "global"))
| map(select(.key | test("^agent:[^:]+:cron:") | not))
| sort_by(.updatedAt // 0)
| last
| .key
'
)
openclaw gateway call sessions.reset --params "{\"key\":\"$KEY\",\"reason\":\"reset\"}" --json
That test("^agent:[^:]+:cron:") catches both:
agent:main:cron:<jobId>agent:main:cron:<jobId>:run:<runId>(even though run-keys are already filtered out upstream)
If you also want, you can extend the filter to exclude other non-conversation keys (like discord:slash: command sessions, hook:, etc.), but cron-only is a good start.
Well, the agent does not always tell when it changed the config and restarted the gateway⊠so, how should I tell it to reload config? Would have to do it in AGENTS.md or is a skill the better idea? Both are probably not 100% reliableâŠ
âReload configâ is kind of two different things:
- The Gateway reloading config â that already happens on hot-reload / restart (that part is deterministic).
- The model updating its beliefs about what the config is â thatâs the part that drifts, and you fix it by forcing a re-read/verify step.
What Iâd do (most reliable, minimal moving parts): put a hard rule in AGENTS.md
A skill is less reliable here because skills can be gated/omitted; AGENTS.md is always injected.
Add something like this to AGENTS.md:
- If you are about to change config: announce it
- After any config change (or any gateway restart): verify reality by re-reading config from the gateway, then summarize whatâs actually set
- Never rely on âI changed it earlierâ from chat history
Concrete verification command that works well:
openclaw gateway call config.get --json
openclaw gateway status
(So the agent anchors on tool output, not memory.)
If you also want to know when the gateway restarted: use BOOT.md + the boot-md hook
This is the âdonât rely on the agent remembering to tell meâ option.
- Enable internal hooks + boot hook:
{
hooks: {
internal: {
enabled: true,
entries: { "boot-md": { enabled: true } },
},
},
}
Then create a BOOT.md that does a tiny deterministic routine on startup, e.g.:
- run
openclaw gateway call config.get --json - send you a message like âGateway restarted; config snapshot checked; if you were mid-config-change, start fresh (/new)â.
Docs: https://docs.openclaw.ai/automation/hooks#boot-md
Honest limitation
Thereâs no 100% reliable way for the model to infer âI changed config in Discord vs Telegramâ after a crash unless you:
- funnel config/ops through a single âadmin chatâ, or
- have an external mechanism (hook/script) that records âlast config mutation came from session key Xâ.
If you want, I can suggest a very small âops disciplineâ pattern that makes it deterministic (e.g., always do config changes in one thread/DM, and auto-/new that one on startup via BOOT.md).
The reason I am asking this⊠I am working on a watchdog for Linux installations that monitors config changes, saves good configs to a vault and reverts bad configs to the last known good one. When it reverts a change, it writes diagnostics to a MD-File in the workspace. I can get the agent to read this file on session start, but not anytime. Ah! Boot.md is a good hint.
Yes, please suggest the âops disciplineâ pattern!
Hereâs an âops disciplineâ pattern that ends up practical for exactly your watchdog setup (and avoids relying on the model ârememberingâ things).
The core idea
Make config ops happen in one deterministic place (one agent + one chat), and make your watchdog the source of truth when it reverts.
That gives you:
- a fixed session key you can always reset
- a fixed alert file the agent always checks when it matters
- a fixed notification path so the agent sees alerts immediately, not only âon next session startâ
1) Create a dedicated âops agentâ + one admin chat
Do not do config changes from random Discord channels/Telegram chats. Pick one:
- Discord: a private
#opschannel (or a single thread you keep using) - Telegram: your DM with the bot
Route that chat to an agent like agentId: "ops" (separate workspace is even better).
Why: your watchdog can now hardcode exactly one session key to reset, and exactly one place to notify.
Docs (Discord session keys): https://docs.openclaw.ai/channels/discord
2) Establish a âtransactionâ rule for config changes (AGENTS.md for the ops agent)
In the ops agentâs AGENTS.md, add a rule like:
- Before changing config: read current config (
openclaw gateway call config.get --json) and state what youâre changing. - Apply change.
- After change: read config again and run
openclaw gateway status/ quick health checks. - If any step fails: stop and report; donât âassume it stuckâ.
This converts âbeliefâ into âverified by tool outputâ.
(Youâre right itâs not 100% â but it eliminates a lot of drift.)
3) Make watchdog ârevertsâ wake the ops agent immediately (not just via a file)
Writing diagnostics to a workspace .md file is great â but the agent wonât see it until you prompt it.
So when the watchdog reverts, do both:
- Write your diagnostic file, e.g.
ops/alerts/last-revert.md(overwrite)- optionally append to
ops/alerts/history.md
- Send a message into the ops chat that says something like:
âWATCHDOG: reverted config to last-known-good. Read ops/alerts/last-revert.mdâ
That message is what forces an agent run now, so it can read the file now.
If you donât want to integrate directly with Discord/Telegram APIs, another clean option is: watchdog calls the Gateway RPC message.send (or uses openclaw message send ...) from the host. Either way: send one small message only on revert (rare), so itâs not spammy.
4) On revert, also reset the ops session (your earlier idea, automated)
This is where your earlier sessions.reset work pays off.
Because ops happens in one chat, your watchdog can hardcode one âreset targetâ (or resolve it by search) and do:
- revert config
- restart gateway
sessions.resetthat ops chat session key- then send the watchdog alert message (which starts a clean session)
That eliminates the âagent thinks its old config change persistedâ failure mode almost completely.
5) Use BOOT.md + boot-md as the secondary safety net
Enable the boot-md hook and add a tiny BOOT.md that does:
- check if
ops/alerts/last-revert.mdexists / changed since last ack - if yes, send a short notification to the ops chat
This covers: âgateway restarted and the watchdog already reverted, but no message got throughâ.
Docs: https://docs.openclaw.ai/automation/hooks#boot-md
Minimal concrete file convention (recommended)
ops/alerts/last-revert.md(always overwritten; contains the latest incident)ops/alerts/history.md(append-only)ops/alerts/ack.json(stores last-ack timestamp/hash; watchdog can manage it, not the model)
Then the agentâs instruction is simple: always read ops/alerts/last-revert.md when you see an ops alert message (or on BOOT).
Quick question (so I can make this fully concrete)
On Linux, will your watchdog be able to run openclaw ... commands locally on the gateway host (same user / same env), or is it running as root/another user?
If it can run openclaw, I can give you an exact ârevert â restart â reset ops session â send alertâ shell snippet that doesnât depend on jq too heavily.
Yes, watchdog can run openclaw - and it does for verification reasons.
Why should I use a dedicated ops-channel? Isnât the BOOT.md enough? It could contain something like âif you tried to change config - you just failed! Read NOTIFOCATION.md to learn what happened!â. What do you think? I guess the boot-hook is pretty reliable to get the agent to read it⊠so it would be beneficial if the session continues after gateway resetâŠ
A dedicated ops channel isnât strictly required, but it solves a bunch of hard problems that BOOT.md alone canât, especially once you have multiple chats and an automated watchdog in the mix.
Why BOOT.md alone is not enough
-
BOOT.md only runs on gateway startup (via the
boot-mdhook).
If your watchdog reverts a config while the gateway stays up (or you hot-reload without a full restart), BOOT.md wonât fire. -
BOOT.md doesnât know âwhich session was doing config ops.â
Your idea (âif you tried to change config â you failed!â) is inherently ambiguous. The gateway may have restarted for unrelated reasons (deploy/update/reboot/crash), and BOOT.md has no reliable way to identify the culprit session unless you give it a single, well-known target chat to notify. -
boot-md runs BOOT.md through the agent runner (LLM).
Itâs pretty good, but not deterministic. If your model auth is broken (which is a common âbad configâ symptom) you can get exactly the situation where you most need the notification⊠and the BOOT.md run canât complete.
So BOOT.md is best as a backup / safety net, not the primary control plane.
What a dedicated ops channel buys you (practically)
- Deterministic notification target
Your watchdog can always do:
-
revert config
- restart gateway
- reset exactly one session key (the ops chat)
- send exactly one message (âreverted; read diagnostics fileâ)
No guessing. No âmost recent non-cron sessionâ heuristics.
-
Keeps ops noise out of normal chats
If youâre chatting in Discord/Telegram about unrelated things, you donât want surprise âconfig revertedâ or auto-/newmessages showing up there. -
Security / blast-radius reduction
If you ever talk to the agent in a public-ish Discord channel, the last thing you want is a prompt-injection path that leads to âedit config + restart gatewayâ. Keeping config ops in one private/admin chat makes it much easier to lock down policy elsewhere.
A pattern thatâs hard to beat (hybrid)
- Primary path: watchdog sends a message to the ops channel only when it reverts (rare), and optionally resets that ops session.
- Backup path: BOOT.md checks for
ops/alerts/last-revert.mdand pings the ops channel on startup if thereâs an unacked alert.
That gives you reliability even when:
- the revert happened right before a crash/restart
- the model is partially broken
- you forgot you were doing config work in some other thread
âBeneficial if the session continues after gateway resetâ⊠yes, but:
Continuing the same session is only beneficial if the modelâs beliefs match reality. In your scenario, the whole issue is âbelief drift after a revertâ.
So the usual best practice is:
- persist the truth in files (your diagnostics MD + maybe a small âchange logâ the watchdog appends to)
- feel free to reset the ops session aggressively, because the durable record is now the workspace, not the chat transcript
If you tell me what you want to use as the ops channel (Discord channel ID or Telegram DM/chat id), I can give you a concrete watchdog flow like:
- validate new config
- if bad: revert + write diagnostics
openclaw gateway restart
sessions.resetfor the ops session keyopenclaw message sendto ops channel with a short alert pointing at the MD file
The problem with the ops-channel I see is that i cannot ensure the ONLY the ops channel makes changes to the config. If any agent session does change the config (adding tokens for discord or telegram for example), this session will still believe in wrong chats and the notified ops-channel does not know what it should do with the notificationâŠ
You actually can get pretty close to âonly ops can mutate configâ, but you need hard enforcement, not just etiquette.
1) First: stop chat-initiated config writes entirely (removes a big class of surprise edits)
If the ârandom session changed configâ is coming from /config set|unset etc, turn those off at the channel level:
{
channels: {
discord: { configWrites: false },
telegram: { configWrites: false },
},
}
Docs: Discord âConfig writesâ section + config reference note that channels.<provider>.configWrites gates channel-initiated config mutations.
That alone means: a Discord/Telegram conversation canât silently mutate config via command features.
2) Then: make it impossible for non-ops chats to do âedit file + restartâ style changes
Even with configWrites:false, the model could still mutate config via tools (e.g. exec running openclaw config set, or write to ~/.openclaw/openclaw.json) unless you block those tools where you donât want them.
OpenClaw supports per-channel tool restrictions (deny wins), e.g. for Discord guild channels. The docs call this out here:
https://docs.openclaw.ai/channels/groups#groupchannel-tool-restrictions-optional
So the pattern is:
- default for all channels: deny
exec/write/edit(whatever would let it change config) - for the one ops channel: allow them back (optionally only for your sender id via
toolsBySender)
Thatâs the âonly ops channel can do dangerous stuffâ guarantee youâre looking for.
3) âBOOT.md is enoughâ â itâs a good backup, but it doesnât solve attribution
BOOT.md can tell the agent âhey, something bad happened, read NOTIFICATION.mdâ, but:
- it only runs on gateway startup
- it doesnât reliably tell you which chat/session caused the bad config
- itâs LLM-executed (boot-md runs BOOT.md via the agent runner), so it can fail in exactly the scenarios where config is broken
So BOOT.md is great as a safety net, not as your primary mechanism.
4) If you truly allow any session to change config, you need a âtransaction markerâ
If you want to allow config mutations from any chat, the only robust way to avoid âwrong chat believes wrong thingâ is to force every config change attempt to leave a breadcrumb your watchdog can use, e.g.:
- agent writes
ops/pending-config-change.jsonbefore applying (includes timestamp + channel + chat/thread id + what it tried to change) - watchdog reads that file when it reverts and can then:
- reset that exact session key (using the search-by-id trick), and/or
- send the revert notification back to that same chat
Thatâs more complex than âops channel onlyâ, but itâs the deterministic fix.
5) The simplest robust architecture for your watchdog
- watchdog is the only writer of
openclaw.json(plus restarts)
- agent can suggest changes anywhere, but canât apply them except in ops
- watchdog posts revert diagnostics to ops channel + resets ops session
If you want, paste which surface you want as ops (Discord channel/thread ID is perfect), and Iâll write you the exact watchdog sequence (commands + a jq-less fallback) to:
- detect change â validate â snapshot to vault
- on failure: revert â restart gateway
- reset ops session (excluding cron) â send one alert message pointing to your MD diagnostics
I donât want hot-reload anyway, as the agent atm does not know this and restarts the gateway anyway (adding tokens trouble atmâŠ). So my idea is to disable hot-reload at deployment and make the watchdog disallow changing this⊠this way, I can make sure in case of failure the gateway definitely is restarted. Will BOOT.md work then? I donât see the agent runner as a real problem. Either there is a LLM that can take care of the information or the gateway wonât start anywayâŠ
Disabling hot-reload so that every config change implies a full restart is a sane watchdog-friendly approach.
Will BOOT.md work in that setup?
Yes â if the gateway actually reaches âstartedâ state. The boot-md hook runs on gateway startup (after channels start), so a restart-driven workflow is exactly when BOOT.md is most useful.
But there are two important caveats:
-
If the gateway canât start at all, BOOT.md wonât run.
Syntax errors / invalid JSON5 / missing required fields / crash during early init = no hooks, no BOOT. -
Gateway can start even when the LLM is broken.
Your âeither an LLM can take care of it or the gateway wonât start anywayâ assumption isnât always true. A very common failure mode is:- gateway + channels come up fine
- model auth is broken / rate-limited / misconfigured
- BOOT.md runs via the agent runner, so it may fail to send the âhereâs what happenedâ message precisely when you need it.
So: BOOT.md is a great âpost-start notifierâ, but it shouldnât be your only alarm path.
The more robust pattern (since your watchdog can run openclaw)
Use BOOT.md as backup, but make the watchdog the primary notifier:
- On revert, watchdog should:
- write diagnostics MD into workspace
openclaw gateway restart- reset the ops session (or âmost recent non-cron sessionâ heuristic)
- send a message to your ops chat with a short summary + link/path to the diagnostics MD
Critically: openclaw message send doesnât require an LLM, so you still get alerts even if model auth is broken.
About disabling hot reload
If you want ârestart alwaysâ, set the reload mode accordingly and have the watchdog enforce it. (Docs mention gateway.reload.mode with default "hybrid"; youâd choose a mode that always restarts.)
Even if you do that, Iâd still keep the watchdog-driven notification, because itâs the only piece that remains reliable when models are down but the gateway is up.
If you tell me whether your ops chat is Discord or Telegram (and the target id format you prefer), I can sketch the exact watchdog command sequence (including sessions.reset + message send) thatâs LLM-independent.
You are right, but if the model does not come up, there is nothing that could take care of the message or the problem or whatever else⊠the agent just is not operational at allâŠ
Totally fair: if no model is usable, the agent canât âthinkâ or run tool plans â itâs effectively down.
But two important points for your watchdog design:
1) You still want a message even when the agent is down
Because âagent is downâ is exactly the kind of failure you want to surface to the operator.
Your watchdog can still:
- revert config to last-known-good
- restart the gateway
- send you an alert via
openclaw message send âŠ
That outbound send path does not require an LLM run. It wonât magically fix the world, but it gives you:
- visibility (âitâs down because Xâ)
- a breadcrumb trail (where diagnostics MD lives)
- confirmation that the watchdog took action (reverted/restarted)
2) âModel didnât come upâ is often recoverable even if it isnât âfixableâ automatically
Common cases: expired key, missing env var after service restart, provider outage, quota/rate limit. Your watchdog canât negotiate billing, but it can keep the system in a known-good config and tell you what broke.
If you want the system to be less âall-or-nothingâ, the real fix is configuring model/provider failover so one outage doesnât brick the agent. (Docs: https://docs.openclaw.ai/concepts/models)
Practical recommendation
Use BOOT.md/boot-md as a nice-to-have when models are healthy, but treat watchdog-sent notifications as the reliable channel for incidents â including âLLM unavailableâ.
If you tell me which channel you want the watchdog to notify (Discord channel id vs Telegram chat id), I can give you a concrete alert command you can drop into the revert path.
You are right. Itâs an important information that the gateway still can send messages without the need for an active agent! Will have to think about thisâŠ