Claude Code 对接 OpenAI 兼容网关：EdgeFn / LiteLLM / 多模型切换实践

归类：Claude Code / LiteLLM / OpenAI 兼容网关 / 模型路由

一、先说结论

如果后续要让 Claude Code 通过 EdgeFn 这类 OpenAI 兼容平台工作，不一定非要把默认 claude 命令永久改成别名脚本，但在日常使用里，保留一个单独入口通常是最稳的。

推荐优先级通常是：

保留原始 claude 不动，再新增 claude-edgefn
当你确认主要工作流都走第三方网关后，再决定是否把 claude 映射到网关版入口
如果需要频繁切换多个模型或多个平台，最好引入统一的“网关启动脚本 + 环境文件 + 模型别名”方案，而不是每次手写环境变量

如果你没有 Claude Max / Pro / Teams / Enterprise，也没有 Anthropic Console API key，而只有第三方平台代理模型，那么默认浏览器登录式初始化通常是走不通的。

这不代表 Claude Code 不能用，而是说明：

默认登录流不适合你的接入方式
你需要改走“Claude Code -> LLM gateway -> 第三方平台”这条部署路径
日常入口通常会变成 claude-edgefn 这类包装命令，而不是裸跑的 claude 登录流程

二、这条链路是不是官方支持

1. 官方支持的部分

Anthropic 官方文档明确支持 Claude Code 通过 LLM gateway 工作，并给出了 LiteLLM 的配置说明。

官方支持的核心点是：

Claude Code 可以通过 ANTHROPIC_BASE_URL 指向一个统一的网关入口
Claude Code 可以通过 ANTHROPIC_AUTH_TOKEN 等方式向网关传递鉴权信息
官方文档给出了 LiteLLM 作为网关的示例配置

也就是说，下面这半段思路属于官方文档明确覆盖的范围：

text

Claude Code -> LLM Gateway

2. 不是官方背书的部分

Anthropic 同时也明确说明：

LiteLLM 是第三方代理服务
Anthropic 不对 LiteLLM 的安全性、功能性或持续兼容性做背书、维护或审计

所以：

text

Claude Code -> LiteLLM(local)

这条路是“官方文档允许并介绍的做法”，但不是“Anthropic 官方产品能力的一部分”。

3. 本次链路里自定义兼容的部分

本次使用的是：

text

Claude Code -> LiteLLM(local) -> EdgeFn -> MiniMax-M2.5

这里真正属于我们自己定义的兼容层，是后半段：

EdgeFn 提供的是 OpenAI 风格接口
当前实际可用的是 /v1/chat/completions
Claude Code 原生更偏向 Anthropic Messages 语义
因此需要借助 LiteLLM 把 Anthropic 风格请求转成下游 OpenAI 风格请求

换句话说：

Claude Code -> LiteLLM：官方文档覆盖
LiteLLM -> EdgeFn -> MiniMax-M2.5：属于自定义接入方案

三、为什么不能直接在 Claude Code 初始化页里选 EdgeFn

Claude Code 初始化页里的第三方平台主要指：

Amazon Bedrock
Google Vertex AI
Microsoft Foundry

这类是 Claude Code 文档单独列出的企业平台集成。

而 EdgeFn 这类 OpenAI 兼容平台不在初始化向导的标准选项里。

如果你直接面对的是：

text

https://xxx/v1/chat/completions

通常不能直接靠初始化页完成接入，而是要走：

Claude Code 指向一个 Anthropic 风格网关
网关再把请求路由到 OpenAI 兼容提供方

三点五、LiteLLM `MASTER_KEY` 不是下游平台 token

这是本地部署里最容易混淆的一层。

如果链路是：

text

Claude Code -> LiteLLM(local) -> EdgeFn -> MiniMax-M2.5

那至少会出现两类密钥：

下游平台密钥
- 例如 EDGEFN_API_TOKEN
- 只用于 LiteLLM -> EdgeFn
代理层密钥
- 例如 LITELLM_MASTER_KEY
- 用于 LiteLLM /ui 登录、管理接口和代理层鉴权

所以 LiteLLM Admin UI 登录页里看到的：

text

Username: admin
Password: MASTER_KEY

这里的 MASTER_KEY 指的是 LiteLLM Proxy 自己的管理密钥，不是 EdgeFn token，也不是 Claude 账号密码。

更稳妥的做法是：

