CliRelay：统一AI工具代理网关，实现多模型管理与智能路由

1. 项目概述：一个为AI命令行工具设计的统一代理网关

如果你和我一样，日常开发中重度依赖各种AI辅助工具，比如Claude Code、Gemini CLI，或者那些基于OpenAI API的IDE插件，那你一定遇到过这个痛点：每个工具都需要单独配置API密钥，管理起来麻烦不说，不同工具的订阅状态、配额限制、请求日志还都散落在各处，想统一查看和分析几乎不可能。更别提有些工具只支持特定的认证方式，比如OAuth，而你的密钥可能又是另一种形式。

CliRelay就是为了解决这个“AI工具管理碎片化”问题而生的。它是一个用Go语言编写的、开源的统一代理服务器。简单来说，你可以把它理解为你所有AI工具和上游AI服务商（如Google Gemini、Anthropic Claude、OpenAI等）之间的一个“智能路由器”和“数据中台”。你只需要将你的AI客户端（无论是命令行工具还是兼容OpenAI API的SDK）的请求指向CliRelay，它就能帮你处理复杂的认证路由、负载均衡、请求日志记录和配额管理。

它的核心价值在于“统一”和“透明化”。通过一个统一的本地端点（默认是http://localhost:8317），你就能接入几乎所有主流的AI服务。更重要的是，它提供了一个功能强大的Web管理面板和终端TUI（文本用户界面），让你能清晰地看到每一个请求的来龙去脉：谁发的、用了哪个模型、消耗了多少Token、响应时间多长、是否成功。这对于团队协作、成本核算和故障排查来说，简直是神器。

2. 核心功能深度解析与设计思路

2.1 多提供商代理引擎：不只是简单的转发

很多同类工具只是一个简单的HTTP代理，把请求从一个地方转发到另一个地方。CliRelay的设计思路则复杂和智能得多，它更像一个“AI流量调度中心”。

统一端点与协议兼容：它的首要任务是提供一个与OpenAI Chat Completions API协议兼容的端点。这意味着任何能调用OpenAI API的客户端，理论上都能无缝接入CliRelay，无需修改代码。它内部维护了一个庞大的“模型-提供商”映射表，当收到一个请求指定使用gpt-4模型时，CliRelay会根据你的配置，智能地将这个请求路由到背后真正的OpenAI端点，或者你配置的其他兼容服务（如OpenRouter、甚至是自建的模型服务）。这种设计极大地扩展了工具的适用性。

智能负载均衡与故障转移：这是我认为最实用的功能之一。假设你为同一个提供商（比如OpenAI）配置了多个API密钥，CliRelay支持两种调度策略：轮询（Round-robin）和填满优先（Fill-first）。轮询就是平均分配请求，避免单个密钥过快耗尽；填满优先则会优先使用第一个密钥，直到其配额用尽再切换到下一个。更关键的是“自动故障转移”，当某个上游通道（比如某个API密钥对应的服务）因为配额耗尽、网络错误或服务不可用而失败时，CliRelay会自动、无缝地切换到备用的健康通道，对前端客户端来说，这个失败过程几乎是不可感知的，极大地提升了服务的可用性。

多模态与流式响应支持：现代AI应用早已不止于文本。CliRelay完整支持文本+图像的输入（Multimodal），以及函数调用（Function Calling/Tools）。对于流式响应（Server-Sent Events, SSE），它也能正确地进行代理和传输，确保像ChatGPT那样的逐字输出体验不受影响。

2.2 全链路请求日志与监控：让每一次对话都有迹可循

数据驱动决策的前提是有数据。CliRelay内置了一个基于SQLite的、极其详尽的请求日志系统。它不仅仅记录“成功”或“失败”，而是捕获了近乎全量的交互数据。

结构化日志记录：每一条API请求和响应都会被解析并结构化地存入SQLite数据库。记录的信息包括：

