🔀 ccmr — Claude Code Model Router

会话中一句话切换 40+ 第三方模型——不用重启，不用改配置文件。

ccmr 是一个跑在本机的轻量 API 网关：Claude Code 连它，它把请求原样转发给你选的模型（DeepSeek、Kimi、Qwen、GLM、MiniMax、Step、MiMo、豆包 Seed，8 家 44 个型号全部预配好）。在会话里 /model kimi 回车即切；Key 失效时错误信息直接告诉你「改哪个变量、去哪申请、跑什么命令验证」；配置和 Key 改完约 1 秒热重载。默认只监听 127.0.0.1，全本地。

English · 简体中文

$ npx claude-code-model-router@latest setup

Providers (key status from environment and .env):
   1. DeepSeek        DEEPSEEK_API_KEY        [no key]
   2. Kimi            KIMI_API_KEY            [no key]
   ...（18 家，标注控制台地址）
Configure which providers? 1
Paste DEEPSEEK_API_KEY for DeepSeek (get one: https://platform.deepseek.com/): ********
Verify keys now with one tiny request per provider? [y/N] y
  [OK] deepseek-v4-pro
Default model [deepseek-flash] (Enter = accept): 

$ ccmr claude        # 进入 Claude Code，会话内任意切：
> /model kimi        # 上一句还在 DeepSeek，这一句已经是 Kimi
> /model glm         # 再一句，GLM-5.3

为什么是 ccmr

多数方案切换模型 = 改环境变量/配置文件 + 重启 Claude Code。ccmr 是活的网关：模型切换发生在会话里（/model 回车即生效，上下文不丢），因为它始终以稳定的本机地址面对 Claude Code，变化只发生在网关背后。

| | 手改 env / 配置 | 配置切换器 | ccmr | |---|---|---|---| | 切换模型 | 改文件 + 重启进程 | 改文件 + 重启进程 | 会话内 /model，即切即用 | | 上下文 | 重启即丢 | 重启即丢 | 保留 | | 内置模型 | 手填各家端点/ID | 逐家录入 | 8 家 44 型号预配，别名即选 | | Key 体检 | 出错才知道 | — | ccmr doctor 逐模型微型真请求 | | 401 报错 | 一句透传原文 | — | 原文保留 + 指明改哪个变量/去哪申请 | | 用量统计 | — | — | 按模型请求数/错误/tokens | | 故障降级 | — | — | 5xx/429 按链切换备选模型 | | 热重载 | — | — | models.yaml/.env 改动约 1 秒生效 | | 官方订阅共存 | — | 常互相覆盖 | 独立配置目录，claude 与 ccmr claude 互不干扰 |

诚实说明：ccmr 是 Anthropic 协议直通网关，不做协议转换——只接各家官方 Anthropic 兼容端点（智谱国内按量付费只有 OpenAI 协议，故仅支持其 Coding Plan 订阅）。流式、工具调用、思考模式原样转发，不解析不改写你的上下文。

快速开始

# 一条命令：选厂商 → 粘贴 Key（隐藏输入）→ 可选即时验证 → 设默认模型
npx claude-code-model-router@latest setup   # 网关未运行时 ccmr claude 会自动拉起

# 启动 Claude Code（第三方模型，网关模式）
npx claude-code-model-router claude

# 或者全局安装后直接用 ccmr
npm install -g claude-code-model-router
ccmr setup
ccmr claude

# CI / 脚本（无交互）：从环境变量取 Key，逐厂商验证，全败退出码 1
DEEPSEEK_API_KEY=sk-... npx claude-code-model-router setup --yes --validate

也可以手动 ccmr start 前台启动网关（日志直接可见）；ccmr claude 自动拉起的网关日志在 ~/.ccmr/gateway.log。 claude 命令仍然走官方订阅——两种模式配置完全隔离，互不影响。

命令说明

# 初始化配置文件（git 仓库内会自动把 .env 加入 .gitignore）
npx claude-code-model-router init
npx claude-code-model-router init --global  # 写入 ~/.ccmr，全目录共享一份配置

# 引导式配置 API Keys（选厂商 → 粘贴 Key → 可选即时验证 → 设默认模型）
npx claude-code-model-router setup
npx claude-code-model-router setup --yes --validate  # 非交互：取环境变量里的 Key 并逐个验证
# --validate 下「全部厂商验证失败」时退出码为 1（CI 门禁语义）；部分失败只报告不阻断

# 启动网关（前台运行；models.yaml / .env 修改后自动热重载，无需重启）
npx claude-code-model-router start
npx claude-code-model-router start --port 9000  # 指定端口
npx claude-code-model-router start --host 0.0.0.0  # 需设置入站鉴权令牌

# 查看本机正在运行的网关（端口 / PID / 版本 / 配置来源 / Key 状态）
npx claude-code-model-router status

# 停止网关（含 `ccmr claude` 后台自动拉起的那个）
npx claude-code-model-router stop
npx claude-code-model-router stop --port 9000
npx claude-code-model-router stop --all

# 查看可用模型
npx claude-code-model-router models

# 切换默认模型（持久化写回 models.yaml，运行中的网关自动生效）
npx claude-code-model-router use kimi

# 连通性体检：对每个已配 Key 的模型发一条微型真实请求
# 一次性暴露端点错误、Key 失效、账号未开通模型等问题
npx claude-code-model-router doctor            # 检查全部
npx claude-code-model-router doctor seed kimi  # 只检查指定模型

# 查看网关的按模型用量统计（请求数 / 错误数 / tokens）
npx claude-code-model-router stats

# 更新到 npm 上的最新版本（等同 npm install -g claude-code-model-router@latest）
npx claude-code-model-router update
npx claude-code-model-router update --check            # 只查有没有新版，不安装
npx claude-code-model-router update --package-manager pnpm  # npm / pnpm / yarn / bun

# 启动 Claude Code（网关模式；网关未启动时会自动拉起）
npx claude-code-model-router claude
npx claude-code-model-router claude --gateway-port 9000  # 自定义网关端口

# 启动 Claude Code（官方订阅）
claude

配置发现顺序：-c 指定路径 > ./models.yaml > ./config/models.yaml > ./.claude-router.yaml > ~/.ccmr/models.yaml。显式 -c 不存在或配置非法时会直接报错，不会回退到另一份配置。.env 按 ~/.ccmr/.env < ./.env < 配置文件相邻 .env 的优先级加载，父进程环境变量优先级最高（CCMR_HOME 可改写全局目录位置，日志也随之移动）。

网关的生命周期

| 启动方式 | 关掉终端窗口后 | 日志去向 | |----------|----------------|----------| | ccmr start | 随之退出（前台进程） | 直接打印在终端 | | ccmr claude 自动拉起 | 继续在后台运行 | ~/.ccmr/gateway.log |

自动拉起的网关是 detached 进程（自成进程组、PPID=1），收不到终端的 SIGHUP——这是有意设计：多个 Claude Code 会话可以共用同一个网关，关掉其中一个窗口不该打断其他会话。代价是它不会自己消失，用 ccmr status 查看、ccmr stop 收掉。

复用网关前会比较配置路径、路由内容、.env 来源及 API Key 的不可逆摘要。若端口上的网关来自另一个项目，ccmr claude 会拒绝复用并提示换端口或先停止旧网关，避免提示词发往错误的供应商账号。

ccmr stop 会同时校验 /health 身份和 ~/.ccmr/gateway-<port>.identity.json 中的本机随机身份记录，匹配后才会发送信号。只伪造 HTTP 响应不能诱导它停止任意 PID。由 v1.8.2 及更早版本启动的旧网关没有身份记录，沿用其 /health 自报 PID 停止，升级后仍可正常回收。

安全提示：网关默认绑定到 127.0.0.1（仅本机可访问）。网关会用你本地配置的各厂商 API Key 代理上游请求，因此任何能访问该端口的人都能消耗你的额度。 若确需通过 --host 0.0.0.0 暴露到局域网，必须设置环境变量 CCMR_REQUIRED_AUTH_TOKEN，此时调用方需在 x-api-key 或 Authorization: Bearer <token> 中携带该令牌。未设置时网关默认拒绝启动；仅在已隔离且明确接受风险时使用 --allow-insecure-network。远程未认证的 /health 只返回基础存活信息，不暴露 PID、路径或 Key 状态。

Claude Code 原生参数支持

ccmr claude 命令完整支持 Claude Code 的原生启动参数：

# YOLO 模式（跳过所有权限确认）
ccmr claude --dangerously-skip-permissions

# 继续上一次会话
ccmr claude --continue
ccmr claude -c

# YOLO 模式 + 继续上一次会话
ccmr claude --dangerously-skip-permissions --continue

# 恢复指定会话（交互式选择）
ccmr claude --resume
ccmr claude -r

# 恢复指定会话 ID
ccmr claude --resume <session-id>

# 调试模式
ccmr claude --debug
ccmr claude --verbose

# 连接 IDE
ccmr claude --ide

# 指定权限模式
ccmr claude --permission-mode bypassPermissions

# 打印模式（非交互式）
ccmr claude -p "你的问题"
ccmr claude --print --output-format json "你的问题"

支持的完整参数列表：

| 参数 | 说明 | |------|------| | -c, --continue | 继续最近的会话 | | -r, --resume [id] | 恢复指定会话或打开会话选择器 | | --fork-session | 恢复时创建新会话 ID | | --dangerously-skip-permissions | 跳过所有权限检查（YOLO 模式） | | --permission-mode <mode> | 权限模式：acceptEdits, bypassPermissions, default, dontAsk, plan | | -p, --print | 打印模式（非交互式） | | --output-format <format> | 输出格式：text, json, stream-json | | --model <model> | 指定模型（覆盖网关路由） | | --system-prompt <prompt> | 自定义系统提示 | | --add-dir <dirs...> | 添加额外目录权限 | | -d, --debug | 调试模式 | | --verbose | 详细输出 | | --ide | 自动连接 IDE | | --gateway-port <port> | 指定网关端口（默认 8080） |

提示： 任何 Claude Code 原生支持的参数都可以直接传递给 ccmr claude

ccmr claude 会为网关模式自动注入独立环境变量：

• CLAUDE_CONFIG_DIR=~/.claude-gateway
• ANTHROPIC_BASE_URL=http://127.0.0.1:<gateway-port>
• ANTHROPIC_AUTH_TOKEN=ccmr-local-gateway
• ANTHROPIC_MODEL 和 Claude 默认模型变量会指向当前 default_model；若该模型的 context_window ≥ 1M，会自动带上 [1m] 后缀（如 deepseek-flash[1m]）。Claude Code 只有在模型名带这个后缀时才会真正开启 1M 上下文，并且会在请求发出前把后缀剥掉，因此不影响上游模型 ID
• CLAUDE_CODE_AUTO_COMPACT_WINDOW 会按启动模型的 context_window 自动注入（如 Seed/Kimi 256K、DeepSeek 1M），避免 Claude Code 把第三方模型默认裁剪到 ~200k。若你已自行设置该变量，则尊重你的值不覆盖。注意它是会话级全局：运行时用 /model 切到不同上下文窗口的模型时，压缩阈值不会跟着变，需要重启或用 ccmr claude --model <模型> 重新启动以匹配（1M 模型之间互相切换不受影响）

这些变量只作用于 ccmr claude 启动的 Claude Code 子进程，不会修改你的官方 Claude Code 配置，也不会影响直接运行 claude 的官方订阅模式。

支持的模型

| 短名称 | 版本别名 | 模型 | 提供商 | |--------|----------|------|--------| | deepseek-v4-pro | deepseek, deepseek-v4, deepseek-pro, ds | DeepSeek V4 Pro（官方计划下线，09-14 12:00 起路由到 V4.1 Flash） | DeepSeek | | deepseek-flash | deepseek-chat, deepseek-4.1-flash, ds-4.1, deepseek-vision, ds-vision, deepseek-v4-flash | DeepSeek V4.1 Flash（原生多模态） | DeepSeek | | kimi-k3 | k3 | Kimi K3 | Moonshot（国际站） | | kimi-k2.6 | kimi, kimi-k2, moonshot | Kimi K2.6 | Moonshot（国际站） | | kimi-k2.7-code | kimi-code, k2.7-code | Kimi K2.7 Code | Moonshot（国际站） | | kimi-k2.7-code-highspeed | kimi-highspeed, k2.7-highspeed | Kimi K2.7 Code HighSpeed | Moonshot（国际站） | | kimi-cn-k3 | kimi-cn, moonshot-cn, k3-cn | Kimi K3 | Moonshot（国内开放平台） | | kimi-cn-k2.6 | - | Kimi K2.6 | Moonshot（国内开放平台） | | kimi-cn-k2.7-code | - | Kimi K2.7 Code | Moonshot（国内开放平台） | | kimi-cn-k2.7-code-highspeed | - | Kimi K2.7 Code HighSpeed | Moonshot（国内开放平台） | | kimi-plan-k3-1m | kimi-plan | Kimi K3 1M（Allegretto 及以上） | Kimi Code 会员订阅 | | kimi-plan-k3 | - | Kimi K3 256K（Moderato 及以上） | Kimi Code 会员订阅 | | kimi-plan-for-coding | kimi-for-coding | Kimi K2.7 Code（全档位） | Kimi Code 会员订阅 | | kimi-plan-for-coding-highspeed | kimi-plan-highspeed | Kimi K2.7 Code HighSpeed（Allegretto 及以上） | Kimi Code 会员订阅 | | minimax-m3 | minimax, minimax-cn, mm | MiniMax M3 | MiniMax CN | | minimax-m3.1-flash | minimax-flash, minimax-m3.1, mm-flash | MiniMax M3.1 Flash（强制开启 thinking） | MiniMax CN | | minimax-global-m3 | minimax-global, minimax-io | MiniMax M3 | MiniMax Global | | minimax-global-m3.1-flash | minimax-global-flash, minimax-global-m3.1, minimax-io-flash | MiniMax M3.1 Flash（强制开启 thinking） | MiniMax Global | | qwen3.8-max | qwen, tongyi, qwen3.8 | Qwen3.8 Max | 阿里云（按量付费） | | qwen3.7-max | qwen-max, qwen3.7 | Qwen3.7 Max | 阿里云（按量付费） | | qwen3.8-flash | qwen-flash | Qwen3.8 Flash（多模态，支持图片/视频输入） | 阿里云（按量付费） | | qwen-plan-3.8-max | qwen-plan, qwen-plan-3.8, qwen-plan-max | Qwen3.8 Max | 千问 Token Plan（订阅） | | qwen-plan-3.7-max | qwen-plan-3.7 | Qwen3.7 Max | 千问 Token Plan（订阅） | | qwen-plan-3.8-flash | qwen-plan-flash | Qwen3.8 Flash（多模态，支持图片/视频输入） | 千问 Token Plan（订阅） | | glm-plan-5.3 | glm-plan, glm, glm-5.3, zhipu, chatglm | GLM-5.3 | 智谱 GLM Coding Plan（订阅） | | glm-plan-5.2 | glm-5.2 | GLM-5.2 | 智谱 GLM Coding Plan（订阅） | | glm-plan-5.3-flash | glm-flash, glm-5.3-flash, glm-plan-flash | GLM-5.3-Flash（原生多模态） | 智谱 GLM Coding Plan（订阅） | | glm-global-5.3 | glm-global, zai, z-ai | GLM-5.3 | Z.ai（国际） | | glm-global-5.2 | - | GLM-5.2 | Z.ai（国际） | | glm-global-5.3-flash | glm-global-flash, zai-flash | GLM-5.3-Flash（原生多模态） | Z.ai（国际） | | step-5-preview | step, step-5, step5, stepfun | Step 5 Preview（1M 上下文，支持图片输入） | 阶跃星辰(按量付费) | | step-plan-5-preview | step-plan, step-plan-5, stepplan | Step 5 Preview (Step Plan) | 阶跃星辰(订阅) | | mimo-v2.5-pro | mimo, mimo-pro, mimo-token-sgp, xiaomi | MiMo V2.5 Pro | MiMo Token Plan SGP | | mimo-v2.5 | mimo-v2 | MiMo V2.5 | MiMo Token Plan SGP | | mimo-token-cn-v2.5-pro | mimo-token-cn, mimo-cn | MiMo V2.5 Pro | MiMo Token Plan CN | | mimo-token-ams-v2.5-pro | mimo-token-ams, mimo-ams | MiMo V2.5 Pro | MiMo Token Plan AMS | | mimo-payg-v2.5-pro | mimo-payg, mimo-payg-pro | MiMo V2.5 Pro | MiMo Pay-as-you-go | | seed-2.1-pro | seed, seed-pro, doubao | Doubao Seed 2.1 Pro | 火山方舟（按量付费） | | seed-2.1-turbo | seed-turbo | Doubao Seed 2.1 Turbo | 火山方舟（按量付费） | | seed-plan-2.1-pro | seed-plan, seed-plan-pro, doubao-plan | Doubao Seed 2.1 Pro | 火山方舟（Agent Plan 订阅） | | seed-plan-2.1-turbo | seed-plan-turbo | Doubao Seed 2.1 Turbo | 火山方舟（Agent Plan 订阅） |

模型参数

| 模型 | Context Window | Max Output Tokens | |------|----------------|-------------------| | DeepSeek V4 Pro | 1M | 384K | | DeepSeek V4.1 Flash | 1M | 384K | | Kimi K3 (国际站 / 国内) | 1M | 1M（默认 128K） | | Kimi K2.6 (国际站 / 国内) | 256K | 32K | | Kimi K2.7 Code / HighSpeed (国际站 / 国内) | 256K | 32K | | Kimi K3 (Coding Plan kimi-plan-k3-1m / kimi-plan-k3) | 1M / 256K（按档位） | 1M / 128K | | Kimi K2.7 Code / HighSpeed (Coding Plan) | 256K | 32K | | MiniMax M3 (CN / Global) | 1M | 128K | | MiniMax M3.1 Flash (CN / Global) | 1M | 512K | | Qwen3.8 Max (按量付费 / Token Plan) | 1M | 64K | | Qwen3.7 Max (按量付费 / Token Plan) | 1M | 64K | | Qwen3.8 Flash (按量付费 / Token Plan) | 1M | 128K | | GLM-5.3 / GLM-5.2 (Coding Plan / 国际) | 1M | 128K | | GLM-5.3-Flash (Coding Plan / 国际) | 1M | 128K | | Step 3.7 Flash (按量付费 / Step Plan) | 256K | 384K | | MiMo V2.5 Pro | 1M | 128K | | MiMo V2.5 | 1M | 128K | | Doubao Seed 2.1 Pro / Turbo (按量付费 / Agent Plan) | 256K | 256K |

内置 Web Search 支持

Claude Code 内置的 Web Search 是 Anthropic 服务端工具（web_search_20250305）：搜索不在本地执行，而是由 API 提供方的服务器在生成过程中代跑。走网关后"服务器"是各家的 Anthropic 兼容端点，是否真的执行搜索取决于供应商是否实现了该服务端工具——网关对两种情况的转发行为完全相同。实测（2026-07-17，各发一条带 web_search 工具的真实请求）：

| 供应商 | 服务端 Web Search | 表现 | |--------|-------------------|------| | Moonshot 国内（kimi-cn-k3） | ✅ 支持 | 返回 server_tool_use + web_search_tool_result，搜到实时结果 | | DeepSeek | ✅ 支持 | 同上 | | MiniMax CN（minimax-m3） | ✅ 支持 | 同上 | | 智谱 GLM（glm-plan-5.2） | ❌ 不支持 | 工具被静默忽略，模型回答"无法联网"，Claude Code 显示 Did 0 searches | | Qwen 按量付费（qwen3.7-max） | ❌ 不支持 | 同上 |

其余供应商（Kimi 国际站、GLM Global、Step、MiMo、Doubao Seed、MiniMax Global）未实测，以实际行为为准；供应商随时可能补齐支持。

对不支持的模型，可给 Claude Code 配一个客户端执行的 MCP 搜索工具（在本机跑，与所选模型无关），例如：

claude mcp add tavily -- npx -y tavily-mcp   # 也可用 Exa、Brave Search 等

内置的 WebFetch（抓取指定 URL）由客户端执行，各家模型均可正常使用，缺的只是"搜索"这一步。

配置

环境变量 (.env)

推荐用 ccmr setup 引导式填写（隐藏输入、可选即时验证）；也可以直接编辑 .env：

DEEPSEEK_API_KEY=sk-xxx    # https://platform.deepseek.com/
KIMI_API_KEY=sk-xxx        # Kimi 国际站: https://platform.kimi.ai/
KIMI_CN_API_KEY=sk-xxx     # Kimi 国内开放平台（与国际站不互通）: https://platform.kimi.com/
KIMI_CODE_API_KEY=sk-xxx   # Kimi Code 会员 coding 订阅（与开放平台不互通）: https://www.kimi.com/code/console
MINIMAX_API_KEY=xxx        # MiniMax CN / Token Plan: https://platform.minimaxi.com/
MINIMAX_GLOBAL_API_KEY=xxx # MiniMax Global: https://platform.minimax.io/
QWEN_API_KEY=sk-xxx        # Qwen 按量付费: https://dashscope.console.aliyun.com/
QWEN_PLAN_API_KEY=sk-sp-xxx # Qwen Token Plan 订阅（专属接入点 token-plan.cn-beijing.maas.aliyuncs.com）: https://platform.qianwenai.com/
GLM_PLAN_API_KEY=xxx       # GLM Coding Plan 订阅（智谱国内）: https://bigmodel.cn/claude-code
GLM_GLOBAL_API_KEY=xxx     # GLM 国际版（Z.ai）: https://z.ai/model-api
ARK_API_KEY=xxx            # Doubao Seed 火山方舟 按量付费 (/api/compatible): https://console.volcengine.com/ark
ARK_PLAN_API_KEY=xxx       # Doubao Seed 火山方舟 Agent Plan 订阅 (/api/plan) 专属 Key
STEP_API_KEY=xxx           # 阶跃星辰按量付费: https://platform.stepfun.com/
STEP_PLAN_API_KEY=xxx      # 阶跃星辰 Step Plan 订阅: https://platform.stepfun.com/
MIMO_API_KEY=tp-xxx        # MiMo Token Plan，默认 SGP 集群
MIMO_TOKEN_CN_API_KEY=tp-xxx  # MiMo Token Plan CN 集群
MIMO_TOKEN_AMS_API_KEY=tp-xxx # MiMo Token Plan AMS 集群
MIMO_PAYG_API_KEY=sk-xxx   # MiMo Pay-as-you-go: https://platform.xiaomimimo.com/

# 可选网关设置
GATEWAY_PORT=8080
REQUEST_TIMEOUT=300
LOG_LEVEL=INFO             # DEBUG / INFO / WARN / ERROR / SILENT
CCMR_REQUIRED_AUTH_TOKEN=  # 非回环监听时必须设置

ccmr claude 与 ccmr stats 会自动使用 CCMR_REQUIRED_AUTH_TOKEN。如客户端与服务端使用不同环境，可在客户端单独设置 CCMR_AUTH_TOKEN 覆盖发送令牌。

MiMo Token Plan 的 Base URL 与购买套餐所在集群绑定。默认 mimo 使用 SGP 集群；如果订阅页显示 CN 或 AMS 集群，请分别配置 MIMO_TOKEN_CN_API_KEY / MIMO_TOKEN_AMS_API_KEY，并使用 mimo-token-cn 或 mimo-token-ams。tp-* Token Plan Key 不能用于按量付费接口，sk-* 按量付费 Key 也不能用于 Token Plan 接口。

智谱 GLM 国内仅支持 Coding Plan 订阅：open.bigmodel.cn/api/anthropic 是智谱国内唯一的 Anthropic 兼容端点，且被 Coding Plan 门控——按量付费 key / tokens 资源包调用会返回 429 [1309] 套餐已到期/未订阅，官方 FAQ 明确资源包在该通道不可用、套餐额度耗尽也不会转按量计费。国内按量付费只提供 OpenAI 协议（/api/paas/v4），ccmr 作为 Anthropic 协议直通网关暂无法接入，待智谱开通按量 Anthropic 端点后再支持。

配置文件 (models.yaml)

可以自定义供应商、模型变体、别名等。运行 init 命令会生成 providers -> variants 结构的模板；旧版平铺 models 配置仍然兼容。

网关运行中修改 models.yaml 或 .env 会自动热重载（轮询检测，约 1 秒生效），新增、轮换或删除 Key 都会生效；入站鉴权令牌也可热轮换。即使文件启动时不存在，之后创建也会被捕获。注意：gateway.host / gateway.port 变更仍需重启才能重新绑定。

排查某个网关到底在用哪份配置：

curl -s :8080/health | jq '{version, config_file, ccmr_home, default_model}'

配置作用域：项目级 vs 全局

配置发现按当前目录优先：./models.yaml > ./config/models.yaml > ./.claude-router.yaml > ~/.ccmr/models.yaml；.env 同理，./.env 逐变量覆盖 ~/.ccmr/.env。ccmr claude 自动拉起网关时会继承当前工作目录，因此网关看到的配置和你在这个目录里看到的一致。

由此产生两种使用形态：

• 项目级：Key 只放在某个项目目录的 .env 里（不配 ~/.ccmr/.env）。在该目录里直接 ccmr claude 即可，无需手动 ccmr start——但网关是"项目级"的，换到其他目录就不可用：新目录里自动拉起的网关找不到任何 Key 会被启动检查拦下；而复用原网关会因配置来源指纹不一致（跨项目保护，防止 A 项目会话误用 B 项目的 Key 和路由）被 ccmr claude 拒绝。
• 全局：ccmr init --global 生成 ~/.ccmr/models.yaml + ~/.ccmr/.env 并填入 Key（或直接把项目 .env 拷贝为 ~/.ccmr/.env），之后在任意目录都能 ccmr claude 随开随用。

两者可以共存，但合并规则不同：.env 按变量逐个覆盖（项目值优先，shell 环境变量最优先）；models.yaml 则整体取第一个命中的文件——项目里存在 models.yaml 时全局那份完全不参与（两者都只与内置默认配置合并）。常见组合是"Key 放全局 ~/.ccmr/.env、需要独立路由的项目放一份自己的 models.yaml"。

故障降级（fallback）

任意 variant 可声明降级链，上游返回 5xx/429 或连接失败（含超时）时按序切换到备选模型；4xx 客户端错误不会触发降级，流式响应一旦开始输出也不再切换：

providers:
  deepseek:
    # ...
    variants:
      v4-pro:
        model_id: deepseek-v4-pro
        fallback: [kimi-k2.6, glm-5.2]  # 依次降级

使用场景

双模式使用（配置完全隔离）

本工具通过独立的配置目录实现完全隔离，让你可以同时使用官方订阅和第三方模型：

┌─────────────────────────────────────────────────────────────────┐
│  模式1: 官方订阅（默认）                                          │
│  命令: claude                                                    │
│  配置: ~/.claude/settings.json                                  │
│  用途: 使用 Claude 官方模型（订阅额度）                           │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  模式2: 第三方模型（网关）                                        │
│  命令: npx claude-code-model-router claude                      │
│  配置: ~/.claude-gateway/settings.json                          │
│  用途: 使用第三方 AI 模型（DeepSeek, GLM, Qwen 等）              │
└─────────────────────────────────────────────────────────────────┘

为什么配置是隔离的？

• 官方模式使用 ~/.claude/ 配置目录（Claude Code 默认）
• 网关模式使用 ~/.claude-gateway/ 配置目录（独立隔离）
• 两个配置目录完全独立，互不干扰
• 在网关模式切换模型不会影响官方模式

使用步骤

第一步：启动网关

npx claude-code-model-router start

第二步：选择使用模式

使用官方订阅（终端 A）：

claude

• 使用官方 Claude 模型（Sonnet, Opus, Haiku）
• 消耗订阅额度
• 配置存储在 ~/.claude/

使用第三方模型（终端 B）：

npx claude-code-model-router claude

• 使用第三方 AI 模型（DeepSeek V4, GLM-5.3, Qwen3.8, Kimi K3, Doubao Seed 2.1, MiMo V2.5 等）
• 按 API 使用量付费
• 配置存储在 ~/.claude-gateway/

跨平台支持

所有命令在 Windows、macOS、Linux 上完全相同，无需修改。

在 Claude Code 中切换模型

官方模式（直接 claude 启动）

/model sonnet     # Claude Sonnet 4.5
/model opus       # Claude Opus 4.5
/model haiku      # Claude Haiku 3.5

网关模式（npx ... claude 启动）

使用短名称或版本别名切换模型：

# 使用短名称（向后兼容）
/model deepseek   # 切换到 DeepSeek V4 Pro
/model qwen       # 切换到 Qwen3.8 Max（按量付费）
/model qwen-plan  # 切换到 Qwen3.8 Max（千问 Token Plan 订阅）
/model glm        # 切换到 GLM-5.3（智谱 Coding Plan 订阅）
/model glm-global # 切换到 GLM-5.3（国际 Z.ai）
/model deepseek-flash # 切换到 DeepSeek V4.1 Flash（原生多模态，支持图片输入）
/model qwen-flash # 切换到 Qwen3.8 Flash（按量付费，多模态）
/model glm-flash  # 切换到 GLM-5.3-Flash（智谱 Coding Plan 订阅，原生多模态）
/model seed       # 切换到 Doubao Seed 2.1 Pro（火山方舟 按量付费）
/model seed-plan  # 切换到 Doubao Seed 2.1 Pro（火山方舟 Agent Plan 订阅）
/model step       # 切换到 Step 5 Preview（按量付费）
/model step-plan  # 切换到 Step 5 Preview（Step Plan 订阅）
/model kimi       # 切换到 Kimi K2.6
/model kimi-code  # 切换到 Kimi K2.7 Code（编程专用）
/model kimi-highspeed # 切换到 Kimi K2.7 Code HighSpeed（约 6 倍速）
/model minimax    # 切换到 MiniMax M3（国内 Token Plan）
/model minimax-global # 切换到 MiniMax M3（海外）
/model mimo       # 切换到 MiMo V2.5 Pro（Token Plan SGP）
/model mimo-token-cn  # 切换到 MiMo V2.5 Pro（Token Plan CN）
/model mimo-payg      # 切换到 MiMo V2.5 Pro（按量付费）

# 使用版本别名（明确指定版本）
/model deepseek-v4-pro           # DeepSeek V4 Pro（09-14 起上游路由到 V4.1 Flash）
/model deepseek-flash            # DeepSeek V4.1 Flash（别名 deepseek-chat / ds-4.1 / deepseek-vision）
/model glm-plan-5.3              # GLM-5.3（智谱 Coding Plan 订阅）
/model glm-plan-5.2              # GLM-5.2（智谱 Coding Plan 订阅）
/model glm-plan-5.3-flash        # GLM-5.3-Flash（智谱 Coding Plan 订阅；别名 glm-flash）
/model glm-global-5.3            # GLM-5.3（国际 Z.ai）
/model glm-global-5.2            # GLM-5.2（国际 Z.ai）
/model glm-global-5.3-flash      # GLM-5.3-Flash（国际 Z.ai；别名 glm-global-flash）
/model step-5-preview            # Step 5 Preview（按量付费；别名 step、step-5）
/model step-plan-5-preview       # Step 5 Preview（Step Plan 订阅；别名 step-plan）
/model minimax-m3                # MiniMax M3
/model minimax-global-m3         # MiniMax M3 Global
/model kimi-k2.6                 # Kimi K2.6
/model kimi-k2.7-code            # Kimi K2.7 Code
/model kimi-k2.7-code-highspeed  # Kimi K2.7 Code HighSpeed
/model qwen3.8-max               # Qwen3.8 Max（按量付费；别名 qwen / qwen3.8）
/model qwen3.7-max               # Qwen3.7 Max（按量付费）
/model qwen-plan-3.8-max         # Qwen3.8 Max（Token Plan 订阅）
/model qwen-plan-3.7-max         # Qwen3.7 Max（Token Plan 订阅）
/model qwen3.8-flash             # Qwen3.8 Flash（按量付费；别名 qwen-flash）
/model qwen-plan-3.8-flash       # Qwen3.8 Flash（Token Plan 订阅；别名 qwen-plan-flash）
/model seed-2.1-pro              # Doubao Seed 2.1 Pro（按量付费）
/model seed-2.1-turbo            # Doubao Seed 2.1 Turbo（按量付费）
/model seed-plan-2.1-pro         # Doubao Seed 2.1 Pro（Agent Plan 订阅）
/model seed-plan-2.1-turbo       # Doubao Seed 2.1 Turbo（Agent Plan 订阅）
/model mimo-v2.5-pro             # MiMo V2.5 Pro
/model mimo-v2.5                 # MiMo V2.5
/model mimo-token-ams-v2.5-pro   # MiMo V2.5 Pro Token Plan AMS

重要： 两个模式的配置完全独立，在网关模式切换模型不会影响官方模式！

API 端点

| 端点 | 方法 | 说明 | |------|------|------| | /v1/messages | POST | Anthropic Messages API | | /v1/messages/count_tokens | POST | 转发到所选供应商的兼容 token counting 端点 | | /v1/models | GET | 列出可用模型 | | /usage | GET | 按模型的用量统计（请求数 / 错误数 / tokens，网关重启后清零） | | /health | GET | 健康检查；本机或已认证请求额外返回 PID、配置来源和模型状态 |

开发

# 克隆项目
git clone https://github.com/luwill/Claude-Code-Model-Router.git
cd Claude-Code-Model-Router

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 类型检查、测试、冒烟测试与依赖审计
npm run check

# 本地测试
npm link
ccmr start

故障排除

第一步：先跑 doctor

npx claude-code-model-router doctor

对每个已配 Key 的模型发一条微型真实请求，直接给出结论：连通（含延迟）/ 上游报错原文（Key 失效、模型未开通、端点错误）/ 未配 Key。绝大多数"模型用不了"的问题一条命令即可定位。

端口被占用

# 使用其他端口
npx claude-code-model-router start --port 9000

API Key 错误

1. 运行 npx claude-code-model-router doctor 查看上游的具体报错
2. 检查 .env 文件中的 Key 是否正确（修改后网关自动热重载，无需重启）
3. 确认账户有余额
4. 运行 npx claude-code-model-router models 查看 Key 配置状态

换目录后 ccmr claude 被拒绝（无 Key / 配置来源不一致）

Key 只配在某个项目目录的 .env 里时，网关是项目级的，换目录不可用——见配置作用域：项目级 vs 全局。想在任意目录使用，运行 ccmr init --global 并把 Key 填入 ~/.ccmr/.env。

模型不执行 Web Search（Did 0 searches）

内置 Web Search 是 Anthropic 服务端工具，是否可用取决于供应商——见内置 Web Search 支持的实测表和 MCP 替代方案。

网关模式提示地区不支持

请确认是用 npx claude-code-model-router claude 或 ccmr claude 启动第三方模型模式，而不是直接运行 claude。网关模式会自动设置本地 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 和默认模型，避免 Claude Code 走官方 Anthropic 登录/地区检查路径。

DeepSeek 报 Invalid user_id

DeepSeek Anthropic 兼容接口会忽略 metadata 字段，但某些 Claude Code 会话会携带包含特殊字符的 metadata.user_id，导致 DeepSeek 在请求校验阶段返回 400。路由器会在转发 DeepSeek 请求前移除该元数据，不影响上下文、工具调用或模型输出。

更新日志

v1.23.0

• 新增 MiniMax-M3.1-Flash，国内版与国际版分别接入、各用各的 Key：
  • 国内版 minimax-m3.1-flash（别名 minimax-flash / minimax-m3.1 / mm-flash）：api.minimaxi.com/anthropic，MINIMAX_API_KEY
  • 国际版 minimax-global-m3.1-flash（别名 minimax-global-flash / minimax-global-m3.1 / minimax-io-flash）：api.minimax.io/anthropic，MINIMAX_GLOBAL_API_KEY
• 参数：1M 上下文（官方文档）；最大输出 512K（官方文档未写明，取上游实测硬上限 does not support max tokens > 524288）
• 该模型强制开启 thinking，传 thinking: disabled 会被上游返回 400；思考 token 计入 max_tokens
• minimax / minimax-global 短名仍指向 M3，默认行为不变

v1.22.0

产品易用性专项（新用户旅程 UX 审计驱动），四个面向用户的改进：

• 新增 ccmr setup 引导式配置：一条命令完成「查看各厂商 Key 状态 → 选择厂商 → 粘贴 Key（终端隐藏输入）→ 可选逐厂商即时验证（与 doctor 同款微型请求）→ 写入 .env → 设默认模型」；--yes 非交互模式取环境变量中的 Key（CI/脚本友好），--validate 附带逐厂商验证。裸 ccmr 在「无配置且无任何 Key」时直接指引 setup（顺带修复了裸命令 Quick Start 提示从未显示过的死代码问题）
• Key 错误自愈：缺 Key 的 401 现在指明「改哪个环境变量、去哪申请（新增 provider 级 console_url 字段）、用什么命令验证」；上游 401/403 保留厂商原始错误文本并追加同样的修复指引——审计发现真实环境里 Key 大面积失效时，用户此前只能看到一句不含任何行动线索的透传报错
• ccmr models 标记默认模型（* 前缀 + 图例），ccmr use 的效果在列表里可见；ccmr stats 自报数据来源网关端口（多网关并存时不再张冠李戴）
• 诚实口径回归锁定：listModels、/v1/models、/health 三处「无 Key = 不可用」的行为补齐聚合测试固化；console_url 在 DEFAULT_CONFIG、YAML 模板与 .env 注释三处由一致性测试钉死，不会再漂移

v1.21.0

• 新增 Step 5 Preview：阶跃星辰 2026-09-18 发布的新旗舰，600B 总参数 / 27B 激活，1M 上下文，支持文本与图片输入
  • 两个出口都加了：按量付费 step-5-preview（https://api.stepfun.com，STEP_API_KEY）和订阅版 step-plan-5-preview（https://api.stepfun.com/step_plan，STEP_PLAN_API_KEY），上游模型 ID 都是 step-5-preview
  • 裸别名改指向新旗舰：step、stepfun → step-5-preview，step-plan、stepplan → step-plan-5-preview
  • 移除 Step 3.7 Flash 的两个模型键（step-3.7-flash、step-plan-3.7-flash）及其别名，阶跃星辰这一侧只保留 Step 5 Preview。不把旧名字反向别名到新模型：按量付费下两者价差约 5 倍（$0.2/$1.15 对 $1.00/$2.70），静默改道等于替用户加钱；且 1.21.0 之前生成的配置里存在 step -> step-3.7-flash，加反向别名会形成别名环（参见 DeepSeek V4 Flash 下线那次）。老配置自带 provider 块，升级后照常可加载
  • 上下文窗口实测：1,034,012 tokens 可接受，约 1,059,900 被拒，按 1M 登记，因此会自动带 [1m] 后缀；max_tokens 沿用 Step 3.7 Flash 的 393216，上游对该值来者不拒，无法探测
  • 实测两个端点的 /v1/messages 都返回 200 并回显 step-5-preview

v1.20.0

• 新增 ccmr update：一条命令更新到 npm 上的最新版本，等同 npm install -g claude-code-model-router@latest
  • 先向 npm registry 查已发布版本并与本机版本做数值比较（避免 1.9.0 被字符串比较误判为高于 1.10.0），已是最新则不做任何安装
  • 本地版本领先 registry 时也判定为最新，不会把未发布的本地构建降级回线上版本
  • --check 只报告不安装；--package-manager 支持 npm / pnpm / yarn / bun，且限定在白名单内——该值会成为被拉起进程的 argv[0]，不接受任意字符串
  • 安装直接透传 npm 自己的输出，权限错误等原文可见；失败时以 npm 的退出码退出，并提示改用用户可写的 prefix
  • 更新成功后会扫描本机运行中的网关，列出仍在跑旧版本的实例并提示重启（包升级不同于配置热重载，旧进程会继续跑旧代码），但不会替你去停用户的进程

v1.19.0

• 1M 模型自动带 [1m] 后缀：Claude Code 在自定义 base_url 后面默认按 ~200k 处理第三方模型，只有模型名以 [1m] 结尾时才会开启百万上下文——此前需要每次手动 /model deepseek-flash[1m]。现在两个出口都会自动补后缀：
  • ccmr claude 注入的 ANTHROPIC_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL / ..._OPUS_MODEL / ..._HAIKU_MODEL（解决"刚进界面就是 200K"）
  • GET /v1/models 返回的模型 id（解决"用 /model 切换后又变回 200K"）
• 判定规则：context_window ≥ 1000000 才加后缀，当前 42 个模型中 27 个符合（DeepSeek、Kimi K3、Qwen3.8、GLM-5.x、MiniMax M3、MiMo 等）；256K 及以下的模型（Seed、Kimi K2.x、Step）保持裸名——给小窗口模型挂 [1m] 会让 Claude Code 超发上下文
• 后缀只对客户端有意义：网关在解析模型名时会先剥掉 [1m] 再查别名，上游收到的始终是裸模型 ID（Kimi 曾因 k3[1m] 报 401）。因此 deepseek-flash 和 deepseek-flash[1m] 都能正常路由，老配置、老脚本不受影响

v1.18.0

• DeepSeek V4.1 Flash 正式版接入（官方 2026-09-10 发布公告 / 定价页）：正式模型名 deepseek-flash，取代 09-08 的内测 id（deepseek-v4.1-flash-expires-on-0910，已过期）。552B MoE、Causal-Encoder-Decoder 非对称结构（输入激活 8B / 输出激活 16B）、原生多模态视觉理解，1M 上下文、最大输出 384K。实测：文本 200（0.62s）；base64 image block 真实进入上下文（8×8 纯蓝图正确答 "Blue"，input_tokens 227）
• V4 Flash 与 V4 Flash Vision Exp 已被官方下线：模型条目 deepseek-v4-flash、deepseek-v4-flash-vision-exp、deepseek-v4.1-flash-exp 一并移除，但这些名字保留为别名指向 deepseek-flash，既有配置和 /model 习惯不受影响（上游同样把这些 id 路由到 V4.1 Flash——实测三者返回的 model 字段均为 deepseek-flash）。deepseek-vision / ds-vision 也指向新模型，语义仍然成立（V4.1 Flash 原生多模态）
• 价格下调（09-10 12:00 生效，仍为峰谷定价、闲时为高峰一半）：deepseek-flash 每百万 tokens 输入 $0.15（闲时）/ $0.3（高峰），输出 $0.6 / $1.2，缓存命中输入 $0.003 / $0.006
• 升级提示：本次移除了三个模型条目，但没有把 deepseek-v4-flash / deepseek-v4-flash-vision-exp 反向别名到 deepseek-flash——1.18 之前生成的 models.yaml 里有 deepseek-flash: deepseek-v4-flash，两者相遇会形成别名环让配置整体失效（已加回归测试锁定）。老配置升级后仍可正常加载：这些名字会继续解析到你 yaml 里保留的旧条目，上游暂时路由到 V4.1 Flash。但上游的兼容路由是"暂时"的，建议重新生成 models.yaml（备份旧文件后 ccmr init）以切到新条目
• deepseek-v4-pro 进入下线流程，默认模型改为 deepseek-flash：官方公告称北京时间 2026-09-14 12:00 之后，访问该 id 的请求将全部路由到 V4.1 Flash 并按其单价计费，直到 V4.1 Pro 上线。目前该 id 仍返回真实 V4 Pro（实测），故条目与 deepseek / ds 别名保留；但内置 default_model 已从 deepseek-v4-pro 切到 deepseek-flash，避免 09-14 之后出现"显示 V4 Pro、实际跑 V4.1 Flash"的错位。已有 models.yaml 的用户不受影响（用户配置里的 default_model 优先），需要时用 ccmr use deepseek-flash 切换

v1.17.0

• 新增 DeepSeek V4.1 Flash（内测）：模型 deepseek-v4.1-flash-exp（别名 deepseek-4.1-flash / deepseek-v4.1-flash / ds-4.1），上游 id deepseek-v4.1-flash-expires-on-0910。来源为 DeepSeek 官方小助手 2026-09-08 公告：新模型结构、原生多模态、计费同 V4 Flash、每账号限 20 并发，id 于 2026-09-10 过期（正式 id 发布后本条目会移除或替换）。官方暂无文档页，上下文/最大输出按公告"计费同 V4 Flash"继承 V4 Flash 的 1M / 384K（API 实测不校验 max_tokens，无法用报错探测上限）。实测：文本调用 200（0.34s）；Anthropic base64 image block 真实进入上下文（8×8 纯红图正确答"Red"，input_tokens 227），对照组 deepseek-v4-flash 同请求只收到占位文本。默认模型不变（deepseek 仍指向 V4 Pro）
• 修正过时说明：DeepSeek 文本模型收到图片已不再返回 400——现为端点静默替换为"unsupported image"占位文本（2026-09-08 实测），配置注释与文档已同步更新

v1.16.0

• 新增 GLM-5.3-Flash（智谱文档 / Z.ai 文档）：GLM-5 系列首个原生多模态模型（视频/图片/文本/文件输入），320B 总参、18B 激活，1M 上下文、最大输出 128K，定价为 GLM-5.3 的 1/10。国内 glm-plan-5.3-flash（别名 glm-flash / glm-5.3-flash / glm-plan-flash）与国际 glm-global-5.3-flash（别名 glm-global-flash / zai-flash）同步新增，端点与 Key 复用现有 provider；两份官方 Claude Code 配置均已直接使用 glm-5.3-flash。Coding Plan 额度为 GLM-5.3 的 3 倍。默认模型不变（glm / glm-global 仍指向 5.3）。与 GLM-5.3 一样强制开启思考
• 新增 Qwen3.8 Flash（百炼模型信息 / 百炼 Anthropic 兼容 API）：千问多模态 flash 档（图片/视频/文本输入），1M 上下文、最大输出 131,072；百炼北京按量价 ¥0.8 / ¥2.7 每百万 tokens（输入/输出）。按量 qwen3.8-flash（别名 qwen-flash）与 Token Plan qwen-plan-3.8-flash（别名 qwen-plan-flash）同步新增；默认模型不变（qwen / qwen-plan 仍指向 3.8 Max）。按量版实测 ccmr doctor 通过；Token Plan 版依据千问 AI 平台 latest-model 文档「Token Plan 支持 Qwen3.8-Flash」收录，但 Token Plan 概述的档位模型表尚未列出它（该表仍含已下线的 glm-5.1，应为过期），且本次未能实测（测试订阅对 3.8-max 同样返回 403 AccessDenied.Unpurchased）——若你的档位不含该模型，上游会返回同样的 403。国际版：百炼国际站（{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com）与 QwenCloud（dashscope-intl）同样提供该模型，但 ccmr 目前没有国际版 Qwen provider，需要的话请开 issue
• 关于 qwen3.8-flash-next：它是 Qwen4 架构的开源预览版权重（HF，Qwen Community License），百炼 / 千问 AI 平台 / QwenCloud / OpenRouter 均无该 id 的托管 API，官方说明线上正式版即 qwen3.8-flash。因此不提供路由——需要它的话直接用 qwen3.8-flash

v1.15.0

• 新增 GLM-5.3（智谱文档 / Z.ai 文档）：智谱最新旗舰，1M 上下文、最大输出 128K，GLM Coding Plan 已全量上线。国内 glm-plan-5.3 与国际 glm-global-5.3 同步新增并设为默认——glm / zhipu / glm-plan 现指向 5.3，glm-global / zai 同理；5.2 保留（glm-5.2 / glm-plan-5.2 / glm-global-5.2）。注意：GLM-5.3 强制开启思考（reasoning_effort 支持 low/high/max，默认 max），上游不再接受 thinking.type: "disabled"
• 新增 DeepSeek V4 Flash Vision（实验版）（视觉指南）：模型 deepseek-v4-flash-vision-exp（别名 deepseek-vision / ds-vision），DeepSeek 目前唯一支持图片输入的模型，Anthropic 协议 image block（base64 / url / file）直通可用；1M 上下文、最大输出 384K，价格与 V4 Flash 相同，复用 DEEPSEEK_API_KEY 与现有端点。文本默认模型不变（deepseek 仍指向 V4 Pro）；图片仅限 user 消息，文本模型收到图片会报 400

v1.14.0

• Qwen3.8 Max 正式版（GA）：模型 ID 去掉 -preview 后缀，统一更新为 qwen3.8-max（旧 qwen3.8-max-preview 上游暂可用但已弃用），qwen-plan-3.8-max 同步切到 GA id
• 恢复按量付费 qwen3.8-max 并设为默认：正式版已开放按量付费（实测按量 key 在 dashscope Anthropic 端点返回 200，兑现 v1.11.1 的"待开放后恢复"）。裸别名 qwen / tongyi 及 qwen3.8 / qwen3.8-max 现指向按量版 3.8；qwen3.7-max（别名 qwen-max / qwen3.7）保留

v1.13.0

• 移除 GLM-5.1（国内 glm-plan-5.1 与国际 glm-global-5.1，别名 glm-5 / glm-5.1 同步下线）：智谱官方已退役 5.1，Coding Plan 对旧模型的调用会被上游自动切换到 GLM-5.2，继续保留只会误导。GLM 现仅保留 5.2（国内 Coding Plan / 国际 Z.ai）

v1.12.0

• GLM 国内 provider 更名为 glm-plan（GLM Coding Plan），如实反映其订阅属性：open.bigmodel.cn/api/anthropic 是智谱国内唯一的 Anthropic 兼容端点，且被 Coding Plan 门控——按量付费 key / tokens 资源包实测返回 429 [1309]，官方 FAQ 明确资源包在 Claude Code 通道不可用、套餐额度耗尽也不转按量。模型键 glm-5.2 / glm-5.1 变为 glm-plan-5.2 / glm-plan-5.1，环境变量 GLM_API_KEY → GLM_PLAN_API_KEY（迁移：把订阅 key 换到新变量名即可）；旧别名 glm / zhipu / chatglm / glm-5.2 / glm-5.1 / glm-5 全部保留指向订阅模型，/model glm 不受影响
• 说明：智谱国内按量付费暂无法接入 ccmr——按量只提供 OpenAI 协议（/api/paas/v4），无 Anthropic 兼容端点（候选路径实测均 404），ccmr 是 Anthropic 协议直通网关不做协议转换；待智谱开通按量 Anthropic 端点后再支持。GLM Global（Z.ai glm-global）不受本次变更影响

v1.11.3

• 修复 Qwen Token Plan 报 403 invalid api-key：Token Plan 有专属 Anthropic 接入点 https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic（官方 Claude Code 接入参数确认），sk-sp- 订阅 Key 打到按量付费的 dashscope.aliyuncs.com/apps/anthropic 会被拒。v1.11.1 中"与按量付费同一端点"的说法有误，已更正 qwen-plan 的 base_url 及相关注释；Bearer 与 x-api-key 两种鉴权头实测均可用

v1.11.2

• 修复 Kimi Code 订阅 kimi-plan-k3-1m 报 401 ... recognized as other:k3[1m]：上游 Model ID 应为纯 k3，k3[1m] 只是 Claude Code 原生环境变量写法（原生 CC 会剥掉 [1m] 再发 k3），作为第三方网关必须发 k3。改 model_id: k3[1m] → k3；1M 上下文仍由 context_window → CLAUDE_CODE_AUTO_COMPACT_WINDOW 提供，kimi-plan-k3-1m 与 kimi-plan-k3 现共用上游模型 k3、仅上下文窗口不同（依据 Kimi Code 官方文档：k3[1m] 仅 Claude Code 环境变量场景需要，API 请求只填 k3）

v1.11.1

• 修正 v1.11.0 的一个错误假设：qwen3.8-max-preview 目前仅通过千问 Token Plan（sk-sp- 订阅 Key）发放，按量付费账号调用返回 403 Model.AccessDenied（权限问题，且无自助开通入口）。因此：
  • 从按量付费 qwen provider 移除 qwen3.8-max 变体，默认改回 qwen3.7-max；裸别名 qwen / tongyi 回指 qwen3.7-max
  • 3.8 仅保留在 qwen-plan provider（订阅可用）；别名 qwen3.8 / qwen3.8-max 现指向 qwen-plan-3.8-max
  • 待阿里将该预览开放到按量付费后，再恢复 pay-go 变体

v1.11.0

• 新增 Qwen3.8 Max Preview（qwen3.8-max，模型 ID qwen3.8-max-preview，阿里 2026-07-19 发布的 2.4T 旗舰预览版）：按量付费 qwen provider 的默认模型，裸别名 qwen / tongyi 现指向它；qwen3.7-max（别名 qwen-max / qwen3.7）保留
• 新增 Qwen Token Plan 订阅 provider（qwen-plan-3.8-max，别名 qwen-plan）：Key 来自 千问 AI 平台 的 sk-sp- 订阅密钥，需配置 QWEN_PLAN_API_KEY；走 DashScope 同一 Anthropic 兼容端点（dashscope.aliyuncs.com/apps/anthropic），但按订阅额度计费，另含 qwen-plan-3.7-max
• 移除 Qwen3.5 Plus / Qwen3.5 Flash（qwen3.5-plus、qwen3.5-flash 及别名 qwen3.5 下线）

v1.10.0

• 新增 Kimi Code 会员 coding 订阅入口（api.kimi.com/coding，Key 来自 kimi.com 会员控制台，与开放平台不互通）：需配置 KIMI_CODE_API_KEY，提供 kimi-plan-k3-1m（别名 kimi-plan，Allegretto 及以上）、kimi-plan-k3（Moderato 及以上，256K）、kimi-plan-for-coding（别名 kimi-for-coding，全档位）、kimi-plan-for-coding-highspeed；模型与上下文按会员档位限权
• 兼容性说明：既有别名 kimi-code / kimi-code-highspeed 仍指向国际站 K2.7 Code 模型，含义不变；订阅版统一使用 kimi-plan 前缀（与 step-plan / seed-plan 命名一致）

v1.9.1

• ccmr claude 启动模型缺少 API Key 时的指引拆分：若网关本身健康且有其他可用模型，直接提示 ccmr use <可用模型>（或 --model 单次指定、补配该模型的 Key），不再误导用户去 ccmr stop + ccmr init 重建配置；"stop + init"指引仅保留给网关完全无 Key 或不认识该模型的场景

v1.9.0

• 新增 Kimi K3（Moonshot 旗舰，1M 上下文，max_completion_tokens 最高 1M）：国际站短名称 kimi-k3（别名 k3，沿用 KIMI_API_KEY）
• 新增 Kimi 国内开放平台入口（api.moonshot.cn/anthropic，platform.kimi.com，原 platform.moonshot.cn）：需配置 KIMI_CN_API_KEY（与国际站 Key 不互通），提供 kimi-cn-k3（别名 kimi-cn / k3-cn）及 K2 系列 kimi-cn-k2.6 / kimi-cn-k2.7-code / kimi-cn-k2.7-code-highspeed

v1.8.4

• 修复 v1.8.3 回归：网关不再校验单条消息的 role/content——Claude Code v2.1+ 会在 messages 中携带 role: "system" 的上下文条目，v1.8.3 的白名单校验导致所有真实会话在本地报 400 messages[1].role must be user or assistant。网关现在只校验路由自身依赖的结构，消息协议交由上游判定
• ccmr stop 遇到无法自报 PID 的旧网关（v1.8.1 及更早）时，按平台给出手动停止命令（Windows 用 netstat + taskkill，不再显示无效的 pkill），并提示可改用其他端口
• ccmr claude 拒绝复用旧网关时，同时给出"换端口直接启动新网关"的出路，不再只有先停旧网关一条指引

v1.8.3

• 阻止 detached 网关跨项目复用错误的配置、端点或 API Key
• 流式转发改用增量 UTF-8 解码，兼容 CRLF SSE；客户端断开会取消上游请求并处理背压，且不再误判为连接错误而触发 failover 或污染用量统计
• .env 删除 Key 后会真正撤销，入站鉴权支持热轮换；内置客户端统一使用相同令牌
• 非回环无鉴权监听改为默认拒绝，远程 /health 隐藏本机路径、PID 与 Key 状态
• ccmr stop 增加本机随机身份记录校验，不再只信任 HTTP 自报 PID（旧版网关没有身份记录，沿用原停止方式，升级后仍可回收）
• 显式配置路径、YAML、端口、超时和 CLI 数值参数改为严格校验；YAML/env/CLI 优先级保持一致
• 实现兼容 /v1/messages/count_tokens 转发，并执行 streaming/tools 能力声明
• 修复流式断连继续计费、生产依赖漏洞和缺失 LICENSE；CI/发布前新增依赖审计

v1.8.2

• 新增 ccmr status：列出本机正在运行的 ccmr 网关及其端口、PID、版本、配置来源、可用模型数。ccmr claude 自动拉起的网关是 detached 进程（关掉终端后继续运行），此前只能靠 lsof 才能找到它
• 新增 ccmr stop：停止网关，支持 --port / --all / --force。只会停止通过 /health 自证身份的 ccmr 网关；端口被其他程序占用时明确报错并拒绝操作，不会误杀无关进程
• /health 新增 pid 字段：status / stop 因此无需解析 lsof / netstat，跨平台一致，且从原理上保证只能操作 ccmr 自己的进程
• 修复日志目录不一致：自动拉起的网关日志此前写死在 ~/.ccmr/gateway.log，不随 CCMR_HOME 移动，导致配置和日志分居两地
• README 补充网关生命周期说明（ccmr start 前台即退 vs ccmr claude 后台常驻）

v1.8.1

修复一类隐蔽故障：网关在配置文件存在之前被 ccmr claude 自动拉起后，会静默地退回内置默认配置（零 API Key），且此后无论你怎么补配置都不会生效，表现为 Claude Code 里持续报 401 API key not configured。

• 热重载改为监视「候选路径」而非「启动时已存在的文件」：先起网关、后跑 ccmr init --global（或手工放置 models.yaml / .env）现在也能被捕获，约 1 秒内自动生效。此前这种情况下监视列表为空，热重载永不触发
• 零可用模型时启动告警：找不到配置文件、或 0 个模型有 API Key 时，启动横幅会明确警告并给出查找路径与修复命令，不再静默
• ccmr claude 启动前校验模型可用性：复用已在运行的网关前先检查它能否服务目标模型；不能则直接报错，附上该网关的配置来源与 pkill 修复命令，而不是让你在 Claude Code 内部撞上 401
• /health 新增 config_file 与 ccmr_home 字段：一条 curl 即可确认某个网关到底在用哪份配置

ccmr start 行为不变。自动拉起只在目标端口探测不到网关时触发。

v1.8.0

易用性

• 新增 ccmr doctor [models...]：对每个已配 Key 的模型发一条微型真实请求做连通性体检，一次性暴露端点错误、Key 失效、账号未开通模型等问题
• 新增 ccmr use <model>：持久化切换默认模型（文本级改写 default_model，保留注释），运行中的网关自动生效
• 新增 ccmr stats 与 GET /usage：按模型统计请求数 / 错误数 / 输入输出 tokens
• ccmr claude 检测网关未启动时自动拉起（detached，日志在 ~/.ccmr/gateway.log）；检测到网关与 CLI 版本不一致时给出警告
• 配置热重载：网关运行中修改 models.yaml / .env 约 1 秒内自动生效，无需重启
• 全局配置目录：~/.ccmr/models.yaml 与 ~/.ccmr/.env 作为兜底（cwd 优先），ccmr init --global 一键生成；CCMR_HOME 可改写位置
• 新增模型降级链：variant 级 fallback: [...]，上游 5xx/429/连接失败时按序切换备选模型

风险修复

• ccmr init 在 git 仓库内自动把 .env 加入 .gitignore，防止 API Key 被误提交
• 移除 ESM-only 的 node-fetch（CJS 产物在 Node <22.12 会 ERR_REQUIRE_ESM 崩溃），改用 Node 18+ 内置 fetch，engines: >=18 恢复真实；同时移除未使用的 chalk 依赖
• 流式转发增加空闲超时看门狗，上游挂死不再永久悬挂连接
• 入站鉴权改为常量时间比较（crypto.timingSafeEqual）
• 端口被占用时给出友好错误提示（原为裸堆栈崩溃）
• 配置热重载遇到损坏的 YAML 时保留旧配置继续运行，不再静默退化为默认配置

工程化

• 引入 vitest 测试体系：路由解析 / URL 构建 / SSE 转发 / 鉴权 / 热重载 / failover / 用量统计，以及 DEFAULT_CONFIG 与 YAML 模板的一致性测试
• 新增 GitHub Actions CI：Node 18/20/24 矩阵构建 + 测试 + dist 一致性校验

v1.7.1

• 修正 Doubao Seed 接入点：按量付费应走 https://ark.cn-beijing.volces.com/api/compatible（而非旧 Coding Plan 的 /api/coding），模型 ID 带版本后缀 doubao-seed-2-1-pro-260628 / doubao-seed-2-1-turbo-260628
• 新增 Agent Plan 订阅入口 seed-plan（https://ark.cn-beijing.volces.com/api/plan，需 ARK_PLAN_API_KEY），与按量付费 seed 区分，模式同 step / step-plan
• Kimi 新增 kimi-k2.7-code 与 kimi-k2.7-code-highspeed（编程专用，256K 上下文；别名 kimi-code / kimi-highspeed）
• ccmr claude 启动时按所选模型的 context_window 自动注入 CLAUDE_CODE_AUTO_COMPACT_WINDOW（已自行设置则不覆盖），并在启动横幅显示当前模型与压缩窗口

v1.7.0

• Qwen 旗舰升级为 Qwen3.7 Max（qwen3.7-max，别名 qwen-max / qwen3.7）
• GLM 升级为 GLM-5.2 并区分国内/国际版：
  • 国内版（智谱 open.bigmodel.cn）默认 glm-5.2，保留 glm-5.1
  • 新增国际版（Z.ai api.z.ai），别名 glm-global / zai，需配置 GLM_GLOBAL_API_KEY
• 新增字节豆包 Doubao Seed 2.1 Pro / Turbo（火山方舟 ark.cn-beijing.volces.com，Anthropic 协议），别名 seed / seed-turbo / doubao，需配置 ARK_API_KEY（目前仅国内版，国际版 BytePlus 暂未上线 Seed 2.1）

v1.3.3

• CLI 和健康检查版本号改为从 package.json 读取，避免发布后显示旧版本

v1.3.1

• MiniMax 默认端点切换为国内 Token Plan 兼容的 https://api.minimaxi.com/anthropic
• 新增 MiniMax Global 入口，海外 API Key 可使用 MINIMAX_GLOBAL_API_KEY 和 minimax-global-* 模型
• MiMo 默认切换为 Claude Code 文档推荐的 mimo-v2.5-pro，并区分 Token Plan 集群与 Pay-as-you-go API
• ccmr claude 自动注入本地网关认证 token 和默认模型，避免误走官方 Claude Code 地区检查
• DeepSeek 转发前移除 Claude Code 会话元数据，避免 metadata.user_id 格式触发上游 400 校验错误

v1.3.0

• 新增供应商级 providers -> variants 配置结构，并兼容旧版平铺 models 配置
• 移除 KAT-Coder-Pro V2
• DeepSeek 更新为 DeepSeek V4 Pro / V4 Flash，并更新 Anthropic API 配置
• Kimi 更新为 Kimi K2.6
• GLM 更新为 GLM-5.1
• MiniMax 新增 MiniMax M2.7 Highspeed
• Qwen 新增 Qwen3.5 Flash 和 Qwen3 Max
• 新增 MiMo V2.5

v1.2.0

• 更新 GLM 模型至 GLM-5 版本
• 更新 MiniMax 模型至 M2.7 版本
• 更新 Qwen 模型至 Qwen3.5 Plus 版本
• 更新 Kimi 模型至 K2.5 版本
• 更新各模型的 context window 和 max tokens 参数
• 新增版本别名支持（如 glm-5、minimax-m2.7、qwen3.5-plus、kimi-k2.5）

v1.1.0

• 更新 MiniMax 模型至 M2.1 版本
• 更新 GLM 模型至 4.7 版本
• 更新 GLM API 端点至 https://open.bigmodel.cn/api/anthropic
• 新增版本别名支持（如 glm-4.7、minimax-m2.1）
• 优化日志显示，显示具体模型版本
• 更新各模型的 context window 和 max tokens 参数

v1.0.1

• 添加 Claude Code 原生参数支持

v1.0.0

• 初始版本发布

License

MIT