文本编辑器工具

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Claude 可以使用 Anthropic 架构的文本编辑器工具来查看和修改文本文件，帮助您调试、修复和改进代码或其他文本文档。这使 Claude 能够直接与您的文件交互，提供实际操作的帮助，而不仅仅是建议更改。

有关模型支持，请参阅工具参考。

何时使用文本编辑器工具

以下是使用文本编辑器工具的一些示例：

代码调试： 让 Claude 识别并修复代码中的错误，从语法错误到逻辑问题。
代码重构： 让 Claude 通过有针对性的编辑来改进代码结构、可读性和性能。
文档生成： 要求 Claude 为您的代码库添加文档字符串、注释或 README 文件。
测试创建： 让 Claude 根据其对实现的理解为您的代码创建单元测试。

使用文本编辑器工具

使用 Messages API 向 Claude 提供文本编辑器工具（名为 str_replace_based_edit_tool）。

您可以选择指定 max_characters 参数来控制查看大型文件时的截断。

max_characters 仅与 text_editor_20250728 及更高版本的文本编辑器工具兼容。

文本编辑器工具可以按以下方式使用：

文本编辑器工具命令

文本编辑器工具支持多个用于查看和修改文件的命令：

view

view 命令允许 Claude 检查文件的内容或列出目录的内容。它可以读取整个文件或特定范围的行。

参数：

command：必须为 "view"
path：要查看的文件或目录的路径
view_range（可选）：一个包含两个整数的数组，指定要查看的开始和结束行号。行号从 1 开始，结束行为 -1 表示读到文件末尾。此参数仅在查看文件时适用，不适用于目录。

str_replace

str_replace 命令允许 Claude 用新字符串替换文件中的特定字符串。这用于进行精确编辑。

参数：

command：必须为 "str_replace"
path：要修改的文件的路径
old_str：要替换的文本（必须完全匹配，包括空格和缩进）
new_str：要插入以替换旧文本的新文本

create

create 命令允许 Claude 创建一个包含指定内容的新文件。

参数：

command：必须为 "create"
path：应创建新文件的路径
file_text：要写入新文件的内容

insert

insert 命令允许 Claude 在文件中的特定位置插入文本。

参数：

command：必须为 "insert"
path：要修改的文件的路径
insert_line：要在其后插入文本的行号（0 表示文件开头）
insert_text：要插入的文本

示例：使用文本编辑器工具修复语法错误

此示例演示了 Claude 如何使用文本编辑器工具修复 Python 文件中的语法错误。

首先，您的应用程序为 Claude 提供文本编辑器工具和修复语法错误的提示：

Claude 首先使用文本编辑器工具查看文件：

Output

{
  "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
  "model": "claude-opus-4-6",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue."
    },
    {
      "type": "tool_use",
      "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
      "name": "str_replace_based_edit_tool",
      "input": {
        "command": "view",
        "path": "primes.py"
      }
    }
  ]
}

您的应用程序应该读取文件并将其内容返回给 Claude：

行号

在上面的示例中，view 工具结果包含文件内容，每行前面都有行号（例如，"1: def is_prime(n):"）。行号不是必需的，但对于成功使用 view_range 参数检查文件的特定部分和 insert_line 参数在精确位置添加内容至关重要。

Claude 识别语法错误并使用 str_replace 命令修复它：

Output

{
  "id": "msg_01VwXyZAbCdEfGhIjKlMnO",
  "model": "claude-opus-4-6",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01PqRsTuVwXyZAbCdEfGh",
      "name": "str_replace_based_edit_tool",
      "input": {
        "command": "str_replace",
        "path": "primes.py",
        "old_str": "    for num in range(2, limit + 1)",
        "new_str": "    for num in range(2, limit + 1):"
      }
    }
  ]
}

您的应用程序应该进行编辑并返回结果：

最后，Claude 提供了修复的完整说明：

Output