单独生成一个本地代理管理密钥
不要复用下游平台 token 作为 LiteLLM MASTER_KEY
需要让 Claude Code 访问代理时，再让客户端鉴权 token 与 MASTER_KEY 对齐，或者使用后续生成的虚拟 key

一条简单、可维护的本地约定通常是：

text

EDGEFN_API_TOKEN      = 下游平台密钥
LITELLM_MASTER_KEY    = 本地代理管理密钥
CLAUDE_EDGEFN_AUTH_TOKEN = Claude Code 访问 LiteLLM 时使用的代理层 token

在最小可用方案里，最后两个值可以先保持一致；但语义上它们仍然属于“代理层”，不属于下游平台。

四、没有订阅、只有第三方平台代理模型时，到底能不能用 Claude Code

可以用，但要区分“默认登录初始化”和“网关部署”这两件事。

Anthropic 官方文档当前说明是：

Claude Code 登录认证需要 Pro、Max、Teams、Enterprise 或 Console 账户
免费 Claude.ai 计划不包含 Claude Code 访问权限
也可以通过第三方 API provider 使用 Claude Code，例如 Bedrock、Vertex、Foundry

这意味着：

如果你走的是 Claude.ai 免费账户登录页，浏览器会要求升级，这是正常行为
如果你没有 Anthropic 官方订阅或 Console key，就不要把“浏览器登录失败”理解成“Claude Code 不能用”
你此时要走的是部署型接入，而不是订阅型接入

对 EdgeFn 这类平台来说，更准确的说法应该是：

不是“Claude Code 默认无法初始化”
而是“Claude Code 默认登录式初始化不适合这类 OpenAI 兼容平台”

五、`claude-edgefn` 到底是什么

claude-edgefn 不是一个新平台，也不是 LiteLLM 本身。

更准确地说，它是一个本地包装入口。

它的职责通常有三件：

先确保本地 LiteLLM 网关已经启动
再注入 Claude Code 所需的环境变量，例如：
- ANTHROPIC_BASE_URL
- ANTHROPIC_AUTH_TOKEN
- ANTHROPIC_DEFAULT_SONNET_MODEL
最后再调用真正的 claude

所以角色关系应该这样理解：

text

claude-edgefn = 面向用户的本地启动入口
LiteLLM = 本地协议兼容与模型路由网关
EdgeFn = 下游平台代理平台
MiniMax-M2.5 = 实际推理模型

也就是说：

claude-edgefn 不是平台
claude-edgefn 不是网关
claude-edgefn 是“启动 Claude Code 并接入指定网关配置”的包装器

五点五、为什么 `/openapi.json` 可能 500，但代理仍然能用

如果你访问：

text

http://127.0.0.1:4000/

看到的是 Swagger 页面报错，例如：

text

Failed to load API definition
Fetch error
Internal Server Error /openapi.json

这通常不代表 LiteLLM 到下游模型的转发一定失败。

在本地环境里，更常见的含义是：

LiteLLM 当前版本和运行时依赖存在兼容问题
FastAPI / Pydantic 的 OpenAPI schema 生成失败
但实际 /v1/messages、/chat/completions 或 /model/info 等核心转发路径仍然可用

本次排障中，/openapi.json 500 的直接表现和 Python 3.9 环境下的类型兼容问题有关，因此应把它理解成：

“管理页面的 OpenAPI 展示坏了”
而不是“整个代理链路不可用”

更安全的判断方式应该优先看：

Claude Code 实际是否能走完整链路
/ui 是否能登录
/model/info 是否能返回当前模型信息
本地日志里是否有成功请求

六、`claude-gateway` 和 `claude-router` 又是什么关系

这两个名字都不是 Claude Code 官方固定命令，更适合作为你自己本地工具链里的命名约定。

推荐按职责拆开理解：

`claude-gateway`

更偏基础设施层。

它负责：

管理 LiteLLM 或其他本地网关进程
生成或加载 config.yaml
维护本地端口、日志、健康检查
管理 LaunchAgent 常驻服务
暴露 /ui、Swagger、日志入口

一句话理解：

claude-gateway 关注的是“网关服务怎么活着”

`claude-router`

更偏用户交互层。

它负责：

切换当前使用的平台 profile
切换当前使用的真实模型
选择别名映射
启动 claude
展示当前激活的是哪条路由

一句话理解：

claude-router 关注的是“这次我想走哪条路”

四、后续是不是都必须使用 `claude-edgefn`

不必须，但很建议。

