メニュー経路: ダッシュボード > タスク > ローカル

ローカルワーカー (CLI)

概要

ローカルワーカーは、PC 上のファイルにある関数です。その PC で 3Min API CLI（npm パッケージ @3minapi/cli）が動き、AI が送ったタスクを取得して、各タスクの入力で関数を実行し、結果を報告します。AI とあなたの PC が直接通信することはなく、間には 3Min API が入ります。

公開 URL もポート開放も不要です。 CLI は外向きのリクエストだけを送ります
関数が読み取ったものは PC から出ません。 出ていくのは関数が返した値だけです
ファイル 1 つ = 関数 1 つ = ワーカー 1 つ

公開 URL にあるサーバーについてはタスク（パブリックワーカー）をご覧ください。

用語	意味
ホスト	CLI を実行する PC。ダッシュボード → タスク → ローカルで PC ごとに 1 つ追加します
ホストトークン	`tm_host_…`。その PC の CLI がログインに使います。表示は一度だけです
プロジェクトフォルダ	既定は `~/3minapi`: `3minapi.json`、`workers/`、`data.db`、`.gitignore`。ホストごとに 1 つ
`data.db`	プロジェクト内の SQLite ファイル。すべての結果がここに保存され、ワーカー独自のデータも置けます
結果リーダー	`data.db` に保存された結果を AI が読めるように、CLI が登録する組み込みのローカルワーカー

種類	`worker_list` の `kind`	タスクの届き方	Free での数	API 呼び出し
パブリックワーカー	`"public"`	3Min API があなたの URL へ POST する	1	配信は 0 回
ローカルワーカー	`"local"`	CLI が取得する（既定はリアルタイム通知、または定期確認）	無制限	リアルタイム: 待機中は 0 回。定期確認: 取得は空でも毎回 1 回

インストールと更新

コマンドは PC のターミナルで実行します — Windows では ターミナル または PowerShell（スタートメニュー）、macOS では ターミナル（アプリケーション → ユーティリティ）です。

Node.js 24.12 以上。 node -v でバージョンを確認できます。ない場合や古い場合は nodejs.org から LTS をインストールし（Windows なら winget install OpenJS.NodeJS.LTS でも可）、新しいターミナルを開いてください
CLI:

npm install -g @3minapi/cli
3minapi --version

Windows PowerShell では "running scripts is disabled on this system" と表示されて拒否されることがあります。3minapi の代わりに 3minapi.cmd と入力してください — 何も変更せずに動きます。自分のアカウントでスクリプトを許可したい場合は Set-ExecutionPolicy -Scope CurrentUser RemoteSigned で設定できます（元に戻すまでその設定が残ります）
npx @3minapi/cli <command> ならインストールせずに実行できます
更新も同じコマンドです: npm install -g @3minapi/cli
3minapi doctor は Node.js・設定・トークン・ネットワーク・プロキシ設定を確認し、直すべき点を示します。プロキシ環境では NODE_USE_ENV_PROXY=1 を設定してください

クイックスタート

ローカル タブの設定カードと同じ順序です。

npm install -g @3minapi/cli
3minapi init
3minapi worker new hello
3minapi worker run hello --input '{"message":"hi"}'
3minapi login
3minapi start

3minapi init が ~/3minapi にプロジェクトを作ります（場所を選ぶなら 3minapi init <folder>）。以後、コマンドはどのフォルダからでも動きます
3minapi worker new hello がテンプレートから workers/hello.mjs を作ります。まず説明を、次に handler を編集してください
3minapi worker run hello --input '…' は PC 上で 1 回だけ実行します — タスクも API 呼び出しもありません。正しく動くまで繰り返してください
ダッシュボード → タスク → ローカル → ホストを追加 でトークンをコピーし、3minapi login のプロンプトに貼り付けます
3minapi start がワーカーファイルをローカルワーカーとして登録し、そのタスクを実行します。これで AI の worker_list に kind: "local" として表示されます

ワーカーファイルがないと start はすぐに終了します。

コマンド

すべてのコマンドはどのフォルダからでも動きます。--json で機械可読な出力になり、3minapi help <command> ですべてのフラグを確認できます。

ホスト

