程式碼執行工具

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

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

程式碼執行是建構高效能代理的核心基礎元件。它能在網頁搜尋和網頁擷取工具中實現動態過濾，讓 Claude 在結果進入「context window」（上下文視窗）之前先行處理，從而提高準確性並減少 token 消耗。



模型相容性

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



平台可用性

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

• Claude API（Anthropic）
• Claude Platform on AWS
• Microsoft Foundry

程式碼執行目前不適用於 Amazon Bedrock 或 Vertex AI。



快速入門

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "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)



程式碼執行的運作方式

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

1. Claude 會評估程式碼執行是否有助於回答您的問題
2. 該工具會自動為 Claude 提供以下功能：
   • Bash 命令：執行 shell 命令以進行系統操作和套件管理
   • 檔案操作：直接建立、檢視和編輯檔案，包括編寫程式碼
3. Claude 可以在單一請求中使用這些功能的任意組合
4. 所有操作都在安全的沙箱環境中執行
5. Claude 會提供結果以及任何產生的圖表、計算或分析



Claude 何時執行程式碼

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

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

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

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

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



將程式碼執行與其他執行工具搭配使用

當您同時提供程式碼執行工具與其他也會執行程式碼的用戶端提供工具（例如 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 需要區分這兩者。



如何使用此工具



上傳並分析您自己的檔案

若要分析您自己的資料檔案（例如 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=open("data.csv", "rb"),
)

# 將 file_id 用於程式碼執行
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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)



擷取產生的檔案

當 Claude 在程式碼執行期間建立檔案時，您可以使用 Files API 擷取這些檔案：

# 初始化用戶端
client = Anthropic()

# 請求執行會建立檔案的程式碼
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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):
    file_ids = []
    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":
                # 具體型別的清單：List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.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"
}

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

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



回應格式

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



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
  }
}



檔案操作回應

檢視檔案：

{
  "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_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "numLines": 4,
    "startLine": 1,
    "totalLines": 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_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_result",
    "oldStart": 3,
    "oldLines": 1,
    "newStart": 3,
    "newLines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}



結果

所有執行結果都包含：

• stdout：成功執行的輸出
• stderr：執行失敗時的錯誤訊息
• return_code：0 表示成功，非零表示失敗

檔案操作的額外欄位：

• 檢視：file_type、content、numLines、startLine、totalLines
• 建立：is_file_update（檔案是否已存在）
• 編輯：oldStart、oldLines、newStart、newLines、lines（diff 格式）



錯誤

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

常見錯誤（所有工具）：

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

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



pause_turn 停止原因

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



容器

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



執行環境

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



資源限制

• 記憶體：5GiB RAM
• 磁碟空間：5GiB 工作區儲存空間
• CPU：1 個 CPU



網路與安全性

• 網際網路存取：基於安全考量完全停用
• 外部連線：不允許對外的網路請求
• 沙箱隔離：與主機系統和其他容器完全隔離
• 檔案存取：僅限於工作區目錄
• 工作區範圍：與 Files 類似，容器的範圍限定於 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



容器重複使用

您可以透過提供先前回應中的容器 ID，在多個 API 請求之間重複使用現有的容器。這讓您能夠在請求之間保留已建立的檔案。



範例

# 第一個請求：建立一個包含隨機數字的檔案
response1 = client.messages.create(
    model="claude-opus-4-8",
    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
container_id = response1.container.id

# 第二個請求：重複使用該容器來讀取檔案
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-8",
    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)



串流

啟用「streaming」（串流）後，您將在程式碼執行事件發生時即時接收：

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

// Code execution streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"code\":\"import pandas as pd\\ndf = pd.read_csv('data.csv')\\nprint(df.head())\"}"}}

// Pause while code executes

// Execution results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": ""}}}



批次請求

您可以在 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-2025-08-25，您可以取得檔案操作和 Bash 功能，包括多種語言的程式碼。價格沒有差異。



變更內容



向後相容性

• 所有現有的 Python 程式碼執行繼續完全如常運作
• 現有的僅限 Python 工作流程無需任何變更



升級步驟

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

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

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

• 先前用於 Python 執行回應的區塊將不再傳送
• 取而代之的是，將傳送用於 Bash 和檔案操作的新回應類型（請參閱「回應格式」一節）



程式化工具呼叫

若要在程式碼執行容器內執行工具，請參閱程式化工具呼叫。



資料保留

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

如需了解所有功能的 ZDR 資格，請參閱 API 與資料保留。



將程式碼執行與 Agent Skills 搭配使用

程式碼執行工具使 Claude 能夠使用 Agent Skills。Skills 是由指令、腳本和資源組成的模組化功能，可擴展 Claude 的功能。

請參閱 Agent Skills 和透過 API 使用 Agent Skills 以了解更多資訊。