model-relay v0.6.0

Use Remote Control without losing the relay (proxy.enabled with a local CA constrained to api.anthropic.com), point haiku / sonnet / opus aliases at any provider in one command (setup.mjs alias & /provider alias), and spawn provider subagents on the fly (subagent_type: "model-relay:<name>") without .claude/agents/*.md files or restarting your session. The /provider panel also adds live toggles for 429 failover (failover.chain), retries (retry.enabled), and Remote Control (f / t / x).

Upgrading: Pull the latest version or run claude plugin update model-relay@model-relay. Run node tools/setup.mjs migrate --go if you want to clean up legacy config keys.

Added

• Remote Control with the relay still in the path (HTTPS proxy mode): Claude Code keeps api.anthropic.com as its address, which Remote Control requires, and uses the relay as its HTTPS_PROXY. The relay answers for api.anthropic.com with its own certificate and routes model calls exactly as before (providers, sticky 429 failover, retries); token refresh, Remote Control traffic and WebSocket upgrades pass to Anthropic unchanged, and every other host is a plain byte tunnel. Opt-in: off by default, so the router never acts as an open proxy for anyone who does not use Remote Control. Setting: proxy.enabled.
• Name-constrained local certificate authority: The CA can only vouch for api.anthropic.com, its private key is discarded after it signs the one leaf certificate, and only processes that carry NODE_EXTRA_CA_CERTS trust it. Without a usable certificate the relay tunnels api.anthropic.com untouched, so Claude Code keeps working.
• setup.mjs proxy and setup.mjs rc: proxy status|enable|disable|renew (add --go to apply) switches settings.json between API-address mode and proxy mode, keeps a settings.json.relay-backup copy and refuses settings it does not own; rc starts the router when needed and then runs claude remote-control.
• Failover chain: failover.chain lists the providers that take over, in order. When Claude hits its limit the first one answers, and with retry.failover a provider that keeps failing hands the request to the next one, never back to one it already tried. A provider can override this with providers.<name>.fallback (false for nobody, or its own list).
• Retry master switch: retry.enabled set to false turns retrying off everywhere and keeps the other retry settings for later.
• Switches in the /provider panel: three rows turn 429 failover, retry and Remote Control on or off (hotkeys f, t, x). Remote Control asks for confirmation first because it rewrites settings.json; the panel changes the file through the same set and proxy commands of setup.mjs.
• Config commands in setup.mjs: set changes one switch or list after validating it, providers shows routes, failover and retry per provider, remove deletes a provider from the file and from every failover list, and migrate moves an old file to the current layout. Edits keep a .relay-backup copy, tokens are never printed, and the router reads the result on its next request.
• First-class model alias management (setup.mjs alias & /provider alias): Inspect or point haiku, sonnet, opus, or subagent (CLAUDE_CODE_SUBAGENT_MODEL) at any provider or back to Claude in one command, keeping ~/.claude/settings.json (ANTHROPIC_DEFAULT_*_MODEL) and ~/.claude/model-relay.json (matchModels) in sync. /provider and the panel now display model aliases separately from 429 failover and support /provider alias|failover|retry|rc directly from the prompt.
• Dynamic model-relay:<provider> subagent types ($.agent.register & agent.spawn): Because Claude Code's Agent tool validates model against "sonnet"|"opus"|"haiku"|"fable", the plugin dynamically registers model-relay:<name> (such as model-relay:glm and model-relay:gemini) with full parent tools and the provider's model ID, and locks that model in on('agent.spawn')—no static .claude/agents/*.md file or session restart needed.

Changed

• doctor understands proxy mode: doctor --fix no longer puts ANTHROPIC_BASE_URL back when proxy mode is on, and /__health reports proxy state and connection counts.
• Cleaner config layout: failover holds enabled, chain and cooldownMs, and providers live only under providers. The old top-level baseUrl, token, model, gemini, failoverEnabled, probeEveryMin and failoverProvider still work and are read as if migrated; migrate --go rewrites the file with the same behaviour.
• doctor checks the config: it warns about an old layout, failover names that match no provider, and a model name that another provider's matchModels claims first, and its failover line shows the chain and the cooldown.
• /__health reports the switches: failoverChain and config show what the router is really doing, so the panel never guesses.

Fixed

• failover.cooldownMs was ignored: the documented setting had no effect because the router read probeEveryMin. failover.cooldownMs now sets how long new sessions stay off Claude, with a one-minute minimum.
• A half-saved config no longer fails requests: the router keeps the last good config when the file cannot be read for a moment, and the setup.mjs commands write files in one step.
• Claude model names matched via matchModels are now rewritten on the wire: when a request carrying a claude-* model (such as a hardcoded claude-haiku-4-5-20251001) matches a provider's matchModels, the router now rewrites the body's model field to that provider's target model instead of forwarding the claude-* name unchanged.

---

繁體中文

支援保留轉發站的手機 Remote Control（proxy.enabled 搭配只限 api.anthropic.com 的本機 CA）、一行指令設定 haiku／sonnet／opus 模型別名分流（setup.mjs alias 與 /provider alias），並動態註冊可直接派工的供應商子代理（subagent_type: "model-relay:<name>"），免建 .claude/agents/*.md 也免重開對話。/provider 互動面板同步新增 429 備援（failover.chain）、失敗重試（retry.enabled）與手機遙控三列開關（熱鍵 f／t／x）。

升級： 拉取最新版本或執行 claude plugin update model-relay@model-relay。若想整理舊版設定鍵，可執行 node tools/setup.mjs migrate --go。

新增

• 轉發站留在路徑上也能用 Remote Control（HTTPS 代理模式）： Claude Code 維持 api.anthropic.com 當位址（Remote Control 的要求），改把轉發站當成它的 HTTPS_PROXY。轉發站以自己的憑證代答 api.anthropic.com，模型請求照舊分流（供應商、429 黏著備援、重試）；token 更新、Remote Control 流量與 WebSocket 升級原封不動交給 Anthropic，其他網站則是單純的位元組通道。選用功能：預設關閉，沒用 Remote Control 的人，轉發站不會變成開放代理。設定：proxy.enabled。
• 限定網域的本機憑證授權單位： 這個 CA 只能為 api.anthropic.com 背書，簽完唯一的那張葉憑證後私鑰立即丟棄，而且只有帶 NODE_EXTRA_CA_CERTS 的程序才會信任它。沒有可用憑證時，轉發站會把 api.anthropic.com 原封不動轉送，Claude Code 照常運作。
• setup.mjs proxy 與 setup.mjs rc： proxy status|enable|disable|renew（加 --go 才會套用）在 API 位址模式與代理模式之間切換 settings.json，保留 settings.json.relay-backup 備份，且不會碰不屬於轉發站的設定；rc 會在需要時先啟動轉發站，再執行 claude remote-control。
• 備援名單： failover.chain 依序列出接手的供應商。Claude 額度用完時由第一個回答；開啟 retry.failover 後，持續失敗的供應商會把請求交給下一個，不會回頭找已經試過的。供應商可以用 providers.<name>.fallback 覆寫（false 代表不交給任何人，或自己的清單）。
• 重試總開關： retry.enabled 設為 false 即全面停止重試，其他重試設定會保留，之後再開即可。
• /provider 面板上的開關： 三列開關可開關 429 備援、重試與 Remote Control（熱鍵 f、t、x）。Remote Control 會改寫 settings.json，所以先確認再執行；面板是透過 setup.mjs 同一組 set 與 proxy 指令修改檔案。
• setup.mjs 的設定指令： set 驗證後修改單一開關或清單，providers 逐一列出路由、備援與重試，remove 把供應商從檔案與所有備援名單中移除，migrate 把舊格式檔案整理成目前的格式。每次修改都會留一份 .relay-backup 備份、token 一律不會印出，轉發站在下一個請求就會讀到結果。
• 一鍵模型別名管理（setup.mjs alias 與 /provider alias）： 可在單一指令查看或將 haiku、sonnet、opus 與 subagent（CLAUDE_CODE_SUBAGENT_MODEL）指向指定供應商或還原回 Claude，自動同步更新 ~/.claude/settings.json（ANTHROPIC_DEFAULT_*_MODEL）與 ~/.claude/model-relay.json（matchModels）。/provider 與互動面板現在將「別名分流」與「429 備援」分開揭露，並支援直接在對話框輸入 /provider alias|failover|retry|rc。
• 動態註冊 model-relay:<provider> 子代理類型（$.agent.register 與 agent.spawn）： 針對 Claude Code Agent 工具 model 欄位只接受 "sonnet"|"opus"|"haiku"|"fable" 的限制，外掛現在會自動為每個供應商動態註冊具備完整父層工具的 model-relay:<name>（如 model-relay:glm、model-relay:gemini），並在 on('agent.spawn') 鎖定該供應商的模型 ID——無須建立 .claude/agents/*.md 或重開對話。

變更

• doctor 認得代理模式： 代理模式開啟時，doctor --fix 不會再把 ANTHROPIC_BASE_URL 加回去，/__health 也會回報代理狀態與連線數。
• 設定檔格式更乾淨： failover 底下放 enabled、chain 與 cooldownMs，供應商只放在 providers。舊的頂層 baseUrl、token、model、gemini、failoverEnabled、probeEveryMin 與 failoverProvider 仍可使用，讀取時等同已整理過；migrate --go 會在行為不變的前提下改寫檔案。
• doctor 會檢查設定： 提醒舊版格式、備援名單裡不存在的供應商，以及被別的供應商的 matchModels 先攔走的模型名稱，備援那一行也會顯示名單與冷卻時間。
• /__health 回報開關狀態： failoverChain 與 config 讓面板顯示轉發站實際的狀態，而不是猜測。

修正

• failover.cooldownMs 沒有作用： 文件寫的設定沒有生效，因為轉發站讀的是 probeEveryMin。現在 failover.cooldownMs 會決定新對話離開 Claude 多久，最小一分鐘。
• 存到一半的設定檔不再讓請求失敗： 檔案暫時讀不到時，轉發站會沿用上一份正常的設定；setup.mjs 的指令也改成一次寫完整個檔案。
• 經由 matchModels 攔截的 claude-* 請求會正確改寫模型名稱： 當帶有 claude-*（例如 Claude Code 內部寫死的 claude-haiku-4-5-20251001）的請求符合某個供應商的 matchModels 時，轉發站現在會把送往上游的 model 欄位改寫為該供應商的目標模型，不再原樣送出 claude-*。

Full changelog / 完整差異： v0.5.0...v0.6.0

model-relay v0.4.0

Type /provider to open an interactive AbovePrompt control panel right above your prompt input box: switch the current window's model with one click (or hotkeys 1–9), test live latency across every provider ([Ping]), and protect long prompt caches with a two-click confirmation before switching back to Claude. Both English and Traditional Chinese READMEs now have their own animated banners and story diagrams.

Upgrading: Pull the latest version or run claude plugin update model-relay@model-relay. No configuration changes are required.

Added

• Interactive AbovePrompt control panel: Running /provider or /provider panel opens an interactive panel above the prompt where you can switch providers by clicking buttons or pressing ctrl+x tab + 1–9, with a two-step confirmation before switching a pinned session back to Claude.
• Live upstream latency ping (/__ping and /provider ping): Test live HTTP status and response time for all configured providers directly from the panel ([Ping]) or via /provider ping, and reset 429 cooldown timers via [Retry Claude] or /provider probe.
• Separate English and Traditional Chinese animated SVGs: Added dedicated English and Traditional Chinese dark/light banners (banner-dark.svg, banner-light.svg, banner-dark.zh-TW.svg, banner-light.zh-TW.svg) and story animations (relay-flow.svg / .zh-TW.svg, panel.svg / .zh-TW.svg).

---

繁體中文

輸入 /provider 即可在輸入框上方開啟 AbovePrompt 互動控制面板：一鍵（或按熱鍵 1–9）切換單一視窗的模型、即時測試各供應商的回應延遲（[Ping]），並在切回 Claude 前提供二次確認以保護長對話快取。英文與繁體中文 README 現在各自擁有獨立的深淺色動態 Banner 與情境動畫圖。

升級： 拉取最新版本或執行 claude plugin update model-relay@model-relay 即可，無須修改現有設定檔。

新增

• 輸入框上方的 AbovePrompt 互動控制面板： 執行 /provider 或 /provider panel 會在輸入框上方打開互動面板，可直接點選按鈕或按 ctrl+x tab 加數字鍵 1–9 切換模型，並在將已固定的長對話切回 Claude 前提供二次確認防呆。
• 上游供應商即時連線測速（/__ping 與 /provider ping）： 可直接從面板點選 [Ping] 或輸入 /provider ping 即時測試所有供應商的 HTTP 狀態碼與回應時間，並支援透過 [Retry Claude] 或 /provider probe 重置 429 冷卻計時。
• 中英雙語獨立動態 SVG： 為英文與繁體中文分別設計專屬的深淺色動態 Banner（banner-dark.svg、banner-light.svg、banner-dark.zh-TW.svg、banner-light.zh-TW.svg）以及兩組情境動畫（relay-flow.svg / .zh-TW.svg、panel.svg / .zh-TW.svg）。

Full changelog / 完整差異： v0.3.0...v0.4.0

model-relay v0.3.0

model-relay is now open-source as a flexible, multi-provider localhost router and failover toolkit for Claude Code. You can route individual conversations or haiku subagents across Claude, GLM (z.ai), Gemini (via local gateway), DeepSeek, Kimi, MiniMax, or OpenRouter without losing prompt cache efficiency when Claude hits a 429 usage limit.

Upgrading: Existing ~/.claude/custom-agent.json files continue to work without changes. Run node tools/setup.mjs init --fix and node tools/setup.mjs doctor --ping to verify your setup or migrate to ~/.claude/model-relay.json.

Added

• Flexible multi-provider routing and built-in presets: Configure any number of providers under providers.<name> using built-in presets (zai, glm, deepseek, kimi, minimax, openrouter, gemini, magpie) so baseUrl, model, matchModels, stripToolSearch, stripCacheControl, and authHeader work out of the box with just a token. Setting: providers.
• Cache-safe sticky 429 failover: When Anthropic returns a 429 usage-limit response, the router automatically forwards to failover.provider and pins that session for 7 days so recovering Claude quota never triggers an expensive 800k-token prompt cache rebuild on existing long chats. Setting: failover.
• Structured /provider command and live provider sync: /provider now displays an aligned route list (● active vs ○ available) synced directly with the router's live /__health endpoint, hiding providers whose env:VAR_NAME token is unset.
• One-command doctor and upstream --ping CLI: Run node tools/setup.mjs doctor --fix --ping to validate config syntax, detect unset env:VAR variables, wire ANTHROPIC_BASE_URL into ~/.claude/settings.json, check localhost router health, and send a 1-token live probe to every configured provider.
• Local gateway supervision (launch): Providers pointing at 127.0.0.1 or localhost can declare launch: { command, args } so the router automatically spawns the local gateway whenever its TCP port is closed. Setting: providers.<name>.launch.
• Cross-platform and bilingual UI support: Supports both Windows (powershell.exe + curl.exe) and macOS/Linux (sh + curl), with English and Traditional Chinese status/command output plus SVG architecture diagrams.

Removed

• Legacy child-process custom_agent tool: Removed the deprecated claude.exe -p child-process wrapper so the plugin focuses purely on fast, zero-overhead HTTP relay and session routing.

---

繁體中文

model-relay 正式開源為 Claude Code 專用的多供應商本機模型轉發站與 429 自動備援工具。你可以在不中斷工作、不浪費長對話快取的前提下，將單一對話或 haiku 子代理靈活分流至 Claude、GLM（z.ai）、Gemini（透過本地端 Gateway）、DeepSeek、Kimi、MiniMax 或 OpenRouter。

升級： 既有的 ~/.claude/custom-agent.json 無須修改即可繼續使用。可執行 node tools/setup.mjs init --fix 與 node tools/setup.mjs doctor --ping 進行全鏈路體檢或遷移至 ~/.claude/model-relay.json。

新增

• 彈性多供應商路由與內建 Presets： 在 providers.<name> 下自由新增任意數量的供應商，內建 zai、glm、deepseek、kimi、minimax、openrouter、gemini、magpie 預設集，只需填寫 token 即可自動帶入最佳的 baseUrl、model、matchModels、stripToolSearch、stripCacheControl 與 authHeader。設定：providers。
• 保護快取的 429 自動備援與對話黏著： 當 Anthropic 回傳 429 額度上限時，自動切換至 failover.provider 並將該對話固定 7 天；Claude 額度恢復後只有新對話回到 Claude，避免長對話切回時重建 80 萬+ token 快取而瞬間燒光額度。設定：failover。
• 結構化 /provider 清單與即時狀態同步： /provider 改為對齊顯示目前所在路由（●）與可切換路由（○），並直接與轉發站 /__health 同步，自動隱藏尚未匯出 env:VAR_NAME 金鑰的供應商。
• 一鍵 doctor 全鏈路體檢與上游 --ping 實測： 執行 node tools/setup.mjs doctor --fix --ping 即可一次檢查設定檔語法、未設定的 env:VAR 環境變數、自動將 ANTHROPIC_BASE_URL 寫入 ~/.claude/settings.json、確認本機轉發站健康度，並對每個供應商發送 1-token 真實請求測試連線延遲。
• 本地端 Gateway 自動拉起（launch）： 指向 127.0.0.1 或 localhost 的供應商可設定 launch: { command, args }，當本機連接埠未開啟時由轉發站在背景自動啟動程序。設定：providers.<name>.launch。
• 跨平台與中英雙語介面： 同時支援 Windows（powershell.exe + curl.exe）與 macOS/Linux（sh + curl），依 Claude Code 語系設定自動切換繁體中文／英文介面，並附深淺色 Banner 與架構流程 SVG。

移除

• 舊版 custom_agent 子程序工具： 移除已棄用的 claude.exe -p 子程序包裝程式碼，讓外掛專注於純粹、零額外負擔的 HTTP 模型轉發與對話路由。

Full changelog / 完整差異： https://github.com/cablate/model-relay/releases/tag/v0.3.0