diff --git a/docs/concepts/system-prompt.md b/docs/concepts/system-prompt.md index 911a7dd6fd08..3fa2db8b249d 100644 --- a/docs/concepts/system-prompt.md +++ b/docs/concepts/system-prompt.md @@ -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. diff --git a/docs/concepts/timezone.md b/docs/concepts/timezone.md index fb8ec4bff4a5..2e41e6a120bb 100644 --- a/docs/concepts/timezone.md +++ b/docs/concepts/timezone.md @@ -10,11 +10,11 @@ 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` | -| 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` | +| 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 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 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 diff --git a/docs/date-time.md b/docs/date-time.md index cb24fde24fcd..8a92b4c60a69 100644 --- a/docs/date-time.md +++ b/docs/date-time.md @@ -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) diff --git a/docs/docs_map.md b/docs/docs_map.md index 08650cd21e19..588babdd0330 100644 --- a/docs/docs_map.md +++ b/docs/docs_map.md @@ -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 diff --git a/docs/gateway/config-agents.md b/docs/gateway/config-agents.md index ef1e7b9ba2b2..046614bd6f0d 100644 --- a/docs/gateway/config-agents.md +++ b/docs/gateway/config-agents.md @@ -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 diff --git a/docs/install/docker.md b/docs/install/docker.md index 642841f45b6b..a36092510f4e 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -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 |