Claude API Bash 与 Text Editor 内置工具怎么用:状态保持、文件查看修改与安全边界

自己搭编程智能体不必手写文件修改和命令行 JSON Schema。本文按官方文档讲清 bash_20250124 与 text_editor_20250728 两个内置客户端工具的调用格式、Shell 状态保持、str_replace 唯一匹配要求与安全边界。

NNathaniel bigo··原创首发·AI 辅助撰写
13 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 其他 账号

结论先说

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

Bash 与 Text Editor 内置工具对比

图:本站根据 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 已被移除):

  1. view(查看文件或列出目录):传入 path 和可选的 view_range(如 [1, 80],从第 1 行起算,末位填 -1 代表读到文件末尾)。如果 path 是目录,返回目录下的非隐藏文件列表;如果是文件,务必在每行前面拼上行号返回(例如 1: import os),模型后续调用 insert 全靠这套行号定位;
  2. create(新建文件):传入 path 与完整内容 file_text。为防模型无意覆盖已有业务源码,若目标文件已存在,建议在客户端拦截或先提示先读再改;
  3. str_replace(精确字符串替换):传入 path、old_str 和 new_str。客户端读取文件后统计 old_str 出现次数:等于 0 次返回「未找到匹配文本,请检查缩进与空格」;大于 1 次返回「匹配到多处,请在 old_str 中多带几行前后上下文确保唯一」;恰好 1 次才执行替换并落盘,同时把 is_error: True 留给前两种异常情况;
  4. 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 整理的示意图

因为这两个工具直接碰触文件系统与操作系统命令,上线前必须守住三条安全边界:

  1. 路径规范化防目录穿越:对模型传入的所有 path 先做 Path.resolve() 规范化解析,严格校验最终真实路径落在允许的项目根目录之内,并且显式拉黑 .env、私钥目录与凭证文件;
  2. 容器沙箱与高危命令拦截:多租户或无人值守场景必须在受限 Docker 容器、微虚拟机或 OS 级沙箱中执行 Bash,对 rm -rf、修改权限、访问内网元数据地址等高危命令加前置审批;
  3. 写文件前留好回退快照:既然新版编辑工具去掉了内置撤销动作,建议客户端在每次 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 开发者平台文档: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

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  2. 02

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0
  3. 03

    Langfuse 开源本地部署(Docker Compose)与提示词版本管理(Prompt Management)从零上手教程

    企业内网严禁业务日志出境,又想免费拥有大模型调用链追踪与不发版热更新提示词的能力?本文按 Langfuse 官方文档整理 Docker Compose 本地一键启动(含 ClickHouse 架构注意事项)、密钥配置与 Prompt Management 标签化版本管理全流程。

    Claude其他 AI 工具0
  4. 04

    LangSmith 入门教程:给 LangGraph 与原生 OpenAI / Claude 接口加调用链追踪、Token 成本统计与免费层限额

    智能体多步调用总是找不到哪一轮提示词跑偏、单次请求到底烧了多少 Token?本文按 LangSmith 官方文档讲清环境变量零侵入接入 LangGraph、用 wrap_openai / wrap_anthropic 与 @traceable 追踪原生接口,以及 Developer 免费层额度与留存规则。

    Claude其他 AI 工具0
  5. 05

    Zotero 搭配 Claude / ChatGPT 高效读英文文献:PDF 翻译插件、批注导出精读与防捏造参考文献流程

    在 Zotero 里读英文顶会论文怎么无缝联动 Claude 与 ChatGPT?本文整理 Translate for Zotero 划词翻译配置、高亮批注导出精读提示词,以及杜绝 AI 捏造假 DOI 参考文献的核验闭环。

    Claude其他 AI 工具0
  6. 06

    Obsidian 接入 Claude、ChatGPT 与本地 Ollama 做个人双链笔记问答:主流插件配置与隐私脱敏边界

    想在 Obsidian 里基于自己的双链笔记库做 AI 问答又担心隐私外泄?本文对比 Copilot 与 Smart Connections 插件,整理接入 Claude、OpenAI 官方 API 与本地 Ollama 的步骤及敏感目录隔离规则。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~