OpenClaw 配置调试实战：解决飞书插件冲突和 Ollama 自动配置陷阱

🎧 收听播客版本

⏱️ 时长约1分15秒 | 📥 也可以在通勤、运动时收听

问题背景

OpenClaw 已经稳定运行一段时间，但一直有两个告警问题困扰着我：

1. 飞书插件冲突：duplicate plugin id 警告不断出现
2. Ollama 配置反复注入：明明没用 Ollama，models.json 却总是被写入 ollama provider

这两个问题看似独立，但都关乎配置管理的规范化。今天终于抽时间彻底解决了，记录一下排查过程。

问题一：飞书插件 duplicate plugin id 错误

现象

每次重启 OpenClaw，都会看到这样的警告：

看起来你有两个 feishu 插件：
• 内置版本: /usr/lib/node_modules/openclaw/extensions/feishu
• 用户版本: /root/.openclaw/extensions/feishu
因为两者都存在，所以产生冲突。

排查过程

一开始以为是安装时的残留文件，但检查后发现：

1. 内置版本：在 /usr/lib/node_modules/openclaw/extensions/feishu
2. 用户版本：在 /root/.openclaw/extensions/feishu

两个插件 ID 相同，加载时检测到冲突。

解决方案

根据错误提示，删除旧的用户版本，保留内置的新版本：

rm -rf /root/.openclaw/extensions/feishu

然后重启 Gateway：

openclaw gateway restart

结果：duplicate plugin id 警告消失 ✅

经验教训

插件系统应该有版本优先级，内置版本应该优先于用户版本。但 OpenClaw 的检测机制是”两者都存在就报警”，所以需要手动清理。

这也提醒我：升级时要注意检查是否有旧版本的残留配置或扩展。

问题二：Ollama 配置反复自动注入

现象

即使没有使用 Ollama，每次重启后 ~/.openclaw/agents/main/agent/models.json 都会被自动写入：

"ollama": {
  "baseUrl": "http://127.0.0.1:11434",
  "api": "ollama",
  "models": [],
  "apiKey": "OLLAMA_API_KEY"
}

同时日志中不断出现：

Failed to discover Ollama models: TypeError: fetch failed

排查过程

第一阶段：删除配置

最初尝试手动删除 models.json 中的 ollama 配置：

# 删除 ollama 配置节点
sed -i '' '/"ollama":/,/}/d' models.json

但重启后又回来了。

第二阶段：查找配置源头

搜索 OpenClaw 源码，发现自动检测逻辑：

const ollamaKey = resolveEnvApiKeyVarName("ollama") ?? resolveApiKeyFromProfiles({
  provider: "ollama",
  store: authStore
});

if (ollamaKey) {
  const ollamaBaseUrl = params.explicitProviders?.ollama?.baseUrl;
  providers.ollama = {
    ...await buildOllamaProvider(ollamaBaseUrl),
    apiKey: ollamaKey
  };
}

关键在于 resolveEnvApiKeyVarName("ollama") —— 如果环境变量存在，就自动注入。

第三阶段：查找环境变量

检查 shell 配置：

grep -r "OLLAMA" ~/.zshrc ~/.bash_profile ~/.profile

找到：

# ~/.zshrc
export OLLAMA_API_KEY="ollama-local"

原因找到了！ 环境变量存在，OpenClaw 检测到后认为你想使用 Ollama，所以自动配置。

解决方案

方法 A：删除环境变量（推荐）

注释掉或删除 ~/.zshrc 中的 Ollama 环境变量：

# 注释掉
# export OLLAMA_API_KEY="ollama-local"

然后手动清理 models.json 中的残留配置，重启 Gateway。

最终结果

删除环境变量 + 清理 models.json 后，Ollama 不再自动注入，错误消失 ✅

注意：尝试过通过配置 explicit providers 来禁用自动发现的方法，但测试发现 OpenClaw 的配置文件不直接支持此参数，因此环境变量删除是最可靠的解决方案。

配置管理的最佳实践

通过这两个问题，总结出一些配置管理的经验：

1. 环境变量要定期审查

像 OLLAMA_API_KEY 这样的环境变量，如果不再使用应该及时清理。否则可能导致意外的自动配置行为。

建议：

• 定期回顾 ~/.zshrc、~/.bash_profile 中的环境变量
• 使用 env | grep -E "API|KEY" 检查敏感变量
• 建议在注释中说明每个环境变量的用途

2. 插件版本管理

安装升级时要注意：

• 检查是否有旧版本扩展残留（用户目录、全局目录）
• 内置版本优先于用户版本
• 删除前确认功能兼容性

3. 配置文件要定期审计

models.json 这类自动生成的配置文件，应该：

• 定期检查是否有异常的 provider
• 手动清理不用的配置
• 提交到版本控制前审查变更

4. 错误日志要及时关注

长期的警告日志容易被忽视，但实际上隐藏着潜在问题：

• duplicate plugin id → 可能导致功能冲突
• Failed to discover → 影响启动性能
• 建议：定期检查日志，特别是重启后的警告

调试工具推荐

排查这些问题时用到的工具：

1. 搜索配置文件

# 搜索配置中的关键词
grep -r "ollama" ~/.openclaw --include="*.json" --include="*.yaml"

# 搜索环境变量
grep -r "OLLAMA" ~/.zshrc ~/.bash_profile ~/.profile

2. 检查进程和端口

# 检查 OpenClaw 进程
ps aux | grep openclaw

# 检查 Ollama 端口（如果确认没用的服务）
lsof -i :11434

3. 查看日志

# OpenClaw 日志
tail -f ~/Library/Logs/openclaw-gateway.log

# 或者通过 Control UI 的日志面板查看

总结

这次调试解决了两个长期困扰的问题，虽然过程有些曲折，但也学到了：

1. 环境变量的”自动配置”陷阱：很多框架会根据环境变量自动注入配置，如果不及时清理废弃的环境变量，会出现莫名其妙的问题。

2. 插件系统要警惕版本冲突：升级时旧版本扩展残留导致的冲突很常见，删除前要确认功能兼容性。

3. 日志告警不能忽视：看似无害的警告，可能在背后持续消耗资源或影响性能。

4. 配置文件要定期审计：自动生成的配置文件（如 models.json）需要人工审查，确保没有异常内容。

现在 OpenClaw 启动干净，没有警告，运行更加稳定。这两个问题虽然不大，但解决后的清爽感还是很明显的 😄

相关文章：

• 飞书机器人接入指南
• 工具自动化的一天