故障排除
故障排除¶
WSL2 崩溃循环(反复重启)
在带有 NVIDIA/CUDA 的 WSL2 上,官方 Ollama Linux 安装程序会创建一个
ollama.service systemd 单元,并设置 Restart=always。如果该服务
自动启动,并在 WSL2 启动期间加载 GPU 支持的模型,Ollama 在加载时可能
会固定主机内存;Hyper-V 内存回收并不总能回收
这些页面,因此 Windows 可能会终止 WSL2 虚拟机,systemd 会重启
Ollama,循环随之重复。
证据:WSL2 反复重启/终止,WSL2 启动后 app.slice 或
ollama.service 的 CPU 占用很高,并且来自 systemd 的 SIGTERM
而不是 Linux OOM killer。
当 OpenClaw 检测到 WSL2、ollama.service
已启用且设置为 Restart=always,并且存在可见的 CUDA 标记时,
它会记录一条启动警告。
缓解措施:
在 Windows 一侧,将此内容添加到 %USERPROFILE%\.wslconfig,然后运行
wsl --shutdown:
或者缩短 keep-alive / 仅在需要时手动启动 Ollama:
未检测到 Ollama
确认 Ollama 正在运行,并且位于代理的模型范围内。对于自动
localhost 发现,请设置 OLLAMA_API_KEY(或一个认证配置)。显式的
自托管端点无论是否列出模型都会被发现:
没有可用模型
在本地拉取模型,或在
models.providers.ollama 中显式定义它:
远程主机使用 curl 正常但 OpenClaw 不正常
从运行 Gateway 的同一台机器和运行时进行验证:
常见原因:
baseUrl指向localhost,但 Gateway 运行在 Docker 中或另一台主机上。- URL 使用了
/v1,选择的是 OpenAI 兼容行为而不是原生 Ollama。 - 远程主机需要防火墙或 LAN 绑定更改。
- 模型在你的笔记本守护进程中,但不在远程守护进程中。
模型将工具 JSON 输出为文本
通常是因为提供商处于 OpenAI 兼容模式,或者模型无法 处理工具架构。优先使用原生模式:
如果小型本地模型仍然无法处理工具架构,请在该模型条目上设置
compat.supportsTools: false 并重新测试。
重复的工具错误会停止当前轮次
OpenClaw 会在同一工具和参数连续出现三次相同失败后停止,
包括重复的未知工具 ID。此保护始终
处于激活状态;无需启用 tools.loopDetection。
在 Ollama 0.40.1 中,某些模型模板可能导致服务器将
<tool_call> 标记误认为 Tool Search 的 tool_call 函数。OpenClaw 通过
仅用于传输的工具别名来避免
这种冲突,因此 Tool Search 可以保持
启用。执行和会话历史保留原始工具名称;原始
提供商请求中可能出现诸如 openclaw_tool_call 之类的名称。
此翻译涵盖原生 Ollama 以及 Ollama 插件已识别的 OpenAI 兼容 chat-completions 路由。其他提供商保持不变。 使用不同标记的自定义 Ollama 模板可能需要单独诊断。
检查所记录错误中的参数。如果模型反复编造 工具名称或无法使用已暴露的架构,请切换到支持原生 工具调用的模型并开始新的轮次。发生变化的错误和成功的重试 会重置计数。参见 工具循环检测。
Kimi 或 GLM 返回乱码符号
托管 Kimi/GLM 响应中出现的长串非语言符号 会被视为失败的提供商调用,而不是成功的回复,因此 正常的重试/回退/错误处理会接管,而不是将 损坏的文本持久化到会话中。
如果问题再次发生,请记录模型名称、当前会话文件,
以及该运行使用的是 Cloud + Local 还是 Ollama Cloud,然后尝试新的
会话和一个回退模型:
冷启动本地模型超时
大型本地模型可能需要很长的首次加载时间。将超时范围限定为 Ollama 提供商,并可选择在轮次之间保持模型加载:
{
models: {
providers: {
ollama: {
timeoutSeconds: 300,
models: [
{
id: "gemma4:26b",
name: "gemma4:26b",
params: { keep_alive: "15m" },
},
],
},
},
},
}
如果主机本身接受连接很慢,timeoutSeconds 还会
延长此提供商受保护的连接超时。
大上下文模型过慢或内存不足
许多模型宣称的上下文大于你的硬件能够
舒适运行的范围。原生请求会转发有效的 contextTokens,除非
params.num_ctx 覆盖它。同时限制 OpenClaw 的预算和 Ollama 的请求
上下文,以获得可预测的首 Token 延迟:
如果 OpenClaw 发送的 prompt 过多,请降低模型条目的 contextTokens。如果 Ollama 的运行时上下文对于机器来说过大,请降低 params.num_ctx。如果生成耗时过长,请降低 maxTokens。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw