GGB Docs

docs.ggb.gg

PUBLIC DOCS FOR GGB USERS

GGB API 接入文档

从下载 Codex、创建 Key、填写 Base URL，到生成客户端配置，这一页按真实接入顺序整理。新用户先按 3 分钟流程跑通，熟练用户可以直接复制 SDK 示例或使用配置生成器。

开始接入 打开控制台 生成配置
!
重要：CCSwitch / Codex 这类 Responses 端点通常填 https://ggb.gg；OpenAI SDK / Chat Completions 兼容示例使用 https://ggb.gg/v1。如果后台「API 端点」显示了默认地址，优先按后台和客户端提示填写。

接入控制台

这些值是用户最容易填错的地方，所以放在第一屏。

控制台 https://ggb.gg
Responses https://ggb.gg
SDK /v1 https://ggb.gg/v1
API Key sk-xxxxxxxx
模型名 以后台显示为准 
curl https://ggb.gg/v1/models \
  -H "Authorization: Bearer sk-xxxxxxxx"

Quickstart

3 分钟跑通 Codex

这套流程故意很短：下载工具，拿到 Key，填入配置，重启客户端。遇到不确定项，优先复制后台「使用密钥」里生成的配置。

1

安装 Codex 或打开你的客户端

如果你要使用 Codex，先从 OpenAI 官方页面下载或了解 Codex。其他支持 OpenAI-compatible API 的客户端也可以使用 GGB。

Codex 官方页面 Codex CLI 文档
2

登录 GGB 控制台并创建 Key

进入「API 密钥」，创建一个容易识别的 Key，例如 codex-main。Key 通常只完整显示一次，创建后请立即保存。

打开控制台
3

生成配置并重启客户端

把 Key、Base URL 和模型名填入客户端。保存配置后重启 Codex / IDE / CLI，再用一个短问题测试是否返回。

打开配置生成器

Downloads

下载入口

只放官方或项目主页链接。第三方工具版本更新很快，下载按钮尽量指向 latest，减少过期版本误导。

Codex

OpenAI 的编码代理工具。适合写代码、改配置、看日志、跑验证，也适合把 GGB 接到日常开发工作流里。

OpenAI Coding Agent
官方下载页 Windows 文档

CCSwitch

用于管理 Claude Code / Codex 等工具的 Provider 配置。适合不想手改配置文件的用户。

当前核验 v3.16.4 2026-06-27
官网 GitHub 最新版

OpenAI SDK

Python / Node.js 项目可以直接使用 OpenAI-compatible Base URL。最关键的是填对 base_url / baseURL。

Python Node.js curl
查看示例

Endpoint Map

端点速查

很多接入失败不是 Key 错，而是把“根地址”“/v1 Base URL”“完整接口地址”混用了。先按这张表填，再看客户端自己的提示。

使用场景 应该填写 不要这样填 判断方法
Codex App / CLI https://ggb.gg 不要手动追加 /v1/chat/completions 配置里如果有 wire_api 或 provider 概念，优先用根地址。
CCSwitch https://ggb.gg 不要在“API 请求地址”里额外加 /v1 CCSwitch 会按工具类型生成请求路径，用户只填供应商根地址。
OpenAI Python / Node SDK https://ggb.gg/v1 不要填成 https://ggb.gg/v1/chat/completions 字段叫 base_url / baseURL 时，填到 /v1 为止。
curl Chat Completions https://ggb.gg/v1/chat/completions 不要只请求 https://ggb.gg curl 是直接打接口，所以要写完整路径。
Claude / Anthropic 兼容工具 通常是 https://ggb.gg 不要混用 OpenAI 的 /v1/chat/completions 如果后台生成了专用配置，以后台生成结果为准。
!
一句话记忆：工具类客户端通常填根地址；OpenAI SDK 的 Base URL 填 /v1；自己写 curl 请求时才写完整接口路径。

Basics

基础信息

公开文档只写稳定信息。模型、倍率、活动和套餐可能调整，最终以控制台实时显示为准。

服务地址

  • 控制台 / 后台：https://ggb.gg
  • CCSwitch / Codex Responses 端点：https://ggb.gg
  • OpenAI SDK / Chat Completions Base URL：https://ggb.gg/v1
  • Key 格式通常为：sk-xxxxxxxx
  • 如果客户端要求完整地址，一般填写 /v1/chat/completions。

