通过Sub2API，让国内个人也能用上Grok等国外大模型

AI这碗饭，作为一个中登学习，每天都在被现实教育，这年头互联网 AI学习，真的是一天一个样。

Cloud Code还没整明白，又感觉OpenCode也不错，这里openclaw才研究出来了点眉目，这里hermes又来了，大模型更是天天换榜单，早上还在看A，晚上已经变成B了。心态是崩溃的，也不知道到底学什么才对，就像买这个LLM也是一样的。

话说回来，年初在MiniMax和智谱之间二选一的时候，我选了MiniMax。现在回头看有点后悔。现在感觉智谱更顺手。

所以那句老话又对了：

> 大模型年付，真的要谨慎。
>
> 这行变化太快，“长期主义”很容易变成“长期交学费”。

今天撸了这一篇，不是教大家怎么冲榜，也不是劝你弃坑国内模型。  
我只想把最近踩过的坑、摸着石头过河总结出来，给和我一样的小白一条小路，也给未来的自己留一份可翻的操作笔记。

毕竟，作为一个中登，每天这样学，真的不容易。

## 一、关于大模型：学不完的工具，看不完的榜单

现在对AI的真实体感就八个字：

> 学不完的工具，看不完的大模型。

我最近其实在考虑替换MiniMax，换到智谱GLM。结果还没上手就发现智谱这coding plan，完全有小米那味的饥饿营销：
* 每天10开抢
* 结果还是抢不到
* 套餐价格也不算便宜

抢完一轮，人已经有点小丑了。只能拿opencode go试了下，感觉真不错就是token不够用啊。

就在为抢GLM发愁的时候，榜单上这几天马圣的Grok 4.5非常给力。于是我突然想通了一件事：

> 为啥非得天天蹲着国内这些大模型看？
>
> 国外更好用的模型，为什么个人不能正儿八经用上？

答案很残酷：不是不能用，是门槛卡人。

### 门槛 1：支付

Grok、Cursor这类服务，国人支付经常因为某种神秘力直接被拒。  
想自己正规买，很多时候就是一脚油门踩空。

### 门槛 2：访问

就算买到了，国内运营商网络也访问不了官方和API地址。  
还是那个“神秘力量”，买得着，用不顺；用不顺，就白买。

所以也别怪我现在才把这些坑写出来，因为我也是最近才搞明白，原来还有中转代理这一说。  
逼近中登的学习节奏，本来就是：先交学费，再写总结。

## 二、关于大模型的购买：虚拟卡 vs 某鱼代充

国外大模型买不顺，本质上就两条路。

### 路线 A：注册虚拟信用卡自己付

听起来很美，实际体验是：

* 注册确实不难
* 充值才是大问题
* 不是想象中支付宝/微信一键到账
* 经常要各种转账、各种手续费
* 就算充上了，支付时还可能再扣一层

举个真实体感：

> SuperGrok 标价 30 刀/月
> 虚拟卡绕一圈下来，可能要到35 刀左右

贵就贵了，关键是还折腾。  
对个人用户来说，不够香。

### 路线 B：代付 / 代充

知乎上一搜，很多“教程帖”最后都通向代充推广。  
代充最大的问题就两个字：信任。

* 怕不稳定
* 怕跑路
* 怕把账号信息交出去

后来我突然想起来——号称中国最大黑市的某鱼。  
上去一搜SuperGrok，瞬间豁然开朗。

### 我个人的选择

我个人的SuperGrok，是通过某鱼代购充值完成的：

* 不用提供自己的账号信息
* 到账速度也快
* 比虚拟卡省心

> 个人推荐：如果只是个人用，某鱼代充比虚拟卡更省心。
>
> 当然，平台和卖家选择要自己擦亮眼睛，风险自负。

## 三、关于使用：买到了，国内怎么正常访问？

大模型成功购买后，最后一个问题来了：

> 国内如何正常访问和使用？

这里就需要反代 / 中转。

作为一个搞IT运维的人，我第一反应是：Nginx 反代一下不就完了？  
结果一看资料，并没有那么简单。

现在已经有不少成熟的开源中转方案，比如：

* CLI Proxy API
* Sub2API
* New API 等组合方案

我试过CLI Proxy API + New API的组合，最后还是选了Sub2API。

原因很简单，因为我是个人使用，不对外也不商用。同时Sub2API主要部署一个服务即可。而其他方案需要同时部署CLI Proxy API和sub2api维护和管理的成本也不一样，另外对于VPS的配置要求也就不一样。

## 四、Sub2API 是什么？为什么适合个人

