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 软件包