充值与模型

  • 历史活动口径：注册赠送额度，充值比例和赠送活动以后台为准。
  • 模型 ID 必须逐字复制后台展示的名称，大小写、点号、短横线都不要改。
  • 不同模型和分组倍率不同，真实消耗以控制台记录为准。
  • 长上下文、工具调用、图片、文件会增加消耗。
!
Key 只给自己用：不要把完整 API Key 发到公开群、论坛、截图或给陌生人。如果怀疑泄露，请删除旧 Key 后重新创建。

Screenshots

图文接入流程

下面的截图来自 GGB 控制台和 CCSwitch，已做公开站脱敏处理。用户照着箭头找按钮，少看大段文字。

1

进入「API 密钥」，点击创建密钥

左侧选择「API 密钥」。如果当前还没有 Key，可以点右上角或空状态里的「创建密钥」。页面上方会显示当前默认 API 端点：https://ggb.gg。

GGB API 密钥页面，创建密钥入口
2

选择你要使用的模型分组

创建 Key 时，名称建议写成用途，例如 codex-main、ccswitch。分组请按自己要用的模型池选择，倍率和可用模型以后台显示为准。

创建 API 密钥时选择模型分组
3

在 CCSwitch 里添加 GGB 供应商

打开 CCSwitch，点击右上角加号添加供应商。供应商名称可以写 ggb，API 请求地址填写 https://ggb.gg，不要额外加 /v1。

CCSwitch 供应商列表和添加按钮
4

填入 Key 和 API 请求地址

把刚创建的 Key 粘贴到 API Key；API 请求地址填写 https://ggb.gg。填好后保存并测试，成功后在 CCSwitch 中启用该供应商。

CCSwitch 添加供应商，填写 API Key 和 https://ggb.gg

Config Builder

配置生成器

所有生成逻辑都在浏览器本地完成，不会上传你的 Key。生成后按对应客户端要求写入配置文件并重启。

这里只在本页生成配置，不会发送到服务器。

模型名必须以后台可用模型为准。

CCSwitch / Codex 通常用根地址；Python / Node SDK 选择后会自动使用 /v1。

Codex

Codex 接入

不同 Codex 版本的配置项可能变化。这里给的是 OpenAI-compatible 网关常用模板；如果控制台生成配置不同，优先用控制台。

Windows 常见路径

  • 按 Win + R 输入 %USERPROFILE%\.codex。
  • 常见文件：config.toml 和 auth.json。
  • 注意不要保存成 config.toml.txt。
  • 修改后重启 Codex App / CLI / IDE 插件。

先跑一个最小测试

  • 先用后台展示的推荐模型。
  • 先问一个短问题，不要一上来跑大任务。
  • 如果失败，先看错误码，再检查 Key、Base URL、模型名。
config.toml 
model = "替换为后台显示的模型名"
model_provider = "ggb"

[model_providers.ggb]
name = "GGB"
base_url = "https://ggb.gg"
wire_api = "chat"
auth.json 
{
  "OPENAI_API_KEY": "sk-xxxxxxxx"
}

Codex Tips

Codex 专项避坑

Codex 比普通聊天工具更容易触发长上下文、工具调用和文件读取，所以接入时要先小步验证，再跑真实任务。

先问短问题

新 Key 第一次使用时，先问“只回复 ok”。能返回后再让 Codex 改代码、跑命令、读大文件。

改完配置要重启

Codex App、CLI、IDE 插件可能会缓存 provider 配置。修改 Key、Base URL 或模型名后，请完整退出再打开。

不要混用协议

Codex / CCSwitch 通常走根地址；OpenAI SDK 示例走 /v1。把两种配置混在一起，最容易出现 404 或请求格式错误。

长任务会更耗

长上下文、工具调用、图片和文件都会增加消耗。连续调试很久后，可以让 Codex 总结当前状态，再开新会话继续。

压缩当前 Codex 会话的提示词 
请把当前任务压缩成一份可交接摘要，包含：已完成事项、关键文件路径、当前配置、仍未解决的问题、下一步建议、需要避免的坑。不要输出完整 API Key。

SDK

OpenAI SDK 示例

适合开发者、脚本、后端服务。不要把 Key 写死进公开仓库，生产环境请用环境变量。

Python

python 
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxx",
    base_url="https://ggb.gg/v1",
)

resp = client.chat.completions.create(
    model="替换为后台显示的模型名",
    messages=[{"role": "user", "content": "你好，简单介绍一下你自己。"}],
)

