程式碼執行工具

Claude 可以直接在 API 對話中分析資料、建立視覺化圖表、執行複雜計算、執行系統命令、建立和編輯檔案，以及處理上傳的檔案。程式碼執行工具讓 Claude 能夠在安全的沙箱環境中執行 Bash 命令並操作檔案，包括撰寫程式碼。

當與網頁搜尋或網頁擷取（web_search_20260209、web_fetch_20260209 或更新版本）一起使用時，程式碼執行是免費的。 當您的請求中包含其中一個工具時，該請求中的程式碼執行除了標準 token 費用外不會產生額外費用。這涵蓋了動態過濾背後的程式碼執行以及 Claude 直接執行的任何程式碼。當未包含這些工具時，則適用標準的程式碼執行定價。

程式碼執行也為網頁搜尋和網頁擷取工具中的動態過濾提供支援：Claude 會在程式碼執行環境中過濾結果，然後才將其送入上下文視窗。當動態過濾執行時，API 會自動為該請求配置所需的程式碼執行，因此您不需要為此在請求中加入程式碼執行工具。



模型相容性

程式碼執行工具可在以下模型上使用：

每個工具版本都建立在前一個版本的基礎上：

• code_execution_20250825 支援 Bash 命令和檔案操作，並且可在表格中的每個模型上使用。
• code_execution_20260120 新增了 REPL 狀態持久化以及從沙箱內進行程式化工具呼叫的功能。Claude Haiku 4.5 接受 code_execution_20260120 和 code_execution_20260521 工具類型，但程式化工具呼叫以及依賴它的 REPL 狀態持久化在該模型上不可用，因此較新的版本在該模型上的行為與 code_execution_20250825 相同。
• code_execution_20260521 與 code_execution_20260120 是相同的執行環境。差異在於工具描述會告知 Claude 程式化工具呼叫中每個 Python 儲存格有 90 秒的實際時間（wall-clock）限制，因此 Claude 可以為長時間執行的儲存格做好規劃。超過限制的儲存格會回傳正常的程式碼執行結果，其中包含非零的 return_code 以及輸出中的 detection_timeout 狀態訊息。這與 execution_time_exceeded 錯誤代碼不同，後者是當整個工具呼叫超過最大執行時間時由 API 回傳的。

這三個工具版本均已正式推出，不需要 anthropic-beta 標頭。舊版的程式碼執行 beta 標頭仍然是有效的選用項目。

本頁的範例使用 code_execution_20250825，因為表格中的每個模型都支援它。目前的網頁搜尋和網頁擷取工具（web_search_20260209、web_fetch_20260209 及更新版本）需要 code_execution_20260120 或更新版本作為其程式碼執行版本。



平台可用性

程式碼執行可在以下平台使用：

• Claude API（Anthropic）
• Claude Platform on AWS
• Microsoft Foundry（需要 Hosted on Anthropic 部署）

程式碼執行目前無法在 Amazon Bedrock 或 Google Cloud 上使用。



快速開始

以下是一個要求 Claude 執行計算的範例：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Use the code execution tool to calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response.to_json())

回應會將 server_tool_use 區塊（Claude 執行的命令）與其工具結果區塊交錯排列，後面接著 Claude 的文字。頂層還包含一個 container 物件，您可以在多個請求之間重複使用其 id。請參閱回應格式以了解區塊的結構。



程式碼執行的運作方式

當您將程式碼執行工具加入 API 請求時：

1. Claude 會評估程式碼執行是否有助於回答您的問題
2. 該工具會自動為 Claude 提供以下功能：
   • Bash 命令： 執行 shell 命令以進行系統操作
   • 檔案操作： 直接建立、檢視和編輯檔案，包括撰寫程式碼
3. Claude 可以在單一請求中使用這些功能的任意組合
4. 所有操作都在安全的沙箱容器中執行。該容器沒有網際網路存取權限，因此 Claude 無法在執行時下載套件：只有預先安裝的函式庫可用
5. API 會在伺服器端執行每個命令，並在同一個請求中將結果回傳給 Claude，因此您永遠不需要自己執行程式碼或回傳 tool_result 區塊。一個例外是當 Claude 在程式碼執行的同時呼叫您的其中一個用戶端工具時：API 會回傳程式碼執行呼叫但不含其結果。結果會在您回傳用戶端工具的 tool_result 區塊之後，在後續的回應中送達
6. 除非您將先前回應的容器 ID 傳回，否則每個請求都會在新容器中執行（請參閱容器重複使用）
7. Claude 會提供結果以及任何產生的圖表、計算或分析

