Skip to content

README.zh.md

Latest commit

 

History

History
238 lines (164 loc) · 13.9 KB

README.zh.md

File metadata and controls

238 lines (164 loc) · 13.9 KB

English | 中文

clovapi — 按 CLI 管理 API profiles

官网： https://clovapi.com — 支持的 Agent · 配置教程 · Agent Skill

小型跨平台 CLI：保存按 CLI 维度的上游 API 配置（Base URL、密钥、api_style、模型），并写入你使用的各类编程 Agent 二进制对应的配置——Claude Code、Codex、OpenCode、OpenClaw、Hermes、Kimi Code CLI 等。

流程：clovapi add --name …（保存并探测连通性）→ clovapi switch --cli … 或交互式 clovapi switch（每次下发到单一 CLI 配置）。

Claude Code 的环境变量写法与社区 cc-switch / ccswitch 一致；详见下文 与社区 cc-switch / ccswitch 的对比。

命令

命令 说明
clovapi list 展示已保存的 profiles 与各 CLI 的 active 绑定（别名：ls）
clovapi profiles 为脚本与桌面 UI 加载/保存/测试 profiles（见下文）
clovapi add --name NAME 保存一个上游 profile（CLI 在 switch 时再选择）；持久化前先测连通（--name 必填，别名：set、new）
clovapi remove <name> 删除一条已保存 profile（别名：rm、delete）
clovapi switch [--cli KIND] [VENDOR/MODEL] 将 provider/model 绑定应用到某一 CLI（--provider + --model、--vendor + --model，或交互选择）。别名 use。脚本可加 --json
clovapi auth Claude/Codex 订阅 OAuth（status、login、logout；均可 --json）
clovapi proxy 运行并查看内置本地代理（start、stop、status、health、config、logs 等；status / health 支持 --json）
clovapi reset 清空所有 profile 与绑定记录（--yes / -y 跳过确认）

clovapi profiles（JSON API）

子命令与桌面端 / Electron 调用一致。加 --json 输出结构化 JSON（save 从 stdin 读 JSON）：

子命令 说明
load --json 读取规范化后的 profiles.json（vendors、active、proxy 绑定）
save --json 合并 stdin 载荷并写盘
test --json 经本地代理探测 provider/model（--provider、--model，可选 --cli、--port）
list-models --vendor NAME --json 拉取并合并某一 vendor 的模型列表
usage --vendor NAME --json 查询某一 API vendor 的额度/余额
catalog --json 固定 provider 注册表与 model adapter 目录

旧版 clovapi desktop profiles|vendor|auth … 仍可用；新脚本请优先用上述顶层命令。

示例：

clovapi profiles load --json
clovapi profiles save --json < payload.json
clovapi switch --cli opencode --provider custom-api --model my-model --json
clovapi auth status --json
clovapi proxy status --json

构建

cd core
go build -o clovapi ./cmd

包管理器安装

npm

npm i -g @clovapi/cli
clovapi --help

npm 包是推荐的 shell 命令入口。它会把轻量 clovapi launcher 安装到 PATH，并把真实 core 二进制统一放在 ~/.config/clovapi/bin/clovapi，与 clovapi update 和桌面端使用同一位置。

在仓库根目录：

npm run core:build   # 输出 core/clovapi（Windows 上为 clovapi.exe）
npm run core:test

测试

cd core && go test ./...

配置文件位置

  • Unix（macOS/Linux）：$XDG_CONFIG_HOME/clovapi 或 ~/.config/clovapi
  • Windows：%APPDATA%\clovapi

状态文件：profiles.json（权限 0600）。内含 profiles（vendor 与模型列表）、active（每个 CLI 的 provider_id + model_id），以及 proxy（本地监听 host/port）。

clovapi switch 始终只针对单一 CLI。交互流程：选 CLI → 选 vendor → 选 model。脚本示例：

clovapi switch --cli codex --provider codex --model gpt-5.5 --json
clovapi switch --cli codex --vendor "Codex Subscription" --model gpt-5.5
clovapi switch --cli codex "Codex Subscription/gpt-5.5"
clovapi switch --cli codex   # 无参数时复用 active 绑定，或进入交互选择

