Timezones

OpenClaw standardizes timestamps so the model sees a single reference time.

Message envelopes (local by default)

Inbound messages are wrapped in an envelope like:

text
Copy
[Provider ... 2026-01-05 16:26 PST] message text

The timestamp in the envelope is host-local by default, with minutes precision.

You can override this with:

json5
Copy
{
  agents: {
    defaults: {
      envelopeTimezone: "local", // "utc" | "local" | "user" | IANA timezone
      envelopeTimestamp: "on", // "on" | "off"
      envelopeElapsed: "on", // "on" | "off"
    },
  },
}

• text

  Copy

  envelopeTimezone: "utc"
  uses UTC.
• text

  Copy

  envelopeTimezone: "user"
  uses
  text

  Copy

  agents.defaults.userTimezone
  (falls back to host timezone).
• Use an explicit IANA timezone (e.g.,
  text

  Copy

  "Europe/Vienna"
  ) for a fixed offset.
• text

  Copy

  envelopeTimestamp: "off"
  removes absolute timestamps from envelope headers.
• text

  Copy

  envelopeElapsed: "off"
  removes elapsed time suffixes (the
  text

  Copy

  +2m
  style).

Examples

Local (default):

text
Copy
[Signal Alice +1555 2026-01-18 00:19 PST] hello

Fixed timezone:

text
Copy
[Signal Alice +1555 2026-01-18 06:19 GMT+1] hello

Elapsed time:

text
Copy
[Signal Alice +1555 +2m 2026-01-18T05:19Z] follow-up

Tool payloads (raw provider data + normalized fields)

Tool calls (

, , etc.) return raw provider timestamps. We also attach normalized fields for consistency:

• text

  Copy

  timestampMs
  (UTC epoch milliseconds)
• text

  Copy

  timestampUtc
  (ISO 8601 UTC string)

Raw provider fields are preserved.

User timezone for the system prompt

Set

to tell the model the user's local time zone. If it is unset, OpenClaw resolves the host timezone at runtime (no config write).

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

The system prompt includes:

• text

  Copy

  Current Date & Time
  section with local time and timezone
• text

  Copy

  Time format: 12-hour
  or
  text

  Copy

  24-hour

You can control the prompt format with

( | | ).

See Date & Time for the full behavior and examples.

Related

• Heartbeat — active hours use timezone for scheduling
• Cron Jobs — cron expressions use timezone for scheduling
• Date & Time — full date/time behavior and examples