CCS

接入原理

本頁使用 CCS 官方支援的 OpenAI-Compatible Routing：

Claude Code
    ↓ Anthropic Messages
CCS 本機代理（127.0.0.1，連接埠由 CCS 自動分配）
    ↓ OpenAI Chat Completions
https://www.coffeerouter.ai/v1/chat/completions

因此 CoffeeRouter 的 API Base URL 必須填寫：

https://www.coffeerouter.ai/v1

不要填寫完整的 /chat/completions 請求位址，也不要重複加入 /v1。CCS 會自動啟動本機代理、完成協定轉換，並把請求轉送到 CoffeeRouter。

準備工作

開始前請確認：

• 已安裝 Node.js 18 或更新版本。
• 已安裝 Claude Code，並且可以在終端機執行 claude --version。
• 已登入 CoffeeRouter 控制台，並在「權杖管理」頁面建立可用權杖。
• 已記下目前權杖允許使用的正確模型 ID；模型名稱必須與 CoffeeRouter 中顯示的內容完全一致。

1. 安裝 CCS

在 PowerShell、Windows Terminal 或 macOS/Linux 終端機中執行：

npm install -g @kaitranntt/ccs@latest

安裝完成後檢查版本：

ccs --version

2. 開啟 API Profiles

執行：

ccs config

CCS 會在瀏覽器中開啟本機設定面板。在左側選擇 API Profiles，然後點擊 New 或 Create Profile。

3. 建立 CoffeeRouter Profile

在 Basic Information 中填寫：

設定項	填寫內容
Profile Name	coffeerouter
API Base URL	https://www.coffeerouter.ai/v1
API Key	CoffeeRouter 權杖，例如 sk-your-api-key
Default Target	Claude Code

Profile Name 會成為啟動指令的一部分，建議只使用小寫英文字母、數字和連字號。

4. 設定模型對應

切換到 Model Configuration，填寫目前 CoffeeRouter 權杖允許使用的模型 ID：

設定項	說明
Default Model	預設使用的模型，例如 your-model-id
Opus Model	Claude Code 請求 Opus 等級時使用的模型
Sonnet Model	Claude Code 請求 Sonnet 等級時使用的模型
Haiku Model	Claude Code 請求 Haiku 等級時使用的模型

如果只準備使用一個模型，可以把四項都設定為相同的模型 ID。需要不同模型時，請確認每個 ID 都在目前權杖的模型權限範圍內。

只有在 CoffeeRouter 上游帳戶和所選模型確實支援長上下文時，才啟用 CCS 的 [1m] 選項；該選項不能繞過上游額度或權限限制。

完成後儲存 Profile。

5. 確認 OpenAI 相容類型

這是 CoffeeRouter 接入 CCS 時必須檢查的一步。開啟剛建立的 coffeerouter Profile，在環境變數或 Additional Variables 中確認存在：

CCS_DROID_PROVIDER=generic-chat-completion-api

這個設定會告訴 CCS：CoffeeRouter 使用 OpenAI Chat Completions 相容介面，需要由 CCS 的本機代理轉換 Claude Code 請求後再轉送。

如果目前 CCS 介面沒有顯示該欄位，請編輯 Profile 設定檔：

• Windows：%USERPROFILE%\.ccs\coffeerouter.settings.json
• macOS/Linux：~/.ccs/coffeerouter.settings.json

確認關鍵內容類似以下範例：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://www.coffeerouter.ai/v1",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-api-key",
    "ANTHROPIC_MODEL": "your-model-id",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "your-model-id",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "your-model-id",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "your-model-id",
    "CCS_DROID_PROVIDER": "generic-chat-completion-api"
  }
}

6. 啟動 Claude Code

在需要工作的專案目錄中執行：

ccs coffeerouter

CCS 會自動啟動該 Profile 對應的本機 OpenAI 相容代理，並開啟 Claude Code。終端機通常會顯示類似以下提示：

Using local OpenAI-compatible proxy for "coffeerouter" on port ...

可以在另一個終端機檢查代理狀態：

ccs proxy status coffeerouter

進入 Claude Code 後傳送一則簡單訊息，確認模型可以正常回應。

選用：使用終端機精靈建立 Profile

不使用網頁設定面板時，也可以執行：

ccs api create coffeerouter

依照提示依序填寫：

1. API Base URL：https://www.coffeerouter.ai/v1
2. API Key：CoffeeRouter 權杖
3. Default Model：目前權杖允許的模型 ID
4. Opus / Sonnet / Haiku 對應：依需求填寫
5. Default Target：選擇 Claude Code，不要設為 Factory Droid

精靈完成後，仍需依照上一節檢查 CCS_DROID_PROVIDER。不建議把真實權杖直接寫入帶有 --api-key 參數的指令，因為它可能保留在終端機歷史記錄、程序資訊或錄影中。

設定檔與安全

CCS 的主要設定儲存在 ~/.ccs/。其中 Profile 設定檔會包含完整 CoffeeRouter 權杖。

• 不要分享 *.settings.json、設定匯出檔、終端機截圖或偵錯日誌。
• 不要把 ~/.ccs/ 提交到 Git。
• 建議為 CCS 建立獨立 CoffeeRouter 權杖，以便個別設定模型、額度、IP 白名單和撤銷策略。
• 如果權杖外洩，請立即在 CoffeeRouter 控制台停用或刪除，並更新 CCS Profile。
• CCS 本機代理預設繫結到 127.0.0.1。除非已設定可靠的驗證、防火牆和可信網路，否則不要暴露到區域網路或公網。

常見問題

官方資料

• CCS 官方網站
• CCS 官方文件
• CCS GitHub 儲存庫
• CCS OpenAI-Compatible Provider Routing
• CCS npm 軟體包