🔀 CliRelay

一个专为 AI CLI 工具设计的统一代理服务器 —— 使用您的现有订阅搭配任何 OpenAI / Gemini / Claude / Codex 兼容客户端。

English | 中文

📖 文档 · 🖥️ 管理面板 · 🐛 报告 Bug · ✨ 请求新功能

## ⚡ 什么是 CliRelay？ CliRelay 将 AI CLI 订阅、OAuth 凭证、API 密钥以及兼容的上游服务转化为一个统一的托管 API 层。它通过一个统一的端点代理 Claude Code、Gemini CLI、OpenAI Codex、Amp CLI、OpenAI 兼容客户端以及其他 AI 编码工具，并在此基础上增加了路由组、故障转移、请求日志、配额控制、模型计费、图像生成支持、API 密钥自助服务、在线更新、`/manage` 网页托管以及终端管理工作流。 ``` ┌───────────────────────┐ ┌──────────────┐ ┌────────────────────┐ │ AI Coding Tools │ │ │ │ Upstream Providers │ │ │ │ │ ──────▶ │ Google Gemini │ │ Claude Code │ ──────▶ │ CliRelay │ ──────▶ │ OpenAI / Codex │ │ Gemini CLI │ │ :8317 │ ──────▶ │ Anthropic Claude │ │ OpenAI Codex │ │ │ ──────▶ │ Qwen / iFlow │ │ Amp CLI / IDE │ │ │ ──────▶ │ Antigravity │ │ Any OAI-compatible │ └──────────────┘ │ Vertex / OpenAI │ └───────────────────────┘ │ iFlow / Qwen / │ │ Kimi / Claude │ └────────────────────┘ ``` ## ✨ 核心特性 ### 🔌 多提供商代理引擎 | 特性 | 描述 | |:--------|:------------| | 🌐 **统一端点** | 通过单个 `http://localhost:8317` 统一代理 Gemini、Claude、Codex、Qwen、iFlow、Antigravity、Vertex 兼容端点、OpenAI 兼容上游以及 Amp 集成 | | ⚖️ **智能负载均衡** | 对同一提供商的多个 API 密钥采用轮询或优先填满调度策略 | | 🧭 **分组与路径路由** | 将通道绑定至分组，限制 API 密钥仅访问允许的分组，并为不同团队或工作负载公开自定义路径命名空间 | | 🔄 **自动故障转移** | 当配额耗尽或发生错误时，自动切换到备用通道 | | 🧠 **多模态支持** | 全面支持文本 + 图像输入、图像生成路由、函数调用（工具）以及 SSE 流式响应 | | 🔗 **OpenAI 兼容** | 支持任何采用 OpenAI Chat Completions 协议的上游服务 | ### 📊 请求日志与监控 | 特性 | 描述 | |:--------|:------------| | 📝 **完整请求捕获** | 每个 API 请求都会记录到 SQLite，包含时间戳、模型、Token 数（输入/输出/推理/缓存）、延迟、状态以及源通道 | | 💬 **消息体存储** | 在压缩的 SQLite 存储中捕获完整的请求/响应消息体，并为内容和元数据设置独立的保留策略 | | 🔍 **高级查询** | 按 API 密钥、模型、状态、时间范围筛选日志，支持高效的分页查询（LIMIT/OFFSET） | | 📈 **分析聚合** | 预计算的仪表盘：每日趋势、模型分布、小时热力图、单密钥统计 | | 🏥 **健康评分引擎** | 综合成功率、延迟、活跃通道和错误模式计算实时 0–100 健康评分 | | 📡 **WebSocket 监控** | 通过 WebSocket 流式传输实时系统状态：CPU、内存、goroutines、网络 I/O、数据库大小 | | 🗄️ **No-CGO SQLite** | 使用 `modernc.org/sqlite` —— 纯 Go 实现，无 CGO 依赖，易于交叉编译 | ### 🔐 API 密钥与访问管理 | 特性 | 描述 | |:--------|:------------| | 🔑 **API 密钥 CRUD** | 通过管理 API 创建、编辑、删除 API 密钥 —— 每个密钥具有自定义名称、备注和独立的启用/禁用开关 | | 📊 **单密钥配额** | 为每个密钥设置最大 Token / 请求配额并自动执行限制 | | ⏱️ **速率限制** | 基于单个密钥的速率限制（每分钟/小时请求数） | | 👥 **团队权限** | 将 API 密钥分配给不同的用户或分组，并设定限定范围的通道访问和模型权限 | | 🔒 **密钥脱敏** | API 密钥在 UI 和日志中始终以脱敏形式（`sk-***xxx`）显示 | | 🌍 **公开查询页** | 最终用户可以通过公开的自助服务页面查询自己的使用统计和请求日志（无需登录） | ### 🔗 提供商通道管理 | 特性 | 描述 | |:--------|:------------| | 📋 **多标签页配置** | 按提供商类型管理组织好的通道：Gemini、Claude、Codex、Vertex、OpenAI 兼容、Ampcode | | 🏷️ **通道命名** | 每个通道可以拥有自定义名称、备注、代理 URL、自定义请求头以及模型别名映射 | | 🧩 **可复用代理池** | 维护出站代理条目，并在需要时将其附加到 OAuth/认证通道 | | ⏱️ **延迟追踪** | 追踪每个通道的平均延迟（`latency_ms`）并附带可视化指示器 | | 🔄 **启用/禁用** | 可单独开启/关闭通道而无需删除 | | 🚫 **模型排除** | 从通道中排除特定模型（例如，在备用密钥上屏蔽昂贵的模型） | | 🧾 **模型库同步** | 维护自定义模型，并从 OpenRouter 同步模型 ID/定价以用于配额核算 | | 📊 **通道统计** | 在每个通道卡片上显示单通道的成功/失败计数以及模型可用性 | ### 🛡️ 安全与认证 | 特性 | 描述 | |:--------|:------------| | 🔐 **OAuth 支持** | 支持 Gemini、Claude、Codex、Qwen、iFlow、Antigravity 和 Kimi 的原生 OAuth 流程，以及在支持情况下的设备/浏览器/Cookie 变体 | | 🪪 **身份指纹** | 集中管理上游身份元数据，使提供商收到一致的客户端指纹 | | 🔒 **TLS 处理** | 为上游通信提供可配置的 TLS 设置 | | 🏠 **面板隔离** | 管理面板的访问由管理员密码独立控制 | | 🛡️ **请求伪装** | 移除上游请求中的客户端识别请求头以保护隐私 | ### 🛠️ 运维体验 | 特性 | 描述 | |:--------|:------------| | 🖥️ **可视化管理面板** | 从 `/manage` 配置提供商、认证、API 密钥、模型、路由、日志、更新和系统状态 | | 🌐 **中文 / 英文界面** | 为管理面板和 Compose/TUI 内置国际化语言选择 | | 🌙 **暗黑模式** | 为长时间运维会话提供完整的暗黑主题 | | 🧬 **可视化配置编辑器** | 可视化编辑运行时配置，或在需要精确控制时检查 YAML 源码 | | 🔄 **在线更新流程** | 从面板检查版本、查看更新说明、触发更新程序边车并等待后端恢复 | | 📥 **CC Switch 导入** | 将 cc-switch 样式的配置导入到托管的模型/通道工作区中 | ### 🗄️ 数据持久化 | 特性 | 描述 | |:--------|:------------| | 💾 **SQLite 存储** | 所有使用数据、请求日志和消息体均存储在本地 SQLite 数据库中 | | 🔄 **Redis 备份** | 可选的 Redis 集成，用于定期快照和跨重启的指标保留 | | 🗃️ **可插拔认证/配置后端** | 默认使用本地文件，可选 PostgreSQL、Git 或 S3 兼容对象存储后端用于配置/认证持久化 | | 📦 **配置快照** | 以 JSON 格式导入/导出整个系统配置，用于备份和迁移 | ## 📸 管理面板预览 CliRelay 可以在 `/manage` 暴露一个内置的 Web 控制面板。服务器可以托管打包的 SPA 资源，或者从配置的面板仓库同步回退到同步的管理资产。 下面的画廊使用了最新提供的截图，涵盖了当前端到端的管理工作流。 ### 仪表盘、语言与主题 | 主页概览 | 运维概览 | | :------------ | :------------------ | | | | | 中文/英文界面 | 暗黑模式 | | :-------------------------- | :-------- | | | | ### 监控、日志与自助服务 | 监控中心 | 请求日志 | | :------------- | :----------- | | | | | 请求详情 | 日志查询系统 | | :-------------- | :--------------- | | | | | API 密钥查询 | | :------------- | | | ### 认证、身份与访问 | 统一 OAuth 管理 | 身份指纹 | | :----------------------- | :-------------------- | | | | | 团队权限 | OAuth 代理分配 | | :--------------- | :--------------------- | | | | ### 通道、路由与配置 | 多通道 API 设置 | 分组路由与自定义路径 | | :---------------------- | :----------------------------- | | | | | 可视化配置 | 上游调试透传 | | :------------ | :------------------------- | | | | | CC Switch 导入 | | :--------------- | | | ### 模型、图像生成与更新 | OpenRouter 模型同步 | 自定义模型维护 | | :-------------------- | :----------------------- | | | | | 图像生成配置 | 在线更新流程 | | :---------------------- | :----------------- | | | | | 系统信息 | | :----------------- | | | ## 🏗️ 支持的提供商 | 提供商 / 通道 | 认证方式 | 备注 | |:-------------------|:|:------| | Google Gemini | OAuth + API 密钥 | Gemini CLI / AI Studio 样式流程 | | Anthropic Claude | OAuth + API 密钥 | Claude Code 及兼容 Claude 的客户端 | | OpenAI Codex | OAuth + API 密钥 | 包括 Responses 和 WebSocket 桥接 | | Qwen | OAuth | Qwen Code 样式登录流程 | | iFlow / GLM | OAuth + Cookie | 支持 iFlow 路由及相关模型系列 | | Kimi | OAuth | 基于浏览器的登录流程 | | Antigravity | OAuth | 专用 OAuth 通道，支持模型回填 | | Vertex 兼容端点 | API 密钥 | 自定义 Base URL、请求头、别名、排除项 | | OpenAI 兼容上游 | API 密钥 | OpenRouter、Grok 兼容端点以及自定义提供商 | | Amp 集成 | 上游 API 密钥 + 映射 | 直接 Amp 上游回退或映射的本地路由 | ## 🚀 快速入门 ### 🐳 使用 Docker Compose 安装 Docker Compose 是 CliRelay 推荐的安装方式。其中包含的 `docker-compose.yml` 默认使用已发布的 `ghcr.io/kittors/clirelay:latest` 镜像，并同时启动 API 服务和更新程序边车。 ``` git clone https://github.com/kittors/CliRelay.git cd CliRelay cp config.example.yaml config.yaml docker compose up -d ``` 编辑 `config.yaml` 以添加您的 API 密钥或 OAuth 凭证，然后重启服务： ``` docker compose restart cli-proxy-api ``` 默认情况下，客户端 API 路由（`/v1`、`/v1beta`）需要 API 密钥。要在没有客户端密钥的情况下运行，请在 `config.yaml` 中设置 `allow-unauthenticated: true`（不建议在生产环境中使用）。 启动后： - API 端点：`http://localhost:8317` - Web 面板：`http://localhost:8317/manage` - 日志：`docker compose logs -f cli-proxy-api` - 重启：`docker compose restart cli-proxy-api` - 停止：`docker compose down` - TUI：`docker compose exec cli-proxy-api ./cli-proxy-api -tui` - OAuth 登录模式：`docker compose exec cli-proxy-api ./cli-proxy-api -login` 在您的 Compose 环境中设置 `CLIRELAY_LOCALE=en` 或 `CLIRELAY_LOCALE=zh` 以控制默认的 TUI 语言。 对于只允许挂载一个目录的云平台，请将 `AUTH_PATH` 设置为容器内的认证目录，例如 `/CLIProxyAPI/auths`。`CLI_PROXY_AUTH_PATH` 保留为主机端的绑定路径，而 `AUTH_PATH` 也用于在运行时覆盖 `auth-dir`。 要禁用自动更新提示，请在 `config.yaml` 中进行以下设置，或在配置页面关闭 **Automatic Update Checks**： ``` auto-update: enabled: false ``` 更新检查默认遵循稳定的 `main` Docker 镜像。要测试开发版本，请在 `config.yaml` 中设置 `channel: dev`，或在配置页面的 **Update Channel** 中选择 **Development (dev)**： ``` auto-update: channel: dev ``` ### 🗄️ 启用数据持久化 默认情况下，API 使用日志存储在 SQLite 中以确保持久性。如需额外备份： 1. 确保您有一个正在运行的 Redis 服务器。 2. 编辑 `config.yaml` 并设置 `redis.enable: true` 以及您的 Redis 地址。 CliRelay 将在每次启动时自动快照并恢复流量指标！ 对于大型部署，请在 `config.yaml` 中调整 `request-log-storage`，以控制如何保留完整的请求/响应体。默认情况下，完整的消息体会被压缩，保留 30 天，并设置约 1GB（1024MB）的上限；轻量级的请求元数据仍可在更长的周期内进行统计查询。将 `content-retention-days` 设置为 `0` 可无限期保留完整内容，将 `store-content` 设置为 `false` 可停止存储新的消息体而不删除已有的历史内容，并调整 `max-total-size-mb` 以限制消息体存储大小，从而在达到保留窗口之前清除最旧的完整消息体。 如果您需要非本地配置/认证持久化，服务器还通过基于环境变量的引导设置支持 PostgreSQL、Git 支持以及 S3 兼容的对象存储后端。 ### 3️⃣ 指向您的工具 将您 AI 工具的 API 基地址设置为 `http://localhost:8317` 并开始编码！ **示例：OpenAI Codex (`~/.codex/config.toml`)** ``` [model_providers.tabcode] name = "openai" base_url = "http://localhost:8317/v1" requires_openai_auth = true ``` ## 🖥️ 管理面板 启用控制面板后，请打开： ``` http://localhost:8317/manage ``` - `remote-management.disable-control-panel` 在示例配置中默认为 `false`，因此在标准 Docker Compose 部署后即可访问控制面板。 - 启用后，当前的面板路由为 `/manage/login`。旧的 `management.html#/login` 路由仅为旧版保留。 - Docker Compose 部署在 `/manage` 暴露该面板。 - 服务器可以在需要时提供打包的 SPA 目录或自动获取面板资产。 - 此仓库包含 `/manage` 的托管/更新路径；独立的 Web 面板源码与 Go 服务器代码分开维护。 - 终端优先的管理也可通过 `docker compose exec cli-proxy-api ./cli-proxy-api -tui` 使用。 - 如果您想自定义面板资产源，请设置 `remote-management.panel-github-repository`。 ## 📐 架构 ``` CliRelay/ ├── cmd/server/ # Binary entry point and CLI mode dispatch ├── internal/api/ # HTTP server, management routes, middleware ├── internal/auth/ # Provider OAuth / cookie / browser auth flows ├── internal/config/ # Config parsing, defaults, migrations ├── internal/store/ # Local, Git, PostgreSQL, object-store auth/config persistence ├── internal/tui/ # Terminal management UI ├── internal/usage/ # SQLite usage DB, retention, analytics ├── internal/managementasset/ # /manage panel hosting and asset sync ├── sdk/ # Reusable Go SDK, handlers, executors ├── auths/ # Local credential storage ├── examples/ # SDK / custom provider examples ├── docs/ # Local docs and panel screenshots └── docker-compose.yml # Container deployment entry ``` ## 📚 文档 | 文档 | 描述 | |:----|:------------| | [入门指南](https://help.router-for.me/) | 完整的安装与设置指南 | | [管理 API](https://help.router-for.me/management/api) | 管理 API 端点的 REST API 参考 | | [Amp CLI 指南](https://help.router-for.me/agent-client/amp-cli.html) | 与 Amp CLI 及 IDE 扩展集成 | | [SDK 使用](docs/sdk-usage.md) | 在 Go 应用中嵌入代理 | | [SDK 高级](docs/sdk-advanced.md) | Executors 与 Translators 深入解析 | | [SDK 访问](docs/sdk-access.md) | SDK 上下文中的认证 | | [SDK 监视器](docs/sdk-watcher.md) | 凭证加载与热重载 | ## 📜 许可证 本项目基于 **MIT 许可证** 授权 —— 详见 [LICENSE](LICENSE) 文件。 ## 🙏 致谢与特别感谢 本项目是基于优秀的开源核心逻辑 **[router-for-me/CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)** 项目进行深度增强的分支。 我们要向原版 **CLIProxyAPI** 项目及其所有贡献者表达最深切的感激之情！ 正是得益于上游构建的坚实且创新的代理分发基础，我们才能站在巨人的肩膀上。这使我们能够开发出独特的高级管理功能（如 API 密钥追踪与控制、基于 SQLite 的完整请求日志记录，以及实时系统监控），并从零开始重新构建了一个全新的前端仪表盘。 向开源精神致敬！ ❤️

标签：AI中转, AI代理, AI编程工具, API中转, API管理面板, API网关, Claude API, Codex, DLL 劫持, EVTX分析, Failover, Gemini 2.5 Pro, Gemini API, Go语言, GPT-5, LLM, OAuth, OpenAI API, Unmanaged PE, 令牌管理, 免费API, 兼容层, 反向代理, 多模型聚合, 多路复用, 大语言模型, 搜索引擎查询, 日志审计, 程序破解, 请求拦截, 请求日志, 负载均衡, 路由分发, 配额控制