コマンド	すること
`3minapi init [folder]`	ホストのプロジェクトを作成。何度実行しても安全。ターミナルがない場合は `--yes` が必要。`--move` で移動
`3minapi login`	ホストトークンを保存（入力はマスク表示）。スクリプトでは `--with-token` で標準入力から読み取り
`3minapi logout`	保存したトークンをこの PC からのみ削除
`3minapi start`	ワーカーファイルを登録し、停止するまでタスクを実行。`--mode poll` で既定のリアルタイムの代わりに間隔ごとに取得。Ctrl+C で停止
`3minapi start --detach`	同じ動作をバックグラウンドで。再起動後は自動で始まりません
`3minapi reload`	実行中の `start` にワーカーファイルを読み直させて登録。実行中のタスクは続行。1 回
`3minapi stop`	どこで起動したかにかかわらず、この PC の `start` を停止
`3minapi status`	`start` が実行中か、ローカルワーカー、繰り返しタスク、残りの呼び出し回数。1 回
`3minapi logs [-f]`	CLI 自身のログ — 取得、停止、エラー
`3minapi doctor`	環境の確認。トークンは送らず、呼び出し回数も使いません
`3minapi paths`	プロジェクトのファイルと CLI 自身のフォルダの絶対パス

ワーカー

コマンド	すること
`3minapi worker new <name> [--ts]`	`workers/<name>.mjs` を作成（`--ts` なら `.mts`）。`start` が実行中ならすぐ登録（`--no-reload` で省略）
`3minapi worker run <name> --input '<json>'`	ローカルで 1 回実行。`--input-file <file>` を使うと Windows のシェルのクォート問題を避けられます
`3minapi worker list`	プロジェクトのワーカー一覧。それぞれ読み込めるかを確認。API 呼び出しなし
`3minapi worker logs <name> [-f]`	ワーカー 1 つのログ: `ctx.log`、コンソール出力、スタックトレース付きのエラー
`3minapi worker delete <name>`	3Min API からローカルワーカーとそのタスク履歴を削除し、続いてファイルを削除。元に戻せません

結果と履歴

コマンド	すること
`3minapi worker results list`	保存された結果を新しい順に。`--worker`、`--since`、`-n`
`3minapi worker results show <task_id>`	保存された結果 1 件の全体。繰り返しタスクの回は `--run <n>`
`3minapi worker results runs <task_id>`	繰り返しタスクの回の一覧
`3minapi worker results describe <task_id>`	結果 1 件が持つパス。`--worker <name>` でワーカーの結果を形ごとにまとめる
`3minapi worker results query "<SQL>"`	保存された結果への読み取り専用 SQL。API 呼び出しなし
`3minapi worker results prune --before <date>`	その日付より古い保存結果を `data.db` から削除
`3minapi tasks prune --before <date>`	その日付より前に終わったタスクの、このホスト上の記録を削除。最近のものと未完了のものは残ります
`3minapi dashboard`	ブラウザで開く読み取り専用ページ: 実行、結果、ワーカー、ログ。ログイン不要、API 呼び出しなし

dashboard --detach でバックグラウンド実行、dashboard url でリンクを再表示、dashboard stop で終了します
dashboard --lan はネットワーク上の他の機器にも 暗号化されない HTTP で提供します。信頼できるネットワークでのみ使ってください
破壊的なコマンドと --lan は確認を求めます。 ターミナルがない場合（または --json の場合）は --yes が必要です

ワーカーの書き方

workers/ 内のファイル 1 つがワーカー 1 つで、名前はファイル名になります。

名前: 英小文字・数字・_・-、50 文字以内。_ で始めない、Windows のデバイス名（con、aux など）でないこと。大文字・小文字を区別せず、すべてのワーカー — パブリックワーカーや他の PC のワーカーも含めて — で一意です
.mjs（既定）または .mts/.ts — TypeScript はビルドなしで動きます（enum・namespace は不可）

// workers/rename_photos.mjs
export const description =
	'Renames the photos in a folder by the date taken. input: { folder: string }';
export const timeoutMs = 10 * 60_000; // 任意 — 既定 60 秒、最大 23 時間

