Claude Code CLI — Configuration with OmniRoute (中文 (繁體))

快速開始

# 針對本機 OmniRoute 啟動 Claude Code（自動偵測目前啟用的情境）
omniroute launch

# 針對遠端 OmniRoute 啟動（執行 `omniroute connect <host>` 後會自動套用）
omniroute launch --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# 產生各模型專屬設定檔，然後使用其中一個啟動
omniroute setup-claude            # 寫入 ~/.claude/profiles/<name>/settings.json
omniroute launch --profile glm52  # Claude Code 透過 OmniRoute 使用 glm/glm-5.2

---

Claude Code 如何連線至閘道

Claude Code 使用 Anthropic Messages API，並透過環境變數指向自訂 端點（它沒有 --base-url 旗標）：

變數	用途
ANTHROPIC_BASE_URL	閘道根 URL（Claude Code 會附加 /v1/messages）。請勿加上 /v1 後綴。
ANTHROPIC_AUTH_TOKEN	以 Authorization: Bearer … 傳送——請使用你的 OmniRoute 存取權杖／API 金鑰
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	自動壓縮的 token 閾值

環境變數只會在啟動時讀取一次——變更後請重新啟動 Claude Code。

omniroute launch 會替你設定上述所有項目：它會從目前啟用的情境解析基礎 URL 與權杖 （因此先執行 omniroute connect <vps>，再執行 omniroute launch 即可直接運作）、 檢查伺服器健康狀態，然後執行 claude。

---

探索別名——讓非 Claude 模型顯示在 /model 選擇器中

Claude Code 的閘道模型探索功能只會列出 ID 以 claude 或 anthropic 開頭的模型，因此即使設定了 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1，原生 /model 選擇器通常也只會顯示 OmniRoute 的 Claude／Anthropic 模型—— kimi/kimi-k2.6 或 glm/glm-5.2 永遠不會出現，即使它們可正常路由。

OmniRoute 可以使用 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 提供者）則一律保持不變。

此功能預設關閉，並由三級控制機制管理（最具體的設定優先），因此未使用 Claude Code 的用戶端連接一般 OmniRoute 時，模型目錄不會增加一倍：

層級	位置
模型	提供者詳細資料頁面 → 各模型的「Expose in Claude Code」切換開關
提供者	提供者詳細資料頁面 → 提供者層級的切換開關（涵蓋其所有模型）
全域	設定 → 功能旗標 → EXPOSE_CC_DISCOVERY_ALIASES（預設關閉）

EXPOSE_CC_DISCOVERY_ALIASES 環境變數會強制啟用全域層級，並優先於儀表板的覆寫設定 （透過環境變數啟用時，「功能旗標」畫面會顯示「active via environment variable」 提示）。各提供者與各模型的切換開關可在此基礎上進一步細分——例如，全域關閉但 啟用 Kimi 提供者時，只會公開 Kimi 的模型。

⚠️ 非 Claude 模型的視窗不符。 Claude Code 會假設任何無法辨識的 ID 都有 200K 的上下文視窗（它無法從 /v1/models 讀取實際視窗大小）。對於視窗更大的 模型（例如 Kimi K2 的 256K），請將 CLAUDE_CODE_AUTO_COMPACT_WINDOW 設定為 低於模型實際視窗大小的值，避免過早觸發自動壓縮。上述產生的設定檔已針對各模型 完成此項設定。

---

儀表板上的入門設定區塊

Claude 工具卡片（儀表板 → CLI Code）會在探索別名資訊按鈕旁顯示此執行個體的確切 settings.json 片段，並附有複製按鈕：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<您的 OmniRoute API 金鑰>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
  },
}

基礎 URL 是卡片解析出的 URL（包括您輸入的自訂覆寫值），並且已正規化——沒有 /v1 後綴，也沒有尾端斜線。絕不會顯示金鑰：此區塊提供的是預留位置，因此螢幕截圖或貼上的片段不會洩漏金鑰。請將您的金鑰貼到該位置。

對於實際上下文視窗不是 200K 的任何模型，請在同一個 env 區塊下新增 CLAUDE_CODE_AUTO_COMPACT_WINDOW——Claude Code 會假設所有無法辨識的 id 都具有 200K 的上下文視窗，因此自動壓縮會在錯誤的時間點觸發（請參閱上一節的警告）。片段建構器也接受此值，因此知道目標模型視窗大小的呼叫端可以直接輸出該值。

來源：src/shared/services/claudeCliConfig.ts::buildClaudeDiscoverySettingsSnippet（純建構器，已通過單元測試），由 ClaudeGatewayOnboardingBlock 轉譯。

