AI 代理伺服器端程式執行工具對照

假設你正在構建一個能回答客戶上傳的 CSV 檔案相關問題的代理程式。模型需要執行 Python 以取得答案。這段程式碼會在何處執行？

一種選擇是自行執行。這代表使用像是 E2B 或 Modal 的沙盒平臺，或在 Docker 上執行自己的容器，並且要進行將其與資料庫及網際網路隔離、限制執行時間、以及修補映像檔的工作。

另一個選項是使用伺服端程式碼執行工具。你將該工具加入 API 請求，模型決定何時需要執行程式，供應商則在自己的沙盒中執行指令，並在同一次請求中將輸出回傳給模型。此處的沙盒指的是一個獨立的 Linux 容器，擁有自己的檔案系統、時間限制，預設不具備網路存取。

本文將介紹目前提供伺服端程式碼執行的四家供應商、各自沙盒能做與不能做的事、延遲與成本，以及仍需自行操作沙盒的工作。

簡短說明

• 伺服端程式碼執行工具會在你的 API 請求期間於供應商的沙盒中執行模型的指令。你不需要自行配置、修補或保護容器。
• OpenAI、Anthropic 和 Google 都會為自己的模型執行程式碼。我們的 openrouter:shell 工具可在 Responses 與 Messages API 為任何模型執行指令，而我們的 openrouter:bash 工具則僅在 Messages API 執行。兩個工具皆處於測試階段。
• 我們的沙盒是一個以帳戶和工作區為範圍的獨立容器，預設不開啟外向網路存取，且每條指令都有執行時間與輸出大小限制。沙盒使用時間以每秒 $0.0001 計費，且新容器或休眠容器最低 30 秒。
• 自行操作的沙盒平臺仍是自訂基底映像、GPU 工作或需要持續執行數小時的會話的最佳選擇。

伺服端程式碼執行的意義

模型本身不會執行任何程式。當它呼叫工具時，會發出一個命名工具和引數的請求，並且必須有某物來執行它。對於客戶端工具，這個「某物」是你的應用程式碼或你所建立的代理框架。你的應用程式會接收呼叫、執行，並在後續請求中回傳結果。對於伺服端工具，供應商會在自己的基礎設施上執行呼叫，並在同一次請求中將結果回傳給模型，讓你的…

你可能已經在使用這種方式運作的工具。Web search 允許模型在即時網路上查詢資訊，web fetch 允許它讀取 URL 的內容。在兩種情況下，你只需在請求中加入一個條目…

工具呼叫如何變成一個…

以下步驟適用於任何伺服端程式碼執行工具。當…

1. 你將工具加入請求的 tools 陣列中。
2. 模型決定需要執行程式，並發出一個攜帶一個或多個 shell 指令的呼叫。
3. 供應商按順序在沙盒容器內執行這些指令。
4. 每個指令的標準輸出、標準錯誤與執行結果會回傳給模型。執行結果可能是退出碼或逾時。
5. 模型閱讀結果後，會回覆你或在同一次請求中執行更多指令。

第二到第五步重複進行，直到模型給出答案。模型執行某些指令，閱讀輸出，判斷是否需要再傳送指令，然後重複。這個迴圈就是程式碼執行工具發揮作用的地方，因為模型可以將結果與實際輸出比對，而非猜測。

我們限制這個迴圈。max_tool_calls 欄位設定單一請求可執行的伺服器工具步驟數。我的伺服器工具參考將預設值與最大值都設為 30。

託管沙盒與自行執行的沙盒有何差異

自行執行沙盒表示你擁有提供者本來會擁有的所有部份。你選擇基礎映像、配置運算資源、接入 SDK 以啟動執行並讀取輸出，並管理每一次執行的生命週期。你同時擁有安全邊界。

託管工具以一個 JSON 陣列專案換取上述控制權。你不需要規劃容器大小、打補丁或操作容器。我們為每個請求僅需少量短指令的情境打造了 openrouter:shell。

目前提供託管程式碼執行的服務商

本文涵蓋 OpenAI、Anthropic、Google 與 OpenRouter。代理 SDK 與專用沙盒平臺屬於不同類別，且在本文後續部分討論。區分這四家供應商的關鍵在於各自支援執行程式碼的模型。

OpenAI 為其模型提供託管 shell

