新手最小路徑教程：一次接上Claude Code/Codex/Gemini/OpenCode等六大CLI
整理版優先睇
CC Switch 幫你打通國內模型同六大 CLI 工具嘅 API 協議，唔使再手改配置
呢篇文章係由一個成日玩 AI CLI 工具嘅開發者寫嘅。佢發現用 OpenCode 接 DeepSeek 好地地，但一轉去 Codex 就報錯，唔係 Key 或者模型有問題，而係 API 協議唔夾。國內模型（DeepSeek、Kimi、MiniMax 等）都係用 Chat Completions API，但 Codex 新版綁死咗 Responses API，兩套協議根本唔互通。
作者介紹咗 CC Switch 呢個開源工具，可以同時管理 OpenCode、Codex、Claude Code、Gemini、OpenClaw、Hermes 六大主流 CLI 嘅配置，仲做到協議轉換——將 Codex 嘅 Responses API 請求轉成 Chat Completions，等國內模型都用到。作者仲分享咗 Windows 安裝嘅權限問題解決方法，同埋四步跑通 OpenCode 同 Codex 嘅實際操作步驟。
整體結論係：當你要同時管理多個工具、多套協議、多個模型嘅時候，手改配置嘅成本會愈來愈高，CC Switch 可以幫你統一收埋呢啲嘢，令你更專注用 AI 做嘢，而唔係同配置鬥智鬥力。
- CC Switch 可將 Codex 嘅 Responses API 請求轉譯成 Chat Completions，令國內模型可以直接用，唔使改 Key 或模型
- 一次過管理 OpenCode、Codex、Claude Code、Gemini 等六款 CLI 工具嘅配置，唔使逐個手改唔同格式嘅檔案
- Windows 安裝失敗多數係權限問題，用管理員身份執行安裝程式或直接叫大模型幫你裝就得
- 四步跑通：新增 Provider → 開本地路由 → 配模型映射 → 重啟 CLI 測試，先求跑通再求最優
- 多工具管理先係 CC Switch 嘅價值，單一工具時手改配置冇問題，但多工具時邊際成本會暴增
CC Switch GitHub 項目
CC Switch 嘅原始碼同安裝說明，支援六大 CLI 工具嘅配置管理同協議轉換
點解國內模型喺 Codex 用唔到？因為 API 協議唔夾
你喺 OpenCode 配好咗 DeepSeek，跑得好順。一轉去 Codex 就報錯，下意識以為係模型或者 Key 有問題，但其實唔關事。問題係 API 協議唔同：OpenCode 用 Chat Completions API（/v1/chat/completions），而 Codex 新版 CLI 硬綁咗 Responses API（/v1/responses）。國內模型（DeepSeek、Kimi、MiniMax、硅基流動）一律只支援 Chat Completions，兩套協議根本唔互通。
CC Switch 係咩？可以接邊啲 CLI？
CC Switch 係一個配置管理 + 協議轉換工具。佢唔會自己叫模型，淨係負責幫你寫好配置，同埋喺需要嘅時候做協議翻譯。支援呢六大主流 CLI 工具：
- 1 OpenCode — Chat Completions
- 2 Codex — Responses API
- 3 Claude Code — Chat Completions
- 4 Gemini (CLI) — Chat Completions
- 5 OpenClaw — Chat Completions
- 6 Hermes — Chat Completions
佢嘅核心能力包括：協議轉換——Codex 出 Responses API 請求，CC Switch 本地路由會譯返做 Chat Completions 畀國內模型，結果再譯返做 Codex 睇得明嘅格式，全程你唔使理；模型映射——國內模型名好亂（deepseek-v4-flash、kimi-k2.5、glm-4.7），Codex 唔識佢哋，CC Switch 畀你喺表單入面直接填對應關係；配置統一管理——OpenCode 用 opencode.json，Codex 用 auth.json + config.toml，格式唔同，CC Switch 一次過接管，你喺一個界面操作就搞掂；多 provider 切換——同時管多個 Key、模型同工具，一鍵轉換。
Windows 裝唔到？先試管理員權限
喺 Windows 裝 cc-switch 報錯，先唔好懷疑軟件本身。多數情況係權限問題。解決方法：右鍵安裝程式揀「以管理員身份執行」，呢招通常得。如果仲係唔得，直接叫大模型幫你裝，佢會自動請求管理員權限。作者就係咁樣搞掂，唔使煩。
四步跑通 OpenCode 同 Codex
- 1 喺 CC Switch 新增一個 OpenCode provider：揀 Custom 或對應預設，填 API Key 同 base URL，拉模型或手動填 ID，儲存。然後開啓 cc switch，勾選你用緊嘅 CLI（例如 OpenCode），開啓本地路由。最後喺 OpenCode 發句最簡單嘅測試，保證 Key 同 endpoint 通咗先。
- 2 新增 Codex provider：填入同一個 API Key 同 base URL。如果你上游唔係標準 Responses API（絕大多數國內廠商都唔係），就要勾選「Needs Local Routing」。
- 3 配模型映射：如果模型名同 Codex 預期嘅唔一致，喺映射表入面填返實際名同展示名就搞掂。
- 4 儲存，重啟 Codex（佢嘅配置係啟動時 load 嘅），發一句「hello」睇下正常返。如果唔通，跟呢個順序排查：Key 正確？endpoint 係 API 地址？本地路由有冇開？模型映射齊唔齊？先求跑通，唔好追求最優配置。
多工具管理，先係 CC Switch 嘅真正價值
CC Switch 解決嘅唔係「點樣填 API Key」，而係「點樣將 OpenCode 同 Codex 呢兩套唔同脾氣嘅系統，收埋到一個統一、可切換、可排錯嘅接入流程裏面」。當你淨係管一個工具嘅時候，手改配置冇問題；但當你開始同時管多個 provider、多套協議、多個模型嘅時候，手改配置嘅邊際成本會愈嚟愈高。CC Switch 就係喺呢個節點上變得值得用。
你喺OpenCode 裏面 set 好咗 DeepSeek，運行得好正常。一轉去 Codex，就報錯喇。
下意識以為係模型有問題，或者 Key 打錯。反複檢查，冇錯。
呢個唔係模型嘅問題，係 API 協議嘅問題。
國內所有模型——DeepSeek、Kimi、MiniMax、硅基流動——佢哋對外暴露嘅接口都係 Chat Completions 格式。Codex 新版 CLI 硬綁嘅係 Responses API。
呢兩套協議根本唔互通，所以你個模型喺 OpenCode 裏面好哋哋，轉去 Codex 就廢咗。
點樣解決？CC Switch，一個工具同時支援 OpenCode、Codex、Claude Code、Gemini、OpenClaw、Hermes 六大主流 CLI 嘅配置管理 + 協議轉換。你唔使手改任何設定檔，喺一個界面入面就可以搞掂呢件事。
你嘅國內模型，喺Codex裏面根本行唔到
OpenCode 同 Codex 食嘅唔係同一種「語言」。
OpenCode 行嘅係 Chat Completions API（/v1/chat/completions）。國內幾乎所有模型廠商都只暴露呢一種接口。生態成熟、無狀態、結構簡單，接入門檻低。
Codex 新版 CLI 硬綁定嘅係 Responses API（/v1/responses）。呢個係面向智能體場景設計嘅新協議，有狀態、多模態、原生工具調用，Codex 嘅代碼生成同多輪推理能力就依賴呢個協議。
換句話講：國內模型講嘅係「方言」，Codex 只聽得明「普通話」。
兩種協議本來就係俾唔同情境設計嘅，撈唔埋唔係邊個嘅錯。
CC Switch 係乜嘢，駁到邊啲 CLI？
CC Switch 係一個配置管理 + 協議轉換工具。佢唔做模型調用，只負責將你嘅配置寫到正確位置，並喺需要時做協議翻譯。
佢支援嘅六大主流 CLI 工具：
CC Switch 核心能力：
協議轉換。 Codex 發出 Responses API 格式嘅請求，CC Switch 本地路由將佢翻譯成 Chat Completions 格式，發俾國內模型；模型返回結果之後，再翻譯返 Codex 接受到嘅格式。全程對你透明。
模型映射。 國內模型命名千奇百怪——deepseek-v4-flash、kimi-k2.5、glm-4.7，Codex 唔認識呢啲名。CC Switch 俾你喺表單入面直接維護映射關係，唔使手改 toml。
配置統一管理。 OpenCode 睇 opencode.json，Codex 睇 auth.json + config.toml，兩套格式完全唔同。CC Switch 同時接管呢兩套配置，你喺一個界面操作，佢自動寫到各自正確嘅位置。
多 provider 切換。 同時管理多個 API Key、多個模型、多個工具，一鍵切換，唔使每次重新配置。
Windows 上裝唔到？先試管理員運行
喺 Windows 上裝 cc-switch 報錯，唔好咁急懷疑軟件本身。
大多數安裝失敗係權限問題，同軟件本身冇關係。
解決方法：
右鍵安裝程式 選擇「以管理員身份執行」 重新安裝
呢招可以解決大部分「安裝到一半卡住」嘅問題。仲係唔得嘅話，直接掉俾大模型等佢嚟安裝，然後就會請求管理員權限安裝。
我部電腦安裝，右鍵安裝程式，就冇見到cc-switch嘅管理員權限菜單，懶得諗咁多，直接叫大模型安裝除錯，一切搞掂。
四步，由零開始行通 OpenCode 同 Codex
第一步：先喺 CC Switch 入面駁 OpenCode
新增一個 OpenCode provider，揀 Custom 或對應預設，填 API Key 同 base URL，自動拉模型或手動填模型 ID，儲存。
-開啓cc switch，剔選你用緊嘅cli，例如我用opencode比較多；
-跟住就係開啓路由，佢嘅功能就係用本地路由接管Claude、codex、Gemini其中一個，例如我只係想俾Claude行本地路由，可以保持codex、Gemini 關閉。
-可以自定義加入供應商，揀適合嘅接口格式，一系列填寫完成後儲存
-返去cli就可以用啦，例如opencode，呢度特別講明，cc switch嘅開啓狀態下，先至保障接入嘅cli行嘅係cc switch嘅配置。
然後喺 OpenCode 入面發一句最簡單嘅問話，睇嚇可唔可以正常返回。呢一步只驗證一件事：Key 同 endpoint 本身通唔通。
第二步：喺 CC Switch 入面新增 Codex provider
填入同一個 API Key 同 base URL。如果你嘅上游唔係標準 Responses API——國內絕大多數廠商都唔係——剔選「Needs Local Routing」。
第三步：配模型映射
如果模型名同 Codex 預期嘅命名習慣唔一致，喺 CC Switch 嘅映射表入面填入實際模型名同展示名。
第四步：儲存，重啓 Codex，發一個最簡單請求
Codex 嘅配置喺啓動時加載，切換完必須重啓終端。發一句 hello，睇嚇返回是否正常。
如果唔通，排查順序：Key 是否正確 → endpoint 係 API 地址定網頁地址 → 本地路由是否真係啓動咗 → 模型映射是否完整。
先追求行得通，唔追求最優配置。
一套穩定可用嘅配置，永遠比一套概念上更高級但周圍報錯嘅配置更有價值。
多工具管理，先係 CC Switch 嘅用武之地
CC Switch 解決嘅唔係「點樣填 API Key」，而係「點樣將 OpenCode 同 Codex 呢兩套唔同脾氣嘅系統，收攏到一個統一、可切換、可排錯嘅接入流程入面」。
當你只係管一個工具嘅時候，手改配置冇乜問題。但當你開始同時管多個 provider、多套協議、多個模型嘅時候，手改配置嘅邊際成本會越來越高。CC Switch 就係喺呢個節點上變得值得。
項目地址：
https://github.com/farion1231/cc-switch
你在OpenCode 裏配好了DeepSeek，跑得好好的。切到 Codex，報錯了。
下意識以為是模型有問題，或者 Key 寫錯。反覆檢查，沒錯。
這不是模型的問題，是 API 協議的問題。
國內所有模型——DeepSeek、Kimi、MiniMax、硅基流動——它們對外暴露的接口都是 Chat Completions 格式。Codex 新版 CLI 硬綁的卻是 Responses API。
這兩套協議根本不互通，所以你的模型在 OpenCode 裏好好的，換到 Codex 就廢。
怎麼解決？CC Switch，一個工具同時支持 OpenCode、Codex、Claude Code、Gemini、OpenClaw、Hermes 六大主流 CLI 的配置管理 + 協議轉換。你不用手改任何配置文件，在一個界面裏就能把這件事跑通。
你的國內模型，在Codex里根本跑不起來
OpenCode 和 Codex 吃的不是同一種"語言"。
OpenCode 走的是 Chat Completions API（/v1/chat/completions）。國內幾乎所有模型廠商都只暴露這一種接口。生態成熟、無狀態、結構簡單，接入門檻低。
Codex 新版 CLI 硬綁定的是 Responses API（/v1/responses）。這是面向智能體場景設計的新協議，有狀態、多模態、原生工具調用，Codex 的代碼生成和多輪推理能力就依賴這個協議。
換句話說：國內模型說的是"方言"，Codex 只聽得懂"普通話"。
兩種協議本來就是給不同場景設計的，混不起來不是誰的錯。
CC Switch是什麼，能接哪些CLI？
CC Switch 是一個配置管理 + 協議轉換工具。它不做模型調用，只負責把你的配置寫到正確位置，並在需要時做協議翻譯。
它支持的六大主流 CLI 工具：
CC Switch 核心能力：
協議轉換。 Codex 發出 Responses API 格式的請求，CC Switch 本地路由把它翻譯成 Chat Completions 格式，發給國內模型；模型返回結果後，再翻譯回 Codex 能接受的格式。全程對你透明。
模型映射。 國內模型命名千奇百怪——deepseek-v4-flash、kimi-k2.5、glm-4.7，Codex 不認識這些名字。CC Switch 讓你在表單裏直接維護映射關係，不用手改 toml。
配置統一管理。 OpenCode 看 opencode.json，Codex 看 auth.json + config.toml，兩套格式完全不同。CC Switch 同時接管這兩套配置，你在一個界面操作，它自動寫到各自正確的位置。
多 provider 切換。 同時管多個 API Key、多個模型、多個工具，一鍵切換，不用每次重新配置。
Windows 上裝不上？先試管理員運行
在 Windows 上裝 cc-switch 報錯，先別急着懷疑軟件本身。
大多數安裝失敗是權限問題，跟軟件本身沒關係。
解決方式：
右鍵安裝程序 選擇"以管理員身份運行" 重新安裝
這一招能解決大部分"安裝到一半卡住"的問題。還是不行的話，直接丟給大模型讓它來安裝，然後就會請求管理員權限安裝。
我的電腦安裝，右鍵安裝程序，就沒有看到cc-switch的管理員權限菜單，懶得費那個腦子，直接讓大模型安裝調試，一切搞定。
四步，從零跑通 OpenCode 和 Codex
第一步：先在 CC Switch 裏接 OpenCode
新增一個 OpenCode provider，選 Custom 或對應預設，填 API Key 和 base URL，自動拉模型或手動填模型 ID，保存。
-開啓cc switch，勾選你所使用的cli，比如我使用opencode比較多；
-接下來就是開啓路由，它的功能就是使用本地路由接管Claude、codex、Gemini其中一個，比如我只想讓Claude走本地路由，可以保持codex、Gemini 關閉。
-可以自定義添加供應商，選擇合適的接口格式，一系列填寫完成後保存
-回到cli就可以使用了，比如opencode，這裏特別說明一下，cc switch的開啓狀態下，才能保障接入的cli走的是cc switch的配置。
然後在 OpenCode 裏發一句最簡單的問話，看能不能正常返回。這一步只驗證一件事：Key 和 endpoint 本身通不通。
第二步：在 CC Switch 裏新增 Codex provider
填入同一個 API Key 和 base URL。如果你的上游不是標準 Responses API——國內絕大多數廠商都不是——勾選"Needs Local Routing"。
第三步：配模型映射
如果模型名和 Codex 預期的命名習慣不一致，在 CC Switch 的映射表裏填入實際模型名和展示名。
第四步：保存，重啓 Codex，發一個最簡單請求
Codex 的配置在啓動時加載，切換完必須重啓終端。發一句 hello，看返回是否正常。
如果不通，排查順序：Key 是否正確 → endpoint 是 API 地址還是網頁地址 → 本地路由是否真的啓動了 → 模型映射是否完整。
先追求跑通，不追求最優配置。
一套穩定可用的配置，永遠比一套概念上更高級但到處報錯的配置更有價值。
多工具管理，才是CC Switch 的用武之地
CC Switch 解決的不是"怎麼填 API Key"，而是"怎麼把 OpenCode 和 Codex 這兩套不同脾氣的系統，收攏到一個統一、可切換、可排錯的接入流程裏"。
當你只管一個工具的時候，手改配置沒什麼問題。但當你開始同時管多個 provider、多套協議、多個模型的時候，手改配置的邊際成本會越來越高。CC Switch 就是在這個節點上變得值得。
項目地址：
https://github.com/farion1231/cc-switch