Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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