---
title: "Trigger — 将来の仕事を起動する"
description: "時刻や文書条件でWorkflowまたは新しいSessionを起動し、履歴を確認して競合や成否不明から安全に復旧します。"
---

# Trigger — 将来の仕事を起動する

Project Triggerは、時刻や文書条件を満たしたときに**公開Workflowまたは新しいSession**を開始します。定期的なレビュー、一度だけの将来の仕事、Shared Documentが合意した状態になった後の作業に使います。既存Sessionへturnを追加することはありません。既存Sessionのfollow-upは別の[Session](/ja/docs/sessions)機能で、再利用する仕事を今すぐ実行するときは[Workflow run](/ja/docs/workflows)を使います。

## 権限と起動先の準備

activeなProjectを使います。viewerは内容を確認でき、automationの作成・管理にはcollaborator/adminの権限が必要です。Agentが作るTriggerでは、その現在の人間ownerにもactiveなProject collaborator/admin権限が必要です。Sessionの起動先にはactiveなcollaborator/adminのAgentを選びます。開始時には実行ownerのruntimeとAgent設定が利用可能でなければなりません。予定を登録してもrepository、tool、本番操作の権限が増えることはありません。

WebUIではProjectの**Triggers**を開いて**New trigger**を選ぶか、対応する新しいSession/Workflowの依頼を準備するときに**When**を使います。起動先、予定、timezone、入力を選び、previewを確認して保存します。Triggersの一覧と詳細に、次回の予定、履歴、実行可能な管理操作が表示されます。仕事の中身は起動したSessionやRunを開いて確認します。

以下のCLI操作は、Projectへアクセスできる実行中のaachat Session内のAgent向けです。**すべての`chat trigger`コマンドに`--project <team>/<project>`が必須**で、cwdでは選択しません。結果を使う前に、応答の`project`を確認します。placeholderは実際の名前とIDへ置き換えます。

```bash
chat trigger list --project <team>/<project>
chat workflow list --project <team>/<project>
chat workflow show greeting --project <team>/<project>
chat project members <team>/<project> --runtime-profiles
```

同じautomationがないと判断する前に、`list`が返す`next_command`を`null`になるまで辿ります。公開Workflowの正確なslug、またはactiveなAgentの正確な名前を使います。CLIが解決するので、内部UUIDに置き換えません。

## 平日のWorkflow Triggerを作る

先に[Workflowガイド](/ja/docs/workflows)の`greeting`を作成・公開するか、実在するWorkflowを選び、`show`のschemaに入力を合わせます。次の完全な入力をWorkflow Bundleの外の`trigger.json`へ保存します。例を使う前に日付を将来の期間へ更新してください。

```json
{
  "name": "Weekday greeting",
  "description": "Generate a greeting on weekday mornings.",
  "schedule": {
    "kind": "calendar",
    "time": "09:00:00",
    "days": ["mon", "tue", "wed", "thu", "fri"],
    "timezone": "Asia/Singapore",
    "starts_on": "2026-09-07",
    "ends_on": "2026-12-31"
  },
  "target": {
    "kind": "workflow",
    "workflow": "greeting",
    "input": {"reader": "Alex"}
  }
}
```

予定だけをpreviewし、その後1回だけ作成します。

```bash
jq '{schedule}' trigger.json | chat trigger preview --project <team>/<project> --stdin
chat trigger create --project <team>/<project> --stdin < trigger.json
chat trigger show <trigger-id> --project <team>/<project>
```

`preview`はautomationを作らず、serverが正規化した予定と次の3回の時刻を返します。現地時刻、timezone、日付を確認します。`create`は有効なTriggerを作るため、条件を満たすと仕事が起動し得ます。IDを控え、`show`を読み、起動後に履歴を確認します。occurrenceのacceptedは起動先を開始したという意味で、仕事の成功ではありません。

名前はtrim後1–120文字、任意のdescriptionは1,000文字までです。Workflowの`input`は作成・編集時と起動時に、その時点の公開入力schemaで検証されます。互換性のない入力契約を公開すると既存Triggerが自動pauseする場合があります。Triggerの起動先は公開Workflowで、親Workflow Revisionが固定する子とは異なり、作成時に公開参照先を固定しません。

## 新しいSessionを起動する

完全な入力の`target`をSession向けに置き換えます。例のmemberは実在するProject memberへ変更します。`workspace_repo`を指定する場合はProject repositoryまたはTeam default repositoryに一致させ、それ以外では省略して有効な設定済みrepositoryを使います。

```json
{
  "kind": "session",
  "agent": "reviewer.yourname",
  "prompt": "Review the Project's latest results and record the next decision.",
  "launch": {
    "runtime_kind": "codex-acp",
    "config_overrides": []
  },
  "workspace_repo": "owner/repository",
  "working_branch": "main"
}
```

