文字編輯器工具

此功能符合「Zero Data Retention」（零資料保留），即 ZDR 的資格。當您的組織具有 ZDR 安排時，透過此功能傳送的資料在 API 回應返回後不會被儲存。

Claude 可以使用 Anthropic 定義結構的文字編輯器工具來檢視和修改文字檔案，協助您除錯、修正和改進程式碼或其他文字文件。這讓 Claude 能夠直接與您的檔案互動，提供實際操作的協助，而不僅僅是建議變更。

如需模型支援資訊，請參閱工具參考。

何時使用文字編輯器工具

以下是一些使用文字編輯器工具的範例情境：

程式碼除錯： 讓 Claude 識別並修正程式碼中的錯誤，從語法錯誤到邏輯問題皆可。
程式碼重構： 讓 Claude 透過針對性的編輯來改善程式碼結構、可讀性和效能。
文件產生： 請 Claude 為您的程式碼庫新增 docstring、註解或 README 檔案。
測試建立： 讓 Claude 根據其對實作的理解，為您的程式碼建立單元測試。

使用文字編輯器工具

使用 Messages API 將文字編輯器工具（名稱為 str_replace_based_edit_tool）提供給 Claude。

您可以選擇性地指定 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-8",
  "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-8",
  "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-8",
  "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."
    }
  ]
}

實作文字編輯器工具

文字編輯器工具是以無結構描述（schema-less）工具的形式實作。使用此工具時，您不需要像其他工具一樣提供輸入結構描述；結構描述已內建於 Claude 的模型中，無法修改。

對於 Claude 4 模型，工具類型為 type: "text_editor_20250728"。

實作文字編輯器工具時，請記住以下事項：

安全性： 此工具可存取您的本機檔案系統，因此請實作適當的安全措施。
備份： 在允許編輯重要檔案之前，務必建立備份。
驗證： 驗證所有輸入以防止非預期的變更。
唯一比對： 確保取代內容僅符合一個位置，以避免非預期的編輯。

處理錯誤

使用文字編輯器工具時，可能會發生各種錯誤。以下是處理這些錯誤的指引：

遵循實作最佳實務

定價與 token 用量

文字編輯器工具採用與 Claude 其他工具相同的定價結構。它遵循基於您所使用的 Claude 模型的標準輸入和輸出 token 定價。

除了基本 token 之外，文字編輯器工具還需要以下額外的輸入 token：

工具	額外輸入 token
`text_editor_20250429`（Claude 4.x）	700 個 token

如需更詳細的工具定價資訊，請參閱工具使用定價。

將文字編輯器工具與其他工具整合

文字編輯器工具可以與其他 Claude 工具一起使用。結合工具時，請確保您：

將工具版本與您使用的模型相符
考量請求中包含的所有工具所產生的額外 token 用量

變更記錄

日期	版本	變更
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 命令。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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?",
        }
    ],
)

print(response)

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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?",
        }
    ],
)

print(response)

response = client.messages.create(
    model="claude-opus-4-8",
    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()',
                }
            ],
        },
    ],
)

print(response)

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}],
    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.",
                }
            ],
        },
    ],
)

print(response)

初始化您的編輯器實作
建立輔助函式來處理檔案操作，例如讀取、寫入和修改檔案。考慮實作備份功能以便從錯誤中復原。

處理編輯器工具呼叫

建立一個函式，根據命令類型處理來自 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":
        # 讀取並回傳檔案內容
        pass
    elif command == "str_replace":
        # 取代檔案中的文字
        pass
    elif command == "create":
        # 建立新檔案
        pass
    elif command == "insert":
        # 在指定位置插入文字
        pass

實作安全措施
新增驗證和安全檢查：
- 驗證檔案路徑以防止目錄遍歷攻擊
- 在進行變更前建立備份
- 妥善處理錯誤
- 實作權限檢查

處理 Claude 的回應

從 Claude 的回應中擷取並處理工具呼叫：

# 處理 Claude 回應中的工具使用
for content in response.content:
    if content.type == "tool_use":
        # 根據命令執行工具
        result = handle_editor_tool(content)

        # 將結果回傳給 Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

str_replace

insert

undo_edit

何時使用文字編輯器工具

使用文字編輯器工具

文字編輯器工具命令

view

view 命令範例

str_replace

str_replace 命令範例

create

create 命令範例

insert

insert 命令範例

範例：使用文字編輯器工具修正語法錯誤

實作文字編輯器工具

處理錯誤

找不到檔案

取代時有多個符合項目

遵循實作最佳實務

提供清楚的上下文

明確指定檔案路徑

編輯前建立備份

定價與 token 用量

將文字編輯器工具與其他工具整合

變更記錄

後續步驟

取代時沒有符合項目

權限錯誤

謹慎處理唯一文字取代

驗證變更

何時使用文字編輯器工具

使用文字編輯器工具

文字編輯器工具命令

view

str_replace

create

insert

範例：使用文字編輯器工具修正語法錯誤

實作文字編輯器工具

處理錯誤

遵循實作最佳實務

定價與 token 用量

將文字編輯器工具與其他工具整合

變更記錄

後續步驟