OpenRouter 推出 Shell 伺服器工具與 Files API，讓任何模型可執行終端指令與檔案操作

推出 openrouter:shell 伺服器工具與 Files API：OpenRouter 上的任何模型現在都能在託管的 Linux 容器中執行指令。Files API 允許上傳檔案讓模型使用，並下載輸出。兩項功能今日已進入測試階段。

Shell 與 Files 加入我們日益擴大的 伺服器工具清單，讓您能建立可跨模型切換的伺服器端代理行為。例如，您可以請任何模型搜尋網路，寫一段程式將結果轉成圖表，並完全以伺服器端運算執行。

在 聊天室 開啟 shell 工具試試看，並閱讀 shell、containers 與 Files API 指南以瞭解 API 詳情。沙盒時間每秒 $0.0001，作為請求的一部分計費，且包含 Files API 使用。詳情見 價格 區段。

Shell 的工作原理

要使用 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" } }
    ]
  }'

我們推出三項功能，協同提供伺服器端指令執行與檔案處理：

• Shell 與 Bash：我們支援 OpenAI 相容的 Shell 工具，於 Responses API 與 Anthropic Messages API，以及 openrouter:bash，Anthropic 相容的 Bash 工具，於 Messages API。兩者皆可與任何模型配合。
• Files API：工作區儲存於 /api/v1/files。上傳檔案，透過 id 附加到容器，並保留執行產生的檔案。
• Containers：這些是執行 shell 指令的沙盒。寫入的檔案會在共用容器 id 的請求間持久化。您可透過 /api/v1/containers API 存取容器內容。

當模型呼叫工具時，它會發出一批指令。這些指令在容器內執行，每個指令單獨呼叫，並將 stdout、stderr 與退出碼回傳給模型。這樣模型就能對收到的輸出做出回應。例如，如果它寫了一段指令碼來解析你的 CSV，且解析失敗，模型可以在 stderr 上看到問題，並在回答前修正指令碼。

在 日誌頁面 的產生細節檢視中，請求會以時間軸呈現。模型執行與沙盒執行各自顯示為獨立列，並各自有持續時間與費用：

Shell 與 Bash

我們推出兩種不同的沙盒指令執行工具，以相容 OpenAI 與 Anthropic 規範。最顯著的差異在於 bash 工具預設會請您的應用程式在本機執行指令。在 OpenRouter，您可更改引擎以覆寫此行為，並於伺服器執行。

engine: "openrouter" 在任一工具上確保在 OpenRouter 沙盒中以伺服器端執行，且適用於任何模型。

Containers

容器是 OpenRouter 基礎設施上針對您的工作區所範圍的隔離 Linux 環境。容器可依應用需求進行設定：

• Network：預設關閉對外連線。對於 pip3 install 之類的工作，將 network_policy 設為允許清單，例如 { "type": "allowlist", "allowed_domains": ["pypi.org", "files.pythonhosted.org"] }，或 { "type": "allowlist", "allowed_domains": ["*"] } 以允許不受限制的出口。允許清單中的主機可在 80 與 443 埠存取；對於不在允許清單外的網域請求會以 HTTP 520 失敗，而非連線錯誤。容器啟動後無法更改此政策。
• 檔案：僅捕獲位於主目錄 (/workspace/home) 下的檔案。每個 Shell 結果也會返回一個由命令建立或更改的檔案 id 列表（以 cfile_ 為字首）。容器檔案端點 列出容器中儲存的所有內容，檔案 API 用於進出移動檔案。
• 跨請求重用：預設情況下，對話會獲得一個新的容器。如果請求包含 session_id 或具有可辨識容器的先前 Shell 結果，該容器將被重用。要明確選擇容器，請在工具的 environment 欄位傳遞 { "type": "container_reference", "container_id": "my-project" }。
• 存活時間：容器在空閒 5 分鐘後進入睡眠。此行為不可配置。

檔案與 Shell 一起使用

檔案 API 是位於容器旁的工作區儲存。你可以將輸入上傳到那裡讓 Shell 處理，然後將 Shell 的輸出移回去。

為 Shell 上傳檔案

使用 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"

接著在工具的 environment 欄位按 id 附加：

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

附加的檔案會以可寫複本的形式出現在主目錄中，每個容器最多 20 個。每個複本的名稱由檔案 id 的最後 8 個字元加上原始檔名組成，因此 data/sales.csv 附加時使用上述 id 會變成 ~/NR6q4V8w-sales.csv。容器內的變更不會影響工作區原始檔案。容器僅包含你附加的檔案。

下載 Shell 產生的檔案

每個 Shell 結果列出命令所觸及的檔案，並為每個檔案提供一個 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，你可以像上傳一樣將其附加到後續執行。與上傳不同，提升的檔案可透過檔案 API 下載。

檔案 API 詳情

你可以在 工作區檔案頁面 檢視所有檔案。直接上傳的檔案無法下載，但從容器提升的檔案可以。

同時使用多個伺服器工具

Shell 是我們提供的多種 伺服器工具 之一，並且在協同工作時非常強大。此處模型使用網路搜尋尋找素材，然後用 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 會出現在 Shell 結果的檔案列表中，你可以使用上方的容器檔案內容端點下載它。

如果你不想給容器網路存取權，此組合也很重要。網路搜尋在容器外執行，模型可以拉取網路內容並將其傳遞給命令，而容器則保持預設網路政策，無自己的網路存取。

在 聊天室 中，開啟 Shell 和網路搜尋開關後，同樣的組合可用。執行所產生的檔案會以下載形式出現在對話中。

定價

Shell 與 Bash 的使用會依沙箱時間計費。價格為 $0.0001 每秒活躍時間，從請求首次執行沙箱指令到最後一次指令的時段計算。請求結束後容器空閒時間不計費。

當請求啟動冷容器（無論是新容器還是已空閒的容器）時，我們會收取最少 30 秒費用。若代理連續對同一容器傳送多個請求，僅第一次會收取此最低費用。

按請求計費可輕鬆查詢執行特定請求的成本。請求的成本為其 token 成本加上 sandbox 時間，sandbox 時間會顯示為請求時間線上的獨立一行，位於 Logs 頁面。

Files API 的使用不另行收費，但總儲存容量限制為 10 GiB。

停用工作區的工具

伺服器工具預設為啟用。工作區管理員可在工作區的 Server Tools 頁面關閉任何工具，每個工具都有一個開關顯示 Available 或 Blocked。此設定適用於工作區所發出的每一次請求，無論是透過 API 金鑰、聊天室或預設值。

開始使用

Shell、Bash、Files API 與 containers 目前處於測試版並已開放使用。API 可能在測試期間變更。如有任何功能未按預期運作，請在 Discord 上的 #feedback 讓我們知道。

• Shell server tool
• Bash server tool
• Files API
• Containers
• All server tools