AI Agents Getting the Date Wrong? Timezone Configuration in OpenCLAW

Running an AI agent platform from New Zealand means living 12 to 13 hours ahead of Coordinated Universal Time (UTC). When your agents think it's yesterday, greet you with "good morning" at 9pm, or schedule something for tomorrow using today's date, you've got a timezone problem. And it's more common than you'd think.

I run a multi-agent business operating system on OpenCLAW from Whangārei Heads, New Zealand, hosted on a Microsoft Azure Virtual Machine (VM), with agents coordinated through Telegram. After weeks of agents getting dates wrong, giving inappropriate greetings, and confusing "today" with "tomorrow", I dug into the root cause and fixed it. Here's what I found.

The problem isn't specific to Azure. Whether you're on Amazon Web Services (AWS), Google Cloud Platform (GCP), a Hetzner Virtual Private Server (VPS), a Raspberry Pi in your garage, or a Docker container on bare metal, if your host defaults to UTC and you don't, your agents are going to get time wrong.

Why Agents Get Time Wrong#

Large Language Models (LLMs) have no internal clock. They don't know what day it is, what time it is, or what timezone you're in unless something explicitly tells them. Left to their own devices, they'll infer dates from training data, message context, or memory file names and get it wrong regularly.

OpenCLAW injects a ## Current Date & Time section into each agent's system prompt, but by default it only includes the timezone name, not the actual date or time. This is a deliberate design choice to keep the system prompt stable for provider-side prompt caching. The trade-off is that agents are left guessing.

When your VM runs on UTC (the default for Azure, AWS, GCP, and most hosting providers) and you're in New Zealand Daylight Time (NZDT, UTC+13), everything compounds. Message envelope timestamps show UTC. The date command returns UTC. Memory files get stamped with UTC dates. An agent reading a file dated 2026-03-18 at 9am on March 19th NZ time has no reliable way to know whether that file is from "today" or "yesterday" because from the server's perspective, it is still March 18th.

The Fix: Four Layers#

No single change solves this. You need to align the entire stack.

1. Set the VM System Timezone#

If your server runs on UTC and you don't need it to, change it. For New Zealand:

sudo timedatectl set-timezone Pacific/Auckland

This uses the Internet Assigned Numbers Authority (IANA) timezone database, which handles daylight saving automatically: NZDT (+13) in summer, New Zealand Standard Time (NZST, +12) in winter. The date command, cron jobs, log timestamps, and file modification times all follow the system timezone.

Docker users: Containers typically inherit UTC regardless of the host. Set TZ as an environment variable in your docker-compose.yml or pass -e TZ=Pacific/Auckland at runtime. Alternatively, mount the host's timezone data: -v /etc/localtime:/etc/localtime:ro.

Cloud providers: Azure, AWS, and GCP all default new VMs to UTC. The timedatectl command works on any systemd-based Linux (Ubuntu, Debian, Red Hat Enterprise Linux, etc.). If you're on Alpine or a minimal container image without systemd, set the TZ environment variable instead.

2. Pin the Gateway Process to Your Timezone#

OpenCLAW's gateway is a Node.js process. Node inherits TZ from its environment. Add it to your systemd service file and your .env:

# In your openclaw.service [Service] section
Environment="TZ=Pacific/Auckland"

# In your .env file
TZ=Pacific/Auckland

Run sudo systemctl daemon-reload after editing the service file.

3. Configure OpenCLAW's Timezone Settings#

OpenCLAW has two key settings in openclaw.json under agents.defaults:

{
  "agents": {
    "defaults": {
      "userTimezone": "Pacific/Auckland",
      "envelopeTimezone": "Pacific/Auckland",
      "envelopeTimestamp": "on",
      "envelopeElapsed": "on"
    }
  }
}

userTimezone controls what appears in the system prompt's time section. envelopeTimezone controls the timestamps on message envelopes, the metadata wrapper around each message that the agent sees. With both set to your local timezone, the agent sees local time everywhere it looks.

