Skip to Content
开发者指南工具简介

Qwen Code 工具

Qwen Code 内置了多种工具，模型可通过这些工具与你的本地环境交互、获取信息并执行操作。这些工具扩展了 CLI 的功能，使其不再局限于文本生成，还能协助完成各种任务。

Qwen Code 工具概览

在 Qwen Code 中，工具是指模型可以请求执行的特定函数或模块。例如，如果你要求模型“总结 my_document.txt 的内容”，它通常会识别出需要读取该文件，并请求执行 read_file 工具。

核心组件（packages/core）负责管理这些工具，向模型提供它们的定义（schema），在收到请求时执行工具，并将结果返回给模型，以便模型进一步处理并生成面向用户的响应。

这些工具提供以下能力：

  • 访问本地信息： 工具允许模型访问你的本地文件系统、读取文件内容、列出目录等。
  • 执行命令： 借助 run_shell_command 等工具，模型可以运行 shell 命令（需配合适当的安全措施和用户确认）。
  • 与 Web 交互： 工具可以从 URL 获取内容。
  • 执行操作： 工具可以修改文件、写入新文件或对你的系统执行其他操作（同样通常带有安全保护机制）。
  • 确保回答基于实际上下文： 通过使用工具获取实时或特定的本地数据，模型的回答可以更准确、更相关，并紧密贴合你的实际上下文。

如何使用 Qwen Code 工具

要使用 Qwen Code 工具，只需向 CLI 输入提示词。具体流程如下：

  1. 你向 CLI 输入提示词。
  2. CLI 将提示词发送给核心组件。
  3. 核心组件将你的提示词、对话历史以及可用工具列表及其描述/schema 一起发送给配置好的模型 API。
  4. 模型分析你的请求。如果判断需要调用工具，其响应将包含执行特定工具及相应参数的请求。
  5. 核心组件接收该工具请求，进行验证，并在（通常针对敏感操作需用户确认后）执行该工具。
  6. 工具的输出结果被发送回模型。
  7. 模型利用工具的输出结果组织最终回答，该回答随后通过核心组件返回给 CLI 并展示给你。

你通常会在 CLI 中看到相关消息，提示工具何时被调用以及调用成功或失败的状态。

安全与确认机制

许多工具（尤其是那些可能修改文件系统或执行命令的工具，如 write_file、edit、run_shell_command）在设计时都充分考虑了安全性。Qwen Code 通常会：

  • 要求确认： 在执行潜在的敏感操作前向你发出提示，明确展示即将执行的操作。
  • 使用沙箱隔离： 所有工具均受沙箱机制的限制（参见 Qwen Code 中的沙箱机制）。这意味着在沙箱环境中运行时，你希望使用的任何工具（包括 MCP 服务器）都必须存在于沙箱环境_内部_。例如，若要通过 npx 运行 MCP 服务器，则 npx 可执行文件必须安装在沙箱的 Docker 镜像中，或在 sandbox-exec 环境中可用。

在允许工具继续执行前，务必仔细审阅确认提示。

深入了解 Qwen Code 工具

Qwen Code 的内置工具大致可分为以下几类：

  • 文件系统工具： 用于与文件和目录交互（读取、写入、列出、搜索等）。
  • Shell 工具（run_shell_command）： 用于执行 shell 命令。
  • Web 抓取工具（web_fetch）： 用于从 URL 获取内容。
  • Web 搜索工具（web_search）： 用于搜索互联网。
  • 多文件读取工具（read_many_files）： 专用于从多个文件或目录读取内容的工具，通常由 @ 命令调用。
  • 记忆工具（save_memory）： 用于跨会话保存和回忆信息。
  • Todo 写入工具（todo_write）： 用于在编码会话中创建和管理结构化任务列表。
  • 任务工具（task）： 用于将复杂任务委派给专门的子代理（subagent）。
  • 退出计划模式工具（exit_plan_mode）： 用于退出计划模式并进入实现阶段。

此外，这些工具还结合了以下机制：

  • MCP 服务器：MCP 服务器充当模型与你的本地环境或其他服务（如 API）之间的桥梁。
  • 沙箱机制：沙箱将模型及其产生的更改与你的环境隔离，以降低潜在风险。
Last updated on
Java SDK（Alpha）文件系统