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.

Related docs

← Back to docs