• 基础信息：时间戳、请求ID、客户端IP（如果可获取）。
• 请求内容：使用的API密钥（脱敏后）、目标模型、提示词（Prompt）和系统指令（System Message）的完整内容。
• 性能指标：请求耗时、响应状态码。
• 用量详情：输入Token数、输出Token数、推理Token数（如果提供商返回）、缓存Token数。这是进行成本核算的黄金数据。
• 路由信息：最终使用了哪个上游提供商（Channel）、哪个具体的API密钥。

高性能与可查询性：所有日志都支持高级过滤和分页查询。你可以在管理面板中轻松地按时间范围、API密钥、模型、状态进行筛选。对于需要长期审计或分析团队使用情况的场景，这个功能不可或缺。

健康评分引擎：这是一个很酷的运维特性。CliRelay会实时计算每个上游通道的“健康分”（0-100），综合考量成功率、平均延迟、当前活跃状态以及近期的错误模式。在管理面板上，你可以一眼就看到哪些通道是绿色的（健康）、黄色的（警告）或红色的（故障），便于快速定位问题根源。

2.3 精细化的API密钥与访问管理

在团队或复杂个人使用场景下，密钥管理是头等大事。CliRelay将密钥管理提升到了企业级水平。

密钥的全生命周期管理：你可以通过管理API或Web界面创建、编辑、禁用或删除API密钥。每个密钥都可以附加自定义名称和备注，例如“前端团队-测试密钥”或“张三的Claude配额”。

配额与限流：这是控制成本的关键。

• 配额限制：你可以为每个密钥设置总Token数上限或总请求数上限。一旦达到限额，该密钥的所有请求将被拒绝，防止意外超支。
• 速率限制：支持基于时间的限流，例如“每分钟最多60次请求”或“每小时最多1000次请求”。这既能防止滥用，也能适配不同上游API的调用频率限制。

密钥绑定与模型权限：你可以指定某个密钥只能使用特定的模型或特定的上游通道。例如，你可以创建一个“低成本专用密钥”，只允许它调用gpt-3.5-turbo模型，并绑定到价格更优惠的第三方OpenAI兼容服务上，从而实现对不同用途、不同成本的请求进行物理隔离。

2.4 安全与认证架构

安全是代理服务的生命线。CliRelay在安全设计上考虑得非常周全。

多样化的上游认证支持：它几乎支持了所有常见的AI服务认证方式：

• API密钥：最直接的方式，适用于OpenAI、Anthropic等。
• OAuth 2.0：对于像Google Gemini、Claude Code这类通过浏览器登录获取令牌的服务，CliRelay内置了完整的OAuth授权流程。你只需要在管理面板点击“登录”，它会引导你完成授权，并安全地存储刷新令牌。
• Cookie / 设备码：对于一些特殊服务（如某些国内的模型平台），它甚至支持通过导入浏览器Cookie或使用设备码流进行认证。

请求“隐身”：为了保护客户端隐私，CliRelay在将请求转发给上游提供商时，会剥离或重写可能暴露客户端真实身份的信息（如特定的User-Agent头）。这在一定程度上增加了匿名性。

管理面板隔离：Web管理面板的访问受独立密码保护，与代理API的认证体系分离。这意味着即使有人知道了你的代理服务地址，也无法直接访问管理后台查看日志和密钥。

3. 从零开始部署与配置实战

理论讲得再多，不如动手搭一个。下面我将以最推荐的Docker部署方式，带你一步步搭建一个属于你自己的CliRelay服务。

3.1 环境准备与一键部署

CliRelay官方提供了极其便捷的一键安装脚本，它能够自动处理Docker安装、容器配置和语言选择。

第一步：执行安装脚本打开你的终端（Linux/macOS），运行以下命令。这个脚本会从GitHub拉取最新的安装脚本并执行。

curl -fsSL https://raw.githubusercontent.com/kittors/CliRelay/main/install.sh | bash

