free-llm-installer

免费 LLM 一键安装与实测验证

核心原则

「标 free」不等于「真能用」。 本技能内置的模型都是逐个发真实请求 （含 function calling）验证过的。使用者不需要自己再验证一遍。

已踩过的坑，不要重复：

内置模型（2026-10-11 实测）

免 key 梯队（Kilo Gateway，无需注册）

⭐ 最重要的一条：kilo-auto/free 的官方描述就是 "Rotates through available free models" ——它是随机轮换池，每次可能给你不同的模型，抽到重推理的就极慢。 正确做法：锁定具体模型 id（如上面的 LFM2.5），别用 auto 路由。 探网关有什么可选（免 key）：

curl -s -H "Authorization: Bearer anonymous" \
  https://api.kilo.ai/api/gateway/v1/models | python -c "import json,sys; [print(m['id'],m.get('context_length')) for m in json.load(sys.stdin)['data'] if 'free' in m['id']]"

omni 模型是免费读图兜底：免 key（apiKey 填 anonymous）、能读图、能调工具。 注意 reasoning 模型会先吐 reasoning 吃 token，max_tokens 给到 ≥1024 否则响应会被截断。

智谱 BigModel 梯队（需 key，但有永久免费档，效果最好）

用 --zhipu-key 安装；key 形如 xxxxxxx.YYYYYYYY（用户已有，见 glm profile）。 | 模型 id | 免费性质 | 工具调用 | 读图 | 推理 | |---|---|---|---|---| | glm-4-flash | 永久免费 | ✅ | ❌ | ❌ | 日常主力·最稳 | | glm-4.7-flash | 免费·高峰易 429 | ✅ | ❌ | ✅ | 带推理·质量更好 | | glm-z1-flash | 完全免费 | ❌ | ❌ | ✅ | 数学/代码推理，不输出结构化工具（仅聊天/推理用） | | glm-4v-flash | 永久免费 | ❌ | ✅ | ❌ | 免费读图，无工具（仅聊天/读图用） | | glm-4.1v-thinking-flash | 免费 | ❌ | ✅ | ✅ | 视觉+推理最强，但工具调用是智谱自定义「文本框」格式（非标准 tool_calls），不能用于 agent / 不能进切换器；读图实测可用（仅 WorkBuddy 聊天/读图用） | | glm-4.6v-flash | 免费·高峰持续 1305/500 | ❌ | ✅ | ❌ | 与 4.1v 同为视觉模型，但服务端极不稳定（实测连续 429→500→429），工具调用格式同为文本框。暂不可用，不加 |

Claude Code 切换器只放支持标准工具调用的模型（glm-4-flash / glm-4.7-flash）， 因为 Claude Code 靠工具调用干活；z1/v/4.1v/4.6v 都不输出结构化 tool_calls，加切换器会断 agent 循环，仅 WorkBuddy 聊天/读图用。

已移除 / 不可用

• space-bunny-free（OpenCode Zen）：2026-10-11 起上游 403 封 API 直连，暂不可用。
• glm-4.6v-flash：持续 1305 服务器过载，用户侧无解，不加。

国内外平台免费格局（时效内 + 效果好）

2026-10-13 普查结论：目前唯一免 key 免注册能用的聚合网关就是 Kilo（它的模型 id 就是 OpenRouter 的命名，本质是 OpenRouter 目录的匿名代理）。其他平台都要 key —— 所以要扩免费模型池， 正确路径是在 Kilo 里换模型 id，而不是换平台。 ⚠️ StepFun 类"限时免费"额度耗尽是账号级的：实测 step-5 / 3.5 / 3.7 全变 402，而 /v1/models 仍返回 200（key 有效）。所以别把关键工作流挂在限时免费模型上。

结论：本机最稳的免费组合 = GLM-4-Flash（文本+工具）+ GLM-4V-Flash（读图）+ GLM-Z1-Flash（推理）（智谱一个 key，30 并发，永久免费）+ Kilo 两个免 key 模型作零注册备用。DeepSeek-V4 是付费的，自动模式易烧钱，非必要别用。

执行流程

场景 A：用户要装免费模型

python scripts/install_free_llms.py                 # 装 Kilo 免 key 三件套 + 验证
python scripts/install_free_llms.py --zhipu-key KEY # 额外装智谱 GLM 永久免费梯队