OpenAI 的 shell 工具在 OpenAI 管理的容器中執行指令，透過 Responses API。OpenAI 將託管執行環境描述為 Debian 12，預設工作目錄為 /mnt/data。指令不會帶有 sudo，且不支援互動式 TTY 會話。檔案中列出的預裝語言包括 Python 3.11、Node.js 22.16、Java 17、PHP 8.2、Ruby 3.1 與 Go 1.23。

託管容器預設無外部網路存取。若要啟用，組織管理員需在 OpenAI 儀錶板設定允許清單，且你需在請求中為容器環境設定 network_policy。容器可透過在 container_reference 環境中傳遞其 ID 於多個請求中重複使用，並於容器建立時設定其到期時間。OpenAI 還提供獨立的 Python 程式碼解譯器工具。

Anthropic 為 Claude 模型執行 Python 與 Bash

Anthropic 的 程式碼執行工具在 Anthropic 管理的沙盒中執行 Python 與 Bash，透過 Messages API。檔案中描述的環境為 Linux x86_64 容器，配備 Python 3.11、5 GiB RAM、5 GiB 工作區儲存與一個 CPU。網際網路存取被停用且不允許外部連線，故 Claude 只能使用預安裝的函式庫，且無法在執行期間安裝套件。

存在三個 工具版本，且每個支援的模型皆接受全部三種。code_execution_20250825 支援 Bash 指令與檔案操作。code_execution_20260120 加入 Python 解譯器狀態，可在請求間持續，需依賴 Anthropic 的程式化工具呼叫，且在 Claude Haiku 4.5 上不可用。容器於建立後 30 天過期。當容器在約 5 分鐘無活動後會被快照，若在 30 天視窗內再次傳送帶有其 ID 的請求即可還原。

Google 為 Gemini 模型執行 Python

Google 的 程式碼執行工具在 Google 管理的沙盒中執行 Python，透過請求工具中的 code_execution 引數啟用。檔案指出模型只能產生與執行 Python，程式碼環境的最大執行時間為 30 秒，且無法安裝自訂套件。Google 公開列出環境所包含的函式庫清單。

我們為任何模型提供託管 shell

上述三個工具各自只支援單一公司的模型。我的工具則支援 Responses 與 Messages API 上的任何模型，因為我們在路由層執行沙盒，而非在單一模型供應商內部。

我們提供兩個程式碼執行工具。openrouter:shell 形似 OpenAI 主機化的 shell 工具，並可在 Responses API 與 Messages API 兩者上使用。openrouter:bash 形似 Anthropic 的 bash 工具，只能在 Messages API 上使用。

兩個工具皆為測試版，API 可能會變動。Sandboxed 執行僅在全球 openrouter.ai 端點執行。區域內端點不提供 shell 工具，Chat Completions 會以 400 回應並列出支援它們的 API。

在任一工具上將 engine 設為 openrouter 時，指令會在我們的沙盒中執行。預設的 engine 為 auto。對於 openrouter:shell，auto 會保留供應商原生託管的 shell（若有）並在沒有時轉至我們的沙盒。對於 openrouter:bash，auto 會將工具呼叫回傳給您的應用程式以在客戶端執行，伺服器端不會執行任何程式。

在我們的沙盒中執行指令

以下是一個完整的請求範例，執行兩條指令並回傳結果。

import os
import requests

response = requests.post(
    "https://openrouter.ai/api/v1/responses",
    headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"},
    json={
        "model": "anthropic/claude-sonnet-4.5",
        "input": "Run `cat /etc/os-release` and `python3 --version`, then tell me the OS and Python version in one sentence.",
        "tools": [
            {"type": "openrouter:shell", "parameters": {"engine": "openrouter"}}
        ],
    },
)

for item in response.json()["output"]:
    if item["type"] == "openrouter:shell":
        print(item["container_id"], item["action"]["commands"])
        for result in item["output"]:
            print(result["stdout"], result["outcome"])

我們於 2026 年 9 月 22 日執行此請求。模型在一次 shell 呼叫中傳送兩條指令，且每條指令都回傳各自的結果。完整的 os-release 輸出包含多行，這裡僅擷取前兩行。

{
  "type": "openrouter:shell",
  "container_id": "sess_art10-418b8597e044",
  "action": { "commands": ["cat /etc/os-release", "python3 --version"] },
  "output": [
    {
      "stdout": "PRETTY_NAME=\"Ubuntu 22.04.5 LTS\"\nNAME=\"Ubuntu\"\n",
      "stderr": "",
      "outcome": { "type": "exit", "exit_code": 0 }
    },
    {
      "stdout": "Python 3.11.14",
      "stderr": "",
      "outcome": { "type": "exit", "exit_code": 0 }
    }
  ]
}

