Date & Time¶

OpenClaw defaults to host-local time for transport timestamps and user timezone only in the system prompt. Provider timestamps are preserved so tools keep their native semantics (current time is available via session_status).

Message envelopes (local by default)¶

Inbound messages are wrapped with a timestamp (minute precision):

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

This envelope timestamp is host-local by default, regardless of the provider timezone.

You can override this behavior:

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

envelopeTimezone: "utc" uses UTC.
envelopeTimezone: "local" uses the host timezone.
envelopeTimezone: "user" uses agents.defaults.userTimezone (falls back to host timezone).
Use an explicit IANA timezone (e.g., "America/Chicago") for a fixed zone.
envelopeTimestamp: "off" removes absolute timestamps from envelope headers.
envelopeElapsed: "off" removes elapsed time suffixes (the +2m style).

Examples¶

Local (default):

[WhatsApp +1555 2026-01-18 00:19 PST] hello

User timezone:

[WhatsApp +1555 2026-01-18 00:19 CST] hello

Elapsed time enabled:

[WhatsApp +1555 +30s 2026-01-18T05:19Z] follow-up

System prompt: Current Date & Time¶

If the user timezone is known, the system prompt includes a dedicated Current Date & Time section with the time zone only (no clock/time format) to keep prompt caching stable:

Time zone: America/Chicago

When the agent needs the current time, use the session_status tool; the status card includes a timestamp line.

System event lines (local by default)¶

Queued system events inserted into agent context are prefixed with a timestamp using the same timezone selection as message envelopes (default: host-local).

System: [2026-01-12 12:19:17 PST] Model switched.

Configure user timezone + format¶

{
  agents: {
    defaults: {
      userTimezone: "America/Chicago",
      timeFormat: "auto", // auto | 12 | 24
    },
  },
}

userTimezone sets the user-local timezone for prompt context.
timeFormat controls 12h/24h display in the prompt. auto follows OS prefs.

Time format detection (auto)¶

When timeFormat: "auto", OpenClaw inspects the OS preference (macOS/Windows) and falls back to locale formatting. The detected value is cached per process to avoid repeated system calls.

Tool payloads + connectors (raw provider time + normalized fields)¶

Channel tools return provider-native timestamps and add normalized fields for consistency:

timestampMs: epoch milliseconds (UTC)
timestampUtc: ISO 8601 UTC string

Raw provider fields are preserved so nothing is lost.

Slack: epoch-like strings from the API
Discord: UTC ISO timestamps
Telegram/WhatsApp: provider-specific numeric/ISO timestamps

If you need local time, convert it downstream using the known timezone.