这篇文章记录我在 Linux 上部署 CliproxyAPI 的完整流程，包含安装、Web UI 配置、Gemini CLI 授权和常见坑点。官方文档对已经熟悉代理和 CLI 工具的人比较友好，但第一次上手时，还是需要一份更偏实战的记录。

这篇更适合第一次把服务在 Linux 机器上跑通的人看。如果你已经部署成功，可以直接跳到“调用方式”和“systemd 服务”两节。

很多人在折腾这类代理和授权链路时，都会顺手准备多个邮箱。原因其实很直接：我们最终还是要用邮箱去注册 GPT 账号，后面的验证码、登录提醒、密码找回和安全通知，也都依赖邮箱来承接。所以邮箱不是“可有可无的附属品”，而是整个授权流程里最基础的一层身份入口。

一键安装

直接执行安装脚本：

1
curl -fsSL https://raw.githubusercontent.com/brokechubb/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bash

安装完成后，程序默认会落在 ~/cliproxyapi 目录，也就是当前用户家目录下。

首次启动与 Web UI

先进入安装目录，编辑 config.yaml，给 secret-key 设一个值：

1
secret-key:

例如：

1
secret-key: "123456"

然后在目录中直接启动程序：

1
./cli-proxy-api

启动后访问 http://localhost:8317/management.html，输入 123456 即可进入。

Gemini CLI 授权流程

1. 创建 Google Cloud 项目

进入 Google Cloud Console，新建一个项目，并记下项目 ID。

2. 启用所需 API

搜索并启用：

1
cloudaicompanion.googleapis.com

3. 在 Web UI 中完成授权

回到 CliproxyAPI 的管理后台，把项目 ID 填进去，按页面提示完成 Gemini CLI 授权。

Codex 授权流程截图

如果你在授权页面里一时分不清该点哪里，可以按下面这三张图对照着走。页面样式后面可能会变，但整体流程基本就是按顺序完成登录、确认和回跳。

授权截图 1

Codex 授权流程截图 1

登录授权页面，先确认当前账号和目标服务是否对应。

授权截图 2

Codex 授权流程截图 2

按页面提示继续确认权限，避免跳错账号或工作区。

授权截图 3

Codex 授权流程截图 3

完成授权后再回到 CliproxyAPI 管理页检查状态是否已经刷新。

调用方式

部署完成后，常用调用参数如下：

  • BASE_URL：http://127.0.0.1:8317
  • API_KEY：在 Web UI 中自行修改

如果只是确认服务已经跑起来，可以先试一下：

1
2
curl http://127.0.0.1:8317/v1/models \
  -H "Authorization: Bearer your-api-key"

我踩过的几个坑

  1. 必须先在终端里跑一次 ./cli-proxy-api
    不管你后面是不是只打算用 Web UI，都建议先手动启动一次。否则授权登录时生成的文件可能不会被正确记录。

  2. secret-key 不要留空
    如果你准备使用管理页面，建议一开始就把 secret-key 设置好，不然后面再改容易忘。

  3. 确认端口与防火墙
    默认是 8317，如果你有安全组、ufw 或服务器面板，记得把端口放通。

如果你发现 Web UI 授权完成了，但本地配置或令牌状态没有变化，优先检查是不是没有先手动启动过 ./cli-proxy-api。

可选：做成 systemd 服务

如果你已经验证服务可用，建议再补一个 systemd，避免机器重启后忘记拉起：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[Unit]
Description=CliproxyAPI
After=network.target

[Service]
Type=simple
User=YOUR_USER
WorkingDirectory=/home/YOUR_USER/cliproxyapi
ExecStart=/home/YOUR_USER/cliproxyapi/cli-proxy-api
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

写好以后执行：

1
2
3
sudo systemctl daemon-reload
sudo systemctl enable --now cliproxyapi
sudo systemctl status cliproxyapi

参考