高级
高级配置¶
旧版 OpenAI 兼容模式
Warning
在此模式下,工具调用不可靠。 仅当代理需要 OpenAI 格式,并且你不依赖原生工具调用时使用它。
对于位于 /v1/chat/completions 后面的代理,请显式设置 api: "openai-completions":
{
models: {
providers: {
ollama: {
baseUrl: "http://ollama-host:11434/v1",
api: "openai-completions",
injectNumCtxForOpenAICompat: true, // default: true
apiKey: "ollama-local",
models: [...]
}
}
}
}
此模式可能不支持同时使用流式和工具调用;你可能需要在 models.providers.ollama.models 中的模型上设置 params: { streaming: false }。你也可以在 agents.defaults.models["ollama/<model>"].params 下设置它。对于 openai-completions,这会向上游发送 stream: false,并返回完整回复及其用量、推理和工具调用。未设置时流式保持启用;此设置不会更改原生 Ollama /api/chat 请求。
在此模式下,OpenClaw 默认注入 options.num_ctx,以免 Ollama 静默回退到 4096 个 token 的上下文。如果你的代理拒绝未知的 options 字段,请禁用它:
上下文窗口
对于自动发现的模型,OpenClaw 使用 /api/show 报告的上下文窗口,包括来自自定义 Modelfile 的更大 PARAMETER num_ctx 值;否则回退到 OpenClaw 默认的 Ollama 上下文窗口。
每个模型的 contextWindow 声明原生窗口元数据,每个模型的 contextTokens 限制活动输入。提供商级别的 maxTokens 仍然是输出 token 默认值;模型条目可以覆盖它。原生 /api/chat 请求首先从正的 params.num_ctx 设置 options.num_ctx,然后(如果存在)从生效模型的 contextTokens 设置。本地发现通常将 contextTokens 限制在 32,768(或模型更小的原生窗口),因此即使没有显式 params.num_ctx,OpenClaw 也可以覆盖更小的 Modelfile 上下文。无效、零、负数或非有限 params.num_ctx 值会被忽略。只有当这两个值都不可用时,Ollama 才会选择其自身的模型、Modelfile、OLLAMA_CONTEXT_LENGTH 或基于 VRAM 的默认值;原生适配器不会直接回退到所声明的 contextWindow。升级旧配置后,运行 openclaw doctor --fix。Doctor 会保留当前 contextTokens 上限,而不会创建更强的模型或提供商 num_ctx 固定值;未设上限的旧版原生条目仍会迁移其旧的上下文预算。现有显式 params.num_ctx 值仍然具有权威性,包括旧版 Doctor 已写入的固定值。检查或移除过大的现有固定值,以便再次由 contextTokens 驱动请求。使用 params.num_ctx 显式覆盖原生请求上下文。OpenAI 兼容适配器仍默认从 params.num_ctx 注入 options.num_ctx,然后从匹配模型条目的 contextTokens 或 contextWindow 注入;如果上游拒绝 options,请使用 injectNumCtxForOpenAICompat: false 禁用。
原生模型条目还接受 params 下的常见 Ollama 运行时选项,并作为原生 /api/chat 的 options 转发:num_keep、seed、num_predict、top_k、top_p、min_p、typical_p、repeat_last_n、temperature、repeat_penalty、presence_penalty、frequency_penalty、stop、num_batch、num_gpu、main_gpu、use_mmap 和 num_thread。运行时采样控制(temperature、topP、frequencyPenalty、presencePenalty 和 seed)会覆盖匹配的模型默认值,包括显式零值。Gateway 的 Chat Completions API 将 top_p、frequency_penalty 和 presence_penalty 映射到这些控制项。当 temperature: 0 时,OpenClaw 在应用覆盖后仍会将 top_p 规范化为 1,用于贪心采样。少数键(format、keep_alive、truncate、shift)作为顶层请求字段转发,而不是嵌套的 options。本地原生聊天请求默认使用 truncate: false 和 shift: false,因此支持的服务器会拒绝溢出输入,而不是静默丢弃历史。然后 OpenClaw 会尝试压缩并重试,或报告失败。填满窗口的生成仍可能产生带标记的部分回复。此行为已在 Ollama 0.33.3 上验证;旧版服务器可能会忽略这些字段。显式的每个模型值会覆盖这些默认值。托管模型和 OpenAI 兼容端点保持其现有行为。OpenClaw 仅转发这些 Ollama 请求键,因此仅运行时参数(如 streaming)永远不会发送到 Ollama。使用 params.think(或 params.thinking)设置顶层 think;false 会禁用 Qwen 风格思考模型的 API 级思考。
每个模型的 agents.defaults.models["ollama/<model>"].params.num_ctx 也有效;如果两者都设置,显式提供方模型条目优先。
思考控制
原生本地 Ollama 压缩摘要默认关闭思考。这可避免摘要使用其默认的三分钟请求窗口进行推理;Qwen3.5 将 low 视为启用思考,而不是降低思考预算。显式的 agents.defaults.compaction.thinkingLevel 会覆盖此偏好。现有的每个模型的 params.think/params.thinking 设置保持其正常优先级。托管路由保留其压缩默认值。
OpenClaw 会按 Ollama 期望的方式转发思考:顶层 think,而不是 options.think。其 /api/show 报告了 thinking 能力的自动发现模型会暴露 /think low、/think medium、/think high 和 /think max;非思考模型仅暴露 /think off。当 /api/show 还报告 thinking.values 时,发现机制会缓存模型特定的映射。布尔型模型发送 false 或 true;分级模型发送其支持的强度字符串。已声明的 xhigh 也可通过 /think xhigh 和 --thinking xhigh 使用。
现有选择会使用 OpenClaw 共享的思考等级阶梯映射到最近的支持档位。例如,声明支持 low、medium 和 xhigh 的模型,在高和最大时会收到 xhigh。如果模型无法关闭思考,关闭档会使用其最低支持档位。OpenClaw 保留其现有的关闭默认值,而不是采用 thinking.default。发现机制会随模型元数据缓存这些映射;轮次不会再次获取它们。
在重放助手消息时,原生请求会将其可用的推理保留在 Ollama 独立的 thinking 字段中,与文本和工具调用并列。这使工具后续操作能够复用由会话历史策略保留的推理,而不会将其混入可见的回答文本中。
openclaw agent --model ollama/gemma4 --thinking off
openclaw agent --model ollama/gemma4 --thinking low
或设置模型默认值:
每个模型的 params.think/params.thinking 可以为特定模型禁用或强制 API 思考。当当前运行仅有隐式的 off 默认值时,OpenClaw 会保留该显式配置;非 off 的运行时命令(例如 /think medium)仍会覆盖它。标记为 reasoning: false 的模型会抑制已启用的运行时选择。但是,强制思考模型对于关闭档或已配置的 false 仍会使用其最低支持档位,即使其可见性被禁用,也会将推理排除在回答之外。
模型成本
Ollama 在本地运行且免费,因此自动发现和手动定义的模型的所有模型成本均为 0。
内存嵌入
内置的 Ollama 插件会为 内存搜索 注册一个内存嵌入提供方。它使用已配置的 Ollama 基础 URL 和 API 密钥,调用 /api/embed,并在可能时将多个内存块批量合并为一个 input 请求。
当 proxy.enabled=true 时,发往由已配置 baseUrl 派生的精确主机本地回环源地址的嵌入请求会使用 OpenClaw 的受保护直连路径,而不是受管正向代理。已配置的主机名本身必须是 localhost 或回环 IP 字面量——仅解析到回环的 DNS 名称仍会使用受管代理路径。局域网、tailnet、私有网络和公共 Ollama 主机始终保持在受管代理路径上,重定向到其他主机/端口不会继承信任。proxy.loopbackMode: "proxy" 仍会将回环流量通过代理路由;proxy.loopbackMode: "block" 会在连接前拒绝它——参见 受管代理。
| 属性 | 值 |
|---|---|
| 默认模型 | nomic-embed-text |
| 自动拉取 | 否;请先在 Ollama 主机上拉取模型 |
| 嵌入并发 | 由提供方管理;无需 memory-search 调优键 |
在索引内存之前,请在已配置的 Ollama 主机上运行 ollama pull nomic-embed-text(或拉取由 memory.search.model 选择的模型)。缺失的模型会返回 HTTP 404;OpenClaw 不会自动下载它。
查询时的嵌入会使用检索前缀,适用于需要或建议使用检索前缀的模型:nomic-embed-text、qwen3-embedding 和 mxbai-embed-large。文档批次保持原始状态,因此现有索引无需格式迁移。
嵌入并发和批处理行为由 Ollama 内存提供方管理。对于远程嵌入主机,请使用支持的 remote.baseUrl 和 remote.apiKey 字段,将身份验证范围限定到该主机:
流式配置
Ollama 默认使用 **原生 API**(`/api/chat`),它同时支持流式传输和工具调用——无需特殊配置。
与 Chat Completions 类似,原生 Ollama 会保留持久回复块,直到消息完成时已知文本阶段,即使设置了 `blockStreamingBreak: "text_end"`。工具叙述不会出现在回复中;普通最终回复和长度受限的回答仍可投递。启用时,独立的实时预览仍可以更新。
参见 [待处理文本阶段](../../concepts/streaming.md#pending-text-phases)。
对于原生请求,/think off、openclaw agent --thinking off 以及插件 api.runtime.llm.complete({ reasoning: "off" }) 调用会发送顶层 think: false,除非已配置显式的 params.think/params.thinking,或发现报告某个模型无法禁用思考。省略 reasoning 的直接补全会保留模型默认值。在没有发现思考描述符的情况下,/think low|medium|high 会发送对应的 effort 字符串。已验证支持完整 effort 的 Ollama Cloud 系列,例如 GLM 5.2、GLM 5.3、GLM 5.3 Flash、Kimi K3、DeepSeek V4 和 DeepSeek V4.1 Flash,对于 /think max 也会发送原生 think: "max";其他模型和本地服务器保持兼容的 think: "high" 映射。原生 max 适用于 ollama-cloud 提供商,以及 base URL 为 https://ollama.com 的任何 ollama 提供商。通过本地 Ollama 服务器访问的 :cloud 模型保持 high,因为 Ollama 0.21.2 及更早版本会拒绝 max。
Ollama Cloud 上的 GLM 5.3 和 GLM 5.3 Flash 无法关闭思考:它们的 /api/show thinking 值中没有 false,并且 think: false 会使它们以推理内联方式回答。对于这些模型,/think off 和已配置的 false 会在 agent 轮次以及诸如 openclaw infer model run 的一次性补全中,改为发送其最低级别 think: "low"。
Tip
对于 OpenAI 兼容端点,则请参见上文中的“旧版 OpenAI 兼容模式”——在那里,流式传输和工具调用可能无法同时工作。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw