my-free-code

这是什么？适合谁？

my-free-code（hkqr/my-free-code）是一个面向 Claude Code 等编程 Agent 的多供应商 AI 网关：提供模型路由、流式输出、工具调用、推理、故障切换与本地模型支持，帮 Agent 摆脱单一模型供应商的绑定。

核心价值：给编程 Agent 加一层「模型路由 + 故障切换」的网关——同一套 Agent 可随时切到更便宜或更可用的模型，支持本地模型，兼顾成本管控与可用性。

适合人群：

• 用 Claude Code / 类 Agent 做开发、想自由换模型的开发者
• 需要多供应商故障切换的高可用需求者
• 想接本地模型降低成本的自建用户

使用前提：一个编程 Agent（Claude Code 等）；至少一个可用的模型供应商或本地模型服务。

准备工作

1. 编程 Agent：Claude Code 或兼容的 CLI Agent。
2. 模型供应商：准备一个或多个模型 API（或本地模型）。
3. 网关配置：按 README 配置路由规则与供应商。
4. 成本：MIT 开源免费；模型按所选供应商计费。
5. 时间预算：安装 + 接入第一个模型约 15 分钟。

快速上手（3 步）

第一步：安装网关

git clone https://github.com/hkqr/my-free-code
cd my-free-code
pip install -r requirements.txt   # 具体配置以 README 为准

第二步：配置供应商

配置要路由的模型供应商与本地模型地址。

第三步：接入 Agent

把 Claude Code 等 Agent 指向网关，开始按规则路由。

成功判定：让 Claude Code 通过网关调用不同供应商/本地模型，并在某供应商故障时自动切换。

初级用法

模型路由

按规则把请求路由到不同供应商或本地模型。

流式输出

支持流式返回，保持 Agent 交互的实时性。

故障切换

某供应商不可用时自动切换到备用供应商。

高级玩法

本地模型接入

接本地部署模型，降低长期推理成本。

成本管控

按任务类型路由到不同价位的模型，控制开销。

工具与推理分离

把工具调用与推理请求按需分发到不同模型。

小技巧

1. 先单供应商跑通：再加多供应商与切换规则。
2. 故障切换要留余量：备用供应商至少一个。
3. 本地模型预热：冷启动慢，提前拉起。
4. 记录路由日志：便于审计成本与可用性。
5. Key 走环境变量：不落盘。

常见踩坑

踩坑 1：路由规则错误

• 现象：请求发到错误的供应商或直接失败。
• 原因：路由规则配置不当。
• 解决：简化规则，先按默认再逐步细化。

踩坑 2：故障切换失效

• 现象：主供应商挂了但没切到备用。
• 原因：备用供应商未配置或健康检查缺失。
• 解决：确认健康检查与备用配置。

踩坑 3：本地模型性能不足

• 现象：本地模型响应慢、质量下降。
• 原因：本地算力与模型规模不匹配。
• 解决：按任务难度分流，重任务用云端模型。

踩坑 4：协议兼容问题

• 现象：Agent 请求格式与供应商不兼容。
• 原因：各供应商协议差异。
• 解决：以网关的协议适配为准，必要时自定义映射。

踩坑 5：项目较新

• 现象：某些供应商适配不全。
• 原因：项目 2026-08 创建。
• 解决：关注更新，按需自写适配。

常见问题 FAQ

Q1: 和普通 API 网关的区别？

A: 它面向编程 Agent，强调模型路由、流式、工具调用与本地模型支持。

Q2: 支持哪些 Agent？

A: 面向 Claude Code 等编程 Agent，具体兼容列表以仓库为准。

Q3: 免费吗？

A: MIT 开源免费；模型调用按供应商计费。

Q4: 能省成本吗？

A: 通过路由到更便宜的模型或本地模型可降低成本，但需权衡质量。

Q5: 适合生产吗？

A: 社区 fork 较多（31），但项目较新，生产使用需自行验证。

进阶学习建议

掌握基础后，建议深入：

1. 配置本地模型 + 云端模型的双层路由，把轻任务留在本地。
2. 研究故障切换策略，设计多供应商高可用拓扑。
3. 为不同 Agent 任务类型定制路由规则，实现精细化成本管控。

参考链接

• 官方仓库

最后更新：2026-08-29 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成