> ## Content Index
> Fetch the complete content index at: https://tbbbk.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# CLIProxyAPI 终极指南：VPS 自建 OpenAI 兼容接口（WebUI + Docker + Nginx）
- URL: https://tbbbk.com/cliproxyapi-setup-linux-and-docker-guide-webui/
- Published: 2026-01-31T18:51:27.000Z
- Updated: 2026-01-31T18:51:27.000Z
- Description: 在 VPS 上通过 Docker 或直装方式部署 CLIProxyAPI，解决 Gemini/Claude 地区限制，附带 Nginx HTTPS 配置和多客户端实战对接指南。
- Author: TuBaiBai
- Tags: AI API 中转, 折腾日记, #Import 2026-07-20 07:13

事情的起因还是 OpenClaw。前几天搭建 OpenClaw 时，发现我的韩国 VPS IP 被 Google 风控“送中”了（识别为中国地区），导致 **Gemini API** 直接报错 `User location is not supported`。

为了拯救我的 GCP $300 赠金，也为了解决 **Claude 4.5 Sonnet**、**OpenAI Codex** 等各种 API 的地区限制和格式兼容问题，我找到了这个神器：**CLIProxyAPI**。

它不仅是一个简单的反代工具，更是一个**全能的 API 聚合网关**。

**它的核心价值：**

1. **接口统一**：把 Gemini、Claude、Copilot、Qwen 等统统转成标准 OpenAI 接口 (`/v1/chat/completions`)。
2. **自带 WebUI**：图形化管理，不用死磕配置文件。
3. **多账号负载均衡**：你有 10 个 Gemini Key？它能自动轮询，提高并发上限。
4. **支持 OAuth**：不仅支持 API Key，还能通过 OAuth 登录 Google/Anthropic 账号（薅免费额度必备）。

---

## 方案一：Docker Compose 部署（推荐，最省事）

如果你熟悉 Docker，这是最快、最干净的部署方式。不用担心环境依赖，一行命令搞定。

### 1\. 准备目录和配置

```bash
mkdir -p /root/cliproxyapi
cd /root/cliproxyapi

# 下载官方示例配置
wget -O config.yaml https://raw.githubusercontent.com/router-for-me/CLIProxyAPI/main/config.example.yaml
```

**修改 `config.yaml`**（关键点）：

```yaml
host: ""  #留空代表可以公网访问/或者需要反代可以填127.0.0.1
# Server port
port: 8317
# TLS settings for HTTPS. When enabled, the server listens with the provided certificate and key.
tls:
  enable: false
  cert: ""
  key: ""

remote-management:
  allow-remote: true #这个要改为true，支持远程访问
  secret-key: "" # 这个是web ui的密码 登录要填进去 建议弄个强密码
  disable-control-panel: false #不要禁用
```

### 2\. 创建 docker-compose.yml

```bash
nano docker-compose.yml
```

写入以下内容：

```yaml
version: '3.8'

services:
  cliproxy:
    image: eceasy/cli-proxy-api:latest
    container_name: cliproxy
    restart: always
    ports:
      - "8317:8317"
    volumes:
      - ./config.yaml:/CLIProxyAPI/config.yaml
      - ./auth:/CLIProxyAPI/auth  # 持久化登录凭证
    environment:
      - TZ=Asia/Shanghai
```

### 3\. 启动服务

```bash
docker compose up -d
```

启动后，访问 `http://你的IP:8317/management.html` 即可进入管理后台。

---

## 方案二：Linux 二进制直装（Systemd 托管）

如果不喜欢 Docker，直接跑二进制文件也是极好的，资源占用更低。

### 1\. 下载与解压

```bash
cd /root
mkdir -p cliproxyapi && cd cliproxyapi

# 请去 GitHub Releases 下载最新版
wget https://github.com/router-for-me/CLIProxyAPI/releases/download/v6.7.38/CLIProxyAPI_6.7.38_linux_amd64.tar.gz

tar -xzvf CLIProxyAPI_6.7.38_linux_amd64.tar.gz
chmod +x CLIProxyAPI
```

### 2\. 配置 Systemd 开机自启

```bash
sudo nano /etc/systemd/system/cliproxyapi.service
```

写入：

```ini
[Unit]
Description=CLIProxyAPI Service
After=network.target

[Service]
Type=simple
WorkingDirectory=/root/cliproxyapi
ExecStart=/root/cliproxyapi/CLIProxyAPI
Restart=always
User=root
# 如果你想通过环境变量设置密码
Environment="MANAGEMENT_PASSWORD=你的强密码"

[Install]
WantedBy=multi-user.target
```

启动并设置自启：

```bash
systemctl daemon-reload
systemctl enable --now cliproxyapi
```

---

## 进阶：Nginx 反代 + HTTPS（安全加固）

直接把 8317 端口暴露在公网是不安全的（容易被扫）。建议配合 Nginx 配置 SSL 证书。

### Nginx 配置示例

在 `/etc/nginx/sites-available/cliproxy` 中写入：

```bash
server {
    listen 80;
    server_name api.yourdomain.com; # 你的域名

    location / {
        proxy_pass http://127.0.0.1:8317;
        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;
        
        # 支持 SSE 流式输出（关键！）
        proxy_buffering off;
        proxy_cache off;
    }
}
```

配合 `certbot` 申请证书后，你就可以用 `https://api.yourdomain.com/v1` 安全访问了。

---

## 对接 OpenClaw / NextChat

现在你拥有了一个属于自己的 OpenAI 兼容接口。

