clipal：极简 CLI LLM API 反向代理服务最新版

clipal 是一个轻量级、无状态的 LLM API 反向代理服务，专为命令行 AI 工具（如 Claude Code、Codex CLI、Gemini CLI）设计。它不提供 UI、不存储历史、不修改请求格式——只做一件事：智能路由你的 API 调用到可用的供应商。

通过简洁的 YAML 配置，clipal 实现多供应商管理、自动故障转移与优先级调度，让你的 CLI 工具在 API 不稳定或配额耗尽时依然保持可用。

核心理念

• 极简：无数据库、无 Web 界面、无日志持久化，仅一个可执行文件；
• 透明：不转换消息格式，完全依赖上游 API 的兼容性（如 OpenAI 兼容端点）；
• 便携：单一二进制，支持 macOS、Linux、Windows（含 ARM64）；
• 可靠：自动跳过失效供应商，并在恢复后自动重试。

功能特性

🔌 多供应商 + 优先级调度

• 为每个客户端类型（Claude / Codex / Gemini）维护独立的供应商列表；
• 按 priority 字段排序，优先使用高优先级 API；
• 支持任意 OpenAI 兼容端点（如 Ollama、Cloudflare Workers AI、自托管 vLLM 等）。

🔄 自动故障转移

• 当前供应商返回网络错误、鉴权失败或配额耗尽（HTTP 4xx/5xx）时；
• 自动切换至列表中下一个可用供应商；
• 无缝重试，对 CLI 工具完全透明。

⏸️ 智能临时禁用

• 若某供应商连续失败，clipal 会将其 临时停用（deactivate）；
• 根据配置的 reactivate_after（如 5m），在指定时间后自动恢复尝试；
• 避免反复请求已知失效端点，提升响应速度。

📄 配置热加载

• 修改 claude-code.yaml、codex.yaml 或 gemini.yaml 后；
• clipal 自动重新加载配置并验证 API 可用性；
• 无需重启服务，变更即时生效。

📊 结构化日志

• 支持 DEBUG / INFO / WARN / ERROR 四级日志；
• 默认输出 INFO，可通过 --log-level 调整；
• 便于调试路由行为与故障原因。

🗂️ 三套独立配置

为避免配置冲突，clipal 按客户端分离配置：

每个文件可单独管理其供应商列表与策略。

典型使用场景

• 你同时使用多个 LLM 供应商（如 Anthropic + 自托管 Llama 3 + OpenRouter）；
• 某个 API 突然限流，CLI 工具卡住——clipal 自动切到备用；
• 在本地开发时，优先调用本地 Ollama，失败时回退到云端 API；
• 希望 CLI 工具“永远有响应”，而不手动修改 API 密钥或端点。