OmniRoute 配置指南：让 Claude Code CLI 无缝接入多模型网关

本文讲解如何把 Claude Code CLI 指向本地或远程 VPS 上的 OmniRoute 网关：包括环境变量注入、/model 选择器的发现别名机制、基于 CLAUDE_CONFIG_DIR 的 per-model 配置文件（profiles）、自动同步与故障排查。读完本文，你可以让 Claude Code 通过 OmniRoute 路由到 Kimi、GLM、DeepSeek 等非 Anthropic 模型，并用一条命令为每个模型生成独立配置。

快速开始

# 让 Claude Code 指向本地 OmniRoute（自动检测当前上下文）
omniroute launch

# 指向远程 OmniRoute（omniroute connect <host> 之后可自动完成）
omniroute launch --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# 生成 per-model profiles，然后启动其中任意一个
omniroute setup-claude            # 写入 ~/.claude/profiles/<name>/settings.json
omniroute launch --profile glm52  # 通过 OmniRoute 使用 glm/glm-5.2 的 Claude Code

omniroute launch 会自动完成三件事：从当前上下文解析 base URL 和 token、对服务器做健康检查、然后 exec claude。

Claude Code 如何连接网关

Claude Code 使用 Anthropic Messages API 协议，通过环境变量指向自定义端点（它没有 --base-url 命令行参数）：

变量	作用
ANTHROPIC_BASE_URL	网关根 URL（Claude Code 会自行拼接 /v1/messages）。不要带 /v1 后缀
ANTHROPIC_AUTH_TOKEN	以 Authorization: Bearer … 发送 —— 填你的 OmniRoute access token / API key
ANTHROPIC_API_KEY	备选：以 x-api-key 发送。两者同时设置时 ANTHROPIC_AUTH_TOKEN 优先
ANTHROPIC_MODEL	强制指定某个模型（覆盖 /model 选择器的默认值）
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY	1 → 原生 /model 选择器列出 /v1/models 中的 claude*/anthropic* 模型
CLAUDE_CODE_MAX_OUTPUT_TOKENS	限制每次响应的输出 token 数（例如 65536）
CLAUDE_CODE_AUTO_COMPACT_WINDOW	自动压缩（auto-compact）的 token 阈值

环境变量只在 Claude Code 启动时读取一次 —— 修改后必须重启 claude 才生效。

ANTHROPIC_BASE_URL 的归一化逻辑在源码中一目了然：normalizeClaudeBaseUrl 只做 trim 和去掉尾部斜杠，不会替你补也不会剥 /v1，所以带 /v1 结尾的 URL 是常见的手误来源（见文末"排查"一节）。

发现别名：让非 Claude 模型进入 /model 选择器

Claude Code 的网关模型发现只会列出以 claude 或 anthropic 开头的模型 id。因此即使打开了 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，原生 /model 选择器里通常也只有 OmniRoute 的 Claude/Anthropic 模型 —— kimi/kimi-k2.6、glm/glm-5.2 这些明明能正常路由的模型却不会出现。

OmniRoute 的解决办法：把任意已启用的模型（以及 combo）镜像成一个 claude/… 前缀的别名 id，从而通过这个过滤：

kimi/kimi-k2.6            →  claude/kimi/kimi-k2.6      "Kimi K2.6 (OmniRoute)"
glm/glm-5.2              →  claude/glm/glm-5.2         "GLM 5.2 (OmniRoute)"
<combo "custo-otimizado"> →  claude/combo/custo-otimizado

在 Claude Code 中选中这些别名后，OmniRoute 会在路由前剥掉 claude/ 包装、还原成真实 id；而真实的 claude/<real-claude-model> id（Claude OAuth 提供商）则永远保持原样。

该功能默认关闭，由三级开关控制（越具体的层级优先级越高），避免普通 OmniRoute 给不使用 Claude Code 的客户端凭空翻倍目录：

层级	位置
Model	提供商详情页 → 单模型 "Expose in Claude Code" 开关
Provider	提供商详情页 → provider 级开关（覆盖其全部模型）
Global	Settings → Feature Flags → EXPOSE_CC_DISCOVERY_ALIASES（默认关）

环境变量 EXPOSE_CC_DISCOVERY_ALIASES 会强制打开全局层，且优先于仪表盘上的开关（Feature Flags 页面会显示 "active via environment variable" 提示）。provider / model 级开关在全局层之上做进一步细化 —— 例如全局关 + Kimi provider 开，则只暴露 Kimi 的模型。