[Sub2API](https://github.com/Wei-Shaw/sub2api) 是一个开源的 AI API 网关 / 中转平台，可以把 Claude、OpenAI、Gemini、Grok 等订阅能力统一接入，方便个人或小团队使用。

它适合我的点主要有：

1. Docker Compose 一键部署，不用从零拼一堆组件
2. 自带管理后台，配置相对直观
3. 个人自用时，维护成本明显低于多组件组合
4. 后面再挂 Nginx 反代，就能在国内更稳地访问

## 五、Sub2API 安装：官方 Docker Compose 一键部署

官方推荐个人/服务器快速上手的方式，就是 **Docker Compose 一键部署**。

### 1\. 前置条件

* 一台能访问外网的Linux VPS（建议海外节点）
* 已安装：

* Docker 20.10+
  * Docker Compose v2+
* 服务器能拉 GitHub / Docker 镜像

检查一下：

```bash
docker -v
docker compose version
```

### 2\. 一键准备部署文件（官方脚本）

```bash
# 创建部署目录
mkdir -p sub2api-deploy \&\& cd sub2api-deploy

# 下载并运行官方部署准备脚本
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash
```

这个脚本会帮你做这些事：

* 下载 `docker-compose.local.yml`（本地保存为 compose 配置）
* 下载 `.env.example`
* 自动生成安全凭证：

* `JWT\_SECRET`
  * `TOTP\_ENCRYPTION\_KEY`
  * `POSTGRES\_PASSWORD`
* 创建 `.env`,这里建议把里面的8080改为其他的一个端口，防止被恶意扫描
* 创建数据目录（方便备份迁移）
* 把生成的凭证打印出来，建议立刻抄下来

### 3\. 启动服务

```bash
# 启动
docker compose -f docker-compose.local.yml up -d

# 看日志
docker compose -f docker-compose.local.yml logs -f sub2api
```

如果管理员密码是自动生成的，可以在日志里找：

```bash
docker compose -f docker-compose.local.yml logs sub2api | grep "admin password"
```

### 4\. 访问后台

浏览器打开：

```text
http://你的服务器IP:8080
```

默认端口是 `8080`。  
如果只是自己先测通，这一步就够了；如果要长期用，建议继续往下做Nginx 反代 + 域名。

### 5\. 常用运维命令

```bash
# 查看状态
docker compose -f docker-compose.local.yml ps

# 重启
docker compose -f docker-compose.local.yml restart

# 升级
docker compose -f docker-compose.local.yml pull
docker compose -f docker-compose.local.yml up -d

# 停止
docker compose -f docker-compose.local.yml down
```
其他的部署方式可以看官方的文档。

## 六、Nginx 反向代理 Sub2API

Sub2API 默认跑在 `8080`，如果改过8080就按自己修改端口来。  
个人长期使用时，我更建议：

1. 用 Nginx 反代到 80/443
2. 绑定自己的域名
3. 防火墙只放行必要端口
4. 最好再上 HTTPS

### 1\. 先开放 HTTP 权限

如果你用的是 `ufw`：

```bash
# 允许 HTTP / HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# 如果暂时还要直接访问 8080 调试，可以临时开
# sudo ufw allow 8080/tcp

sudo ufw reload
sudo ufw status
```

如果是云厂商安全组（阿里云 / 腾讯云 / AWS 等），也记得同步放行：

* **入站 TCP 80**
* **入站 TCP 443**
* 生产环境建议**不要长期裸奔 8080 到公网**

> 小建议：  
> Sub2API 本身可以继续监听 `127.0.0.1:8080` 或内网端口，  
> 对外只暴露 Nginx 的 80/443，会更干净。

### 2\. 安装 Nginx（如未安装）

Debian / Ubuntu：

```bash
sudo apt update
sudo apt install -y nginx
sudo systemctl enable nginx
sudo systemctl start nginx
```

### 3\. Nginx 反代配置示例

新建站点配置，例如：

```bash
sudo nano /etc/nginx/sites-available/sub2api.conf
```

写入下面这段（把域名改成你自己的）：

```nginx
server {
    listen 80;
    server\_name api.example.com;   # 改成你的域名

# 日志（可选）
    access\_log /var/log/nginx/sub2api.access.log;
    error\_log  /var/log/nginx/sub2api.error.log;

# 上传/请求体大小，按需要调整
    client\_max\_body\_size 50m;

location / {
        proxy\_pass http://127.0.0.1:8080;

proxy\_http\_version 1.1;

# WebSocket / 流式输出常见头
        proxy\_set\_header Upgrade $http\_upgrade;
        proxy\_set\_header Connection "upgrade";

proxy\_set\_header Host $host;
        proxy\_set\_header X-Real-IP $remote\_addr;
        proxy\_set\_header X-Forwarded-For $proxy\_add\_x\_forwarded\_for;
        proxy\_set\_header X-Forwarded-Proto $scheme;

# 大模型流式响应很关键：关掉缓冲
        proxy\_buffering off;
        proxy\_cache off;
        chunked\_transfer\_encoding on;

# 超时放宽，避免长回复被掐断
        proxy\_connect\_timeout 60s;
        proxy\_send\_timeout 3600s;
        proxy\_read\_timeout 3600s;
        send\_timeout 3600s;
    }
}
```
**Nginx 反向代理注意事项**:
如果你用 Nginx，并且要支持 Codex CLI 或依赖粘性会话的多账号调度，需要在 http block 里加：

underscores_in_headers on;

原因是 Nginx 默认会丢弃带下划线的 header，例如 session_id。sub2api README 明确提醒：这会破坏多账号场景下的 sticky session routing。

启用配置：

```bash
sudo ln -s /etc/nginx/sites-available/sub2api.conf /etc/nginx/sites-enabled/sub2api.conf
sudo nginx -t
sudo systemctl reload nginx
```

### 4\. 建议再上 HTTPS（可选但强烈建议）

如果你已经有域名解析到这台机器，可以用 Let's Encrypt：

```bash
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d api.example.com
```

签完以后，访问就变成：

```text
https://api.example.com
```

### 5\. 一个更稳的安全建议

如果 Sub2API 只给自己用，可以考虑：

* Nginx 层加 Basic Auth
* 或者只允许你家 IP / 公司 IP 访问
* 或者前面再挂一层 Cloudflare / 自己的入口

个人自用场景里，能少暴露一点就少暴露一点。但记得需要把你的中转站点api在Cloudflare防火墙里设置一个规则进行开放，否则会大概率被Cloudflare拦截导致中转访问慢或者失败，具体如何配置Cloudflare增加防火墙规则自行查找哈。

## 七、Sub2API 反代后的使用：OpenCode 接 SuperGrok 的 Grok 4.5

前面把 Sub2API 和 Nginx 都架好了，只完成了一半。  
真正开始干活，还得把客户端接上。

我这边日常用的是OpenCode和OpenClaw，我这里已OpenCode为例。
目标很直接：

> 不走官方 xAI 直连，  
> 而是让 OpenCode 通过我自己的 Sub2API 反代，  
> 用上 SuperGrok 订阅里的Grok 4.5。

一句话讲清链路：

```text
OpenCode
  → 你的反代域名（Nginx）
    → Sub2API（本地 8080）
      → 上游 SuperGrok / xAI 能力
```

### 1\. 先在 Sub2API 后台准备 3 样东西

登录你的 Sub2API 管理后台，确认这三件齐了：

1. **已经接入 Grok 上游账号**  
（SuperGrok / Grok 相关账号导入成功，状态正常）
2. **有一个绑定 Grok 平台的 Group / 分组**  
（API Key 最终要挂在这个分组下）
3. **生成一把自己的 API Key**  
（后面填进 OpenCode 的就是它，不是 xAI 官方 console 那把）

记下来两个值：

- 反代 Base URL：https://api.example.com/v1 ，注意末尾带/v1。 API
   
 - Key：sk-xxxx...，Sub2API 后台生成的 Key。

Sub2API具体的使用方法我就不多说了，自行查询一下，总之Sub2API的后台配置很简单不复杂。

> 本地还没上域名时，也可以先用：  
> `http://127.0.0.1:8080/v1`  
> 但长期还是建议域名 + HTTPS。

### 2\. 先用 curl 自测

很多“OpenCode 连不上”，其实是反代或 Key 本身就没通。

```bash
# 1）看模型列表
curl -sS https://api.example.com/v1/models \\
  -H "Authorization: Bearer sk-xxxx"

# 2）试一次 chat completions（把模型名按你后台实际可用的改）
curl -sS https://api.example.com/v1/chat/completions \\
  -H "Authorization: Bearer sk-xxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "grok-4.5",
    "messages": \[{"role":"user","content":"ping，回我一句 ok"}],
    "stream": false
  }'
```

看到的结果：

* `/v1/models` 能返回模型列表
* `/v1/chat/completions` 能正常回内容，而不是 401 / 502 / timeout

Sub2API 对 Grok 常见会露出类似这些 model id（以你后台实际列表为准）：

* `grok-4.5`
* `grok-4.5-latest`
* `grok`
* `grok-latest`

我自己写配置时，优先用后台 `/v1/models` 真实返回的那个 id，别凭感觉瞎填。

### 3\. 在 OpenCode 里添加“第三方反代”凭证

OpenCode 官方对内置 xAI 有三种登录：

* SuperGrok 浏览器 OAuth
* SuperGrok 无头 device-code
* xAI Console 的官方 API Key

但我们现在要走的是自己的 Sub2API 中转，所以不要选内置 `xAI` 那套直连。  
正确姿势是：Custom provider / Other（OpenAI-compatible）。

#### 步骤 A：`/connect` 添加凭证

在 OpenCode 里执行：

```txt
/connect
```

然后：

1. 往下滚，选 **Other**
2. Provider ID 建议填：`sub2api`  
（这个 ID 后面会写进 `opencode.json`，自己好记就行）
3. API Key 粘贴 Sub2API 后台生成的那把 `sk-xxxx`

这一步只是存密钥。  
OpenCode 会提示你：还需要去 `opencode.json` 里把这个自定义 provider 配完整。

#### 步骤 B：写 `opencode.json`

推荐先写全局配置（本机所有项目都能用）：

```bash
mkdir -p \~/.config/opencode
nano \~/.config/opencode/opencode.json
```

也可以写到某个项目根目录的 `opencode.json`（只对当前项目生效）。

最小可用配置如下：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "sub2api/grok-4.5",
  "provider": {
    "sub2api": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Sub2API (Grok)",
      "options": {
        "baseURL": "https://api.example.com/v1"
      },
      "models": {
        "grok-4.5": {
          "name": "Grok 4.5 (via Sub2API)"
        },
        "grok-4.5-latest": {
          "name": "Grok 4.5 Latest (via Sub2API)"
        }
      }
    }
  }
}
```

几个关键点，中登一定要对齐：

- `provider` 下的 key必须和 `/connect` 时填的 Provider ID 一致
 - `myproxy`，直接对不上 `npm`固定用 `@ai-sdk/openai-compatible`
 - `/v1/chat/completions` 兼容接口 `options.baseURL`，`https://你的域名/v1`
 - `/v1`、多写一截路径，都会 404 `models` 里的 key，必须是上游真实 model id显示名随便起
 - `默认模型`provider\_id/model\_id`，例如 sub2api/grok-4.5

> 如果你更喜欢把 Key 直接写进配置，也可以：
>
> ```json
> "options": {
>   "baseURL": "https://api.example.com/v1",
>   "apiKey": "sk-xxxx"
> }
> ```
>
> 但我更建议：Key 走 `/connect` 存本地凭证，配置文件里只留 `baseURL`。  
> 这样以后分享 `opencode.json` 时，不会把密钥一起交出去。

#### 步骤 C：选模型并开干

重启 OpenCode 后：

```txt
/models
```

你应该能看到类似：

* `My Sub2API (Grok)` / `Grok 4.5 (via Sub2API)`

选中它，然后随便问一句：

```txt
你现在是谁？用一句话说明你的模型名。
```

通了，就说明： OpenCode 已经不再直连官方 xAI，而是走你自己的 Sub2API 反代在干活。

### 4\. 一版“复制就能改”的完整示例

假设：

* 域名：`https://grok.fungj.com`
* Provider ID：`sub2api`
* 默认模型：`grok-4.5`

