结论先说
- 官方预训练模式,客户端本地执行:声明
text_editor_20250728和bash_20250124时不需要自己写冗长的input_schema,Claude 原生熟悉这套参数与行号修改规范,但真正的读写文件和跑 Shell 命令由你的后端程序执行并通过tool_result回传。 - 两者固定名称一个字都不能改:文本编辑工具的
name固定为str_replace_based_edit_tool,命令行工具的name固定为bash。 - Bash 工具预期保持持久会话状态:同一个任务循环内,上一轮执行的
cd切换目录、export环境变量应当在下一轮继续生效,直到模型主动传入restart: true重置终端。 - 文本修改靠精确字符串替换防改崩:
str_replace要求待替换片段old_str在目标文件中恰好只匹配一处;匹配不到或匹配多处时,客户端必须返回报错让模型补上下文重试,绝不能全量替换。 - 国内免卡开通与账号服务入口:自有账号免上号自助开通可见本站 Claude Pro 充值页 与 Claude Max 充值页;缺可用账号或遇身份核验可查看 Claude 注册说明 与 Claude KYC 认证协助。

图:本站根据 Claude 官方文档:Text editor tool 与 Bash tool 整理的示意图
本文根据 Claude 开发者平台官方文档《Bash tool》《Text editor tool》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic 官方网站。
适用于谁
- 搜「claude api text editor tool」「claude bash tool 怎么用」,正在自研编程智能体或自动化运维助手的开发者;
- 自己写了文件读写函数,却老遇到模型改错行号、漏大括号或把长文件截断重写的人;
- 想分清客户端内置工具(Bash + Text Editor)与服务端沙盒代码执行工具区别的人。
如果你希望代码直接跑在 Anthropic 托管的云端容器里而不在本地执行,请改看 /guides/claude-api-code-execution-tool。
一、标准请求写法:把看改代码与跑测试配成闭环
在软件工程智能体里,官方最推荐的组合是把 Text Editor(负责精确查看和改代码)与 Bash(负责跑编译、单测和 Git)同时放进 tools 数组。当前主流模型直接调用即可,无需再加额外的 anthropic-beta 请求头:
python
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
tools=[
{
"type": "text_editor_20250728",
"name": "str_replace_based_edit_tool",
"max_characters": 10000,
},
{
"type": "bash_20250124",
"name": "bash",
},
],
messages=[
{"role": "user", "content": "查看 src/utils.py 里的除零报错,修复后运行 pytest 验证。"}
],
)
其中 max_characters 是 text_editor_20250728 支持的可选参数,用于提示和控制查看大文件时的单次字符截断上限,防止模型一上来读进几万行构建产物撑爆上下文(基础工具回传循环见 /guides/claude-tool-use-basics)。
二、Text Editor 四大子命令与客户端实现要点
当模型调用 str_replace_based_edit_tool 时,输出的 input 会携带 command 字段。在 text_editor_20250728 版本中,你需要实现以下四个子命令分支(早期版本里的 undo_edit 已被移除):
view(查看文件或列出目录):传入path和可选的view_range(如[1, 80],从第 1 行起算,末位填-1代表读到文件末尾)。如果path是目录,返回目录下的非隐藏文件列表;如果是文件,务必在每行前面拼上行号返回(例如1: import os),模型后续调用insert全靠这套行号定位;create(新建文件):传入path与完整内容file_text。为防模型无意覆盖已有业务源码,若目标文件已存在,建议在客户端拦截或先提示先读再改;str_replace(精确字符串替换):传入path、old_str和new_str。客户端读取文件后统计old_str出现次数:等于 0 次返回「未找到匹配文本,请检查缩进与空格」;大于 1 次返回「匹配到多处,请在old_str中多带几行前后上下文确保唯一」;恰好 1 次才执行替换并落盘,同时把is_error: True留给前两种异常情况;insert(按行号插入):传入path、insert_line与new_str,在指定行号之后插入新文本(传0代表插在文件最开头)。
Claude 会员充值与成品号提示:国内银行卡在结账页被拒时,可通过本站支付宝、微信支付或 AlipayHK 获取 iOS 订阅卡密自助开通 Claude Pro 或高配额 Claude Max(全程无需上号交密码);需要现成账号可了解 Claude Pro 成品号 与 Claude Max 5x 成品号(注:Anthropic 消费者条款禁止共享转让账号且违规可终止无退款,成品号均明确标注不质保封号)。
三、Bash 状态保持机制与防卡死设计
模型调用 bash 工具时,输入只有两种形态:传 {"command": "pytest -q"} 执行命令,或传 {"restart": true} 要求重启一个干净的 Shell 进程。客户端落地时要注意三个工程细节:
- 怎么保持状态:不要每收到一次请求就调无状态的
subprocess.run()完事,否则模型上一轮执行了cd backend && source .venv/bin/activate,下一轮又回到根目录,虚拟环境也没了。标准做法是维护一个绑定当前会话的常驻/bin/bash子进程或容器连接,收到restart: true时再销毁重建; - 严防交互式命令挂死标准输入:模型偶尔会写出
vim、less、top、不带-y的安装命令或一直监听端口的npm run dev。客户端必须给单次命令加上硬超时(如 30 到 120 秒),超时后终止进程组并把已捕获的stdout/stderr连同超时提示返回给模型; - 截断超长标准输出:一次
cat大日志或打印巨型堆栈可能吐出几兆文本,回传tool_result前应在客户端做头尾保留截断。
四、客户端安全边界与现成替代方案

