goose3/goose Tool Shim 使用指南:让不具备原生工具调用能力的 LLM 也能稳定执行工具

原创2026-09-08 21:32:231,674 阅读
文章标签:人工智能AI 应用AI Agent交互助手工具调用MCP Clients本地部署桌面应用CLI代码智能体Agent 工作流

goose3/goose Tool Shim 使用指南:让不具备原生工具调用能力的 LLM 也能稳定执行工具

Tool Shim(工具垫片)是 goose3/goose 提供的一项实验性能力,用于解决"模型没有原生 function calling,或偶发把工具调用输出成纯文本"导致的工具失效问题。本指南基于仓库文档 tool-shim.md,并结合 toolshim.rs 源码实现,完整讲解启用场景、工作原理、Ollama 与本地推理两种后端配置、环境变量与故障排查,读完即可在本地模型或自定义 OpenAI 兼容 Provider 上让 goose 稳定执行工具调用。

:::warning 实验性功能 Tool shim 是实验性功能,配置项与行为可能在后续版本中变化,升级 goose 后请留意 RELEASE.md 与文档变更。 :::

为什么需要 Tool Shim

主流云模型通常原生支持结构化工具/函数调用(tool calling),但相当一部分模型并非如此:

  • 本地模型(如通过 Ollama、llama.cpp 部署的模型)大多没有针对结构化工具调用做过指令微调;
  • 部分云模型偶尔会在会话中途"退化",把本该走工具 API 的请求以纯文本形式输出;
  • 带推理能力的模型(输出 <think> 推理标签)会把推理内容与工具调用混在一起,导致普通解析器失败。

当出现以下现象时,说明模型可能已经切换到文本格式输出工具调用,而 goose 无法直接执行:

  • 会话中途工具突然失效——模型明明调用了工具,goose 却没有执行;
  • 模型输出形如 functions.shell:0 <|tool_call_argument_begin|> {...} 的纯文本,而不是走工具 API;
  • 使用的本地模型(Ollama、llama.cpp)本身不支持原生工具调用;
  • 自定义 OpenAI 兼容 Provider 路由到会混用 <think> 推理标签与工具调用的模型,引发解析失败。

Tool Shim 正是为此设计:它检测这些基于文本的工具调用格式,并将其转换为 goose 可以执行的结构化工具调用。

工作原理:拦截、转译、回填

从源码模块注释(toolshim.rs)可以看到完整的数据流:

  1. 拿到任意 LLM 的文本输出;
  2. 将其交给一个独立的 interpreter model(解释器模型);
  3. 由解释器模型从文本中提取工具调用意图,输出为合适的格式(工具名 + JSON 参数);
  4. 把解释器模型的输出转换为 goose 的标准工具调用结构(CallToolRequestParams);
  5. 将解析出的工具调用回填(augment)到原始 assistant 消息上,随后 goose 照常执行。

ToolInterpreter trait 是整条链路的抽象核心(toolshim.rs),目前提供两种实现:

  • OllamaInterpreter:调用 Ollama 的 /api/chat 结构化输出接口;
  • LocalInterpreter:调用 goose 内置的 llama.cpp/本地推理后端。

关键点:解释器模型与主对话模型相互独立

Shim 需要一个单独的解释器模型,默认使用本地 Ollama。解释器模型与主对话使用哪个 Provider 完全无关——即使主对话走 Bedrock、自定义路由器或任何云服务,解释器仍可以在本地 Ollama 上运行(这也是它能给无原生工具调用能力模型"补课"的原因)。

实际调用发生时,goose 把解释器系统提示词设计为"若检测到 JSON 格式的工具请求,就按 {"tool_calls": [{"name": "...", "arguments": {...}}]} 输出;否则返回 noop 空调用"(见 toolshim.rs)。Ollama 后端还会附带一份严格 JSON Schema(要求 tool_calls 数组且每项必含 name 与 arguments,见 toolshim.rs),从而拿到完全可机读的结构化输出。