{
  "id": "msg_01IjKlMnOpQrStUvWxYzAb",
  "model": "claude-opus-4-6",
  "stop_reason": "end_turn",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I've fixed the syntax error in your primes.py file. The issue was in the `get_primes` function at line 19. There was a missing colon (:) at the end of the for loop line.\n\nHere's what I changed:\n\nFrom:\n```python\nfor num in range(2, limit + 1)\n```\n\nTo:\n```python\nfor num in range(2, limit + 1):\n```\n\nIn Python, a colon is required at the end of statements that start a new code block, such as for loops, if statements, function definitions, etc. Without the colon, Python raises a syntax error because it doesn't know where the code block begins.\n\nYour code should now run correctly. The function will properly generate a list of prime numbers up to the specified limit."
    }
  ]
}

实现文本编辑器工具

文本编辑器工具是作为无模式工具实现的。使用此工具时，您不需要像其他工具那样提供输入模式；该模式内置于 Claude 的模型中，无法修改。

对于 Claude 4 模型，工具类型为 type: "text_editor_20250728"。

实现文本编辑器工具时，请记住：

安全性： 该工具可以访问您的本地文件系统，因此请实现适当的安全措施。
备份： 在允许编辑重要文件之前，始终创建备份。
验证： 验证所有输入以防止意外更改。
唯一匹配： 确保替换恰好匹配一个位置，以避免意外编辑。

处理错误

使用文本编辑器工具时，可能会发生各种错误。以下是如何处理它们的指导：

遵循实现最佳实践

定价和令牌使用

The text editor tool uses the same pricing structure as other tools used with Claude. It follows the standard input and output token pricing based on the Claude model you're using.

In addition to the base tokens, the following additional input tokens are needed for the text editor tool:

Tool	Additional input tokens
`text_editor_20250429` (Claude 4.x)	700 tokens
`text_editor_20250124` (Claude Sonnet 3.7 (deprecated))	700 tokens

有关工具定价的更多详细信息，请参阅工具使用定价。

将文本编辑器工具与其他工具集成

文本编辑器工具可以与其他 Claude 工具一起使用。组合工具时，请确保：

将工具版本与您使用的模型匹配
考虑请求中包含的所有工具的额外令牌使用

更改日志

日期	版本	更改
2025 年 7 月 28 日	`text_editor_20250728`	发布更新的文本编辑器工具，修复了一些问题并添加了可选的 `max_characters` 参数。除此之外，它与 `text_editor_20250429` 相同。
2025 年 4 月 29 日	`text_editor_20250429`	为 Claude 4 发布文本编辑器工具。此版本删除了 `undo_edit` 命令，但保持了所有其他功能。工具名称已更新以反映其基于 str_replace 的架构。
2025 年 3 月 13 日	`text_editor_20250124`	引入独立文本编辑器工具文档。此版本针对 Claude Sonnet 3.7 进行了优化，但具有与之前版本相同的功能。
2024 年 10 月 22 日	`text_editor_20241022`	使用 Claude Sonnet 3.5（已停用）初始发布文本编辑器工具。通过 `view`、`create`、、和命令提供查看、创建和编辑文件的功能。

后续步骤

以下是如何以更便捷和强大的方式使用文本编辑器工具的一些想法：

与您的开发工作流集成：将文本编辑器工具构建到您的开发工具或 IDE 中
创建代码审查系统：让 Claude 审查您的代码并进行改进
构建调试助手：创建一个系统，其中 Claude 可以帮助您诊断和修复代码中的问题
实现文件格式转换：让 Claude 帮助您将文件从一种格式转换为另一种格式
自动化文档：设置工作流让 Claude 自动为您的代码编写文档

文本编辑器工具使 Claude 能够直接与您的代码库一起工作，支持从调试到自动化文档的工作流。

工具使用概述

了解如何实现与 Claude 一起使用的工具工作流。

Bash 工具

