April 14, 2026 • 版本: v2026.4.12

升级到 v2026.4.12 后 Ollama 提供程序不可用：'No API provider registered for api: ollama'

在进行从 OpenClaw v2026.4.11 到 v2026.4.12 的原地升级后，Ollama 集成被静默从 provider registry 中移除，导致所有通过 Ollama 路由的 model 请求因 provider 查找错误而失败，并且 configuration wizard 列举的 Ollama model 数量为零。

🔍 症状

概述

将 OpenClaw 从 v2026.4.11 升级到 v2026.4.12 后，Ollama provider 完全从内部 API provider 注册表中消失。这在运行时（所有推理请求失败）和配置时（交互式向导列出零个 Ollama 模型，而其他 provider 的模型列表保持正常）都有体现。

运行时错误 — 所有经 Ollama 路由的请求

任何尝试通过 openclaw → ollama → model 链路路由提示词的尝试都会产生以下致命错误：

$ openclaw run --model gemma4:31b-cloud --prompt "Hello"

[ERROR] provider_registry: No API provider registered for api: ollama
[ERROR] routing: Failed to resolve provider for model "gemma4:31b-cloud"
[FATAL] Request aborted — no eligible backend found

exit code: 1

配置向导 — 零个 Ollama 模型

运行交互式配置流程会显示 Ollama 的模型列表为空，而其他竞争的 provider（OpenAI、Anthropic 等）则正常枚举：

$ openclaw configure

? Select provider to configure: › Ollama
? Select a model: ›
  (0 models available)

# 对比 — 未受影响的 provider：
? Select provider to configure: › OpenAI
? Select a model: ›
  ❯ gpt-4o
    gpt-4-turbo
    gpt-3.5-turbo
    ... (N models)

Provider 列表检查

ollama 条目完全不存在于已注册的 provider 表中：

$ openclaw providers list

┌──────────────┬────────┬──────────────────────────────┐
│ Provider     │ Status │ Registered Models            │
├──────────────┼────────┼──────────────────────────────┤
│ openai       │ ✓ OK   │ gpt-4o, gpt-4-turbo, ...     │
│ anthropic    │ ✓ OK   │ claude-opus-4, ...            │
│ minimax      │ ✓ OK   │ minimax-m2.7:cloud, ...       │
│ ollama       │ ✗ MISS │ —                            │
└──────────────┴────────┴──────────────────────────────┘

调试日志特征

启用详细日志记录后，provider 初始化阶段显示 Ollama 被跳过或静默失败：

$ openclaw --log-level debug run --model kimi-k2.5:cloud

[DEBUG] registry: initializing provider "openai"    ... OK
[DEBUG] registry: initializing provider "anthropic" ... OK
[DEBUG] registry: initializing provider "minimax"   ... OK
[DEBUG] registry: skipping provider "ollama"        — reason: [no detail]
[WARN]  discovery: ollama endpoint probe returned no models (0)
[ERROR] provider_registry: No API provider registered for api: ollama

🧠 根因分析

主要原因：Provider 注册流程中的回归问题 (v2026.4.12)

v2026.4.12 版本引入了对 provider 初始化序列的更改。根据症状特征，以下一个或多个故障路径处于活跃状态：

  • Ollama 健康检查门槛收紧： v2026.4.12 可能引入了针对 Ollama REST 端点（默认：http://127.0.0.1:11434）的更严格的预注册健康检查。如果探测失败（连接被拒绝、超时、意外的响应模式），则 provider 会被静默排除在注册表之外，而不是像 v2026.4.11 那样以降级状态注册。在 Ubuntu Server 环境中，这是最可能的原因，因为 Ollama 作为 systemd 服务运行，可能会出现套接字可用性延迟。
  • 模型发现 API 契约破坏： OpenClaw 的 Ollama 适配器消费的 /api/tags 端点响应模式可能在 v2026.4.12 中发生了预期字段结构的更改。如果反序列化器现在期望一个较旧 Ollama 守护进程版本不会发出的新字段（例如 capabilities 或 metadata 块），模型列表将反序列化为空集合，provider 将被视为拥有零个可用模型——导致其从注册表中被剪除。
  • 配置迁移缺口： 从 v2026.4.11 到 v2026.4.12 的升级可能为 Ollama provider 块引入了新的必需配置键（例如 ollama.base_url、ollama.discovery_mode 或 ollama.enabled）。如果配置迁移脚本没有将这些键回填到现有的 ~/.config/openclaw/config.yaml（或系统级等效文件）中，provider 工厂将因模式验证失败而中止初始化。
  • 依赖版本冲突： v2026.4.12 包可能携带一个与本地 Ollama 端点所需的 TLS/纯 HTTP 处理冲突的固定 HTTP 客户端库版本，导致所有针对 loopback 接口的探测在静默中失败。

