Claude API 代碼執行工具（code execution）怎麼用：tools 寫法、上載文件分析、取回生成文件、容器限制和計費

本文根據 Claude 開發者平台官方文檔《Code execution tool》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。本站（bigolab.com）不是 Anthropic 官方網站。

適用於誰

• 想讓 Claude 在 API 調用裏真正執行代碼，做數據分析、畫圖、生成 Excel / PDF 的開發者；
• 看到響應裏有 bash_code_execution、server_tool_use，不知道是什麼的人。

基礎調用見 /guides/claude-api-python-quickstart。想自己定義工具、自己執行，見 /guides/claude-tool-use-basics；代碼執行是 Anthropic 一側執行的工具，和它不同。網頁版 Claude 的數據分析見 /guides/claude-data-analysis-csv。

結論先說

1. 官方定義： 代碼執行工具讓 Claude 在安全的沙盒容器裏運行 Bash 命令、創建和編輯文件（包括寫代碼），在 API 對話中分析數據、畫圖表、做複雜計算、處理上載的文件。
2. 服務端執行，不需要你回傳結果。 官方說 API 在服務端運行每條命令，並在同一次請求裏把結果交給 Claude，你不需要自己執行代碼，也不用回傳 tool_result（只有 Claude 同時調用你自己的客戶端工具時，才會出現需要你回傳的情況）。
3. 三個版本： code_execution_20250825（Bash 和文件操作）、code_execution_20260120（再加 REPL 狀態保持和程序化工具調用）、code_execution_20260521（與前者同一運行時，只是工具描述裏告知了每個 Python 單元 90 秒牆鐘上限）。三個版本都不需要 anthropic-beta 頭。
4. 容器沒有網絡。 官方明確：沙盒完全禁止聯網，不能運行時下載包，只能用預裝庫。
5. 計費： 與聯網搜尋 / 網頁抓取（web_search_20260209 或 web_fetch_20260209 及更新版本）一起用時，除標準 token 外不額外收費；否則按執行時間計，每個組織每月有免費額度，超出部分按小時算（具體數字見第五節，以官方當前顯示為準）。

圖：本站根據 Claude 官方文檔：Code execution tool 整理的示意圖

一、最小請求

官方 Quick start 讓 Claude 計算一組數的平均值和標準差。Python 寫法：

python
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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)

工具定義不需要額外參數。官方說明兩個字段都是固定的：type 選擇工具版本，name 必須是 code_execution。

加了這個工具，Claude 自動獲得兩個子工具：bash_code_execution（運行 shell 命令）和 text_editor_code_execution（查看、創建、編輯文件）。

Claude 什麼時候會跑代碼： 官方列出：非平凡的數學（大數、多步、對精度敏感）、數據分析 / 文件解析 / 可視化、算法執行或模擬，以及你明確要求「運行」「計算」「執行」。簡單算術、事實問答、簡單換算和翻譯會直接回答。邊界情況想讓它跑，就明確說「run code to verify this」。

二、上載自己的文件來分析

官方列出的可處理文件：CSV、Excel（.xlsx、.xls）、JSON、XML、圖片（JPEG、PNG、GIF、WebP）以及 .txt / .md / .py 等文本文件。三步：

1. 用 Files API 上載文件；
2. 在消息裏用 container_upload 內容塊引用它；
3. 請求裏帶上代碼執行工具。

官方 Python 示例：

python
from pathlib import Path
import anthropic

client = anthropic.Anthropic()

# 上載文件
file_object = client.files.upload(file=Path("data.csv"))