建议把 liquid/lfm-2.5-2.6b:free（Claude Code 重活）或 glm-4-flash（日常对话）设为默认。别用 kilo-auto/free（随机轮换池，会抽到极慢的模型）。

场景 B：用户要验证已有配置

python scripts/install_free_llms.py --verify

发真实请求逐个验证。标记 supportsToolCall:false 的模型（glm-z1/v）只验证对话可用，不要求工具调用。 常见失败原因：

• 429 → 免费池高峰限流，等几分钟重试，不是配置错
• 401 → apiKey 写错或 id 被简化
• 未调工具 → 该模型不支持 function calling，不能用于 agent
• HTTP404 → 模型已下线，用 --refresh 拉当前清单

场景 C：用户问「现在还有哪些免费模型 / 国外平台有免费吗」

python scripts/install_free_llms.py --probe-foreign   # 探测国外平台免费 LLM
python scripts/install_free_llms.py --refresh --dry-run  # 从 Kilo 拉实时清单

--probe-foreign 会实测各国外平台可达性，并从 OpenRouter 公开列表拉出当前所有定价为 0 的免费模型。 注意：新拉到的模型不在实测清单内，必须先 --verify 确认工具调用可用再推荐。

场景 D：用户要定期巡检（定时任务 / 每周报告）

python scripts/install_free_llms.py --report          # 一轮体检 + 国外探测，输出汇总
python scripts/install_free_llms.py --watch           # 常驻后台，状态变化才报告

--report 适合做成自动化（每周跑一次，出变化报告）。 --watch 长期挂机（Windows 可交给计划任务），每 30 分钟一轮，只在状态变化时打印。

python scripts/install_free_llms.py --watch --watch-interval 1800
python scripts/install_free_llms.py --watch --watch-rounds 3 --watch-interval 3600

状态持久化在 ~/.workbuddy/free_llm_watch_state.json；变化写 ~/.workbuddy/free_llm_watch.log。

场景 E：用户要清理

python scripts/install_free_llms.py --uninstall

只移除本脚本添加的（按 vendor 识别），保留用户自己的模型。

场景 F：给不读图的模型加读图桥接（MCP）

问题：glm-4-flash（及多数免费文本模型）不读图，但 Claude Code 又依赖它的标准 工具调用干活。智谱能读图的模型（glm-4.1v-thinking-flash 等）用的是自定义「文本框」 伪工具调用（见上方踩坑表），不能进 Claude Code 切换器。

方案：用 tools/vision_bridge_mcp.py 起一个 MCP server，提供 read_image(path) 工具。 glm-4-flash 遇到图片路径时调 read_image，MCP 把图发给读图后端、回填文字描述—— 纯文本模型也能「看」图，且不破坏 agent 循环（比透明代理更安全、调试简单）。

读图后端优先级（自动回退）：

1. 智谱 glm-4.1v-thinking-flash（免费，需 ZHIPU_API_KEY，质量最好）
2. Kilo Omni nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free（免 key，兜底）

部署步骤：

# 1) （可选但推荐）设置智谱 key；不设置也能用，只是直接走 Kilo 兜底
export ZHIPU_API_KEY=你的智谱key   # Windows: set ZHIPU_API_KEY=...

# 2) 在 ~/.claude/settings.json（或某个 profile）注入 mcpServers：

{
  "mcpServers": {
    "vision-bridge": {
      "command": "python",
      "args": ["/绝对路径/free-llm-installer/tools/vision_bridge_mcp.py"]
    }
  }
}

# 3) 重启 Claude Code。对话里把图片本地路径给它，模型会经 read_image 自动看图。

• command 填 python（任意 Python 3 即可，脚本零依赖仅用标准库）；若 python 不在 PATH，改成绝对路径（如 Windows 隔离 python.exe）。
• 想只在某些 profile 启用：把上面的 mcpServers 写进对应 ~/.claude/profiles/xxx.json 即可，切换 profile 时自动带上/卸下。
• 已内置容错：智谱过载/未配 key 会自动降级到 Kilo，不会让「看图」整体失败。

场景 G：接入阶跃星辰 StepFun Step 5 Preview（限时免费·全能力）

