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