下发行为摘要

  • claude-code + claude：写入 ~/.claude/settings.json，设置 env.ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_BASE_URL（与 ccswitch 同款）。从 env 中移除 ANTHROPIC_API_KEY，避免 Claude Code 提示「Auth conflict: Both a token and an API key are set」。
  • codex + openai-responses：合并 ~/.codex/config.toml——配置 [model_providers.clovapi]（base_url、wire_api、experimental_bearer_token）、model_provider = "clovapi"，以及顶层 model（来自已保存的绑定）。
  • opencode + 任意支持的风格：与 OpenCode 配置加载说明 一致——全局文件位于 ~/.config/opencode/（Windows：优先 %AppData%\opencode\，其次 ~/.config\opencode\），按 config.json → opencode.json → opencode.jsonc 合并（后者覆盖冲突项）。clovapi 写入与 OpenCode 自身相同的全局文件（上游中的 globalConfigFile）：在 opencode.jsonc、opencode.json、config.json 中取首个已存在的，若都不存在则新建 opencode.jsonc，从而使新设置优先于旧版 config.json。Anthropic 形态网关：provider.anthropic.options + model anthropic/…。OpenAI 形态：provider.clovapi + npm、options、models，顶层 model clovapi/…。Gemini 中继：provider.gemini + model gemini/…。项目级 opencode.json / .opencode/ 仍会覆盖全局；若「切换无效」，请检查仓库内项目配置或 OPENCODE_CONFIG / OPENCODE_CONFIG_CONTENT。可选环境变量 CLOVAPI_SWITCHER_OPENCODE_DIR 可强制指定全局配置目录（测试中使用）。
  • openclaw + 任意支持的风格：合并 ~/.openclaw/openclaw.json（可用 OPENCLAW_CONFIG_PATH 覆盖）：models.mode=merge，models.providers.clovapi（baseUrl、apiKey、api = anthropic-messages | openai-completions | openai-responses | google-generative-ai），agents.defaults.model.primary clovapi/<model-id>。合并要求文件为合法 JSON（JSON5 注释无法被解析）。
  • hermes + 任意支持的风格：合并 ~/.hermes/config.yaml——model.default、model.provider（anthropic | clovapi | gemini）、model.base_url、model.api_key。
  • kimi-code + 任意支持的风格：合并 ~/.kimi/config.toml——default_model、[providers.clovapi]（type 由 api-style 映射）、[models.<id>] 中 provider = "clovapi"、model 与必填的 max_context_size（默认 200000，若条目已存在则保留原值）。

cc-switch / ccswitch 只处理 Claude Code 的 JSON；OpenCode / OpenClaw / Hermes / Kimi 为 clovapi 独有适配（与各上游文档对齐）。

在 Windows 上会正确展开用户目录与 AppData 路径。

与社区 cc-switch / ccswitch（「cc-switcher」）对比

Claude Code 路径： clovapi 与 huangdijia/ccswitch / HoBeedzc/cc-switch 使用相同的凭据结构：env.ANTHROPIC_AUTH_TOKEN（+ ANTHROPIC_BASE_URL），不含 ANTHROPIC_API_KEY（避免 Claude Code「认证冲突」）。settings.json 为合并写入（保留其他顶层键）；model 与 env.ANTHROPIC_*_MODEL 来自本次绑定。

扩展： clovapi 将同一套上游设置同步到 Codex、OpenCode、OpenClaw、Hermes、Kimi Code CLI——超出常见 npm cc-switch 的范围。

命令别名（沿用 cc-switch / ccswitch 肌肉记忆）

clovapi 别名 类似
list ls cc-switch list、ccswitch list
profiles （子命令组，不是 list 的别名） 桌面/脚本的 profiles.json JSON API
add set、new 一次性保存上游绑定
switch [--cli …] use … 将单个绑定推入单一工具
remove NAME rm、delete 删除单条 profile

说明： 旧文档曾把 clovapi profiles 当作 list 的别名；现 profiles 为独立子命令组（load、save 等）。查看人类可读表格请用 clovapi list 或 clovapi ls。

状态存放位置

