- name
- agent-timezone-lock
- description
- Stops your OpenClaw agent from reporting the wrong time. Prevents the common UTC-as-local mistake that makes agents look broken. Install this if your agent has ever said the wrong time, confused UTC with local time, or if you want all times reported in your local timezone automatically. Triggers on: what time is it, wrong time, wrong timezone, UTC, local time, set my timezone, or any heartbeat where time accuracy matters.
Timezone Enforcement Skill
Enforces correct local-time awareness for this agent. Prevents the classic UTC-as-local mistake.
What This Skill Does
When installed, this skill:
- Reads the user timezone from USER.md (Timezone: field)
- Ensures timezone is applied when the agent calls now.py for time output
- Provides /timezone command for users to check/set timezone
- Validates that the agent never reports UTC time as local time
- Patches AGENTS.md with standing timezone instructions
Prerequisites — Required Before Install
USER.md must contain a timezone field in this exact format: Timezone: America/New_York
Use a valid IANA timezone string. Examples:
- America/New_York
- America/Chicago
- America/Los_Angeles
- Europe/London
- Asia/Tokyo
Do NOT use abbreviations like EST, PST, or free-text like "New York time" — these will fail.
If USER.md does not exist or has no Timezone field, timezone_setup.py will prompt the user to enter one interactively.
Invalid timezone recovery:
- If the string fails IANA validation, halt and show: "Invalid timezone: [input]. Please provide a valid IANA string e.g. America/New_York"
- Do not default silently to UTC
- Do not proceed until a valid string is confirmed
Startup - Run Once on Install
On first use, run: python3 /opt/openclaw/workspace/skills/timezone/scripts/timezone_setup.py
Note: timezone_setup.py requires an interactive shell. For headless or automated environments, pre-populate tz_config.json directly with the IANA string before first run.
This script detects timezone from USER.md, writes TZ_CONFIG to tz_config.json, and patches AGENTS.md. Do not patch AGENTS.md manually until this script has run. It requires a valid tz_config.json first.
Answering What Time Is It
Always run: python3 /opt/openclaw/workspace/skills/timezone/scripts/now.py
Report the output verbatim. Never guess time from internal knowledge. If now.py fails: report the error, ask user to run timezone_setup.py first. Do not guess. If USER.md has no Timezone field: run timezone_setup.py before proceeding. Do not default to UTC silently.
Heartbeat Integration
On every heartbeat where time is mentioned:
- Call now.py to get current local time
- If any prior message contains a UTC time presented as local time, flag it
- If drift over 30 minutes between what agent said and actual time, self-correct
If now.py fails during heartbeat: log the failure, skip time reporting, flag to user at next opportunity.
UTC Trap Detection
If about to output a time, ask: Is this UTC or local?
- UTC ends in Z, +00:00, or +0000 — convert before reporting
- Timestamps with no timezone offset at all are ambiguous — treat as UTC and note the assumption to the user
- Times from APIs, cron, system are usually UTC - always convert
- Times in USER.md or user messages are usually local - use as-is
/timezone Command
When user types /timezone:
- Show current configured timezone and current local time
- Offer to change
- If changing: run timezone_setup.py with their input
- Confirm the change
If tz_config.json does not exist: run timezone_setup.py first.
Standing Rules - patch into AGENTS.md only after timezone_setup.py has run
- NEVER report UTC time as local time
- All time output must be in users local timezone
- When in doubt: run now.py before reporting any time
- API/cron/system timestamps are UTC - always convert before displaying
- If now.py fails: flag to user, do not guess
What This Skill Does NOT Do
- Does NOT automatically intercept all time output — the agent must explicitly call now.py before reporting any time
- Does NOT self-correct without being triggered — heartbeat integration requires the agent framework to call now.py on schedule
- Does NOT validate timezone strings at runtime beyond what the system tz database supports
- Does NOT handle multi-user or multi-timezone environments — one timezone per agent instance
- Does NOT detect if USER.md has changed since install — if timezone changes, re-run timezone_setup.py manually to sync tz_config.json