安装过程详解：

1. Docker检测与安装：脚本首先会检查系统是否安装了Docker。在Linux上，如果没找到，它会尝试自动安装Docker Engine。在macOS上，它不会自动安装Docker，但会检查Docker Desktop、OrbStack或Colima是否正在运行。如果没运行，它会给出明确提示，你需要先手动启动Docker服务。
2. 架构识别：脚本会自动检测你的CPU架构（amd64或arm64），并拉取对应平台的Docker镜像，确保兼容性。
3. 语言选择：运行过程中，脚本会提示你选择界面语言，输入1为英文，2为中文。这个选择会被写入容器配置，后续Web面板和TUI都会默认使用该语言。
4. 容器部署：脚本会拉取最新的ghcr.io/kittors/clirelay:latest镜像，并启动一个Docker容器。所有配置和数据都会通过Docker卷（Volume）持久化在宿主机上，即使容器重启也不会丢失。
5. 命令行工具安装：安装完成后，你的系统路径中会多出一个clirelay命令。这是一个管理助手，用于后续的日常操作，如查看状态、更新、重启等。

注意：一键脚本非常方便，但它会在你的系统上安装Docker并启动服务。如果你对生产环境有严格的管控要求，或者希望进行更定制化的部署，可以参考后文的手动Docker Compose部署方式。

第二步：验证服务状态安装完成后，运行以下命令检查服务是否正常运行：

clirelay status

如果一切正常，你会看到服务正在运行，并输出本地访问地址（通常是http://localhost:8317）。

此时，你的CliRelay代理服务已经在后台运行了。你可以通过http://localhost:8317访问代理API，通过http://localhost:8317/manage访问Web管理面板（首次访问需要设置管理密码）。

3.2 核心配置文件详解

虽然一键安装已经生成了默认配置，但要想充分发挥CliRelay的能力，你必须理解并修改其核心配置文件config.yaml。这个文件通常位于Docker卷映射的目录下，例如./data/config.yaml（具体路径安装脚本会有提示）。

让我们拆解几个最关键的部分：

基础服务器配置：

server: host: "0.0.0.0" # 监听地址，0.0.0.0表示接受所有网络接口的连接 port: 8317 # 监听端口，就是你的AI工具要连接的端口 # 管理面板相关 management: enabled: true # 是否启用Web管理面板 path: "/manage" # 面板访问路径

上游提供商通道配置： 这是配置的核心。你需要在providers部分添加你拥有的各个AI服务的访问凭证。以下是一个配置了OpenAI和Google Gemini的例子：

providers: # OpenAI 兼容服务组 - type: "openai-compatible" name: "我的OpenAI主账号" # 通道自定义名称 enabled: true config: # 方式1: 使用API密钥 api_key: "sk-你的OpenAI-API密钥开头几位***" # 在面板中填写完整密钥更安全 base_url: "https://api.openai.com/v1" # OpenAI官方端点 # 你可以配置多个API密钥实现负载均衡 api_keys: - "sk-***key1" - "sk-***key2" # 模型别名映射：将通用模型名映射到提供商特定模型名 model_aliases: "gpt-4": "gpt-4-turbo-preview" "gpt-3.5-turbo": "gpt-3.5-turbo-0125" # 排除某些昂贵模型不使用此通道 excluded_models: - "gpt-4-32k" # Google Gemini 配置 - type: "gemini" name: "我的Gemini账户" enabled: true config: # 方式2: 使用OAuth（推荐，更安全且无需处理密钥轮换） # 在Web面板的“OAuth登录”页面完成授权后，会自动生成auth文件 # 此处只需引用auth文件路径（在Docker中，路径是容器内的路径） auth_file: "/app/auths/gemini_auth.json" # 或者，如果你已有API密钥 # api_key: "AIza***"

API密钥管理配置： 这里定义客户端访问你的CliRelay代理时需要使用的密钥。

