OpenCode Free Models v2.7

自动配置 opencode.ai Zen 免费模型到 OpenClaw。

触发词

• "配置 opencode 免费模型"
• "添加 opencode 模型"
• "opencode 免费"
• "free model"

架构

1. 网络层 — 重试 3 次，Cloudflare 拦截自动退避（2s/4s/6s）
2. 模型缓存 — ~/.openclaw/.opencode-free-cache.json，6 小时 TTL
3. 健康探测 — 逐模型调 /chat/completions 真实验证
4. 配置管理 — diff 检测跳过无变化写盘
5. Fallback 管理 — 自动替换失效模型，支持恢复已恢复的模型
6. 上下文窗口探测 — 梯度查找模型最大 max_tokens，缓存结果并回写 provider 配置

CLI 命令

入口：python scripts/opencode_free.py <命令>（wrapper 转发到上层 configure-models.py）

# 自动配置（探测 + 添加 provider + 更新 fallback）
python scripts/opencode_free.py auto [--force] [--test] [--count N] [--all]

# 列出免费模型（--all 列出全量 62 个）
python scripts/opencode_free.py list [--refresh] [--all]

# 查看当前配置状态
python scripts/opencode_free.py status

# 实时健康探测所有模型（--all 探测全量，--probe-context 探测窗口上下文）
python scripts/opencode_free.py test [--refresh] [--all] [--probe-context]

# 旋转 fallback 链（移除失效，--restore 恢复已恢复的）
python scripts/opencode_free.py rotate [--restore] [--count N]

# 强制刷新模型缓存（--all 刷新全量）
python scripts/opencode_free.py refresh [--all]

# 更新 fallback 链（自定义数量，--probe-context 探测窗口上下文）
python scripts/opencode_free.py fallbacks [--test] [--count N] [--refresh] [--probe-context]

标准流程

# 1. 自动配置（探测 + 添加 + fallback + 上下文窗口）
python scripts/opencode_free.py auto --yes --test

# 2. 重启 Gateway
openclaw gateway restart

上下文窗口探测

• auto --test 默认开启：对每个可用模型梯度查找最大 max_tokens（131072 → 65536 → 32768 → 16384 → 8192），首个有非空响应的值即为上限
• 结果缓存到 ~/.openclaw/.opencode-free-cache.json 的 model_limits 字段，避免重复探测
• 自动回写 provider 配置：maxTokens = 实测值，contextWindow = maxTokens * 8
• 已有模型保留其实测值，不会被覆盖
• 手动触发：python scripts/opencode_free.py test --probe-context 或 python scripts/opencode_free.py fallbacks --test --probe-context

文件布局

opencode-free-models/
  configure-models.py      # 主实现（v2.3，~30KB）
  SKILL.md                 # 技能说明
  README.md                # 项目说明
  skill-card.md            # SkillHub 卡片
  _meta.json               # SkillHub 本地元数据
  scripts/
    opencode_free.py       # 入口 wrapper（转发到 ../configure-models.py）

最新验证（2026-08-21）

• 权威源修复（v2.7）：探测/注册以官方 GET /zen/v1/models 免费清单为准，手填白名单不再拦截（仅作 NEW/KNOWN 标注兜底）。旧版白名单漏报官方新免费模型且含死名字残留，已根治
• fallback 全量入链（v2.7）：稳定可用在前、限流保留在后、不再截断 5；限流模型保留注册不剔除。旧版 filtered[:5] 会把探测时刻限流的模型（如 laguna）截掉
• --count 默认 None=全量；显式传 int 才截断
• 实测：官方免费清单 8 个，可用 6 个（big-pickle / x-preview-f-free / mimo-v2.5-free / hy3-free / nemotron-3-ultra-free / nemotron-3.5-lightning-free）+ laguna-s-2.1-free 抖动可用
• deepseek-v4-flash-free 已下架免费档（401 Free promotion has ended），自动剔除
• muse-spark-1.2-contributor-free 对中国区 403 RegionError（地区封锁），非故障，自动剔除
• 端点特性：opencode 免费端点动态限流剧烈，同模型不同时刻 200/429 互跳，单次探测快照只是当时额度窗口投影；连发 3 次取稳定性已缓解但无法根治

v2.8.0 缺陷修复（2026-08-29）

• 白名单外可用候选未注册缺陷（根治）：cmd_auto 原把探测成功的 unknown（白名单外可用候选，如 ling-3.0-flash-fin-free）排除在注册集与 fallback 链之外，仅标注 NEW 但不注册，导致新免费模型永不被使用。改为 reg_ids = available | ratelimited | unknown 统一进入注册与 fallback；上下文窗口探测同步覆盖 unknown
• HTTP 400/403 误判为限流（回归修复）：重写探测逻辑时把 HTTPError 统一当空响应→限流保留，导致已下架的 deepseek-v4-flash-free(400) 与地区封锁的 muse-spark-1.2-contributor-free(403) 错误保留注册并塞进 fallback。现区分 FAIL(400/403) 与 RATELIMIT(429/503)，永久失败正确剔除
• 实测：官方免费清单 9 个，可用 7 个（big-pickle / mimo-v2.5-free / hy3-free / nemotron-3-ultra-free / nemotron-3.5-lightning-free / laguna-s-2.1-free / ling-3.0-flash-fin-free）+ 2 永久失败（deepseek-v4-flash-free 400、muse-spark-1.2-contributor-free 403）