沙盒在該日期報告的作業系統為 Ubuntu 22.04.5 LTS，Python 版本為 3.11.14。執行時映像可能會變動，請從容器中讀取版本，而非硬編碼。server tools reference 覆蓋其餘引數。

為您封裝沙盒的 Agent SDK

若您使用 Agent SDK 而非直接呼叫 API，部分 SDK 會封裝上述工具之一。

OpenAI Agents SDK 附帶 CodeInterpreterTool，它在 OpenAI 的沙盒中執行程式碼，還有 ShellTool，它會在您的本地執行環境或 OpenAI 主機容器中執行，取決於您如何設定其環境。請先確認您設定的模式，再假設指令已在遠端執行。對我們而言，openrouter:shell 是 tools 陣列中的一個專案，與其他專案相同，因此它會像進入原始請求一樣進入 OpenRouter Agent SDK 迴圈。

仍需您自行搭建沙盒的情境

託管工具適用於簡短、受限的工作，例如執行指令碼、轉換檔案或檢查結果。若需要特定基礎映像或 GPU，則不屬於四種託管工具之一，必須使用您自行運營的沙盒平臺。

比較

每個託管工具欄位皆來自上述供應商的官方檔案，除 OpenRouter 執行環境欄位外，其內容即為我們執行請求時沙盒回報的資訊。自管理欄位描述的是您自行執行的沙盒，而非任何單一平臺。

我們的沙盒所執行的限制

沙盒的目的在於您不必信任模型。您未曾預期的指令無法存取網路或其他人的容器，且會在執行時間與輸出量上設定硬性上限。此章節的所有內容皆描述我們的沙盒。上表顯示其他三項的差異。

適用於每條指令的限制

我們將每條指令在隔離容器中執行，與處理您請求的基礎設施以及您的機器分離，並限定於您的帳戶與工作區。您可使用 timeout_ms 設定指令可執行的最大時間，並以 max_output_length 設定可輸出的最大字元。timeout_ms 預設為 120,000 毫秒，最高不可超過 300,000 毫秒。max_output_length 預設為每個串流 16,384 字元，最高不可超過 65,536。若 shell 呼叫包含超過 100 個指令，將被拒絕。

除非您開啟，否則外向網路存取為關閉。於 2026 年 9 月 22 日，我們傳送一個沒有 network_policy 的請求，要求模型以 curl 引數抓取 https://example.com，僅印出 HTTP 狀態碼，並於 5 秒後放棄。該指令印出 000，這是 curl 在未收到回應時的輸出，並以程式碼 28 結束，為 curl 逾時。

{ "stdout": "000", "stderr": "curl: (28) Failed to connect to example.com port 443 after 5206 ms: Connection timed out", "outcome": { "type": "exit", "exit_code": 28 } }

若要開啟網路存取，請設定一個最多 50 個主機名稱或 glob 模式的 network_policy 允許清單。僅允許 80 與 443 埠可連線，且政策在容器啟動時即固定。pip install 需要將 pypi.org 與 files.pythonhosted.org 同時加入允許清單。

提示注入與沙盒限制

為模型提供 shell 會讓您暴露於 提示注入。若您的代理程式閱讀網頁、支援單或他人上傳的檔案，攻擊者可在該文字中隱藏指令，告訴模型忽略您的提示…

上述限制無論模型是遵循您的提示還是攻擊者的指令皆適用。受注入指令執行的命令無法連線到您所設定的 network_policy 之外的任何主機，且在您關閉政策時完全沒有網路存取。它也無法連到其他租戶的容器，並且會在相同的逾時時間停止。允許清單會擴大注入命令可存取的範圍，而 allowed_domains: ["*"] 允許無限制的外向連線，請將允許清單僅限於工作所需的主機。

您亦可偵測到請求本身中出現的嘗試。提示注入偵測 在 工作區防護 中，會在將請求轉發至模型前，將每個進來的請求中使用者提供的訊息內容與常見注入技術的正規表示式模式做比對。它不會檢查伺服器工具在此之後抓取的內容，因此模型透過工具讀取的頁面、檔案或命令輸出，需要您自行控制，例如審核您的應用程式所接收的沙盒輸出。一次比對會根據您設定的動作執行三種之一。

