企业官网建设流程全解析

CliRelay 是一个自托管（self-hosted）的OpenAI 兼容 AI 网关，专为编程 CLI 工具设计：它把你已经在付费的 Claude、Codex、Gemini 订阅账号和各种 API Key 统一挂在一个端点后面，让 Claude Code、Codex、Gemini CLI 以及任何 OpenAI 兼容客户端都能直接复用，同时提供多租户 Web 控制台、完整请求日志和消费配额管理。

为什么你需要一个 AI 网关

用过 Claude Code 或 Codex 的同学大概都遇到过这些场景：

• 📇账号池管理头疼：手上有 3 个 Claude 订阅、2 个 Codex 账号，切换要反复改环境变量或配置文件；
• 💸用量不可控：团队成员共用你的 Key，跑了一天不知道烧了多少钱；
• 🩹没有容灾：某个账号额度用尽或 429 限流，任务直接中断，手动切账号；
• 📊零可观测性：谁调用了哪个模型、耗了多少 token、延迟多少，完全摸黑。

CliRelay 的思路是：客户端只认一个地址，剩下的事（鉴权、选账号、协议转换、失败切换、记账）全部交给网关。

CliRelay 核心能力一览

一个请求是怎么流转的

客户端发来的每一个请求，在 CliRelay 内部会经过四步：

1. 鉴权（Authenticate）：客户端 Key 解析出所属门户账号和权限配置，决定可用通道组、模型和配额；
2. 准入（Admit）：在请求到达上游之前，先检查日/周期/终身消费、请求数配额、RPM、TPM 和并发限制；
3. 路由（Route）：按调度策略把请求投给组内健康的通道（AI 账号或 Provider Key），失败则冷却该通道并自动故障转移到下一个；
4. 转换与记录（Translate & Record）：执行器负责 OpenAI ⇄ Anthropic ⇄ Gemini 协议互转，流式返回结果，并写入请求日志与用量统计，驱动所有仪表盘。

协议转换的实现在 internal/translator/，各上游的调度、冷却与执行器在 internal/runtime/executor/。

支持哪些上游

CliRelay 支持的上游非常宽，主流接入方式包括：

添加账号时控制台是引导式的：按"浏览器登录 / 设备码 / 凭据导入"三类分组，一步步告诉你该复制哪个地址、为什么登录页打不开、凭据从哪来。已有的 Claude 会话 Key、Codex refresh token、Grok SSO Cookie 可以直接批量导入成账号，失败行还能单独重试。

快速上手：Docker Compose 三步跑起来

推荐用 Docker Compose 部署，它会一次性启动 CliRelay、PostgreSQL 15、Redis 7 和 updater 升级边车：

git clone https://gitcode.com/gh_mirrors/cl/CliRelay cd CliRelay docker compose up -d

首次启动时clirelay-init服务会自动创建.env和config.yaml，并生成管理密码等密钥。启动后记住两个地址：

然后在控制台完成两件事：

1. 加上游：AI Accounts → Add AI account登录订阅账号，或AI Providers添加 API Key；
2. 建客户端 Key：Portal Accounts → Create user，每个门户账号可持有一个或多个 Key。

⚠️ 全新安装默认没有可用客户端 Key，任何客户端请求都会被拒绝，务必先创建 Key。config.example.yaml 里的your-api-key-*都是占位符，永远无效。

把你的编程 CLI 接上网关

拿到客户端 Key 后，各工具改一行配置就能指向 CliRelay。

Claude Code——设置两个环境变量即可：

export ANTHROPIC_BASE_URL=http://localhost:8317 export ANTHROPIC_AUTH_TOKEN=sk-your-client-key claude

Codex CLI——在~/.codex/config.toml中新增一个自定义 provider：

model_provider = "clirelay" [model_providers.clirelay] name = "openai" base_url = "http://localhost:8317/v1" requires_openai_auth = true

任何 OpenAI 兼容客户端——直接用 Chat Completions 接口，把Authorization换成你的客户端 Key 即可。

💡 控制台里的CC Switch Config还能一键生成 Claude Code / Codex 的导入预设，模型映射和通道组都填好了，省去手改配置。

控制台巡礼：请求日志、配额与多租户

请求日志：每次调用都有据可查

请求日志列出每一次调用的通道、门户用户与 Key、缓存/输入/输出 Token、延迟和成本，支持按用户、模型、通道、状态筛选。开启正文存储后，还能点开查看完整的请求与响应内容。

相关查询与写入实现在 internal/usage/ 下的请求日志与滚动统计模块。

通道组与模型广场：流量往哪走，一目了然

通道组决定某个 Key 能用哪些通道、组内流量怎么分摊；模型广场则展示当前租户可达的每个模型的能力、服务通道与百万 Token 价格。

多租户与审计：为团队而生的权限体系

租户各自持有独立的账号、Key、路由和数据，管理员可在头部切换生效租户；角色以resource.action形式授权（如providers.test、models.write），决定每个用户能看到哪些页面和按钮；谁改了什么、从哪里改的、是否成功，全部记录在审计日志中。

生产部署与进阶玩法

其他值得了解的设计点：

• 🗄️PostgreSQL 15+ 是唯一事实来源，Redis 7+ 只存可重建的缓存、锁、限流和队列状态，迁移细节见 docs/postgres-redis-migration.md；
• ⚙️配置可热改：面板 Config 页提供分组表单 + 内联校验，也能用 YAML 源码编辑器；小内存主机可一键套用推荐的低资源配置；
• 🔁在线升级：updater 边车负责拉取新版本，面板会展示目标版本、每个阶段和最终结果；
• 📦可嵌入 SDK：sdk/ 提供了可嵌入的 Go SDK，方便在自己的应用里复用这套代理能力，用法见 docs/sdk-usage_CN.md。

写在最后

CliRelay 解决的本质问题很简单：让你已经付费的 AI 账号像 API 池一样被管理——一个 OpenAI 兼容端点收口所有客户端，账号自动调度与故障转移，消费可计量可封顶，团队可按租户隔离使用。如果你正在同时维护 Claude Code、Codex、Gemini CLI 多个工具，又希望用量和成本尽在掌握，这套网关值得部署到自己的服务器上跑一跑。

项目核心入口在 cmd/server/，完整部署编排见 docker-compose.yml。CliRelay 基于 MIT 协议开源，感谢上游 CLIProxyAPI 项目奠定的代理核心。