注意事项

• 默认只扫 free 关键字：list / test / auto 默认只处理官方清单中 ID 含 free 的模型（权威源）
• --all 全量探测：list --all / test --all / auto --all --test 可对 API 全量 64 个模型逐个 chat probe，发现 ID 不带 free 但实际可用的模型
• 付费模型 401：non-free 模型用 public key 探测全部返回 401，只有官方免费清单内模型可用
• 无需 API Key：opencode.ai Zen 免费模型使用 public 凭据
• 端点：https://opencode.ai/zen/v1
• GBK 安全：所有日志输出用 ASCII 标记，无 emoji
• 幂等：多次运行不重复添加，配置无变化不写盘
• 环境变量：OPENCODE_API_KEY（默认 public）、OPENCODE_PROVIDER_KEY（默认 opencode-free）
• 探测 max_tokens=1024 + 空响应重试（v2.1）：big-pickle/deepseek 等思考模型的 reasoning tokens 计入 max_tokens 预算，128 时复杂思考占满预算 → finish_reason=length → content 空（误判不可用）。1024 预留思考空间，空响应重试一次防波动。探测从 128→1024 后 6/6 全过
• 空响应判失败（v2.1）：HTTP 200 但 content 为空 = 不可用，不再当作可用（重试一次后仍空才判 FAIL）
• FAIL 重试（v2.2）：单模型探测 FAIL 后延迟 2s 再探一次，降低 reasoning 模型首轮慢响应误判
• 内置模型数据库限制（v2.1）：OpenClaw 启动会用内置模型库（dist/provider-catalog-*.js）规范化 provider，数据库不认识的模型会被丢弃（如 ling-3.0-flash-free、laguna-s-2.1-free 曾被清掉）。技能维护 KNOWN_SAFE_MODELS 名单与 catalog 对齐，add_provider/add_models_to_provider 只操作安全集，update_fallbacks 过滤未注册模型，避免 fallback 悬空
• 白名单已扩展（2026-08-15）：当前 11 个模型（big-pickle/deepseek-v4-flash-free/mimo-v2.5-free/nemotron-3-ultra-free/nemotron-3-super-free/north-mini-code-free/qwen3.6-plus-free/minimax-m3-free/hy3-free/nemotron-3.5-lightning-free/laguna-s-2.1-free），覆盖 catalog 认识模型 + 当前配置已有 + 在线可用模型
• 默认全量扫描（v2.6）：auto --test 默认 fetch 全量 62 个模型元数据，健康探测只测白名单内模型（快），注册时只保留 tested available 模型，不在探测结果中的旧模型自动剔除（如 north-mini-code-free）。--all 用于全量 chat probe 发现新免费模型
• 探测超时 30s（v2.2）：REQUEST_TIMEOUT 从 15s 提到 30s，减少 reasoning 模型慢响应超时误判
• 实测窗口上限（2026-08-01 实测，写入 openclaw.json）：big-pickle 1M/131K、deepseek-v4-flash-free 1M/131K、nemotron-3-ultra-free 262K/65K、mimo-v2.5-free 262K/32K、north-mini-code-free 100K/8K（north-mini 262K 时 400 超窗，100K 是实际上限）。_build_model_config 保留现有模型实测元数据，rotate 不会冲回默认 65536/8192
• 备份：修复前文件保留为 *.bak-20260801
• 上下文窗口自动探测（v2.4）：auto --test 默认对可用模型做上下文窗口探测，梯度查找最大 max_tokens（131072 → 65536 → 32768 → 16384 → 8192），结果缓存到 .opencode-free-cache.json 的 model_limits 字段，并回写 provider 配置的 maxTokens/contextWindow。contextWindow = maxTokens * CONTEXT_WINDOW_MULTIPLIER（默认 8）。test --probe-context 和 fallbacks --test --probe-context 可按需手动触发
• Windows 重启限制（2026-08-15 实测）：gateway 工具的 restart 在 Windows 上走 mode: emit，不会真正重启 Scheduled Task 托管的 Gateway 进程（PID 不变）。必须用 CLI openclaw gateway restart 才会真正重启（PID 会变）。技能内 _gateway_restart() 已针对 Windows 使用 detached 后台进程重启，避免杀掉当前 exec 会话
• name 字段非空（2026-08-15 修复）：_build_model_config 新增模型时若 API 返回空 name，会回落到模型 id，避免 Gateway 校验失败（models.providers.opencode-free.models.X.name: Invalid input）