方案 A：保留 `claude` 原样，新增 `claude-edgefn`

这是最推荐的做法。

优点：

不影响原始 Claude Code 登录流和官方账号使用
第三方网关故障时，不会把原始 claude 一起带坏
更容易做多平台并存，例如：
- claude
- claude-edgefn
- claude-bedrock
- claude-vertex

适合：

还在试验第三方平台
需要同时保留 Anthropic 官方直连
想把风险控制在最小范围

方案 B：把 `claude` 直接别名到 `claude-edgefn`

例如在 ~/.zshrc 里写：

bash

alias claude="claude-edgefn"

优点：

使用最省心
日常无需区分命令

缺点：

之后看到的所有 claude 行为，其实都建立在你的本地兼容层之上
一旦网关、LiteLLM、本地端口或第三方模型异常，排障会更绕

适合：

你已经确认之后基本都走第三方网关
不再依赖 Claude 官方登录态

方案 C：保留 `claude`，再提供一个显式切换器

例如统一提供：

bash

claude-router edgefn
claude-router anthropic
claude-router vertex

或者：

bash

use-llm edgefn
use-llm anthropic

本质上是在 shell 层切换一组环境变量，而不是替换 Claude Code 本体。

这更适合长期多模型、多平台并存。

七、为什么会显示自己是 Sonnet 4.6

这是本次兼容层里最容易让人误解的一点。

Claude Code 当前会根据模型别名、默认模型映射和状态栏展示逻辑，认为自己正在调用一个 Claude 风格模型。

本次为了让 Claude Code 顺利通过模型选择流程，我们把下游网关别名映射成了：

text

claude-sonnet-4-6

而真实下游模型其实是：

text

MiniMax-M2.5

所以你看到：

状态栏显示 Sonnet 4.6
回答“我是什么模型”时说自己是 Claude Sonnet 4.6

本质上都是别名映射带来的结果。

这是不是“隐藏真实模型”

是的，本质上就是别名屏蔽了真实下游模型。

但要分清两个层面：

功能层面

对 Claude Code 来说，这种别名映射是有价值的。

它能：

让模型选择流程更稳定
让 sonnet / opusplan 这类别名继续可用
降低 Claude Code 对非原生模型名的兼容摩擦

认知层面

它会带来明显的认知偏差。

你在 UI、日志或模型自述里看到的是 Claude Sonnet 4.6，但真实调用的是 MiniMax。

所以长期使用时，至少要在网关日志或管理面板里把下面三层都展示清楚：

Claude Code 看到的别名
LiteLLM 暴露的 model_name
真实下游 provider + model_id

有没有副作用

有，但不是“不能用”的那种副作用，而是“可观测性和预期管理”的副作用。

最常见的影响是：

状态栏模型名不再等于真实模型
对话里询问“你是什么模型”时，回答可能会偏向别名身份
团队成员可能误以为当前真的在调用 Anthropic Sonnet
工具调用、格式遵循、思维痕迹控制等行为，不一定和真正的 Claude Sonnet 一样

所以：

如果只是个人实验，这种映射可以接受
如果准备长期团队化使用，必须把真实下游路由显示做出来

如何减少这种 UI 误导

Claude Code 官方文档其实给了两个更干净的方向：

使用 ANTHROPIC_CUSTOM_MODEL_OPTION
使用 ANTHROPIC_DEFAULT_*_MODEL_NAME / _DESCRIPTION / _SUPPORTED_CAPABILITIES

对于 gateway 场景，更推荐优先考虑：

bash

export ANTHROPIC_CUSTOM_MODEL_OPTION="edgefn/minimax-m2.5"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="MiniMax M2.5 via EdgeFn"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Routed through local LiteLLM gateway"

这样你至少可以在 /model 里看到一个明确的自定义入口，而不是完全依赖 claude-sonnet-4-6 这种伪装式别名。

需要注意的是：

自定义模型入口更利于认知清晰
但某些 Claude Code 能力开关仍然更依赖内建 Claude 模型模式识别
所以很多人最终会采用“双轨制”

双轨制的意思是：

对 Claude Code 内部保留稳定的 Claude 风格 alias，确保兼容性
对人类操作层额外暴露清晰的自定义入口、日志字段和管理界面，确保可观测性

八、如果后续要接更多模型，怎么做才灵活

关键不是“继续复制更多脚本”，而是把可变项收敛到配置层。

最常见的可变项其实只有四类：

