---
canonical: "https://agi-labo.com/tools/wings/docs/handlers-runs"
title: "Handler と Run"
description: "保存したコードと1回ごとの実行を区別します。"
section: "主要機能"
order: 4
pageType: "concept"
lastVerifiedVersion: "1.4.16"
lastVerifiedAt: "2026-10-15"
draft: false
surfaces: ["cli", "console", "api"]
plans: ["free", "member"]
---

Handler は保存した JavaScript、Run は1回の実行です。
保存せずに `wings run --file handler.js` で動かすこともできます。

通常の Handler は `export default async function (event, env)` を使います。
[Web アプリ](/tools/wings/docs/web-apps)は `fetch(request, env)` を使います。

## 外への通信を許可する

外への `fetch()` には、相手のホストに一致する Connection を Handler または Run に割り当てる必要があります。
公開ページ・RSS・公開 API も同じです。
認証のいらないホストには `wings connection add status-claude --host status.claude.com --auth none` で作成し、`wings run --file handler.js` または `wings handler deploy` に `--connection status=status-claude` を付けます。
fetch のオプションに `agiWings: { connection: 'status' }` を指定して選択できます。
ホストの完全一致や Console・API の手順は [Connection](/tools/wings/docs/connections)を参照してください。

## 更新する

```sh
wings handler deploy --update <handler-id> --file handler.js
```

更新しても、ID、Trigger、Secret、Database、実行履歴は残ります。
`--connection` を省略すると、設定済みの Connection も残ります。
指定した場合は、Connection の設定全体を置き換えます。
更新時は `--schedule` を併用できません。

## 削除する

```sh
wings handler rm <handler-id>
```

Handler を削除すると、Trigger、Secret、Connection との関連付けも消えます。
過去の Run は、この Handler の `logs` や `run show` で読めなくなります。
必要な結果は先に保存してください。

## ファイルを渡す

```sh
wings run <handler-id> --input ./input.bin
```

Handler は `await env.input()` でファイルを受け取ります。
返された Response の内容を読めるのは1回だけです。

- 渡せるのは通常のファイル1つです。容量は最大1 GiBです。
- 8 MiBまでのチャンクに分けて転送します。
- 1アカウントで同時に準備・実行できる入力は1つです。
- 入力は保存しません。終了、キャンセル、期限切れで破棄します。

## 大きなデータを外部 API とやり取りする

外部 API への fetch に `agiWings: { stream: true }` を指定すると、ストリームで転送できます。
送信は100 MiB、応答は1 GiBまでです。
指定しない場合は、送信1 MiB、応答4 MiBまでです。

外部サービス側の制限も適用されます。
Run の30秒／120秒の期限は延びません。
転送した分だけ外部の処理が進んでいる可能性があるため、自動では再送しません。

[実行時間の数え方](/tools/wings/docs/run-duration)と[実行履歴](/tools/wings/docs/history-logs)も確認してください。