**在 OpenClaw 中配置：**

- **Base URL**: `http://你的IP:8317/v1` (如果配了 Nginx 就是 `https://域名/v1`)
- **API Key**: 你在 `config.yaml` 或 WebUI 里生成的 `sk-xxxx`
- **Model ID**:
- `gemini-3-pro`
- `claude-4-5-sonnet`
- `gpt-5.2` (如果你配置了 Codex)

**在 NextChat (ChatGPT-Next-Web) 中配置：**

- **接口地址**: `http://你的IP:8317`
- **API Key**: `sk-xxxx`
- **自定义模型**: `+gemini-1.5-pro,claude-3-5-sonnet`

我是登录了**Google Antigravity ，能用这这些模型：**

![Google Antigravity 额度](https://tbbbk.com/content/images/2026/01/-------------2026-02-01-021715.png)

****Google Antigravity** 额度

*可以在后台把 使用统计 打开，这样能看到使用情况*

---

## 🛠️ 避坑指南 & 常见问题 (FAQ)

在使用 CLIProxyAPI 搭建 OpenAI 兼容接口的过程中，可能会遇到以下问题。

### 1\. Google/Claude OAuth 无法在 VPS 上登录 (Localhost 回调问题)

**现象**：  
在 VPS 上运行 `./CLIProxyAPI --login` 时，终端提示让你打开浏览器访问 `http://localhost:xxxx`，但 VPS 是没有浏览器的，导致无法完成 OAuth 验证。

**解决方案（推荐“本地偷渡法”）**：  
这是最简单粗暴的方法，完美解决 **CLIProxyAPI OAuth 远程登录** 难题。

1. 在你的**本地电脑**（Windows/Mac）上也下载一个 CLIProxyAPI。
2. 在本地运行登录命令（如 `./CLIProxyAPI --login google`），浏览器会自动弹出，正常登录。
3. 登录成功后，本地目录下会生成一个 `auth` 文件夹（里面有 `auth.json` 或类似凭证）。
4. 把这个 `auth` 文件夹**打包上传**到你 VPS 的 CLIProxyAPI 目录下，覆盖原有的 `auth` 目录。
5. 重启 VPS 上的服务，即可直接识别登录状态。

### 2\. 对接 NextChat/OpenClaw 回复不流畅（Nginx 流式输出卡顿）

**现象**：  
配置了 Nginx 反代后，AI 回复不是一个字一个字蹦出来的（打字机效果），而是卡顿很久后直接**一次性显示一大段**。

**原因**：  
Nginx 默认开启了缓冲（Buffering），会把后端的数据攒够一定大小才发给客户端，破坏了 SSE（Server-Sent Events）流式传输。

**解决方案**：  
在 Nginx 的 `location` 配置中强制关闭缓冲：

```bash
location / {
    proxy_pass http://127.0.0.1:8317;
    # 关键配置：关闭缓冲，支持流式输出
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding on;
}

```

### 3\. 服务启动正常，但公网无法访问 (Connection Refused)

**现象**：  
日志显示 `Server started`，但在本地浏览器输入 `http://VPS_IP:8317` 却打不开。

**排查步骤**：

1. **检查监听地址**：打开 `config.yaml`，确保 `host` 填的是 `"0.0.0.0"`。如果填的是 `127.0.0.1` 或空，它只监听本机，公网是连不上的。
2. **检查云防火墙**：这是新手最容易漏的。去你的云服务商控制台（AWS 安全组 / GCP 防火墙 / 阿里云安全组），放行 **TCP 8317** 端口。
3. **检查系统防火墙**：在 VPS 上跑一下 `ufw allow 8317` 或 `iptables -F`（慎用）测试。

### 4\. Docker 部署后 WebUI 报错或无法保存配置

**现象**：  
使用 Docker 部署，在 WebUI 添加模型时提示 Permission Denied，或者重启容器后配置丢失。

**原因**：  
Docker 容器内的用户权限与挂载目录的权限不一致。

**解决方案**：

1. 或者在 `docker-compose.yml` 中指定 `user: "root"`（不推荐生产环境，但自用省事）。

确保挂载到容器内的 `config.yaml` 和 `auth` 目录在宿主机上有读写权限：

```bash
chmod -R 777 /root/cliproxyapi/auth
chmod 666 /root/cliproxyapi/config.yaml

```

### 5\. 客户端报错 401 Unauthorized

**现象**：  
连接时提示鉴权失败。

**原因**：  
弄混了“两个密码”。

- **WebUI 登录密码** (`management-password`)：仅用于登录浏览器后台。
- **API Key** (`api-keys`)：这才是填入 NextChat、OpenClaw 的 `sk-xxxx`。  
**修正**：请去 WebUI 左侧点击 **API Keys**，复制那个以 `sk-` 开头的密钥。

### 6\. Systemd 服务启动失败 (Exec format error)

**现象**：  
`systemctl start` 报错，日志显示 `Exec format error`。

**原因**：  
下载了错误的架构版本。比如你的 VPS 是 AMD64 架构，你却下载了 `linux_arm64`（给树莓派用的）包。  
**修正**：运行 `uname -m` 查看架构，`x86_64` 请下载 `linux_amd64`，`aarch64` 请下载 `linux_arm64`。

---

### CLIProxyAPI 是目前市面上最强的“个人 API 网关”之一。不仅解决了**Gemini 地区限制**，还把混乱的各家接口统一成了标准 OpenAI 格式。对于喜欢折腾 VPS、搭建 AI 机器人的玩家来说，绝对是必备神器。