Schedule and manage an agent reminder
Who this is for: Operators who want a connected OPVS agent to return at a chosen time or when a condition becomes true.
What this does: Saves a reminder in the agent's calendar and shows you how to check, move or stop it.
Before you begin¶
- Make Reminders, installed as
@opvs-ai/reminders, available to your agent through your workspace's skill setup. - Use an agent connected to the workspace where the reminder belongs. Its OPVS token determines the workspace.
- Choose the work to resume, a date and time zone, or a real card and the status to watch.
Reminders gives the agent a reason to return. A clock can check a condition without calling a model for each empty check. An actual wake requires the calendar's live mode and must fit its policy. Saving an entry does not prove the agent has woken or finished the work.
Steps¶
- Check the calendar first. Ask your agent:
Show my scheduled reminders and read my calendar policy. Tell me its mode, time zone, quiet hours and limits before adding anything.
The agent uses reminders_list and reminders_policy_get. In shadow mode, the clock records what would fire but wakes nobody. In off mode, due fires are refused and recorded. Ask your operator about changing the mode; the agent should not switch it to live on its own.
- Describe the reminder. For a single return, give a future date, time, zone and task:
Remind me tomorrow at 10:00 Europe/Kyiv to review the proposal. Confirm the exact date and local time before saving it.
For a repeat, state its end as well:
Return every Monday at 10:00 Europe/Kyiv for the weekly review, until the end of next month. Preview the dates before saving it.
For a condition, name a real card in your workspace:
When my approval card reaches its board's done status, return once to prepare the follow-up. Check that the card and status exist before saving the reminder.
-
Check the proposed schedule. The agent resolves dates with a time zone and checks the entry against your limits. A new repeat or condition should be previewed with
reminders_preview, which saves nothing. For a card trigger, it also checks the condition withreminders_check_conditions. Ablindresult needs a correction before saving;falsemeans the condition is not true yet and still needs a valid status value. -
Save and keep the entry ID. The agent calls
reminders_create, then reads the entry back. Ask for its ID, the exact time or watched condition, and any end date. A one-shot trigger closes after its first fire; a standing trigger watches for new false-to-true transitions until its end date. -
Manage the same entry when plans change. Ask the agent to move its time, pause it or resume it. It reads the current entry with
reminders_getand sends its current version with each change. Usereminders_donewhen the work is finished, orreminders_cancelwhen you no longer need it. Cancellation is permanent; use pause for a temporary stop.
Verify it worked¶
Ask the agent to read the saved entry back. Check the title, status, zone and next fire time; for a trigger, check the exact card and condition instead. Keep the ID so you can find the same entry later.
After the scheduled time or condition, ask for reminders_runs and the outcome. A shadow run records a simulated fire. A real wake and its outcome are separate from the work's completion: verify the proposal review or follow-up itself before treating that task as finished.
Troubleshoot¶
Why was the time refused? Use a future date with an explicit zone. The agent must send an offset or Z with a timestamp; a bare local time is refused.
Why did nothing wake? Check the policy mode and the run's reason. Quiet hours may hold or skip a fire. Other refusals, such as an unreadable condition, also appear in run history. Fix the cause rather than repeatedly adding the same entry.
Why does a card trigger wait forever? Confirm the card exists and its target status is one the board uses. A nonexistent status can return false forever. An unreadable card may return blind; correct the reference or access first.
Why did an update return 409? Another session or the clock changed the entry. Read its current version, reapply the intended change and retry once.
Why did my repeat expire? Repeats have a policy limit. Ask the agent to renew the existing entry with reminders_renew, within that limit.
Does this replace OpenClaw's calendar tools? OpenClaw's native calendar_add, calendar_list, calendar_cancel and calendar_preview use the same calendar. Reminders supplies the wider workflow, including updates, pauses, conditions and history. The marketplace skill replaces the older @opvs-ai/calendar; its methods use the reminders_ prefix.