api_keys: - key: "clirelay-sk-客户端密钥1" # 客户端工具配置时使用的密钥 name: "开发环境通用密钥" enabled: true quota: max_tokens: 1000000 # 总Token数限制 max_requests: 10000 # 总请求数限制 rate_limit: requests_per_minute: 60 # 每分钟限流 # 绑定此密钥只能使用特定的上游通道 allowed_channels: - "我的OpenAI主账号" - "我的Gemini账户" # 绑定此密钥只能使用特定模型 allowed_models: - "gpt-3.5-turbo" - "gemini-pro"

数据持久化与日志配置：

database: # SQLite是默认且推荐的，无需额外服务 path: "/app/data/usage.db" # 日志数据库路径 request_log_storage: store_content: true # 是否存储完整的请求/响应内容（用于详情查看） content_retention_days: 30 # 完整内容保留30天 max_total_size_mb: 1024 # 内容存储总大小上限1GB，超出会自动清理最旧的数据 # 元数据（非完整内容）会永久保留，供统计图表使用 # 可选：Redis集成，用于跨重启保存实时指标（如健康分） redis: enable: false # 默认关闭，如需开启请设置true并配置地址 # address: "redis:6379"

修改完配置后，需要重启CliRelay服务使配置生效：

clirelay restart

3.3 配置你的AI客户端工具

服务跑起来，密钥也配好了，接下来就是让AI工具用起来。原理很简单：把你原来直接指向官方API的地址，改成指向本地的CliRelay。

以Visual Studio Code的CodeGPT插件为例：

1. 打开VSCode设置（Ctrl+,或Cmd+,）。
2. 搜索CodeGPT。
3. 找到Api Base Url或类似的设置项。
4. 将其值从https://api.openai.com/v1改为http://localhost:8317/v1。
5. 在Api Key处，填入你在CliRelay中创建的客户端API密钥（例如clirelay-sk-客户端密钥1）。

以命令行工具ollama（假设其兼容OpenAI API）为例： 你可以通过环境变量来设置：

export OPENAI_API_BASE=http://localhost:8317/v1 export OPENAI_API_KEY=clirelay-sk-客户端密钥1 ollama run llama2 # ollama会通过CliRelay代理请求

以curl直接测试：

curl http://localhost:8317/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer clirelay-sk-客户端密钥1" \ -d '{ "model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "Hello, CliRelay!"}], "stream": false }'

如果返回了正常的JSON响应，恭喜你，代理链路已经通了！

4. 高级运维与故障排查实录

即使部署顺利，在实际使用中你也会遇到各种问题。下面分享一些我踩过的坑和对应的解决方案。

4.1 管理面板无法访问或白屏

问题现象：服务启动后，访问http://localhost:8317/manage出现404错误或空白页面。

排查步骤：

1. 检查服务状态：首先运行clirelay status或docker ps确认clirelay容器是否在运行。
2. 检查配置：确认config.yaml中server.management.enabled为true。一键安装脚本默认是开启的。
3. 检查面板资源：CliRelay的Web面板资源可以是内嵌的，也可以从远程Git仓库动态拉取。如果网络问题导致拉取失败，可能会白屏。查看容器日志：

   clirelay logs

   搜索关键字management asset或panel，看是否有下载失败的错误。你可以尝试在管理面板的“配置”页面，将remote-management.panel-github-repository暂时改为kittors/codeProxy（这是官方仓库）并重启服务。
4. 防火墙/端口冲突：确认宿主机防火墙没有阻止8317端口。检查是否有其他程序占用了8317端口：sudo lsof -i :8317。

4.2 客户端请求返回“401 Unauthorized”或“Invalid API Key”

问题现象：AI工具连接CliRelay时报认证错误。

排查步骤：