下游平台地址
下游 API key
下游模型名
Claude Code 侧暴露给自己的模型别名

推荐做法 1：一平台一套环境文件

例如：

text

~/.claude-edgefn.env
~/.claude-openrouter.env
~/.claude-custom-gateway.env

每套环境文件只定义：

API_BASE_URL
API_TOKEN
MODEL_ID
MODEL_ALIAS
LOCAL_GATEWAY_PORT

脚本逻辑保持不变，只换环境文件。

这适合：

平台之间差异比较大
你想让每个平台彼此隔离

推荐做法 2：一份模型注册表 + 一个统一入口

例如自己维护一个简单映射：

yaml

edgefn-minimax:
  api_base_url: https://api.edgefn.net/v1
  model_id: MiniMax-M2.5
  model_alias: claude-sonnet-4-6
  port: 4000

edgefn-deepseek:
  api_base_url: https://api.edgefn.net/v1
  model_id: DeepSeek-V3.2
  model_alias: claude-sonnet-4-6
  port: 4001

然后统一通过：

bash

claude-gateway use edgefn-minimax
claude-gateway use edgefn-deepseek

来选择下游模型。

这适合：

你经常切换不同模型
你希望未来继续增加更多网关后端

推荐做法 3：显式切换器 + 模型注册表 + 统一入口

这是最适合长期演进的方式。

建议把三个概念明确拆开：

text

profiles registry   -> 管理平台、模型、别名、端口、鉴权
claude-router       -> 选择当前 profile
claude-gateway      -> 启动/停止/查看本地网关

例如：

yaml

profiles:
  edgefn-minimax:
    provider: edgefn
    api_base_url: https://api.edgefn.net/v1
    actual_model: MiniMax-M2.5
    exposed_alias: claude-sonnet-4-6
    local_port: 4000

  edgefn-deepseek:
    provider: edgefn
    api_base_url: https://api.edgefn.net/v1
    actual_model: DeepSeek-V3.2
    exposed_alias: claude-sonnet-4-6
    local_port: 4001

  openrouter-qwen:
    provider: openrouter
    api_base_url: https://openrouter.ai/api/v1
    actual_model: qwen/qwen3-coder
    exposed_alias: claude-sonnet-4-6
    local_port: 4002

然后让：

claude-router use edgefn-minimax 负责切换
claude-gateway start 负责托管本地网关
claude-router run 或 claude-edgefn 负责真正启动 Claude Code

如果你只想保留一个用户入口，也可以把它们收敛成：

bash

claude-router use edgefn-minimax
claude-router run

但内部仍建议保留 claude-gateway 作为独立基础设施层。

推荐做法 4：把“Claude 侧模型名”固定，把“真实下游模型”放到网关里路由

这是最适合 Claude Code 的长期方案。

核心思路：

Claude Code 永远只看到稳定模型名，例如 claude-sonnet-4-6
真实调用哪个模型，由网关配置决定

好处：

Claude Code 侧配置最稳定
切换底层模型时不必频繁调整命令、环境变量或项目配置
便于做灰度、回滚、AB 实验

代价：

你需要自己维护“别名到真实模型”的映射关系
文档必须写清楚，避免团队误以为当前真的在调用 Claude Sonnet

九、为什么这次要把 MiniMax 暴露成 `claude-sonnet-4-6`

这是一个兼容性折中，不是最佳语义。

原因是 Claude Code 会对模型名做自己的选择和校验。为了让它顺利通过模型选择流程，本次把网关对外暴露的模型别名设成了 Claude 风格名称：

text

claude-sonnet-4-6

但实际下游模型是：

text

MiniMax-M2.5

这意味着：

对 Claude Code 而言，它认为自己在调用一个 Claude 风格模型
对网关而言，它实际把流量转发给 MiniMax

这种做法能跑通，但文档里必须讲清楚。

十、要不要建设 LaunchAgent + LiteLLM 本地看板

如果你只是偶尔个人试验，可以先不做。

但如果出现下面任一情况，就很值得建设：

你准备长期依赖第三方平台代理模型
你会接多个平台或多个模型
你想随时知道当前真实走的是哪个 provider / model
你想在不打开终端的情况下查看日志、路由和服务状态

为什么值得做

Anthropic 官方把 gateway 视作一个集中认证、路由、成本控制、审计日志的中间层。

LiteLLM 官方也提供了：

/ui 管理界面
model management
usage / logs
config-driven alias routing