• Flag 會記錄偵測並將請求原封不動轉發。
• Redact 會將符合的區段取代為 [PROMPT_INJECTION]，並轉發已清理的請求。
• Block 會在請求到達模型之前，以 403 拒絕該請求。

若多個防護同時適用，最嚴格的動作會優先執行，順序為 block、redact、flag。偵測並非完整，可能產生誤報，請先於 flag 模式下測量比對率，再決定是否執行 redact 或 block。您可於 Logs 頁面報告誤報。

託管沙盒對您產生的時間與成本

託管沙盒會為請求增加秒數，且不提供任何可執行的基礎設施。它還會給您一個可重複使用的容器。

檔案會在請求之間持續存在

命令在 /workspace/home 內執行，我們會在每次命令後將變更的檔案儲存於該目錄。傳送一個穩定的 session_id，或在工具的 environment 設定中指定容器 ID，所有帶該 ID 的請求都會到達同一個容器及同一組檔案。session_id 必須僅使用字母、數字、_ 與 -。若 ID 含有其他字元，將被忽略，我們會像未送出任何 session_id 一樣選擇容器，這代表回放對話中最近的 container_id（若有），否則為該請求的新容器。當 session_id 超過 20 個字元時，我們只使用最後 20 個，兩個長 ID 若結尾相同則共用同一容器。container_reference ID 可為 1 到 40 個字元，且不會被截斷，若您需要精確 ID，請使用此方式。我們於 2026 年 9 月 22 日確認此行為，透過在一個請求中寫入檔案並在共享同一 session_id 的第二個請求中讀取。

容器在閒置 5 分鐘後會進入睡眠，且閒置時間不可設定。睡眠並不會刪除檔案。當稍後收到相同 ID 的請求時，會啟動新的沙盒並先載入已儲存的檔案。開啟的程式、環境變數及已安裝的系統狀態不會被還原，請將喚醒的容器視為擁有您檔案的新機器。已儲存的檔案會在容器最後使用後 30 天內保留。若要擷取 artefact，GET /api/v1/containers/{container_id}/files 會列出容器產出的內容，promote endpoint 會將檔案複製至您的工作區檔案，並不會過期。

您之後可檢視的內容

每個 shell 工具結果在回應中攜帶模型執行的命令以及每條命令的 stdout、stderr 和結果，讓您的應用程式可以以與記錄其餘回應相同的方式記錄它們。輸入 & 輸出記錄將您的提示和完成內容儲存在 OpenRouter，供在日誌頁面檢閱，並且安全防護檢測也會顯示在那裡。對於生產監控，Broadcast 在請求完成時將追蹤資料串流到外部可觀測平臺。

若您使用 in-region 路由，shell 工具將不可用，輸入 & 輸出記錄將被跳過，即使它已啟用。Broadcast 支援 in-region 路由，且每個目的地都會配置其接收追蹤資料的資料區域。

往返成本

執行 sandbox 命令的請求比不執行同樣命令的請求耗時更長。在 2026 年 9 月 22 日我們傳送的一組單一請求中，未使用 shell 工具的請求約 2 秒回應，而進行一次 shell 呼叫的請求則根據模型不同，回應時間為 8 至 21 秒。這些只是單一會話的樣本，而非基準測試。請為每一次 shell 呼叫預留數秒的額外開銷。

Sandbox 時間以每秒 $0.0001 計費。計時從請求首次執行 sandbox 命令時開始，到回應完成時停止。啟動新容器或處於睡眠狀態的容器的請求最低計費 30 秒，之後重複使用同一個熱容器的請求僅支付其計量時間。上述請求啟動了新容器，其使用物件報告的 server_tool_cost 為 0.003，即 30 秒的最低計費。請求之間閒置的容器不會計費。

在不更改工具程式碼的情況下更換模型

交換模型時，您的工具定義保持不變。

我們於 2026 年 9 月 22 日將同一請求主體傳送六次，只更改 model 欄位，並要求每個模型在 sandbox 中執行 python3 -c "print(sum(range(1, 101)))"。每個模型都進行了一次 shell 呼叫，並返回 5050。

所有六個模型在同一個沙盒中執行，使用相同的工具定義，無論它們自己的提供者原生提供什麼，因為沙盒屬於我們而非模型的提供者。在構建之前先測試你打算使用的模型，因為不同模型之間的工具呼叫可靠性不同。我們的 工具呼叫指南 覆蓋了伺服器工具與你自己的功能工具如何共用一個 tools 陣列。

