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:
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?”
Claude usa a ferramenta para examinar arquivos ou diretórios
- Claude avalia o que precisa analisar e usa o comando
viewpara 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_usecom o comandoview.
- Claude avalia o que precisa analisar e usa o comando
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_charactersna 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
usercontendo um bloco de conteúdotool_result.
Claude usa a ferramenta para modificar arquivos
- Após examinar o arquivo ou diretório, Claude pode usar um comando como
str_replacepara fazer alterações ouinsertpara 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.
- Após examinar o arquivo ou diretório, Claude pode usar um comando como
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.
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 serviewpath: O caminho para o arquivo ou diretório a ser visualizadoview_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.
Exemplo de visualização de um arquivo:
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "str_replace_based_edit_tool",
"input": {
"command": "view",
"path": "primes.py"
}
}Exemplo de visualização de um diretório:
{
"type": "tool_use",
"id": "toolu_02B19r91rw91mr917835mr9",
"name": "str_replace_based_edit_tool",
"input": {
"command": "view",
"path": "src/"
}
}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 serstr_replacepath: O caminho para o arquivo a ser modificadoold_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
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"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):"
}
}create
O comando create permite que Claude crie um novo arquivo com o conteúdo especificado.
Parâmetros:
command: Deve sercreatepath: O caminho onde o novo arquivo deve ser criadofile_text: O conteúdo a ser escrito no novo arquivo
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "str_replace_based_edit_tool",
"input": {
"command": "create",
"path": "test_primes.py",
"file_text": "import unittest\nimport primes\n\nclass TestPrimes(unittest.TestCase):\n def test_is_prime(self):\n self.assertTrue(primes.is_prime(2))\n self.assertTrue(primes.is_prime(3))\n self.assertFalse(primes.is_prime(4))\n\nif __name__ == '__main__':\n unittest.main()"
}
}insert
O comando insert permite que Claude insira texto em um local específico de um arquivo.
Parâmetros:
command: Deve serinsertpath: O caminho para o arquivo a ser modificadoinsert_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
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "str_replace_based_edit_tool",
"input": {
"command": "insert",
"path": "primes.py",
"insert_line": 0,
"insert_text": "\"\"\"Module for working with prime numbers.\n\nThis module provides functions to check if a number is prime\nand to generate a list of prime numbers up to a given limit.\n\"\"\"\n"
}
}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:
{
"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:
{
"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:
{
"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.
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.
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:
Pythondef 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 passImplemente 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
Processe as respostas do Claude
Extraia e lide com as chamadas de ferramenta das respostas do Claude:
Python# 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:
Se Claude tentar visualizar ou modificar um arquivo que não existe, retorne uma mensagem de erro apropriada no tool_result:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: File not found",
"is_error": true
}
]
}Se o comando str_replace do Claude corresponder a múltiplos locais no arquivo, retorne uma mensagem de erro apropriada:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Found 3 matches for replacement text. Please provide more context to make a unique match.",
"is_error": true
}
]
}Se o comando str_replace do Claude não corresponder a nenhum texto no arquivo, retorne uma mensagem de erro apropriada:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: No match found for replacement. Please check your text and try again.",
"is_error": true
}
]
}Se houver problemas de permissão ao criar, ler ou modificar arquivos, retorne uma mensagem de erro apropriada:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Permission denied. Cannot write to file.",
"is_error": true
}
]
}Siga as melhores práticas de implementação
Ao pedir ao Claude para corrigir ou modificar código, seja específico sobre quais arquivos examinar ou quais problemas resolver. Um contexto claro ajuda Claude a identificar os arquivos certos e fazer as alterações apropriadas.
Prompt menos útil: “Você pode corrigir meu código?”
Prompt melhor: “Há um erro de sintaxe no meu arquivo primes.py que impede sua execução. Você pode corrigi-lo?”
Especifique os 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 em busca de problemas de desempenho?”
Implemente um sistema de backup na sua aplicação que crie cópias dos arquivos antes de permitir que Claude os edite, especialmente para código importante ou de produção.
def backup_file(file_path):
"""Create a backup of a file before editing."""
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())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.
def safe_replace(file_path, old_text, new_text):
"""Replace text only if there's exactly one match."""
with open(file_path, "r") as f:
content = f.read()
count = content.count(old_text)
if count == 0:
return "Error: No match found"
elif count > 1:
return f"Error: Found {count} matches"
else:
new_content = content.replace(old_text, new_text)
with open(file_path, "w") as f:
f.write(new_content)
return "Successfully replaced text"Depois que Claude fizer alterações em um arquivo, verifique as alterações executando testes ou checando se o código ainda funciona como esperado.
def verify_changes(file_path):
"""Run tests or checks after making changes."""
try:
# Para arquivos Python, verifica se há erros de sintaxe
if file_path.endswith(".py"):
import ast
with open(file_path, "r") as f:
ast.parse(f.read())
return "Syntax check passed"
except Exception as e:
return f"Verification failed: {str(e)}"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:
| Ferramenta | Tokens 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
| Data | Versão | Alterações |
|---|---|---|
| 28 de julho de 2025 | text_editor_20250728 | Lanç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 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 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 2024 | text_editor_20241022 | Lanç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
Claude API
- API
- Messages API
- Modelos
- Todos os modelos
Amazon Bedrock
- API
- Messages API
- Modelos
- Todos os modelos
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Modelos
- Todos os modelos
Claude Platform on AWS
- API
- Messages API
- Modelos
- Todos os modelos
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Modelos
- Todos os modelos
Microsoft Foundry
- API
- Messages API
- Modelos
- Todos os modelos
Tratamento de dados
Visão geral do tratamento de dadosEndpoints aplicáveis
/v1/messagescom a ferramentatext_editor
Exclui Modelos cobertos
Ferramenta no lado do cliente executada no seu ambiente.
Esta página foi útil?