openclaw/docs/date-time.md
Jon Shapiro 92697edb7c fix(venice): add compat settings to prevent HTTP 400 errors
Venice's API doesn't support certain OpenAI-compatible parameters that
Clawdbot sends by default:

- `store`: Venice returns HTTP 400 with no body when this is present
- `developer` role: Not supported by Venice's API

This adds VENICE_COMPAT settings (supportsStore: false,
supportsDeveloperRole: false) to all Venice model definitions, both
from the static catalog and dynamically discovered models.

Fixes issues reported in PR #1666 where users experienced silent
failures (HTTP 400, no body) when using Venice models.

Co-authored-by: jonisjongithub <jonisjongithub@users.noreply.github.com>
Co-authored-by: Clawdbot <bot@clawd.bot>
2026-01-26 17:56:01 -08:00

3.4 KiB

summary read_when
Date and time handling across envelopes, prompts, tools, and connectors
You are changing how timestamps are shown to the model or users
You are debugging time formatting in messages or system prompt output

Date & Time

Clawdbot 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 & 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", Clawdbot 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.