那全局配置可以直接长这样：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "sub2api/grok-4.5",
  "small\_model": "sub2api/grok-4.5",
  "provider": {
    "sub2api": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Sub2API Reverse Proxy",
      "options": {
        "baseURL": "https://grok.fungj.com/v1",
        "timeout": 600000
      },
      "models": {
        "grok-4.5": {
          "name": "Grok 4.5",
          "limit": {
            "context": 256000,
            "output": 65536
          }
        },
        "grok-4.5-latest": {
          "name": "Grok 4.5 Latest"
        }
      }
    }
  }
}
```

说明：

* `timeout` 拉大一点，长上下文 coding 时不容易被客户端先掐断
* `limit` 不是必须，但有助于 OpenCode 判断上下文余量
* 具体 context 上限以后台和上游实际能力为准，上面只是个人常用写法

### 5\. 常见翻车点（我已经替你踩过一轮）

#### 1）Provider ID 对不上

`/connect` 存的是 `sub2api`，配置文件却写成 `my-grok`。  
表现：有 Key，但 `/models` 里看不到你的自定义模型。

#### 2）baseURL 少了 `/v1`

错误：

```text
https://api.example.com
```

正确：

```text
https://api.example.com/v1
```

OpenCode 的 OpenAI-compatible provider，会在这个 base 后面拼 `/chat/completions`、`/models`。

#### 3）模型名写飘了

后台实际是 `grok-4.5`，你写成 `grok-4.5-super` / `Grok-4.5`。  
显示名可以好看，请求里的 model id 必须严格匹配。

#### 4）Nginx 缓冲没关，流式半死不活

如果聊天能回，但流式断断续续、长时间卡住，回头检查 Nginx：

* `proxy\_buffering off;`
* `proxy\_read\_timeout` / `proxy\_send\_timeout` 足够大

#### 5）把官方 xAI 直连和 Sub2API 中转混了

* 想直连官方：用 OpenCode 内置 `xAI`（OAuth / device-code / 官方 API Key）
* 想走自己反代：用 **Other + `@ai-sdk/openai-compatible` + 你的域名**

两条路别混着配，否则你都不知道请求到底从哪出去的。

#### 6）凭证排查命令

```bash
opencode auth list
```

先确认 `sub2api` 这套凭证还在。  
再核对 `\~/.config/opencode/opencode.json` 或项目内 `opencode.json`。

### 6\. 这套接法，适合什么客户端？

只要客户端支持 OpenAI Compatible API，基本都能套同一套：

对个人用户来说，Sub2API 的舒服点就在这儿：上游账号你自己管，客户端只认你的反代地址和一把 Key。

## 八、部署完成后，你可以怎么用

通了之后，典型用法大概是：

1. 登录 Sub2API 管理后台
2. 接入你已经买到的 Grok / 其他模型订阅或上游能力
3. 生成自己的 API Key
4. 在 OpenCode / 其他客户端里，把 Base URL 指到你的反代域名
5. 之后国内请求先打到你的 Nginx，再由 Sub2API 去访问上游

对个人来说，价值就在这：支付问题靠靠谱代充解决，访问问题靠 Sub2API + Nginx 解决，日常使用靠 OpenCode 自定义 provider 解决。

这三关过了，国外模型才算真正“能用”，而不是“看得到、买得到、用不成”。

最后再补一句中登碎碎念：

> AI 这行变化太快，今天的最优解，可能下个月就过气。  
> 所以与其迷信某一个“年付神卡”，不如把可迁移、可替换、可自建的能力练出来。

这篇就当我摸着石头过河后的一份笔记。  
如果你也是被国内抢购、支付被拒、API 访问不通折磨过的人，希望这条小路能帮你少走几步弯路。

有坑欢迎评论区继续补充。  
毕竟中登学 AI...累就一个字。

### 参考

* Sub2API 官方仓库：https://github.com/Wei-Shaw/sub2api
* 官方 Docker 一键部署脚本：https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh
* 官方部署说明：https://github.com/Wei-Shaw/sub2api/blob/main/deploy/README.md

AI这碗饭，作为一个中登学习，每天都在被现实教育，这年头互联网 AI学习，真的是一天一个样。

话说回来，年初在MiniMax和智谱之间二选一的时候，我选了MiniMax。现在回头看有点后悔。现在感觉智谱更顺手。

所以那句老话又对了：

大模型年付，真的要谨慎。
这行变化太快，“长期主义”很容易变成“长期交学费”。

今天撸了这一篇，不是教大家怎么冲榜，也不是劝你弃坑国内模型。
我只想把最近踩过的坑、摸着石头过河总结出来，给和我一样的小白一条小路，也给未来的自己留一份可翻的操作笔记。

毕竟，作为一个中登，每天这样学，真的不容易。

一、关于大模型：学不完的工具，看不完的榜单

现在对AI的真实体感就八个字：

学不完的工具，看不完的大模型。

我最近其实在考虑替换MiniMax，换到智谱GLM。结果还没上手就发现智谱这coding plan，完全有小米那味的饥饿营销：

每天10开抢
结果还是抢不到
套餐价格也不算便宜

抢完一轮，人已经有点小丑了。只能拿opencode go试了下，感觉真不错就是token不够用啊。

就在为抢GLM发愁的时候，榜单上这几天马圣的Grok 4.5非常给力。于是我突然想通了一件事：

为啥非得天天蹲着国内这些大模型看？
国外更好用的模型，为什么个人不能正儿八经用上？

答案很残酷：不是不能用，是门槛卡人。

门槛 1：支付

Grok、Cursor这类服务，国人支付经常因为某种神秘力直接被拒。
想自己正规买，很多时候就是一脚油门踩空。

门槛 2：访问

就算买到了，国内运营商网络也访问不了官方和API地址。
还是那个“神秘力量”，买得着，用不顺；用不顺，就白买。

所以也别怪我现在才把这些坑写出来，因为我也是最近才搞明白，原来还有中转代理这一说。
逼近中登的学习节奏，本来就是：先交学费，再写总结。

二、关于大模型的购买：虚拟卡 vs 某鱼代充

国外大模型买不顺，本质上就两条路。

路线 A：注册虚拟信用卡自己付

听起来很美，实际体验是：

注册确实不难
充值才是大问题
不是想象中支付宝/微信一键到账
经常要各种转账、各种手续费
就算充上了，支付时还可能再扣一层

举个真实体感：

SuperGrok 标价 30 刀/月
虚拟卡绕一圈下来，可能要到35 刀左右

贵就贵了，关键是还折腾。
对个人用户来说，不够香。

路线 B：代付 / 代充

知乎上一搜，很多“教程帖”最后都通向代充推广。
代充最大的问题就两个字：信任。

怕不稳定
怕跑路
怕把账号信息交出去

后来我突然想起来——号称中国最大黑市的某鱼。
上去一搜SuperGrok，瞬间豁然开朗。

我个人的选择

我个人的SuperGrok，是通过某鱼代购充值完成的：

不用提供自己的账号信息
到账速度也快
比虚拟卡省心

个人推荐：如果只是个人用，某鱼代充比虚拟卡更省心。
当然，平台和卖家选择要自己擦亮眼睛，风险自负。

三、关于使用：买到了，国内怎么正常访问？

大模型成功购买后，最后一个问题来了：

国内如何正常访问和使用？

这里就需要反代 / 中转。

作为一个搞IT运维的人，我第一反应是：Nginx 反代一下不就完了？
结果一看资料，并没有那么简单。

现在已经有不少成熟的开源中转方案，比如：

CLI Proxy API
Sub2API
New API 等组合方案

我试过CLI Proxy API + New API的组合，最后还是选了Sub2API。

四、Sub2API 是什么？为什么适合个人

Sub2API 是一个开源的 AI API 网关 / 中转平台，可以把 Claude、OpenAI、Gemini、Grok 等订阅能力统一接入，方便个人或小团队使用。

它适合我的点主要有：

Docker Compose 一键部署，不用从零拼一堆组件
自带管理后台，配置相对直观
个人自用时，维护成本明显低于多组件组合
后面再挂 Nginx 反代，就能在国内更稳地访问

五、Sub2API 安装：官方 Docker Compose 一键部署

官方推荐个人/服务器快速上手的方式，就是 Docker Compose 一键部署。

1. 前置条件

一台能访问外网的Linux VPS（建议海外节点）
已安装：
- Docker 20.10+
- Docker Compose v2+
服务器能拉 GitHub / Docker 镜像

检查一下：

docker -v
docker compose version

2. 一键准备部署文件（官方脚本）

# 创建部署目录
mkdir -p sub2api-deploy \&\& cd sub2api-deploy

# 下载并运行官方部署准备脚本
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

这个脚本会帮你做这些事：

下载 docker-compose.local.yml（本地保存为 compose 配置）
下载 .env.example
自动生成安全凭证：
- JWT\_SECRET
- TOTP\_ENCRYPTION\_KEY
- POSTGRES\_PASSWORD
创建 .env,这里建议把里面的8080改为其他的一个端口，防止被恶意扫描
创建数据目录（方便备份迁移）
把生成的凭证打印出来，建议立刻抄下来

3. 启动服务

# 启动
docker compose -f docker-compose.local.yml up -d

# 看日志
docker compose -f docker-compose.local.yml logs -f sub2api

如果管理员密码是自动生成的，可以在日志里找：

docker compose -f docker-compose.local.yml logs sub2api | grep "admin password"

4. 访问后台

浏览器打开：

http://你的服务器IP:8080

默认端口是 8080。
如果只是自己先测通，这一步就够了；如果要长期用，建议继续往下做Nginx 反代 + 域名。

5. 常用运维命令

# 查看状态
docker compose -f docker-compose.local.yml ps

# 重启
docker compose -f docker-compose.local.yml restart

# 升级
docker compose -f docker-compose.local.yml pull
docker compose -f docker-compose.local.yml up -d

# 停止
docker compose -f docker-compose.local.yml down

其他的部署方式可以看官方的文档。

六、Nginx 反向代理 Sub2API

Sub2API 默认跑在 8080，如果改过8080就按自己修改端口来。
个人长期使用时，我更建议：

用 Nginx 反代到 80/443
绑定自己的域名
防火墙只放行必要端口
最好再上 HTTPS

1. 先开放 HTTP 权限

如果你用的是 ufw：

# 允许 HTTP / HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# 如果暂时还要直接访问 8080 调试，可以临时开
# sudo ufw allow 8080/tcp

sudo ufw reload
sudo ufw status

如果是云厂商安全组（阿里云 / 腾讯云 / AWS 等），也记得同步放行：

入站 TCP 80
入站 TCP 443
生产环境建议不要长期裸奔 8080 到公网

小建议：
Sub2API 本身可以继续监听 127.0.0.1:8080 或内网端口，
对外只暴露 Nginx 的 80/443，会更干净。

2. 安装 Nginx（如未安装）

Debian / Ubuntu：

sudo apt update
sudo apt install -y nginx
sudo systemctl enable nginx
sudo systemctl start nginx

3. Nginx 反代配置示例

新建站点配置，例如：

sudo nano /etc/nginx/sites-available/sub2api.conf

写入下面这段（把域名改成你自己的）：

server {
    listen 80;
    server\_name api.example.com;   # 改成你的域名

    # 日志（可选）
    access\_log /var/log/nginx/sub2api.access.log;
    error\_log  /var/log/nginx/sub2api.error.log;

    # 上传/请求体大小，按需要调整
    client\_max\_body\_size 50m;

    location / {
        proxy\_pass http://127.0.0.1:8080;

        proxy\_http\_version 1.1;

        # WebSocket / 流式输出常见头
        proxy\_set\_header Upgrade $http\_upgrade;
        proxy\_set\_header Connection "upgrade";

        proxy\_set\_header Host $host;
        proxy\_set\_header X-Real-IP $remote\_addr;
        proxy\_set\_header X-Forwarded-For $proxy\_add\_x\_forwarded\_for;
        proxy\_set\_header X-Forwarded-Proto $scheme;

        # 大模型流式响应很关键：关掉缓冲
        proxy\_buffering off;
        proxy\_cache off;
        chunked\_transfer\_encoding on;

        # 超时放宽，避免长回复被掐断
        proxy\_connect\_timeout 60s;
        proxy\_send\_timeout 3600s;
        proxy\_read\_timeout 3600s;
        send\_timeout 3600s;
    }
}

Nginx 反向代理注意事项:
如果你用 Nginx，并且要支持 Codex CLI 或依赖粘性会话的多账号调度，需要在 http block 里加：

underscores_in_headers on;

原因是 Nginx 默认会丢弃带下划线的 header，例如 session_id。sub2api README 明确提醒：这会破坏多账号场景下的 sticky session routing。

启用配置：

sudo ln -s /etc/nginx/sites-available/sub2api.conf /etc/nginx/sites-enabled/sub2api.conf
sudo nginx -t
sudo systemctl reload nginx

4. 建议再上 HTTPS（可选但强烈建议）

如果你已经有域名解析到这台机器，可以用 Let's Encrypt：

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d api.example.com

签完以后，访问就变成：

https://api.example.com

5. 一个更稳的安全建议

如果 Sub2API 只给自己用，可以考虑：

Nginx 层加 Basic Auth
或者只允许你家 IP / 公司 IP 访问
或者前面再挂一层 Cloudflare / 自己的入口

七、Sub2API 反代后的使用：OpenCode 接 SuperGrok 的 Grok 4.5

前面把 Sub2API 和 Nginx 都架好了，只完成了一半。
真正开始干活，还得把客户端接上。

我这边日常用的是OpenCode和OpenClaw，我这里已OpenCode为例。
目标很直接：

不走官方 xAI 直连，
而是让 OpenCode 通过我自己的 Sub2API 反代，
用上 SuperGrok 订阅里的Grok 4.5。

一句话讲清链路：

OpenCode
  → 你的反代域名（Nginx）
    → Sub2API（本地 8080）
      → 上游 SuperGrok / xAI 能力

1. 先在 Sub2API 后台准备 3 样东西

登录你的 Sub2API 管理后台，确认这三件齐了：

已经接入 Grok 上游账号
（SuperGrok / Grok 相关账号导入成功，状态正常）
有一个绑定 Grok 平台的 Group / 分组
（API Key 最终要挂在这个分组下）
生成一把自己的 API Key
（后面填进 OpenCode 的就是它，不是 xAI 官方 console 那把）

记下来两个值：

反代 Base URL：https://api.example.com/v1 ，注意末尾带/v1。 API
Key：sk-xxxx...，Sub2API 后台生成的 Key。

Sub2API具体的使用方法我就不多说了，自行查询一下，总之Sub2API的后台配置很简单不复杂。

本地还没上域名时，也可以先用：
http://127.0.0.1:8080/v1
但长期还是建议域名 + HTTPS。

2. 先用 curl 自测

很多“OpenCode 连不上”，其实是反代或 Key 本身就没通。

# 1）看模型列表
curl -sS https://api.example.com/v1/models \\
  -H "Authorization: Bearer sk-xxxx"

# 2）试一次 chat completions（把模型名按你后台实际可用的改）
curl -sS https://api.example.com/v1/chat/completions \\
  -H "Authorization: Bearer sk-xxxx" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "grok-4.5",
    "messages": \[{"role":"user","content":"ping，回我一句 ok"}],
    "stream": false
  }'

看到的结果：

/v1/models 能返回模型列表
/v1/chat/completions 能正常回内容，而不是 401 / 502 / timeout

Sub2API 对 Grok 常见会露出类似这些 model id（以你后台实际列表为准）：

grok-4.5
grok-4.5-latest
grok
grok-latest

我自己写配置时，优先用后台 /v1/models 真实返回的那个 id，别凭感觉瞎填。

3. 在 OpenCode 里添加“第三方反代”凭证

OpenCode 官方对内置 xAI 有三种登录：

SuperGrok 浏览器 OAuth
SuperGrok 无头 device-code
xAI Console 的官方 API Key

但我们现在要走的是自己的 Sub2API 中转，所以不要选内置 xAI 那套直连。
正确姿势是：Custom provider / Other（OpenAI-compatible）。

步骤 A：`/connect` 添加凭证

在 OpenCode 里执行：

/connect

然后：

往下滚，选 Other
Provider ID 建议填：sub2api
（这个 ID 后面会写进 opencode.json，自己好记就行）
API Key 粘贴 Sub2API 后台生成的那把 sk-xxxx

这一步只是存密钥。
OpenCode 会提示你：还需要去 opencode.json 里把这个自定义 provider 配完整。

步骤 B：写 `opencode.json`

推荐先写全局配置（本机所有项目都能用）：

mkdir -p \~/.config/opencode
nano \~/.config/opencode/opencode.json

也可以写到某个项目根目录的 opencode.json（只对当前项目生效）。

最小可用配置如下：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "sub2api/grok-4.5",
  "provider": {
    "sub2api": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Sub2API (Grok)",
      "options": {
        "baseURL": "https://api.example.com/v1"
      },
      "models": {
        "grok-4.5": {
          "name": "Grok 4.5 (via Sub2API)"
        },
        "grok-4.5-latest": {
          "name": "Grok 4.5 Latest (via Sub2API)"
        }
      }
    }
  }
}

几个关键点，中登一定要对齐：

provider 下的 key必须和 /connect 时填的 Provider ID 一致
myproxy，直接对不上 npm固定用 @ai-sdk/openai-compatible
/v1/chat/completions 兼容接口 options.baseURL，https://你的域名/v1
/v1、多写一截路径，都会 404 models 里的 key，必须是上游真实 model id显示名随便起
默认模型provider\_id/model\_id`，例如 sub2api/grok-4.5

