Claude pode usar uma ferramenta de editor de texto definida pela Anthropic para visualizar e modificar arquivos de texto, ajudando você a depurar, corrigir e melhorar seu código ou outros documentos de texto.
Claude pode usar uma ferramenta de editor de texto definida pela 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 mudanças.
Claude Sonnet 3.5 (descontinuado) requer o cabeçalho beta computer-use-2024-10-22 ao usar a ferramenta de editor de texto.A ferramenta de editor de texto está geralmente disponível nos modelos Claude 4 e Claude Sonnet 3.7.
A ferramenta text_editor_20250728 para modelos Claude 4 não inclui o comando undo_edit. Se você precisar dessa funcionalidade, será necessário usar Claude Sonnet 3.7 ou Sonnet 3.5 com suas respectivas versões de ferramenta.
Versões mais antigas de ferramentas não são garantidas para serem compatíveis com versões anteriores com modelos mais novos. Sempre use a versão da ferramenta que corresponde à sua versão do modelo.
Forneça a ferramenta de editor de texto (chamada str_replace_based_edit_tool) para Claude usando a API Messages.Você pode opcionalmente especificar um parâmetro max_characters para controlar o truncamento ao visualizar arquivos grandes.
max_characters é compatível apenas com text_editor_20250728 e versões posteriores da ferramenta de editor de texto.
Copy
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-sonnet-4-5", "max_tokens": 1024, "tools": [ { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool", "max_characters": 10000 } ], "messages": [ { "role": "user", "content": "Há um erro de sintaxe no meu arquivo primes.py. Você pode me ajudar a corrigi-lo?" } ] }'
A ferramenta de editor de texto pode ser usada da seguinte maneira:
1
Forneça a Claude a ferramenta de editor de texto e um prompt do usuário
Inclua a ferramenta de editor de texto em sua solicitação de API
Forneça um prompt do usuário que pode 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 examinar e usa o comando view para examinar o conteúdo dos arquivos ou listar o conteúdo dos diretórios
A resposta da API conterá 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 ferramenta de Claude
Leia o conteúdo do arquivo ou liste o conteúdo do diretório
Se um parâmetro max_characters foi especificado na configuração da ferramenta, truncar o conteúdo do arquivo para esse comprimento
Retorne os resultados para 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 mudanças 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 ferramenta adequadamente formatada com o texto antigo e o novo texto para substituí-lo
5
Execute a edição e retorne os resultados
Extraia o caminho do arquivo, texto antigo e novo texto da solicitação de uso de ferramenta de Claude
Execute a substituição de texto no arquivo
Retorne os resultados para 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 quais mudanças fez
O comando view permite que Claude examine o conteúdo de um arquivo ou liste o conteúdo de um diretório. 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 para visualizar. Os números de linha são indexados em 1, e -1 para a linha final significa ler até o final do arquivo. Este parâmetro se aplica apenas ao visualizar arquivos, não diretórios.
Exemplos de comandos view
Copy
// Exemplo para visualizar um arquivo{ "type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "str_replace_editor", "input": { "command": "view", "path": "primes.py" }}// Exemplo para visualizar um diretório{ "type": "tool_use", "id": "toolu_02B19r91rw91mr917835mr9", "name": "str_replace_editor", "input": { "command": "view", "path": "src/" }}
O comando str_replace permite que Claude substitua uma string específica em um arquivo por uma nova string. Isso é 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
Exemplo de comando str_replace
Copy
{ "type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "str_replace_editor", "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):" }}
O comando insert permite que Claude insira texto em um local específico em 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 inserir o texto (0 para o início do arquivo)
new_str: O texto a ser inserido
Exemplo de comando insert
Copy
{ "type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "str_replace_editor", "input": { "command": "insert", "path": "primes.py", "insert_line": 0, "new_str": "\"\"\"Módulo para trabalhar com números primos.\n\nEste módulo fornece funções para verificar se um número é primo\ne para gerar uma lista de números primos até um limite dado.\n\"\"\"\n" }}
O comando undo_edit permite que Claude reverta a última edição feita em um arquivo.
Este comando está disponível apenas no Claude Sonnet 3.7 e Claude Sonnet 3.5 (descontinuado). Não é suportado nos modelos Claude 4 usando o text_editor_20250728.
Parâmetros:
command: Deve ser “undo_edit”
path: O caminho para o arquivo cuja última edição deve ser desfeita
Exemplo: Corrigindo um erro de sintaxe com a ferramenta de editor de texto
Este exemplo demonstra como os modelos Claude 4 usam a ferramenta de editor de texto para corrigir um erro de sintaxe em um arquivo Python.Primeiro, sua aplicação fornece a Claude a ferramenta de editor de texto e um prompt para corrigir um erro de sintaxe:
Copy
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-sonnet-4-5", "max_tokens": 1024, "tools": [ { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool" } ], "messages": [ { "role": "user", "content": "Há um erro de sintaxe no meu arquivo primes.py. Você pode me ajudar a corrigi-lo?" } ] }'
Claude usará a ferramenta de editor de texto primeiro para visualizar o arquivo:
Copy
{ "id": "msg_01XAbCDeFgHiJkLmNoPQrStU", "model": "claude-sonnet-4-5", "stop_reason": "tool_use", "role": "assistant", "content": [ { "type": "text", "text": "Vou ajudá-lo a corrigir o erro de sintaxe no seu arquivo primes.py. Primeiro, deixe-me dar uma olhada no arquivo para identificar o problema." }, { "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 para Claude:
Copy
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-sonnet-4-5", "max_tokens": 1024, "tools": [ { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool" } ], "messages": [ { "role": "user", "content": "Há um erro de sintaxe no meu arquivo primes.py. Você pode me ajudar a corrigi-lo?" }, { "role": "assistant", "content": [ { "type": "text", "text": "Vou ajudá-lo a corrigir o erro de sintaxe no seu arquivo primes.py. Primeiro, deixe-me dar uma olhada no arquivo para identificar o problema." }, { "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()" } ] } ] }'
Números de linhaNo exemplo acima, o resultado da ferramenta view inclui o conteúdo do arquivo com números de linha anexados a cada linha (por exemplo, “1: def is_prime(n):”). Os números de linha não são obrigatórios, mas são essenciais para usar com sucesso o parâmetro view_range para examinar seções específicas de arquivos e o parâmetro insert_line para adicionar conteúdo em locais precisos.
Claude identificará o erro de sintaxe e usará o comando str_replace para corrigi-lo:
Copy
{ "id": "msg_01VwXyZAbCdEfGhIjKlMnO", "model": "claude-sonnet-4-5", "stop_reason": "tool_use", "role": "assistant", "content": [ { "type": "text", "text": "Encontrei o erro de sintaxe no seu arquivo primes.py. Na função `get_primes`, há dois pontos (:) ausentes no final da linha do loop for. Deixe-me corrigir isso para você." }, { "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:
Copy
response = client.messages.create( model="claude-sonnet-4-5", max_tokens=1024, tools=[ { "type": "text_editor_20250728", "name": "str_replace_based_edit_tool" } ], messages=[ # Mensagens anteriores... { "role": "assistant", "content": [ { "type": "text", "text": "Encontrei o erro de sintaxe no seu arquivo primes.py. Na função `get_primes`, há dois pontos (:) ausentes no final da linha do loop for. Deixe-me corrigir isso para você." }, { "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": "Texto substituído com sucesso em exatamente um local." } ] } ])
Finalmente, Claude fornecerá uma explicação completa da correção:
Copy
{ "id": "msg_01IjKlMnOpQrStUvWxYzAb", "model": "claude-sonnet-4-5", "stop_reason": "end_turn", "role": "assistant", "content": [ { "type": "text", "text": "Corrigi o erro de sintaxe no seu arquivo primes.py. O problema estava na função `get_primes` na linha 19. Havia dois pontos (:) ausentes no final da linha do loop for.\n\nAqui está o que mudei:\n\nDe:\n```python\nfor num in range(2, limit + 1)\n```\n\nPara:\n```python\nfor num in range(2, limit + 1):\n```\n\nEm Python, dois pontos são obrigatórios no final de declarações que iniciam um novo bloco de código, como loops for, declarações if, definições de função, etc. Sem os dois pontos, Python gera um erro de sintaxe porque não sabe onde o bloco de código começa.\n\nSeu código agora deve executar corretamente. A função gerará adequadamente uma lista de números primos até o limite especificado." } ]}
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 com outras ferramentas; o esquema está incorporado no modelo de Claude e não pode ser modificado.O tipo de ferramenta depende da versão do modelo:
Claude 4: type: "text_editor_20250728"
Claude Sonnet 3.7: type: "text_editor_20250124"
Claude Sonnet 3.5 (descontinuado): type: "text_editor_20241022"
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 funcionalidade de backup para recuperar de erros.
2
Lidar com chamadas de ferramenta do editor
Crie uma função que processa chamadas de ferramenta de Claude baseadas no tipo de comando:
Copy
def handle_editor_tool(tool_call, model_version): input_params = tool_call.input command = input_params.get('command', '') file_path = input_params.get('path', '') if command == 'view': # Ler e retornar conteúdo do arquivo pass elif command == 'str_replace': # Substituir texto no arquivo pass elif command == 'create': # Criar novo arquivo pass elif command == 'insert': # Inserir texto no local pass elif command == 'undo_edit': # Verificar se é um modelo Claude 4 if 'str_replace_based_edit_tool' in model_version: return {"error": "comando undo_edit não é suportado no Claude 4"} # Restaurar do backup para Claude 3.7/3.5 pass
3
Implementar medidas de segurança
Adicione validação e verificações de segurança:
Validar caminhos de arquivo para prevenir travessia de diretório
Criar backups antes de fazer mudanças
Lidar com erros graciosamente
Implementar verificações de permissões
4
Processar respostas de Claude
Extrair e lidar com chamadas de ferramenta das respostas de Claude:
Copy
# Processar uso de ferramenta na resposta de Claudefor content in response.content: if content.type == "tool_use": # Executar a ferramenta baseada no comando result = handle_editor_tool(content) # Retornar resultado para Claude tool_result = { "type": "tool_result", "tool_use_id": content.id, "content": result }
Ao implementar a ferramenta de editor de texto, tenha em mente:
Segurança: A ferramenta tem acesso ao seu sistema de arquivos local, então implemente medidas de segurança adequadas.
Backup: Sempre crie backups antes de permitir edições em arquivos importantes.
Validação: Valide todas as entradas para prevenir mudanças não intencionais.
Correspondência única: Certifique-se de que as substituições correspondam exatamente a um local para evitar edições não intencionais.
Se o comando str_replace de Claude corresponder a múltiplos locais no arquivo, retorne uma mensagem de erro apropriada:
Copy
{ "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Erro: Encontradas 3 correspondências para o texto de substituição. Por favor, forneça mais contexto para fazer uma correspondência única.", "is_error": true } ]}
Nenhuma correspondência para substituição
Se o comando str_replace de Claude não corresponder a nenhum texto no arquivo, retorne uma mensagem de erro apropriada:
Copy
{ "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Erro: Nenhuma correspondência encontrada para substituição. Por favor, verifique seu texto e tente novamente.", "is_error": true } ]}
Erros de permissão
Se houver problemas de permissão com criação, leitura ou modificação de arquivos, retorne uma mensagem de erro apropriada:
Copy
{ "role": "user", "content": [ { "type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9", "content": "Erro: Permissão negada. Não é possível escrever no arquivo.", "is_error": true } ]}
Ao pedir para Claude corrigir ou modificar código, seja específico sobre quais arquivos precisam ser examinados ou quais problemas precisam ser abordados. Contexto claro ajuda Claude a identificar os arquivos corretos e fazer mudanças apropriadas.Prompt menos útil: “Você pode corrigir meu código?”Prompt melhor: “Há um erro de sintaxe no meu arquivo primes.py que impede que ele execute. Você pode corrigi-lo?”
Ser explícito sobre caminhos de arquivo
Especifique caminhos de arquivo claramente quando necessário, especialmente se você estiver trabalhando com múltiplos arquivos ou arquivos em diretórios diferentes.Prompt menos útil: “Revise meu arquivo auxiliar”Prompt melhor: “Você pode verificar meu arquivo utils/helpers.py para quaisquer problemas de desempenho?”
Criar backups antes de editar
Implemente um sistema de backup em sua aplicação que cria cópias de arquivos antes de permitir que Claude os edite, especialmente para código importante ou de produção.
Copy
def backup_file(file_path): """Criar um backup de um arquivo antes de editar.""" backup_path = f"{file_path}.backup" if os.path.exists(file_path): with open(file_path, 'r') as src, open(backup_path, 'w') as dst: dst.write(src.read())
Lidar com substituição de texto única cuidadosamente
O comando str_replace requer uma correspondência exata para o texto a ser substituído. Sua aplicação deve garantir que haja exatamente uma correspondência para o texto antigo ou fornecer mensagens de erro apropriadas.
Copy
def safe_replace(file_path, old_text, new_text): """Substituir texto apenas se houver exatamente uma correspondência.""" with open(file_path, 'r') as f: content = f.read() count = content.count(old_text) if count == 0: return "Erro: Nenhuma correspondência encontrada" elif count > 1: return f"Erro: Encontradas {count} correspondências" else: new_content = content.replace(old_text, new_text) with open(file_path, 'w') as f: f.write(new_content) return "Texto substituído com sucesso"
Verificar mudanças
Após Claude fazer mudanças em um arquivo, verifique as mudanças executando testes ou verificando se o código ainda funciona como esperado.
Copy
def verify_changes(file_path): """Executar testes ou verificações após fazer mudanças.""" try: # Para arquivos Python, verificar erros de sintaxe if file_path.endswith('.py'): import ast with open(file_path, 'r') as f: ast.parse(f.read()) return "Verificação de sintaxe passou" except Exception as e: return f"Verificação falhou: {str(e)}"
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:
Lançamento de uma ferramenta de editor de texto atualizada que corrige alguns problemas e adiciona um parâmetro opcional max_characters. É idêntica ao text_editor_20250429.
29 de abril de 2025
text_editor_20250429
Lanç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 2025
text_editor_20250124
Introdução da documentação da ferramenta de editor de texto independente. Esta versão é otimizada para Claude Sonnet 3.7 mas tem capacidades idênticas à versão anterior.
22 de outubro de 2024
text_editor_20241022
Lançamento inicial da ferramenta de editor de texto com Claude Sonnet 3.5 (descontinuado). Fornece capacidades para visualizar, criar e editar arquivos através dos comandos view, create, str_replace, insert e undo_edit.
Aqui estão algumas ideias de como usar a ferramenta de editor de texto de maneiras mais convenientes e poderosas:
Integrar com seu fluxo de trabalho de desenvolvimento: Construa a ferramenta de editor de texto em suas ferramentas de desenvolvimento ou IDE
Criar um sistema de revisão de código: Faça Claude revisar seu código e fazer melhorias
Construir um assistente de depuração: Crie um sistema onde Claude pode ajudá-lo a diagnosticar e corrigir problemas em seu código
Implementar conversão de formato de arquivo: Deixe Claude ajudá-lo a converter arquivos de um formato para outro
Automatizar documentação: Configure fluxos de trabalho para Claude documentar automaticamente seu código
Conforme você constrói aplicações com a ferramenta de editor de texto, estamos animados para ver como você aproveita as capacidades de Claude para aprimorar seu fluxo de trabalho de desenvolvimento e produtividade.