goose3/goose Tool Shim 使用指南:让不具备原生工具调用能力的 LLM 也能稳定执行工具
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)可以看到完整的数据流:
- 拿到任意 LLM 的文本输出;
- 将其交给一个独立的 interpreter model(解释器模型);
- 由解释器模型从文本中提取工具调用意图,输出为合适的格式(工具名 + JSON 参数);
- 把解释器模型的输出转换为 goose 的标准工具调用结构(
CallToolRequestParams); - 将解析出的工具调用回填(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)会先尝试本地直接解析常见的两类文本格式,命中即无需额外的解释器往返:
- 令牌化标记格式:由
<|tool_calls_section_begin|>、<|tool_call_begin|>、<|tool_call_argument_begin|>、<|tool_call_argument_end|>、<|tool_call_end|>、<|tool_calls_section_end|>等标记包裹的工具调用块(常量定义见 toolshim.rs); - 内联 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。