OpenClawDocs
On this page

On this page

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Technical reference

Timezones

OpenClaw standardizes timestamps so the model sees a single reference time instead of a mix of provider-local clocks. Three surfaces show timezones, each with its own purpose:

Three timezone surfaces

Surface What it shows Default Configured via
Message envelopes Wraps inbound channel messages: [Signal +1555 Sun 2026-01-18 00:19:42 PST] hello Host timezone if userTimezone unset agents.defaults.userTimezone
Tool payloads Channel readMessages-style tools return raw provider time plus normalized timestampMs / timestampUtc UTC fields always present Not configurable; preserves provider-native timestamps
Runtime context A per-turn Temporal Context block with the local date and time zone; exact time remains tool-backed Host timezone if userTimezone unset agents.defaults.userTimezone

The date and zone travel in the current-turn runtime context, outside the system prompt. Day rollover updates that context while preserving the complete system prompt and earlier conversation bytes for prefix-cache reuse. The context deliberately omits the live clock; when the agent needs exact current time and session_status is available, it calls that tool.

Setting the user timezone

json5
{  agents: {    defaults: {      userTimezone: "America/Chicago",    },  },}

If userTimezone is unset, OpenClaw resolves the host timezone at runtime via Intl.DateTimeFormat().resolvedOptions().timeZone without writing config. The same resolved zone is used for message envelopes, queued system events, the prompt's local date, and heartbeat active hours.

Clock rendering follows the host operating-system and locale preference. There is no separate 12-hour or 24-hour config setting.

For provider examples and elapsed-time formatting, see Date & Time.

  • Date & Time - full envelope/tool/prompt behavior and examples.
  • Heartbeat - active hours use timezone for scheduling.
  • Cron Jobs - cron expressions use timezone for scheduling.
  • System prompt - the Temporal Context section that carries the user-local date and time zone into the prompt.
Was this useful?