# 在代碼執行裏使用 file_id
response = client.messages.create(
    model="claude-opus-5-5",
    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 沒調用工具，也會按執行時間計費，因為文件會被預加載到容器裏。

三、取回 Claude 生成的文件

圖：本站根據官方文檔整理的示意圖

官方機制：每次 bash_code_execution 調用都會得到一個全新的空目錄，命令裏可通過環境變量 $OUTPUT_DIR 訪問。命令結束後，該目錄頂層的文件會被捕獲，並作為 file_id 條目出現在結果的 content 列表裏；寫在別處的文件留在容器裏，不會返回。拿到 file_id 後，用 Files API 下載。

官方建議：如果你的應用依賴拿到某個文件，在提示詞裏讓 Claude 把文件複製到 $OUTPUT_DIR 並在同一條命令裏列出目錄，ls 的輸出能確認文件確實被捕獲（Claude 自己看不到 content 列表）：

bash
python /tmp/make_report.py && cp /tmp/report.pdf "$OUTPUT_DIR/" && ls "$OUTPUT_DIR"

如果文件被寫在別處，可以複用容器，再讓 Claude 複製進 $OUTPUT_DIR。

官方還提到：在 Claude API 上，沙盒裏生成的受支持的圖片、影片、音頻文件，通過 Files API 下載時會帶 C2PA 內容憑證，所以下載文件的大小和校驗值與容器裏的不同；文本、PDF 和 Office 文檔不會被簽名。

四、返回裏怎麼看，錯誤怎麼查

命令結果（bash_code_execution_result）包含 stdout、stderr、return_code（0 為成功，非 0 為失敗）和 content（$OUTPUT_DIR 裏的文件列表）。文件操作有各自的結果類型，例如查看文件 text_editor_code_execution_view_result、創建文件 text_editor_code_execution_create_result。

錯誤會出現在結果塊的 error_code 裏，官方列出的錯誤碼：

另外，官方說明已過期的容器不能複用，引用它的請求會返回錯誤；重新發請求，不帶 container 參數即可拿到新容器。長回合可能返回 stop_reason: "pause_turn"，把響應原樣放進下一次請求就能讓 Claude 繼續，並且要把響應裏的容器 ID 一起帶上，否則會在新容器裏繼續，之前的文件會丟。

五、容器、複用和計費

運行環境（官方）： Python 3.11、Linux、x86_64；5 GiB 內存、5 GiB 工作區磁盤、1 個 CPU；完全禁止聯網；容器創建 30 天后過期。

預裝庫： 數據科學（pandas、numpy、scipy、scikit-learn、statsmodels）、可視化（matplotlib、seaborn）、文件處理（pyarrow、openpyxl、xlsxwriter、xlrd、pillow、python-pptx、python-docx、pypdf、pdfplumber 等）、數學（sympy、mpmath），以及 unzip、rg、sqlite 等命令行工具。完整列表見官方頁面。

容器複用： 響應裏有頂層 container 對象，帶 id 和 expires_at。把這個 ID 通過請求的頂層 container 參數傳回，就能繼續使用同一個容器、保留創建的文件。官方說明：容器約 5 分鐘不活動會被存檔，在 30 天內帶 ID 請求可以恢復；響應裏的 expires_at 是更短的滾動值，不代表 30 天的上限。使用 code_execution_20260120 或更新版本並配合程序化工具調用時，Python 解釋器狀態（比如變量）也會保留。

計費（官方頁面 2026-11-05）：

• 與聯網搜尋 / 網頁抓取（web_search_20260209、web_fetch_20260209 或更新）一起用，除標準 token 外無額外費用；
• 單獨使用時按執行時間計費，與 token 分開統計：最少 5 分鐘；每個組織每月有 1,550 小時免費；超出部分每個容器每小時 0.05 美元；
• 用量在響應的 usage.server_tool_use.code_execution_requests 裏體現。

價格以官方頁面當前顯示為準。聯網搜尋見 /guides/claude-api-web-search-tool。

六、和你自己的執行工具一起用

官方提醒：如果同時提供了你自己的、也能執行代碼的客戶端工具（比如 Bash 工具或自定義 REPL），Claude 面對的是「多台計算機」的環境：代碼執行工具在 Anthropic 的沙盒容器裏，你的工具在你控制的另一個環境裏，Claude 有時會用錯工具，或誤以為兩邊狀態共享。解決辦法是在系統提示詞裏寫清區別，官方給了一段示例，要點是：變量和文件不會在不同環境間保留；通用計算用 code_execution；需要訪問用戶本地文件時用客戶端工具；要傳結果就在後續調用裏明確帶上。聯網搜尋和網頁抓取會自動啟用代碼執行，所以組合使用時尤其要注意。

常見問題

Q：能裝自己需要的 Python 包嗎？

不能。官方說容器沒有網絡，不能運行時下載或安裝包，只能用預裝庫。

Q：能用在 Bedrock、Vertex 上嗎？

官方頁面的支持平台列了 Claude API、Claude Platform on AWS、Claude Models on Google Cloud（Anthropic 託管）和 Microsoft Foundry（託管在 Anthropic 上）。其他平台請看官方「Availability」一節。

Q：數據會保留多久？敏感數據能用嗎？

官方說明容器數據最多保留 30 天，並且代碼執行不符合零數據保留條件。涉及敏感數據請先自行評估。

Q：429 怎麼辦？

見 /guides/claude-api-error-429-rate-limit。

相關教學

• /guides/claude-tool-use-basics：自己定義的工具調用
• /guides/claude-api-web-search-tool：聯網搜尋工具
• /guides/claude-api-python-quickstart：Python 快速上手

參考資料

• Claude 開發者平台文檔：Code execution tool — https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool