#Session restart

1 messages · Page 1 of 1 (latest)

jovial radish
#

If the gateway restarts (hot reload or manual restart) does this automatically trigger a new session for the agent?

brittle moonBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

devout prism
#

True

graceful widgetBOT
#

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.

jovial radish
#

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


graceful widgetBOT
#

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.

  1. Restart:
openclaw gateway restart
  1. 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 '{}'
  1. 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.

jovial radish
#

probably either discord or telegram


graceful widgetBOT
#

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

  1. Restart gateway:
openclaw gateway restart
  1. Find the session key (pick one):
  • In the chat: send /status (it typically shows the session key), or
  • From shell:
#

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.

jovial radish
#

I can't tell. I want to script it! So I need to know the Session which changed the config


graceful widgetBOT
#

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:


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.

jovial radish
#

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


graceful widgetBOT
#

Yep — you can exclude cron cleanly.

A couple nuances from the implementation:

  • sessions.list already 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.

jovial radish
#

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


graceful widgetBOT
#

“Reload config” is kind of two different things:

  1. The Gateway reloading config — that already happens on hot-reload / restart (that part is deterministic).
  2. 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).

jovial radish
#

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!

graceful widgetBOT
#

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 #ops channel (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:

  1. Write your diagnostic file, e.g.
  • ops/alerts/last-revert.md (overwrite)
  • optionally append to ops/alerts/history.md
  1. 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.reset that 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.md exists / 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.

jovial radish
#

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


graceful widgetBOT
#

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

  1. BOOT.md only runs on gateway startup (via the boot-md hook).
    If your watchdog reverts a config while the gateway stays up (or you hot-reload without a full restart), BOOT.md won’t fire.

  2. 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.

  3. 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)

  1. 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.

  1. 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-/new messages showing up there.

  2. 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.md and 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:

  1. validate new config
  2. if bad: revert + write diagnostics
  3. openclaw gateway restart
#
  1. sessions.reset for the ops session key
  2. openclaw message send to ops channel with a short alert pointing at the MD file
jovial radish
#

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


graceful widgetBOT
#

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.json before 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
jovial radish
#

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


graceful widgetBOT
#

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:

  1. 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.

  2. 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:
    1. write diagnostics MD into workspace
    2. openclaw gateway restart
    3. reset the ops session (or “most recent non-cron session” heuristic)
    4. 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.

jovial radish
#

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


graceful widgetBOT
#

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.

jovial radish
#

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