特点：step-5-preview 是阶跃星辰旗舰，OpenAI 兼容（/v1/chat/completions，Bearer ）， 支持 1M 上下文 + 工具调用 + 多模态(base64 读图) + 推理。免费 = 限时试用（平台额度）， 非永久，重任务白嫖期可用，长期默认仍建议 glm-4-flash（永久免费）。本机已实测 tool_calls / base64 读图 / reasoning 全部可用。

接入三选一（推荐全做）：

# 1) WorkBuddy models.json（直连，保留完整读图/工具/推理能力）
python scripts/install_free_llms.py --stepfun-key <你的StepFun Key>
#   会写入 id=step-5-preview、supportsToolCall/Images/Reasoning 全 true 的条目。
#   不给 key 不会安装（与 --zhipu-key 同机制）。

# 2) Claude Code profile（走 ccproxy 透明代理 → Anthropic 格式）
#    在 ~/.claude/profiles/stepfun.json 写入（key 明文或环境变量）：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3459",
    "ANTHROPIC_MODEL": "step-5-preview",
    "API_TIMEOUT_MS": "600000",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000"
  },
  "model": "step-5-preview",
  "modelSettings": { "step-5-preview": { "effortLevel": "medium" } }
}

ANTHROPIC_AUTH_TOKEN 必须填你本机 ccproxy 生成的 client_token（首次启动 ccproxy 时 写入 ~/.claude-code-proxy.json 的 client_token 字段，或启动日志里的 "generated a client token"）。 每个安装实例不同，不要照抄别人的值，否则网关拒连（401 authentication_error）。

# 3) 切换器按钮（tools/claude_model_switcher.py 已内置两个 StepFun 按钮）：
#    ·「StepFun Step 5 (推理·限时免费)」  → port 3459，思考开（默认）
#    ·「StepFun Step 5 (无推理·限时免费)」→ port 3460，加 --no-reasoning（思考关，秒回）
#    key 从环境变量 STEPFUN_API_KEY 读取，不写死在脚本里，避免随技能泄密。
#    启动：pythonw tools/claude_model_switcher.py  （Windows 双击也可，.cmd 启动器见仓库外本地副本）
#    点按钮后重启 Claude Code 即可。
#
# 无推理网关手动启动（Claude Code 走 ccproxy 时才需要，直连 WorkBuddy 不用）：
#    python tools/ccproxy.py --port 3460 \
#      --upstream https://api.stepfun.com/v1/chat/completions \
#      --model step-5-preview --key $STEPFUN_API_KEY --no-reasoning

推理 vs 无推理（按需切换）：

• step-5-preview 是推理模型，答题前默认先"想"很久 → 墙钟慢（重 agentic 任务可达数分钟）。
• 加 --no-reasoning 后 ccproxy 向上游发 chat_template_kwargs: {"enable_thinking": false}， 模型直接出答案，同 prompt 约快 2 倍（实测 10s → 5s）。
• 两个 profile：~/.claude/profiles/stepfun.json（3459，思考开）、 stepfun-nothink.json（3460，思考关）。切换器两个按钮分别对应，互不冲突（不同端口）。

关键注意（必读）：

• Claude Code 经 ccproxy 现在也能原生读图了：本技能内置的 ccproxy.py 已修复图片转发 （2026-10-12），把 Anthropic image 块转成 OpenAI image_url 直发上游。所以 StepFun / omni 在 Claude Code 里贴图即看，无需 vision bridge 兜底。
• 想用 vision bridge 给纯文本模型加读图，仍走场景 F；StepFun 自带读图，直接用即可。
• StepFun 偶发空 content（上游 quirks）：个别请求返回 200 但 content 为空。本技能内置 ccproxy.py 已加 空回复自动重试（retry_empty，默认 2 次），非流式请求空回复会自动 重发，实测 5/5 稳定返回正文；流式不受重试保护。仍偶发空时换一次即可。
• effortLevel: medium / forward_images: true：关重推理避免空 content，开图片转发。
• StepFun 免费非永久，监控下线用 --watch（平台额度耗尽会变 401）。

桥接层专项优化（ccproxy 已内置，针对"推理模型很慢"）：

• WorkBuddy 直连 vs Claude Code 经 ccproxy：能力完全一致（都走官方 OpenAI 端点），区别仅在于 Claude Code 多一层本地代理；代理已支持图片，无能力损失。

其他命令