4. Tell Your Agents How to Use Time#

Configuration gets the right data into the context. But LLMs still need explicit instructions on what to do with it. I added a ## Time Awareness section to the shared user context file that every agent loads at session start:

• All operations run on New Zealand time. Never reference or display UTC.
• At session start, read the envelope timestamp before greeting. Use an appropriate greeting for the time of day.
• When referencing "today", "tomorrow", or "yesterday", verify against the envelope timestamp or run date. Do not infer from memory file names alone.
• The system prompt may only show the timezone name without the clock time. Always confirm the actual date from envelope timestamps before making date-relative statements.

This last layer matters more than you might expect. Without it, even agents that have the right time available will still occasionally default to LLM instincts, guessing dates from file names or defaulting to a generic greeting.

The Outcome#

After applying all four layers and restarting the gateway:

• Gateway logs show +13:00 offsets instead of +00:00
• date returns NZDT on the VM
• Message envelopes carry NZ timestamps that agents can read directly
• Agents have explicit instructions to check the time before greeting and to verify dates before making relative references

The underlying issue is that buildTimeSection() in OpenCLAW's system prompt only injects the timezone name, not the resolved date. This is a known limitation with multiple open issues on GitHub (#1928, #4629, #17633, #28958, #31893). Until that's fixed upstream, the combination of correct system timezone, explicit config, and agent-level instructions is the most reliable workaround.

A Prompt to Diagnose and Fix Your Setup#

If you're running into timezone issues with your own OpenCLAW instance (or any self-hosted AI agent platform), here's a prompt you can hand to Claude, ChatGPT, or any capable LLM. Replace the placeholder values with your own details and let it audit your stack.

I run an AI agent platform (OpenCLAW / [your framework]) on a Linux server
hosted on [Azure / AWS / GCP / VPS / Docker / bare metal / Raspberry Pi].
My timezone is [Your/Timezone] (e.g. Pacific/Auckland, America/New_York, Europe/London).

My agents frequently get the current date wrong, use incorrect "today"/"tomorrow"
references, or give greetings that don't match my time of day.

Please audit and fix my timezone configuration across all layers:

1. SYSTEM LAYER: Check my server's system timezone (timedatectl, or TZ env var
   if Docker/container) and set it to [Your/Timezone] if it's currently UTC.
   Verify that date returns local time.

2. PROCESS LAYER: Check whether my agent gateway process inherits the correct
   TZ environment variable. Check my systemd service file and any .env files
   for TZ settings. Add TZ=[Your/Timezone] where missing.

3. APPLICATION LAYER: Check my openclaw.json (or equivalent config) for:
   - agents.defaults.userTimezone -- should be set to [Your/Timezone]
   - agents.defaults.envelopeTimezone -- should match, so message timestamps
     show local time
   - agents.defaults.envelopeTimestamp -- should be "on"
   - agents.defaults.envelopeElapsed -- should be "on"

4. AGENT INSTRUCTION LAYER: Check my agent bootstrap/context files (SOUL.md,
   USER.md, or equivalent) for explicit time-awareness instructions. If missing,
   add directives that tell agents to:
   - Never display UTC -- always use local time
   - Check envelope timestamps before choosing a greeting
   - Verify the current date before using relative terms like "today" or "tomorrow"
   - Not infer dates from memory file names alone

After each layer, show me what you found and what you changed.
Verify the fix works end-to-end before finishing.

This prompt works because it forces a systematic, layer-by-layer audit rather than a surface-level fix. Most people only address one layer (usually the config) and then wonder why the problem persists. The issue is that timezone awareness in an agent stack has to be consistent from the OS kernel all the way up to the natural language instructions the LLM reads at session start.

Mark Smith is the founder of Cloverbase, an AI strategy consultancy based in Whangārei Heads, New Zealand.

Short link to this post: m1.nz/wjv4tjx