概要

2026-09-05 時点の OpenCode で cron(定期実行)機能があるかを調査し、組み込み機能がないことを確認した上で、プラグイン・GitHub Actions・OS cron を組み合わせた4つの代替手段を整理した記録。

opencode 本体の cron 機能

2026-09-05 時点の OpenCode CLI には組み込みの cron 機能は存在しない。提供されているコマンドは run / serve / session / stats などで、スケジューリング機能は含まれていない。将来のバージョンで変わる可能性があるため、導入前に opencode --help と公式ドキュメントで確認する。

非対話モードの opencode run は外部のスケジューラから呼び出す前提で設計されており、定期実行はプラグインや OS の仕組みを組み合わせて実現する。

非対話モード

opencode run "プロンプト" は自動化・スクリプティング用途に最適。--auto フラグで権限を自動承認できるため、無人実行に使える。

代替手段 1: opencode-scheduler プラグイン

OS のネイティブスケジューラ(macOS: launchd / Linux: systemd / Windows: schtasks)を利用して opencode run を定期実行するプラグイン。OS の cron フォールバックも持つ。

インストール

opencode plugin opencode-scheduler

プラットフォーム別バックエンド

プラットフォームスケジューラ備考
macOSlaunchd完全対応(監視付き実行)
Linux (systemd)systemd --user完全対応(監視付き実行)
Linux / POSIXcron (crontab)フォールバック(機会損失の補完なし)
Windowsschtaskscron サブセットで対応

主なツール

ツール説明
schedule_jobcron 式でジョブ作成
list_jobsジョブ一覧表示
update_jobジョブ更新
delete_jobジョブ削除
run_job即時実行
job_logs実行ログ表示

cron 構文

標準の5フィールド cron 式を使用する。

┌───────────── 分 (0-59)
│ ┌───────────── 時 (0-23)
│ │ ┌───────────── 日 (1-31)
│ │ │ ┌───────────── 月 (1-12)
│ │ │ │ ┌───────────── 曜日 (0-6, 日曜=0)
│ │ │ │ │
* * * * *
式意味
0 9 * * *毎日 9:00
0 */6 * * *6時間ごと
30 8 * * 1毎週月曜 8:30
0 9,17 * * *毎日 9時と17時

動作の仕組み

  1. 自然言語でジョブを記述
  2. プラグインが workdir 単位でジョブファイルを書き、OS スケジューラにタイマー登録
  3. 指定時刻に OS スケジューラが監視スクリプトを呼び出し
  4. ジョブを実行し、ログ・メタデータを更新

監視機能

ジョブは workdir 単位でスコープされ、前回実行が未完了なら次の実行をスキップする(重複防止)。timeoutSeconds で強制タイムアウトも設定可能。

代替手段 2: opencode-cron プラグイン

セッション内で cron ジョブを管理する軽量プラグイン。ジョブは SQLite(~/.config/opencode/cron.db)に保存され、実行履歴も記録される。

opencode plugin opencode-cron
ツール説明
create_cron_jobcron 式でジョブ作成
list_cron_jobsジョブ一覧(状態・次回実行時刻)
delete_cron_jobジョブ削除
enable_cron_jobジョブ有効化
disable_cron_jobジョブ無効化
watch_cron_jobsスケジューラ起動(自動トリガー)
stop_watching_cronスケジューラ停止
get_cron_history実行履歴表示

制約

セッション内で動作する設計のため、watch_cron_jobs はセッション中のみ機能する。セッション終了時には自動停止する。

代替手段 3: GitHub Actions

opencode github install で GitHub 連携をセットアップし、schedule イベントの cron ワークフローで定期実行する。CI 基盤に乗るため、マシンが起動していなくても動作する。

.github/workflows/opencode-scheduled.yml:

name: Scheduled OpenCode Task
on:
  schedule:
    - cron: "0 9 * * 1" # 毎週月曜 9時 UTC
 
# 既定では同時実行が許可される。短い間隔で動かす場合は明示的に直列化する
concurrency:
  group: scheduled-opencode-task
  cancel-in-progress: false
 
jobs:
  opencode:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: write
      pull-requests: write
      issues: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          persist-credentials: false
      - name: Run OpenCode
        uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514
          prompt: |
            Review the codebase for any TODO comments and create a summary.
            If you find issues worth addressing, open an issue to track them.

schedule イベントの注意

スケジュール実行には prompt 必須。ユーザーコンテキストがないため、PR 作成等には contents: write と pull-requests: write の権限付与が必要。出力はログと PR に反映される(コメント先のissueがないため)。
同時実行の重複防止は既定では行われない。上の例の concurrency は、同じグループの実行を同時に 1 件だけに制限する。cancel-in-progress: false の場合、実行中の run は完了まで継続する。ただし、待機中(pending)の run は既定の queue: single では新しい run に置き換えられる。複数の run を順に待たせる場合は queue: max を指定する(待機上限は 100 件。超過分はキャンセルされる)。

代替手段 4: OS cron + opencode run

シンプルな方法。OS の cron(または launchd)から opencode run を直接呼び出す。

# crontab の例: 毎日 9:00 に実行
0 9 * * * cd /path/to/project && opencode run --auto "TODOコメントを集計してサマリを作成"
  • 最小構成で動作する
  • ログ管理・実行制御は自分で実装する必要がある
  • MCP 設定(opencode.json)を拾うため workdir から実行するのが重要

方法の比較

方法バックエンド永続性セッション依存マシン稼働必須重複防止
opencode-schedulerlaunchd/systemd○なし○○
opencode-cronセッション内 (SQLite)要 watch○○-
GitHub ActionsGitHub 側○なし不要concurrency 設定時のみ
OS cron + runcron○なし○手動

推奨

ローカルでの定期実行なら opencode-scheduler、GitHub と連携した自動化なら GitHub Actions が最も実用的。

結論

opencode 自体に組み込みの cron 機能はないが、opencode-scheduler プラグイン(ローカル・OSネイティブ)と GitHub Actions の schedule イベント(クラウド・CI)の2つが主要な実現手段。用途に応じて使い分けるのがよい。

参考情報

参照元

ソースURL内容
opencode CLI ドキュメントhttps://opencode.ai/docs/cli/run コマンド等の非対話実行
opencode GitHub ドキュメントhttps://opencode.ai/docs/github/schedule イベントのワークフロー例
different-ai/opencode-schedulerhttps://github.com/different-ai/opencode-schedulerlaunchd/systemd 使ったプラグイン
kziemski/opencode-schedulerhttps://github.com/kziemski/opencode-scheduler同系統の別実装
opencode-cron (npm)https://www.npmjs.com/package/opencode-cronセッション内 cron プラグイン
opencode-scheduler (npm)https://www.npmjs.com/package/opencode-schedulerスケジューラプラグイン

関連項目