Date and 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.

Message envelopes

Inbound messages are wrapped with a timestamp at second precision. The default format is:

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

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

Override the behavior under agents.defaults:

{
  agents: {
    defaults: {
      envelopeTimezone: "local", // "utc" | "local" | "user" | IANA timezone
      envelopeTimestamp: "on", // "on" | "off"
      envelopeElapsed: "on", // "on" | "off"
    },
  },
}
  • envelopeTimezone: "utc" forces UTC.
  • envelopeTimezone: "local" uses the gateway host timezone.
  • envelopeTimezone: "user" uses agents.defaults.userTimezone (falls back to host timezone).
  • An explicit IANA value such as "America/Chicago" sets a fixed zone.
  • envelopeTimestamp: "off" removes absolute timestamps from envelope headers, direct agent prompt prefixes, and embedded model-input prefixes.
  • envelopeElapsed: "off" removes elapsed-time suffixes such as +2m.

Examples

Local (default):

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

User timezone:

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

Elapsed time enabled:

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

System prompt

When a user timezone is known, the system prompt includes a dedicated Current Date & Time section that contains only the time zone (no clock or time format). This keeps prompt caching stable:

Time zone: America/Chicago

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

System event lines

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 and format

{
  agents: {
    defaults: {
      userTimezone: "America/Chicago",
      timeFormat: "auto", // auto | 12 | 24
    },
  },
}
  • userTimezone sets the user-local timezone used for prompt context.
  • timeFormat controls 12h/24h display in the prompt. auto follows OS preferences.

Time format detection (auto)

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

Tool payloads and connectors

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

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

Raw provider fields are preserved. Examples include epoch-like strings from Slack, UTC ISO timestamps from Discord, and provider-specific numeric or ISO values from Telegram and WhatsApp. Convert to local time downstream using the known timezone when required.

Updated June 17, 2026