折腾日记

CLIProxyAPI 终极指南：VPS 自建 OpenAI 兼容接口（WebUI + Docker + Nginx）

在 VPS 上通过 Docker 或直装方式部署 CLIProxyAPI，解决 Gemini/Claude 地区限制，附带 Nginx HTTPS 配置和多客户端实战对接指南。

TuBaiBai

TuBaiBai

— 7 min read
CLIProxyAPI 终极指南：VPS 自建 OpenAI 兼容接口（WebUI + Docker + Nginx）
Photo by Nigel Hoare / Unsplash

事情的起因还是 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. 准备目录和配置

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（关键点）：

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

nano docker-compose.yml

写入以下内容：

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. 启动服务

docker compose up -d

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

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

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

1. 下载与解压

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 开机自启

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

写入：

[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

启动并设置自启：

systemctl daemon-reload
systemctl enable --now cliproxyapi

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

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

Nginx 配置示例

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

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 额度
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 配置中强制关闭缓冲：

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 目录在宿主机上有读写权限：

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 机器人的玩家来说，绝对是必备神器。

Read more