代码执行工具

Claude 可以直接在 API 对话中分析数据、创建可视化图表、执行复杂计算、运行系统命令、创建和编辑文件，以及处理上传的文件。"code execution tool"（代码执行工具）允许 Claude 在安全的"sandbox"（沙箱）环境中运行 Bash 命令并操作文件，包括编写代码。

与网络搜索或网页获取（web_search_20260209、web_fetch_20260209 或更高版本）一起使用时，代码执行是免费的。 当您的请求中包含这些工具之一时，该请求中的代码执行除标准令牌费用外不会产生额外费用。这既涵盖动态过滤背后的代码执行，也涵盖 Claude 直接运行的任何代码。未包含这些工具时，适用标准代码执行定价。

代码执行还为网络搜索和网页获取工具中的"dynamic filtering"（动态过滤）提供支持：Claude 会在结果进入"context window"（上下文窗口）之前，在代码执行环境中对其进行过滤。当动态过滤运行时，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 秒的挂钟时间限制，以便 Claude 为长时间运行的单元格做好时间规划。超出该限制的单元格会返回一个正常的代码执行结果，其中 return_code 为非零值，输出中包含 detection_timeout 状态消息。这与 execution_time_exceeded 错误代码不同，后者是在整个工具调用超出最大执行时间时由 API 返回的。

这三个工具版本都不需要 anthropic-beta 标头。旧版代码执行 beta 标头仍然是有效的选择性启用方式。

本页中的示例使用 code_execution_20250825，它涵盖了示例所演示的 Bash 和文件操作，并且在每个受支持的模型上行为一致；当您需要程序化工具调用或 REPL 状态持久化时，请使用 code_execution_20260120 或更高版本。当前的网络搜索和网页获取工具（web_search_20260209、web_fetch_20260209 及更高版本）要求代码执行版本为 code_execution_20260120 或更高版本。

较旧的工具版本不保证与较新的模型保持兼容。当您采用新模型时，请查看工具版本和兼容性，并优先使用您的集成所支持的最新工具版本。

快速入门

以下示例要求 Claude 执行一项计算：

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.to_json())

响应中会交替出现 server_tool_use 块（Claude 运行的命令）及其工具结果块，随后是 Claude 的文本。顶层还包含一个 container 对象，您可以在多个请求之间复用其 id。有关各个块的结构，请参阅响应格式。

代码执行的工作原理

当您将代码执行工具添加到 API 请求中时：

1. Claude 评估代码执行是否有助于回答您的问题
2. 该工具会自动为 Claude 提供以下能力：
   • Bash 命令： 运行 shell 命令以执行系统操作
   • 文件操作： 直接创建、查看和编辑文件，包括编写代码
3. Claude 可以在单个请求中任意组合使用这些能力
4. 所有操作都在安全的沙箱"container"（容器）中运行。容器无法访问互联网，因此 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.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 在代码执行期间将文件保存到其输出目录时（请参阅如何捕获生成的文件），每个文件的 ID 都会出现在代码执行工具结果中，您可以使用 Files API 下载它：

client = Anthropic()

# 请求执行会创建文件的代码
response = client.messages.create(
    model="claude-opus-5-5",
    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: Message) -> 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.files.retrieve_metadata(file_id)
    file_content = client.files.download(file_id)
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

如何捕获生成的文件

每次 bash_code_execution 调用都会获得一个新的空目录，命令可以通过 $OUTPUT_DIR 访问该目录。命令完成后，该目录顶层的文件会被捕获，并作为结果 content 列表中的 file_id 条目返回。写入其他任何位置的文件会保留在容器中，不会被返回。

工具描述会告知 Claude 通过将文件复制到 $OUTPUT_DIR 来共享文件。如果您的应用程序依赖于接收某个文件，请提示 Claude 将其复制到 $OUTPUT_DIR，并在同一命令中列出该目录，以便 ls 的输出确认文件已被捕获（Claude 看不到 content 列表）：

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

Claude 写入其他位置的文件仍在容器中，因此您可以复用该容器，并要求 Claude 将其复制到 $OUTPUT_DIR。

生成文件上的 Content Credentials

在 Claude API 上，当您通过 Files API 下载 Claude 在代码执行沙箱中生成的受支持图像、视频和音频文件时，这些文件会带有 C2PA Content Credentials（内容凭证）。受支持的格式包括 PNG、JPEG、GIF、WebP、TIFF、HEIC、AVIF、SVG、MP4、MOV、MP3、WAV、FLAC 和 M4A。该凭证是嵌入在文件元数据中的经过加密签名的清单。它将 Anthropic 标识为签发者，带有时间戳，并记录操作描述"Claude provided this file at the request of a user and may have created or modified the file contents."

签名无需对您的请求或响应处理进行任何更改，并且清单不会记录任何关于您、您的组织或您的请求的信息。文件的可见内容保持不变。清单会增加几千字节，因此下载文件的大小和校验和与容器内的文件不同。文本文件、PDF 和办公文档不会被签名，因为它们不是受支持的签名格式。您上传的文件会按原样存储，包括它们已带有的任何 Content Credentials。

要验证凭证，请使用任何兼容 C2PA 的工具检查文件，例如开源的 c2patool 命令行实用程序。重新编码、格式转换、截图以及会剥离元数据的工具都会移除凭证，因此缺少凭证并不意味着文件不是由 Claude 生成的。有关凭证可能缺失的更多原因，请参阅 Claude 如何标记 AI 生成的内容。

工具定义

代码执行工具不需要额外的参数：

{
  "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 时间戳。在顶层 container 请求参数中传回该 ID，即可继续使用同一容器。请参阅容器复用。

响应格式

根据操作的不同，代码执行工具可以返回两种类型的结果：

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：一个列表，命令留在 $OUTPUT_DIR 中的每个文件都对应一个条目（请参阅如何捕获生成的文件）。每个条目都带有 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 一样，容器的作用范围限定于请求所属的工作区
• 过期： 容器在创建 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 分钟后会被创建检查点，在 30 天期限内使用其 ID 发送请求即可恢复该容器。响应的 container 对象中的 expires_at 时间戳是一个较短的滚动值，并不反映 30 天的期限。已过期的容器无法复用。请在不带 container 参数的情况下重新发送请求，以获取新容器。

示例

client = anthropic.Anthropic()

# 第一个请求：在新容器中创建一个包含随机数的文件
response1 = client.messages.create(
    model="claude-opus-5-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-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 请求中的调用相同。

用量与定价

与 web search（网页搜索）或 web fetch（网页抓取）一起使用时，代码执行是免费的。 当您的 API 请求中包含 web_search_20260209（或更高版本）或 web_fetch_20260209（或更高版本）时，除标准的输入和输出令牌费用外，代码执行工具调用不会产生额外费用。

在不与这些工具一起使用时，代码执行按执行时间计费，并与令牌用量分开跟踪：

• 执行时间最少按 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.files.download() 获取）会一直保留，直到被明确删除。

有关所有功能的 ZDR 资格，请参阅 API 与数据保留。

后续步骤

Compatibility