python scripts/install_free_llms.py --list                # 列出已配置的模型
python scripts/install_free_llms.py --dry-run             # 只看要做什么，不写文件
python scripts/install_free_llms.py --force               # 覆盖同 id 的现有配置
python scripts/install_free_llms.py --zhipu-key KEY      # 安装智谱 GLM 梯队
python scripts/install_free_llms.py --deepseek-key sk-xxx # 顺便加 DeepSeek（付费！）
python scripts/install_free_llms.py --stepfun-key KEY    # 安装阶跃星辰 Step 5 Preview（限时免费）
python scripts/install_free_llms.py --models /path/to/models.json
python scripts/install_free_llms.py --watch --watch-log /path/to/watch.log

监控相关参数

关键实现细节

• 配置文件位置：~/.workbuddy/models.json（脚本自动探测，也支持 XDG_CONFIG_HOME）。
• 原子写入：先写 .tmp 再 os.replace，避免写一半损坏。
• 每次写入前自动备份到 backups/models.json.bak-install-free-<时间戳>。
• 网络抖动重试：SSL 中断等 NET 类错误自动重试 2 次（间隔 3s）；429 在工具验证阶段重试 2 次（间隔 8s）。

故障诊断：SSL: UNEXPECTED_EOF_WHILE_READING

报这个错时先怀疑代理链路，不要先怀疑模型（2026-10-14 踩坑：误以为模型下架，实测模型完全正常）。 ~/.claude-code-proxy.json 的 upstream.proxies 是易腐配置——本地代理端口会随 VPN 客户端 重启/换节点漂移，出现「端口还在监听但对该站 TLS 握手必断」的情况。

三路对比定位（一次跑完就知道是哪条链路坏）：

python - <<'PY'
import json, time, urllib.request
URL='https://api.kilo.ai/api/gateway/v1/chat/completions'
BODY=json.dumps({'model':'liquid/lfm-2.5-2.6b:free','max_tokens':200,
                 'messages':[{'role':'user','content':'hi'}]}).encode()
def t(label, opener):
    t0=time.time()
    try:
        r=urllib.request.Request(URL,data=BODY,headers={'content-type':'application/json',
                          'Authorization':'Bearer anonymous'})
        with opener.open(r,timeout=45) as resp: resp.read()
        print('%-18s %.1fs OK' % (label,time.time()-t0))
    except Exception as e:
        print('%-18s FAIL %s: %s' % (label,type(e).__name__,str(e)[:70]))
t('direct',   urllib.request.build_opener(urllib.request.ProxyHandler({})))
t('env-proxy',urllib.request.build_opener(urllib.request.ProxyHandler()))
PY

再单独试配置里那个代理端口（换成实际端口号），哪条 FAIL 就是哪条的问题。

修复：启动时加 --proxy ""（强制直连、忽略环境变量、清空 proxies 池）：

python tools/ccproxy.py --port 3461 \
  --upstream https://api.kilo.ai/api/gateway/v1/chat/completions \
  --model liquid/lfm-2.5-2.6b:free --key anonymous --proxy ""

启动日志会打印 [ccproxy] upstream route: direct（或代理列表）确认生效。 VPN 是 TUN 透明模式时直连就等于已走隧道，不需要再套一层本地代理。

• 非法 JSON 拒绝写入：配置损坏时报错退出，不覆盖用户数据。
• 必须带浏览器 UA：Kilo / Zen 前有 Cloudflare，Python 默认 UA 会被拦。
• 推理模型 token 预算：verify/probe 对 supportsReasoning 模型自动放大 max_tokens，避免 reasoning 截断。

注意事项（转述给用户时用）

• 免费模型不适合当生产主力：额度小，agent 循环一轮要 5-20 次调用。
• 免费池高峰会 429（尤其智谱 glm-4.7-flash / Kilo omni 偶发 16/16）。kilo-auto/free 的自动路由能缓解这个问题。
• 国外平台（Groq/Together/HF/Mistral/Google）从国内网络基本不可达或被封；唯一稳定可达且免 key 的是 OpenRouter 公开列表。
• 免费渠道的数据可能进上游训练集，不要放密钥、用户数据、生产代码。
• 政策随时变。--refresh / --probe-foreign 能查到当前真实情况，但「能列出来」≠「能调用」，仍需 --verify 确认。
• 免费模型会突然限流或下线。--watch / --report 挂后台跑就能第一时间知道。