---
canonical: "https://agi-labo.com/tools/wings/docs/schedules"
title: "Schedule"
description: "日時とタイムゾーンを指定し、再試行と飛ばす回を理解します。"
section: "主要機能"
order: 5
pageType: "how-to"
lastVerifiedVersion: "1.4.16"
lastVerifiedAt: "2026-10-15"
draft: false
surfaces: ["cli", "console", "api"]
plans: ["free", "member"]
---

Schedule は、指定した時刻や間隔で Handler を動かす Trigger です。
まず[最初の Handler](/tools/wings/docs/first-handler)のように、動かすコードを登録してください。

```sh
wings trigger add <handler-id> --schedule "every:1d@09:00" --tz Asia/Tokyo --args '{}'
wings trigger list <handler-id>
```

一覧で、指定した日時とタイムゾーンを確認します。
この例は、日本時間の毎朝9時に実行します。
混雑などで、開始が遅れることがあります。

## 日時の書き方

| 指定 | 動く日時 |
| --- | --- |
| `every:5m`、`every:2h` | 5分、2時間ごと |
| `every:1d@09:00` | 毎日9時 |
| `weekly:mon,wed,fri@09:00` | 月・水・金の9時 |
| `monthly:1@09:00` | 毎月1日の9時 |
| `at:2027-01-01T09:00+09:00` | 指定日時に1回 |
| `cron:0 9 * * 1-5` | 平日9時。5フィールドの cron |

`--tz` を省略すると、CLI を動かすコンピューターのタイムゾーンを使います。
意図した時刻を伝えるため、明示してください。
最短間隔は無料枠5分、会員1分です。
新しい無料アカウントの最初の7日間は15分です。

## 再試行する回、飛ばす回

同じ回の Handler コードを、実行開始後に自動でもう一度開始することはありません。
自動で再試行するのは、実行を開始できなかった回だけです。

再試行の予定が次の回と同じ時刻か、それより後になる場合は、その回を飛ばします。
状態は `skipped`、理由は `superseded_by_next_occurrence` です。
この場合は Run を作りません。

予約済みの再試行も、動く時点で新しい回が作られていれば飛ばします。
新しい回がなければ、遅れていても動きます。

1日の利用時間を使い切った場合は、次の回より先に UTC 0時が来るときだけ0時に再試行します。
5分ごとの Schedule は、通常はその回を飛ばします。
日時指定の1回だけの Schedule は、次の回がないため再試行します。

## 外部の処理を二重に行わないために

開始を記録した回は、応答が失われてコードが動かなかった場合も開始済みと扱います。
結果やエラーを返した後は、自動では再試行しません。
外部 API が429や5xxを返した場合も同じです。

タイムアウトなどで外部の結果が分からない場合は、`dead` / `external_outcome_unknown` になります。
手動でやり直す前に、外部サービスで処理済みか確認してください。

再試行が必要な処理は、Handler の中で組み立てます。
同じ回を見分ける `event.agiWings.occurrenceId` を使って、重複を防いでください。

## 開始時刻と上限

別の Schedule 同士は同時に動くことがあります。
時刻順に開始する保証はありません。
キューからの配信を使い切ると、`queue_delivery_exhausted` で終了します。

有効な Schedule の毎時実行数の合計には[上限](/tools/wings/docs/plans-limits)があります。
上限を超える作成・変更・有効化は、`schedule_rate_limit_exceeded` で断ります。
実行数を減らす変更、無効化、削除はできます。