Configure OpenClaw Timezones: Sync Timestamps in Seconds

Dealing with timezones is often a nightmare. You’ve likely run into issues where a bot gets confused because it doesn’t know if “10:00” means morning in New York or evening in Tokyo. OpenClaw fixes this by standardizing timestamps so the model always sees a single reference time.

Message envelopes (local by default)

OpenClaw wraps inbound messages in an envelope to give the model context. It looks like this:

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

By default, the timestamp in this envelope uses the host-local time with minute precision. If you need to change this behavior, you can use these configuration options:

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

Here is how those settings work:

• Setting envelopeTimezone: "utc" switches everything to UTC.
• Using envelopeTimezone: "user" points to agents.defaults.userTimezone (it uses the host timezone if that is missing).
• You can use an explicit IANA timezone like "Europe/Vienna" if you want a fixed offset.
• If you set envelopeTimestamp: "off", absolute timestamps are removed from the headers.
• Setting envelopeElapsed: "off" hides the elapsed time suffixes, such as the +2m format.

Examples

Local (default):

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

Fixed timezone:

[Signal Alice +1555 2026-01-18 06:19 GMT+1] hello

Elapsed time:

[Signal Alice +1555 +2m 2026-01-18T05:19Z] follow-up

Tool payloads (raw provider data + normalized fields)

When you use tool calls like channels.discord.readMessages or channels.slack.readMessages, the system returns the raw timestamps directly from the provider. To make your life easier, OpenClaw also attaches normalized fields so you have a consistent format to work with:

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

You don’t lose any data because the raw provider fields are still preserved.

User timezone for the system prompt

You can set agents.defaults.userTimezone to let the model know the user’s local time zone. If you leave this unset, OpenClaw automatically resolves the host timezone at runtime without writing to your config.

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

This information helps the model because the system prompt will include:

• A Current Date & Time section showing the local time and timezone.
• A preferred time format, either 12-hour or 24-hour.

You can manage the format using agents.defaults.timeFormat with options for auto, 12, or 24. For a deeper look at how this works, you can check out the Date & Time documentation.

Related

• Heartbeat — see how active hours use timezones for scheduling.
• Cron Jobs — learn how cron expressions use timezones.
• Date & Time — view the full behavior and more examples.

Next Steps

If you need help getting your configuration exactly right, try the AI Setup Assistant.