Claude Platform Docs
MensagensFerramentas

Ferramenta de editor de texto

Forneça ao Claude a ferramenta de editor de texto definida pela Anthropic para visualizar, criar e editar arquivos, e lide com seus comandos view, str_replace, create e insert.

Claude pode usar uma ferramenta de editor de texto com esquema da Anthropic para visualizar e modificar arquivos de texto, ajudando você a depurar, corrigir e melhorar seu código ou outros documentos de texto. Isso permite que Claude interaja diretamente com seus arquivos, fornecendo assistência prática em vez de apenas sugerir alterações.

Para suporte de modelos, consulte a Referência de ferramentas.

Quando usar a ferramenta de editor de texto

Alguns exemplos de quando usar a ferramenta de editor de texto são:

  • Depuração de código: Peça ao Claude para identificar e corrigir bugs no seu código, desde erros de sintaxe até problemas de lógica.
  • Refatoração de código: Deixe Claude melhorar a estrutura, a legibilidade e o desempenho do seu código por meio de edições direcionadas.
  • Geração de documentação: Peça ao Claude para adicionar docstrings, comentários ou arquivos README à sua base de código.
  • Criação de testes: Peça ao Claude para criar testes unitários para o seu código com base na análise da implementação.

Use a ferramenta de editor de texto

Forneça a ferramenta de editor de texto (chamada str_replace_based_edit_tool) ao Claude usando a Messages API.

Opcionalmente, você pode especificar um parâmetro max_characters para controlar o truncamento ao visualizar arquivos grandes.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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)

Use a ferramenta de editor de texto da seguinte forma:

  1. Forneça ao Claude a ferramenta de editor de texto e um prompt do usuário

    • Inclua a ferramenta de editor de texto na sua solicitação de API.
    • Forneça um prompt do usuário que possa exigir examinar ou modificar arquivos, como “Você pode corrigir o erro de sintaxe no meu código?”
  2. Claude usa a ferramenta para examinar arquivos ou diretórios

    • Claude avalia o que precisa analisar e usa o comando view para examinar o conteúdo de arquivos ou listar o conteúdo de diretórios.
    • A resposta da API contém um bloco de conteúdo tool_use com o comando view.
  3. Execute o comando view e retorne os resultados

    • Extraia o caminho do arquivo ou diretório da solicitação de uso de ferramentas do Claude.
    • Leia o conteúdo do arquivo ou liste o conteúdo do diretório.
    • Se você especificou um parâmetro max_characters na configuração da ferramenta, trunque o conteúdo do arquivo para esse comprimento.
    • Retorne os resultados ao Claude continuando a conversa com uma nova mensagem user contendo um bloco de conteúdo tool_result.
  4. Claude usa a ferramenta para modificar arquivos

    • Após examinar o arquivo ou diretório, Claude pode usar um comando como str_replace para fazer alterações ou insert para adicionar texto em um número de linha específico.
    • Se Claude usar o comando str_replace, Claude constrói uma solicitação de uso de ferramentas devidamente formatada com o texto antigo e o novo texto pelo qual substituí-lo.
  5. Faça a edição e retorne os resultados

    • Extraia o caminho do arquivo, o texto antigo e o novo texto da solicitação de uso de ferramentas do Claude.
    • Realize a substituição de texto no arquivo.
    • Retorne os resultados ao Claude.
  6. Claude fornece sua análise e explicação

    • Após examinar e possivelmente editar os arquivos, Claude fornece uma explicação completa do que encontrou e das alterações que fez.

Comandos da ferramenta de editor de texto

A ferramenta de editor de texto suporta vários comandos para visualizar e modificar arquivos:

view

O comando view permite que Claude examine o conteúdo de um arquivo ou liste o conteúdo de um diretório. Ele pode ler o arquivo inteiro ou um intervalo específico de linhas.

Parâmetros:

  • command: Deve ser view
  • path: O caminho para o arquivo ou diretório a ser visualizado
  • view_range (opcional): Um array de dois inteiros especificando os números de linha inicial e final a serem visualizados. Os números de linha começam em 1, e -1 para a linha final significa ler até o fim do arquivo. Este parâmetro só se aplica ao visualizar arquivos, não diretórios.

