自动配置劫持
Clipal 精准合并 ~/.claude/settings.json 及标准配置文件，为 Claude Code 和 AI CLI
提供自动化的反向代理，全程零环境变量污染。
为你的 Coding Agents 打造的稳定 API 基础设施
一键接管 CLI 配置，轻松驾驭
Claude Code, Codex & Gemini API。
原生支持 OpenRouter、new-api、OAuth 账号及任意三方提供商。自动注入 ~/.claude/settings.json 与各类标准配置，普通 Claude/Codex OAuth 客户端默认使用 Agent SDK 兼容包装，并支持通过 Antigravity Google OAuth 调用 Gemini 文本和图片模型。
原生支持 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 端点和 OAuth 上游 (OpenRouter, new-api, sub2api, Claude OAuth, Codex OAuth, Antigravity Google OAuth)。
核心支持协议
CLI 工具与 AI 应用
核心优势
高性能 LLM 代理核心功能。专为开发者工作流打造。
三个让 Clipal 成为唯一值得运行的 LLM 代理的理由。
三方 API 的稳压器
彻底解决 OpenRouter、new-api 等中转 API 频繁限流痛点。Clipal 支持多级 Token 池，毫秒级感知 429 报错并自动轮换多 Key，甚至在节点宕机时将流量无损转移至备用路线。
npm 优先的极速本地网关
不同于臃肿的 Python 依赖 (如 LiteLLM) 或是复杂的 Docker
Compose 编排，Clipal 推荐通过 npm install -g clipal 安装，并以 Go 编译的高性能网关在
macOS、Linux 和 Windows 上运行。需要独立二进制时，也可以从 GitHub Releases 下载。
技术幕后
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
Claude OAuth 使用 Agent SDK 兼容 envelope，并由 Clipal 生成传输 header。
OpenAI / 多中转节点
Codex OAuth 将 Responses 请求归一化为 Agent SDK 兼容上游形态。
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 严格的协议头校验。OAuth 请求使用轻量 Agent SDK envelope，并由 Clipal 处理必要传输字段。
配额管理
Codex & Gemini: 配额/中转首选
自动轮询多密钥以突破 RPS 频率检测。Pro 配额耗尽时秒切 Flash 镜像模型，确保编码工作流永不中断。
快速开始
几分钟内启动 Clipal
选择你偏好的安装方式。
复制以下提示词，粘贴到 Claude Code、Aider 或任何 AI 编程助手中 — 它将为你完成全部安装：
PROMPT
请帮我安装并启动 Clipal。项目地址：https://github.com/PAIArtCom/Clipal 请优先使用推荐的 npm 安装方式：npm install -g clipal。如果当前环境不能使用 npm，再回退到 GitHub Releases 的独立二进制。随后启动 Clipal，并确认我能成功打开 Web UI。需要时请使用以下官方链接： - npm 包：https://www.npmjs.com/package/clipal - GitHub 仓库：https://github.com/PAIArtCom/Clipal - Releases 备用下载：https://github.com/PAIArtCom/Clipal/releases - 快速入门：https://github.com/PAIArtCom/Clipal/blob/main/docs/zh/getting-started.md - Web UI 指南：https://github.com/PAIArtCom/Clipal/blob/main/docs/zh/web-ui.md 完成后，请引导我通过 Web UI 启用 CLI 接管并添加我的第一个提供商。
1
2
启动 Clipal
clipal service install
clipal service start
✓ 成功启动 http://127.0.0.1:3333
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 无效。
获取 Clipal
永久免费与开源。
通过 npm 安装
100% 本地运行，API Key 永不离开你的机器。MIT 开源协议。
加入社区
与其他开发者交流配置心得、获取帮助、探讨新提供商接入。
扫码加入微信交流群