Claude Code 自定义工具插件：为 Claude 添加新工具

Claude Code 自定义工具插件为 Claude 提供可在回合中调用的新工具，例如针对项目的专用搜索、在你的问题跟踪系统中查询，或者为你的代码库所关心的某件事专门做的计算器。工具用 JavaScript 写在插件内部，在 Claude Code 中运行，因此无需另外启动服务器进程。

Claude Code 自定义工具插件如何添加工具？#

插件调用 $.tool.register(...)，传入名称、供 Claude 阅读的描述，以及它接受的输入。当 Claude 决定使用这个工具时，调用会像任何内置工具一样经过 tool.call 事件，插件通过返回 { result } 来作答。$.tool.list() 显示可用的工具，$.tool.call() 则让插件自己调用某个工具。

另外还有两个事件值得关注。tool.describe 在工具描述首次发送给 Claude 时触发；插件可以改写描述文本，或把工具标记为延迟加载，让它在需要之前不占用上下文。agent.offer 和 $.agent.register 则为子代理类型完成同样的工作。API 参考文档记录了 $.tool 和 $.agent 的各个方法。

安装前应该检查什么？#

工具插件会显示 添加命令/工具 标记，其余的标记则说明这个工具能触及哪些资源。查询网络 API 的工具会显示 网络访问；搜索文件的工具会显示 读取文件；运行代码检查器的工具会显示 执行命令。由于何时调用工具由 Claude 决定，这些能力可能在任何回合中被使用，而不只是在你提出要求时，所以请把它们当作 Claude 拥有直接访问权限来审视。

同时检查错误是如何报告的。好的工具会把清晰的错误信息作为结果返回，而不是直接抛出异常，这样 Claude 才能自行恢复。

工具插件与 MCP 服务器有何不同？#

MCP 服务器是为 Claude 提供工具的标准方式，可以在众多客户端中使用。工具插件的适用范围更窄：它只能在 Claude Code 中使用，但除了插件本身之外不需要额外的安装步骤，会随会话一起启动，还能与插件的其他部分共享状态，例如用一条状态栏显示这个工具被使用的频率。