所以“本地 LaunchAgent + LiteLLM UI + 日志入口”并不是偏离产品方向，而是把它从临时脚本升级成稳定的个人本地基础设施。

我的建议

对个人工作流来说，推荐顺序是：

先做统一模型注册表
再做 claude-router
再把 LiteLLM 迁到 LaunchAgent
先启用 LiteLLM 官方 UI
最后再决定是否值得自建更细的本地控制面板

也就是说，不建议一上来就自研完整看板。

更好的顺序是：

先稳定路由
再稳定服务
再增强可观测性

十一、长期维护时最容易踩的坑

1. 误以为“初始化成功”就等于“官方支持”

能跑通不代表这是 Claude Code 官方认证的 EdgeFn 集成。

更准确的说法应该是：

Claude Code 官方支持通过 LLM gateway 工作
LiteLLM 是官方文档提到的第三方方案
EdgeFn 作为 OpenAI 兼容下游，是你自己接进来的

2. 直接把私钥、路径、端口写进仓库

推荐只把方法论写进公开文档，把真实 token、本机路径、私有端口策略留在用户目录或私有文档里。

3. 让下游模型直接暴露思维痕迹

部分非 Claude 模型在兼容层下可能会输出思维痕迹文本或格式不完全一致。

这不是 Claude Code 本体问题，而是：

下游模型行为
网关转换策略
参数映射方式

共同作用的结果。

4. 把“模型切换”做成脚本复制粘贴

如果每加一个模型就复制一套新脚本，维护成本会很快失控。

更好的方式是：

固定脚本
抽离环境文件
用模型注册表管理下游映射

十二、网页录入多平台注册表，推荐做到哪一层

如果已经有本地 dashboard，下一步最值得补的不是再做更多只读卡片，而是让它真正承担“注册表控制面”的角色。

更具体一点说，推荐把能力拆成三层：

dashboard 负责录入和编辑 profile
profile 注册表负责保存 provider、model、alias、端口和脚本关系
claude-router 负责消费这份注册表并切换当前 active route

一个更完整的本地闭环通常会是：

text

网页表单 -> 写入 profile 注册表 -> 生成 env / gateway / claude 入口脚本 -> dashboard 与 claude-router 共用

这样做的好处是：

新接一个平台时，不需要手工复制脚本
route 切换不再依赖手工改环境变量
dashboard 和终端看到的是同一份 route 状态
后续增加更多 provider 时，扩展点会非常清楚

dashboard 里最值得支持的输入项

如果目的是“能在网页里真正接新平台”，最小字段集通常包括：

profile_id
provider
display_name
api_base_url
actual_model
api_token
exposed_alias
gateway_host
gateway_port

如果你还想兼顾运维和代理层管理，再加这几项会更稳：

proxy_auth_token
proxy_master_key
ui_username
ui_password
notes

在线编辑时的一个关键细节

对于已经存在的 profile，编辑表单里的 token 不应该强制回填到前端。

更安全、也更实用的做法是：

新建时要求 token 必填
编辑时允许 token 留空
如果留空，就保留原 env 文件里的 token

这样既避免把现有密钥明文重新带回界面，也不会让一次普通编辑意外清空鉴权配置。

十三、`claude-router` 的更推荐落地形态

如果你已经进入“多平台、多模型、多入口并存”的阶段，claude-router 最好不要只停留在一个 use 命令。

更实用的最小命令面通常是：

bash

claude-router list
claude-router current
claude-router use <profile-id>
claude-router run
claude-router doctor [profile-id]
claude-router remove <profile-id>

这几条命令分别承担不同职责：

list：列出当前注册表
current：输出当前 active route 的完整配置
use：切换 active profile
run：按当前 active profile 启动 Claude Code
doctor：检查 env、脚本、端口、网关存活等本地条件
remove：从注册表移除某条 route，并清理对应的本地管理文件

为什么 `doctor` 很重要

一旦 profile 不再是手工脚本，而是网页动态生成，排障入口就必须统一。

doctor 至少应该能回答这些问题：

env 文件在不在
gateway 启动脚本在不在
直达入口脚本在不在
Claude 二进制在不在
LiteLLM 二进制在不在
token / base URL / model 是否已写入
当前 gateway 端口是否真的在监听

这样用户遇到问题时，就不用再手工去翻多个目录和多个脚本。

`claude-router` 和单平台快捷入口要不要同时保留

建议同时保留。

长期更合理的职责分工是：

