ccs

Claude Code API 代理商切换工具 — 一条命令在不同 provider 之间安全切换。

功能

• 交互式选择 — 运行 ccs 显示列表，选号切换
• 命令行直接切换 — ccs use <name> / ccs back
• 预切换验证 — 验证 API 可达，识别模型名错误，不通则拒绝切换
• 选择性替换 — 只更新 provider 相关 key，保留其他 env
• 切换历史 — ccs history / ccs back 一键回退
• 健康诊断 — ccs doctor 一键自检
• 配置迁移 — ccs export / ccs import 便于多机同步与分享
• 内置预设 — ccs add --preset openrouter|anthropic|deepseek|kimi 开箱即用
• 模型名映射 — model_map 自动转换 Claude 名 → provider 名

安装

cd /path/to/ccs
uv venv && uv pip install -e .

依赖：Python 3.10+、click、rich

命令速查

命令	用途
ccs	交互式选择 provider 并切换
ccs add	交互式添加 provider（支持 flag 与 --preset；末尾可选 verify）
ccs use <name>	直接切换到指定 provider
ccs back	切回上一个 provider
ccs current	显示当前 active provider
ccs history	显示最近的切换历史
ccs list	列出所有 provider（★ 标记当前）
ccs show <name>	查看 provider 详情（含 model_map）
ccs remove <name>	删除 provider
ccs verify [name]	检测 API 可达性（不切换）
ccs doctor [--probe]	健康诊断；--probe 同时检测 active 的连通性
ccs export [--with-secrets] [-o file]	导出 providers.json（默认脱敏）
ccs import <file or -> [--force] [--allow-redacted]	从文件或 stdin 导入
ccs map add|list|remove ...	管理模型名映射

快速开始

# 添加官方 Anthropic API（预设）
ccs add --preset anthropic --name official --api-key sk-ant-xxx

# 添加 OpenRouter（预设，含 model_map）
ccs add --preset openrouter --name or --token sk-or-xxx

# 全 flag 非交互式添加（CI/CD 友好）
ccs add --non-interactive --name custom \
        --base-url https://api.your-provider.com/anthropic \
        --token tp-xxx \
        --model "your-model-name[1m]"

# 添加并立即验证（验证失败仍会保存，不阻塞写入）
ccs add --non-interactive --verify --name myprovider \
        --api-key your-api-key --base-url https://api.example.com

# 查看 / 切换
ccs list
ccs use custom
ccs back

# 配置导出/导入
ccs export --with-secrets -o backup.json
ccs import backup.json

配置

文件	说明
~/.claude/settings.json	Claude Code 配置（切换目标，含 _ccs 元数据）
~/.config/ccs/providers.json	Provider 配置存储（权限 0600）

settings.json 中会写入一个 _ccs 元数据块，记录 active / previous / 历史，用于 ccs current / back / history：

{
  "env": { "ANTHROPIC_AUTH_TOKEN": "...", "ANTHROPIC_BASE_URL": "..." },
  "_ccs": {
    "active": "mimo",
    "previous": "official",
    "switched_at": "2026-05-22T01:23:45Z",
    "history": [{ "name": "official", "switched_at": "..." }, ...]
  }
}

providers.json 格式

{
  "providers": [
    {
      "name": "custom",
      "env": {
        "ANTHROPIC_AUTH_TOKEN": "tp-xxx",
        "ANTHROPIC_BASE_URL": "https://api.your-provider.com/anthropic",
        "ANTHROPIC_MODEL": "your-model-name[1m]"
      },
      "model_map": {
        "claude-opus-4-6": "your-model-name[1m]",
        "claude-sonnet-4-6": "your-sonnet-name[1m]"
      }
    }
  ]
}

model_map 是可选字段：切换时所有 MODEL key 的值如果在 model_map 中有映射，会被替换为目标值。详细说明见 设计文档。

关于 [1m] 后缀

某些 provider 在模型名末尾加 [1m] 表示启用 1M tokens 的扩展上下文窗口。这是 provider 端的私有约定，写在模型名里即可，无需额外配置。

切换流程

选择 provider → 验证 API 连通性 → 备份 settings.json → 替换 provider key → 记录 _ccs.active → 显示 diff
                       ↓
            失败 → 拒绝切换，配置不变

⚠ 切换后需要重启 Claude Code 才能生效。Claude Code 在进程启动时一次性读取 ~/.claude/settings.json 中的 env，运行中不会重新读取。ccs use 完成后 命令行会提示重启。已经在运行的会话仍然使用切换前的 provider。

跨 provider 后 resume 旧会话

claude --resume <session> 会把整个 conversation history 原样回放给当前 provider。 Anthropic API 协议不区分"消息是谁生成的"，但消息里带的特殊结构需要新 provider 支持。当切换发生在不同 provider 之间时，ccs use 会显示跨 provider 警告。

会话内容	风险
纯文本对话	🟢 通常 OK
Tool use / tool_result 历史	🟡 两边 tool schema 不一致时可能 400
Extended thinking blocks（<thinking>）	🔴 deepseek/kimi 多数不支持，会报错
图片 / PDF / 多模态	🔴 provider 多模态支持差异大
Prompt caching marker（cache_control）	🟡 部分 provider 不接受
上下文超出新 provider 上限	🔴 直接 context_length_exceeded

实践建议：

• 保守做法：跨 provider 切换后新开会话，不要 resume
• 同家族切换：同一家 provider 内部切换（base_url 主机相同）通常安全
• 必须 resume：纯文本短对话基本 OK；含 tool / 图片 / thinking 的强烈建议新开

Verify 错误识别

verify 不只看 HTTP 状态码：4xx 响应会进一步解析 body 中的 error.type / error.message：

错误类型	处理
401 / authentication_error / invalid_api_key	失败：认证问题
403 / permission_error	失败：权限问题
not_found_error / model_not_found / "model not found"	失败：模型名错误
其他 4xx（如 invalid_request_error 因 max_tokens=1）	可达：endpoint 通了

这样模型名拼错不会被静默通过。

ℹ 关于额度：verify 会向 provider 的 /v1/messages 发一次 max_tokens=1 的真实请求。 大多数 provider 对这种极短请求几乎不计费，但严格按 token 计费的服务可能扣减少量额度 （通常 < 1 cent）。需要完全免计费可以加 --no-verify 跳过。

环境变量

变量	说明	默认值
CCS_SETTINGS_FILE	settings.json 路径	~/.claude/settings.json
CCS_CONFIG_DIR	配置目录	~/.config/ccs

退出码

码	说明
0	成功
1	用户错误（无效输入、provider 不存在）
2	API 验证失败（配置未变更）
3	配置错误（写入失败，已回滚）

License

GPL-3.0 — see LICENSE for full text.