`prompt`は空ではない依頼内容で、上限は100,000 bytesです。`launch`、`workspace_repo`、`working_branch`は任意です。`launch`を省略するとserverがAgentの既定設定を解決します。Runtimeのkindと型付きconfigは、`chat project members <team>/<project> --runtime-profiles`が示すものだけを使います。公開されているID optionなら、overrideは`{"id":"mode","value":{"type":"id","value":"agent-full-access"}}`という形です。そのAgentが示していないoptionはコピーしません。空のoverride listは独自optionを選択しません。`working_branch`には設定済みのProjectまたはTeam repositoryが必要です。別のrepositoryを選ぶ場合は先にProject/Teamのrepository設定を更新し、有効な設定済みrepositoryでよければ`workspace_repo`を省略します。どちらのrepositoryも存在しない場合は`working_branch`も省略します。working branch名はrepositoryの選択であって、そこへの直接pushの許可ではありません。

## 予定のリファレンス

以下は個別の`schedule` objectで、createの完全な要求ではありません。UTC timestampは末尾に`Z`を付け、有効なIANA timezoneを指定します。例の日付が期限切れになる前に置き換えてください。

```json
{"kind":"once","at":"2026-09-07T01:00:00Z","timezone":"Asia/Singapore"}
```

```json
{"kind":"calendar","time":"09:00:00","days":["mon"],"timezone":"Asia/Singapore","starts_on":"2026-09-07","ends_on":"2026-12-31"}
```

```json
{"kind":"interval","every_seconds":3600,"starts_at":"2026-09-07T01:00:00Z","ends_at":"2026-09-30T01:00:00Z","timezone":"Asia/Singapore"}
```

| kind | 意味と制約 |
|---|---|
| `once` | 将来のUTC `at`に1回起動。timezoneで現地時刻の文脈を指定します。 |
| `calendar` | 現地の`HH:MM:SS`、重複しない1つ以上の曜日`mon`–`sun`、現地日付の`starts_on`。任意の`ends_on`はその日を含みます。 |
| `interval` | UTC基準で最低300秒（5分）の周期。`starts_at`省略時は受付時刻、必須の`ends_at`はその時刻を含みます。 |
| `document_match` | 同じProjectのfrontmatter条件。時刻previewとRun nowはありません。 |

calendarはtimezoneの夏時間規則に従います。現地時刻が重複する場合は早い方の時点に1回、存在しない現地時刻は1秒ずつ最大4時間進めて最初の有効な時刻を選びます。timezoneの切替時期はserverのpreviewを必ず確認します。intervalは経過秒数であり、「毎日同じ現地時刻」ではありません。これらの制約は既存Sessionのfollow-upとは別です。

## 文書が一致したら起動する

起動先を準備した完全なcreate入力で、次の`schedule`を使います。

```json
{"kind":"document_match","on":"reviews/release","match":{"status":"approved","ready":true}}
```

同じProjectの`docs/reviews/release.md`を監視します。一致する[Shared Document](/ja/docs/shared-documents)のfrontmatter例です。

```yaml
---
title: Release review
status: approved
ready: true
---
```

`on`は正確な`kind/doc_id`で、file pathや別Projectの文書ではありません。`match`には少なくとも1つのfieldが必要です。値はstring、number、booleanの完全一致で、複数fieldはAND条件です。`true`はboolean、`"true"`は別のstringです。array、object、nullは条件値に使えません。

文書条件は作成時や再検証時にすでに一致する可能性があります。以後の保存のたびに起動するのではなく、最大1回だけ起動します。監視文書の保存で条件が評価され、文書条件に`run`は使えません。完了後に再び待ち受けるには、新しい文書条件を含む完全なeditを送ります。

## 既存Triggerを管理する

変更前に`show`を読みます。`state_version`は変更でも起動でも進むため、固定値を書いたり古い値を再利用したりしません。`show`は現在のversionを含む、再利用可能な完全な`edit_input`も返します。nullでなければ保存し、確認したversionを保って必要なfieldを変更し、全体を置き換えます。

```bash
chat trigger show <trigger-id> --project <team>/<project> > trigger-state.json
jq '.edit_input' trigger-state.json > trigger-edit.json
```

```bash
chat trigger edit <trigger-id> --project <team>/<project> --stdin < trigger-edit.json
```

2つのコマンドの間に`trigger-edit.json`を意図どおり編集してください。`edit`は部分patchではなく全置換です。時刻予定を変える場合は送信前にpreviewします。起動先が利用できなければ`edit_input`はnullです。新しい起動先を選び、name、schedule、target、任意のdescription、最新の`state_version`を含む完全な入力を作ります。CLI/serverの版移行中に古いserverが起動先を利用不可として返し、edit inputを作れない場合もあります。UUIDで代替しません。返されたSessionのedit inputで、受理済みのrepository既定選択を保つなら`working_branch: ""`、指定branchを保つなら空でない値を維持します。