不依赖解释器也能识别的文本格式

在真正把文本交给解释器之前,augment_message_with_tool_calls(toolshim.rs)会先尝试本地直接解析常见的两类文本格式,命中即无需额外的解释器往返:

  1. 令牌化标记格式:由 <|tool_calls_section_begin|>、<|tool_call_begin|>、<|tool_call_argument_begin|>、<|tool_call_argument_end|>、<|tool_call_end|>、<|tool_calls_section_end|> 等标记包裹的工具调用块(常量定义见 toolshim.rs);
  2. 内联 JSON 格式:散落在文本中的 {"name": "...", "arguments": {...}} JSON 对象。

解析出的工具名还会经过一层名称归一化:resolve_tool_name(toolshim.rs)会去掉 functions. 前缀、去掉 :0 这类序号、并尝试把点号换成 goose 工具命名常用的双下划线(__),逐一与 goose 当前注册的工具清单比对,提升"模型随口写出的名字"与实际工具的匹配率。

兜底与清理

  • 无论解析是否成功,凡是离开 shim 管线的消息都会执行 sanitize_residual_markers(toolshim.rs)作兜底清理,把残留的 <|...|> 标记、Using tool: 指令等从最终输出中剥离,避免把"脏文本"呈现给用户;
  • 在 agent 侧(reply_parts.rs),若 shim 增强失败,只记录 warning 并跳过工具增强,同时做标记清理,不会让整个会话崩溃。

配置方法

1. 开启 Tool Shim

export GOOSE_TOOLSHIM=true

注意:GOOSE_TOOLSHIM 的取值不仅支持 true,也支持 1、yes、on 等布尔表达——goose 在解析配置时统一按 YAML 布尔处理(见 model_config.rs 与 model_config.rs)。

2. Ollama 后端(默认)

默认解释器模型是 mistral-nemo(源码中的默认常量见 toolshim.rs)。使用前需要保证 Ollama 已安装并运行,且本地已拉取该模型:

# 拉取默认解释器模型
ollama pull mistral-nemo

# 可选:换用其他解释器模型
export GOOSE_TOOLSHIM_OLLAMA_MODEL=llama3.2

Ollama 的地址会复用 goose 现有的 Ollama 配置(如 OLLAMA_HOST),未配置时使用默认地址与端口;HTTP 客户端超时使用 Provider 通用默认值(参见 toolshim.rs)。若设置了空的 GOOSE_TOOLSHIM_OLLAMA_MODEL,goose 会直接报错而不是静默忽略(见 model_config.rs)。

3. Local 后端(llama.cpp / 内置本地推理)

如果你本身就在用 goose 的内置本地推理后端,可以让它兼任解释器,而无需再单独跑一个 Ollama 实例:

export GOOSE_TOOLSHIM_BACKEND=local
export GOOSE_TOOLSHIM_MODEL=my-model-name

GOOSE_TOOLSHIM_BACKEND 合法取值:ollama(默认)、local、llama.cpp。

使用 Local 后端时必须指定模型,二选一:

  • 环境变量 GOOSE_TOOLSHIM_MODEL;
  • 配置文件中的 LOCAL_LLM_MODEL 配置键。

解析逻辑是"环境变量优先、配置兜底",两者都未设置时启动即报错(源码见 toolshim.rs)。报错信息会明确提示需要设置二者之一。

环境变量一览

变量 说明 默认值
GOOSE_TOOLSHIM 开启 Tool Shim(true 或 1) false
GOOSE_TOOLSHIM_BACKEND 解释器后端:ollama、local 或 llama.cpp ollama
GOOSE_TOOLSHIM_OLLAMA_MODEL 用作解释器的 Ollama 模型 mistral-nemo
GOOSE_TOOLSHIM_MODEL Local 解释器后端的模型名(使用 local 后端且配置中未设 LOCAL_LLM_MODEL 时必填) —

