Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Three timezone surfaces

SurfaceWhat it showsDefaultConfigured via
Message envelopesWraps inbound channel messages: [Signal +1555 2026-01-18 00:19 PST] helloHost-localagents.defaults.envelopeTimezone
Tool payloadsChannel readMessages-style tools return raw provider time + normalized timestampMs / timestampUtcUTC fields always presentNot configurable — preserves provider-native timestamps
System promptA small Current Date & Time block with the time zone only (no clock value, for cache stability)Host timezone if userTimezone unsetagents.defaults.userTimezone
The system prompt deliberately omits the live clock to keep prompt caching stable across turns. When the agent needs the current time, it calls session_status.

​
Setting the user timezone

{
  agents: {
    defaults: {
      userTimezone: "America/Chicago",
    },
  },
}
If userTimezone is unset, OpenClaw resolves the host timezone at runtime (no config write). agents.defaults.timeFormat (auto | 12 | 24) controls 12h/24h rendering in envelopes and downstream surfaces, not in the system prompt section.

​
When to override

  • Use UTC envelopes (envelopeTimezone: "utc") when you want stable timestamps across hosts in different regions, or when you want UTC-aligned logs to match diagnostics output.
  • Use a fixed IANA zone (e.g. "Europe/Vienna") when the gateway host is in one zone but the user is in another and you want envelopes to read in the user’s zone regardless of host migration.
  • Set envelopeTimestamp: "off" for low-token envelopes when timestamp context is not useful for the conversation.
For the full behavior reference, examples per provider, 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.