该 flag 的服务端解析入口在 Feature Flags API（flag key 为 EXPOSE_CC_DISCOVERY_ALIASES），全局状态的存取位于 ccDiscoveryAliases。

⚠️ 非 Claude 模型的窗口不匹配。Claude Code 对任何它不认识的 id 都假定 200K 上下文窗口（它无法从 /v1/models 读到真实窗口）。对于窗口更大的模型（例如 Kimi K2 的 256K），应把 CLAUDE_CODE_AUTO_COMPACT_WINDOW 设为低于模型真实窗口的值，避免自动压缩过早触发。下文生成的 profiles 已按模型设置该值。

仪表盘上的 Onboarding 配置块

Dashboard → CLI Code 中的 Claude 工具卡片会渲染出针对当前实例的精确 settings.json 片段，旁边是发现别名信息按钮和复制按钮：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  },
}

base URL 由该卡片解析（包含你手动输入的自定义覆盖），且已归一化 —— 无 /v1 后缀、无尾部斜杠。key 永远不会被渲染：块里放的是占位符，因此截图或粘贴的片段不可能泄露密钥，需自行粘贴替换。

对于真实上下文窗口不是 200K 的模型，可在同一个 env 块中追加 CLAUDE_CODE_AUTO_COMPACT_WINDOW。片段构建器同样接受该值 —— 知道目标模型窗口的调用方可以直接生成出来。

源码证据：claudeCliConfig.ts 中的 buildClaudeDiscoverySettingsSnippet 是一个纯函数构建器（无密钥、无 I/O），行为可完整单测：

• ANTHROPIC_BASE_URL 经 normalizeClaudeBaseUrl 归一化（trim + 去尾部斜杠）；
• ANTHROPIC_AUTH_TOKEN 按调用方传入的值逐字渲染 —— 调用方传占位符，所以永远不会写入真实 key；
• 仅当 autoCompactWindow 是有限正数时才追加 CLAUDE_CODE_AUTO_COMPACT_WINDOW，且向下取整后转字符串（Claude Code 把 settings 的 env 值当字符串读）；
• 同文件还导出 getStoredClaudeAuthValue，按 ANTHROPIC_AUTH_TOKEN ?? ANTHROPIC_API_KEY 的顺序取认证值并 trim。

渲染端是 ClaudeGatewayOnboardingBlock.tsx/dashboard/cli-code/components/ClaudeGatewayOnboardingBlock.tsx)，测试覆盖在 claude-cli-config.test.ts。

Profiles：用 CLAUDE_CONFIG_DIR 实现多模型配置

Claude Code 没有原生 profile 文件（不同于 Codex 的 ~/.codex/<name>.config.toml）。惯用机制是 CLAUDE_CONFIG_DIR —— 每个 profile 一个独立配置目录，各自拥有独立的 settings.json、凭据、历史和缓存。

omniroute setup-claude 会拉取线上 /v1/models 目录，为每个模型在 ~/.claude/profiles/<name>/settings.json 写一个 profile，并且复用与 setup-codex 相同的命名（glm52、kimi-k27、deepseek-pro 等）：

// ~/.claude/profiles/glm52/settings.json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "glm/glm-5.2",
  "effortLevel": "xhigh",
  "env": {
    "ANTHROPIC_BASE_URL": "http://192.168.0.15:20128",
    "ANTHROPIC_MODEL": "glm/glm-5.2",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "190000",
  },
}

profile 中从不写入认证 token。 用 omniroute launch --profile <name> 启动（它会从当前上下文注入 ANTHROPIC_AUTH_TOKEN），或者自己 export ANTHROPIC_AUTH_TOKEN 后运行 CLAUDE_CONFIG_DIR=~/.claude/profiles/<name> claude。

生成与使用 profile

# 本地 OmniRoute
omniroute setup-claude

# 远程 VPS（把 VPS URL 固化进每个 profile）
omniroute setup-claude --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# 只处理部分 provider
omniroute setup-claude --only glm,kimi

# 预览但不写文件
omniroute setup-claude --dry-run

# 启动某个 profile
omniroute launch --profile kimi-k27

模型发现后的自动同步（opt-in）

