6a9bccad9e
* fix(agents): preserve prompt caches across midnight
Move current date and timezone from the system prompt to the existing per-turn runtime context, preserving date grounding without invalidating positional history caches. Cover midnight rollover and resumed CLI turns, and isolate the touched source-delivery fixture from shared temporary session databases.
Fixes #148304
* test(agents): align isolated source-delivery fixture with main
Keep the independently landed fixture isolation from 22bca7d84d in the same form to avoid a merge conflict. Prompt behavior is unchanged.
* fix: retain temporal context for prompt prefix reuse
* test: expect retained runtime context for native Ollama
* test: preserve idle facts expectations for code mode fixture
3.5 KiB
| summary | read_when | title | ||
|---|---|---|---|---|
| Date and time handling across envelopes, prompts, tools, and connectors |
|
Date and time |
OpenClaw uses the configured user timezone for message envelopes, system events, and
per-turn runtime context. When agents.defaults.userTimezone is unset, those surfaces use the
host timezone. Provider timestamps are preserved so tools keep their native semantics.
When the agent needs the exact current time and session_status is available, it runs that tool.
Message envelopes (local by default)
Inbound messages are wrapped with a weekday plus second-precision timestamp:
[WhatsApp +1555 Mon 2026-01-05 16:26:34 PST] message text
Envelope timestamps use agents.defaults.userTimezone when configured, otherwise the
host timezone. Absolute timestamps and elapsed-time suffixes are built in.
Examples
Local (default):
[WhatsApp +1555 Sun 2026-01-18 00:19:42 PST] hello
User timezone:
[WhatsApp +1555 Sun 2026-01-18 00:19:42 CST] hello
Elapsed time:
[WhatsApp +1555 +30s Sun 2026-01-18 00:20:12 CST] follow-up
Runtime context: date and time zone
Each turn receives a Temporal Context section with the local calendar date and time zone, outside the system prompt and without a live clock:
Current date: 2026-01-05
Time zone: America/Chicago
The zone is agents.defaults.userTimezone when configured, otherwise the host timezone.
The section travels in the current-turn runtime context without rewriting earlier messages, so
date rollover preserves the complete system prompt and conversation-history prefix for caching.
Chat Completions and native Ollama retain the hidden turn context in history by default; an
explicit provider replay policy can override that behavior. Normal compaction budgets still apply.
Raw model probes omit OpenClaw runtime context. When available, session_status remains the source
for exact current time.
System event lines (local by default)
Queued system events inserted into agent context use agents.defaults.userTimezone when
configured, otherwise the host timezone.
System: [2026-01-12 12:19:17 PST] Model switched.
Configure user timezone
{
agents: {
defaults: {
userTimezone: "America/Chicago",
},
},
}
userTimezonesets the user-local timezone for message envelopes, system events, and prompt context.- Use an IANA timezone such as
America/Chicago,Europe/Vienna, orAsia/Tokyo.
Time format detection
Rendered clock values follow the operating system and locale preference. OpenClaw detects 12-hour or 24-hour display on macOS and Windows, then falls back to locale formatting. The detected value is cached per process.
Tool payloads + connectors (raw provider time + normalized fields)
Channel tools return provider-native timestamps and add normalized fields for consistency:
timestampMs: epoch milliseconds (UTC)timestampUtc: ISO 8601 UTC string
Raw provider fields are preserved so nothing is lost.
- Discord: UTC ISO timestamps
- Slack: epoch-like strings from the API
- Telegram/WhatsApp: provider-specific numeric/ISO timestamps
If you need local time, convert it downstream using the known timezone.