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/zclawzclaw 是一个运行在 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 KeyAnthropicapi.anthropic.com/v1/messagesclaude-sonnet-4-6✅ x-api-keyOpenAIapi.openai.com/v1/chat/completionsgpt-5.4✅ BearerOpenRouteropenrouter.ai/api/v1/chat/completionsopenrouter/auto✅ BearerOllamahttp://127.0.0.1:11434/v1/chat/completionsqwen3:8b❌ 可选一个值得注意的设计OpenAI、OpenRouter、Ollama 三家共用同一套 OpenAI 兼容请求格式见 main/llm.h 中的llm_is_openai_format()只有 Anthropic 走自己独立的 Messages 格式。这意味着 zclaw 实际只维护两套协议就把四个后端都覆盖了。2. 后端如何配置三个 NVS 键搞定一切zclaw 的后端配置存在 ESP32 的 NVS 闪存里相关键定义见 main/nvs_keys.hllm_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 GPTOpenAI 后端使用标准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 configuredNVS 中未配置api_keyOllama 后端除外配置后重启日志Unknown llm_backendllm_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.16. 小结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），仅供参考