str_replace

O comando str_replace permite que Claude substitua uma string específica em um arquivo por uma nova string. Ele é usado para fazer edições precisas.

Parâmetros:

  • command: Deve ser str_replace
  • path: O caminho para o arquivo a ser modificado
  • old_str: O texto a ser substituído (deve corresponder exatamente, incluindo espaços em branco e indentação)
  • new_str: O novo texto a ser inserido no lugar do texto antigo

create

O comando create permite que Claude crie um novo arquivo com o conteúdo especificado.

Parâmetros:

  • command: Deve ser create
  • path: O caminho onde o novo arquivo deve ser criado
  • file_text: O conteúdo a ser escrito no novo arquivo

insert

O comando insert permite que Claude insira texto em um local específico de um arquivo.

Parâmetros:

  • command: Deve ser insert
  • path: O caminho para o arquivo a ser modificado
  • insert_line: O número da linha após a qual o texto será inserido (0 para o início do arquivo)
  • insert_text: O texto a ser inserido

Exemplo: Corrigindo um erro de sintaxe com a ferramenta de editor de texto

Este exemplo demonstra como Claude usa a ferramenta de editor de texto para corrigir um erro de sintaxe em um arquivo Python.

Primeiro, sua aplicação fornece ao Claude a ferramenta de editor de texto e um prompt para corrigir um erro de sintaxe:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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)

Claude usa a ferramenta de editor de texto primeiro para visualizar o arquivo:

Output
{
  "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
  "model": "claude-opus-5-5",
  "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"
      }
    }
  ]
}

Sua aplicação deve então ler o arquivo e retornar seu conteúdo ao Claude:

response = client.messages.create(
    model="claude-opus-5-5",
    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)

Claude identifica o erro de sintaxe e usa o comando str_replace para corrigi-lo:

Output
{
  "id": "msg_01VwXyZAbCdEfGhIjKlMnO",
  "model": "claude-opus-5-5",
  "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):"
      }
    }
  ]
}

Sua aplicação deve então fazer a edição e retornar o resultado:

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

Por fim, Claude fornece uma explicação completa da correção:

Output
{
  "id": "msg_01IjKlMnOpQrStUvWxYzAb",
  "model": "claude-opus-5-5",
  "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."
    }
  ]
}

Implemente a ferramenta de editor de texto

A ferramenta de editor de texto é implementada como uma ferramenta sem esquema. Ao usar esta ferramenta, você não precisa fornecer um esquema de entrada como acontece com outras ferramentas; o esquema está embutido no modelo do Claude e não pode ser modificado.

O tipo da ferramenta é type: "text_editor_20250728" para Claude 4 e modelos posteriores.

  1. Inicialize sua implementação do editor

    Crie funções auxiliares para lidar com operações de arquivo, como ler, escrever e modificar arquivos. Considere implementar uma funcionalidade de backup para se recuperar de erros.

  2. Lide com as chamadas da ferramenta de editor

    Crie uma função que processe as chamadas de ferramenta do Claude com base no tipo de comando:

    def handle_editor_tool(tool_call):
        input_params = tool_call.input
        command = input_params.get("command", "")
        file_path = input_params.get("path", "")
    
        match command:
            case "view":
                # Lê e retorna o conteúdo do arquivo
                pass
            case "str_replace":
                # Substitui texto no arquivo
                pass
            case "create":
                # Cria um novo arquivo
                pass
            case "insert":
                # Insere texto na posição indicada
                pass
  3. Implemente medidas de segurança

    Adicione validações e verificações de segurança:

    • Valide caminhos de arquivo para evitar directory traversal
    • Crie backups antes de fazer alterações
    • Trate erros de forma adequada
    • Implemente verificações de permissão
  4. Processe as respostas do Claude

    Extraia e lide com as chamadas de ferramenta das respostas do Claude:

    # Processa o uso de ferramentas na resposta do Claude
    for content in response.content:
        if content.type == "tool_use":
            # Executa a ferramenta com base no comando
            result = handle_editor_tool(content)
    
            # Retorna o resultado ao Claude
            tool_result = {
                "type": "tool_result",
                "tool_use_id": content.id,
                "content": result,
            }

