OpenRouter Shell 工具與 Files API 指南（Beta）

當模型需要讀取檔案、執行程式、檢查錯誤，再交付產出檔案時，OpenRouter 的 shell 工作流程相當實用。不過要先注意，openrouter:shell、容器與 Files API 目前都還處於 beta 階段，因此建議先從範圍明確、風險受控的任務開始，不要一開始就把它放進攸關生產環境的核心執行流程。

先講結論：什麼情況值得用 OpenRouter shell

OpenRouter 的 openrouter:shell 能讓支援工具呼叫的模型，在代管的 Linux 環境中執行指令。模型可以取得 stdout、stderr 與結束代碼，再根據結果修正工作內容；Files API 則負責處理輸入與輸出的檔案交接。

以下情境很適合使用：

• 希望模型不綁定特定供應商，並在應用程式伺服器之外執行程式的代理程式。
• 需要可重複執行的檔案處理工作，例如 CSV 分析、PDF 擷取或報告產生。
• 想在不先自行打造 sandbox 的情況下，使用伺服器端工具執行功能。

但不要把它當成在本機直接開 shell 的替代品。網路預設會被停用，容器也不會自動持久保存，而且 beta 期間 API 仍可能調整。

實際設計時不能忽略的架構

openrouter:bash 是相容 Anthropic 的另一種選擇。它預設會要求應用程式在本機執行指令；如果需要遠端執行，請設定 engine: "openrouter"，詳情可參考 shell 公告。

檔案在系統中的完整流轉方式

1. 上傳檔案並附加輸入

使用 multipart form data，透過 POST /api/v1/files 上傳檔案。上傳參考文件指出，單一檔案大小上限為 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 放進 shell 環境的 file_ids 陣列中。

附加的檔案會以可寫入的副本形式複製到容器內。根據 shell 公告，單一容器最多可接收 20 個附加檔案。修改容器內的副本，不會影響原本 workspace 中的檔案。

有開發者在分享早期處理 PDF／OCR 時遇到的摩擦後，特別表示希望支援 Files API。這雖然只是個別回饋，卻具體反映出檔案處理確實曾是整合上的痛點（貼文）。

2. 執行、檢查，再反覆修正

模型會把一批指令送進容器執行。每次呼叫都會回傳輸出內容與結束狀態，模型因此能根據實際結果修補失敗的腳本，而不是只靠原始提示詞猜測問題所在（shell 公告）。

預設網路政策是全部拒絕。如果工作需要下載套件或發出外部請求，請在建立容器時設定允許清單。OpenRouter 文件指出，允許清單中的主機可使用連接埠 80 和 443；容器啟動後就不能再變更這項政策。對不在允許清單內網域的請求，可能會收到 HTTP 520（shell 公告）。

shell 結果只會擷取 /workspace/home 底下的檔案。如果希望 API 回報某個產出檔案，就必須把它寫在這個目錄中。由 shell 建立或修改的檔案，會取得 cfile_ 識別碼（shell 公告）。

3. 下載輸出，或將它升級保存

由 shell 產生的檔案，可以透過容器檔案內容端點取得：

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

cfile_ 識別碼屬於該容器。如果產出檔案需要在容器生命週期結束後繼續保留，就應該把它升級保存到 workspace 儲存空間。升級後會建立新的 or_file_ 識別碼，之後的工作可以再次附加這個檔案（shell 公告）。

容器檔案會保留 30 天。任何需要保存更久的檔案，都應該升級保存（shell 公告）。一般檔案下載端點會回傳原始位元組；文件也說明，對使用者上傳的檔案會回傳 HTTP 400。因此，直接上傳的檔案應視為輸入，而不是可任意下載的通用物件儲存檔案。

會左右架構的費用與限制

OpenRouter 的 shell 公告指出，sandbox 啟用期間的費用為每秒 $0.0001。冷啟動容器的最低計費時間是30 秒，因此最低 sandbox 費用依計算為$0.003。Token 費用另計。

相關步驟可以重用暖機中的容器，避免不必要的模型與工具來回呼叫，並將 token 費用與 sandbox 費用分開記錄。公告指出，Logs 檢視畫面會把模型活動與 sandbox 執行內容分成時間軸上的不同列顯示。

核心請求結構

beta 期間環境設定的 schema 可能調整，但文件記載的流程大致如下：先上傳檔案，再把回傳的檔案 ID 傳給啟用 shell 的請求。建議把請求介面封裝得簡單一些，這樣 beta schema 變更時比較容易更新。

{
  "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 endpoint。正式上線前，請以線上 server-tools 文件為準，重新確認目前的請求 schema 與回應欄位。

第一次整合時，可以依照以下順序進行：

1. 先上傳一個小型輸入檔案，記下回傳的檔案 ID。
2. 為支援工具的模型建立請求，並在 tools 中加入 openrouter:shell。
3. 透過 file_ids 明確附加檔案。
4. 要求模型把輸出寫入 /workspace/home 底下。
5. 檢查結束代碼與檔案清單，再判定工作是否成功。
6. 下載容器產出檔案；若之後還要重複使用，就將它升級保存。
7. 把 token 使用量與 sandbox 執行時間分別記錄為不同的費用欄位。

如果是由多個請求組成的工作流程，請傳入 session_id 或明確的容器參照。否則，後續請求可能取得一個全新的容器，先前的狀態也就不會保留。

最容易出問題的地方，以及對應的設計方式

OpenRouter shell 與 Files API 常見問題

OpenRouter shell 會在我的電腦上執行指令嗎？

不會。openrouter:shell 的設計是在 OpenRouter 代管的 sandbox 中執行指令。相容 Anthropic 的 openrouter:bash 預設行為不同；若要遠端執行，請使用 engine: "openrouter"（shell 公告）。

如何在不同請求之間保留檔案？

重用 session 或容器參照。如果沒有明確指定重用路徑，後續請求可能會從全新的容器開始。

or_file_ 和 cfile_ 有什麼不同？

or_file_ 代表 workspace Files API 物件；cfile_ 則代表在容器內建立或修改的檔案。將容器產出檔案升級保存後，會轉換成新的 workspace 檔案 ID。

Files API 會另外收取使用費嗎？

shell 公告表示，Files API 使用本身不會另外收取使用費，但 workspace 儲存空間上限為 10 GiB。Sandbox 執行時間與模型 token 使用量，仍會按照各自適用的費率計費。

Shell 工具已經適合用於生產環境嗎？

目前文件仍將它標示為 beta，公告也提醒 API 可能變更。在把它放進無人值守的生產工作流程前，請先加入明確的限制、範圍受控的指令、應用程式層級的管控，以及可用的備援路徑。

工作流程真的會產生檔案，再考慮採用

OpenRouter 的 shell 與 Files API 適合用在分階段處理、且最終會產生實體產出的流程，例如清理後的 CSV、報告、轉換後的圖片或編譯產物。請明確管理檔案 ID，預先設定網路政策，重用容器，並透過升級保存來保留需要長期使用的輸出。

如果任務只需要產生文字答案，額外的 sandbox 費用與生命週期管理就沒有必要。如果工作需要本機憑證、完全不受限制的網路，或嚴格的生產環境保證，在 beta 成熟到足以承受這些風險之前，仍應把執行工作留在自己能控制的基礎架構中。

來源：OpenRouter shell 與 Files API 公告、Files API 上傳參考文件、檔案內容下載參考文件。