| 操作 | CLI | 期待結果 |
|---|---|---|
| 一覧 | `chat trigger list --project <team>/<project> [--cursor <cursor>] [--limit 50]` | 状態、次回時刻、直近結果。`next_command`を辿ります。 |
| 詳細 | `chat trigger show <trigger-id> --project <team>/<project> [--cursor <cursor>] [--limit 50]` | 状態・version、操作、直近履歴。古い履歴は`next_occurrences_command`を辿ります。 |
| preview | `chat trigger preview --project <team>/<project> --stdin` | `{"schedule": ...}`を入力する読み取り専用の予定確認。 |
| 作成 | `chat trigger create --project <team>/<project> --stdin` | 新しい有効なTrigger。 |
| 置換 | `chat trigger edit <trigger-id> --project <team>/<project> --stdin` | JSON内の`state_version`を使った全置換。 |
| 今すぐ実行 | `chat trigger run <trigger-id> --state-version <version> --project <team>/<project>` | 確認したactiveな時刻Triggerで通常のoccurrenceを1回作成。予定は不変。 |
| pause | `chat trigger pause <trigger-id> --state-version <version> --project <team>/<project>` | 将来の起動を停止。 |
| resume | `chat trigger resume <trigger-id> --state-version <version> --project <team>/<project>` | 提示されている場合、手動pauseから再開。 |
| 削除 | `chat trigger delete <trigger-id> --state-version <version> --project <team>/<project>` | 履歴を保って将来の起動を除去。 |

角括弧は任意引数です。一覧・履歴のlimitは1–100です。pauseとdeleteは、起動済みのSessionやWorkflow Runを取消・削除しません。必要で権限がある場合は起動先を別に管理します。

## 結果を読み、重複作業を避ける

Triggerの状態は`active`、`paused`、`completed`です。occurrenceの状態は`accepted`、`skipped`、`failed`です。acceptedなら`workflow_run_id`または`session_id`と起動先の現在の状態を確認します。`run`はoccurrenceを同期的に返しますが、起動先の成果は待ちません。`state_version`は進み、`next_scheduled_for`と定期予定は変わりません。

| occurrence・条件 | 挙動と対処 |
|---|---|
| 前回acceptedの起動先がまだactive | `previous_run_active`でskipします。queueには積みません。前の起動先を確認します。 |
| 前回Workflow Runが`attention_required` | 次のoccurrenceが前Runを置き換えて取消し、`previous_run_superseded`で新しい仕事を開始します。止まったRunを継続したければ次回より前にretryします。Triggerを進めるためだけの手動取消は不要です。 |
| schedulerの停止後に復帰 | 古い予定は`superseded_during_downtime`でskipし、期限を迎えた最新の1回だけが開始対象になります。 |
| 起動失敗 | Triggerがpauseします。`occurrence.reason`と`pause_message`を読み、原因を直して完全なeditで再検証します。 |

pause済み・completedのTriggerと文書条件は今すぐ実行できません。revisionが変わった場合や起動処理中の場合は、次の起動先を開始する前に競合します。強行せず返された操作に従います。

## 競合、pause、成否不明から復旧する

version競合では、エラーが返した正確なProject指定付き`show`を実行し、新しい状態から判断し直します。何が変わったかを確認せず、古い要求のversionだけ差し替えません。

**createは冪等ではありません。** 構造化エラーが成否不明を示した場合、create JSONを再送しません。返された読み取り専用の`list`を全page辿り、Triggerがすでにできていないか照合します。`run`の成否不明でも再実行せず、返された`show`とoccurrence履歴から開始済みか確認します。それでも証拠が足りなければ、重複作業を作らず未解決として扱います。これは、通信不明時に同一payloadを再送できる[Workflow completion](/ja/docs/workflows)とは異なります。

手動pauseと自動pauseでは復旧が異なります。

| 状態・理由 | 復旧 |
|---|---|
| 手動pauseした文書条件 | 提示されていれば直接resumeします。 |
| 手動pauseした時刻予定 | `show`が将来の予定を確認し、ある場合だけresumeを提示します。なければ完全な将来予定へ置換します。edit後も手動pauseは維持されるため、`show`で最新versionを読み、提示された`resume`を実行します。確認に失敗したら推測せず`show`が失敗します。 |
| `input_contract_invalid` | 現在の公開Workflow入力schemaへ合わせ、完全なeditを送ります。 |
| `target_unavailable` | 利用可能なWorkflow/Agentへ復旧または変更し、完全なeditを送ります。 |
| `permission_revoked` | 必要な権限を戻してeditで再検証します。creatorが実行ownerの所有でなくなった場合、古いTriggerは復旧できず、現在のownerの下で新しく作ります。 |
| `project_inactive` | Projectを仕事ができる状態へ戻し、editで再検証します。 |
| `completed` | 将来の時刻予定または新しい文書条件へeditした場合だけ再びactiveになります。 |

serverは変更時と起動時にProject、creator、実行ownerとの関係、起動先、Runtimeの権限を再確認します。previewや前回の成功は、次回も動く保証ではありません。起動先の成果を読み、実行そのものには[Workflowの復旧手順](/ja/docs/workflows)や[Sessionガイド](/ja/docs/sessions)を使います。