print(resp.choices[0].message.content)

Node.js

javascript 
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-xxxxxxxx",
  baseURL: "https://ggb.gg/v1",
});

const resp = await client.chat.completions.create({
  model: "替换为后台显示的模型名",
  messages: [{ role: "user", content: "你好，简单介绍一下你自己。" }],
});

console.log(resp.choices[0].message.content);

API Quick Reference

API 速查

给开发者和客服排查用。先用模型列表验证 Key 和网络，再用最小聊天请求验证模型名与分组。

查看模型列表

GET /v1/models 
curl https://ggb.gg/v1/models \
  -H "Authorization: Bearer sk-xxxxxxxx"

最小聊天请求

POST /v1/chat/completions 
curl https://ggb.gg/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "替换为后台显示的模型名",
    "messages": [
      { "role": "user", "content": "只回复 ok" }
    ]
  }'
1. 先测 /models确认 Key、网络、网关可用。
2. 再测短聊天确认模型名和分组可用。
3. 再接客户端把通过验证的值填回 Codex / SDK。
4. 最后跑长任务避免一上来消耗大量上下文。

Other Clients

其他客户端接入

不同客户端字段名不同，但核心永远是三件事：Key、Base URL、模型名。能用后台自动生成配置就先用后台。

Claude Code / Claude 插件

如果使用 Anthropic 兼容路径，常见填写方式是根地址而不是 /v1。不要把 OpenAI 兼容配置和 Anthropic 兼容配置混用。

powershell 
$env:ANTHROPIC_BASE_URL="https://ggb.gg"
$env:ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxx"
claude

OpenCode / OpenClaw / IDE 插件

如果客户端支持 OpenAI-compatible provider，先看它要求的是 Responses 根地址还是 Chat Completions 的 /v1 地址：CCSwitch / Codex 通常填 https://ggb.gg，OpenAI SDK 通常填 https://ggb.gg/v1。

  • 字段叫 baseUrl / base_url / api_base 时填 Base URL。
  • 字段叫 endpoint 或完整接口地址时，按客户端说明填到 /chat/completions。
  • 请求被拒绝时，优先检查客户端实际发出的 URL 和模型名。

Client Matrix

客户端接入矩阵

客户问“这个工具能不能用”时，可以先看这张表。字段名可能随客户端版本变化，但 Key、Base URL、模型名这三件事不变。

客户端 推荐入口 Base URL 最常见错误
Codex 配置生成器或 CCSwitch https://ggb.gg 改完配置没有重启，或把 SDK 的 /v1 示例复制到 Codex。
CCSwitch 一键导入链接 / 手动添加 Provider https://ggb.gg API 请求地址多写了 /v1，导致客户端再拼接路径时异常。
OpenAI Python / Node SDK SDK 示例代码 https://ggb.gg/v1 把 Base URL 写成完整接口地址，或把 Key 写死进公开仓库。
Claude Code / Claude 插件 Anthropic 兼容配置 通常 https://ggb.gg 混用 OpenAI-compatible 与 Anthropic-compatible 的字段。
OpenCode / OpenClaw / IDE 插件 OpenAI-compatible Provider 按客户端要求选择根地址或 /v1 字段名相似但含义不同，需要确认是 Base URL 还是完整 endpoint。

Troubleshooting

常见错误

先看错误码，再对照 Key、URL、模型名、余额和客户端协议。不要盲目重装工具。

401

Key 不正确或未携带。检查是否复制完整、是否多了空格、是否写成了旧 Key。确认 Header 是 Authorization: Bearer sk-...。

403

权限、分组或客户端请求被拒绝。检查 Key 是否绑定了可用分组、模型是否在可用范围内；如果是某个客户端单独失败，请对照后台生成配置。

404

URL 填错。最常见是漏了 /v1、把 /v1 写成 /V1，或把 Base URL 和完整接口地址混用。

429

频率或额度限制。稍后重试，或检查当前模型/分组是否有 RPM、日限额、周限额、月限额。

502 / 503

上游或渠道暂时不可用。换一个可用模型或稍后重试。如果持续出现，联系售后时带上时间、模型名、客户端和请求 ID。

MODEL

模型不存在或拼写不一致。模型 ID 必须逐字复制后台显示内容，大小写、点号、短横线都不能擅自改。

Model Groups

模型分组与倍率怎么选

