goose Ollama 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 的实验特性 Ollama Tool Shim它解决本地模型不支持原生工具调用、或偶发以纯文本形式输出工具请求的问题。读完本篇你将掌握完整的启用步骤与全部环境变量配置并理解 goose 源码中直接解析 → 内联 JSON 解析 → 解释器模型兜底的三段式工具调用恢复管线以及 Ollama 与内置 llama.cpp 两种解释器后端的实现差异。需要预先说明Tool Shim 是一个实验性功能文档明确提示其行为与配置项可能在未来版本中变化见 experimental/ollama.md。什么是 Ollama Tool Shim何时需要启用goose 的工具shell、文件读写等 MCP 工具默认依赖模型原生的 function calling 能力模型通过 API 的结构化字段返回工具调用。但很多本地模型尤其是经由 Ollama、llama.cpp 运行的模型并不支持这种机制或者行为不稳定典型症状包括会话中途工具突然失效——模型调用了工具但 goose 没有执行模型输出的是纯文本工具格式例如functions.shell:0 |tool_call_argument_begin| {...}这样的标记串而不是 API 结构化的 tool call推理模型把思考标签think标记和工具调用混在一起输出导致解析失败。启用 Tool Shim 后shim 会拦截模型响应把上述文本形式的工具请求转换成 goose 可执行的结构化工具调用。核心机制是引入一个解释器模型interpreter model它独立于你主对话使用的任何 provider可以是 Ollama、llama.cpp 内置推理专门负责从文本中读懂工具调用意图。完整的使用与排查指南见 guides/tool-shim.md。快速开始官方文档给出的最小路径只有三步安装并启动 Ollama拉取默认解释器模型mistral-nemoollama pull mistral-nemo启用 shim 启动 gooseGOOSE_TOOLSHIMtrue goose session其中mistral-nemo是源码中写死的默认解释器模型定义于 toolshim.rs/// Default model to use for tool interpretation pub const DEFAULT_INTERPRETER_MODEL_OLLAMA: str mistral-nemo;工作原理工具调用的三段式恢复管线从源码 augment_message_with_tool_calls 的实现看每条助手消息进入 shim 后按以下优先级逐级处理只有前两级都没命中时才调用解释器模型第一段tokenized 标记直接解析。很多模型的文本工具输出带有固定的特殊标记shim 用一组常量识别它们toolshim.rsconst TOOL_CALLS_SECTION_BEGIN: str |tool_calls_section_begin|; const TOOL_CALLS_SECTION_END: str |tool_calls_section_end|; const TOOL_CALL_BEGIN: str |tool_call_begin|; const TOOL_CALL_ARGUMENT_BEGIN: str |tool_call_argument_begin|; // ...解析器支持两种写法标准的name |tool_call_argument_begin| {json}以及省略参数标记的name {json}。工具名解析还做了大量容错——去掉:0序号、functions.前缀把.映射成 goose 工具命名约定的__并在多个候选名中匹配真实工具列表见 resolve_tool_name。第二段内联 JSON 解析。有些模型直接输出形如{name: shell, arguments: {...}}的 JSON 指令常伴随Using tool:前缀。shim 用括号配对扫描提取第一个 JSON 对象并做同样容错解析parse_inline_json_tool_calls解析成功后会清理掉文本中残留的 JSON 工具指令避免泄漏到最终回复。第三段解释器模型兜底。前两段都未命中时消息文本连同当前可用工具列表一起发给解释器模型由后者按固定 JSON Schema 输出{tool_calls: [{name, arguments}]}若模型判断没有工具调用则返回名为noop的空调用shim 会过滤掉noop。解析完成后无论是否成功消息都会经过sanitize_residual_markers清洗保证原始标记|tool_call_begin|等不会出现在用户可见的最终输出里。单元测试 crates/goose/src/providers/toolshim.rs 中的 tests 模块 覆盖了这些路径tokenized 标记解析、内联 JSON 解析、Windows 反斜杠路径参数的 JSON 容错、以及直接解析优先于解释器的优先级验证。安全细节execute 别名只允许确定的 shell 转换部分模型会用execute/execute_code这类泛化工具名包裹Developer.shell({ command: ... })形式的 TypeScript 代码。shim 会用 tree-sitter 对这段代码做真实语法解析仅在唯一且明确匹配Developer.shell单参命令时才转换为 goose 的 shell 工具调用maybe_convert_execute_to_shell_tool_call。一旦出现多个 shell 调用、动态参数、额外参数、字符串/注释/正则里的诱饵文本解析直接拒绝并把整条消息内容清空rejected_execute宁可放弃执行也不猜测。相关拒绝用例集中在augment_does_not_interpret_rejected_execute_marker测试中值得作为该设计意图的证据参考。环境变量与配置参考变量说明默认值GOOSE_TOOLSHIM启用 tool shimtrue或1falseGOOSE_TOOLSHIM_BACKEND解释器后端ollama、local或llama.cppollamaGOOSE_TOOLSHIM_OLLAMA_MODELOllama 解释器模型mistral-nemoGOOSE_TOOLSHIM_MODEL本地解释器后端的模型名使用local后端且未设置LOCAL_LLM_MODEL配置时必填—几个源码中可确认的细节可以帮你排配置问题布尔值解析很宽容global_toolshim() 读取GOOSE_TOOLSHIMparse_bool_config 接受1 / true / yes / on小写不敏感为真值0 / false / no / off为假值其余取值直接报错。backend 取值同样容错parse_toolshim_backend 除文档列出的ollama/local/llama.cpp外还接受llama_cpp和空串视为 ollama。本地后端模型名有明确的优先级resolve_local_interpreter_model 先取环境变量GOOSE_TOOLSHIM_MODEL再回退到全局配置键LOCAL_LLM_MODEL两者都为空时启动即报Local toolshim backend requires GOOSE_TOOLSHIM_MODEL or LOCAL_LLM_MODEL to be set。Ollama 地址来自统一配置解释器请求的 base URL 由OLLAMA_HOST配置决定默认localhost:11434ollama.rs解析逻辑见 get_ollama_base_url——未带协议会补http://未带端口会补 11434。诊断入口goose doctor也会检查该开关doctor.rs。三种典型使用组合Ollama 作为主 providerGOOSE_TOOLSHIMtrue goose session主对话与解释器都走本地 Ollama解释器默认mistral-nemo需要时可用GOOSE_TOOLSHIM_OLLAMA_MODEL覆盖。自定义 OpenAI 兼容 providerGOOSE_TOOLSHIMtrue \ GOOSE_TOOLSHIM_OLLAMA_MODELllama3.2 \ goose session主 provider 可以是任意 OpenAI 兼容服务Bedrock、自建路由等。shim 的解释器始终在本地 Ollama 上运行与主对话使用什么 provider 无关——这正是解释器模型独立于主 provider设计要带来的灵活性。内置本地推理后端llama.cpp如果你本来就在用 goose 的内置本地推理可以直接把它当解释器无需再起一个 Ollama 实例。注意此时必须指定模型名否则启动报错GOOSE_TOOLSHIMtrue \ GOOSE_TOOLSHIM_BACKENDlocal \ GOOSE_TOOLSHIM_MODELmy-model-name \ goose session对应实现 LocalInterpreter 会创建一个localprovider 并显式.with_toolshim(false)避免解释器自身再进入 shim 管线造成递归。解释器后端实现细节Ollama 后端使用 Ollama 的结构化输出能力post_structured 以非流式方式调用/api/chat并在请求体中注入固定 JSON Schemapayload[format]约束输出必须形如{ tool_calls: [ { name: tool_name, arguments: { param1: value1 } } ] }系统提示词明确要求检测到 JSON 格式的工具请求就转写为上述格式否则返回{tool_calls: [{name: noop, arguments: {}}]}interpret_to_tool_calls。为什么主模型收不到 tools 定义在 shim 模式下 goose 向模型传空的工具列表把工具说明改以文本形式写进系统提示词——modify_system_prompt_for_tool_json 会追加每个工具的Tool Name / Schema / Description与一次只调一个工具、按 JSON 格式告知要调用的工具的指令历史消息中的工具请求/响应也会由 convert_tool_messages_to_text 降级为纯文本因为部分 provider如 Bedrock会校验 tool_use/tool_result 块只能与工具定义共存。故障排查继承官方指南的四个高频问题1. 会话中途工具突然不工作。模型可能已从原生工具调用切换到文本格式。设置GOOSE_TOOLSHIMtrue并重启会话。2. shim 已启用但工具仍不执行。检查解释器后端可达性Ollama运行ollama list确认服务在跑、解释器模型已拉取Local确认本地推理已配置且模型名已设置环境变量或LOCAL_LLM_MODEL。3. 解释器调用太慢。换一个更小更快的解释器模型export GOOSE_TOOLSHIM_OLLAMA_MODELqwen2.5:3b4. 模型在工具调用前输出推理标签think标记导致解析失败。shim 会自动处理启用后推理内容会从最终消息中剥离。延伸阅读实验特性入口文档documentation/docs/experimental/ollama.md完整 Tool Shim 指南documentation/docs/guides/tool-shim.md核心实现crates/goose/src/providers/toolshim.rs配置解析crates/goose/src/model_config.rsOllama 默认地址常量crates/goose-providers/src/ollama.rs【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 goose Ollama Tool Shim 实战：让不支持函数调用的本地模型也能执行工具
goose Ollama 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 的实验特性 Ollama Tool Shim它解决本地模型不支持原生工具调用、或偶发以纯文本形式输出工具请求的问题。读完本篇你将掌握完整的启用步骤与全部环境变量配置并理解 goose 源码中直接解析 → 内联 JSON 解析 → 解释器模型兜底的三段式工具调用恢复管线以及 Ollama 与内置 llama.cpp 两种解释器后端的实现差异。需要预先说明Tool Shim 是一个实验性功能文档明确提示其行为与配置项可能在未来版本中变化见 experimental/ollama.md。什么是 Ollama Tool Shim何时需要启用goose 的工具shell、文件读写等 MCP 工具默认依赖模型原生的 function calling 能力模型通过 API 的结构化字段返回工具调用。但很多本地模型尤其是经由 Ollama、llama.cpp 运行的模型并不支持这种机制或者行为不稳定典型症状包括会话中途工具突然失效——模型调用了工具但 goose 没有执行模型输出的是纯文本工具格式例如functions.shell:0 |tool_call_argument_begin| {...}这样的标记串而不是 API 结构化的 tool call推理模型把思考标签think标记和工具调用混在一起输出导致解析失败。启用 Tool Shim 后shim 会拦截模型响应把上述文本形式的工具请求转换成 goose 可执行的结构化工具调用。核心机制是引入一个解释器模型interpreter model它独立于你主对话使用的任何 provider可以是 Ollama、llama.cpp 内置推理专门负责从文本中读懂工具调用意图。完整的使用与排查指南见 guides/tool-shim.md。快速开始官方文档给出的最小路径只有三步安装并启动 Ollama拉取默认解释器模型mistral-nemoollama pull mistral-nemo启用 shim 启动 gooseGOOSE_TOOLSHIMtrue goose session其中mistral-nemo是源码中写死的默认解释器模型定义于 toolshim.rs/// Default model to use for tool interpretation pub const DEFAULT_INTERPRETER_MODEL_OLLAMA: str mistral-nemo;工作原理工具调用的三段式恢复管线从源码 augment_message_with_tool_calls 的实现看每条助手消息进入 shim 后按以下优先级逐级处理只有前两级都没命中时才调用解释器模型第一段tokenized 标记直接解析。很多模型的文本工具输出带有固定的特殊标记shim 用一组常量识别它们toolshim.rsconst TOOL_CALLS_SECTION_BEGIN: str |tool_calls_section_begin|; const TOOL_CALLS_SECTION_END: str |tool_calls_section_end|; const TOOL_CALL_BEGIN: str |tool_call_begin|; const TOOL_CALL_ARGUMENT_BEGIN: str |tool_call_argument_begin|; // ...解析器支持两种写法标准的name |tool_call_argument_begin| {json}以及省略参数标记的name {json}。工具名解析还做了大量容错——去掉:0序号、functions.前缀把.映射成 goose 工具命名约定的__并在多个候选名中匹配真实工具列表见 resolve_tool_name。第二段内联 JSON 解析。有些模型直接输出形如{name: shell, arguments: {...}}的 JSON 指令常伴随Using tool:前缀。shim 用括号配对扫描提取第一个 JSON 对象并做同样容错解析parse_inline_json_tool_calls解析成功后会清理掉文本中残留的 JSON 工具指令避免泄漏到最终回复。第三段解释器模型兜底。前两段都未命中时消息文本连同当前可用工具列表一起发给解释器模型由后者按固定 JSON Schema 输出{tool_calls: [{name, arguments}]}若模型判断没有工具调用则返回名为noop的空调用shim 会过滤掉noop。解析完成后无论是否成功消息都会经过sanitize_residual_markers清洗保证原始标记|tool_call_begin|等不会出现在用户可见的最终输出里。单元测试 crates/goose/src/providers/toolshim.rs 中的 tests 模块 覆盖了这些路径tokenized 标记解析、内联 JSON 解析、Windows 反斜杠路径参数的 JSON 容错、以及直接解析优先于解释器的优先级验证。安全细节execute 别名只允许确定的 shell 转换部分模型会用execute/execute_code这类泛化工具名包裹Developer.shell({ command: ... })形式的 TypeScript 代码。shim 会用 tree-sitter 对这段代码做真实语法解析仅在唯一且明确匹配Developer.shell单参命令时才转换为 goose 的 shell 工具调用maybe_convert_execute_to_shell_tool_call。一旦出现多个 shell 调用、动态参数、额外参数、字符串/注释/正则里的诱饵文本解析直接拒绝并把整条消息内容清空rejected_execute宁可放弃执行也不猜测。相关拒绝用例集中在augment_does_not_interpret_rejected_execute_marker测试中值得作为该设计意图的证据参考。环境变量与配置参考变量说明默认值GOOSE_TOOLSHIM启用 tool shimtrue或1falseGOOSE_TOOLSHIM_BACKEND解释器后端ollama、local或llama.cppollamaGOOSE_TOOLSHIM_OLLAMA_MODELOllama 解释器模型mistral-nemoGOOSE_TOOLSHIM_MODEL本地解释器后端的模型名使用local后端且未设置LOCAL_LLM_MODEL配置时必填—几个源码中可确认的细节可以帮你排配置问题布尔值解析很宽容global_toolshim() 读取GOOSE_TOOLSHIMparse_bool_config 接受1 / true / yes / on小写不敏感为真值0 / false / no / off为假值其余取值直接报错。backend 取值同样容错parse_toolshim_backend 除文档列出的ollama/local/llama.cpp外还接受llama_cpp和空串视为 ollama。本地后端模型名有明确的优先级resolve_local_interpreter_model 先取环境变量GOOSE_TOOLSHIM_MODEL再回退到全局配置键LOCAL_LLM_MODEL两者都为空时启动即报Local toolshim backend requires GOOSE_TOOLSHIM_MODEL or LOCAL_LLM_MODEL to be set。Ollama 地址来自统一配置解释器请求的 base URL 由OLLAMA_HOST配置决定默认localhost:11434ollama.rs解析逻辑见 get_ollama_base_url——未带协议会补http://未带端口会补 11434。诊断入口goose doctor也会检查该开关doctor.rs。三种典型使用组合Ollama 作为主 providerGOOSE_TOOLSHIMtrue goose session主对话与解释器都走本地 Ollama解释器默认mistral-nemo需要时可用GOOSE_TOOLSHIM_OLLAMA_MODEL覆盖。自定义 OpenAI 兼容 providerGOOSE_TOOLSHIMtrue \ GOOSE_TOOLSHIM_OLLAMA_MODELllama3.2 \ goose session主 provider 可以是任意 OpenAI 兼容服务Bedrock、自建路由等。shim 的解释器始终在本地 Ollama 上运行与主对话使用什么 provider 无关——这正是解释器模型独立于主 provider设计要带来的灵活性。内置本地推理后端llama.cpp如果你本来就在用 goose 的内置本地推理可以直接把它当解释器无需再起一个 Ollama 实例。注意此时必须指定模型名否则启动报错GOOSE_TOOLSHIMtrue \ GOOSE_TOOLSHIM_BACKENDlocal \ GOOSE_TOOLSHIM_MODELmy-model-name \ goose session对应实现 LocalInterpreter 会创建一个localprovider 并显式.with_toolshim(false)避免解释器自身再进入 shim 管线造成递归。解释器后端实现细节Ollama 后端使用 Ollama 的结构化输出能力post_structured 以非流式方式调用/api/chat并在请求体中注入固定 JSON Schemapayload[format]约束输出必须形如{ tool_calls: [ { name: tool_name, arguments: { param1: value1 } } ] }系统提示词明确要求检测到 JSON 格式的工具请求就转写为上述格式否则返回{tool_calls: [{name: noop, arguments: {}}]}interpret_to_tool_calls。为什么主模型收不到 tools 定义在 shim 模式下 goose 向模型传空的工具列表把工具说明改以文本形式写进系统提示词——modify_system_prompt_for_tool_json 会追加每个工具的Tool Name / Schema / Description与一次只调一个工具、按 JSON 格式告知要调用的工具的指令历史消息中的工具请求/响应也会由 convert_tool_messages_to_text 降级为纯文本因为部分 provider如 Bedrock会校验 tool_use/tool_result 块只能与工具定义共存。故障排查继承官方指南的四个高频问题1. 会话中途工具突然不工作。模型可能已从原生工具调用切换到文本格式。设置GOOSE_TOOLSHIMtrue并重启会话。2. shim 已启用但工具仍不执行。检查解释器后端可达性Ollama运行ollama list确认服务在跑、解释器模型已拉取Local确认本地推理已配置且模型名已设置环境变量或LOCAL_LLM_MODEL。3. 解释器调用太慢。换一个更小更快的解释器模型export GOOSE_TOOLSHIM_OLLAMA_MODELqwen2.5:3b4. 模型在工具调用前输出推理标签think标记导致解析失败。shim 会自动处理启用后推理内容会从最终消息中剥离。延伸阅读实验特性入口文档documentation/docs/experimental/ollama.md完整 Tool Shim 指南documentation/docs/guides/tool-shim.md核心实现crates/goose/src/providers/toolshim.rs配置解析crates/goose/src/model_config.rsOllama 默认地址常量crates/goose-providers/src/ollama.rs【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考