当 provider 模型同步改变了线上目录（新模型/改名）时，OmniRoute 可以自动重新生成上面这批 ~/.claude/profiles/<name>/settings.json，无需重跑命令。该功能默认关闭：在 CLI Code 仪表盘切换（"CLI profile auto-sync" → Claude Code），或设置 OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true（同时受 CLI_ALLOW_CONFIG_WRITES 约束，后者默认开启）。启用后它只写 profile 文件，绝不改动你当前激活的/默认的 Claude 配置、认证或 ~/.claude/settings.json。

claudeProfileAutoSync.ts 的实现印证了这些安全边界：

• 开关解析走 feature flag（OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES），优先级为 DB/仪表盘开关 > 环境变量 > 默认 "false"；
• 先过 ensureCliConfigWriteAllowed() 写保护，未授权直接跳过；
• 通过内部接口拉 /v1/models（10 秒超时，redirect: "error"），失败时返回跳过原因而非抛错；
• 生成的 profile base URL 会剥掉尾部 /v1（注释明确写着 "Claude Code appends the version segment itself"）；
• 最后动态导入 CLI 命令模块 bin/cli/commands/setup-claude.mjs 的 syncClaudeProfilesFromModels，保证自动同步与手动 omniroute setup-claude 行为完全一致。

模型层级（可选）

Claude Code 会按能力层级（tier）路由请求。如果想让不同层级走不同 provider，可用环境变量或 settings 映射：

export ANTHROPIC_DEFAULT_OPUS_MODEL="glm/glm-5.2"
export ANTHROPIC_DEFAULT_SONNET_MODEL="kmc/kimi-k2.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm/glm-4.7-flash"

不设置时，单一 ANTHROPIC_MODEL（即 profiles 设置的那个）将用于全部请求。

远程模式

执行过 omniroute connect <host>（参见 Remote Mode）后，omniroute launch 和 omniroute setup-claude 会自动指向该远程服务器并使用其 scoped access token，无需额外参数。也可用 --remote / --api-key 在单次调用时覆盖。

故障排查

Claude Code 忽略了网关 —— 确认 ANTHROPIC_BASE_URL 没有 /v1 后缀，并重启 claude（env 只在启动时读一次）。omniroute launch 会替你处理好这些。

/model 选择器为空 / 缺少网关模型 —— 需要 Claude Code v2.1.219+ 且 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1。选择器中只会出现 claude* / anthropic* 开头的模型 id；其他模型请用 ANTHROPIC_MODEL=<id> 强制指定（profiles 就是这么做的）。

400 Ambiguous model 'claude-…' —— Claude Code 发送的始终是不带前缀的模型 id（如 claude-opus-4-8）。当 Claude Code（cc/…）和 Claude（claude/…）两个 provider 同时连接时，裸 id 会命中两条路由，OmniRoute 拒绝猜测。两种修法：用 ANTHROPIC_MODEL=cc/claude-opus-4-8 固定带前缀的 id；或启用 Prefer Claude Code for unprefixed Claude models（Claude provider 页面上的开关，或环境变量 OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=true，默认关，见 Environment 参考），把裸 claude-* id 路由到 Claude Code。显式 provider 前缀始终优先。

认证错误 —— profile 里不存 token。用 omniroute launch --profile（自动注入）或自行导出 ANTHROPIC_AUTH_TOKEN。

Profiles 没有隔离 —— 每个 profile 就是一个独立的 CLAUDE_CONFIG_DIR；在会话内执行 echo $CLAUDE_CONFIG_DIR，应指向 ~/.claude/profiles/<name>。

小结与延伸阅读

• 核心配置逻辑：claudeCliConfig.ts（纯函数、可单测）与 claudeProfileAutoSync.ts（opt-in 自动同步）；
• 仪表盘渲染：ClaudeGatewayOnboardingBlock.tsx/dashboard/cli-code/components/ClaudeGatewayOnboardingBlock.tsx)；
• 测试：claude-cli-config.test.ts；
• 本文对应的仓库原始文档：CLAUDE-CODE-CONFIGURATION.md；
• 相关指南：Codex CLI 配置、Remote Mode、Environment 参考。

整套方案的关键取舍值得记住：密钥永不落盘（profile 与仪表盘片段都只放占位符）、自动写盘默认关闭并受双重开关约束、base URL 归一化只去尾部斜杠而不代劳 /v1 —— 这些约束共同保证了多模型接入既方便又可审计。