日常工作知识库

Appearance

Claude Code 多模型切换：claude-router 设计原理与隔离实践 ​

在使用 Claude Code 时，开发者经常需要切换不同的模型服务商（如 Anthropic 官方、讯飞 Astron、百度千帆等）。由于 Claude Code 强依赖环境变量和全局配置文件，不当的切换方式会导致严重的配置冲突。

1. 核心问题：环境变量“张冠李戴” ​

现象 ​

启动 Claude Code 后报错： API Error: 500 ... msg: PathDomainError:Model Not Found

根因分析 ​

  1. 全局变量污染：在 .zshrc 或 .bashrc 中硬编码了 ANTHROPIC_BASE_URL（指向服务商 A），但在终端中又手动或通过脚本设置了 ANTHROPIC_MODEL（属于服务商 B）。
  2. Shim 脚本硬编码：为了方便而创建的 claude 别名或 Shim 脚本（如 ~/.local/bin/claude）中硬编码了 --model <model_name> 参数。这会导致即使环境变量正确，命令参数依然会覆盖环境变量，造成冲突。

2. 设计方案：claude-router 的隔离机制 ​

claude-router 是一个多配置管理器，其核心设计理念是 “档位切换”与“环境注入”的分离。

A. 档位切换 (use) ​

运行 claude-router use <profile-id> 时，它仅修改一个状态文件（如 active_profile.txt），而不改变当前 Shell 的任何环境变量。这保证了全局环境的纯净。

B. 环境注入 (run) ​

运行 claude-router (不带参数) 或 claude-router run 时，它会执行以下流程：

  1. 根据 active profile 找到对应的 入口脚本 (Entrypoint Script)。
  2. 入口脚本在子进程中 export 该 profile 专属的环境变量（Base URL, Key, Model）。
  3. 使用 exec 调用真实的 claude 二进制文件。

隔离优势：变量只在 claude-router 及其拉起的 claude 进程中生效，终端窗口退出后即刻消失，互不干扰。

3. 故障排查：解决 Model Not Found ​

如果直接运行 claude 报错，请检查以下三项：

  1. 检查软链接： 确认 which claude 指向的是真实二进制文件，而不是一个带有硬编码逻辑的 Shim 脚本。

    bash
    # 如果发现是 shim，建议移除并重新链接到真实 binary
rm ~/.local/bin/claude
ln -s <path_to_real_binary> ~/.local/bin/claude

  2. 清理全局配置： 检查 ~/.claude/settings.json 是否被某些脚本硬编码了 env 字段。建议保持该文件简洁，主要依靠环境变量进行动态控制。

  3. 区分 /model 与服务商切换：

    • 同一服务商内部切换：可使用 claude 会话内的 /model 命令。
    • 跨服务商切换：必须退出会话，使用 claude-router use 切换 Base URL。

4. 最佳实践工作流 ​

  1. 设定默认值：在 .zshrc 中只保留你最常用的一个服务商配置作为全局兜底。
  2. 多终端并存：
    • 终端 A：claude-router use xfyun -> claude-router (进入讯飞环境)
    • 终端 B：claude-router use qianfan -> claude-router (进入千帆环境)
  3. 互不干扰：由于每个终端窗口的进程环境是独立的，这种方式可以完美实现多个模型同时对比测试，而不会发生冲突。