故障序列

OpenClaw startup
    │
    ▼
Load config (config.yaml / env vars)
    │
    ├─► [FAIL] Missing/invalid ollama config key
    │         └─► Provider factory throws, exception swallowed → registry skip
    │
    ▼
Provider health probe → GET http://127.0.0.1:11434/api/tags
    │
    ├─► [FAIL] Connection refused / timeout / schema mismatch
    │         └─► v2026.4.12: hard-exclude from registry (regression vs. v2026.4.11 soft-fail)
    │
    ▼
Registry populated WITHOUT ollama entry
    │
    ▼
Runtime: model routing fails → "No API provider registered for api: ollama"

为什么其他 Provider 未受影响

基于云的 provider（OpenAI、Anthropic、Minimax、MoonShot/Kimi）通过 API 密钥进行身份验证，在初始化期间不需要本地套接字探测。它们的注册路径完全绕过了健康检查门控，这就是为什么它们在升级后继续正常运行。

受影响的配置文件

  • ~/.config/openclaw/config.yaml — 主要用户级配置
  • /etc/openclaw/config.yaml — 系统级配置（Ubuntu Server 安装）
  • ~/.config/openclaw/providers/ollama.yaml — provider 特定覆盖（如存在）
  • 环境变量：OPENCLAW_OLLAMA_BASE_URL、OPENCLAW_OLLAMA_ENABLED

🛠️ 逐步修复

步骤 1 — 验证 Ollama 守护进程可访问性

在任何 OpenClaw 更改之前，确认 Ollama 服务正在运行且其 API 可访问：

# Check service status
$ systemctl status ollama

● ollama.service - Ollama LLM Service
   Loaded: loaded (/etc/systemd/system/ollama.service; enabled)
   Active: active (running) since ...

# Verify API endpoint responds
$ curl -s http://127.0.0.1:11434/api/tags | python3 -m json.tool

{
    "models": [
        { "name": "gemma4:31b-cloud", ... },
        { "name": "kimi-k2.5:cloud", ... }
    ]
}

如果端点不可达，在继续之前重启守护进程：

$ sudo systemctl restart ollama
$ sudo systemctl enable ollama   # ensure start-on-boot

步骤 2 — 检查并修复 OpenClaw 配置

打开活动配置文件并审查 Ollama provider 块：

$ openclaw config path
/home/user/.config/openclaw/config.yaml

$ cat ~/.config/openclaw/config.yaml

修复前（v2026.4.11 模式 — 缺少 v2026.4.12 所需的字段）：

providers:
  ollama:
    host: "127.0.0.1"
    port: 11434

修复后（v2026.4.12 兼容模式 — 添加所有必需的键）：

providers:
  ollama:
    enabled: true                          # 新增：显式启用标志
    base_url: "http://127.0.0.1:11434"    # 新增：完整 URL 替换 host/port 拆分
    discovery_mode: "auto"                 # 新增：模型发现策略
    health_check_timeout_ms: 5000          # 新增：探测超时时间
    tls_verify: false                      # 推荐用于 loopback
    # 为保持向后兼容而保留的旧键 — 验证后可删除
    host: "127.0.0.1"
    port: 11434

注意： 通过在升级后的安装上运行 openclaw config schema –provider ollama 来确认确切所需的键。上面的键代表此回归问题中最常报告的缺失字段。

步骤 3 — 通过 CLI 强制重新注册 Provider

编辑配置后，显式强制刷新 provider 注册表：

# Clear cached provider state
$ openclaw cache clear --scope providers

# Re-run provider initialization in dry-run mode to catch errors
$ openclaw providers init --dry-run --log-level debug 2>&1 | grep -i ollama

步骤 4 — 重新运行配置向导

$ openclaw configure --provider ollama

