跳到主要内容
AI教程

使用 My Free Code 构建多提供商编程智能体网关

安装 My Free Code v0.8，配置云端或本地模型，并实现智能体接入、分层路由、有序回退、管理监控与本地安全防护。

AI我搜编辑部阅读约 13 分钟
My Free Code 多提供商编程智能体网关

My Free Code 的功能

My Free Code v0.8 是一个面向 Claude Code 和其他编程智能体的独立多提供商网关。它会运行一个本地 FastAPI 网关，用于接收智能体请求、选择已配置的模型、将请求转换为相关提供商所需的格式，并将响应以流式方式返回客户端。该项目与 Anthropic 无关联。

该网关支持位于 /v1/messages 的 Anthropic Messages 协议、位于 /v1/messages/count_tokens 的 Anthropic token 计数接口，以及位于 /v1/responses 的 OpenAI Responses 兼容端点。它还通过 /v1/models 提供模型发现功能，通过 /health 提供健康检查端点，通过 /admin 提供本地 Admin UI，并在 /api/admin/* 下提供需要身份验证的管理 API。

主要功能

  • 多种智能体协议：通过一个网关接收 Anthropic Messages 和 OpenAI Responses 兼容请求。
  • 智能体能力：处理流式服务器发送事件（Server-Sent Events）、工具定义、工具调用、工具结果、图像以及推理元数据透传。
  • Claude 分层路由：为 Fable、Opus、Sonnet 和 Haiku 请求分配不同的上游模型。
  • 弹性路由：使用有序模型回退、提供商健康状态退避、按提供商设置的并发控制以及速率窗口控制。
  • 稳定的模型身份：即使路由器将请求发送给其他提供商，也能保持网关公开模型身份不变。
  • 推理标准化：将 Claude 风格的思考意图与提供商特有的请求字段分离。
  • 本地模型支持：通过 OpenAI 兼容端点连接 Ollama、LM Studio 或 llama.cpp。
  • 智能体启动器：为 Claude Code、Codex、Pi、OpenCode、Cline、Hermes、DeepSeek Harness、Grok Build 和 Muse Code 准备代理环境。

提供商目录包含大量云服务和本地运行时。常见的 OpenAI 兼容提供商使用共享传输层，而采用特殊身份验证方式或协议的提供商则需要专用适配器。因此，在没有针对具体提供商进行配置的情况下，不应将目录中的条目理解为对通用支持的承诺。

架构的工作原理

             编程智能体 / IDE
                      |
          +-----------+-----------+
          |                       |
    Anthropic Messages       OpenAI Responses
          |                       |
          +-----------+-----------+
                      |
                FastAPI 网关
                      |
                 模型路由器
                      |
          +-----------+-----------+
          |                       |
        主模型                   回退模型
          |                       |
          +-----------+-----------+
                      |
                提供商运行时
                      |
       +--------------+--------------+
       |              |              |
 OpenAI 兼容适配器   专用适配器    本地运行时
       |              |              |
     API          提供商 API   Ollama/LM Studio

该设计将传入的线协议与路由和提供商集成相分离。HTTP 适配器接收请求，应用层选择并执行路由，而提供商运行时则通过共享的 OpenAI 兼容传输层、专用适配器或本地运行时进行通信。CLI 启动器仍作为独立层，用于配置客户端环境，并将执行委托给已安装的编程智能体。

安装网关

前置条件

  • Python 3.10 或更高版本。
  • 仓库的本地副本。
  • 计划使用的所有远程提供商的凭据。
  • 已安装并可通过 PATH 访问的目标编程智能体客户端。

1. 创建虚拟环境

python -m venv .venv

2. 激活环境并安装依赖项

在 Windows PowerShell 中运行：

.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
copy .env.example .env

在 macOS 或 Linux 中运行：

source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env

3. 启动 My Free Code

python -m my_free_code

默认情况下，可通过 http://127.0.0.1:8082 访问网关。你可以通过 http://127.0.0.1:8082/health 检查服务，并在 http://127.0.0.1:8082/admin 打开本地 Admin UI。

配置模型和提供商

编辑生成的 .env 文件，选择默认模型、为 Claude 各层级分配模型并定义有序回退。以下示例使用了来自多个提供商的模型：

MODEL=open_router/openrouter/free
MODEL_SONNET=deepseek/deepseek-chat
MODEL_HAIKU=groq/llama-3.3-70b-versatile
MODEL_OPUS=nvidia_nim/meta/llama-3.3-70b-instruct
FALLBACK_MODELS=deepseek/deepseek-chat,ollama/llama3.1

将相应提供商的 API 密钥添加到 .env。请以 .env.example 作为受支持配置字段的参考。更改环境配置后，请重启网关。

MODEL 用于选择网关的通用模型。MODEL_SONNET、MODEL_HAIKU 和 MODEL_OPUS 等层级专用变量允许路由器将 Claude 模型层级定向到不同的上游服务。FALLBACK_MODELS 是一个以逗号分隔且具有顺序的备用模型列表。

连接 Claude Code

选项 1：手动设置环境

在 Windows PowerShell 中，将 Claude Code 指向本地的 Anthropic 兼容网关：

$env:ANTHROPIC_BASE_URL="http://127.0.0.1:8082"
$env:ANTHROPIC_AUTH_TOKEN="local"
$env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
claude

基础 URL 会将 Claude Code 请求重定向到 My Free Code，而模型发现功能则允许客户端查询网关的模型目录。

选项 2：使用启动器适配器

python -m my_free_code.cli.mfc claude

启动器会准备本地代理环境，然后将参数传递给已安装的 Claude Code 客户端。它本身不会安装客户端。

启动其他编程智能体

同一套启动器抽象还支持多个其他客户端：

python -m my_free_code.cli.mfc codex
python -m my_free_code.cli.mfc pi
python -m my_free_code.cli.mfc opencode
python -m my_free_code.cli.mfc cline
python -m my_free_code.cli.mfc hermes
python -m my_free_code.cli.mfc deepseek-harness
python -m my_free_code.cli.mfc grok
python -m my_free_code.cli.mfc muse

运行其中任何一条命令前，请确认对应客户端已安装且可通过 PATH 访问。启动器只负责设置网关环境并调用现有程序。

理解有序回退

假设环境中包含以下路由配置：

MODEL_SONNET=deepseek/deepseek-chat
FALLBACK_MODELS=groq/llama-3.3-70b-versatile,ollama/llama3.1

Sonnet 请求首先会发送到 deepseek/deepseek-chat。如果该尝试在产生输出前失败，路由器将尝试 groq/llama-3.3-70b-versatile。如果第二次尝试也在输出前失败，则会尝试 ollama/llama3.1。

Claude Code
    |
    v
deepseek/deepseek-chat
    |
    | 输出前失败
    v
groq/llama-3.3-70b-versatile
    |
    | 输出前失败
    v
ollama/llama3.1

一旦流式响应已经提交输出，网关就不会在后台悄然切换提供商。这样可以避免重复执行一轮对话，或将不同模型的部分响应拼接在一起。

使用本地模型

Ollama

单独启动 Ollama 服务，然后配置其 OpenAI 兼容基础 URL 和模型：

OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
MODEL=ollama/llama3.1

LM Studio

启动 LM Studio 本地服务器并使用：

LM_STUDIO_BASE_URL=http://127.0.0.1:1234/v1
MODEL=lmstudio/qwen3.5-coder

llama.cpp

运行 llama.cpp 服务器并进行如下配置：

LLAMACPP_BASE_URL=http://127.0.0.1:8080/v1
MODEL=llamacpp/my-model

本地运行时也可以出现在 FALLBACK_MODELS 中，从而在远程请求于输出内容前失败时，让本地模型充当备用选项。

配置推理行为

网关接受 Claude 风格的思考意图，并在提供商适配器转换请求之前对其进行标准化。支持的模式包括：

auto
on
off

可选的推理强度级别包括：

low
medium
high

这种分离方式使面向智能体的推理策略独立于提供商特有的字段。每个提供商适配器都可以根据上游提供商的文档，将标准化后的模式和强度映射到相应字段。

监控网关

在本地打开 Admin UI：

http://127.0.0.1:8082/admin

需要身份验证的 JSON Admin API 包括：

GET /api/admin/status
GET /api/admin/models
GET /api/admin/providers

使用这些端点检查网关状态、模型目录和已配置的提供商。管理端点需要身份验证，并且应保持私有。

高级技巧

保持公开模型身份稳定

请求可能会被路由到层级专用模型或备用提供商，但网关会保持其公开模型身份稳定。因此，客户端应用程序可以与网关模型交互，而无需跟踪每一次上游路由决策。

有意识地设计回退顺序

按照实际尝试顺序，将模型准确地放入 FALLBACK_MODELS。请考虑提供商的可用性，以及是否应将本地运行时作为最后选项。请记住，只有在提交流式输出之前才会执行回退。

注意提供商之间的差异

许多提供商使用通用的 OpenAI 兼容传输层，但特殊的身份验证方案或协议需要专用适配器。请确认相关提供商适配器和凭据可用，而不要假设目录中的所有条目都具有相同行为。

在需要时直接使用协议端点

  • 将 Anthropic Messages 请求发送到 /v1/messages。
  • 通过 /v1/messages/count_tokens 计算 Anthropic 格式的 token 数量。
  • 通过 /v1/responses 使用 OpenAI Responses 兼容接口。
  • 通过 /v1/models 发现模型。
  • 通过 /health 检查服务健康状态。

运行测试套件

pytest -q

该仓库包含针对路由、协议转换、身份验证、推理、模型目录和流式处理原语的确定性测试。修改网关、路由或提供商代码后，请运行这些测试。

安全指南

My Free Code 适用于本地使用。请采取以下预防措施：

  • 保持 HOST=127.0.0.1，使服务仅绑定到本地计算机。
  • 设置一个强度足够的 PROXY_AUTH_TOKEN。
  • 切勿将 .env 文件提交到源代码管理系统。
  • 不要将 Admin 端点直接暴露到互联网。
  • 将提供商凭据保存在环境变量或配置中。网关不会把某个提供商的凭据发送给另一个提供商。

总结

My Free Code 在编程智能体与多个云端或本地模型提供商之间提供本地兼容与路由层。安装 Python 依赖项、配置模型和凭据并启动网关后，你可以连接 Claude Code 或其他受支持的客户端，按 Claude 层级分配模型，并构建可控的回退链。协议、路由、提供商和启动器各层相互分离，也让该项目更容易检查和测试。