when-clock-skill (OpenClaw Skill Description)

1. Skill Overview

• - Entry script: INLINECODE0
• Runtime: Python 3.9+, standard library only, no pip required
• Target devices: WHEN / WHEN Voice clock (LAN HTTP, auto-detected)
• Config file: config.json in script directory (fill devices array with id and clock_ip)

2. Invocation Format

CODEBLOCK0

INLINECODE5 defaults to default (for backward compatibility with single-device config).

3. Mode Quick Reference

4. Mode Details

4.1 chime — Voice Time Announcement (WHEN Voice only)

Announces current time. WHEN devices do not support this mode.

CODEBLOCK1

Optional: --volume 1~30 (uses device current volume if not specified)

Output:

{"ok": true, "mode": "chime", "action": "voice_announce_preview", "result": "success", "status": 0, "message": "succ"}

4.2 weather — Weather Broadcast (WHEN Voice only)

WHEN devices do not support this mode.

Note: Weather broadcast currently only supports China region. More regions will be added in future updates.

CODEBLOCK3

Output:

{"ok": true, "mode": "weather", "action": "voice_weather_preview", "result": "success", "status": 0, "message": "succ"}

4.3 get_alarm — Query Alarm List

CODEBLOCK5

WHEN device alarm entries do not include volume field.

WHEN Voice output example (with volume):
CODEBLOCK6

INLINECODE20 is the --alarm-index value needed by edit_alarm / delete_alarm.

4.4 set_alarm — Add New Alarm

CODEBLOCK7

Optional params (use config.json alarm_defaults if not specified):

• - --alarm-mode: once/weekly/workday/restday/off, default INLINECODE31
• INLINECODE32: required for weekly, e.g. 1,2,3,4,5 or INLINECODE35
• INLINECODE36: ring ID (WHEN Voice: 1~50, WHEN: 1~6 beep1-beep6)
• INLINECODE37: duration level (0-based, 0~11)
• INLINECODE38: volume 1~30 (WHEN Voice only)

Maximum 10 alarms per device.

Output:

{"ok": true, "mode": "set_alarm", "action": "add_alarm", "result": "success", "status": 0, "message": "succ", "alarm_count": 3, "added_alarm": {"mode": "Once", "time": "07:30:00", "ring": "Reveille", "ring_duration_level": "2min", "volume": 20, "active_days": []}}

4.5 edit_alarm — Modify Alarm

Only specified fields are updated; other fields keep original values.

CODEBLOCK9

INLINECODE39 is required (use get_alarm to check indices first).

Output:

{"ok": true, "mode": "edit_alarm", "action": "update_alarm", "result": "success", "status": 0, "message": "succ", "alarm_count": 3, "updated_alarm": {"index": 1, "mode": "Once", "time": "07:45:00", "ring": "Reveille", "ring_duration_level": "2min", "volume": 20, "active_days": []}}

4.6 delete_alarm — Delete Alarm

CODEBLOCK11

INLINECODE41 is required.

Output:

{"ok": true, "mode": "delete_alarm", "action": "remove_alarm", "result": "success", "status": 0, "message": "succ", "alarm_count": 2, "removed_alarm": {"index": 2, "mode": "Once", "time": "09:00:00", "ring": "Weather(1x)", "ring_duration_level": "30S", "volume": 15, "active_days": []}}

4.7 set_timer — Countdown Timer

Takes current local time + offset, writes as a single-shot alarm to device.

CODEBLOCK13

INLINECODE42 format: 5m, 1h, 1h30m, 90s, 1h30m20s. Plain number treated as minutes.

Output:

{"ok": true, "mode": "set_timer", "action": "add_timer", "result": "success", "status": 0, "message": "succ", "alarm_count": 3, "timer": {"offset": "5m", "offset_seconds": 300, "trigger_at": "14:35:00", "ring": "Reveille", "ring_duration_level": "2min", "volume": 20}}

5. Ring Tone Reference

WHEN Voice (50 tones, common)

WHEN (6 tones)

Full WHEN Voice list in config.json alarm_defaults_note.ring_id_name.

6. Important Conventions

• - Alarm index (--alarm-index) is 1-based, starting from 1
• Ring ID (--alarm-ring) is 1-based, internally converted to device 0-based
• Volume range 1~30, sent as volume-1 (WHEN Voice only)
• WHEN device has no volume parameter, ring fixed to beep1-beep6
• Maximum 10 alarms per device
• INLINECODE54 devices array must have valid id and clock_ip, or script exits with code 2
• Check success: prefer ok == true, fallback to INLINECODE59
• Errors to stderr, normal JSON to INLINECODE61

7. Exit Codes