迁移指南 · 2026-11-01

从官方 API 或别家中转迁移到微澜

已有 Anthropic SDK、OpenAI SDK、Claude Code 或 Codex 的调用代码，把 base URL 和 Key 换掉即可迁移：改什么、不用改什么、常见冲突排查、验证清单与回退方法。

适用场景

这篇给三类人看：已经在用 Anthropic / OpenAI 官方 API 的、正在用别家中转或聚合网关的、以及用 Claude Code、Codex、Cline、Cherry Studio 这类客户端连自定义端点的。共同点是：业务代码不用重写，只换地址和密钥。

不适用的情况也说清楚：如果你只需要网页版聊天，不需要 API，那本文帮不上；如果你依赖 Anthropic 独有的 Beta 能力（例如某些未公开的实验性接口），迁移前请先确认我们的目录是否声明支持，再决定。

本文只讲接入，不判断哪种计费方式更便宜。迁移完成后请用控制台的真实用量和自己的月账单对比，再决定是否长期使用，具体方法见最后一节。

改什么，不用改什么

项目	要不要改	说明
Base URL	要改	改成 https://api.latentide.com；Claude Code 场景不要自己加 /v1
API Key	要改	换成控制台创建的微澜 Key；官方 Key 与微澜 Key 不能混用
模型 ID	可能要改	以价目页的模型 ID 为准，区分大小写
请求体结构	不用改	messages / chat/completions / responses 的字段保持原样
SDK 依赖	不用改	anthropic、openai 官方 SDK 均可直接指向新地址
业务代码	不用改	函数调用、流式输出、工具调用逻辑不变
计费方式	会变	从订阅或预付费额度，变成按每次调用的 token 数扣费

Claude Code：改 settings.json

不想手动改配置文件的话，可以直接在控制台创建 Key 时点「一键导入 CC Switch」，或按 /guides/claude-code#cc-switch 用桌面工具 CC Switch 图形化切换。

Claude Code 读 ~/.claude/settings.json 的 env 字段。把下面整段贴进去、替换 Key 即可，不用再改别的地方：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.latentide.com",
    "ANTHROPIC_API_KEY": "<你的微澜 API Key>",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-5-5"
  }
}

ANTHROPIC_SMALL_FAST_MODEL 是后台小任务（生成标题、补全之类）用的模型，单独指到便宜档位能省一部分钱。如果你原来的 settings.json 里已经有别的配置（权限、hooks、statusline），只把 env 里这几个键合并进去，不要整份覆盖。

改完重启 Claude Code。会话里可以用 /model claude-opus-5-5 临时切到更强的模型，不必改配置。

Codex：加一个 model provider

Codex 的配置在 ~/.codex/config.toml。用 Responses 协议指向微澜：

model = "claude-sonnet-5-5"
model_provider = "latentide"

[model_providers.latentide]
name = "Latentide"
base_url = "https://api.latentide.com"
env_key = "LATENTIDE_API_KEY"
wire_api = "responses"

env_key 写的是环境变量名，不是 Key 本身。启动前先 export LATENTIDE_API_KEY=<你的微澜 API Key>，或者写进 shell 配置文件。

SDK：只改 base_url 与 key

Anthropic SDK 用 x-api-key 鉴权，OpenAI SDK 用 Bearer。两种协议我们都支持，选你原来用的那套即可。

from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.latentide.com",
    api_key="<你的微澜 API Key>",
)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.latentide.com",
    api_key="<你的微澜 API Key>",
)

注意 OpenAI SDK 的 base_url 通常会被拼成 /chat/completions，所以这里写到域名即可，SDK 自己会补路径。环境变量更省事：OPENAI_BASE_URL 与 OPENAI_API_KEY，或 ANTHROPIC_BASE_URL 与 ANTHROPIC_API_KEY。

迁移后不生效？先查环境变量冲突

九成「明明改了却还在扣官方账户」的情况，是旧变量还在生效。按这个顺序排查：

旧 shell 配置：~/.zshrc、~/.bashrc、~/.profile 里是否还有 ANTHROPIC_BASE_URL 或 OPENAI_BASE_URL 指向别处；后加载的会覆盖先加载的。
系统级变量：macOS 的 launchctl setenv、Windows 的「系统环境变量」，会盖过 shell 配置。
Claude Code 专用变量：ANTHROPIC_AUTH_TOKEN 存在时会优先于 ANTHROPIC_API_KEY；CLAUDE_CODE_USE_BEDROCK 或 CLAUDE_CODE_USE_VERTEX 打开时会绕过自定义地址。
IDE 与客户端缓存：VS Code 插件、Cherry Studio、Cline 之类可能各自存了一份配置，改环境变量对它们无效，要在插件设置里改。
代理变量：HTTP_PROXY / HTTPS_PROXY 指向了本地代理时，请求可能被转走；先临时 unset 掉再验证。

排查办法很直接：新开一个终端，只 export 我们这一组变量，然后跑下一节的 curl。能通，说明问题在原地环境；不通，再往下查 Key 与余额。

验证清单

先脱离客户端，用 curl 确认链路、Key、余额三件事都正常：

curl https://api.latentide.com/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":64,"messages":[{"role":"user","content":"ping"}]}'

返回正常 JSON：链路通了。
打开控制台「调用明细」，刚才那条请求应该立刻出现，带模型、tokens 和扣费金额。
再启动客户端随便问一句，明细里出现第二条记录，说明客户端也走通了。
对账：明细里的金额 = 用量 × 价目页单价，逐笔可查。

如果 curl 通、客户端不通，问题一定在客户端配置或环境变量，不用怀疑 Key。

想退回怎么办

迁移前先备份原配置，回退就是几分钟的事：

cp ~/.claude/settings.json ~/.claude/settings.json.bak
# 需要回退时
cp ~/.claude/settings.json.bak ~/.claude/settings.json

用环境变量的话，把 export 那几行删掉或注释掉，重开终端即可。别把官方 Key 和微澜 Key 放在同一个变量里轮换，容易两边都失效。

余额可以按需充值，不存在「包月用不完」的沉没成本；但反过来，按量计费也没有「用超了自动降速」的保护，跑批量任务前建议先小额试跑。

迁完怎么判断划不划算

不要凭单价判断。先按原工作流跑一两天，然后在控制台看两件事：每天的实际扣费、以及调用明细里的缓存命中率。缓存命中率高的场景，输入 token 的绝大部分按缓存读取计价，实际花费会比「按单价乘总量」低很多。

拿到日均花费后，用费用计算器把你的真实用量代入，和订阅价做对比：月费 ÷ 单次平均花费 = 回本次数。调用次数明显低于回本次数，按量更省；明显高于且订阅额度够用，订阅更划算。

还有一条常被忽略：按量计费下，换模型是零成本的。简单任务用便宜档、难题临时切强模型，这种混用在固定订阅里通常做不到。