---

設定檔（CLAUDE_CONFIG_DIR）

Claude Code 沒有原生設定檔檔案（不同於 Codex 的 ~/.codex/<name>.config.toml）。慣用機制是 CLAUDE_CONFIG_DIR——每個設定檔使用獨立的設定目錄，各自擁有自己的 settings.json、憑證、歷史記錄與快取。

omniroute setup-claude 會擷取即時 /v1/models 目錄，並在 ~/.claude/profiles/<name>/settings.json 中為每個模型寫入一個設定檔，重複使用與 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",
  },
}

驗證權杖絕不會寫入設定檔。 請使用 omniroute launch --profile <name> 啟動（它會從作用中的上下文注入 ANTHROPIC_AUTH_TOKEN），或自行匯出 ANTHROPIC_AUTH_TOKEN，然後執行 CLAUDE_CONFIG_DIR=~/.claude/profiles/<name> claude。

模型探索後自動同步（選用）。 每當提供者模型同步變更即時目錄時，OmniRoute 可以自動重新產生相同的 ~/.claude/profiles/<name>/settings.json 檔案——因此新增或重新命名的模型不需重新執行命令即可取得設定檔。此功能預設為關閉：請從 CLI Code 儀表板切換此設定（「CLI 設定檔自動同步」→ Claude Code），或設定 OMNIROUTE_AUTO_SYNC_CLAUDE_PROFILES=true（它也會遵循 CLI_ALLOW_CONFIG_WRITES，此設定預設為開啟）。啟用後，它只會寫入設定檔檔案；絕不會變更作用中／預設的 Claude 設定、驗證資訊或 ~/.claude/settings.json。

產生及使用設定檔

# 本機 OmniRoute
omniroute setup-claude

# 遠端 VPS（將 VPS URL 寫入每個設定檔）
omniroute setup-claude --remote http://192.168.0.15:20128 --api-key oma_live_xxx

# 僅限部分提供者
omniroute setup-claude --only glm,kimi

# 預覽但不寫入
omniroute setup-claude --dry-run

# 啟動設定檔
omniroute launch --profile kimi-k27

---

模型層級（選用）

Claude Code 會路由至不同的能力層級。若你想為每個層級使用不同的提供者，可透過環境變數／設定，將各層級對應至 OmniRoute 模型：

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（由設定檔設定）。

---

遠端模式

執行 omniroute connect <host> 後（請參閱 遠端模式），omniroute launch 和 omniroute setup-claude 會自動以該遠端伺服器為目標，並使用其限定範圍的存取權杖，無須 額外旗標。可在每次呼叫時使用 --remote／--api-key 覆寫。

---

疑難排解

Claude Code 忽略閘道 — 確認 ANTHROPIC_BASE_URL 不包含 /v1，並重新啟動 claude（環境變數只會在啟動時讀取一次）。omniroute launch 會自動為你處理此事。

/model 選擇器是空的／缺少閘道模型 — 需要 Claude Code v2.1.219+ 以及 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1。選擇器中只會顯示 claude*／ anthropic* 模型 ID；若要強制使用任何其他模型，請設定 ANTHROPIC_MODEL=<id>（設定檔正是如此運作）。

400 Ambiguous model 'claude-…' — Claude Code 一律傳送不帶前綴的 模型 ID（例如 claude-opus-4-8），因此當 Claude Code（cc/…）和 Claude（claude/…）提供者皆已連線時，裸 ID 會符合兩條路由，而 OmniRoute 會拒絕自行猜測。可使用任一方式修正：透過 ANTHROPIC_MODEL=cc/claude-opus-4-8 鎖定帶前綴的 ID，或啟用 未加前綴的 Claude 模型優先使用 Claude Code — Claude 提供者頁面上的切換開關，或 OMNIROUTE_PREFER_CLAUDE_CODE_FOR_UNPREFIXED_CLAUDE_MODELS=true（預設關閉； 請參閱環境）— 這會改為將裸 claude-* ID 路由至 Claude Code。明確的提供者前綴一律優先。

驗證錯誤 — 設定檔不包含權杖。請使用 omniroute launch --profile （會注入權杖）或匯出 ANTHROPIC_AUTH_TOKEN。

設定檔未隔離 — 每個設定檔都是不同的 CLAUDE_CONFIG_DIR； 請確認工作階段內的 echo $CLAUDE_CONFIG_DIR 指向 ~/.claude/profiles/<name>。

---

OmniRoute 原始碼 (a58000c7685f)