容器已預先安裝 Python。Claude 使用檔案操作子工具撰寫 Python，並使用 Bash 命令執行它。使用 code_execution_20260120 或更新版本以及程式化工具呼叫時，Python 直譯器狀態（例如變數繫結）也會在重複使用容器的請求之間持續存在。



Claude 何時執行程式碼

當請求能從計算或檔案處理中受益時，Claude 會執行程式碼：

• 非簡單的數學運算（大數字、多步驟、對精確度敏感的結果）
• 資料分析、檔案解析或視覺化
• 演算法執行或模擬
• 明確要求「執行」、「計算」或「運行」

對於以下情況，Claude 會直接回答而不執行程式碼：

• 簡單的算術和眾所周知的數學事實
• 事實性、對話性或創意性的請求
• 簡單的單位換算或翻譯

如果您希望 Claude 為邊界情況的請求執行程式碼，請明確要求（例如「執行程式碼來驗證這一點」）。



處理檔案



上傳並分析您自己的檔案

若要分析您自己的資料檔案（例如 CSV、Excel 或圖片），請透過 Files API 上傳它們並在您的請求中引用：

Python 環境可以處理透過 Files API 上傳的各種檔案類型，包括：

• CSV
• Excel（.xlsx、.xls）
• JSON
• XML
• 圖片（JPEG、PNG、GIF、WebP）
• 文字檔案（.txt、.md、.py 等）



上傳並分析檔案

1. 使用 Files API 上傳您的檔案
2. 在您的訊息中使用 container_upload 內容區塊引用該檔案
3. 在您的 API 請求中包含程式碼執行工具

client = anthropic.Anthropic()

# 上傳檔案
file_object = client.beta.files.upload(file=Path("data.csv"))

# 將 file_id 與程式碼執行搭配使用
response = client.beta.messages.create(
    model="claude-opus-5",
    betas=["files-api-2025-04-14"],
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": file_object.id},
            ],
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response.to_json())



擷取產生的檔案

當 Claude 在程式碼執行期間建立檔案時，每個建立的檔案 ID 都會出現在程式碼執行工具結果中，您可以使用 Files API 下載它：

client = Anthropic()

# 請求執行會建立檔案的程式碼
response = client.beta.messages.create(
    model="claude-opus-5",
    betas=["files-api-2025-04-14"],
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a matplotlib visualization and save it as output.png",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)


# 從回應中擷取檔案 ID
def extract_file_ids(response: BetaMessage) -> list[str]:
    file_ids: list[str] = []
    for item in response.content:
        if item.type == "bash_code_execution_tool_result":
            content_item = item.content
            if content_item.type == "bash_code_execution_result":
                for output_block in content_item.content:
                    file_ids.append(output_block.file_id)
    return file_ids


# 下載建立的檔案
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id)
    file_content = client.beta.files.download(file_id)
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")



工具定義

程式碼執行工具不需要額外的參數：

{
  "type": "code_execution_20250825",
  "name": "code_execution"
}

這兩個欄位都是固定的：type 選擇工具版本，而 name 必須是 code_execution。

當您提供此工具時，Claude 會自動獲得兩個子工具的存取權限：

• bash_code_execution：執行 shell 命令
• text_editor_code_execution：檢視、建立和編輯檔案，包括撰寫程式碼

當 Claude 執行程式碼時，回應還會包含一個頂層的 container 物件，其中包含容器的 id 和 expires_at 時間戳記。將該 ID 傳回頂層的 container 請求參數中，即可繼續使用同一個容器。請參閱容器重複使用。



回應格式

程式碼執行工具可以根據操作回傳兩種類型的結果：



Bash 命令回應

{
  "type": "server_tool_use",
  "id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "name": "bash_code_execution",
  "input": {
    "command": "ls -la | head -5"
  }
},
{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "content": {
    "type": "bash_code_execution_result",
    "stdout": "total 24\ndrwxr-xr-x 2 user user 4096 Jan 1 12:00 .\ndrwxr-xr-x 3 user user 4096 Jan 1 11:00 ..\n-rw-r--r-- 1 user user  220 Jan 1 12:00 data.csv\n-rw-r--r-- 1 user user  180 Jan 1 12:00 config.json",
    "stderr": "",
    "return_code": 0,
    "content": []
  }
}



檔案操作回應

檢視檔案：

{
  "type": "server_tool_use",
  "id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "text_editor_code_execution",
  "input": {
    "command": "view",
    "path": "config.json"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": {
    "type": "text_editor_code_execution_view_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "num_lines": 4,
    "start_line": 1,
    "total_lines": 4
  }
}

建立檔案：

