OpenRouter、任意モデルにターミナルとファイル操作機能をベータ提供

OpenRouter の openrouter:shell サーバーツールと Files API をご紹介します。これにより、OpenRouter 上のあらゆるモデルが、ホストされた Linux コンテナ内でコマンドを実行できるようになります。Files API を利用すれば、モデルが処理するためのファイルのアップロードや、生成された出力のダウンロードも可能になりました。両機能とも本日よりベータ版として提供を開始します。

Shell と Files は、サーバーサイドでエージェントのような振る舞いをモデル間で柔軟に切り替えられるようにする、私たちの「server tools」リストに新たに加わりました。例えば、任意のモデルにウェブ検索を依頼し、その結果をもとにチャート作成スクリプトを書かせ、実行までをすべてサーバー側で完結させるようなワークフローも実現可能です。

シェルツールを有効にして チャットルーム で試すか、API の詳細については Shell、コンテナ、そして Files API のガイドをお読みください。サンドボックスの利用料は 1 秒あたり 0.0001 ドルで、リクエストの一部として請求され、Files API の利用も含まれます。詳細は 料金 セクションをご覧ください。

シェルの仕組み

openrouter:shell を使用するには、ツール呼び出しをサポートする任意のモデルに対して tools アレイに指定します。これにより、モデルがターミナルを必要とするタイミングや、いつ呼び出すかを判断できるようになります：

curl https://openrouter.ai/api/v1/responses \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4-pro-0813",
    "input": "Check the Python version, then write a script that prints the first 20 primes and run it.",
    "tools": [
      { "type": "openrouter:shell", "parameters": { "engine": "openrouter" } }
    ]
  }'

サーバーサイドでのコマンド実行とファイル管理を可能にする、3 つの機能を連携して導入しました。

• Shell と Bash: OpenAI 互換の Shell ツールをサポートしています。これは Responses API および Anthropic Messages API で利用可能です。また、Messages API では Anthropic 互換の Bash ツール openrouter:bash も提供しています。いずれもあらゆるモデルと併用できます。

• Files API: `/api/v1/files` 配下にワークスペースストレージを設けています。ファイルのアップロード、ID を指定したコンテナへのアタッチ、および実行結果として生成されたファイルの保存が可能です。

コンテナ：シェルコマンドが実行されるサンドボックスです。ここに書き込まれたファイルは、同じコンテナ ID を共有するリクエスト間でも保持されます。コンテナ内のコンテンツは、`/api/v1/containers` API からアクセスできます。

モデルがツールを呼び出すと、一連のコマンドバッチが生成されます。これらはコンテナ内でそれぞれ独立した実行として処理され、標準出力（stdout）、標準エラー（stderr）、および終了コードがモデルに返されます。この仕組みにより、モデルは受け取った出力に応じて動的に対応できます。例えば、CSV を解析するスクリプトを作成したが解析に失敗した場合でも、モデルは stderr に表示されたエラーを確認し、回答を生成する前にスクリプトを修正することができます。

Logs ページ の「生成詳細」ビューでは、リクエストがタイムライン形式で表示されます。モデルの推論とサンドボックスの実行はそれぞれ独立した行として記録され、各行に実行時間とコストが表示されます：

シェルと Bash

OpenAI と Anthropic の両仕様に互換性を持たせるため、サンドボックス環境でのコマンド実行に対応する 2 つのツールをリリースしました。最も大きな違いは、bash ツールのデフォルト設定が「アプリ側でローカルにコマンドを実行させる」ことにあります。OpenRouter ではエンジンを変更することでこの動作を上書きし、サーバー上で実行することも可能です。

engine: "openrouter" を指定すれば、どのモデルでも OpenRouter のサンドボックス内でサーバーサイド実行が保証されます。

コンテナ

コンテナは、OpenRouter のインフラストラクチャ上に構築された、ワークスペースに限定された孤立した Linux 環境です。アプリの要件に合わせてコンテナを設定可能です。

• ネットワーク: デフォルトでは外部へのアクセスはオフになっています。pip3 install のようなジョブを行う場合は、network_policy を以下のような許可リストに設定してください。

network_policy:
  allow: ["pypi.org", "github.com"]

{"type": "allowlist", "allowed_domains": ["pypi.org", "files.pythonhosted.org"] } または、制限を解除する場合は { "type": "allowlist", "allowed_domains": ["*"] } を指定します。 （原文の技術表記: { "type": "allowlist", "allowed_domains": ["pypi.org", "files.pythonhosted.org"] }）

許可リストに登録されたホストはポート 80 と 443 でアクセス可能ですが、リストにないドメインへのリクエストは接続エラーではなく HTTP 520 エラーで失敗します。コンテナ起動後にこのポリシーを変更することはできません。

ファイル：キャプチャされるのはホームディレクトリ（/workspace/home）内のファイルのみです。各シェル実行結果には、コマンドによって作成または変更されたファイルの ID リストも含まれます（先頭に cfile_ が付与されます）。コンテナ内に保存されているすべてのファイルをリストアップするには container files endpoint を利用し、ファイルの送受信には Files API を使用します。

リクエスト間で再利用可能：デフォルトでは、会話ごとに新しいコンテナが作成されます。ただし、session_id を指定するか、識別可能なコンテナを持つ以前のシェル結果を含むリクエストの場合は、そのコンテナが再利用されます。明示的にコンテナを選択するには、ツールの environment フィールドに { "type": "container_reference", "container_id": "my-project" } を渡してください。

寿命：コンテナは 5 分間アイドル状態になるとスリープします。この動作は変更できません。