使用 Claude 执行 shell 命令。

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "text_editor_20250728",
        "name": "str_replace_based_edit_tool",
        "max_characters": 10000
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "There'\''s a syntax error in my primes.py file. Can you help me fix it?"
      }
    ]
  }'

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "text_editor_20250728",
        "name": "str_replace_based_edit_tool"
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "There'\''s a syntax error in my primes.py file. Can you help me fix it?"
      }
    ]
  }'

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "text_editor_20250728",
        "name": "str_replace_based_edit_tool"
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "There'\''s a syntax error in my primes.py file. Can you help me fix it?"
      },
      {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I'\''ll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue."
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
                    "name": "str_replace_based_edit_tool",
                    "input": {
                        "command": "view",
                        "path": "primes.py"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
                    "content": "1: def is_prime(n):\n2:     \"\"\"Check if a number is prime.\"\"\"\n3:     if n <= 1:\n4:         return False\n5:     if n <= 3:\n6:         return True\n7:     if n % 2 == 0 or n % 3 == 0:\n8:         return False\n9:     i = 5\n10:     while i * i <= n:\n11:         if n % i == 0 or n % (i + 2) == 0:\n12:             return False\n13:         i += 6\n14:     return True\n15: \n16: def get_primes(limit):\n17:     \"\"\"Generate a list of prime numbers up to the given limit.\"\"\"\n18:     primes = []\n19:     for num in range(2, limit + 1)\n20:         if is_prime(num):\n21:             primes.append(num)\n22:     return primes\n23: \n24: def main():\n25:     \"\"\"Main function to demonstrate prime number generation.\"\"\"\n26:     limit = 100\n27:     prime_list = get_primes(limit)\n28:     print(f\"Prime numbers up to {limit}:\")\n29:     print(prime_list)\n30:     print(f\"Found {len(prime_list)} prime numbers.\")\n31: \n32: if __name__ == \"__main__\":\n33:     main()"
                }
            ]
        }
    ]
  }'

ant messages create <<'YAML'
model: claude-opus-4-6
max_tokens: 1024
tools:
  - type: text_editor_20250728
    name: str_replace_based_edit_tool
messages:
  # Previous messages...
  - role: assistant
    content:
      - type: text
        text: >-
          I found the syntax error in your primes.py file. In the `get_primes`
          function, there is a missing colon (:) at the end of the for loop
          line. Let me fix that for you.
      - type: tool_use
        id: toolu_01PqRsTuVwXyZAbCdEfGh
        name: str_replace_based_edit_tool
        input:
          command: str_replace
          path: primes.py
          old_str: "    for num in range(2, limit + 1)"
          new_str: "    for num in range(2, limit + 1):"
  - role: user
    content:
      - type: tool_result
        tool_use_id: toolu_01PqRsTuVwXyZAbCdEfGh
        content: Successfully replaced text at exactly one location.
YAML

初始化您的编辑器实现
创建辅助函数来处理文件操作，如读取、写入和修改文件。考虑实现备份功能以从错误中恢复。

处理编辑器工具调用

创建一个函数来处理来自 Claude 的工具调用，基于命令类型：

def handle_editor_tool(tool_call):
    input_params = tool_call.input
    command = input_params.get("command", "")
    file_path = input_params.get("path", "")

    if command == "view":
        # Read and return file contents
        pass
    elif command == "str_replace":
        # Replace text in file
        pass
    elif command == "create":
        # Create new file
        pass
    elif command == "insert":
        # Insert text at location
        pass

实现安全措施
添加验证和安全检查：
- 验证文件路径以防止目录遍历
- 在进行更改前创建备份
- 优雅地处理错误
- 实现权限检查

处理 Claude 的响应

从 Claude 的响应中提取和处理工具调用：

# Process tool use in Claude's response
for content in response.content:
    if content.type == "tool_use":
        # Execute the tool based on command
        result = handle_editor_tool(content)

        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

str_replace

insert

undo_edit

何时使用文本编辑器工具

使用文本编辑器工具

文本编辑器工具命令

view

查看命令示例

str_replace

str_replace 命令示例

create

create 命令示例

insert

insert 命令示例

示例：使用文本编辑器工具修复语法错误

实现文本编辑器工具

处理错误

文件未找到

替换的多个匹配

遵循实现最佳实践

提供清晰的上下文

明确指定文件路径

在编辑前创建备份

定价和令牌使用

将文本编辑器工具与其他工具集成

更改日志

后续步骤

替换没有匹配

权限错误

小心处理唯一文本替换

验证更改