# CLI Tools — OmniRoute (中文 (繁體)) 🌐 **Languages:** 🇺🇸 [English](../../../../reference/CLI-TOOLS.md) · 🇪🇹 [am](../../../am/docs/reference/CLI-TOOLS.md) · 🇸🇦 [ar](../../../ar/docs/reference/CLI-TOOLS.md) · 🇦🇿 [az](../../../az/docs/reference/CLI-TOOLS.md) · 🇧🇬 [bg](../../../bg/docs/reference/CLI-TOOLS.md) · 🇧🇩 [bn](../../../bn/docs/reference/CLI-TOOLS.md) · 🇧🇦 [bs](../../../bs/docs/reference/CLI-TOOLS.md) · 🇨🇿 [cs](../../../cs/docs/reference/CLI-TOOLS.md) · 🇩🇰 [da](../../../da/docs/reference/CLI-TOOLS.md) · 🇩🇪 [de](../../../de/docs/reference/CLI-TOOLS.md) · 🇬🇷 [el](../../../el/docs/reference/CLI-TOOLS.md) · 🇪🇸 [es](../../../es/docs/reference/CLI-TOOLS.md) · 🇪🇪 [et](../../../et/docs/reference/CLI-TOOLS.md) · 🇮🇷 [fa](../../../fa/docs/reference/CLI-TOOLS.md) · 🇫🇮 [fi](../../../fi/docs/reference/CLI-TOOLS.md) · 🇫🇷 [fr](../../../fr/docs/reference/CLI-TOOLS.md) · 🇮🇪 [ga](../../../ga/docs/reference/CLI-TOOLS.md) · 🇮🇳 [gu](../../../gu/docs/reference/CLI-TOOLS.md) · 🇳🇬 [ha](../../../ha/docs/reference/CLI-TOOLS.md) · 🇮🇱 [he](../../../he/docs/reference/CLI-TOOLS.md) · 🇮🇳 [hi](../../../hi/docs/reference/CLI-TOOLS.md) · 🇭🇷 [hr](../../../hr/docs/reference/CLI-TOOLS.md) · 🇭🇺 [hu](../../../hu/docs/reference/CLI-TOOLS.md) · 🇦🇲 [hy](../../../hy/docs/reference/CLI-TOOLS.md) · 🇮🇩 [id](../../../id/docs/reference/CLI-TOOLS.md) · 🇳🇬 [ig](../../../ig/docs/reference/CLI-TOOLS.md) · 🇮🇹 [it](../../../it/docs/reference/CLI-TOOLS.md) · 🇯🇵 [ja](../../../ja/docs/reference/CLI-TOOLS.md) · 🇬🇪 [ka](../../../ka/docs/reference/CLI-TOOLS.md) · 🇰🇭 [km](../../../km/docs/reference/CLI-TOOLS.md) · 🇮🇳 [kn](../../../kn/docs/reference/CLI-TOOLS.md) · 🇰🇷 [ko](../../../ko/docs/reference/CLI-TOOLS.md) · 🇱🇹 [lt](../../../lt/docs/reference/CLI-TOOLS.md) · 🇱🇻 [lv](../../../lv/docs/reference/CLI-TOOLS.md) · 🇮🇳 [ml](../../../ml/docs/reference/CLI-TOOLS.md) · 🇮🇳 [mr](../../../mr/docs/reference/CLI-TOOLS.md) · 🇲🇾 [ms](../../../ms/docs/reference/CLI-TOOLS.md) · 🇲🇹 [mt](../../../mt/docs/reference/CLI-TOOLS.md) · 🇲🇲 [my](../../../my/docs/reference/CLI-TOOLS.md) · 🇳🇵 [ne](../../../ne/docs/reference/CLI-TOOLS.md) · 🇳🇱 [nl](../../../nl/docs/reference/CLI-TOOLS.md) · 🇳🇴 [no](../../../no/docs/reference/CLI-TOOLS.md) · 🇮🇳 [or](../../../or/docs/reference/CLI-TOOLS.md) · 🇮🇳 [pa](../../../pa/docs/reference/CLI-TOOLS.md) · 🇵🇭 [phi](../../../phi/docs/reference/CLI-TOOLS.md) · 🇵🇱 [pl](../../../pl/docs/reference/CLI-TOOLS.md) · 🇵🇹 [pt](../../../pt/docs/reference/CLI-TOOLS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/CLI-TOOLS.md) · 🇷🇴 [ro](../../../ro/docs/reference/CLI-TOOLS.md) · 🇷🇺 [ru](../../../ru/docs/reference/CLI-TOOLS.md) · 🇱🇰 [si](../../../si/docs/reference/CLI-TOOLS.md) · 🇸🇰 [sk](../../../sk/docs/reference/CLI-TOOLS.md) · 🇸🇮 [sl](../../../sl/docs/reference/CLI-TOOLS.md) · 🇷🇸 [sr](../../../sr/docs/reference/CLI-TOOLS.md) · 🇸🇪 [sv](../../../sv/docs/reference/CLI-TOOLS.md) · 🇰🇪 [sw](../../../sw/docs/reference/CLI-TOOLS.md) · 🇮🇳 [ta](../../../ta/docs/reference/CLI-TOOLS.md) · 🇮🇳 [te](../../../te/docs/reference/CLI-TOOLS.md) · 🇹🇭 [th](../../../th/docs/reference/CLI-TOOLS.md) · 🇹🇷 [tr](../../../tr/docs/reference/CLI-TOOLS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/CLI-TOOLS.md) · 🇵🇰 [ur](../../../ur/docs/reference/CLI-TOOLS.md) · 🇺🇿 [uz](../../../uz/docs/reference/CLI-TOOLS.md) · 🇻🇳 [vi](../../../vi/docs/reference/CLI-TOOLS.md) · 🇳🇬 [yo](../../../yo/docs/reference/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/CLI-TOOLS.md) --- 最後更新: 2026-08-23 OmniRoute與分佈在三個專用儀表板頁面上的三類CLI工具整合： | 頁 | 路線 | 概念 | 數數 | | ----------- | ----------------------- | ---------------------------------------------------------------- | ------------ | | **CLI代碼** | `/dashboard/cli-code` | 你指向OmniRoute的編碼工具（Client → CLI → OmniRoute → Provider） | 26 | | **CLI代理** | `/dashboard/cli-agents` | 您指向OmniRoute自治代理（相同流程，範圍更廣） | 11 | | **ACP代理** | `/dashboard/acp-agents` | CLIs ， OmniRoute透過stdio/ACP作為後端產生（反向流） | 請參閱註冊表 | 舊路由透過 308 重定向： `/dashboard/cli-tools` → `/dashboard/cli-code`、 `/dashboard/agents` → `/dashboard/acp-agents`。 --- ## 運作方式 ``` CLI 程式碼／CLI 代理程式（使用流程）： Claude / Codex / OpenCode / Cline / KiloCode / Continue / Hermes Agent / Goose / ... │ ▼ （全部指向 OmniRoute） http://YOUR_SERVER:20128/v1 │ ▼ （OmniRoute 會將請求路由至正確的提供者） Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ... ACP 代理程式（反向產生流程）： 用戶端請求 → OmniRoute → 透過 stdio/ACP 產生 CLI → 回應 ``` **優點：** - 使用一組 API 金鑰管理所有工具 - 在儀表板中追蹤所有 CLI 的成本 - 切換模型時無須重新設定每個工具 - 可在本機及遠端伺服器上運作（VPS、Docker、Akamai、Cloudflare Tunnel） --- ## 使用`setup-*`自動配置 您不必手動編寫每個工具的配置。 OmniRoute為每個受支援的CLI提供一個`setup-*`命令，該命令讀取**居住**從正在運行的OmniRoute （本地或遠端）中取得模型目錄，並將該工具自己的配置寫入您的電腦： ```bash omniroute setup-codex omniroute setup-claude omniroute setup-opencode omniroute setup-cline omniroute setup-kilo omniroute setup-continue omniroute setup-cursor omniroute setup-roo omniroute setup-crush omniroute setup-goose omniroute setup-qwen omniroute setup-aider omniroute setup-5dive omniroute setup-zed omniroute setup-whycodes ``` 每個都接受`--remote --api-key ` （針對遠端OmniRoute配置本機工具）、 `--dry-run` （無需編寫即可預覽）和`--port`。沒有模型自動發現的工具（Cline、 Kilo、 Roo、 Goose、 Aider、 Qwen、 5dive、 WhyCodes）採用`--model ` （以及用於非互動式運行的`--yes` ）。 `setup-5dive`是不在`$HOME`下編寫的配方：它透過在艦隊主機上寫入 root 擁有的身份驗證設定檔來配置 5dive 代理艦隊，因此它透過`sudo`重新執行，並且沒有自己的遠端模式。要在註入正確的環境且根本不編寫配置的情況下啟動CLI ，請使用通用`omniroute run `啟動器（claude、codex、aider、goose、opencode、qwen、gemini、whycodes - 目標和別名來自`bin/cli/cli-manifest.mjs`）；舊版每個工具啟動器`omniroute launch` （Claude代碼）和`omniroute launch-codex` Codex可用。 Gemini CLI僅啟動：它是`omniroute run`目標，但沒有`setup-*`/`configure`配方。 > **完整參考：**主表——每個命令寫入的內容、每個標誌、本地與遠端以及哪些工具需要`/v1`後綴——位於**[CLI集成](../guides/CLI-INTEGRATIONS.md)**。 ### 在容器內運行它們 在OmniRoute容器內執行的`setup-*`指令會寫入容器自己的 home，主機CLI不會讀取該 home，而這個指令會隨容器一起消失。 OmniRoute偵測到這一點並使用指令而不是寫入退出`2` 。有兩種支援的方法 — 在主機上安裝CLI ，在容器上安裝`omniroute connect` ，或綁定掛載設定目錄並設定`CLI_CONFIG_HOME` （撰寫`host`設定檔）。每個`setup-*`命令，加上`omniroute configure`和`omniroute config set`，在配置容器自己的CLIs時接受`--allow-container-write`是您實際的意思； `OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE=true`對伺服器做同樣的事情。請參閱[Docker指南→配置主機CLI工具](../guides/DOCKER_GUIDE.md#configuring-host-cli-tools-when-omniroute-runs-in-docker)。 儀表板的**應用端點**(`POST /api/cli-tools/apply`) 強制執行相同的保護：在容器中，目標未從主機答案綁定安裝的寫入**`422`**使用`containerEphemeralTarget: true`，安全錯誤文字，以及 - 對於具有主機配方的工具（claude、codex、opencode、cline、kilo、 continue） - 在主機上運行的`hostSetupCommand` （例如`omniroute setup-opencode`）；什麼也沒寫。 `dryRun: true`繼續在容器模式下工作，並傳回經過編輯的預覽+目標路徑，而無需接觸磁碟。預覽內容不是要複製或匯入的帶有憑證的配置。應用主機上的原始tool/base URL/API key/model輸入，或使用指示的主機端設定指令。請參閱預覽標頭和請求合約的[CLI配置安全性](../security/CLI-CONFIGURATION.md)。這種行為是故意的，並且由`tests/unit/api/cli-tools/apply-container-guard.test.ts`進行回歸保護——永遠不要透過刪除保護來「修復」422。 --- ## 真實來源 統一目錄位於 `src/shared/constants/cliTools.ts`，其定義為 `CLI_TOOLS: Record`。 每個項目都包含以下欄位（定義於 `src/shared/schemas/cliCatalog.ts`）： | 欄位 | 類型 | 說明 | | ----------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------ | | `category` | `"code" \| "agent"` | 工具顯示於哪個頁面 | | `vendor` | `string` | 工具來源（「Anthropic」、「OSS (P. Gauthier)」） | | `acpSpawnable` | `boolean` | 是否也可作為 ACP Agent 使用（顯示徽章） | | `baseUrlSupport` | `"full" \| "partial" \| "none"` | 自訂端點支援等級。`"none"` = MITM 待辦清單 | | `configType` | `"env" \| "custom" \| "guide" \| "custom-builder" \| "mitm"` | 設定機制 | | `id`, `name`, `color`, `description`, `docsUrl` | 標準 | 核心顯示欄位 | 具有 `baseUrlSupport: "none"` 的項目**不會顯示**於儀表板頁面中——它們已登錄至計畫 11 的 MITM 待辦清單（請參閱 `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`）。 ### 能力層級（已收錄 × 可偵測 × 可設定 × 可啟動） 並非每個已收錄的工具都可偵測、可設定或可啟動。每個層級都有一個 宣告來源，並由差異測試確保它們保持一致： | 層級 | 含義 | 宣告位置 | | ---------- | ------------------------------------------------------------ | --------------------------------------------------------------- | | **已收錄** | 顯示於儀表板目錄中（名稱、提供者、文件、設定類型） | `src/shared/constants/cliTools.ts`（`CLI_TOOLS`） | | **可偵測** | 二進位檔／設定偵測、健康狀態檢查、設定路徑 | `src/shared/services/cliRuntime.ts`（`CLI_TOOLS` 執行階段目錄） | | **可設定** | 受 `omniroute configure ` 支援（已有設定程序） | `bin/cli/cli-manifest.mjs`（`configure: true`） | | **可啟動** | 受 `omniroute run ` 支援（已定義環境變數／引數注入） | `bin/cli/cli-manifest.mjs`（`run: true`） | `bin/cli/cli-manifest.mjs` 是 CLI 命令介面的規範可執行資訊清單： `run`、`configure` 與 shell 自動完成產生器皆從中衍生其 目標清單、別名解析（例如 `kilocode`/`kilo-code`/`kilo_cli` → `kilo`） 以及 `--model` 旗標的連接方式。差異防護測試 `tests/unit/cli/cli-manifest-drift.test.ts` 會確認資訊清單、執行階段 目錄、UI 目錄及所有使用端介面保持同步——若僅在其中一個介面新增 目標而未同步至其他介面，測試套件便會失敗，而非讓差異悄然產生。 --- ## 1. CLI代碼目錄（28個工具） `/dashboard/cli-code`中出現的所有工具。那些帶有`baseUrlSupport: none`連接通過MITM或手動指南而不是自訂基礎URL： | ID | 姓名 | 小販 | baseUrlSupport | configType | acpSpawnable | | ------------ | --------------------- | --------------------- | -------------- | ------------ | ------------ | | 克勞德 | Claude代碼 | Anthropic | 滿的 | 環境 | 真的 | | 法典 | OpenAI Codex CLI | OpenAI | 滿的 | 風俗 | 真的 | | 零碼 | ZCode （GLM編碼計劃） | 愛 | 沒有任何 | 風俗 | 錯誤的 | | 克萊因 | Cline | OSS （前克勞德·戴夫） | 滿的 | 風俗 | 真的 | | 公斤 | 基洛程式碼 | 基洛組織 | 滿的 | 風俗 | 錯誤的 | | 袋鼠 | 袋鼠程式碼 | 袋鼠 (OSS) | 滿的 | 指導 | 錯誤的 | | 繼續 | 繼續 | 繼續.dev | 滿的 | 指導 | 錯誤的 | | 助理 | 艾德爾 | OSS （P.高蒂爾） | 滿的 | 指導 | 真的 | | 鍛造 | ForgeCode | HQ | 滿的 | 風俗 | 真的 | | 程式碼 | 程式碼 | 1傑黃 (OSS) | 滿的 | 風俗 | 錯誤的 | | 深度搜尋-tui | DeepSeek TUI | 獵人弓 (OSS) | 滿的 | 風俗 | 錯誤的 | | 碼鯨 | CodeWhale | 赫姆本 (OSS) | 滿的 | 風俗 | 錯誤的 | | 開放程式碼 | OpenCode | 異常（前 SST） | 滿的 | 指導 | 真的 | | 機器人 | 工廠機器人 | 工廠AI | 部分的 | 指導 | 錯誤的 | | 副駕駛 | GitHub Copilot CLI | GitHub/MS | 滿的 | 風俗 | 錯誤的 | | 遊標 CLI | Cursor CLI | 任何領域 | 部分的 | 指導 | 真的 | | 冶煉 | 冶煉 | 倫納德塞爾 (OSS) | 滿的 | 風俗 | 錯誤的 | | 圓周率 | Pi（pi 編碼代理） | M.澤克納（OSS） | 滿的 | 風俗 | 錯誤的 | | 格羅克構建 | Grok構建 | xAI | 滿的 | 風俗 | 錯誤的 | | 壓碎 | 壓碎 | OSS （魅力） | 滿的 | 風俗 | 錯誤的 | | 麴 | Qwen代碼 | Alibaba | 滿的 | 指導 | 真的 | | 開放克勞德 | OpenClaude | 吉特勞布（OSS） | 滿的 | 指導 | 錯誤的 | | 澤德 | Zed | Zed實業 | 滿的 | 指導 | 錯誤的 | | 游標 | Cursor | 任何領域 | 沒有任何 | 指導 | 錯誤的 | | 反重力 | Antigravity | Google | 沒有任何 | 中間人 | 錯誤的 | | 愛馬仕 | 赫爾墨斯 | 諾斯研究 | 沒有任何 | 指導 | 錯誤的 | | 基羅 | Kiro AI | Amazon | 沒有任何 | 中間人 | 錯誤的 | | 風俗 | 客製化CLI | — | 滿的 | 客製化建造者 | 錯誤的 | 使用`baseUrlSupport: "partial"`的工具會在儀表闆卡中顯示徽章「⚠ Base URL parcial」。 --- ## CLI代理目錄（11個工具） `/dashboard/cli-agents`中出現的自主代理： | ID | 姓名 | 小販 | 基本Url支持 | acp可生成 | | ---------- | ------------ | -------------------- | ----------- | --------- | | 愛馬仕代理 | 愛馬仕代理 | 諾斯研究 | 滿的 | 錯誤的 | | 開爪 | OpenClaw | OSS （P.斯坦伯格） | 滿的 | 真的 | | 鵝 | 鵝 | 區塊 / Linux基金會 | 滿的 | 真的 | | 口譯員 | 打開解釋器 | OSS | 滿的 | 真的 | | 經 | Warp AI | Warp公司 | 部分的 | 真的 | | 代理平台 | 特工套牌 | 阿什什戈普拉尼 (OSS) | 滿的 | 錯誤的 | | 奧普 | 喔我的圓周率 | OSS | 滿的 | 真的 | | 萊塔 | 萊塔CLI | 萊塔 | 滿的 | 錯誤的 | | 主要代理人 | 首席經紀人 | 原始智力 (OSS) | 滿的 | 錯誤的 | | 5次潛水 | 5次潛水 | OSS (5dive-ai) | 滿的 | 錯誤的 | | 原因碼 | WhyCodes | 為什麼選擇公司 | 滿的 | 錯誤的 | --- ## 3. ACP 代理（/dashboard/acp-agents） 此頁面（從 `/dashboard/agents` 重新命名）顯示 OmniRoute 可透過 stdio/ACP 通訊協定作為後端執行引擎**啟動**的 CLI。此目錄在 `src/lib/acp/registry.ts` 中獨立維護，與 `CLI_TOOLS` **並不**相同。 --- ## 4. MITM 待辦清單（未顯示於儀表板中） 下列 CLI 原生不支援自訂基礎 URL，因此**不會列於** CLI Code 或 CLI Agents 頁面中。它們是計畫 11 中進行 MITM 攔截的候選項目： | CLI | 原因 | | ------------------- | -------------------------------------------- | | windsurf | BYOK 僅限於特定 Claude 模型以及企業 URL/權杖 | | amp | 封閉式生態系統（Sourcegraph） | | amazon-q / kiro-cli | AWS SSO 驗證，不支援自訂 URL | | cowork | Anthropic Desktop，無法設定端點 | 如需完整交叉參照，請參閱 `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`。 --- ## 5. 批次偵測 API 所有工具的偵測均透過單一端點彙整： **`GET /api/cli-tools/all-statuses`** - 驗證：`requireCliToolsAuth(request)`（與其他 `/api/cli-tools/` 路由相同） - 傳回：`Record`（類型：`src/shared/types/cliBatchStatus.ts`） - 策略：對所有工具使用 `Promise.all`，每個工具的逾時時間為 5 秒 - 快取：以設定檔 `mtime` 為索引的記憶體內 LRU。當 mtime 變更時，快取即失效。伺服器重新啟動時重設。 每個工具的回應結構： ```ts interface ToolBatchStatus { detection: { installed: boolean; runnable: boolean; version?: string; command?: string; commandPath?: string; reason?: string; }; config: { status: "configured" | "not_configured" | "not_installed" | "unknown" | "other"; endpoint?: string | null; lastConfiguredAt?: string | null; }; error?: string; // 已清理，不含堆疊追蹤 } ``` --- ## 6. 新工具的設定處理程序 `configType: "custom"`的新工具有專門的設定API路由： | 路線 | 工具 | | ------------------------------------------- | ------------------------------------------------------------- | | `POST /api/cli-tools/forge-settings` | ForgeCode (.forge.toml) | | `POST /api/cli-tools/jcode-settings` | jcode（--base-url標誌） | | `POST /api/cli-tools/deepseek-tui-settings` | DeepSeek TUI （OPENAI_BASE_URL，遺留） | | `POST /api/cli-tools/codewhale-settings` | CodeWhale （OPENAI_BASE_URL、主要+遺留`~/.deepseek`同步） | | `POST /api/cli-tools/smelt-settings` | 冶煉 | | `POST /api/cli-tools/pi-settings` | Pi編碼劑（`~/.pi/agent/models.json`， `providers.omniroute`） | | `POST /api/cli-tools/grok-build-settings` | Grok建構 (~grok/config.toml, `[model.omniroute]`) | | `POST /api/cli-tools/qwen-settings` | Qwen代碼（`~/.qwen/settings.json` +專用`.env`鑰） | 所有路由都使用`sanitizeErrorMessage()`進行錯誤回應（硬規則 #12）。 --- ## 7. 儀表板頁面架構 ### CLI Code（`/dashboard/cli-code`） - `src/app/(dashboard)/dashboard/cli-code/page.tsx` — 伺服器元件 - `src/app/(dashboard)/dashboard/cli-code/CliCodePageClient.tsx` — 用戶端網格 - `src/app/(dashboard)/dashboard/cli-code/[id]/page.tsx` — 工具詳細資訊頁面 - `src/app/(dashboard)/dashboard/cli-code/components/` — 12 個專用工具卡片 + `ToolDetailClient.tsx` ### CLI 代理（`/dashboard/cli-agents`） - `src/app/(dashboard)/dashboard/cli-agents/page.tsx` — 伺服器元件 - `src/app/(dashboard)/dashboard/cli-agents/CliAgentsPageClient.tsx` — 用戶端網格 - `src/app/(dashboard)/dashboard/cli-agents/[id]/page.tsx` — 重複使用 `ToolDetailClient` ### ACP 代理（`/dashboard/acp-agents`） - `src/app/(dashboard)/dashboard/acp-agents/page.tsx` — 伺服器元件（從 `agents/` 移入） ### 共用 UI 元件（`src/shared/components/cli/`） | 檔案 | 用途 | | ----------------------- | ---------------------------------- | | `CliToolCard.tsx` | 智慧狀態卡片（偵測 + 設定 + 端點） | | `CliConceptCard.tsx` | 各頁面的概念說明卡片 | | `CliComparisonCard.tsx` | 跨 CLI 類型的三欄比較 | | `BaseUrlSelect.tsx` | 端點下拉式選單（本機／雲端／自訂） | | `ApiKeySelect.tsx` | API 金鑰選擇器 | | `ManualConfigModal.tsx` | 可複製的設定片段互動視窗 | ### 共用 Hook（`src/shared/hooks/cli/`） | 檔案 | 用途 | | ------------------------- | ---------------------------------------------------------- | | `useToolBatchStatuses.ts` | 擷取 `/api/cli-tools/all-statuses`，管理載入／重新整理狀態 | --- ## 8. i18n 計畫 14 F9 中新增了以下命名空間： | 命名空間 | 用途 | | ----------- | ------------------------------------------------------ | | `cliCommon` | 共用字串（卡片標籤、概念／比較文字、詳細資料頁面標籤） | | `cliCode` | CLI Code 頁面的字串 | | `cliAgents` | CLI Agents 頁面的字串 | | `acpAgents` | ACP Agents 頁面的字串 | 已提供完整的 PT-BR 與 EN 翻譯。其他 39 個語系會透過 `src/i18n/request.ts` 中的命名空間層級合併，自動回退至 EN。 --- ## 9. 快速啟動 ### 步驟 1 —取得OmniRoute API密鑰 1. 打開`/dashboard/api-manager` →**建立API密鑰** 2. 為其命名（例如`cli-tools`）並選擇所有權限 3. 複製密鑰—下面的每個CLI都需要它 > 您的金鑰如下所示： `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx` --- ### 步驟2 —安裝CLI工具 所有基於 npm 的工具都需要Node.js 22.22.2 +或 24.x： ```bash # Claude Code (Anthropic) npm install -g @anthropic-ai/claude-code # OpenAI Codex npm install -g @openai/codex # OpenCode npm install -g opencode-ai # Cline npm install -g cline # KiloCode npm install -g kilocode # Qwen Code npm install -g @qwen-code/qwen-code # Google Gemini CLI (launchable via `omniroute run gemini` → /v1beta surface) npm install -g @google/gemini-cli # Aider pip install aider-chat # Smelt cargo install smelt # Rust-based # Pi coding agent npm install -g --ignore-scripts @earendil-works/pi-coding-agent # jcode # see https://github.com/1jehuang/jcode for install ``` --- ### 步驟 3 —透過儀表板配置 1. 前往`http://localhost:20128/dashboard/cli-code` 2. 在網格中找到您的工具 3. 點擊卡片開啟工具詳情頁面 4. 選擇您的API鑰和基礎URL 5. 點選**應用程式配置**或複製手動設定片段 --- ### 步驟4 —設定全域環境變數 ```bash # OmniRoute Universal Endpoint export OPENAI_BASE_URL="http://localhost:20128/v1" export OPENAI_API_KEY="sk-your-omniroute-key" export ANTHROPIC_BASE_URL="http://localhost:20128" export ANTHROPIC_AUTH_TOKEN="sk-your-omniroute-key" # Gemini CLI reads GOOGLE_GEMINI_BASE_URL at the ROOT (its SDK appends /v1beta/... itself) export GOOGLE_GEMINI_BASE_URL="http://localhost:20128" export GEMINI_API_KEY="sk-your-omniroute-key" ``` > 對於一個**遠端伺服器**將`localhost:20128`替換為伺服器IP或網域，例如`http://:20128`。 --- ### 步驟 4 —設定每個工具 #### Claude代碼 ```bash # Create ~/.claude/settings.json: mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF { "env": { "ANTHROPIC_BASE_URL": "http://localhost:20128", "ANTHROPIC_AUTH_TOKEN": "sk-your-omniroute-key" } } EOF ``` Claude程式碼使用統一的Anthropic網關根。不要在此處附加`/v1` 。 **測試：** `claude "say hello"` --- #### OpenAI Codex 現代Codex (v0.137 +) 僅讀取`~/.codex/config.toml` —舊`config.yaml`屬於舊版 npm CLI並被默默忽略。 API密鑰保留在`OMNIROUTE_API_KEY`環境變數 (`env_key`) 中，而不是在檔案中： ```bash mkdir -p ~/.codex && cat > ~/.codex/config.toml << EOF model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute" base_url = "http://localhost:20128/v1" env_key = "OMNIROUTE_API_KEY" requires_openai_auth = false EOF export OMNIROUTE_API_KEY="sk-your-omniroute-key" ``` 完整參考（設定檔、 `wire_api`、上下文視窗）： [CODEX-CLI-CONFIGURATION.md](../guides/CODEX-CLI-CONFIGURATION.md) 。 **測試：** `codex "what is 2+2?"` --- #### OpenCode ```bash mkdir -p ~/.config/opencode && cat > ~/.config/opencode/opencode.json << EOF { "\$schema": "https://opencode.ai/config.json", "provider": { "omniroute": { "npm": "@ai-sdk/openai-compatible", "name": "OmniRoute", "options": { "baseURL": "http://localhost:20128/v1", "apiKey": "sk-your-omniroute-key" }, "models": { "claude-sonnet-4-5": { "name": "claude-sonnet-4-5" }, "claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" }, "gemini-3-flash": { "name": "gemini-3-flash" } } } } } EOF ``` **測試：** `opencode` > 使用`opencode run "your prompt" --model omniroute/claude-sonnet-4-5-thinking --variant high`發送思維變體。 --- #### Pi編碼劑 使用`npm install -g --ignore-scripts @earendil-works/pi-coding-agent`安裝官方 Pi Coding Agent 套件。 Pi 從`~/.pi/agent/models.json`讀取自訂提供者；設定`PI_CODING_AGENT_DIR`移動整個代理目錄。儀表板遵循該覆蓋。 Pi 不會從自訂端點發現模型，因此OmniRoute使用 Pi 的`openai-completions` API和OmniRoute OpenAI 相容`/v1`端點在`models[]`中寫入所選模型。 在**CLI工具→ Pi** ，選擇端點、 API鑰和模型，查看提供者預覽，然後套用。預覽是一個提供者片段：在手動配置 Pi 時將`providers.omniroute`合併到現有的`models.json`中，以便其他提供者和設定保持不變。 ```json { "$schema": "https://pi.dev/schemas/models.schema.json", "providers": { "omniroute": { "baseUrl": "http://localhost:20128/v1", "api": "openai-completions", "apiKey": "sk-your-omniroute-key", "omnirouteManaged": true, "models": [{ "id": "auto/best-coding", "name": "auto/best-coding" }] } } } ``` 當您開啟`/model`時，Pi 會重新載入`models.json` 。使用您選擇的提供者 ID 和模型 ID 測試配置的路由： ```bash pi --provider omniroute --model auto/best-coding --print "Reply with a short greeting." ``` 參考資料： [Pi 模型和自訂提供者](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)、 [Pi 環境變數](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/environment-variables.md)、 [Pi 安裝說明](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md)。 --- #### Cline （CLI或VS代碼） **CLI模式：** ```bash mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF { "apiProvider": "openai", "openAiBaseUrl": "http://localhost:20128/v1", "openAiApiKey": "sk-your-omniroute-key" } EOF ``` **VS代碼模式：** Cline擴充設定→ API提供者： `OpenAI Compatible` →基礎URL： `http://localhost:20128/v1` 或使用OmniRoute儀表板→**CLI工具→ Cline →應用程式配置**。 --- #### KiloCode （CLI或VS代碼） **CLI模式：** ```bash kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key ``` **VS代碼設定：** ```json { "kilo-code.openAiBaseUrl": "http://localhost:20128/v1", "kilo-code.apiKey": "sk-your-omniroute-key" } ``` 或使用OmniRoute儀表板→**CLI工具→ KiloCode →應用程式配置**。 --- #### 繼續（VS代碼擴充） 編輯`~/.continue/config.yaml`： ```yaml models: - name: OmniRoute provider: openai model: auto apiBase: http://localhost:20128/v1 apiKey: sk-your-omniroute-key default: true ``` 編輯完成後重啟VS程式碼。 --- #### VS代碼內部人士 (`chatLanguageModels.json`) 當VS Code Insiders 配置為自訂端點模型並且您希望OmniRoute在沒有自訂標頭欄位的情況下工作時，請使用此選項。 **推薦地點：** - Linux: `~/.config/Code - Insiders/User/chatLanguageModels.json` - Windows: `%APPDATA%/Code - Insiders/User/chatLanguageModels.json` **使用標記化OmniRoute別名的範例：** ```json [ { "vendor": "customendpoint", "id": "auto", "name": "OmniRoute Auto", "family": "gpt-4", "version": "1.0.0", "url": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/chat/completions", "modelsUrl": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/models", "requestFormat": "openai-chat-completions", "contextWindow": 256000, "maxOutputTokens": 32768, "auth": { "type": "none" } } ] ``` **筆記：** - 將`sk-your-omniroute-key`替換為OmniRoute中所建立的API鑰。 - `url`欄位應指向`/api/v1/vscode/{token}/chat/completions`。 - `modelsUrl`欄位應指向`/api/v1/vscode/{token}/models`。 - 當客戶端支援自訂標頭時，首選正常的`/v1` +承載標頭流。 - URL 嵌入令牌是一種相容性回退，可能會出現在編輯器日誌或代理程式歷史記錄中。 --- #### Kiro CLI (Amazon) ```bash # Login to your AWS/Kiro account: kiro-cli login # The CLI uses its own auth — OmniRoute is not needed as backend for Kiro CLI itself. # Use kiro-cli alongside OmniRoute for other tools. kiro-cli status ``` 對於**Kiro IDE**桌面應用程序，使用OmniRoute在`/dashboard/cli-tools → Kiro`下公開的MITM端點。 --- ## 10. 內部 OmniRoute CLI `omniroute` 二進位檔提供伺服器生命週期、設定、診斷及提供者管理等指令。進入點：`bin/omniroute.mjs`。 ```bash omniroute # 啟動伺服器（預設連接埠為 20128） omniroute setup # 互動式設定精靈 omniroute doctor # 檢查設定、資料庫、連接埠及執行環境 omniroute providers list # 已設定的提供者連線 omniroute providers test-all # 測試每個使用中的連線 omniroute reset-password # 重設管理員密碼 omniroute logs # 串流顯示請求日誌 omniroute health # 詳細健康狀態（斷路器、快取、記憶體） omniroute --version # 輸出版本 omniroute --help # 顯示所有指令 ``` ### 設定與初始化 ```bash omniroute setup # 互動式設定精靈 omniroute setup --non-interactive # CI／自動化模式（讀取環境變數與旗標） omniroute setup --password '' # 直接設定管理員密碼 omniroute setup --add-provider \ --provider openai \ --api-key '' \ --test-provider # 一次完成新增及測試提供者 ``` 非互動式設定可辨識的環境變數： | 變數 | 用途 | | ------------------- | ------------------------------------------------------------- | | `OMNIROUTE_API_KEY` | 提供者 API 金鑰（透過 Commander `.env()` 繫結至 `--api-key`） | | `DATA_DIR` | 覆寫 OmniRoute 資料目錄 | 所有其他非互動式輸入都透過旗標傳遞，而非環境變數： `--password`、`--provider`、`--provider-name`、`--provider-base-url`、`--default-model` （請參閱上方的 `omniroute setup` 選項）。 ### 診斷 ```bash omniroute doctor # 檢查設定、資料庫、連接埠、執行環境、記憶體及存活狀態 omniroute doctor --json # 機器可讀的 JSON omniroute doctor --no-liveness # 略過 HTTP 健康狀態探測 omniroute doctor --host 0.0.0.0 # 覆寫存活狀態主機 omniroute doctor --liveness-url # 覆寫完整的健康狀態端點 URL ``` doctor 會執行下列檢查：`設定`、`資料庫`、`儲存空間／加密`、 `連接埠可用性`、`Node 執行環境`、`原生二進位檔`（better-sqlite3）、 `記憶體`及`伺服器存活狀態`。若任何檢查結果為 `fail`，程式將以非零狀態碼結束。 ### 提供者管理 ```bash omniroute providers available # OmniRoute 提供者目錄 omniroute providers available --search openai # 依 ID／名稱／別名／類別篩選目錄 omniroute providers available --category api-key # 依類別篩選（api-key、oauth、free、...） omniroute providers available --json # 機器可讀的 JSON omniroute providers list # 已設定的提供者連線 omniroute providers list --json omniroute providers test # 測試一個已設定的連線 omniroute providers test-all # 測試每個使用中的連線 omniroute providers validate # 僅限本機的結構驗證 omniroute providers add --credential-env PROVIDER_KEY omniroute providers import ./providers.json --dry-run --json omniroute providers auth # 現有的 OAuth 流程 omniroute providers edit --default-model omniroute providers remove --yes ``` `providers add/import/auth/edit/remove` 採 API 優先，因此會針對 使用中的本機或遠端情境運作。憑證輸入應使用 `--credential-stdin` 或 `--credential-env`；`--dry-run --json` 僅會回報 經遮蔽處理的存在狀態／結構。`providers available` 會讀取 OmniRoute 目錄； `providers list/test/test-all/validate` 則保留其本機 SQLite 行為， 不需要啟動伺服器。 對於自訂的 OpenAI 相容或 Anthropic 相容節點，請使用 `omniroute nodes add` 傳回的節點 ID 附加憑證，指令為 `omniroute keys add "$NODE_ID" --stdin`。 這需要伺服器正在執行，且使用中的情境必須具備管理驗證。 CLI 使用 `POST /api/providers`，此端點會驗證節點，並將其端點 設定複製到連線中。若缺少節點、授權失敗或伺服器無法使用， 則會傳回錯誤，而不會建立本機備援憑證。 `nodes add --base-url` 會設定節點端點；此位址不同於 `OMNIROUTE_BASE_URL` 中的伺服器位址。若要處理 OpenAPI 檔案，請使用 `omniroute openapi dump --format json --out ./openapi.json`；全域 `--output` 用於選擇 CLI 顯示格式，而不是目的地檔名。 ### 復原與重設 ```bash omniroute reset-password # 重設管理員密碼（亦可使用：omniroute-reset-password） omniroute reset-encrypted-columns # 顯示警告，並對加密憑證重設進行試執行 omniroute reset-encrypted-columns --force # 實際將 SQLite 中的加密憑證設為 null ``` ### 憑證匯出（⚠ 請謹慎處理） ```bash omniroute auth export # 顯示警告與確認關卡——不存取資料庫 omniroute auth export --force # 將所有連線的已解密憑證以 JSON 格式匯出至 stdout omniroute auth export --force --id # 僅匯出相符的連線 omniroute auth export --force --format env # 輸出 OMNIROUTE__= 格式的行 omniroute auth export --force --out creds.json # 寫入檔案（以 0600 權限建立） ``` `auth export` **僅限本機使用**（直接讀取 SQLite，不經由 HTTP 路由），且會刻意列印／寫入 **明文** `apiKey`/`accessToken`/`refreshToken`/`idToken` 值——這是功能，而不是 錯誤。若未指定 `--force`，則不會從資料庫讀取任何內容，也不會解密任何內容。在輸出任何明文之前， 一律會先將警告橫幅列印至 stderr。必須設定 `STORAGE_ENCRYPTION_KEY`。 若某個欄位解密失敗（例如金鑰過期或密文損毀），則會回報為 `DecryptFailed: true`，而不會中止整個匯出作業或洩漏底層錯誤。 ### 其他子命令 除非另有註明，否則這些命令皆假設 OmniRoute 伺服器正在執行： ```bash omniroute status # 完整的執行階段狀態 omniroute logs # 串流請求日誌（--json、--search、--follow） omniroute config list # 顯示已設定的 CLI 工具 omniroute provider list # 列出可用的提供者（providers list 的別名） omniroute provider add # 將 OmniRoute 註冊為工具的提供者 omniroute keys add | list | remove # 管理 API 金鑰 omniroute models [provider] # 列出模型（--json、--search） omniroute combo list | switch | create | delete omniroute backup # 建立設定與資料庫的快照 omniroute restore # 從先前的快照還原 omniroute health # 詳細的健康狀態（斷路器、快取、記憶體） omniroute quota # 提供者配額用量 omniroute cache # 快取狀態 omniroute cache clear # 清除語意與簽章快取 omniroute mcp status | restart # MCP 伺服器狀態／重新啟動 omniroute a2a status | card # A2A 伺服器狀態／代理程式卡片 omniroute tunnel list | create | stop # 管理通道（cloudflare/tailscale/ngrok） omniroute env show | get | set # 檢視／設定環境變數（暫時） omniroute test # 提供者連線能力冒煙測試 omniroute update # 檢查更新 omniroute completion # 產生 shell 自動補全 ``` ### 常用旗標 | 旗標 | 說明 | | ------------------- | ----------------------------------------------- | | `--no-open` | 啟動時不自動開啟瀏覽器 | | `--port ` | 覆寫 API 連接埠（預設為 20128） | | `--mcp` | 透過 stdio 以 MCP 伺服器模式執行（供 IDE 使用） | | `--non-interactive` | CI 模式（不顯示提示；從環境變數／旗標讀取） | | `--json` | 機器可讀的 JSON 輸出（doctor、providers 等） | | `--help`, `-h` | 顯示命令專屬說明 | | `--version`, `-v` | 列印已安裝的版本 | --- ## 可用的 API 端點 | 端點 | 說明 | 用途 | | -------------------------- | ---------------------------- | ------------------------- | | `/v1/chat/completions` | 標準聊天（所有提供者） | 所有現代工具 | | `/v1/responses` | Responses API（OpenAI 格式） | Codex、代理式工作流程 | | `/v1/completions` | 舊版文字補全 | 使用 `prompt:` 的舊版工具 | | `/v1/embeddings` | 文字嵌入 | RAG、搜尋 | | `/v1/images/generations` | 圖像生成 | GPT-Image、Flux 等 | | `/v1/audio/speech` | 文字轉語音 | ElevenLabs、OpenAI TTS | | `/v1/audio/transcriptions` | 語音轉文字 | Deepgram、AssemblyAI | 以下為可直接貼上的範例，其中包含已權杖化的 OmniRoute URL： ```txt 權杖範例：sk-a3ab3c080beaee3a-69f4a4-070d71af 標準 OpenAI 基底位址：http://localhost:20128/v1 VS Code 模型：http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/models VS Code 聊天：http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/chat/completions VS Code responses：http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/responses Ollama 標籤：http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/tags Ollama 聊天：http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/chat ``` --- ## 疑難排解 | 錯誤 | 原因 | 修正方式 | | -------------------------------- | --------------------- | -------------------------------------------- | | `Connection refused` | OmniRoute 未執行 | `omniroute serve` | | `401 Unauthorized` | API 金鑰錯誤 | 在 `/dashboard/api-manager` 中檢查 | | `No combo configured` | 沒有作用中的路由組合 | 在 `/dashboard/combos` 中設定 | | CLI 顯示「not installed」 | 二進位檔不在 PATH 中 | 檢查 `which ` | | 安裝後儀表板顯示「not detected」 | 快取已過期 | 在儀表板中按一下「⟳ Refresh detection」 | | 舊連結 `/dashboard/cli-tools` | v3.8.6 之前版本的書籤 | 自動重新導向至 `/dashboard/cli-code` (308) | | 舊連結 `/dashboard/agents` | v3.8.6 之前版本的書籤 | 自動重新導向至 `/dashboard/acp-agents` (308) | ## 使用 OmniRoute CLI 管理推論金鑰政策 使用已驗證的管理環境（請參閱[遠端模式](../guides/REMOTE-MODE.md)）， 依照現有推論金鑰的 ID 檢視或更新該金鑰： ```bash omniroute --output json keys policy show KEY_ID omniroute keys policy set KEY_ID --unrestricted omniroute --output json keys policy show KEY_ID ``` `--unrestricted` 是 `--model-access-mode all` 的別名。此更新會清除 模型允許清單。它會保留範圍、連線規則、封鎖的模型、速率限制 及成本限制，因此這些其他控制措施仍可能拒絕請求。明確指定 `--allowed-models ""` 也會選取 `all`；將其與 `--model-access-mode restricted` 結合使用，可維持受限制的金鑰且不允許任何模型。 除非明確指定，否則以逗號分隔的非空白清單會選取 `restricted`。 在傳送請求之前，互相矛盾的 `all` 與非空白允許清單組合會遭到拒絕。 `--rate-limit 30` 會設定每分鐘的請求數，並保留其他時間 區間的規則。`--max-cost 5` 會啟用每日美元上限，而不變更每週上限； `--max-cost 0` 會移除每日上限，並保留現有的用量限制切換狀態 及每週上限。省略的政策欄位會維持不變。速率變更會先讀取 目前的政策；請避免同時編輯同一金鑰的速率限制陣列。 政策命令會使用已驗證的 `GET`/`PATCH /api/keys/{id}`，並遵循作用中的 環境及全域 `--api-key` 選項。JSON 輸出僅包含政策欄位， 不包含儲存的金鑰或其遮罩表示形式。僅限推論的認證 無法授權管理變更。遇到 401/403 時，必須檢查管理 認證與環境；這並不表示本機 CLI 權杖或 salt 發生故障。 如需瞭解獨立的本機驗證合約，請參閱 [CLI 權杖](../security/CLI_TOKEN.md)。