Neura Market Logo

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

Learn how OpenClaw normalizes timestamps across three surfaces: message envelopes, tool payloads, and system prompts. Essential for developers configuring timezone defaults and understanding UTC handling.

Read this when

  • You want a quick mental model for timezone handling
  • You are deciding where to set or override a timezone

OpenClaw normalizes timestamps so the model sees a single reference time rather than a mix of provider-local clocks. Three surfaces display timezones, each serving a distinct purpose:

Three timezone surfaces

SurfaceWhat it showsDefaultConfigured via
Message envelopesWraps inbound channel messages: [Signal +1555 Sun 2026-01-18 00:19:42 PST] helloHost-localagents.defaults.envelopeTimezone
Tool payloadsChannel readMessages-style tools return raw provider time plus 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 intentionally leaves out 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 not set, OpenClaw resolves the host timezone at runtime using Intl.DateTimeFormat().resolvedOptions().timeZone (no config write). agents.defaults.timeFormat (auto | 12 | 24) controls 12h/24h rendering in envelopes and downstream surfaces, but not in the system prompt section.

Envelope timezone values

agents.defaults.envelopeTimezone accepts:

  • "local" (default) or "host" - host machine's timezone.
  • "utc" or "gmt" - UTC.
  • "user" - the resolved agents.defaults.userTimezone (falls back to host timezone if unset).
  • Any explicit IANA zone string, e.g. "Europe/Vienna".

When to override

  • Use "utc" for stable timestamps across hosts in different regions, or to match UTC-aligned diagnostics/log output.
  • Use "user" to keep envelopes aligned with the configured user timezone regardless of which zone the gateway host runs in.
  • Use a fixed IANA zone when the gateway host is in one zone but the envelope should always read in another zone regardless of host migration.
  • Set envelopeTimestamp: "off" when timestamp context is not useful for the conversation. This removes absolute timestamps from envelopes, direct agent prompt prefixes, and embedded model-input prefixes.

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.