ewilliams28/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-08-12 21:53:00 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: correct timezone configuration contract (#116102)

Browse Source
This commit is contained in:
Vincent Koc
2026-07-30 06:23:50 +08:00
committed by GitHub
parent 925fdb023e
commit 3226f07cad
6 changed files with 35 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/concepts/system-prompt.md
-1
View File
@@ -139,7 +139,6 @@ Use `session_status` when the agent needs the exact current time and the tool is
Configure with:
- `agents.defaults.userTimezone`
- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
See [Timezones](/concepts/timezone) and [Date & Time](/date-time) for full behavior details.
docs/concepts/timezone.md
+10 -20
View File
@@ -11,10 +11,10 @@ OpenClaw standardizes timestamps so the model sees a **single reference time** i
## Three timezone surfaces
| Surface | What it shows | Default | Configured via |
| ----------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------ |
| Message envelopes | Wraps inbound channel messages: `[Signal +1555 Sun 2026-01-18 00:19:42 PST] hello` | Host-local | `agents.defaults.envelopeTimezone` |
| ----------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------ |
| Message envelopes | Wraps inbound channel messages: `[Signal +1555 Sun 2026-01-18 00:19:42 PST] hello` | Host timezone if `userTimezone` unset | `agents.defaults.userTimezone` |
| Tool payloads | Channel `readMessages`-style tools return raw provider time plus normalized `timestampMs` / `timestampUtc` | UTC fields always present | Not configurable; preserves provider-native timestamps |
| System prompt | A small volatile `Temporal Context` block with the local date and time zone; exact time remains tool-backed | Host timezone if `userTimezone` unset | `agents.defaults.userTimezone` |
| System prompt | A volatile `Temporal Context` block with the local date and time zone; exact time remains tool-backed | Host timezone if `userTimezone` unset | `agents.defaults.userTimezone` |
The date and zone live below the system-prompt cache boundary, so day rollover does not invalidate the stable prefix. The prompt deliberately omits the live clock; when the agent needs exact current time and `session_status` is available, it calls that tool.
@@ -30,25 +30,15 @@ The date and zone live below the system-prompt cache boundary, so day rollover d
}
```
If `userTimezone` is unset, OpenClaw resolves the host timezone at runtime via `Intl.DateTimeFormat().resolvedOptions().timeZone` (no config write). `agents.defaults.timeFormat` (`auto` | `12` | `24`) controls 12h/24h rendering in envelopes and downstream surfaces, not in the system prompt section because that section has no clock value.
If `userTimezone` is unset, OpenClaw resolves the host timezone at runtime via
`Intl.DateTimeFormat().resolvedOptions().timeZone` without writing config. The same
resolved zone is used for message envelopes, queued system events, the prompt's local
date, and heartbeat active hours.
## Envelope timezone values
Clock rendering follows the host operating-system and locale preference. There is no
separate 12-hour or 24-hour config setting.
`agents.defaults.envelopeTimezone` accepts:
- `"local"` (default) or `"host"` - host machine's timezone.
- `"utc"` or `"gmt"` - UTC.
- `"user"` - the resolved `agents.defaults.userTimezone` (falls back to host timezone if unset).
- Any explicit IANA zone string, e.g. `"Europe/Vienna"`.
## When to override
- **Use `"utc"`** for stable timestamps across hosts in different regions, or to match UTC-aligned diagnostics/log output.
- **Use `"user"`** to keep envelopes aligned with the configured user timezone regardless of which zone the gateway host runs in.
- **Use a fixed IANA zone** when the gateway host is in one zone but the envelope should always read in another zone regardless of host migration.
- **Set `envelopeTimestamp: "off"`** when timestamp context is not useful for the conversation. This removes absolute timestamps from envelopes, direct agent prompt prefixes, and embedded model-input prefixes.
For the full behavior reference, examples per provider, and elapsed-time formatting, see [Date & Time](/date-time).
For provider examples and elapsed-time formatting, see [Date & Time](/date-time).
## Related
docs/date-time.md
+18 -35
View File
@@ -6,9 +6,10 @@ read_when:
title: "Date and time"
---
OpenClaw uses **host-local time for transport timestamps** and puts the **local date plus time zone** in the system prompt.
Provider timestamps are preserved so tools keep their native semantics. When the agent needs the exact current
time and `session_status` is available, it runs that tool.
OpenClaw uses the configured **user timezone** for message envelopes, system events, and
the system prompt. When `agents.defaults.userTimezone` is unset, those surfaces use the
host timezone. Provider timestamps are preserved so tools keep their native semantics.
When the agent needs the exact current time and `session_status` is available, it runs that tool.
## Message envelopes (local by default)
@@ -18,26 +19,8 @@ Inbound messages are wrapped with a weekday plus second-precision timestamp:
[WhatsApp +1555 Mon 2026-01-05 16:26:34 PST] message text
```
The envelope timestamp is **host-local by default**, regardless of the provider timezone.
Override under `agents.defaults`:
```json5
{
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` (host timezone when unset). An explicit IANA name (e.g. `"America/Chicago"`) pins a fixed zone; unrecognized names fall back to UTC. |
| `envelopeTimestamp` | `on` (default), `off` | `off` removes 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` style) shown since the previous message in the session. |
Envelope timestamps use `agents.defaults.userTimezone` when configured, otherwise the
host timezone. Absolute timestamps and elapsed-time suffixes are built in.
### Examples
@@ -53,10 +36,10 @@ Override under `agents.defaults`:
[WhatsApp +1555 Sun 2026-01-18 00:19:42 CST] hello
```
**Elapsed time with `envelopeTimezone: "utc"`:**
**Elapsed time:**
```
[WhatsApp +1555 +30s Sun 2026-01-18T05:19:00Z] follow-up
[WhatsApp +1555 +30s Sun 2026-01-18 00:20:12 CST] follow-up
```
## System prompt: temporal context
@@ -75,34 +58,34 @@ invalidate the stable prefix. When available, `session_status` remains the sourc
## System event lines (local by default)
Queued system events inserted into agent context are prefixed with a timestamp using the
same `envelopeTimezone` selection as message envelopes (default: host-local).
Queued system events inserted into agent context use `agents.defaults.userTimezone` when
configured, otherwise the host timezone.
```
System: [2026-01-12 12:19:17 PST] Model switched.
```
### Configure user timezone + format
### Configure user timezone
```json5
{
agents: {
defaults: {
userTimezone: "America/Chicago",
timeFormat: "auto", // auto | 12 | 24
},
},
}
```
- `userTimezone` sets the **user-local timezone** for prompt context (and for `envelopeTimezone: "user"`).
- `timeFormat` controls **12h/24h display** in prompt-facing times. `auto` follows OS preferences.
- `userTimezone` sets the user-local timezone for message envelopes, system events,
and prompt context.
- Use an IANA timezone such as `America/Chicago`, `Europe/Vienna`, or `Asia/Tokyo`.
## Time format detection (auto)
## Time format detection
When `timeFormat: "auto"`, OpenClaw inspects the OS preference (macOS and Windows)
and falls back to locale formatting. The detected value is **cached per process**
to avoid repeated system calls.
Rendered clock values follow the operating system and locale preference. OpenClaw
detects 12-hour or 24-hour display on macOS and Windows, then falls back to locale
formatting. The detected value is cached per process.
## Tool payloads + connectors (raw provider time + normalized fields)
docs/docs_map.md
+2 -5
View File
@@ -3141,8 +3141,6 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
- Headings:
- H2: Three timezone surfaces
- H2: Setting the user timezone
- H2: Envelope timezone values
- H2: When to override
- H2: Related
## concepts/typebox.md
@@ -3213,8 +3211,8 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
- H3: Examples
- H2: System prompt: temporal context
- H2: System event lines (local by default)
- H3: Configure user timezone + format
- H2: Time format detection (auto)
- H3: Configure user timezone
- H2: Time format detection
- H2: Tool payloads + connectors (raw provider time + normalized fields)
- H2: Related docs
@@ -3419,7 +3417,6 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
- H3: agents.defaults.imageMaxDimensionPx
- H3: agents.defaults.imageQuality
- H3: agents.defaults.userTimezone
- H3: agents.defaults.timeFormat
- H3: agents.defaults.model
- H3: Runtime policy
- H3: CLI backend selection
docs/gateway/config-agents.md
+2 -11
View File
@@ -325,7 +325,8 @@ Values:
### `agents.defaults.userTimezone`
Timezone for the system prompt's local date context (not message timestamps). Falls back to host timezone.
Timezone for message envelopes, queued system events, and the system prompt's local
date context. Falls back to the host timezone.
```json5
{
@@ -333,16 +334,6 @@ Timezone for the system prompt's local date context (not message timestamps). Fa
}
```
### `agents.defaults.timeFormat`
Time format for envelope and other rendered clock values. The system prompt's temporal context has no live clock. Default: `auto` (OS preference).
```json5
{
agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}
```
### `agents.defaults.model`
```json5
docs/install/docker.md
+1
View File
@@ -165,6 +165,7 @@ Optional variables accepted by `scripts/docker/setup.sh` (and, for the gateway c
| `OPENCLAW_INSTALL_BROWSER` | Bake Chromium + Xvfb into the image at build time |
| `OPENCLAW_EXTRA_MOUNTS` | Extra host bind mounts (comma-separated `source:target[:opts]`) |
| `OPENCLAW_HOME_VOLUME` | Persist `/home/node` in a named Docker volume |
| `OPENCLAW_TZ` | Set the gateway and CLI container timezone to an IANA name (default `UTC`) |
| `OPENCLAW_SANDBOX` | Opt in to sandbox bootstrap (`1`, `true`, `yes`, `on`) |
| `OPENCLAW_SKIP_ONBOARDING` | Skip the interactive onboarding step (`1`, `true`, `yes`, `on`) |
| `OPENCLAW_DOCKER_SOCKET` | Override the Docker socket path |