图:本站根据 Claude 官方文档:Bash tool 与 Text editor tool 整理的示意图
因为这两个工具直接碰触文件系统与操作系统命令,上线前必须守住三条安全边界:
- 路径规范化防目录穿越:对模型传入的所有
path先做Path.resolve()规范化解析,严格校验最终真实路径落在允许的项目根目录之内,并且显式拉黑.env、私钥目录与凭证文件; - 容器沙箱与高危命令拦截:多租户或无人值守场景必须在受限 Docker 容器、微虚拟机或 OS 级沙箱中执行 Bash,对
rm -rf、修改权限、访问内网元数据地址等高危命令加前置审批; - 写文件前留好回退快照:既然新版编辑工具去掉了内置撤销动作,建议客户端在每次
str_replace前做内存备份或基于 Git 工作树留存检查点。
如果你不想从零手写持久 Shell、行号拼接与权限拦截代码,直接用官方封装好整套工具链的 /guides/claude-agent-sdk-quickstart 或终端编程工具会省下大量底座开发工作;需要开通官方终端订阅额度时,也可以参考本站 Claude Code 充值页 的套餐说明。
常见问题
问:为什么我把 name 改成了 my_file_editor 后,请求直接报 400 错误?
答:官方内置模式工具的名称与内部训练词绑定,不允许自定义改名。text_editor_20250728 必须配 "name": "str_replace_based_edit_tool",bash_20250124 必须配 "name": "bash"。
问:Windows 服务器上没有 /bin/bash,能用 bash_20250124 工具吗?
答:模型针对该工具生成的语法默认是标准 Linux / POSIX Bash 命令(如 grep、sed、正斜杠路径)。在 Windows 环境下建议把执行器放进 WSL2 或 Linux Docker 容器中运行,直接丢给 PowerShell 会频繁出现语法报错。
问:模型频繁报 str_replace 找不到 old_str 怎么缓解?
答:常见原因是换行符(CRLF 与 LF 混用)或制表符缩进不一致,以及模型没先调用 view 就凭记忆盲改。客户端读取文件时可统一将换行符标准化为 \n,并在报错文本里提醒模型先用 view 查看目标行附近最新内容。
问:人在国内没有外币信用卡,怎么订阅或升级 Claude 付费套餐?
答:可在本站 AI 会员充值总览页 选择 Claude Pro 自助充值 或 Claude Max 充值,付款后即时发卡密、24 小时自助兑换且可开具增值税发票;实时价格与售后边界(含封号不质保)以商品页当天展示为准。
相关教程
- Claude Tool Use(工具调用 / Function Calling)入门:定义工具与返回 tool_result
- Claude API 代码执行工具(code execution)怎么用
- Claude Agent SDK 入门:是什么、怎么装、第一个智能体
- Claude Code 沙箱(sandbox)是什么:限制命令读写与网络访问
参考资料
- Claude 开发者平台文档:Bash tool — https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool
- Claude 开发者平台文档:Text editor tool — https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool
0 条评论
还没有评论,来抢沙发~