分组可以理解成一组可用模型和渠道策略。公开文档只解释选择方法，具体模型、倍率、活动以 GGB 控制台实时显示为准。

新手先选推荐分组

刚接入时不要追求“看起来最强”的模型池。先用后台推荐或客服建议的分组跑通，再根据速度、稳定性和价格调整。

倍率不是唯一标准

倍率低不一定适合所有任务，稳定性、可用模型、并发限制和工具支持也要一起看。真实扣费以控制台消费记录为准。

模型名必须照抄

模型 ID 的大小写、点号、短横线都不能自己改。出现 model not found 时，第一步就是回控制台复制模型名。

按用途拆 Key

Codex、SDK、团队成员和测试脚本尽量使用不同 Key。后续限额、排查、删除都更清楚。

!
推荐话术：“先用推荐分组跑通，再根据任务类型换模型。不要只看倍率，也不要自己猜模型名。”

Checklist

接入前检查清单

这块适合直接发给客户。让客户按顺序核对，比在群里来回问“截图看看”快很多。

1
Key 已创建并保存

确认 Key 没有少复制字符，没有多空格，也没有把旧 Key 填进去。

2
端点按客户端填写

Codex / CCSwitch 用 https://ggb.gg，SDK Base URL 用 https://ggb.gg/v1。

3
模型名逐字复制

不要手打，不要把别家文档里的模型名直接照搬到 GGB。

4
分组和余额可用

确认 Key 绑定的分组能访问该模型，账号余额或赠送额度仍然可用。

5
先跑最小请求

先问“只回复 ok”，成功后再跑长上下文、图片、工具调用或自动化任务。

6
求助前遮住 Key

截图、录屏、发群前必须遮住完整 API Key，只保留前后几位即可。

FAQ

常见问题 FAQ

FAQ 不追求写全，先覆盖最容易让客户卡住的几类问题。后续可以根据售后高频问题继续加。

URL

为什么有时填根地址，有时填 /v1？因为不同客户端要的不是同一个层级。工具类客户端通常自己拼路径，所以填根地址；OpenAI SDK 的 Base URL 按惯例填到 /v1。

KEY

Key 创建后还能再次看到完整内容吗？通常不建议依赖再次查看。创建后请立即保存；如果忘了或怀疑泄露，删除旧 Key 后重新创建。

MODEL

模型名在哪里看？以 GGB 控制台展示为准。不要从别家文档、聊天记录或旧截图里复制模型名。

COST

为什么 Codex 用起来消耗比聊天高？Codex 会带上下文、文件摘要、工具调用和历史记录。长任务前先小请求测试，连续工作很久后建议压缩历史再开新会话。

APP

配置改了还是不生效？先完整退出并重启客户端；如果还不行，检查是否改错了配置文件，或者是否同时存在多个 provider 配置。

SUP

联系售后要发什么？发账号、客户端、Base URL、模型名、错误码、发生时间和 Key 前后几位。不要发送完整 Key。

Announcements

更新公告

这里先放公开站的公告模板，后续可以把模型变化、维护窗口、活动变化写在这里，减少群里重复解释。

2026-06-27：公开文档站上线准备

新增 Codex、CCSwitch、OpenAI SDK、Claude Code、OpenCode 接入说明，并加入本地配置生成器。

维护公告模板

如果某个模型池维护，请写清楚影响范围、开始时间、预计恢复时间、临时替代模型和售后联系入口。

Support

联系售后时请提供

信息越完整，定位越快。请不要发送完整 API Key，最多提供前后几位用于识别。

账号邮箱 / 用户名 API Key 前后 4 位 使用的客户端 Base URL 模型名 错误码与错误文本 发生时间 是否能在控制台看到余额 截图请遮住完整 Key

Security

安全提醒

公开文档最重要的不是“写得多”，而是帮用户少犯会损失额度的错。

不要泄露 Key

Key 等同于余额入口。不要发群、不要发论坛、不要贴到公开 GitHub 仓库。截图时必须遮住完整 Key。

生产环境用环境变量

脚本和服务里不要硬编码 Key。建议使用环境变量、服务器 Secret 管理或 CI Secret。

按用途拆 Key

Codex、OpenCode、脚本、团队成员最好分开创建 Key。某个用途出问题时可以单独删除。

先小请求测试

新配置先跑短问题，确认模型、余额和扣费正常后，再跑长上下文或自动化任务。