claude-router：统一入口，适合切平台、切 profile、做诊断
claude-edgefn / claude-newapi：单平台直达入口，适合熟练用户快速启动

也就是说：

新手或多平台用户优先用 claude-router
已经熟悉某条路由、只想快速开工时，可以继续用单平台直达入口

这两种入口并不冲突，反而应该共用同一份注册表和同一个 active route 状态。

十二、推荐的长期结构

如果你未来会继续接 OpenAI 兼容平台，推荐把结构稳定成：

text

Claude Code
  -> stable alias model (e.g. claude-sonnet-4-6)
  -> LiteLLM gateway
  -> provider route
  -> actual model

对应职责是：

Claude Code：负责交互式开发体验
LiteLLM：负责协议兼容、鉴权透传、模型路由
第三方平台：负责实际推理
模型注册表：负责维护“别名 -> 真实模型”

十三、建议的日常策略

如果你是个人使用者，最稳的方式通常是：

保留原始 claude
单独维护 claude-edgefn
用环境文件管理每个平台的 token 和模型
用稳定别名隐藏真实下游模型切换

如果你未来要扩展成团队共享方案，再把：

环境文件
路由脚本
模型注册表
端口与日志策略

整理成统一网关工具即可。

十四、推荐命名

如果你准备把这一套长期固化，推荐采用下面的命名方式：

claude-router 负责“切哪个平台、切哪个模型、启动哪个 profile”
claude-gateway 负责“本地 LiteLLM 怎么启动、停止、重启、检查健康”
claude-edgefn 作为特定 profile 的兼容快捷入口，保留给单平台直达

也就是说：

claude-edgefn 适合当前单平台快速可用
claude-router 适合长期统一入口
claude-gateway 适合做底层服务管理

如果你后续只保留一个长期推荐入口，我更倾向于：

bash

claude-router use edgefn-minimax
claude-router run

而不是继续复制出很多 claude-xxx 脚本。

十五、接入新的 OpenAI 兼容渠道时，最佳动作是什么

假设你又拿到一个新的 OpenAI 兼容渠道，例如：

newapi
openrouter
其他自建 /v1/chat/completions 平台

最重要的判断标准不是“它是不是新平台”，而是“它是不是 Claude Code 初始化页原生支持的登录提供方”。

如果它只是一个 OpenAI 兼容接口，而不是：

Claude 订阅账号
Anthropic Console
Bedrock / Vertex / Foundry

那就不要优先尝试走 Claude Code 登录页。

更稳的结论是：

这类渠道继续走本地网关部署
也就是继续沿用：

text

Claude Code -> LiteLLM(local) -> 第三方平台 -> 真实模型

换句话说：

newapi 不是替代 claude login 的路径
newapi 更适合作为新的 provider profile 接入到现有 LiteLLM / router 体系里

十六、对于 `newapi`，到底要不要再做一个新的 `claude-newapi`

短期可以做，长期不要只靠它。

短期最小可用

如果你只是想快速验证新渠道，保留一个单平台快捷入口是合理的，例如：

claude-edgefn
claude-newapi

它们适合：

单平台试用
快速排障
与旧习惯兼容

长期推荐

如果你准备持续接多个渠道，最佳结构仍然是：

text

claude-router   -> 统一入口，切平台 / 切模型 / 切 profile
claude-gateway  -> 管理 LiteLLM 本地网关生命周期
claude-edgefn   -> 单平台兼容快捷入口
claude-newapi   -> 单平台兼容快捷入口

也就是说：

claude-newapi 可以有
但它不应该成为长期唯一入口
长期真正稳定的入口仍应是 claude-router

推荐的日常体验应该像这样：

bash

claude-router use newapi-gpt54
claude-router run

而不是长期维护很多彼此独立、逻辑重复的 claude-xxx 脚本。

十七、当前 LiteLLM Local Dashboard 支持在线切换到什么程度

以当前实现为准，dashboard 已经支持的是：

查看当前 active profile
查看当前真实 provider / model / 暴露别名
执行 gateway start / stop / restart
执行 LaunchAgent install / restart / remove
在已登记的 profile 之间切换 active profile

但它目前还不支持的是：

在 UI 里直接新增一个全新的第三方渠道
在 UI 里直接编辑 provider 的 base URL / token / model
在 UI 里直接安全录入 secrets

所以当前 dashboard 更准确的定位是：

它是一个“已登记 profile 的观察与切换台”
还不是“在线配置中心”

