企业官网建设流程全解析

goose 如何启用 tool shim 让不支持原生工具调用的模型正常执行工具？

【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose

当你用 goose 搭配某些不支持原生工具调用（tool calling）的模型时，会碰到一个典型现象：模型嘴上说要调用某个工具，但 goose 并没有真正执行它——它把工具调用以纯文本的形式打印出来了，例如functions.shell:0 <|tool_call_argument_begin|> {...}。goose 提供的tool shim就是为这种情况设计的：它拦截模型返回的文本形式工具调用，转写成 goose 可执行的规范化 tool call，从而让这类模型也能正常驱动 agent 执行动作。tool shim 目前是实验性功能，配置项和行为在未来版本中可能变化（见 Tool Shim 指南）。

上图是官方文档给出的 toolshim 工作示意（文档示例）：主模型负责生成回复和（文本形式的）工具调用，本地运行的一个小模型负责把这段输出转成结构化tool_calls，最后交给 goose 执行。

什么情况下需要启用 tool shim

按 Tool Shim 指南 的说法，出现以下任一情况时就该启用它：

• 会话进行到一半工具突然不生效——模型调用了工具但 goose 没有执行；
• 模型输出functions.shell:0 <|tool_call_argument_begin|> {...}这类纯文本，而不是走工具 API；
• 你在使用不支持原生工具调用的本地模型（Ollama、llama.cpp）；
• 你的 OpenAI 兼容 provider 路由到会把推理标签（think）与工具调用混在一起的模型，导致解析失败。

文档指出：大多数本地部署的模型，以及一些没有针对结构化 tool calling 做过微调的云端模型，都会需要这个 shim。

工作原理：shim 依赖一个独立的解释模型

shim 会拦截模型响应，把其中的文本工具调用格式转换为结构化 tool call。它需要一个单独的解释（interpreter）模型，默认使用 Ollama 来承载。这个解释模型与你主对话用的 provider 相互独立——无论你的主模型跑在 Bedrock、自建路由还是任何 OpenAI 兼容端点上，shim 都可以本地用 Ollama 做解释。

主路径：用 Ollama 作为解释后端（默认）

这是文档给出的默认配置，前提是Ollama 已安装并在运行。

第 1 步：拉取默认的解释模型。默认解释模型是mistral-nemo：

ollama pull mistral-nemo

第 2 步：启用 shim 并启动 goose：

export GOOSE_TOOLSHIM=true GOOSE_TOOLSHIM=true goose session

启动后模型输出中若出现文本形式的工具调用，shim 会将其转成结构化调用执行。如果想换解释模型，用GOOSE_TOOLSHIM_OLLAMA_MODEL覆盖：

export GOOSE_TOOLSHIM_OLLAMA_MODEL=llama3.2

如果主对话用的是自定义 OpenAI 兼容 provider，同样适用——shim 始终在本地走 Ollama，与主 provider 无关：

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

可选路径：用 goose 内置本地推理作为解释后端

如果你的 goose 本身就是跑在内置本地推理后端上，可以直接用它当解释器，不必另起一个 Ollama 实例。此时模型名是必填项——设置GOOSE_TOOLSHIM_MODEL或配置文件中的LOCAL_LLM_MODEL配置键，否则 goose 会在启动时报错：

export GOOSE_TOOLSHIM_BACKEND=local export GOOSE_TOOLSHIM_MODEL=<你的本地模型名>

<你的本地模型名>需替换为你实际加载的模型名（文档示例写作my-model-name）。GOOSE_TOOLSHIM_BACKEND的合法取值为ollama（默认）、local、llama.cpp。

一次性带环境变量启动的完整示例：

GOOSE_TOOLSHIM=true \ GOOSE_TOOLSHIM_BACKEND=local \ GOOSE_TOOLSHIM_MODEL=<你的本地模型名> \ goose session

环境变量参考

完整变量对照见 environment-variables 文档：

另外，这些开关也可以写进config.yaml而不是导出环境变量。config-files 文档的全局设置表中列出了GOOSE_TOOLSHIM（true/false，默认 false）和GOOSE_TOOLSHIM_OLLAMA_MODEL，示例配置中对应的写法是：

GOOSE_TOOLSHIM: true

结果验证与常见问题排查

文档给出的判断与排查顺序如下：

shim 已启用但工具仍不执行——先确认解释后端可达：

• Ollama 后端：运行ollama list，确认 Ollama 在运行、解释模型已拉取；
• Local 后端：确认本地推理已配置且设置了模型（GOOSE_TOOLSHIM_MODEL或LOCAL_LLM_MODEL），未设置时启动会直接失败，这本身就是一种快速反馈。

会话中途工具突然失效——可能是模型从原生工具调用切换到了文本格式。启用GOOSE_TOOLSHIM=true并重启会话即可，这也是 Ollama 实验文档给出的快速开始路径。

解释调用太慢——换一个更小更快的 Ollama 模型：

export GOOSE_TOOLSHIM_OLLAMA_MODEL=qwen2.5:3b

模型在工具调用前输出推理内容（think标签）——部分推理模型会把 thinking 标签和工具调用混排导致解析失败。shim 会自动处理这种情况：启用后推理内容会从最终消息中剥离，无需额外配置。

限制

• tool shim 是实验性功能，配置选项与行为在未来版本中可能变化；
• 解释模型独立于主对话模型，Ollama 后端要求本机有可用且已拉取的解释模型；
• local 后端下缺少模型名设置时，启动会失败而不是回退到其他后端。

更多背景（包括为什么需要 toolshim、以及团队对解释模型微调的规划）见 Finetuning Toolshim Models 博客，操作细节始终以 Tool Shim 指南 为准。

【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose