OpenRouter Shell ToolとFiles API（ベータ版）の使い方ガイド

ファイルを読み込み、コードを実行し、エラーを調べ、成果物まで返したい。そんな処理には、OpenRouterのシェルワークフローが便利です。ただし、openrouter:shell、コンテナ、Files APIはいずれもベータ版。いきなり本番の重要処理を任せるのではなく、まずは範囲を限定したジョブから試すのが安全です。

まず結論：OpenRouterのShell Toolが向いているケース

OpenRouterのopenrouter:shellを使うと、ツール呼び出しに対応したモデルから、ホスト型のLinux環境でコマンドを実行できます。モデルはstdout、stderr、終了コードを受け取り、結果を見ながら処理を修正できます。入力ファイルや出力ファイルの受け渡しを担うのがFiles APIです。

次のような用途なら、導入を検討する価値があります。

• アプリケーションのサーバー上ではなく、モデルにコードを実行させるモデル非依存のエージェントを作りたい。
• CSV分析、PDFからのデータ抽出、レポート生成など、ファイル処理を繰り返し実行したい。
• 自前のサンドボックスを用意せず、サーバー側でツールを実行したい。

一方で、ローカルのシェルをそのまま置き換えられるわけではありません。ネットワークはデフォルトで無効、コンテナは自動的に永続化されず、ベータ期間中はAPIが変更される可能性もあります。

実装前に押さえたい全体構成

openrouter:bashはAnthropic互換の別方式です。デフォルトではアプリケーション側でローカル実行する前提ですが、リモート実行が必要ならengine: "openrouter"を指定します。詳しくはShell Toolの発表記事を確認してください。

ファイルがシステム内をどう移動するか

1. 入力ファイルをアップロードして添付する

POST /api/v1/filesにマルチパートフォームデータを送信してファイルをアップロードします。アップロードリファレンスによると、1ファイルあたりの最大サイズは100 MBです。任意でworkspace_idクエリパラメーターも指定できます。

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

レスポンスには、ファイルID、ファイル名、MIMEタイプ、バイト数、作成日時、downloadableフラグなどのメタデータが含まれます。返されたファイルIDは、シェル環境のfile_ids配列に指定します。

添付したファイルは、書き込み可能なコピーとしてコンテナ内にコピーされます。Shell Toolの発表記事によると、1つのコンテナに添付できるファイルは最大20個です。コンテナ内のコピーを編集しても、元のワークスペースファイルは変更されません。

ある開発者は、以前のPDFやOCR処理での苦労を振り返りながら、Files APIへの対応を歓迎していました。小さな反応ではありますが、ファイル処理が実際の統合上の悩みになっていたことがうかがえます（投稿）。

2. 実行結果を確認しながら処理を進める

モデルはコンテナに対して、複数のコマンドをまとめて送信します。各呼び出しでは出力と終了ステータスが返るため、最初の指示だけを頼りに推測するのではなく、失敗したスクリプトを結果に応じて修正できます（Shell Toolの発表記事）。

ネットワークポリシーは、デフォルトではすべて拒否です。パッケージのダウンロードや外部リクエストが必要な場合は、コンテナ作成時に許可リストを設定します。OpenRouterのドキュメントでは、許可したホストに対してポート80と443が示されています。このポリシーは起動後に変更できません。許可リスト外のドメインへのリクエストは、HTTP520で失敗する場合があります（Shell Toolの発表記事）。

シェルの結果として取得されるのは、/workspace/home以下にあるファイルだけです。APIから報告させたい成果物は、必ずこのディレクトリ配下に書き出してください。シェルによって作成または変更されたファイルには、cfile_から始まるIDが付与されます（Shell Toolの発表記事）。

3. 出力をダウンロード、または永続ストレージへ移す

シェルで生成したファイルは、コンテナのファイル内容エンドポイントから取得できます。

GET /api/v1/containers/{container_id}/files/{file_id}/content

cfile_のIDは、そのコンテナに属するファイルを示します。コンテナのライフサイクルを超えて成果物を残したい場合は、ワークスペースストレージへ昇格させます。昇格すると新しいor_file_のIDが発行され、後続の実行に添付できるようになります（Shell Toolの発表記事）。

コンテナ内のファイルは30日間保持されます。それ以上残したいファイルは昇格させてください（Shell Toolの発表記事）。一般的なファイルダウンロードエンドポイントは生のバイト列を返しますが、ユーザーがアップロードしたファイルについてはHTTP400を返すと記載されています。つまり、直接アップロードしたファイルは入力として扱い、汎用的なオブジェクトストレージのファイルだとは考えないほうがよいでしょう。

設計を左右する料金と制限