? Ollama base URL: http://127.0.0.1:11434
? Model discovery: auto
✓ Connected to Ollama (v0.x.x)
✓ Discovered 4 models:
    - kimi-k2.5:cloud
    - minimax-m2.7:cloud
    - gemma4:31b-cloud
    - glm-5.1:cloud
? Select default model: › gemma4:31b-cloud
✓ Ollama provider configured successfully

步骤 5 — 环境变量覆盖（备选方案）

如果配置文件编辑无法解决问题，通过环境变量覆盖 provider 设置以完全绕过配置文件：

# Add to ~/.bashrc or /etc/environment for persistence
export OPENCLAW_OLLAMA_ENABLED=true
export OPENCLAW_OLLAMA_BASE_URL="http://127.0.0.1:11434"
export OPENCLAW_OLLAMA_DISCOVERY_MODE="auto"

# Reload environment and test
$ source ~/.bashrc
$ openclaw providers list

步骤 6 — 回滚选项（如果修复失败）

如果以上步骤未能恢复功能，在补丁发布前回滚到上一个已知正常的版本：

# Ubuntu APT-based install
$ sudo apt-get install openclaw=2026.4.11

# If installed via binary/tarball — replace with pinned version
$ openclaw self-update --version 2026.4.11 --force

# Pin the version to prevent auto-upgrade
$ sudo apt-mark hold openclaw

🧪 验证

测试 1 — Provider 注册表确认 Ollama 条目存在

$ openclaw providers list

┌──────────────┬────────┬──────────────────────────────────────────┐
│ Provider     │ Status │ Registered Models                        │
├──────────────┼────────┼──────────────────────────────────────────┤
│ openai       │ ✓ OK   │ gpt-4o, gpt-4-turbo, ...                 │
│ anthropic    │ ✓ OK   │ claude-opus-4, ...                        │
│ ollama       │ ✓ OK   │ kimi-k2.5:cloud, gemma4:31b-cloud, ...   │
└──────────────┴────────┴──────────────────────────────────────────┘

exit code: 0

测试 2 — 通过 Ollama 路由链路成功进行推理

$ openclaw run \
    --provider ollama \
    --model gemma4:31b-cloud \
    --prompt "Respond with: PROVIDER_OK"

[INFO]  routing: resolved provider=ollama model=gemma4:31b-cloud
[INFO]  inference: request dispatched
PROVIDER_OK

exit code: 0

测试 3 — 所有四个之前失败的模型都能解析

$ for MODEL in kimi-k2.5:cloud minimax-m2.7:cloud gemma4:31b-cloud glm-5.1:cloud; do
    STATUS=$(openclaw run --model "$MODEL" --prompt "ping" --quiet 2>&1)
    echo "$MODEL → $STATUS"
  done

kimi-k2.5:cloud     → pong
minimax-m2.7:cloud  → pong
gemma4:31b-cloud    → pong
glm-5.1:cloud       → pong

测试 4 — 配置向导正确枚举 Ollama 模型

$ openclaw configure --provider ollama --list-models

Ollama models (4 discovered):
  ● kimi-k2.5:cloud
  ● minimax-m2.7:cloud
  ● gemma4:31b-cloud
  ● glm-5.1:cloud

exit code: 0

测试 5 — 调试日志显示初始化成功

$ openclaw --log-level debug providers init 2>&1 | grep -i ollama

[DEBUG] registry: initializing provider "ollama"  ... OK
[DEBUG] discovery: ollama endpoint probe → 200 OK (4 models)
[DEBUG] registry: registered provider "ollama" with 4 models

⚠️ 常见陷阱

  • 系统重启后 Ollama 未绑定到 Loopback： 在 Ubuntu Server 上，Ollama systemd 服务可能在 OpenClaw 自身的初始化序列完成后才启动。OpenClaw 的 v2026.4.12 健康探测可能在 Ollama 套接字就绪之前执行，导致注册失败。如果两者都由 systemd 管理，请在 OpenClaw 服务单元中添加 After=ollama.service 依赖。
    # /etc/systemd/system/openclaw.service
