Timezones in OpenClaw

Every channel has its own idea of time, and a model fed a mix of provider-local clocks makes date mistakes. OpenClaw standardises timestamps so the model sees a single reference time. The docs describe three surfaces where a timezone shows up, each with its own purpose, and one setting that governs two of them. Here are the surfaces, the setting, how the host zone is resolved when nothing is configured, why the date lives below the prompt cache boundary, and why the live clock is deliberately left out.

Three surfaces

• Message envelopes wrap inbound channel messages with the channel, the sender, the weekday, the date, the time and the zone abbreviation, in the host timezone unless a user timezone is set.
• Tool payloads from the message-reading channel tools return the raw provider time plus normalised UTC fields, a millisecond timestamp and a UTC string, always present and not configurable, so provider-native timestamps are preserved.
• The system prompt carries a volatile temporal context block with the local date and time zone, again in the host timezone unless a user timezone is set; the exact time stays tool-backed.
• Clock rendering follows the host operating system and locale preference; there is no separate twelve-hour or twenty-four-hour setting.

OpenClaw standardizes timestamps so the model sees a single reference time instead of a mix of provider-local clocks.

One setting

The user timezone is set under the agent defaults as an IANA zone name such as America/Chicago. When it is unset, OpenClaw resolves the host timezone at runtime through the platform’s international date formatting API, without writing anything to the config, and the same resolved zone is used for message envelopes, queued system events, the prompt’s local date and heartbeat active hours. Setting the zone once therefore changes what the model reads in envelopes, what it believes today’s date is, when heartbeats are allowed to fire, and how cron expressions are interpreted.

Why the clock stays out

• The date and zone live below the system-prompt cache boundary, so a day rollover does not invalidate the stable prefix the provider has cached.
• The prompt deliberately omits the live clock; when the agent needs the exact current time and the session status tool is available, it calls that tool.
• Because the envelope carries its own timestamp per message, the model can still reason about elapsed time between turns without a ticking clock in the prompt.

OpenClaw heartbeat is where active hours read the zone, and OpenClaw automations where cron expressions do.

The prompt side

The OpenClaw system prompt explains the temporal context section that carries the user-local date and zone into the prompt, and OpenClaw context window and compaction the cache boundary that the date is placed beneath.

On Diali

On Diali the timezone chosen at onboarding is what the assistant runs with, so envelopes, the prompt’s local date and heartbeat active hours follow you rather than the container’s clock. Hosted OpenClaw on Diali is the assistant.

• Three surfaces, one reference time.
• One setting moves envelopes, prompt date, heartbeats and cron together.
• The date is cached below the boundary; the clock is a tool call.