# 模型管理

每項模型與憑證操作，及其對應的 TUI 指令與 HTTP 端點。

一切由 TUI 或本機 HTTP API 管理——沒有 `agen model` CLI 子指令：

| 工作 | TUI | HTTP |
|---|---|---|
| 新增 / 移除供應商或模型 | `/model` → `add`；在模型列按 `d` 移除 | `POST` `/v1/models`、`DELETE` `/v1/models/*name` |
| 調整 fallback 優先序 | — | `GET` `POST` `/v1/model/priority` — `{models}` |
| 設定模型 tier | `/model`，在模型列按 `t` | `POST` `/v1/model/tier` — `{model, tier}` |
| 選擇 dispatcher 模型 | `/model` → `dispatch` | `GET` `POST` `/v1/model` — `{dispatcher}` |
| 選擇 session 的 reasoning 等級 | `/model` → `reasoning`（或 `Shift+A` / `Shift+D`） | `POST` `/v1/session/:id` — `{reasoning}` |
| 選擇 summary 模型 | `/model` → `summary` | `GET` `POST` `/v1/model` — `{summary}` |
| 選擇圖像產生器 | `/model` → `image` | `GET` `POST` `/v1/model` — `{image}`，填 provider 端點而非模型名稱 |
| 選擇 speech-to-text 模型 | `/model` → `stt` | `GET` `POST` `/v1/model` — `{stt}`，取值來自 `GET /v1/model/audio` |
| 選擇 text-to-speech 模型 | `/model` → `tts` | `GET` `POST` `/v1/model` — `{tts}`，取值來自 `GET /v1/model/audio` |
| 選擇 session 使用的模型 | `/model`（或以 `Shift+W` / `Shift+S` 在 `auto` 與已註冊模型間輪替） | `POST` `/v1/session/:id` — `{model, reasoning}` |
| 儲存憑證 | `/key` | `POST` `/v1/provider/:provider/key` |
| OAuth 登入 | `/model` | `GET` `/v1/provider/:provider/oauth`（SSE device code） |
| 清除 OAuth 登入 | `/model` | `DELETE` `/v1/provider/:provider/oauth` |
| 查詢額度 / 餘額 | `Shift+U` | `GET` `/v1/providers/quota`；單一模型所屬供應商：`GET` `/v1/model/quota?model=<name>` |

模型路由是單一物件：`GET` / `POST` `/v1/model` 一併讀取與部分更新 `dispatcher`、`summary`、`image`、`stt` 與 `tts`。未帶到的欄位不動，`""` 為清除。寫入 `config.json` 時對應 `dispatcher_model`、`summary_model`、`image_generator`、`stt_model` 與 `tts_model`。

音訊路由與模型註冊表分離。`stt` 與 `tts` 不是從 `/model add` 註冊過的模型中挑選，而是向目前握有憑證的 OpenAI、Gemini 與 OpenRouter 即時查詢；現階段也只有這三家支援音訊（OpenRouter 於 v1.0.17 加入）。`tts` 選 `off` 會同時把 `generate_audio` 從工具集中移除；`stt` 選 `off` 則讓 `read_files` 不再轉錄音訊與影片，Telegram / Discord 收到的語音訊息也會直接回覆提示要先選模型。

憑證（API key、OAuth token）存放於 OS keychain 的 `agenvoy` 服務，絕不寫入純文字 JSON。`config.json` 的 `keys` 只記錄已儲存的 key 名稱。

Daemon 監看 `config.json`；寫入後會重新載入 agent registry（並重連 Telegram / Discord），不需重啟。

自 v1.0.13 起 registry 條目只持有模型名稱，改為每次 `Send` 時才解析 provider config，不再於啟動時建好 client，因此 keychain 內更新過的 OAuth token 下一次請求即生效，不必等 registry 重新載入。