1. 核对客户端密钥：确保你在AI工具中配置的API Key，是你在CliRelay的api_keys配置段中定义的其中一个key值，并且该密钥的enabled为true。
2. 检查密钥配额：登录Web管理面板，进入“API Keys”页面，找到对应的密钥，查看其“已用配额”是否已经达到了设置的max_tokens或max_requests上限。如果达到上限，请求会被拒绝。
3. 检查速率限制：同样在“API Keys”页面，查看该密钥的请求频率是否触发了requests_per_minute等限流规则。
4. 检查密钥绑定：确认该密钥的allowed_channels和allowed_models是否包含了当前请求试图使用的上游通道和模型。如果请求了一个未被允许的模型，也会返回403错误。
5. 查看请求日志：这是最直接的排查方式。进入管理面板的“Request Logs”页面，过滤出失败的请求（Status非2xx），点击查看详情。日志会明确记录失败的原因，例如quota_exceeded,rate_limit_exceeded,channel_not_allowed等。

4.3 上游提供商认证失败（OAuth令牌过期）

问题现象：请求长时间挂起后失败，或在日志中看到provider authentication failed错误。

排查步骤：

1. OAuth令牌刷新：像Gemini、Claude这类使用OAuth的服务，其访问令牌（Access Token）通常有1小时的有效期，但刷新令牌（Refresh Token）有效期很长。CliRelay会自动尝试使用刷新令牌获取新的访问令牌。如果失败，可能是：
   • 网络问题：无法连接到OAuth提供商的服务。
   • 授权被撤销：你在Google或Anthropic的账户设置中移除了CliRelay的授权。
   • 刷新令牌过期：虽然不常见，但某些服务的刷新令牌也可能过期（例如几个月）。
2. 解决方案：重新进行OAuth授权。
   • 打开Web管理面板，进入“AI Providers”页面。
   • 找到对应提供商的标签页（如Gemini）。
   • 点击“OAuth Login”按钮，按照指引重新完成浏览器登录授权流程。
   • 授权成功后，CliRelay会自动获取新的令牌并更新auth_file。
3. 对于API密钥方式：检查密钥是否在对应服务商的控制台被禁用或删除。如果是，需要生成新密钥并在CliRelay配置中更新。

4.4 请求路由错误或使用了非预期的模型

问题现象：你请求gpt-4，但日志显示实际使用了gemini-pro，或者响应质量不符合预期。

排查步骤：

1. 检查模型别名映射：在提供商配置中，model_aliases会将通用模型名映射到具体模型。请确认你的映射关系是否符合预期。例如，你可能将gpt-4映射到了一个较旧的gpt-4版本，而不是最新的gpt-4-turbo。
2. 检查通道优先级与健康状态：CliRelay在路由时，会优先选择健康分高、且支持所请求模型的启用状态的通道。如果某个通道被禁用（enabled: false）或健康分极低，它不会被选用。进入“Dashboard”查看各通道的实时健康分。
3. 检查模型排除列表：确认你请求的模型不在目标通道的excluded_models列表中。
4. 理解负载均衡策略：如果你为同一个提供商配置了多个API密钥（通道），且它们都支持同一个模型，那么请求会根据配置的调度策略（轮询或填满优先）分配到不同密钥上。这可能导致同一种模型的请求有时快有时慢（如果密钥对应的服务区域不同）。

4.5 数据库文件过大或性能下降

问题现象：运行一段时间后，发现磁盘空间占用增长较快，或者Web面板查询日志时变慢。

优化建议：

1. 调整日志保留策略：这是控制存储增长最有效的方法。编辑config.yaml中的request_log_storage部分：

   request_log_storage: store_content: true # 如果不需要查看历史对话详情，可设为false以节省大量空间 content_retention_days: 7 # 将完整内容保留时间从30天缩短为7天 max_total_size_mb: 500 # 将总大小上限从1GB降低到500MB

   修改后重启服务。CliRelay会在后台自动清理过期数据。
