Timezones in OpenClaw: Envelopes, Tool Payloads, and System Prompt

OpenClaw ensures that all timestamps share a single reference time, so the model never has to deal with a jumble of provider-specific clocks. Timezones appear in three distinct places, each serving a different function:

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
System prompt	A volatile `Temporal Context` block with the local date and time zone; exact time remains tool-backed	Host timezone if `userTimezone` unset	`agents.defaults.userTimezone`

Because the date and zone sit below the system-prompt cache boundary, a day rollover won't force the stable prefix to be regenerated. The prompt leaves out the live clock on purpose; whenever the agent needs the precise current time and session_status exists, it invokes that tool.

Setting the user timezone

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

When userTimezone isn't set, OpenClaw determines the host timezone at runtime through Intl.DateTimeFormat().resolvedOptions().timeZone, leaving the config untouched. That same resolved zone applies to message envelopes, queued system events, the local date in the prompt, and heartbeat active hours.

How the clock is displayed follows the host operating system and locale preferences. No separate configuration toggle exists for 12-hour versus 24-hour format.

Provider examples and elapsed-time formatting are covered in 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.