{
  "type": "server_tool_use",
  "id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "text_editor_code_execution",
  "input": {
    "command": "create",
    "path": "new_file.txt",
    "file_text": "Hello, World!"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": {
    "type": "text_editor_code_execution_create_result",
    "is_file_update": false
  }
}

編輯檔案（str_replace）：

{
  "type": "server_tool_use",
  "id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
  "name": "text_editor_code_execution",
  "input": {
    "command": "str_replace",
    "path": "config.json",
    "old_str": "\"debug\": true",
    "new_str": "\"debug\": false"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
  "content": {
    "type": "text_editor_code_execution_str_replace_result",
    "old_start": 3,
    "old_lines": 1,
    "new_start": 3,
    "new_lines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}



結果

Bash 命令結果（bash_code_execution_result）包含：

• stdout：成功執行的輸出
• stderr：執行失敗時的錯誤訊息
• return_code：0 表示成功，非零表示失敗
• content：一個清單，其中每個項目對應命令建立的一個檔案。每個項目都帶有 file_id，可用於透過 Files API 擷取檔案

檔案操作結果有其自己的欄位：

• 檢視（text_editor_code_execution_view_result）：file_type、content、num_lines、start_line、total_lines
• 建立（text_editor_code_execution_create_result）：is_file_update（檔案是否已存在）
• 編輯（text_editor_code_execution_str_replace_result）：old_start、old_lines、new_start、new_lines、lines（diff 格式）



錯誤

每種工具類型都可能回傳特定的錯誤：

常見錯誤（所有工具）：

{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

依工具類型分類的錯誤代碼：

已過期的容器無法重複使用：引用它的請求會回傳錯誤，而不是還原它。請在不帶 container 參數的情況下再次發送請求以取得新容器。



pause_turn 停止原因

回應可能包含 pause_turn 停止原因，這表示 API 暫停了一個長時間執行的回合。您可以在後續請求中原樣提供該回應，讓 Claude 繼續其回合，或者如果您想中斷對話，也可以修改內容。



容器

程式碼執行工具在專為程式碼執行設計的安全容器化環境中執行，並更著重於 Python。



執行環境

• Python 版本： 3.11
• 作業系統： 基於 Linux 的容器
• 架構： x86_64（AMD64）



資源限制

• 記憶體： 5 GiB RAM
• 磁碟空間： 5 GiB 工作區儲存空間
• CPU： 1 個 CPU
• 執行時間： 超過最大執行時間的工具呼叫會回傳 execution_time_exceeded 錯誤。使用程式化工具呼叫時，每個 REPL 儲存格也有 90 秒的實際時間限制



網路與安全性

• 網際網路存取： 基於安全考量完全停用
• 外部連線： 不允許任何對外網路請求
• 沙箱隔離： 與主機系統和其他容器完全隔離
• 檔案存取： 僅限於工作區目錄
• 工作區範圍： 與 Files API 一樣，容器的範圍限定於 API 金鑰的工作區
• 過期時間： 容器在建立後 30 天過期



預先安裝的函式庫

沙箱 Python 環境包含以下常用函式庫：

• 資料科學： pandas、numpy、scipy、scikit-learn、statsmodels
• 視覺化： matplotlib、seaborn
• 檔案處理： pyarrow、openpyxl、xlsxwriter、xlrd、pillow、python-pptx、python-docx、pypdf、pdfplumber、pypdfium2、pdf2image、pdfkit、tabula-py、reportlab[pycairo]、Img2pdf
• 數學與運算： sympy、mpmath
• 公用程式： tqdm、python-dateutil、pytz、joblib

容器還包含命令列工具，例如 unzip、unrar、7zip、bc、rg（ripgrep）、fd 和 sqlite。

容器沒有網際網路存取權限，因此 Claude 無法在執行時下載或安裝額外的套件：只有預先安裝的函式庫可用。



容器重複使用

您可以透過提供先前回應中的容器 ID，在多個 API 請求之間重複使用現有的容器。這讓您可以在請求之間保留已建立的檔案。使用 code_execution_20260120 或更新版本以及程式化工具呼叫時，Python 直譯器狀態也會持續存在。

容器在建立後 30 天過期。在大約 5 分鐘的閒置後，容器會被建立檢查點（checkpoint），在 30 天期限內發送帶有其 ID 的請求會將其還原。回應的 container 物件中的 expires_at 時間戳記是一個較短的滾動值，並不代表 30 天的限制。已過期的容器無法重複使用。請在不帶 container 參數的情況下再次發送請求以取得新容器。



範例

client = anthropic.Anthropic()

# 第一個請求：在新容器中建立一個包含隨機數字的檔案
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Write a file with a random number and save it to '/tmp/number.txt'",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 第二個請求：傳回容器 ID，讓 Claude 重複使用同一個容器
response2 = client.messages.create(
    container=response1.container.id,
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Read the number from '/tmp/number.txt' and calculate its square",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response2.to_json())



將程式碼執行與其他執行工具一起使用

當您將程式碼執行與同樣會執行程式碼的用戶端提供工具（例如 Bash 工具或自訂 REPL）一起提供時，Claude 是在多電腦環境中運作。程式碼執行工具在 Anthropic 的沙箱容器中執行，而您的用戶端提供工具則在您控制的獨立環境中執行。Claude 有時會混淆這些環境，嘗試使用錯誤的工具或假設它們之間共享狀態。

為了避免這種情況，請在您的系統提示中加入說明以釐清兩者的區別：

When multiple code execution environments are available, be aware that:
- Variables, files, and state do NOT persist between different execution environments
- Use the code_execution tool for general-purpose computation in Anthropic's sandboxed environment
- Use client-provided execution tools (e.g., bash) when you need access to the user's local system, files, or data
- If you need to pass results between environments, explicitly include outputs in subsequent tool calls rather than assuming shared state

當將程式碼執行與網頁搜尋或網頁擷取結合使用時，這一點尤其重要，因為它們會自動啟用程式碼執行。如果您的應用程式已經提供了用戶端 shell 工具，自動的程式碼執行會建立第二個執行環境，Claude 需要區分這兩者。

當 Claude 在程式碼執行的同時呼叫您的其中一個用戶端工具時，API 會回傳程式碼執行呼叫但不含其結果。結果會在您回傳用戶端工具的 tool_result 區塊之後，在後續的回應中送達。



串流

啟用串流（"stream": true）後，您將在程式碼執行事件發生時收到它們。子工具輸入會以 input_json_delta 事件串流，而每個結果區塊會在單一 content_block_start 事件中完整送達：

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "bash_code_execution"}}

// Tool input streamed as partial JSON
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"command\": \"python analyze.py\"}"}}

// Pause while the command runs

// Execution result delivered as a complete block
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "bash_code_execution_result", "stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": "", "return_code": 0, "content": []}}}