这些变量会同时进入 goose 的 Provider 环境变量注册表与模型配置解析(见 init.rs),因此在 goose session 之外,ACL/桌面端 UI 等入口也能读取同一份配置(configUtils.ts 同样引用了该变量)。

三种实战配置示例

场景一:Ollama 同时作为主 Provider 与解释器

GOOSE_TOOLSHIM=true goose session

默认使用 mistral-nemo 作为解释器。如需要,用 GOOSE_TOOLSHIM_OLLAMA_MODEL 覆盖解释器模型。

场景二:自定义 OpenAI 兼容 Provider + 本地 Ollama 解释器

GOOSE_TOOLSHIM=true \
GOOSE_TOOLSHIM_OLLAMA_MODEL=llama3.2 \
goose session

主 Provider 可以是任意服务(Bedrock、自定义路由器等)。无论主对话连的是哪家服务,shim 都使用本地 Ollama 承担解释任务——这正是为"无原生工具调用能力的模型"或"混用推理标签导致解析失败的路由模型"补足能力的典型用法。

场景三:内置本地推理(llama.cpp)担任解释器

GOOSE_TOOLSHIM=true \
GOOSE_TOOLSHIM_BACKEND=local \
GOOSE_TOOLSHIM_MODEL=my-model-name \
goose session

使用 goose 内置的 llama.cpp 后端作为解释器,无需额外 Ollama 进程。注意 GOOSE_TOOLSHIM_MODEL(或配置中的 LOCAL_LLM_MODEL)为必填,未设置则启动失败。

故障排查(Troubleshooting)

症状一:会话中途工具突然不执行

模型可能已从原生工具调用切换到了文本格式。开启 GOOSE_TOOLSHIM=true 并重启会话即可让 shim 接管这类文本格式。

症状二:shim 已开启但工具仍不执行

检查解释器后端是否可达:

  • Ollama:运行 ollama list 确认 Ollama 正在运行且解释器模型已拉取;
  • Local:确认本地推理已正确配置,且已设置模型名。

此外可确认解释器返回的是否为合法 JSON(Ollama 后端会把解释器请求与响应完整打印到 tracing 日志,关键字为 Tool interpreter payload / Tool interpreter response,便于排查,见 toolshim.rs)。

症状三:解释器调用速度慢

每条工具意图的转译都依赖解释器模型额外推理一次,模型越大延迟越高。换一个更小更快的 Ollama 模型:

export GOOSE_TOOLSHIM_OLLAMA_MODEL=qwen2.5:3b

症状四:模型在工具调用前输出推理内容(<think> 标签)

部分推理模型会把思维标签与工具调用混在一起,导致普通解析失败。Tool Shim 会自动处理这类输出——开启后,推理内容会从最终消息中被剥离,不会把思维过程呈现给用户。

更深入:与 goose 其他能力的关系

  • 工具调用前置文本化:当某 Provider(如 Bedrock)不允许在无工具定义时传递 tool_use/tool_result 块时,convert_tool_messages_to_text(toolshim.rs)会把历史工具请求/响应转成文本消息回填,保证 shim 模式下上下文仍然完整;
  • 执行类工具的兼容:shim 对 execute/execute_code 这类工具做了特殊处理——若模型用它们包了一层调用 Developer.shell({...}) 的 TypeScript 代码,shim 会用 tree-sitter 解析这段代码,还原成真正的 shell 工具调用(见 toolshim.rs),解析不出安全命令时会直接拒绝而不是盲目执行;
  • 测试保障:模块内置了完整的单测,覆盖后端取值解析、Local 模型解析优先级、令牌化工具调用解析、execute 别名到 shell 的转换等(见 toolshim.rs),可据此了解各类文本格式的预期解析结果。

想进一步了解内置本地推理后端的模型配置,可阅读 ollama.md 与 local-inference 相关文档;若需要在桌面端配置,参考 config-files.md。

登录后查看全文
goose