Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix [Docs/UX]: help text is misleading — says "cron expressions" only, but should also apply to datetime strings [2 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#59456•Fetched 2026-04-08 02:24:56
View on GitHub
Comments
0
Participants
1
Timeline
7
Reactions
0
Author
rrrrrredyrrrrrredy
Participants
rrrrrredyrrrrrredy
Timeline (top)
referenced ×4cross-referenced ×3

The help text for openclaw cron add --tz says:

Timezone for cron expressions

This is misleading — it implies the flag only affects --cron (cron expression) scheduling, when in reality its intended behavior is to also apply timezone context to --at (absolute datetime) strings. However, as reported in #59441, --tz currently has no effect on --at strings at all.

Error Message

  1. Users don't know --tz is broken for --at: Even users who expect --tz to work with --at get no error — their timezone is silently ignored and the time is treated as UTC.

Root Cause

There are two distinct issues caused by this documentation gap:

Fix Action

Fixed

PR fix notes

PR #59480: fix: clarify --tz help text to mention --at support (#59456)

Description (problem / solution / changelog)

Summary

The --tz help text in both openclaw cron add and openclaw cron edit says "Timezone for cron expressions" — implying it only applies to --cron. Updated to "Timezone for cron and --at expressions" so users know --tz also applies to --at datetime strings.

Fixes #59456

🤖 AI-assisted (Claude Code). I understand what the code does.

Changes

FileChange
src/cli/cron-cli/register.cron-add.ts"Timezone for cron expressions (IANA)" → "Timezone for cron and --at expressions (IANA)"
src/cli/cron-cli/register.cron-edit.tsSame

Test plan

  • Run openclaw cron add --help and verify updated help text
  • Run openclaw cron edit --help and verify updated help text

Changed files

  • src/cli/cron-cli/register.cron-add.ts (modified, +1/-1)
  • src/cli/cron-cli/register.cron-edit.ts (modified, +1/-1)

PR #59487: fix(cli): clarify --tz help text to cover --at time-only format

Description (problem / solution / changelog)

Summary

This is a documentation-only change — no logic modifications. Only two help text strings are changed in schedule-options.ts.

Previously the --tz help text only mentioned "cron expressions", which implied it had no effect on --at datetime inputs. This was misleading: --tz applies to all --at values including time-only HH:MM strings.

Changes

  • Updated --tz help text to explicitly mention that it applies to both cron expressions and --at time-only strings (e.g. 09:00)
  • Added example (Asia/Shanghai, America/New_York) to make the flag more discoverable

Files changed

  • src/cli/cron-cli/schedule-options.ts — two help string updates only

Related

Closes #59456

Changed files

  • src/cli/cron-cli/register.cron-add.ts (modified, +1/-1)
  • src/cli/cron-cli/register.cron-edit.ts (modified, +1/-1)

Code Example

--tz <timezone>    Timezone for cron expressions

---

--tz <timezone>    Timezone for interpreting --cron expressions and --at datetime strings (default: UTC)
RAW_BUFFERClick to expand / collapse

Summary

The help text for openclaw cron add --tz says:

Timezone for cron expressions

This is misleading — it implies the flag only affects --cron (cron expression) scheduling, when in reality its intended behavior is to also apply timezone context to --at (absolute datetime) strings. However, as reported in #59441, --tz currently has no effect on --at strings at all.

The Discoverability Problem

There are two distinct issues caused by this documentation gap:

  1. Users don't know --tz should work with --at: The description says "cron expressions" only, so users writing --at "09:00" --tz Asia/Shanghai don't realize they need to manually convert to UTC.

  2. Users don't know --tz is broken for --at: Even users who expect --tz to work with --at get no error — their timezone is silently ignored and the time is treated as UTC.

Data Supporting This Report

This caused a real misconfiguration: a daily summary job was set with --at "16:00" --tz Asia/Shanghai (intending midnight UTC+8), which silently created a job scheduled at 16:00 UTC (00:00 UTC+8 the next day) instead of 16:00 UTC+8. The bug was only discovered by manually inspecting jobs.json.

Proposed Documentation Fix

Change the help text from:

--tz <timezone>    Timezone for cron expressions

To:

--tz <timezone>    Timezone for interpreting --cron expressions and --at datetime strings (default: UTC)

And add a note in the docs / help output clarifying:

  • For --cron: the expression is interpreted in the given timezone
  • For --at: naive datetime strings (no UTC offset) are interpreted in the given timezone
  • --at strings with explicit UTC offset (e.g. 2026-04-02T09:00:00+08:00) ignore --tz

Related

  • Bug #59441 (fix for --at HH:MM + --tz not working)
  • PR #59444 (implementation fix)

extent analysis

TL;DR

Update the --tz flag documentation to reflect its intended behavior for both --cron and --at scheduling to avoid user confusion.

Guidance

  • Review the current documentation for --tz and update it to include its effect on --at datetime strings, as proposed in the issue.
  • Consider adding examples to the documentation to illustrate how --tz works with both --cron and --at scheduling.
  • Verify that the updated documentation clearly states the default timezone (UTC) and how it applies to --at strings with and without explicit UTC offsets.
  • Test the documentation changes with various scheduling scenarios to ensure they are accurate and easy to understand.

Example

--tz <timezone>    Timezone for interpreting --cron expressions and --at datetime strings (default: UTC)
 
Note:
- For `--cron`: the expression is interpreted in the given timezone
- For `--at`: naive datetime strings (no UTC offset) are interpreted in the given timezone
- `--at` strings with explicit UTC offset (e.g. `2026-04-02T09:00:00+08:00`) ignore `--tz`

Notes

The issue highlights the importance of clear and accurate documentation to avoid user misconfigurations. The proposed documentation fix should help prevent similar issues in the future.

Recommendation

Apply the proposed documentation fix to update the --tz flag description and add clarifying notes to avoid user confusion and ensure accurate scheduling.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#tensor shape#autograd error#model save/load#optimization#mixed precision

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix [Docs/UX]: help text is misleading — says "cron expressions" only, but should also apply to datetime strings [2 pull requests, 1 participants]