OpenRouterのShell Toolの発表記事によると、アクティブなサンドボックスの利用料金は1秒あたり$0.0001です。コールドコンテナには30秒の最低利用時間があるため、計算上の最低サンドボックス料金は$0.003になります。トークン料金は別途発生します。

関連する処理では、ウォーム状態のコンテナを再利用しましょう。不要なモデルとツールの往復も避け、トークン料金とサンドボックス料金は別々に記録します。発表記事によれば、Logsビューではモデルのアクティビティとサンドボックス実行が、タイムライン上の別々の行として表示されます。

基本的なリクエスト構成

ベータ期間中は環境のスキーマが変更される可能性がありますが、ドキュメントに示されている流れは一貫しています。まずファイルをアップロードし、返されたファイルIDをShell Tool対応リクエストに渡します。ベータ版のスキーマが変わっても修正しやすいよう、リクエスト部分は小さなアダプターに切り出しておくとよいでしょう。

{
  "model": "your/tool-capable-model",
  "tools": [
    {
      "type": "openrouter:shell",
      "environment": {
        "type": "container_auto",
        "file_ids": ["or_file_your_uploaded_file_id"]
      }
    }
  ],
  "input": "Analyze the attached CSV and write a summary to /workspace/home/report.md"
}

この形式を、発表記事に記載されたResponsesエンドポイントへ送信します。本番で使う前に、現在のリクエストスキーマとレスポンスフィールドを、最新のサーバーツールのドキュメントで確認してください。

最初の連携は、次の手順で進めるとスムーズです。

1. 小さな入力ファイルを1つアップロードし、返されたファイルIDを記録する。
2. toolsにopenrouter:shellを指定した、ツール対応モデル向けのリクエストを作成する。
3. file_idsを使ってファイルを明示的に添付する。
4. 出力先を/workspace/home以下にするようモデルへ指示する。
5. 成功と判定する前に、終了コードとファイル一覧を確認する。
6. コンテナ内の成果物をダウンロードする。再利用が必要なら昇格させる。
7. トークン使用量とサンドボックス利用時間を、別々の料金項目として記録する。

複数リクエストにまたがるワークフローでは、session_idまたは明示的なコンテナ参照を渡します。そうしないと、後続のリクエストが以前の状態を持たない新しいコンテナで実行される可能性があります。

最初につまずきやすいポイントと対策

OpenRouter Shell ToolとFiles APIに関するFAQ

OpenRouter Shellは自分のパソコン上でコマンドを実行しますか？

いいえ。openrouter:shellは、OpenRouterがホストするサンドボックス内でコマンドを実行する仕組みです。Anthropic互換のopenrouter:bashはデフォルト設定が異なります。リモート実行にはengine: "openrouter"を指定してください（Shell Toolの発表記事）。

リクエストをまたいでファイルを保持するには？

セッションまたはコンテナ参照を再利用します。明示的に再利用する経路を指定しなければ、後続のリクエストは初期状態の新しいコンテナで始まる可能性があります。

or_file_とcfile_の違いは？

or_file_は、ワークスペースのFiles APIオブジェクトを識別します。cfile_は、コンテナ内で作成または変更されたファイルを識別します。コンテナ内の成果物を昇格すると、新しいワークスペースファイルIDに変換されます。

Files APIには別途利用料金がかかりますか？

Shell Toolの発表記事では、Files APIの利用自体に別途料金はかからないと説明されています。ただし、ワークスペースストレージの上限は10 GiBです。サンドボックスの利用時間とモデルのトークン使用量には、それぞれ該当する料金が発生します。

Shell Toolは本番利用できる状態ですか？

現在はベータ版として案内されており、発表記事でもAPIが変更される可能性が警告されています。管理者の介在なしに本番ワークフローへ組み込む前に、明示的な上限、実行範囲を限定したコマンド、アプリケーション側の制限、そしてフォールバック経路を用意してください。

実際に成果物が必要なワークフローなら有力な選択肢

OpenRouterのShell ToolとFiles APIは、整形済みCSV、レポート、変換後の画像、コンパイル済みアーティファクトなど、最終的なファイルを生成する段階的なパイプラインに向いています。明示的なファイルID、事前に定めたネットワークポリシー、コンテナの再利用、永続化が必要な出力の昇格を組み合わせて使いましょう。

テキストで回答するだけのタスクなら、サンドボックス料金やファイルのライフサイクル管理を追加する意味はありません。ローカルの認証情報、制限のないネットワーク、本番環境としての厳格な保証が必要な処理については、ベータ版がそのリスクに十分対応できる段階になるまで、自分で管理できるインフラで実行するのが無難です。

参照：OpenRouter Shell ToolおよびFiles APIの発表記事、Files APIアップロードリファレンス、ファイル内容ダウンロードリファレンス。