自动配置劫持
Clipal 精准合并 ~/.claude/settings.json 及标准配置文件，为 Claude Code 和 AI CLI
提供自动化的反向代理，全程零环境变量污染。
为你的 Coding Agents 打造的稳定 API 基础设施
一键接管 CLI 配置，轻松驾驭
Claude Code, Codex & Gemini API。
原生支持 OpenRouter、new-api 及任意三方提供商。自动注入 ~/.claude/settings.json 与各类标准配置，通过智能密钥轮询与多级兜底，彻底解决第三方 API 在命令行环境下的 429 限流报错。
原生支持 Claude Code, Codex & Gemini
直接补丁 ~/.claude/settings.json & ~/.codex/config.toml。
Clipal 也是 Claude code, Codex, Gemini CLI, Aider, Continue ... 等 Coding Agents，
以及 Jan, Cherry Studio, Chatbox 等 AI 应用的统一代理，支持任意自定义 API 端点 (OpenRouter, new-api, sub2api)。
核心支持协议
CLI 工具与 AI 应用
核心优势
高性能 LLM 代理核心功能。专为开发者工作流打造。
三个让 Clipal 成为唯一值得运行的 LLM 代理的理由。
三方 API 的稳压器
彻底解决 OpenRouter、new-api 等中转 API 频繁限流痛点。Clipal 支持多级 Token 池，毫秒级感知 429 报错并自动轮换多 Key，甚至在节点宕机时将流量无损转移至备用路线。
零依赖的极速单体本地网关
不同于臃肿的 Python 依赖 (如 LiteLLM) 或是复杂的 Docker Compose 编排，Clipal 是完全基于 Go 开发的高并发独立二进制网关。下载即用，告别环境红字报错。
技术幕后
Clipal 架构蓝图
我们如何打造稳定性：零配置损耗、无感认证跳转、统一的 Token 调度池。
命令行 AI 助手
Claude Code / Codex / Gemini CLI. 频繁覆写的配置受到完美保护。
AI 桌面端应用
Cherry Studio / OpenClaw / Chatwise. 所有流量统一收口于一个本地稳定网关。
AST
语法树精准合并
非破坏性配置接管
不同于粗暴覆盖 settings.json，我们解析 JSON AST 仅精准注入
ANTHROPIC_BASE_URL。你的 enabledPlugins 及自定义特殊变量受到 100% 保护。
协议级防篡改网关
Socket 级 Header 清洗
告别无限次要求 /login 的噩梦。Clipal 在代理网关层直接重写 Auth 请求并强制涤除导致握手失败的混乱
Host Header，使 AWS Bedrock / Vertex AI 顺畅直连。
多密钥调度池与重试
429 智能分流与会话粘性
专为第三方 API 设计。单渠道配额耗尽或触发 429 限流？网关会在同一 Provider
池内瞬间无感切换至下一个 Key；智能会话粘性逻辑保障每次上下文路由都尽可能沿用前代环境。
多级 Provider
路由
全局层级兜底 (Failover)
不怕单点全垒崩溃。如果你的主力 Provider 彻底宕机或者所有 Key
均被耗尽，优先级路由会把整个请求安全转移至备用的、不同基座的 Provider 上。
Anthropic / Bedrock
1:1 反向模拟协议，彻底粉碎 401 拒权死循环。
OpenAI / 多中转节点
兼容所有遵循 OpenAI 标准的第三方 API 与中转节点。
Google Vertex / AI Studio
对外部频控限制视若无影，动态池平滑引流不掉线。
差异化竞争优势
为什么资深开发者选择 Clipal
不仅仅是一个代理。Clipal 是 cc-switch 和 ccNexus 用户期待已久的“精装修”基础设施。
| 核心对比指标 | cc-switch | ccNexus | Clipal |
|---|---|---|---|
| 单一二进制 (无 Docker) | ✗ (脚本) | ✓ | ✓ |
| Claude / Gemini 配置接管 | 有限支持 | ✓ | 全生态接管 |
| Codex 多密钥 Token 池 | ✗ | ✓ | 极稳密钥池 |
| 通用 Base-url 应用支持 | ✓ | ✓ | ✓ (附带观测) |
| 非破坏性配置接管 | ✗ (暴力覆盖) | ✓ | ✓ (JSON 合并) |
| 原生协议认证仿真 | 有限支持 | ✗ | ✓ (无死循环) |
| 实时流量观测 | ✗ (黑盒运行) | ✓ | ✓ (实时面板) |
针对主流工具的生态优化
深度集成
Claude Code: 协议抹平专家
告别手动 export 环境变量。Clipal 自动注入 ANTHROPIC_BASE_URL 并处理 Bedrock/Vertex 严格的协议头校验。
配额管理
Codex & Gemini: 配额/中转首选
自动轮询多密钥以突破 RPS 频率检测。Pro 配额耗尽时秒切 Flash 镜像模型，确保编码工作流永不中断。
快速开始
几分钟内启动 Clipal
选择你偏好的安装方式。
复制以下提示词，粘贴到 Claude Code、Aider 或任何 AI 编程助手中 — 它将为你完成全部安装：
PROMPT
请帮我安装并启动 Clipal。项目地址：https://github.com/lansespirit/Clipal 请检测我当前的操作系统和架构，查看项目的 Releases 和文档，并为我完成下载、安装和启动。然后确认我能成功打开 Web UI。需要时请使用以下官方链接： - Releases：https://github.com/lansespirit/Clipal/releases - 快速入门：https://github.com/lansespirit/Clipal/blob/main/docs/zh-CN/getting-started.md - Web UI 指南：https://github.com/lansespirit/Clipal/blob/main/docs/zh-CN/web-ui.md 完成后，请引导我通过 Web UI 启用 CLI 接管并添加我的第一个提供商。
1
2
加入 PATH 并启动
# macOS / Linux
chmod +x clipal-darwin-arm64
mv clipal-darwin-arm64 /usr/local/bin/clipal
clipal service install
clipal service start
✓ 成功启动 http://127.0.0.1:3333
chmod +x clipal-darwin-arm64
mv clipal-darwin-arm64 /usr/local/bin/clipal
clipal service install
clipal service start
✓ 成功启动 http://127.0.0.1:3333
3
打开 Web UI 并配置
访问 http://127.0.0.1:3333，添加 API
Key，启用 CLI 接管，管理提供商。
常见问题
关于 Clipal 的常见问题解答
Clipal 是本地工具还是云端代理？
两者都不是。Clipal 是一个独立的本地二进制文件。你的 API Key 存储在本地被加密的
config.json 中，绝不经过任何云端，保证 100% 数据安全。
我能在 Claude Code 和基于 OpenAI 的工具中配合 OpenRouter 或 new-api 使用 Clipal 吗？
当然可以。Clipal 原生支持 OpenAI 兼容协议、Anthropic Claude 以及 Google Gemini 协议。你可以将终端里的 Claude Code、基于 OpenAI 的 Codex 以及 Gemini CLI 流量，轻松转发至任意第三方提供商或本地端点。
Clipal 如何处理三方中转 API 的 429 (Too Many Requests) 限流报错？
Clipal 提供多维度的可用性保障。除了单 Provider 的多密钥轮询外，我们还支持多 Provider 并发调度与智能会话粘性。如果你的主力 OpenRouter 密钥触发限流，网关会毫秒级切换至其他密钥或备用提供商，并强制执行会话粘性逻辑，确保你的编码工作流永不中断。
在 Codex 中使用 Clipal 会影响我的聊天历史记录或会话稳定性吗？
不会，反而会更稳。针对 Codex / OpenCode，Clipal 采用标准化的
model_provider = "clipal" 配置。不同于其他频繁更换 Provider 标识（这会导致会话历史重置）的方案，Clipal 始终保持 Provider
标识一致，仅在后台无感切换 API 密钥或端点，从而完美保留你的所有上下文和历史记录。
Clipal 与 cc-switch 有什么区别？
cc-switch 主要负责多配置切换，而 Clipal 是高性能本地网关，不仅支持
settings.json 的深度注入与接管，还支持复杂的多密钥 Token 池管理和实时请求观测。
Clipal 能解决 Bedrock 的 "Invalid API Key" 报错吗？
可以。绝大多数代理在处理 Claude Code 连接 Bedrock/Vertex 时会因为 Header 校验失败。Clipal 提供原生协议仿真，从 Socket 层级修复此问题。
运行性能如何？
极度轻量。使用 Go 开发，内存占用低于 50MB，内部协议转发延迟低于 1 毫秒，远比基于 Node.js 或 Python 的代理更高效。
Clipal 如何保护我已有的配置文件？
不同于其他工具直接覆盖整个 settings.json，Clipal 采用非破坏性合并策略。我们仅更新必要的 Provider
字段，并完整保留你的 enabledPlugins 和自定义环境变量。
我厌倦了 Claude Code 的登录循环，Clipal 能解决吗？
是的。登录循环通常是由代理时 Header 处理不当引起的。Clipal 的协议仿真层确保护理所有 Header 注入，让你的会话保持稳定，无需频繁重新认证。
我如何知道代理是否真的在工作？
Clipal 提供实时观测面板。点击即可查看完整的请求流、响应时间和错误代码。如果请求失败，我们会告知是网络超时还是 API Key 无效。
