代码执行工具

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

当与网络搜索或网络获取一起使用时，代码执行是免费的。 当您的请求中包含 web_search_20260209（或更高版本）或 web_fetch_20260209（或更高版本）时，除了标准的输入和输出令牌费用外，代码执行工具调用不会产生额外费用。当不包含这些工具时，将按标准代码执行费用收费。

代码执行是构建高性能智能体的核心基础能力。它支持在网络搜索和网络获取工具中进行动态过滤，使 Claude 能够在结果进入上下文窗口之前对其进行处理，从而提高准确性并减少令牌消耗。



模型兼容性

代码执行工具可在以下模型上使用：



平台可用性

代码执行可在以下平台上使用：

• 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)



流式传输

启用流式传输后，您将在代码执行事件发生时接收到它们：

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（或更高版本）时，除了标准的输入和输出令牌费用外，代码执行工具调用不会产生额外费用。

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

• 执行时间最低按 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 中了解更多信息。