技能介绍

要解决什么问题

在 OpenClaw 里接 opencode.ai Zen 的免费模型，不能靠手填模型 ID：官方清单会变（下架、限流、地区封锁），OpenClaw 内置 catalog 还会丢弃它不认识的 provider 模型。手动改 openclaw.json 容易留下失效 fallback 或错误的 max_tokens。

技能如何工作

入口是 python scripts/opencode_free.py，由 wrapper 转发到 configure-models.py。整体流程可以概括为：

权威清单：以官方 GET /zen/v1/models 为准，默认只处理 ID 含 free 的条目；--all 可对全量模型做 chat 探测，发现不带 free 但实际可用的候选。
健康探测：对每个候选调用 /chat/completions 做真实验证；区分 FAIL（400/403 等永久失败）与 RATELIMIT（429/503）；网络层失败会重试，并对 Cloudflare 做退避。
注册与 fallback：可用、限流、白名单外但探测成功的 unknown 会统一进入注册与 fallback 链；失效模型会被替换，稳定可用在前、限流保留在后。
上下文窗口：auto --test 默认对每个可用模型做梯度探测（131072 → … → 8192），结果写入 ~/.openclaw/.opencode-free-cache.json 的 model_limits，并回写 provider 的 maxTokens / contextWindow（已有实测值不会被覆盖）。
幂等与 diff：配置无变化不写盘；多次运行不会重复堆模型。

无需自备 API Key，默认使用 public 凭据，端点为 https://opencode.ai/zen/v1。

适用边界与注意点

免费端点动态限流剧烈，同模型在不同时刻可能 200/429 互跳，单次探测只是当时窗口的快照。
非 free 清单内模型用 public key 探测会一律 401，只有官方免费清单内的模型可用。
OpenClaw 启动会用内置 catalog 规范化 provider；技能通过 KNOWNSAFEMODELS 等与 catalog 对齐，避免注册了 catalog 不认识的模型后被启动逻辑清掉。
在 Windows 上，若需 Gateway 真正重启，应使用 openclaw gateway restart；技能内已对 Windows 的 restart 行为做了针对性处理。

截图预览

使用场景

刚部署 OpenClaw Gateway，需要把 opencode.ai 官方免费清单里的模型自动注册进 provider，而不是手改 openclaw.json。
官方免费档变更或某模型返回 401/403 后，需要重新探测可用性并重建 fallback 链，避免仍指向已下架模型。
使用 big-pickle 等思考型模型时，需要梯度探测实际上限 max_tokens 并回写 contextWindow，减少 finish_reason=length 导致的空响应。
免费端点频繁 429，需要在保留限流模型注册的前提下，把当前稳定可用的模型排在 fallback 前列。