2. 定期清理：CliRelay提供了管理API来手动清理旧数据。你也可以通过SQLite命令行工具直接操作数据库文件（位于Docker卷中），但操作前请务必备份。
3. SQLite优化：对于非常大的数据库（超过几GB），可以考虑启用SQLite的WAL（Write-Ahead Logging）模式或定期执行VACUUM命令来优化性能和空间。这需要你进入容器内部操作或通过管理API触发。
4. 考虑外部存储：对于企业级部署，可以考虑启用PostgreSQL或S3后端来存储配置和认证信息，虽然请求日志目前仍主要使用SQLite。

4.6 使用clirelay命令行助手

一键安装脚本安装的clirelay命令是你日常运维的好帮手：

• clirelay status：快速查看服务运行状态、版本和访问地址。
• clirelay logs：实时查看容器日志，等同于docker logs -f clirelay。加-n 50可以查看最近50行。
• clirelay restart：重启服务，适用于修改了config.yaml后。
• clirelay update：更新CliRelay到最新版本。它会拉取最新的Docker镜像并重启容器，同时保留你的所有配置和数据。这是最安全的升级方式。
• clirelay tui：打开终端文本用户界面。当没有图形界面或需要快速操作时非常有用，可以完成查看日志、管理密钥、重启服务等大部分操作。

5. 生产环境部署建议与安全考量

如果你计划在团队或生产环境中使用CliRelay，以下几点需要特别注意：

网络暴露：默认配置server.host: 0.0.0.0会使服务监听所有网络接口。如果部署在云服务器上，这意味着8317端口对公网是可访问的。强烈建议：

1. 使用防火墙（如ufw、云服务商安全组）严格限制访问来源IP，只允许受信任的IP段（如公司内网、VPN IP）访问8317端口。
2. 或者，将CliRelay部署在内网，并通过反向代理（如Nginx）对外提供服务。在Nginx上配置HTTPS、访问密码、甚至客户端证书认证，可以极大提升安全性。

管理面板密码：首次访问/manage时会要求设置管理密码。请务必设置一个强密码，并定期更换。管理面板拥有最高权限，可以查看所有请求日志和密钥信息。

API密钥安全：

• 不要在config.yaml中明文填写上游服务商（如OpenAI）的API密钥。最佳实践是：在配置文件中只写一个占位符或注释，然后通过Web管理面板的“AI Providers”页面添加通道，在表单中输入密钥。面板会安全地处理密钥存储。
• 定期轮换（Rotate）你分发给客户端的API密钥（即CliRelay自身的api_keys）。可以在管理面板中禁用旧密钥，生成新密钥，然后通知客户端更新。

数据备份：定期备份Docker卷中的数据目录。这个目录包含了SQLite数据库（所有日志）和认证文件。你可以写一个简单的cron任务，定时将./data目录打包压缩并上传到安全的存储中。

监控与告警：虽然CliRelay自带健康评分和面板，但对于生产环境，建议将其关键指标（如服务是否存活、请求失败率、健康分下降）集成到你的集中监控系统（如Prometheus + Grafana）中。可以通过定期调用CliRelay的管理API/api/health或/api/stats来获取JSON格式的健康状态和统计信息。

资源限制：在Docker Compose文件中，可以为clirelay服务设置CPU和内存限制，防止其异常时影响宿主机。

services: clirelay: image: ghcr.io/kittors/clirelay:latest deploy: resources: limits: memory: 1G cpus: '1.0'

最后，再分享一个我个人的使用体会：CliRelay的价值随着你连接的AI工具和账户数量的增加而指数级增长。当它成为你所有AI流量的唯一出入口时，你获得的不仅仅是便利，更是一种全局的掌控力和洞察力。你可以清晰地知道每个项目、每个成员消耗了多少资源，可以快速定位是哪个上游服务出现了问题，可以灵活地调配资源而不需要每个工具都重新配置。它从一个工具，演变成了你AI工作流中不可或缺的基础设施。