trefeon/freebuff-proxy · 上手攻略

• 仓库：trefeon/freebuff-proxy
• 链接：https://github.com/trefeon/freebuff-proxy
• 分类：AI 接口代理 · 开发工具
• 作者：Tom
• 更新：2026-08-16

是什么

freebuff-proxy 是一个本地网关，把 FreeBuff/Codebuff 的免费 AI 编程模型（deepseek-v4-flash 等）以 OpenAI 兼容接口（/v1/chat/completions）暴露给任意工具——OpenCode、pi、9router、LiteLLM 或自己的脚本。

它的核心价值是"翻译 + 池化 + 隐匿"：

• 翻译：把标准 OpenAI 请求重新打包成上游 CLI 的会话协议，收到 SSE 流再转回 OpenAI chat.completion.chunk 格式
• 池化：多账号 token 轮转（热会话优先 + 轮询启动 + 故障切换），一个 token 限额了自动换下一个
• 隐匿：TLS 指纹、Header 清理、请求抖动，让出口流量看起来像真实浏览器，减少上游风控封号概率

解决什么问题

FreeBuff/Codebuff 的免费模型本身只能用官方 CLI 访问，API 不开放，也没有 OpenAI 兼容层。市面上很多 AI 编程工具（OpenCode、pi 等）只支持 OpenAI 格式的 API，根本接不进去。

freebuff-proxy 补了这个缺口：它是一个单一二进制（无 Go 链，无需 Docker），在本地监听 127.0.0.1:3457，把 OpenAI 格式的请求翻译给 FreeBuff 上游，再把 SSE 流翻译回 OpenAI 格式返回。

⚠️ ToS 风险：使用此代理违反 FreeBuff/Codebuff 服务条款，上游风控可永久封号。SAFE_MODE（默认开启）+ 不跑 24/7 无人值守 + 用真实邮箱注册的账号 + 适量使用，是降低风险的基本要求。

快速安装

方式一：一键安装脚本（推荐，Linux/macOS）

curl -sSL https://raw.githubusercontent.com/trefeon/freebuff-proxy/main/scripts/install-freebuff-proxy.sh | bash

方式二：PowerShell（Windows）

irm https://raw.githubusercontent.com/trefeon/freebuff-proxy/main/scripts/install-freebuff-proxy.ps1 | iex

方式三：Docker Compose

git clone https://github.com/trefeon/freebuff-proxy.git
cd freebuff-proxy
cp .env.example .env
# 编辑 .env 填入 AUTH_TOKENS=cb_xxx
docker compose up -d --build

方式四：直接下载 Release 二进制

从 Releases 页面下载对应平台的二进制（Linux/macOS/Windows × amd64/arm64），无需 Go 工具链。

方式五：从源码构建（需 Go 1.26+）

git clone https://github.com/trefeon/freebuff-proxy.git
cd freebuff-proxy
go build -o freebuff-proxy .
./freebuff-proxy

⚠️ Go 版本标注 1.26+，实测最低要求请以 go.mod 中 go 字段为准。

获取 Token

方式一：官方 CLI 登录（推荐，自动发现）

npm i -g freebuff
freebuff
# 按提示登录，token 自动保存到 ~/.config/manicode/credentials.json
# 代理启动时自动读取，无需手动填入 AUTH_TOKENS

方式二：脚本生成

# Linux/macOS
./scripts/gen-token.sh --clipboard

# Windows PowerShell
.\scripts\gen-token.ps1 -ToClipboard

脚本打开浏览器 OAuth 登录后把 token 打印到终端，不落盘（--save 可存文件，--append 可追加到 .env 的 AUTH_TOKENS）。

核心配置与命令

配置文件

cp .env.example .env
# 编辑 .env：
# AUTH_TOKENS=cb_xxx,...   # 逗号分隔多个 token（池化模式）
# SAFE_MODE=true            # 默认开启，不要关
# LISTEN_ADDR=127.0.0.1:3457  # 默认监听地址

启动

./freebuff-proxy

关键诊断命令

# 健康检查（返回 JSON，含 per-token 配额状态）
curl http://127.0.0.1:3457/healthz

# 完整诊断：配置/端口/DNS-TLS/每个 token 真实会话探针
./freebuff-proxy -doctor

# 单 token 探针：exit 0 = token 有效，exit 1 = 无效（适合脚本/CI）
./freebuff-proxy -test-token

# 列出可用模型
curl http://127.0.0.1:3457/v1/models

# Prometheus metrics
curl http://127.0.0.1:3457/metrics

# 热更新配置
curl -X POST http://127.0.0.1:3457/admin/reload

对接 AI 客户端

# 自动配置（检测已安装的客户端并写入配置）
./freebuff-proxy -setup

代理地址： - Base URL：http://localhost:3457/v1 - API Key：不需要（bridge 模式下填 token） - 模型：deepseek/deepseek-v4-flash

三种工作模式

典型适用场景

1. 把 FreeBuff 模型接进 OpenCode/pi：这些工具原生只支持 OpenAI API，通过 freebuff-proxy 桥接后即可使用 FreeBuff 的免费 deepseek-v4-flash 等模型
2. 多账号轮转跑自动化测试：池化模式下一个 token 限额自动切换下一个，保持 CI 任务不中断
3. 在 LiteLLM 中统一管理多个免费模型：LiteLLM 作为网关，freebuff-proxy 作为其中一路免费模型的适配层
4. 本地开发调试 OpenAI 兼容接口：先在 freebuff-proxy 上调试请求格式，再切到真实 OpenAI 端点

坑与注意

1. ToS 风险是真实的：SAFE_MODE 不要关；不要跑 24/7 大量无人值守任务；不要创建大量临时邮箱账号（已被明确标记为风控触发项）；用真实 Gmail 类邮箱注册，每个 token 对应一个真实账号
2. Docker 下 LISTEN_ADDR 要改：默认 127.0.0.1:3457，Docker 容器内无法监听 loopback，改成 LISTEN_ADDR=:3457（或 0.0.0.0:3457）
3. /healthz 不验证 token：只返回代理状态，不验证 token 是否有效；用 -test-token 验证 token
4. SSE 实时推送限制：Cloudflare quick tunnel 和 Tailscale Serve 不透传 SSE，代理会自动降级轮询
5. Windows 路径分隔符：gen-token.ps1 和 install-freebuff-proxy.ps1 用 PowerShell 语法，不能用 bash 执行
6. token 过期：上游 401 后代理回 502；定期运行 -doctor 检查 token 有效性
7. 并发下的单次会话刷新：代理内部有单次飞行（single-flight）保护，防止高并发工具调用循环下的竞态

与同类对比

freebuff-proxy 比同类 Go 实现多了内置 Admin UI、Bridge/Hybrid 多模式、Safe Mode 默认开启等工程化细节；且 trefeon 版本是目前工作队列里周增最高、社区最活跃的 FreeBuff 代理实现。

一句话推荐结论

需要在 OpenCode/pi/LiteLLM 等 OpenAI 兼容工具里用 FreeBuff 免费模型、又不想自建模型服务，freebuff-proxy 是目前最工程化的方案；使用时严格控制频率、保持 Safe Mode、避免批量无人值守，是长期保住账号的基本修养。

• 原始 commit：https://github.com/trefeon/freebuff-proxy/commits/main
• 构建依赖：Go 1.26+（源码构建）；Node.js >= 22（仅脚本工具）
• 许可证：LICENSE 文件未在 README 摘要中注明，建议使用时自行查看仓库 LICENSE