mirror of
https://github.com/openclaw/openclaw.git
synced 2026-04-04 13:51:30 +00:00
e682b72154
New page: docs/automation/index.md — single entry point for all automation mechanisms (heartbeat, cron, tasks, hooks, standing-orders, webhooks) with a decision flowchart and comparison table. Add "Related" sections to 5 high-traffic pages that were dead ends: - gateway/heartbeat.md → links to tasks, cron-vs-heartbeat, timezone, troubleshooting - concepts/session.md → links to multi-agent, tasks, channel-routing - concepts/multi-agent.md → links to channel-routing, subagents, ACP, presence, session - concepts/agent-loop.md → links to tools, hooks, compaction, exec-approvals, thinking - concepts/timezone.md → links to heartbeat, cron-jobs, date-time Add automation/index to Mintlify nav as first item in Automation group.
98 lines
2.5 KiB
Markdown
98 lines
2.5 KiB
Markdown
---
|
|
summary: "Timezone handling for agents, envelopes, and prompts"
|
|
read_when:
|
|
- You need to understand how timestamps are normalized for the model
|
|
- Configuring the user timezone for system prompts
|
|
title: "Timezones"
|
|
---
|
|
|
|
# Timezones
|
|
|
|
OpenClaw standardizes timestamps so the model sees a **single reference time**.
|
|
|
|
## Message envelopes (local by default)
|
|
|
|
Inbound messages are wrapped in an envelope like:
|
|
|
|
```
|
|
[Provider ... 2026-01-05 16:26 PST] message text
|
|
```
|
|
|
|
The timestamp in the envelope is **host-local by default**, with minutes precision.
|
|
|
|
You can override this with:
|
|
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
envelopeTimezone: "local", // "utc" | "local" | "user" | IANA timezone
|
|
envelopeTimestamp: "on", // "on" | "off"
|
|
envelopeElapsed: "on", // "on" | "off"
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
- `envelopeTimezone: "utc"` uses UTC.
|
|
- `envelopeTimezone: "user"` uses `agents.defaults.userTimezone` (falls back to host timezone).
|
|
- Use an explicit IANA timezone (e.g., `"Europe/Vienna"`) for a fixed offset.
|
|
- `envelopeTimestamp: "off"` removes absolute timestamps from envelope headers.
|
|
- `envelopeElapsed: "off"` removes elapsed time suffixes (the `+2m` style).
|
|
|
|
### 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)
|
|
|
|
Tool calls (`channels.discord.readMessages`, `channels.slack.readMessages`, etc.) return **raw provider timestamps**.
|
|
We also attach normalized fields for consistency:
|
|
|
|
- `timestampMs` (UTC epoch milliseconds)
|
|
- `timestampUtc` (ISO 8601 UTC string)
|
|
|
|
Raw provider fields are preserved.
|
|
|
|
## User timezone for the system prompt
|
|
|
|
Set `agents.defaults.userTimezone` to tell the model the user's local time zone. If it is
|
|
unset, OpenClaw resolves the **host timezone at runtime** (no config write).
|
|
|
|
```json5
|
|
{
|
|
agents: { defaults: { userTimezone: "America/Chicago" } },
|
|
}
|
|
```
|
|
|
|
The system prompt includes:
|
|
|
|
- `Current Date & Time` section with local time and timezone
|
|
- `Time format: 12-hour` or `24-hour`
|
|
|
|
You can control the prompt format with `agents.defaults.timeFormat` (`auto` | `12` | `24`).
|
|
|
|
See [Date & Time](/date-time) for the full behavior and examples.
|
|
|
|
## Related
|
|
|
|
- [Heartbeat](/gateway/heartbeat) — active hours use timezone for scheduling
|
|
- [Cron Jobs](/automation/cron-jobs) — cron expressions use timezone for scheduling
|
|
- [Date & Time](/date-time) — full date/time behavior and examples
|