Date and Time Handling in OpenClaw Envelopes and Prompts
Learn how OpenClaw applies timezones to message envelopes and system prompts. This page is for developers configuring user timezone settings for accurate temporal context.
Read this when
- You are changing how timestamps are shown to the model or users
- You are debugging time formatting in messages or system prompt output
OpenClaw applies the configured user timezone when building message envelopes, system events, and the system prompt. If agents.defaults.userTimezone is not set, the host timezone is used in those places. Provider timestamps remain untouched so tools keep their original semantics. When the agent requires the exact current time and session_status is present, that tool gets executed.
Message envelopes (local by default)
Incoming messages get a weekday and a timestamp accurate to the second:
[WhatsApp +1555 Mon 2026-01-05 16:26:34 PST] message text
Envelope timestamps rely on agents.defaults.userTimezone if it is configured; otherwise the host timezone applies. Absolute timestamps and elapsed-time suffixes are generated automatically.
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
System prompt: temporal context
A volatile Temporal Context section, holding the local calendar date and time zone but no live clock, is part of the system prompt:
Current date: 2026-01-05
Time zone: America/Chicago
The zone comes from agents.defaults.userTimezone when configured, falling back to the host timezone otherwise. This section sits below the prompt-cache boundary, so date rollover or timezone shifts do not disturb the stable prefix. If available, session_status stays the authoritative source for the exact current time.
System event lines (local by default)
System events queued and 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",
},
},
}
- Message envelopes, system events, and prompt context all honor the user-local timezone set by
userTimezone. - Pick an IANA timezone like
America/Chicago,Europe/Vienna, orAsia/Tokyo.
Time format detection
Rendered clock values follow the operating system and locale preferences. OpenClaw determines whether to show 12-hour or 24-hour time on macOS and Windows, then falls back to locale-based formatting. The result is cached for each process.
Tool payloads + connectors (raw provider time + normalized fields)
Channel tools deliver provider-native timestamps and add normalized fields for uniformity:
timestampMs: epoch milliseconds (UTC)timestampUtc: ISO 8601 UTC string
Raw provider fields are kept intact, so no data is lost.
- Discord: UTC ISO timestamps
- Slack: epoch-like strings from the API
- Telegram/WhatsApp: provider-specific numeric/ISO timestamps
For local time, convert downstream using the known timezone.