Cursor 免费起飞！CliRelay：神级 Go 开源代理，把 Claude Code/Gemini 变成标准 API！

🚀 痛点爆破：为什么你需要把 AI CLI 包装成标准 API？

在 AI 辅助编程风靡全球的今天，拥有超强推理与代码理解能力的 Claude 3.5 Sonnet 和 Gemini 1.5 Pro / 2.0 Flash 模型，已经成为了每一位开发者不可或缺的“编程外脑”。然而，高昂的官方 API 账单和严苛的绑卡充值门槛，常常让个人开发者与初创团队望而却步。与此同时，Anthropic 官方最新推出的 Claude Code 以及 Google 的 Gemini CLI 等终端交互工具，提供了极高质量且极低门槛（甚至免费）的试用额度，成了开发者眼中的“白嫖神兵”。

但是，这些命令行工具被牢牢限制在黑框终端里，无法被 Cursor、VS Code Cline 或 Windsurf 等主流 AI 物理编辑器直接调用。因为这些高集成度的 IDE 只认标准的 OpenAI API 格式（即通过 /v1/chat/completions 进行 HTTP 通信）。每次写代码都要在编辑器和终端之间来回复制粘贴，效率大打折扣。这就催生了打破 CLI 与 IDE 之间深渊阻隔的刚性痛点——如何将非 API 的 CLI OAuth 授权完美包装成标准的 Web API 接口，从而在你的编辑器里“白嫖”高配 AI 能力？

🛠️ 从 CLIProxyAPI 到 CliRelay：Go 语言带来的生产级蜕变

为了解决这一痛点，开源社区最先涌现出了诸如 router-for-me/CLIProxyAPI 这样的探索性项目。原版虽然完成了核心功能的最小可行性验证（MVP），但因为使用脚本语言编写，在多并发处理性能、复杂账号管理以及底层资源消耗上存在明显的瓶颈，难以胜任生产级的长驻任务。

近期，使用 Go 语言进行全面重构的 CliRelay (kittors/CliRelay) 强势来袭，完成了脱胎换骨的生产级蜕变：

1. 极致性能与超低开销：得益于 Go 语言优秀的并发模型（Goroutine）与静态编译特性，CliRelay 运行时的内存占用极低（通常不到 20MB），CPU 消耗几乎可以忽略不计。无论是本地常驻后台，还是部署在超轻量级的廉价 VPS 上，都毫无压力。

2. 生产级 Web 控制面板（/manage）：项目内置了极具现代感的图形化 Web UI。管理员可以在浏览器中直观地管理所有的 API Key 分发、实时监控每一个接口的调用频次、自由配置模型映射（Model Mapping），甚至可以直接查看实时的请求审计日志，彻底告别了繁琐、易出错的 YAML 配置文件修改。

3. 强大的 TUI 模式（-tui）：针对无桌面环境的 Linux 服务器，或者通过 SSH 远程连接的开发者，CliRelay 贴心地设计了 TUI（Terminal User Interface）终端图形化交互模式。只需在命令行启动时带上 -tui 参数，就能直接在终端黑框里进行优雅的账户交互、状态审计和授权登录，解决了远程服务器难以完成 OAuth 验证的棘手难题。

4. SQLite 与 Redis 双存储引擎：支持单机 SQLite 数据库（即插即用，零配置负担），同时也完美支持 Redis 缓存集群。对于个人开发者，SQLite 足够轻量；而对于想要搭建多人共享 API 中转站的小型团队，Redis 则能提供高并发的限流与用量审计支撑。

🌐 架构解密：CliRelay 如何在本地 8317 端口施展“换日”魔法？

CliRelay 的核心工作原理是一套非常巧妙的“反向代理与协议伪装”机制。在本地或远程服务器运行起来后，CliRelay 会在后台默默监听 8317 端口，并在该端口上向外暴露出一套完全兼容 OpenAI 规范的 API 路由。

下面是 CliRelay 核心的架构原理与数据流向流程图：

当你的 Cursor 或 VS Code 发起一个针对 http://localhost:8317/v1/chat/completions 的 API 请求时，CliRelay 并不需要去调用昂贵的第三方 API 接口。它的黑魔法在于：在内存中拦截这一 HTTP 请求，提取出 Prompt 和上下文，随后在后台无缝驱动或模拟 Claude Code / Gemini CLI 的底层通信会话。

它会与官方的命令行交互通道维持长连接，将请求伪装成用户的终端输入“喂”给 CLI，紧接着实时捕获 CLI 输出的流式（SSE）响应，再将其精准包装成 OpenAI 格式的流式数据实时返回给你的 IDE 编辑器。这种“金蝉脱壳”的代理中转，使得 IDE 误以为自己正在与官方的高速 API 直接对话，从而实现零阻碍的“降维接入”。

⚙️ 极速上手：生产级 Docker Compose 部署与 YAML 配置实战

为了保障极致的部署体验，我们推荐使用 Docker Compose 进行一键拉起。下面是一份生产级的 docker-compose.yml 编排配置，能够帮助你在本地或 VPS 服务器中快速建立稳定的中转服务。

1. 编写 docker-compose.yml

version: '3.8'

services:
  clirelay:
    image: kittors/clirelay:latest
    container_name: clirelay-service
    restart: always
    ports:
      - "8317:8317"
    volumes:
      - ./config.yaml:/app/config.yaml
      - ./data:/app/data
    environment:
      - TZ=Asia/Shanghai