如果你更喜欢把 Key 直接写进配置，也可以：
"options": {
  "baseURL": "https://api.example.com/v1",
  "apiKey": "sk-xxxx"
}
但我更建议：Key 走 /connect 存本地凭证，配置文件里只留 baseURL。
这样以后分享 opencode.json 时，不会把密钥一起交出去。

步骤 C：选模型并开干

重启 OpenCode 后：

/models

你应该能看到类似：

My Sub2API (Grok) / Grok 4.5 (via Sub2API)

选中它，然后随便问一句：

你现在是谁？用一句话说明你的模型名。

通了，就说明： OpenCode 已经不再直连官方 xAI，而是走你自己的 Sub2API 反代在干活。

4. 一版“复制就能改”的完整示例

假设：

域名：https://grok.fungj.com
Provider ID：sub2api
默认模型：grok-4.5

那全局配置可以直接长这样：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "sub2api/grok-4.5",
  "small\_model": "sub2api/grok-4.5",
  "provider": {
    "sub2api": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Sub2API Reverse Proxy",
      "options": {
        "baseURL": "https://grok.fungj.com/v1",
        "timeout": 600000
      },
      "models": {
        "grok-4.5": {
          "name": "Grok 4.5",
          "limit": {
            "context": 256000,
            "output": 65536
          }
        },
        "grok-4.5-latest": {
          "name": "Grok 4.5 Latest"
        }
      }
    }
  }
}

说明：

timeout 拉大一点，长上下文 coding 时不容易被客户端先掐断
limit 不是必须，但有助于 OpenCode 判断上下文余量
具体 context 上限以后台和上游实际能力为准，上面只是个人常用写法

5. 常见翻车点（我已经替你踩过一轮）

1）Provider ID 对不上

/connect 存的是 sub2api，配置文件却写成 my-grok。
表现：有 Key，但 /models 里看不到你的自定义模型。

2）baseURL 少了 `/v1`

错误：

https://api.example.com

正确：

https://api.example.com/v1

OpenCode 的 OpenAI-compatible provider，会在这个 base 后面拼 /chat/completions、/models。

3）模型名写飘了

后台实际是 grok-4.5，你写成 grok-4.5-super / Grok-4.5。
显示名可以好看，请求里的 model id 必须严格匹配。

4）Nginx 缓冲没关，流式半死不活