Lide com erros

Ao usar a ferramenta de editor de texto, vários erros podem ocorrer. Aqui estão orientações sobre como lidar com eles:

Siga as melhores práticas de implementação


Preços e uso de tokens

A ferramenta de editor de texto usa a mesma estrutura de preços que outras ferramentas usadas com o Claude. Ela segue os preços padrão de tokens de entrada e saída com base no modelo Claude que você está usando.

Além dos tokens base, os seguintes tokens de entrada adicionais são necessários para a ferramenta de editor de texto:

FerramentaTokens de entrada adicionais
text_editor_20250728 (Claude 4.7 e modelos posteriores e Claude Mythos Preview)974 tokens
text_editor_20250728 (Claude 4.6 e modelos anteriores)745 tokens

Para informações mais detalhadas sobre preços de ferramentas, consulte Preços de uso de ferramentas.

Integre a ferramenta de editor de texto com outras ferramentas

Você pode usar a ferramenta de editor de texto junto com outras ferramentas do Claude. Ao combinar ferramentas, certifique-se de:

  • Fazer corresponder a versão da ferramenta com o modelo que você está usando
  • Considerar o uso adicional de tokens de todas as ferramentas incluídas na sua solicitação

Registro de alterações

DataVersãoAlterações
28 de julho de 2025text_editor_20250728Lançamento de uma ferramenta de editor de texto atualizada que corrige alguns problemas e adiciona um parâmetro opcional max_characters. Fora isso, é idêntica a text_editor_20250429.
29 de abril de 2025text_editor_20250429Lançamento da ferramenta de editor de texto para Claude 4. Esta versão remove o comando undo_edit, mas mantém todas as outras capacidades. O nome da ferramenta foi atualizado para refletir sua arquitetura baseada em str_replace.
13 de março de 2025text_editor_20250124Introdução da documentação independente da ferramenta de editor de texto. Esta versão é otimizada para Claude Sonnet 3.7, mas tem capacidades idênticas às da versão anterior.
22 de outubro de 2024text_editor_20241022Lançamento inicial da ferramenta de editor de texto com Claude Sonnet 3.5 (desativado; consulte Descontinuações de modelos). Fornece capacidades para visualizar, criar e editar arquivos por meio dos comandos view, create, str_replace, insert e undo_edit.

Próximos passos

Aqui estão algumas ideias de como usar a ferramenta de editor de texto de formas mais convenientes e poderosas:

  • Integre ao seu fluxo de trabalho de desenvolvimento: Incorpore a ferramenta de editor de texto às suas ferramentas de desenvolvimento ou IDE.
  • Crie um sistema de revisão de código: Peça ao Claude para revisar seu código e fazer melhorias.
  • Construa um assistente de depuração: Crie um sistema em que Claude possa ajudar você a diagnosticar e corrigir problemas no seu código.
  • Implemente conversão de formatos de arquivo: Deixe Claude ajudar você a converter arquivos de um formato para outro.
  • Automatize a documentação: Configure fluxos de trabalho para que Claude documente seu código automaticamente.

A ferramenta de editor de texto permite que Claude trabalhe diretamente com sua base de código, suportando fluxos de trabalho que vão da depuração à documentação automatizada.

Aprenda a implementar fluxos de trabalho de ferramentas para uso com Claude.

Execute comandos de shell com Claude.

Disponibilidade

Ferramenta de editor de texto
Os requisitos de disponibilidade de Ferramenta de editor de texto são os mesmos em todas as plataformas compatíveis.
API
  • Messages API
Modelos
  • Todos os modelos

Endpoints aplicáveis

  • /v1/messages com a ferramenta text_editor
Retenção zero de dadosElegível

Exclui Modelos cobertos

Ferramenta no lado do cliente executada no seu ambiente.

HIPAAElegível

Esta página foi útil?