export async function handler(input, ctx) {
	await ctx.report('Scanning the folder'); // 進捗 — task_get に表示されます
	if (ctx.signal.aborted) return; // キャンセル済み、またはまもなくタイムアウト
	// … 実際の処理 …
	return { renamed: 42 }; // → completed。この値が結果です
	// throw new Error('Folder not found')  // → failed。メッセージがエラーになります
}

export	ルール
`description`	必須。AI が `worker_list` で見る内容、500 文字以内。入力の形をここに書いてください
`timeoutMs`	任意。既定 60 秒、最大 23 時間
`inputSchema`	任意。JSON Schema の小さなサブセット（`type`、`properties`、`required`、`enum`、`items`）。検証は PC 上でのみ行われます
`handler`	必須。`async (input, ctx) => result`

`ctx`	内容
`ctx.report(message)`	進捗メッセージ。256 文字で切り捨て。1 回ごとに 1 回の呼び出し
`ctx.log(message)`	ワーカーログにだけ書き込む
`ctx.env`	システムの環境変数 + プロジェクトの `.env`（`.env` が優先）。`THREEMINAPI_` で始まる変数は除かれます
`ctx.signal`	キャンセルまたはタイムアウトで発火する AbortSignal

handler の終わり方	タスクの状態
`return value`	`completed`。値は JSON でなければなりません
`throw`	`failed`。メッセージ（`cause` を含む）はトークンをマスクし、4,000 文字で切り捨て。スタックはローカルのログにだけ残ります
タイムアウト	`failed`（`timeout`）
キャンセル	`ctx.signal` が発火し、2 秒後に実行が終了されます。戻り値は送られません

変更の反映: handler のコードと .env の変更は次のタスクから反映されます。ファイルの追加・名前変更、説明の変更には 3minapi reload（または次の start）が必要です。worker new は自動で reload します
ファイルを削除しても 3Min API からワーカーは消えず、そのタスクは失敗します。3minapi worker delete <name> を使ってください
シークレット（あなた自身の API キーなど）はプロジェクトの .env に置きます。.gitignore で除外済みです。UTF-8 で保存してください（UTF-16 は拒否されます）
同じタスクが 2 回届くことがあります（at-least-once）。副作用のあるワーカーは重複に耐えられるようにしてください
最上位に _3minapi キーを持つ結果は reserved_result_key で失敗します
ワーカーは data.db に独自のデータを保存できます: node:sqlite で new URL('../data.db', import.meta.url) を開いてください。_3minapi_ で始まるテーブルは CLI のもので、読み取り専用です

AI から実行する

start が実行中なら、いつも通り AI に頼むだけです — ツール名は不要です。

「D:\Photos\2026 の写真を日付で名前変更して」
「BTC の価格を 1 分ごとに 10 回確認して」
「価格チェックを止めて」

AI は worker_list → task_create → task_get を使います。タスクは CLI が取得するまで 3Min API で待機します — リアルタイムモード（既定）で動いている CLI は通知を受けて取得し、定期確認モードは次の確認で取得します。task_get はそれまで delivery: "pending"、取得後は "delivered" を示します。

繰り返しタスク

ローカルワーカーに限り、task_create に repeat を渡すと同じ入力を一定間隔で実行します — タスクは 1 つで、すべての回が同じタスク ID を使います。

{
	"worker": "price-feed",
	"input": { "symbol": "BTC" },
	"repeat": { "interval_seconds": 60, "max_runs": 10 }
}

フィールド / ルール	値
`interval_seconds`	10〜604,800（7 日）。次の回の時刻に前の回がまだ実行中なら、その回はスキップ
`max_runs`	任意。省略するとキャンセルするまで繰り返します — 止めるには AI にキャンセルを頼んでください
状態	`working` のまま。`repeat` に `runs`、`failed`、`last_run_at` が表示されます。最後の回の後は要約付きで `completed`
失敗	失敗した回があっても止まりません。5 回連続で失敗 → `failed`（`repeat_failed`）
コスト	CLI がタスクを受け取るための呼び出しとは別に各回 1 回の呼び出し。終わりなしの 1 分ごとなら月約 43,200 回
変更	キャンセルして新しく作成
CLI が止まっているとき	一時停止。24 時間 + 1 間隔のあいだ回の報告がなければ → `failed`
パブリックワーカー	不可 — `repeatRequiresLocalWorker`