这意味着如果你现在要接 newapi：

先把 newapi profile 加到注册表
再让 dashboard 识别并展示
然后 dashboard 才能对它做在线激活和运维操作

十八、`newapi` 接入时的最佳实现顺序

推荐顺序是：

在模型注册表中新增 newapi profile
为它准备独立 env 文件
复用同一套 LiteLLM gateway 启停逻辑
通过 claude-router use <profile> 激活
让 dashboard 只负责显示和切换，不直接持有 secrets

一个更可维护的 profile 大致长这样：

yaml

newapi-gpt54:
  provider: newapi
  api_base_url: https://<openai-compatible-base>/v1
  actual_model: gpt-5.4
  exposed_alias: claude-sonnet-4-6
  local_port: 4003
  env_file: ~/.claude-newapi.env

推荐把敏感信息只放在：

~/.claude-newapi.env
或其他用户目录下的私有 env 文件

不要直接写进公开仓库，也不要放进 dashboard 前端可见配置里。

十九、最佳方案总结

如果你现在没有 Claude Max / Pro，也没有 Anthropic Console key，而只是新增了 newapi 这种 OpenAI 兼容渠道，那么最佳方案不是：

去 claude 登录页里继续配置新渠道

而是：

继续采用 Claude Code -> LiteLLM(local) -> 第三方平台 -> 真实模型
用 claude-router 作为长期统一入口
用 claude-gateway 管理底层 LiteLLM
保留 claude-edgefn、claude-newapi 这类单平台快捷命令作为兼容入口
让 LiteLLM Local Dashboard 只负责“观察、切换、操作已存在 profile”，不要直接承担 secrets 配置中心角色

一句话版本：

新渠道继续接入现有网关体系，不走 Claude 登录页；长期统一入口选 claude-router，单平台入口只作为兼容快捷命令保留。

参考资料

Anthropic Claude Code Getting Started: https://docs.anthropic.com/en/docs/claude-code/getting-started
Anthropic Claude Code Quickstart: https://docs.anthropic.com/en/docs/claude-code/quickstart
Anthropic Claude Code LLM Gateway: https://docs.anthropic.com/en/docs/claude-code/llm-gateway
Anthropic Claude Code Third-party Integrations: https://docs.anthropic.com/en/docs/claude-code/third-party-integrations
Anthropic Claude Code Model Configuration: https://docs.anthropic.com/en/docs/claude-code/model-config
LiteLLM Admin UI: https://docs.litellm.ai/docs/proxy/ui
LiteLLM Config.yaml: https://docs.litellm.ai/docs/proxy/configs
LiteLLM Routing & Load Balancing: https://docs.litellm.ai/docs/routing

Claude Code 对接 OpenAI 兼容网关：EdgeFn / LiteLLM / 多模型切换实践 ​

一、先说结论 ​

二、这条链路是不是官方支持 ​

1. 官方支持的部分 ​

2. 不是官方背书的部分 ​

3. 本次链路里自定义兼容的部分 ​

三、为什么不能直接在 Claude Code 初始化页里选 EdgeFn ​

三点五、LiteLLM MASTER_KEY 不是下游平台 token ​

四、没有订阅、只有第三方平台代理模型时，到底能不能用 Claude Code ​

五、claude-edgefn 到底是什么 ​

五点五、为什么 /openapi.json 可能 500，但代理仍然能用 ​

六、claude-gateway 和 claude-router 又是什么关系 ​

claude-gateway ​

claude-router ​

推荐关系 ​

四、后续是不是都必须使用 claude-edgefn ​

方案 A：保留 claude 原样，新增 claude-edgefn ​

方案 B：把 claude 直接别名到 claude-edgefn ​

方案 C：保留 claude，再提供一个显式切换器 ​

七、为什么会显示自己是 Sonnet 4.6 ​

这是不是“隐藏真实模型” ​

功能层面 ​

认知层面 ​

有没有副作用 ​

如何减少这种 UI 误导 ​

八、如果后续要接更多模型，怎么做才灵活 ​

推荐做法 1：一平台一套环境文件 ​

推荐做法 2：一份模型注册表 + 一个统一入口 ​

推荐做法 3：显式切换器 + 模型注册表 + 统一入口 ​

推荐做法 4：把“Claude 侧模型名”固定，把“真实下游模型”放到网关里路由 ​

九、为什么这次要把 MiniMax 暴露成 claude-sonnet-4-6 ​

