Timezone

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 h...

Security Scan

The skill's files and runtime instructions are consistent with its stated purpose (enforcing an agent-local timezone); it does not request secrets or external network access — the primary caution is that it automatically modifies the global AGENTS.md file to insert standing timezone rules.

Purpose & Capability

Name and description match what the code and SKILL.md do: detect a timezone from USER.md or system, write tz_config.json, provide now.py for canonical time output, and patch AGENTS.md with standing rules. There are no unrelated environment variables or unexpected binaries requested.

Instruction Scope

SKILL.md instructions are explicit and match the code: run timezone_setup.py on first use (interactive or pre-populate tz_config.json for headless), always call now.py when outputting time, and use /timezone to view/change settings. The instructions do read/write USER.md, tz_config.json, and AGENTS.md as documented; they do not instruct the agent to read arbitrary secrets or send data externally.

Install Mechanism

This is an instruction-only skill with bundled Python scripts (no install spec, no downloads). No external packages are fetched by an installer; timezone resolution uses local system calls or standard Python libraries at runtime.

Credentials

The skill requires no environment variables or credentials. It reads USER.md and system timezone files (timedatectl, /etc/localtime, /etc/timezone) which is appropriate for determining a timezone; there are no unexplained secret accesses.

Persistence & Privilege

The skill writes to AGENTS.md (a workspace/global agent file) outside its own directory to append or update a 'Timezone Standing Order'. The code will patch AGENTS.md unconditionally in some code paths (the --set branch uses 'if args.patch_agents or True' which always triggers the patch), which is intrusive behavior to a system-wide file. While this is documented in SKILL.md, modifying a global agent instructions file is a higher-privilege action and worth noticing before install.

Assessment

What to consider before installing: - This skill is coherent with its stated purpose and does not request secrets or network access, but it will modify AGENTS.md (a global agent document) to insert timezone standing orders — review and back up AGENTS.md first. - timezone_setup.py will attempt to auto-detect local timezone via timedatectl, /etc/localtime, or /etc/timezone and falls back to interactive prompting; in headless setups you should pre-populate tz_config.json with a valid IANA name. - The setup script will always attempt to patch AGENTS.md in some code paths (the script contains an unconditional patch path); if you do not want automatic edits to AGENTS.md, inspect and run timezone_setup.py manually before granting it run privileges. - After install, verify tz_config.json contents and inspect any AGENTS.md changes to confirm the inserted standing order is acceptable. - If you want to be extra cautious, run the scripts in a sandboxed environment first to observe file modifications (they do not perform network calls or exfiltrate data).

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:

1. Reads the user timezone from USER.md (Timezone: field)
2. Ensures timezone is applied when the agent calls now.py for time output
3. Provides /timezone command for users to check/set timezone
4. Validates that the agent never reports UTC time as local time
5. 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:

1. Call now.py to get current local time
2. If any prior message contains a UTC time presented as local time, flag it
3. 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:

1. Show current configured timezone and current local time
2. Offer to change
3. If changing: run timezone_setup.py with their input
4. 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