各回の結果は PC に別々の行として保存されます（run_no 1, 2, …）。

結果の読み取り

すべての結果は PC の data.db に保存されます。 約 100 KB 以下の結果は 3Min API にも送られ、task_get で AI に届きます。それより大きい結果は送られず、タスクは result._3minapi に代わりの値（stored_locally: true、タスク ID、サイズ、shape の要約、reader 名）を入れて完了します。

AI — ホストの結果リーダーを通じて読みます。これは _results_ + ホスト ID の 8 文字という名前の、組み込みのローカルワーカーです。worker_list はこれをワーカー一覧ではなく、hosts 内のそのホストの results_reader として表示します。計算は PC 上で行い、答えだけを返します。下の task_result_* ツールが各手順をこのワーカーに渡し、指定された task_id や worker から PC を選ぶため、AI がその名前を知る必要はありません。

順序	ツール	用途
1	`task_result_describe` (`task_id` または `worker`)	まず形を把握します。結果にないパスは NULL として読まれるため、形が混在すると合計が誤ります
2	`task_result_query` (`sql`, `worker`)	ビュー `results` への読み取り専用 SQL。集計して答えだけを返します
3	`task_result_read` (`task_id`, `path`, `offset`)	約 90 KB ずつの生データ。生データそのものが必要なときだけ

リーダーのタスクは 1 つにつき最低 4 回の呼び出しがかかり、CLI が取得するまで待ちます
リーダーは、ワーカーファイルが 1 つ以上ある状態で start を実行すると登録されます

あなた — 3minapi worker results list/show/describe/query または 3minapi dashboard。data.db は自動では整理されません。worker results prune を使ってください。個人情報を含むことがあります。

AI に CLI を実行させる

AI クライアントの中には、許可すれば PC でコマンドを実行できるものがあります — Claude Code や Codex などのコーディングエージェント、一部のデスクトップアプリです。Web 版の ChatGPT などはできないため、自分でコマンドを実行して、出力を貼り付けてください。

AI ができること	AI が触れてはいけないもの
`workers/*.mjs`（説明、handler）と `3minapi.json` の編集	ホストトークン — チャットにもコマンドラインにも絶対に入れない（`3minapi login` がプロンプトで聞きます）
`worker new`、`worker run`、`reload`、`status`、`doctor`、`logs`、`worker results …` の実行	CLI 自身のフォルダ（`credentials.json`、`control.db`）— `3minapi paths` 参照
場所を確認したうえで `init <folder>` または `init --yes` の実行	`data.db` 内の `_3minapi_` で始まるテーブル

ターミナルがない場合、破壊的なコマンドには --yes が必要で、--yes が唯一の確認になります。worker delete --yes の前にはユーザーに確認してください — ワーカーとそのタスク履歴が削除されます
--json で AI が解析できる出力になります。エラーは { "error": { "kind", "message", "exitCode", "code"?, "resetAt"? } } の形で返ります。呼び出し回数の上限による停止で、リセット時刻がわかる場合は resetAt も付きます

ホストとトークン

状況	すること
複数の PC	PC ごとにホストを 1 つ追加。PC 1 台 = ホスト 1 つ = プロジェクト 1 つ。ワーカー名は PC 間で重複できません
トークンの紛失・漏えい	ホスト画面でトークンをローテーション。古いトークンはすぐに無効になり、それを使う CLI は停止します
別の PC への移行	トークンをローテーション → プロジェクトフォルダをコピー → 新しいトークンで `3minapi login` → `3minapi start`。ワーカーと履歴はそのまま
ホストの削除	そのローカルワーカーとタスク履歴を削除。最初からやり直すときだけ使ってください。実行中の CLI は停止します
フォルダの移動	`3minapi stop` → 移動 → そのフォルダ内でコマンドを実行、または `3minapi init <folder> --move`

ホスト画面には CLI のタスクの受け取り方（リアルタイムまたは定期確認）、最後の接続または確認、確認間隔（定期確認のみ）、同時実行数、バージョン、プラットフォームが表示されます — CLI が報告した事実であり、現在の状態ではありません。