十、要不要建设 LaunchAgent + LiteLLM 本地看板 ​

为什么值得做 ​

推荐分阶段做 ​

第 1 阶段：先把服务常驻化 ​

第 2 阶段：启用 LiteLLM 自带 Admin UI ​

第 3 阶段：再决定要不要做自定义本地看板 ​

推荐结构 ​

我的建议 ​

十一、长期维护时最容易踩的坑 ​

1. 误以为“初始化成功”就等于“官方支持” ​

2. 直接把私钥、路径、端口写进仓库 ​

3. 让下游模型直接暴露思维痕迹 ​

4. 把“模型切换”做成脚本复制粘贴 ​

十二、网页录入多平台注册表，推荐做到哪一层 ​

dashboard 里最值得支持的输入项 ​

在线编辑时的一个关键细节 ​

十三、claude-router 的更推荐落地形态 ​

为什么 doctor 很重要 ​

claude-router 和单平台快捷入口要不要同时保留 ​

十二、推荐的长期结构 ​

十三、建议的日常策略 ​

十四、推荐命名 ​

十五、接入新的 OpenAI 兼容渠道时，最佳动作是什么 ​

十六、对于 newapi，到底要不要再做一个新的 claude-newapi ​

短期最小可用 ​

长期推荐 ​

十七、当前 LiteLLM Local Dashboard 支持在线切换到什么程度 ​

十八、newapi 接入时的最佳实现顺序 ​

十九、最佳方案总结 ​

参考资料 ​

Claude Code 对接 OpenAI 兼容网关：EdgeFn / LiteLLM / 多模型切换实践

一、先说结论

二、这条链路是不是官方支持

1. 官方支持的部分

2. 不是官方背书的部分

3. 本次链路里自定义兼容的部分

三、为什么不能直接在 Claude Code 初始化页里选 EdgeFn

三点五、LiteLLM `MASTER_KEY` 不是下游平台 token

四、没有订阅、只有第三方平台代理模型时，到底能不能用 Claude Code

五、`claude-edgefn` 到底是什么

五点五、为什么 `/openapi.json` 可能 500，但代理仍然能用

六、`claude-gateway` 和 `claude-router` 又是什么关系

`claude-gateway`

`claude-router`

推荐关系

四、后续是不是都必须使用 `claude-edgefn`

方案 A：保留 `claude` 原样，新增 `claude-edgefn`

方案 B：把 `claude` 直接别名到 `claude-edgefn`

方案 C：保留 `claude`，再提供一个显式切换器

七、为什么会显示自己是 Sonnet 4.6

这是不是“隐藏真实模型”

功能层面

认知层面

有没有副作用

如何减少这种 UI 误导

八、如果后续要接更多模型，怎么做才灵活

推荐做法 1：一平台一套环境文件

推荐做法 2：一份模型注册表 + 一个统一入口

推荐做法 3：显式切换器 + 模型注册表 + 统一入口

推荐做法 4：把“Claude 侧模型名”固定，把“真实下游模型”放到网关里路由

九、为什么这次要把 MiniMax 暴露成 `claude-sonnet-4-6`

十、要不要建设 LaunchAgent + LiteLLM 本地看板

为什么值得做

推荐分阶段做

第 1 阶段：先把服务常驻化

第 2 阶段：启用 LiteLLM 自带 Admin UI

第 3 阶段：再决定要不要做自定义本地看板

推荐结构

我的建议

十一、长期维护时最容易踩的坑

1. 误以为“初始化成功”就等于“官方支持”

2. 直接把私钥、路径、端口写进仓库

3. 让下游模型直接暴露思维痕迹

4. 把“模型切换”做成脚本复制粘贴

十二、网页录入多平台注册表，推荐做到哪一层

dashboard 里最值得支持的输入项

在线编辑时的一个关键细节

十三、`claude-router` 的更推荐落地形态

为什么 `doctor` 很重要

`claude-router` 和单平台快捷入口要不要同时保留

十二、推荐的长期结构

十三、建议的日常策略

十四、推荐命名

十五、接入新的 OpenAI 兼容渠道时，最佳动作是什么

十六、对于 `newapi`，到底要不要再做一个新的 `claude-newapi`

短期最小可用

长期推荐

十七、当前 LiteLLM Local Dashboard 支持在线切换到什么程度

十八、`newapi` 接入时的最佳实现顺序

十九、最佳方案总结

参考资料