bot/docs/concepts/timezone.md at main

mirror of https://github.com/hanzoai/bot.git synced 2026-10-30 17:24:26 +00:00

Files

T

zeekay acaeda400a Eradicate OpenClaw — resolve merge conflicts and finish the rebrand

Three coordinated things:

1. Resolve the committed upstream/main merge conflicts. 94 files were
   sitting with raw <<<<<<< HEAD ... >>>>>>> upstream/main blocks. Every
   conflict had HanzoBot/Bot on HEAD and OpenClaw on upstream. Resolved
   by keeping HEAD everywhere — 540 conflict blocks.

2. Rewrite remaining OpenClaw text refs.
     OPENCLAW   → HANZO_BOT
     OpenClaw   → HanzoBot          (PascalCase type identifiers)
     openclaw   → bot               (codebase convention — botToken,
                                    botUsername etc.; avoids invalid
                                    hyphenated JS identifiers)
     openclaw[_]/openclaw[A-Z] → bot[_]/bot[A-Z]   (compound)
     ai.openclaw.x → ai.hanzo.bot.x  (JVM package path)

3. Delete or rename openclaw-named file paths (116 of them). Dead
   duplicates with a Bot-named canonical from the partial migration:
   deleted. Otherwise renamed.
     ai/openclaw/**           → deleted (ai/hanzo/bot/** canonical)
     Sources/OpenClaw*/       → deleted (Sources/Bot* canonical)
     Tests/OpenClawIPCTests/  → deleted (Tests/BotIPCTests canonical)
     OpenClawKit/             → deleted (BotKit canonical)
     openclaw-tools.*.ts      → deleted (bot-tools.*.ts canonical)
     openclaw-root.ts etc.    → deleted (bot-root.ts canonical)
     types.openclaw.ts        → deleted (types.bot.ts canonical)
     extensions/*/openclaw.plugin.json → renamed hanzo-bot.plugin.json
     docs/start/openclaw.md   → renamed hanzo-bot.md (+ zh-CN)
     docs/assets/openclaw-*.png, whatsapp-openclaw*.jpg → deleted
     scripts/.../openclaw-*   → deleted (bot/hanzo-bot parallels)
     openclaw.mjs             → deleted (hanzo-bot.mjs is package.bin)

Then patched 65 broken JS/TS import strings where hanzo-bot had ended
up inside an import path ('./types.hanzo-bot.js' → './types.bot.js'
etc., since the on-disk filename uses the brand-neutral bot- prefix).

Pre-existing lint debt cleaned up to get oxlint --type-aware to 0/0:
removed the dead i18n test that referenced a path no longer existing;
defined the missing DIDConfig and WalletConfig types in types.base.ts
(they were imported but never declared); dropped unused imports;
collapsed redundant type assertion and a tautological meta.bot lookup
that the openclaw→bot rename made redundant.

The a2ui.bundle.js generated artifact is kept at its pre-rebrand
contents — it gets regenerated by 'pnpm canvas:a2ui:bundle' from
sources I cannot rebuild in this commit; the source side is clean.

Verified: 0 occurrences of openclaw (case-insensitive) in tree source
content, 0 file or directory paths with openclaw in the name; oxlint
--type-aware src test reports 0/0.

2026-05-11 17:56:29 -07:00

2.3 KiB

Raw Permalink Blame History

summary, read_when, title

summary

read_when

title

Timezone handling for agents, envelopes, and prompts

You need to understand how timestamps are normalized for the model

Configuring the user timezone for system prompts

Timezones

HanzoBot 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:

{
  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, HanzoBot resolves the host timezone at runtime (no config write).

{
  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 for the full behavior and examples.

2.3 KiB Raw Permalink Blame History