制限と呼び出し回数

項目	値
ローカルワーカー	全プランで無制限
受信（リアルタイム、既定）	接続の維持に呼び出しはかかりません。接続・再接続ごとに 1 回とその後の追いつき取得 1 回、タスクやキャンセルの通知で取得するたびに 1 回。接続はネットワーク側の事情で 1 日に数回切れ、自動で再接続するため、作業がなくても少し呼び出しを使います — 1 日 6 回切れると 1 日約 12 回、月約 360 回
受信（定期確認）	待機中のタスクがなくても、取得は毎回 1 回の呼び出しです。既定の 60 秒ごとで 1 日約 1,440 回、月約 43,200 回
その他の呼び出し	受信確認 1 回ごとに 1、報告（`ctx.report` と最終結果）1 回ごとに 1、繰り返しの各回に 1、`reload`/`status` に 1
同時実行	`concurrency`、既定 4（1〜50）。取得 1 回あたり最大 `concurrency` 件
期限	作成から 24 時間以内に取得されなければ → `failed`（1 時間ごとの確認のため最大約 25 時間）
タスク履歴	有料プランは最低 60 日。Free では、ローカルワーカーとその実行履歴はワーカー登録から 7 日後に削除されます。`reload` または次の `start` で再登録されます
呼び出し回数の上限に達したとき	CLI は自ら停止し（終了コード 5）、再起動しません。報告はブロックされません
3Min API に送られる結果	約 100 KB。それより大きい結果は PC に残ります（代わりの値を送信）
ローカルのログ	既定で 30 日 / 300 MB 保持（`logRetentionDays`、`logMaxBytes`）

呼び出しを減らすには、既定のリアルタイムモードを使ってください。ネットワークの都合で定期確認が必要なら、3minapi.json の pollIntervalMs を大きくして（タスクの取得は遅くなります）再起動してください。

concurrency 件がすべて実行中のあいだ、CLI は新しいタスクを取得しません — そのタスクは pending のままです（キャンセル通知は届きます）。これで決まる処理量は 3minapi start と 3minapi status に表示されます。

状態の確認とトラブルシューティング

動いているか? その PC で 3minapi status を実行して確認してください。Web の CLI受信 や、worker_list が AI に渡す最後の確認・接続時刻は過去の事実であり、現在の状態ではありません。

症状	原因と対処
タスクが `delivery: "pending"` のまま `working`（Web では PC待ち）	CLI がまだ取得していません。その PC で `3minapi start` を実行してください
`3minapi start` がリアルタイム接続を開けないと表示する	社内のプロキシやファイアウォールが遮断しています。`3minapi doctor` で確認し、`--mode poll` で起動する（または `receiveMode: "poll"`）と間隔ごとに取得します
`Not picked up within 24 hours — the 3Min API CLI on the user's PC did not fetch it.`	CLI が 24 時間止まっていました。起動してタスクを送り直してください
`No run was reported for 24 hours — the 3Min API CLI on the user's PC stopped running it.`	繰り返しタスクの CLI が止まりました。起動してタスクを作り直してください
`Worker did not respond within 24 hours.`	CLI が取得したものの結果を報告できなかったローカルタスクです — クラッシュ後に PC が止まったままでした。再実行はされません
`host_stopped` で失敗	実行中に CLI を停止しました（Ctrl+C または `stop`）。繰り返しタスクはその回だけを失います
`host_restarted` で失敗	タスクの途中で PC または CLI が落ちました。実行されたかは不明で、再実行はされません
AI が古い形の入力を送る	`3minapi reload` をせずに説明を変更しました
`worker_list` にワーカーがない	新しいファイルを `reload` していない、読み込みエラー（`3minapi worker list`）、または Free の 7 日削除（`reload`）
CLI が `worker_name_taken` で名前を拒否する	別のワーカー（パブリック、または別の PC）がその名前を使っています。ファイル名を変えてください
CLI が終了コード 4 または 5 で終了	4: トークンが無効、またはプランがない — もう一度 `login`。5: 月間の呼び出し回数を使い切った

終了コード