ファイルとシェルを併用する

Files API は、コンテナの隣に配置されるワークスペースストレージです。シェルで処理するための入力ファイルをここにアップロードし、シェルの出力結果を再びこの領域に戻すことができます。

シェル用にファイルをアップロードする

入力ファイルをアップロードするには、`POST /api/v1/files` エンドポイントを使用します。レスポンスには or_file_ で始まるファイル ID が含まれます。

curl https://openrouter.ai/api/v1/files \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -F "file=@data/sales.csv"

その後、その ID をツールの environment に添付してください。

{
  "type": "openrouter:shell",
  "parameters": {
    "engine": "openrouter",
    "environment": {
      "type": "container_auto",
      "file_ids": ["or_file_011CNha8iCJcU1wXNR6q4V8w"]
    }
  }
}

添付ファイルは、コンテナ内のホームディレクトリに書き込み可能なコピーとして表示されます。コンテナあたり最大 20 個まで添付可能です。各コピーの名前は、ファイル ID の下位 8 文字と元のファイル名を組み合わせたものになります。例えば、上記の ID で data/sales.csv を添付すると、~/NR6q4V8w-sales.csv という名前で表示されます。

コンテナ内で行った変更は、元のワークスペースファイルには影響しません。

コンテナは、そこに添付したファイルのみで始まります。

シェルが生成したファイルをダウンロードする

各シェル実行結果には、コマンドが操作したファイルの一覧と、それぞれのファイルに付与された cfile_ ID が含まれます。これらのファイルをダウンロードするには、コンテナファイルコンテンツ取得エンドポイント を利用してください。

curl "https://openrouter.ai/api/v1/containers/$CONTAINER_ID/files/$FILE_ID/content" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -o output.txt

コンテナ内のファイルは 30 日間保持されます。長期保存が必要な場合は、プロモート してワークスペースのドキュメントとして登録してください。

curl -X POST "https://openrouter.ai/api/v1/containers/$CONTAINER_ID/files/$FILE_ID/promote" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

プロモートすると、コンテナファイルがワークスペースにコピーされ、新しい or_file_ ID が発行されます。この ID は、後続の実行時にアップロード時と同様に添付可能です。アップロードとの違いは、プロモートされたファイルは Files API を通じてダウンロードできる点です。

Files API の詳細

ワークスペースのファイルページ で、所有するすべてのファイルを確認できます。直接アップロードしたファイルはダウンロードできませんが、コンテナからプロモートされたファイルはダウンロード可能です。

複数のサーバーツールの併用

Shell は提供する サーバーツール の一つに過ぎず、他のツールと組み合わせることで強力な力を発揮します。ここではモデルが Web 検索で情報を取得し、それを Shell でファイルに変換しています。

curl https://openrouter.ai/api/v1/responses \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4-pro-0813",
    "input": "Look up the three biggest open-source AI releases this week, then write ~/out/releases.md with one paragraph each and a source link.",
    "tools": [
      { "type": "openrouter:web_search" },
      { "type": "openrouter:shell", "parameters": { "engine": "openrouter" } }
    ]
  }'

生成された ~/out/releases.md は、シェル実行結果のファイルリストに表示されます。上記のコンテナファイルコンテンツ取得エンドポイントを使ってダウンロードできます。

コンテナにネットワークアクセスを与えたくない場合も、この組み合わせは重要です。Web 検索はコンテナ外で実行されるため、モデルが Web コンテンツを取得してコマンドに渡すことができます。その間、コンテナはデフォルトのネットワークポリシーのまま維持され、独自にインターネットへのアクセスを持つことはありません。

チャットルームでは、シェルと Web 検索のスイッチをオンにした状態で同じ組み合わせが機能します。実行中に作成されたファイルは、会話内でダウンロードとして表示されます。

料金体系

シェルの利用料金はサンドボックスの実行時間に基づいて課金されます。料金はアクティブな 1 秒あたり 0.0001 ドルで、リクエストが最初にサンドボックスコマンドを実行した瞬間から、最後のサンドボックスコマンドが完了するまで計測されます。リクエスト終了後にコンテナがアイドル状態になった時間は課金されません。

リクエストが新しいコンテナを開始した場合や、アイドル状態だったコンテナを再利用する場合など、「コールドスタート」が発生した際は、最低 30 秒分の料金を請求します。ただし、エージェントが同じコンテナに対して連続して複数のリクエストを行った場合、最小料金が発生するのは最初の 1 リクエストのみです。

リクエストごとの課金方式を採用しているため、特定のリクエストの実行コストを把握しやすくなっています。各リクエストの費用はトークン使用料とサンドボックス実行時間の合計で算出され、サンドボックス時間は「ログ」ページのタイムラインにおいて独立した行として表示されます。

ファイル API の利用には別途料金がかかりませんが、総ストレージ容量は 10 GiB に制限されています。

ワークスペースでのツール無効化

サーバーツールはデフォルトで有効になっています。ワークスペース管理者は、Server Toolsページから任意のツールを無効化できます。このページでは各ツールのステータスが「利用可能」または「ブロック済み」として切り替え可能です。この設定は、API キー経由、チャットルーム、プリセットを問わず、ワークスペースからのすべてのリクエストに適用されます。

使い方始めよう

Shell、Bash、Files API、コンテナはベータ版として現在利用可能です。ベータ期間中は API の仕様が変わる可能性があります。想定通りに動作しない場合は、Discord の #feedback チャンネルまでご連絡ください。

• Shell サーバーツール

• Bash サーバーツール

• Files API

• コンテナ

• すべてのサーバーツール