2. 编写 config.yaml 配置文件

为了保障凭证的绝对安全，请牢记敏感凭证安全防御规范，切勿将包含真实 API 密钥或 Session Token 的配置文件上传到任何公开仓库。你可以使用以下安全占位符模板进行配置，并在本地运行前用真实的 Token 进行手动替换：

server:
  port: 8317
  web_manage: true
  auth_token: "sk-clirelay-admin-token-placeholder" # 替换为你自定义的 /manage 管理面板强口令

database:
  type: "sqlite" # 可选 "sqlite" 或 "redis"
  dsn: "/app/data/clirelay.db"

# 密钥与模型轮换规则
relays:
  - provider: "claude-code"
    enabled: true
    # 这里填写捕获到的 Claude Code 终端 Session Token
    session_token: "CLAUDE_SESSION_TOKEN_PLACEHOLDER"
    models:
      - "claude-3-5-sonnet"
    weight: 10 # 路由权重

  - provider: "gemini-cli"
    enabled: true
    # 这里填写捕获到的 Gemini CLI 授权 Credential JSON 字符串
    oauth_credential: "GEMINI_OAUTH_CREDENTIAL_PLACEHOLDER"
    models:
      - "gemini-1.5-pro"
      - "gemini-2.0-flash"
    weight: 5

[!WARNING] 安全防泄露红线：session_token 和 oauth_credential 是高价值的敏感凭证。部署时应确保 config.yaml 文件的权限为 600，只允许当前拥有者读写，并在项目的 .gitignore 中明确加入该文件名，防止敏感凭证外泄。

🔑 凭证捕获与 OAuth 命令行授权技巧

在部署完 CliRelay 后，许多开发者在捕获 Claude Code 或 Gemini CLI 的 Session 授权凭证上遇到了困难。CliRelay 针对这一高频卡点，提供了两款极其丝滑的半自动凭证获取与配置方式。

对于 Gemini CLI 的授权，我们可以直接通过命令行启动 CliRelay 的内置捕获程序：

# 启动 CliRelay 并进入 OAuth 自动捕获登录流程
./cli-proxy-api -login -provider gemini

执行该指令后，终端会打印出一个 Google 官方的安全授权 URL，并在本地后台开启一个临时监听回调。你只需要将该 URL 复制到浏览器中打开，登录你拥有试用额度的 Google 账号并点击“允许授权”。授权完成后，浏览器会自动跳转并将 OAuth 凭证回传给本地的回调接口。CliRelay 会自动捕获并无缝写入 SQLite 数据库中，整个过程无需手动抓包，极其优雅。

如果你是在无 GUI 界面的远程 VPS 服务器上进行配置，可以进入 TUI（终端用户界面）模式：

# 在纯字符终端启动 TUI 交互界面
./cli-proxy-api -tui

在这个酷炫的终端界面中，你可以通过键盘方向键和回车键，实时查阅每个接入账号的存活状态、健康度评分、快速配置负载权重，甚至可以通过在 TUI 界面中生成的动态二维码或简易链接，一键实现免密凭证刷新。

🛡️ 高可用避坑指南：多账号轮换与故障自动兜底机制

在多人高频共用或者频繁读写代码的场景下，单个账号的 API Key 非常容易触发大模型的 Rate Limit（频率限制，如每分钟请求次数超限），或者发生 Session 突然过期导致服务中断的情况。CliRelay 引入了工业级的高可用轮换（Key Rotation）和故障兜底（Failover）机制，这让它比普通的单点中转工具拥有更高的可用性：

1. 自动健康度检测：CliRelay 会在后台开启守护协程，定时向各接入的 CLI 引擎发送微型心跳探测。一旦发现某个 Token 出现 Unauthorized（未授权）或触发了 Web 端的防机器人验证码，它会在微秒级将该 Relay 通道标记为“挂起”状态，避免将后续请求分发至失效节点。

2. 多账号权重负载均衡：通过在 config.yaml 中为每个 relay 节点配置 weight，你可以接入多个 Claude 3.5 账号。CliRelay 会采用加权轮询（Weighted Round Robin）算法，将 Cursor 或 Cline 发来的请求合理分配到不同的可用账号中，实现完美的负载分摊。

3. 无感知故障重试（Failover）：当 Cursor 发起请求，若当前被指派的 A 账号突然返回了限制错误（如 HTTP 429），CliRelay 不会将报错暴露给前端。它会在后台静默拦截这一失败响应，并瞬间在微秒内将请求重定向到排在备用队列的 B 账号进行重试。对于前端的 IDE 编辑器来说，整个过程完全无缝，依然能够流畅地流电流式接收到 AI 吐出的代码！

🎯 总结：开启全自动智能开发自由新时代

通过 Go 语言编写的高性能 CliRelay 代理，我们不仅完美打破了非 API 交互式命令行工具（如 Claude Code / Gemini CLI）与本地 IDE 编辑器（如 Cursor / VS Code）之间的壁垒，更为广大开发者省下了成百上千美元的 API 账单。

高可用的多账户轮换和卓越的故障自动重试机制，使得这一中转代理完全能够满足日常高强度、高并发的代码编写需求。心动不如行动，快快参考文中的 Docker Compose 配置在你的本地或云端 VPS 上部署一套吧，让你的 Cursor 编程助手实现真正的“额度起飞，免费畅玩”！

长按二维码关注 “边学边练”