コード	意味
0	正常
1	失敗
2	使い方の誤り（`--yes` の不足を含む）
3	環境または設定のエラー
4	停止: トークンが無効、またはアカウントにプランがない（Free もプランに含む）
5	停止: 月間の呼び出し回数を使い切った
130	中断（Ctrl+C）

4 または 5 の後は、何も自動では再起動しません。

失敗したローカルワーカーのタスクの error.data.reason

reason	意味
`handler_error`	handler が例外を投げた
`timeout`	`timeoutMs` を超えて実行された
`invalid_input`	`inputSchema` に合わない — 実行されていない
`invalid_worker`	ファイルはあるが使えない — `handler` がない、名前の重複、または import エラー
`worker_not_found`	その PC にそのファイルがない
`unsupported_syntax`	CLI がビルドなしで実行できない TypeScript（例: `enum`）
`result_too_large`	約 100 KB を超え、PC にも保存できなかった
`reserved_result_key`	結果の最上位に `_3minapi` キーがある
`host_stopped`	実行中に CLI が停止された
`host_restarted`	実行中に PC または CLI が落ちた。次の `start` で報告される
`repeat_failed`	繰り返しタスクが 5 回連続で失敗した

プロトコルの概要

CLI と 3Min API がどう連携するかの参考情報です。

配信

Pull: リアルタイムモードでは CLI が接続を保ち、通知を受けたとき（と接続のたびに 1 回）3Min API へ待機中のタスクを問い合わせます。定期確認モードでは pollIntervalMs ごとに問い合わせます。どちらも今すぐ実行できる分だけを取得します
Ack: 受信をすぐに確認します（delivery が "delivered" になります）。60 秒間確認がなければタスクは再送されます — 最大 6 回、その後 failed
At-least-once: 同じタスクが 2 回届くことがあります
キャンセル: リアルタイムモードは通知で、定期確認モードは次の取得で伝わり → ctx.signal。タスクは cancelled のままです
報告: 進捗と最終結果はホストトークンで送り返されます。ネットワークで失敗した報告は、最大 24 時間再試行されます

サイズ

項目	上限
`input`	100 KB
送信される結果	約 100 KB（100 KiB から 1 KiB のエンベロープを引いた値）
`ctx.report`	256 文字
エラーメッセージ	4,000 文字
ワーカーの説明	500 文字
ワーカー名	50 文字

3minapi.json（優先順位: フラグ > 環境変数 > プロジェクトファイル > 既定値）

キー	既定値	範囲	環境変数
`workersDir`	`workers`	プロジェクト内	—
`receiveMode`	`live`	`live` または `poll`	`THREEMINAPI_RECEIVE_MODE`
`pollIntervalMs`	60000	5000–3600000（定期確認モードのみ）	`THREEMINAPI_POLL_INTERVAL_MS`
`concurrency`	4	1–50	`THREEMINAPI_CONCURRENCY`
`localServerPort`	3180	1024–65535	`THREEMINAPI_LOCAL_SERVER_PORT`
`logRetentionDays`	30	1–365	`THREEMINAPI_LOG_RETENTION_DAYS`
`logMaxBytes`	300 MB	10 MB–1 GB	`THREEMINAPI_LOG_MAX_BYTES`

receiveMode、pollIntervalMs、concurrency の変更には再起動が必要です。未知のキーは警告だけです。

フォルダ — 3minapi paths で表示されます。

OS	トークンと設定	制御 DB とログ
macOS	`~/Library/Application Support/3minapi`	`~/Library/Application Support/3minapi`, `~/Library/Logs/3minapi`
Windows	`%APPDATA%\3minapi`	`%LOCALAPPDATA%\3minapi`
Linux	`$XDG_CONFIG_HOME/3minapi` (`~/.config`)	`$XDG_STATE_HOME/3minapi` (`~/.local/state`)

トークンはプロジェクトではなくこれらのフォルダにあるため、プロジェクトをコピーしてもトークンはコピーされません。

個人情報について

ワーカーの result と error はそのまま AI との会話に渡されます。必要なものだけを返してください
data.db は、含まれる個人情報も含めてすべての結果を、整理するまで PC に保持します

タスク