跳转至

故障排除

故障排除

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 标记时, 它会记录一条启动警告。

缓解措施:

sudo systemctl disable ollama

在 Windows 一侧,将此内容添加到 %USERPROFILE%\.wslconfig,然后运行 wsl --shutdown:

[experimental]
autoMemoryReclaim=disabled

或者缩短 keep-alive / 仅在需要时手动启动 Ollama:

export OLLAMA_KEEP_ALIVE=5m
ollama serve

参见 ollama/ollama#11317。

未检测到 Ollama

确认 Ollama 正在运行,并且位于代理的模型范围内。对于自动 localhost 发现,请设置 OLLAMA_API_KEY(或一个认证配置)。显式的 自托管端点无论是否列出模型都会被发现:

ollama serve
curl http://localhost:11434/api/tags
没有可用模型

在本地拉取模型,或在 models.providers.ollama 中显式定义它:

ollama list  # See what's installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model
连接被拒绝
# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve
远程主机使用 curl 正常但 OpenClaw 不正常

从运行 Gateway 的同一台机器和运行时进行验证:

openclaw gateway status --deep
curl http://ollama-host:11434/api/tags

常见原因:

  • baseUrl 指向 localhost,但 Gateway 运行在 Docker 中或另一台主机上。
  • URL 使用了 /v1,选择的是 OpenAI 兼容行为而不是原生 Ollama。
  • 远程主机需要防火墙或 LAN 绑定更改。
  • 模型在你的笔记本守护进程中,但不在远程守护进程中。
模型将工具 JSON 输出为文本

通常是因为提供商处于 OpenAI 兼容模式,或者模型无法 处理工具架构。优先使用原生模式:

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434",
        api: "ollama",
      },
    },
  },
}

如果小型本地模型仍然无法处理工具架构,请在该模型条目上设置 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,然后尝试新的 会话和一个回退模型:

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --json
openclaw models set ollama/gemma4
冷启动本地模型超时

大型本地模型可能需要很长的首次加载时间。将超时范围限定为 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 延迟:

{
  models: {
    providers: {
      ollama: {
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            contextTokens: 32768,
            params: { num_ctx: 32768, thinking: false },
          },
        ],
      },
    },
  },
}

如果 OpenClaw 发送的 prompt 过多,请降低模型条目的 contextTokens。如果 Ollama 的运行时上下文对于机器来说过大,请降低 params.num_ctx。如果生成耗时过长,请降低 maxTokens。

Note

更多帮助:故障排除 和 常见问题。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw