zclaw多模型后端实战指南：如何快速在ESP32上接入Anthropic、OpenAI、OpenRouter与本地Ollama
【免费下载链接】zclawYour personal AI assistant at all-in 888KiB (~35KB in app code). Running on an ESP32. GPIO, cron, custom tools, memory, and more.项目地址: https://gitcode.com/gh_mirrors/zc/zclaw
zclaw 是一个运行在 ESP32 芯片上的个人 AI 助手，固件整体不到 888KiB（应用代码仅约 35KB），却自带 GPIO 控制、定时任务、自定义工具和持久记忆。它的核心竞争力之一是多模型后端：同一个固件，可以在 Anthropic Claude、OpenAI GPT、OpenRouter 和本地 Ollama 四种大模型后端之间自由切换，无需重新编写业务逻辑。本文带你快速完成接入与验证。
1. zclaw 的多模型后端架构一览
zclaw 把所有大模型调用收敛在一个 HTTP 客户端里，由启动时读取的后端配置决定「请求发到哪、用什么鉴权、用什么默认模型」。核心逻辑见 main/llm.c，鉴权头构造见 main/llm_auth.c。
四种后端的默认端点与模型定义在 main/config.h：
| 后端 | 默认端点 | 默认模型 | 是否需要 API Key |
|---|---|---|---|
| Anthropic | api.anthropic.com/v1/messages | claude-sonnet-4-6 | ✅ x-api-key |
| OpenAI | api.openai.com/v1/chat/completions | gpt-5.4 | ✅ Bearer |
| OpenRouter | openrouter.ai/api/v1/chat/completions | openrouter/auto | ✅ Bearer |
| Ollama | http://127.0.0.1:11434/v1/chat/completions | qwen3:8b | ❌ 可选 |
一个值得注意的设计：OpenAI、OpenRouter、Ollama 三家共用同一套 OpenAI 兼容请求格式（见 main/llm.h 中的llm_is_openai_format()），只有 Anthropic 走自己独立的 Messages 格式。这意味着 zclaw 实际只维护两套协议，就把四个后端都覆盖了。
2. 后端如何配置：三个 NVS 键搞定一切
zclaw 的后端配置存在 ESP32 的 NVS 闪存里，相关键定义见 main/nvs_keys.h：
llm_backend：取值为anthropic/openai/openrouter/ollama，未知值会回落到 OpenAI 并打印告警api_key：各后端的密钥（Ollama 可留空）llm_model：可选，覆盖默认模型名（最多 64 字节）llm_api_url：可选，整体覆盖端点地址——这是接入任意 OpenAI 兼容自建网关的关键
启动时 llm_init() 按顺序加载这些键，并在日志中打印Backend: xxx, Model: xxx，烧录后看串口日志即可确认配置生效。
3. 逐个接入：四种后端实战要点
3.1 接入 Anthropic Claude
选择anthropic后端后，zclaw 会在 main/llm.c 中附加两个专属请求头：x-api-key（你的 Claude API Key）和anthropic-version: 2023-06-01。注意 Anthropic 的鉴权方式与其他三家完全不同，zclaw 已自动处理，你只需配置密钥即可。
3.2 接入 OpenAI GPT
OpenAI 后端使用标准Authorization: Bearer <key>头，由 llm_build_bearer_auth_header() 构造并做长度校验。想换模型（比如更便宜的 mini 档），配置llm_model覆盖即可，无需改动代码。
3.3 接入 OpenRouter：一把钥匙开多家
OpenRouter 是聚合网关，一个密钥调用上百家模型，非常适合 ESP32 这种资源受限设备做「按量选型」。接入后 zclaw 会额外带上HTTP-Referer和X-Title头（见 main/llm.c）以标识请求来源。默认模型为openrouter/auto，你也可以在llm_model里指定任意 OpenRouter 模型 ID。
3.4 接入本地 Ollama：完全离线的玩法
Ollama 是唯一不需要 API Key的后端（见 llm_backend_requires_api_key()）。默认端点是回环地址http://127.0.0.1:11434/...，适合 ESP32 与 Ollama 在同一主机/容器场景；若要通过网络访问局域网内的 Ollama 服务，必须配置llm_api_url指向对方 IP，否则设备会明确告警（见 main/llm.c）。如果你的 Ollama 前面挂了带鉴权的反向代理，填入 key 后 zclaw 也会自动加上 Bearer 头。默认模型为qwen3:8b，小模型 + 小芯片的组合正是 zclaw 的舒适区。
4. 如何验证接入是否成功
zclaw 内置了三层验证手段：
- QEMU 桩模式：编译时开启 stub LLM（见 scripts/emulate.sh），不联网即可跑通完整 Agent 流程，适合先验框架再配真模型
- 宿主桥接模式：在模拟器中通过 scripts/qemu_live_llm_bridge.py 把 HTTPS 请求转发到宿主机，真模型、快迭代
- 真机 Provider 测试：test/api/ 目录下的 provider_harness.py 与 test_anthropic.py、test_openai.py、test_openrouter.py、test_tool_creation.py 会对各家 API 做真实的工具调用回归测试，覆盖 GPIO 读写、记忆存取等典型场景
5. 常见问题快速排查
| 现象 | 原因与处理 |
|---|---|
日志No API key configured | NVS 中未配置api_key（Ollama 后端除外），配置后重启 |
日志Unknown llm_backend | llm_backend值拼写错误，已回落到 OpenAI，核对四个合法取值 |
日志LLM response truncated | 响应超出缓冲上限，改用更短的模型输出或精简提示词 |
日志Timed out waiting for HTTP gate | 与 Telegram 轮询抢占同一 HTTP 门控，zclaw 已按后端动态调整轮询超时（见 main/telegram_poll_policy.c），一般重试即可 |
| Ollama 连接失败 | 未配置llm_api_url指向局域网地址，仍在访问 127.0.0.1 |
6. 小结
zclaw 用一套统一的llm_request()抽象就打通了 Anthropic、OpenAI、OpenRouter 与本地 Ollama 四大后端：改 NVS 配置即可切换模型供应商，云端、聚合、离线三种形态随意组合。对于想在一块几块钱的开发板上跑真实大模型 Agent 的开发者来说，这正是它最有吸引力的地方。下一步可以阅读 docs-site/README.html 了解 GPIO、cron 与自定义工具的完整玩法。
【免费下载链接】zclawYour personal AI assistant at all-in 888KiB (~35KB in app code). Running on an ESP32. GPIO, cron, custom tools, memory, and more.项目地址: https://gitcode.com/gh_mirrors/zc/zclaw
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