批次請求

您可以在 Messages Batches API 中包含程式碼執行工具。透過 Messages Batches API 進行的程式碼執行工具呼叫，其定價與一般 Messages API 請求中的相同。



使用量與定價

程式碼執行在與網路搜尋或網路擷取一起使用時是免費的。 當您的 API 請求中包含 web_search_20260209（或更新版本）或 web_fetch_20260209（或更新版本）時，除了標準的輸入和輸出 token 費用外，程式碼執行工具呼叫不會產生額外費用。

在不使用這些工具的情況下，程式碼執行會依執行時間計費，與 token 使用量分開追蹤：

• 執行時間最低為 5 分鐘
• 每個組織每月可獲得 1,550 小時的免費使用時數
• 超過 1,550 小時的額外使用量以每個容器每小時 $0.05 美元計費
• 如果請求中包含檔案，即使未呼叫該工具，也會計算執行時間費用，因為檔案會預先載入到容器中

程式碼執行使用量會在回應中追蹤：

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 239,
    "server_tool_use": {
      "code_execution_requests": 1
    }
  }
}



升級至最新工具版本

最新的工具版本是 code_execution_20260521。若要在三個目前的版本之間切換，請更新請求中的 type 字串：這三個版本都會回傳回應格式中記載的回應區塊。請參閱模型相容性以了解每個版本新增的功能以及哪些模型支援它。

本節的其餘部分涵蓋從舊版僅限 Python 的 code_execution_20250522 遷移到目前工具版本的方法。



變更內容



向後相容性

• 所有現有的 Python 程式碼執行都會繼續完全按照以前的方式運作
• 現有的僅限 Python 工作流程不需要任何變更



升級步驟

若要升級，請更新 API 請求中的工具類型：

- "type": "code_execution_20250522"
+ "type": "code_execution_20250825"

檢閱回應處理（如果以程式化方式解析回應）：

• API 不再為 Python 執行回應發送先前的區塊
• 取而代之的是，API 會為 Bash 和檔案操作發送新的回應類型（請參閱回應格式）



資料保留

程式碼執行在伺服器端沙箱容器中執行。容器資料（包括執行產物、上傳的檔案和輸出）最多保留 30 天。此保留政策適用於容器環境中處理的所有資料。程式碼執行在 Files API 中建立的檔案（可透過 client.beta.files.download() 擷取）會持續存在，直到被明確刪除。

有關所有功能的 ZDR 資格，請參閱 API 與資料保留。



後續步驟