工具 配置存放
cc-switch ~/.claude/profiles/*.json + .current
ccswitch ~/.ccswitch/ccs.json
clovapi Windows：%APPDATA%\clovapi\profiles.json；Unix：~/.config/clovapi/profiles.json——profiles 数组 + active 映射

本模块内 go test ./... 可通过；真实上游调用需在本地配置密钥。

相关链接

Agent 配置切换

系统提示与工具变更追踪

  • cchistory — 提取并对比不同 Claude Code 版本的 system prompt 与 tool 定义
  • claude-code-changelog — 社区维护的 Claude Code prompt / feature flag 演进追踪

评测与 Agent 生态

上游模型与套餐

发布流水线

打 vX.Y.Z tag 触发 .github/workflows/release-switcher.yml（core CLI 与 npm）：

产物 构建 R2 路径（公开域名 downloads.clovapi.com）
CLI 压缩包 GoReleaser /clovapi/vX.Y.Z/*、/clovapi/latest.txt
install.sh 同上 /install.sh、/clovapi/install.sh

桌面客户端由 .github/workflows/release-desktop.yml 独立发布：main 上 electron/** 有变更时构建（见 electron/README.md）。

产物 构建 R2 路径
macOS Desktop electron-builder (macOS runner) /desktop/latest/clovapi-desktop-darwin-universal.dmg
Windows Desktop electron-builder (Windows runner) /desktop/latest/clovapi-desktop-windows-x64.exe

GitHub Actions Secrets（Cloudflare R2）：

  • R2_ACCOUNT_ID、R2_ACCESS_KEY_ID、R2_SECRET_ACCESS_KEY、R2_BUCKET
  • R2_ARTIFACT_PREFIX（可选，默认 clovapi）

R2 bucket 需绑定自定义域名（如 downloads.clovapi.com）并开启 Public Access。

本地手动上传（需配置上述 env）：

export R2_ACCOUNT_ID=... R2_ACCESS_KEY_ID=... R2_SECRET_ACCESS_KEY=... R2_BUCKET=...
./scripts/r2-publish.sh cli --tag v0.1.12 --dist core/dist
./scripts/r2-publish.sh install-sh --file landing/public/install.sh
./scripts/r2-publish.sh desktop --tag v0.1.12 --file electron/dist/clovapi-desktop-darwin-universal.dmg --name clovapi-desktop-darwin-universal.dmg

其它：npm i -g @clovapi/cli、clovapi update、install.sh 均优先从 R2 下载；GitHub Releases 为 fallback。

DeepSeek + Claude Code（Anthropic 兼容）

使用 API 形态 claude，Base URL 以 DeepSeek 文档为准：

  • Base URL： https://api.deepseek.com/anthropic
  • API key： DeepSeek 密钥（建议用环境变量 DEEPSEEK_API_KEY 或 CLOVAPI_API_KEY，勿提交密钥）
  • 模型（必填）： 例如 deepseek-v4-flash 或 deepseek-v4-pro，通过 --model 指定（省略时会提示输入）

连通性检测（clovapi add 保存时）：对 POST …/v1/messages 携带模型（Anthropic 头）。若 Messages 路径返回 404，add 会改用 POST https://<同一主机>/v1/chat/completions，Bearer 为同一密钥（统一网关场景）。

clovapi add --api-style claude \
  --name deepseek-claude \
  --base-url https://api.deepseek.com/anthropic \
  --model deepseek-v4-flash \
  --api-key "$DEEPSEEK_API_KEY"

clovapi switch --cli claude-code

DeepSeek + Codex（OpenAI 兼容）

使用 codex + openai-responses（旧写法 openai 仍接受并会存为 responses）。DeepSeek 的 OpenAI Base URL 为 https://api.deepseek.com（列举模型用 GET /v1/models）。Codex 的 model_providers.*.base_url 请带上 /v1 后缀以匹配 OpenAI 风格路由：

export DEEPSEEK_API_KEY="..."   # 勿把密钥粘贴到聊天记录

clovapi add --api-style openai-responses \
  --name deepseek-codex \
  --base-url https://api.deepseek.com/v1 \
  --model deepseek-v4-pro \
  --api-key "$DEEPSEEK_API_KEY"

clovapi switch --cli codex

switch 会写入 ~/.codex/config.toml，提供 clovapi 提供商，根据绑定设置 model，并将 model_provider 指向该块。

仍出现 401 或认证冲突？

在 go build 之后，再次运行 clovapi switch --cli claude-code（前提是已执行 clovapi add）。打开 %USERPROFILE%\.claude\settings.json：应能看到 env.ANTHROPIC_AUTH_TOKEN（以及 ANTHROPIC_BASE_URL），且不应出现 env.ANTHROPIC_API_KEY。若在系统/用户环境变量里全局设置过凭据（setx / 系统属性），请移除重复项。