[Bug] 使用本地 Ollama (OpenAI 兼容端点) 时提示 "no API key configured" 错误

[mikelix]

问题描述:
我在 Windows 11 (WSL2 Ubuntu) 环境下尝试通过 PicoClaw 对接本地运行的 Ollama。虽然 picoclaw status 显示 Provider 已配置，但在执行 agent 命令时，程序无法正确识别本地配置，报错提示缺少 API Key。

环境信息:
操作系统: Windows 11 + WSL2 (Ubuntu 22.04/24.04)

PicoClaw 版本: v0.1.0
本地 LLM 服务: Ollama (运行于 Windows 或 WSL2)

使用的模型: qwen2.5:3b-16k
复现步骤:

确认 Ollama 正常运行在 http://127.0.0.1:11434/v1。执行 curl http://127.0.0.1:11434/v1/models 能正常返回模型列表。

在 ~/.picoclaw/config.json 中配置 openai 或 vllm provider，指向上述 Ollama 地址。

运行命令: picoclaw agent -m "hello"

预期行为:
Agent 应该识别出该模型属于配置好的本地 OpenAI 兼容 Provider，并跳过 API Key 检查（或使用配置文件中提供的 dummy key）。

实际行为:
终端返回错误：
Error creating provider: no API key configured for model: qwen2.5:3b-16k

[mingyue0094]

没key, 就随便写 1234567890 ,应该就可以了吧

[sunglee42]

因為專案更新很快 我不太確定是不是還是這樣
但應該與API Key本身無關 是provider辨識的問題

#75 這邊已經有在處理了 但還沒合併
#28 這邊說合併了 但似乎沒有效果(LM Studio也是同樣情況)
似乎provider辨識和openclaw不一樣 是硬編碼 #96
沒辦法自由的命名 去匹配model與provider
但picoclaw status仍會顯示配置正確

[sunglee42]

更新一下 我是使用lm studio
直接配置在openai裡面 並在agents裡面設定好model
但現在agents裡面還多了一個provider可以設定
把那個在填上openai就能正常運作了
這樣看應該是已經在某版本中修好 請在試試

[FredWang1234567]

同样的问题，看了相关notes，没有一个能给出完整解决方案的，都没用。到现在也无法解决。

[sunglee42]

@FredWang1234567 正好我開新機器測 給你回報一下 (測試版本 13e4028)

最簡單方法就是使用openai類別來建立provider
當然要記得設定agents底下設定provider為openai
不然也會出現"no API key configured"

至於ollama確實有在 http_provider.go 做處理
但只能說有點微妙... 因為他要求模型名稱前面要掛ollama
(例如qwen3 得叫做 ollama/qwen3)
我自己是比較喜歡用provider設定的方式來指定
畢竟有的會掛前綴(例如lm studio) 有的則不會(ollama或openai都是)

畢竟專案現在擴張的有點快 未來可能還會有各種異動
建議選擇openai來設定
未來遇到(設定檔)衝突的機率可能會比較小

[mikelix]

请参考英文另外一个 Picoclaw 讨论同样问题 issue: #430 Google Gemini: 详细的分析，告诉你如何利用 #430 的思路来解决 #109：

1. 为什么 Ollama local models time out in PicoClaw (120s fixed HTTP timeout) while same models respond fine via direct Ollama API #430 的总结能帮到 [Bug] 使用本地 Ollama (OpenAI 兼容端点) 时提示 "no API key configured" 错误 #109？
   在 Issue Ollama local models time out in PicoClaw (120s fixed HTTP timeout) while same models respond fine via direct Ollama API #430 中，我们发现 PicoClaw 的代码里有许多**“硬编码”（Hardcoded）**的逻辑。

Issue #109 的病灶： 报错 "no API key configured" 通常是因为 PicoClaw 在连接本地 Ollama（OpenAI 兼容端点）时，代码逻辑强制校验了 API Key 字段。

关联点： 即使本地 Ollama 并不需要真实的 Key，但如果 PicoClaw 的底层提供商代码（例如 openai_compat/provider.go）被写死成“必须检测到非空字符串”，那么它就会报错。

2. 具体的解决步骤（借鉴 Ollama local models time out in PicoClaw (120s fixed HTTP timeout) while same models respond fine via direct Ollama API #430 的排查思路）
   如果你遇到了 [Bug] 使用本地 Ollama (OpenAI 兼容端点) 时提示 "no API key configured" 错误 #109 的 API Key 错误，可以按照以下方法解决：

方法 A：配置层面的“欺骗”（最简单）
在 #430 中，我们了解到 PicoClaw 会读取 config.json。

操作： 即使 Ollama 本地不需要 Key，你也需要在 PicoClaw 的配置文件中，为该提供商填入一个任意的占位符字符串（例如 "api_key": "ollama" 或 "api_key": "sk-123456"）。

原理： 这能绕过代码中可能存在的 if apiKey == "" 的强制性检查。

方法 B：检查端点路径（借鉴 #430 的代码位置）
Issue #430 提到了 pkg/providers/openai_compat/ 这个目录。

操作： 确保你的 base_url 填写正确。对于本地 Ollama，通常是 http://localhost:11434/v1。

注意： 有些版本的 PicoClaw 可能会在代码里自动拼接路径，如果手动填写的路径不对，也会触发配置校验错误。

方法 C：修改源码（终极方案）
既然我们在 #430 中锁定了 pkg/providers/openai_compat/provider.go 这个关键文件：

操作： 你可以查看该文件中的 NewProvider 或 Validate 函数。

修改建议： 找到检查 api_key 的逻辑，将其改为非强制性，或者在本地编译时直接删掉那个报错分支。

总结建议
Issue #109 实际上是由于 PicoClaw 的 OpenAI 兼容模式做得过于“严谨”导致的。 * 最快解法： 在 config.json 里随便填一个 API Key。

深度解法： 关注 #430 正在推进的 配置灵活性更新。一旦开发者按照 #430 的建议开放了更多配置项（比如超时、跳过 Key 校验），#109 的问题自然会迎刃而解。

如果你现在正卡在 #109 错误上，建议先试着在配置文件里填入 api_key: "anything"，这通常能解决 90% 的这类报错！

[nikolasdehor]

The root cause here is that picoclaw's provider routing was hardcoded to match model name prefixes to providers. This has been significantly improved:

1. PR Add provider field support for explicit provider selection #48 (merged): Added explicit provider field in agent defaults
2. PR Refactor providers by protocol family (discussion #122) #213 (merged): Refactored providers by protocol family
3. PR feat(config): refactor provider architecture to protocol-based model_list #492 (merged): Introduced model_list config for flexible model-to-provider mapping

For Ollama specifically, the recommended config now is:

"agents": {
  "defaults": {
    "provider": "openai",
    "model": "qwen2.5:3b-16k"
  }
},
"providers": {
  "openai": {
    "api_key": "dummy",
    "api_base": "http://127.0.0.1:11434/v1"
  }
}

Key: you must set "provider": "openai" in agent defaults AND use the /v1 endpoint (not /api/chat). The dummy API key is required to pass the non-empty validation check.

For Docker users, PR #491 (merged) fixed container-to-host connectivity, so http://host.docker.internal:11434/v1 now works correctly.