Date and Time Handling in OpenClaw

OpenClaw applies host-local time for transport timestamps and includes only the time zone within the system prompt. Provider timestamps remain unchanged so tools retain their original semantics. Whenever the agent requires the current time, it invokes the session_status tool.

Message envelopes (local by default)

Incoming messages are annotated with a weekday and a timestamp precise to the second:

[WhatsApp +1555 Mon 2026-01-05 16:26:34 PST] message text

The envelope timestamp defaults to host-local, irrespective of the provider's timezone. To change this, configure agents.defaults:

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

Key	Values	Behavior
`envelopeTimezone`	`local` (default), `utc`, `user`, explicit IANA name	`user` uses `agents.defaults.userTimezone` (the host timezone if not set). An explicit IANA name such as `"America/Chicago"` locks in a specific zone; unknown names revert to UTC.
`envelopeTimestamp`	`on` (default), `off`	`off` strips absolute timestamps from envelope headers, direct agent prompt prefixes, and embedded model-input prefixes.
`envelopeElapsed`	`on` (default), `off`	`off` removes the elapsed-time suffix (the `+30s` / `+2m` format) that appears since the prior message in the session.

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 with envelopeTimezone: "utc":

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

System prompt: current date and time

A Current Date & Time section in the system prompt provides only the time zone (no clock or time format), which keeps prompt caching consistent:

Time zone: America/Chicago

The zone becomes agents.defaults.userTimezone when set; otherwise, the host timezone is used. The prompt also tells the agent to call the session_status tool whenever it needs the current date, time, or day of the week.

System event lines (local by default)

Queued system events inserted into the agent context receive a timestamp prefix following the same envelopeTimezone selection used for message envelopes (host-local by default).

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 assigns the user-local timezone for prompt context (and also for envelopeTimezone: "user").
timeFormat governs 12h/24h display for times shown in the prompt. auto respects the operating system's preferences.

Time format detection (auto)

With timeFormat: "auto" enabled, OpenClaw checks the OS preference (on macOS and Windows) and falls back to locale-based formatting. The detected value is cached per process to avoid frequent 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 kept intact so no information is lost.

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

To work with local time, convert it downstream using the known timezone.