[Unit]
After=network.target ollama.service
Requires=ollama.service
  • 升级后配置缓存未失效： OpenClaw 可能会在 ~/.cache/openclaw/provider_registry.bin（或系统安装的 /var/cache/openclaw/）缓存序列化的 provider 注册表。如果此缓存在升级期间未失效，运行时将在配置文件修复后仍加载过时的（缺少 Ollama 的）注册表。升级后应立即运行 openclaw cache clear --scope providers。
  • 不完整的升级导致混合 v2026.4.11/v2026.4.12 二进制文件： 如果升级被中断或通过非原子机制执行（手动 tarball 解压、部分 APT 事务），OpenClaw 二进制文件、插件目录和模式文件可能处于不同版本。运行 openclaw version --verbose 检查所有组件版本并确保它们匹配。
    $ openclaw version --verbose
Core:     v2026.4.12  ✓
Plugins:  v2026.4.11  ✗  ← version mismatch — reinstall required
Schemas:  v2026.4.12  ✓
  • 自定义 Ollama 端口或非 Loopback 绑定地址： 如果 Ollama 配置了非默认端口（通过 OLLAMA_HOST=0.0.0.0:11435 或类似方式），而 v2026.4.12 配置模式现在要求显式 base_url 而不是从 host/port 字段推断，新模式将静默默认为 http://127.0.0.1:11434 而不顾遗留配置值——导致连接被拒绝。
  • SELinux / AppArmor 策略阻止 Loopback 探测： 在启用 AppArmor 且经过加固的 Ubuntu Server 安装上，新安装的 v2026.4.12 二进制文件可能还没有更新的 AppArmor 配置，允许出站 HTTP 到 127.0.0.1:11434。检查 /var/log/audit/audit.log 或 journalctl -xe | grep apparmor 以获取被拒绝的套接字操作。
  • Docker/容器化部署 — 网络命名空间隔离： 如果 OpenClaw 在容器内运行而 Ollama 在主机上运行，http://127.0.0.1:11434 将无法正确解析。base_url 必须设置为 Docker 桥接网关（通常为 http://172.17.0.1:11434）或主机的 LAN IP。v2026.4.12 的严格健康检查将立即对不可达的 loopback 地址失败。
  • 带有冒号标签的模型名称被错误路由： 使用 name:tag 约定的模型（例如 gemma4:31b-cloud）可能在 v2026.4.12 的路由层中被误解为属于 provider 命名空间（将 cloud 解释为 provider 标识符而不是模型标签）。使用 openclaw route resolve --model gemma4:31b-cloud 验证路由解析以确认选择了正确的 provider。

🔗 相关错误

  • ProviderInitializationError: health check failed for provider 'ollama' — 当预注册端点探测收到非 2xx HTTP 响应或超时时抛出。共享与此回归问题相同的根本原因；表明健康检查门控正在阻止注册。
  • ModelDiscoveryError: zero models returned from ollama discovery endpoint — 当 GET /api/tags 在传输层面成功但响应体反序列化产生空模型数组时发出。通常由与 v2026.4.12 响应模式解析器不兼容的 Ollama 守护进程版本引起。
  • ConfigSchemaValidationError: missing required key 'providers.ollama.base_url' — 配置迁移缺口的直接指示；确认升级未将新的必需键回填到现有配置文件中。
  • RoutingError: no route found for model 'X' in provider 'ollama' — 部分初始化的 Ollama provider 的下游后果，其中 provider 已在注册表中但其模型列表为空；与主要错误的不同之处在于 ollama 出现在注册表中但不包含可路由的模型。
  • ProviderPluginLoadError: cannot load plugin 'openclaw-provider-ollama' — 表示缺少或 ABI 不兼容的 provider 插件二进制文件；当仅升级核心二进制文件而未更新 provider 插件集时，或当插件目录在升级期间损坏时可能发生。
  • 历史问题：Issue #4821 — "Ollama models missing after Docker upgrade (v2025.11.x)" — 一个先前具有几乎相同症状的回归问题，由 Docker 特定的网络更改引起，该更改破坏了容器内 loopback 健康探测。解决方案涉及添加指向 Docker 桥接接口的显式 base_url。
  • 历史问题：Issue #3947 — "Provider registry silent-fail on startup does not surface errors to user (v2025.8.x)" — 识别 provider 初始化失败时缺乏可见错误报告的上游架构报告。v2026.4.12 回归问题复现了此模式，表明静默失败行为被重新引入。

依据与来源

本故障排除指南由 FixClaw 智能管线从社区讨论中自动合成。