當你想要自己的沙盒平臺時

如果你需要託管工具無法提供的功能，請選擇專屬沙盒平臺。Modal 檔案說明可從自訂映像建立沙盒，生命週期可配置至多 24 小時並支援 GPU 資源。Daytona 檔案說明可從公共容器映像建立沙盒，包括 GPU 沙盒。E2B 檔案說明沙盒在其 Pro 計畫下可執行長達 24 小時，在基礎計畫下可執行 1 小時，並可為較長工作負載提供暫停與恢復。

結論

對於模型請求中的短小、有限命令，請使用託管工具。你只需在 tools 陣列新增一項，即可獲得一個隔離容器，且關閉外部網路存取；你只需支付推論費用以及沙盒執行的秒數。每次 shell 呼叫預留幾秒的額外開銷，並盡可能重複使用同一容器。

當工作需要自訂基礎映像、GPU、持續數小時的會話，或是需要自行掌握安全邊界時，請切換到您自己操作的沙盒平臺。無論哪種情況，請在執行前先查閱供應商的最新檔案，因為我們的兩項工具仍處於測試階段，其他三位供應商的工具亦會變動。

常見問題

是否有可在請求期間直接被模型呼叫的託管沙盒 shell 工具？

是的。我們的 openrouter:shell 伺服器工具在請求期間為模型提供一個沙盒化的 Linux shell，並在我們的基礎設施上執行，適用於 Responses API 與 Messages API。將 engine 設為 openrouter，指令將在隔離容器中執行，並將每個指令的 stdout、stderr 以及退出或逾時結果回傳給模型。OpenAI、Anthropic 與 Google 各自為其模型提供託管的程式碼執行工具。

我可以給模型一個沙盒化的 shell 讓它執行指令嗎？

是的。將 {"type": "openrouter:shell", "parameters": {"engine": "openrouter"}} 加入 Responses 或 Messages API 請求的 tools 陣列中。模型即可發出 shell 呼叫，我們將在隔離容器中執行指令並回傳每個指令的輸出。除非您設定 network_policy 白名單，否則容器無外部網路存取權。

哪些 SDK 或平臺原生提供伺服器端程式碼執行？

我們的 openrouter:shell 伺服器工具可在 Responses 與 Messages API 為任何模型執行指令，而 openrouter:bash 伺服器工具僅在 Messages API 執行相同功能。OpenAI、Anthropic 與 Google 各自透過 Responses API shell 工具、程式碼執行工具以及 Gemini API 程式碼執行工具為其模型執行程式碼。OpenAI Agents SDK 將 OpenAI 的託管工具包裝成 CodeInterpreterTool 與 ShellTool。E2B、Modal 與 Daytona 是您自行整合並操作的沙盒平臺，而非供應商在 API 呼叫內部執行的工具。

哪一種沙盒最適合 AI 代理？

取決於工作執行時間長短以及您對執行環境所需的控制程度。若是請求內短暫指令，使用像 openrouter:shell 這類託管工具即可無需自行架設基礎設施；若需自訂基礎映像、GPU 存取或長時間執行的會話，則自行操作的沙盒平臺（例如 Modal 或 Daytona）能提供這些控制。

如何為 AI 代理進行沙盒化？

將代理的指令執行於與您自身系統隔離的環境，並限制該環境可存取的範圍。使用託管工具時，供應商會負責此工作。在 OpenRouter 上，容器與我們的基礎設施及您的機器隔離，範圍限定於您的帳號與工作區，預設關閉外部網路存取，每個指令受 timeout_ms 限制，輸出則受 max_output_length 限制。工作區防護層在模型前加入提示注入偵測。

什麼是沙盒化 AI 工具？

它是一種其副作用僅限於隔離環境，而非您的正式系統的工具。對於程式碼執行，模型的指令在擁有獨立檔案系統、受限網路存取及時間限制的容器中執行，並且只有指令輸出回傳給模型。我們的 shell 與 bash 伺服器工具即採此方式。

參考資料

• 伺服器工具參考
• Shell 伺服器工具
• Bash 伺服器工具
• 容器
• 防護層 與 提示注入偵測
• 輸入與輸出記錄
• 工具呼叫指南
• Responses API 工具呼叫
• 模型目錄