CLIProxyAPI 简明部署指南

如果手里有多个 ChatGPT、Claude、Gemini 等订阅账号，或者来自不同模型服务商的 API Key，可以用 CLIProxyAPI 把它们收拢到同一个地址，让 Codex、Claude Code、OpenCode 和其他 AI 客户端统一调用。

CLIProxyAPI 负责保存上游凭据、转换接口协议，并在多个账号之间路由请求。客户端只需要配置一个 Base URL、一枚客户端密钥和模型名称。

AI 客户端
→ CLIProxyAPI
→ OAuth 账号或上游 API Key
→ 模型服务

安装 CLIProxyAPI

服务器需要安装 curl 和 tar。运行官方 Linux 安装器：

curl -fsSL \
  https://raw.githubusercontent.com/router-for-me/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer \
  | bash

这条命令会直接执行远程脚本。对安全要求较高时，可以先下载并检查脚本，再手动运行。

安装完成后，主要文件位于：

完成最小配置

打开主配置文件：

nano "$HOME/cliproxyapi/config.yaml"

安装器首次创建 config.yaml 时，会生成两枚客户端密钥并写入顶层 api-keys。当前配置模板还包含 your-api-key-3 默认值；删除所有 your-api-key-*，只保留安装器生成的 Key。两枚都可以保留，也可以只保留一枚。

同时确认以下运行边界：

host: "127.0.0.1"
port: 8317

tls:
  enable: false

remote-management:
  allow-remote: false
  secret-key: ""

auth-dir: "~/.cli-proxy-api"

api-keys:
  - "<安装器生成的第一枚 Key>"
  - "<安装器生成的第二枚 Key>"

不要用上面的占位文字覆盖配置中的实际 Key。这里有两类不同凭据：

两者不能混用。

接入上游模型

CLIProxyAPI 可以同时使用 OAuth 账号和 API Key。首次部署至少接通一种，确认请求链路正常后，再继续添加其他账号或服务。

使用 OAuth 账号

进入安装目录：

cd "$HOME/cliproxyapi"

根据账号类型运行对应命令：

# ChatGPT Codex
./cli-proxy-api -config ./config.yaml -codex-device-login -no-browser

# Claude
./cli-proxy-api -config ./config.yaml -claude-login -no-browser

# Kimi
./cli-proxy-api -config ./config.yaml -kimi-login -no-browser

# xAI
./cli-proxy-api -config ./config.yaml -xai-login -no-browser

-no-browser 适合没有桌面环境的服务器。程序会显示授权地址或设备码，在自己的电脑或手机上完成授权即可。

登录成功后，凭据会保存到 auth-dir。当前版本支持哪些 OAuth 参数，可以直接查看：

"$HOME/cliproxyapi/cli-proxy-api" -h

使用上游 API Key

API Key 不需要登录，只要在 config.yaml 中添加对应配置。

Gemini、Claude 和 xAI 原生 API Key 分别使用以下配置块。只添加自己需要的部分：

# Gemini
gemini-api-key:
  - api-key: "<GEMINI_API_KEY>"

# Claude
claude-api-key:
  - api-key: "<CLAUDE_API_KEY>"

# xAI
xai-api-key:
  - api-key: "<XAI_API_KEY>"

如果上游提供 OpenAI-compatible API，则使用：

openai-compatibility:
  - name: "<PROVIDER_NAME>"
    base-url: "<UPSTREAM_BASE_URL>"
    api-key-entries:
      - api-key: "<UPSTREAM_API_KEY>"
    models:
      - name: "<UPSTREAM_MODEL_ID>"
        alias: "<CLIENT_MODEL_NAME>"

替换上游名称、Base URL、API Key 和模型名。例如 OpenRouter 的 Base URL 是 https://openrouter.ai/api/v1。

api-key-entries 中的是上游密钥，不是顶层 api-keys 中的客户端密钥。其他 Provider 的配置见 官方配置模板。

启动服务

启用并启动用户级服务：

systemctl --user enable --now cliproxyapi.service
systemctl --user status cliproxyapi.service --no-pager

需要让服务在退出登录和服务器重启后继续运行时，再执行：

sudo loginctl enable-linger "$USER"

如果启动失败，查看日志：

journalctl --user -u cliproxyapi.service -n 100 --no-pager

完成本机验证

先确认进程存活：

curl -fsS http://127.0.0.1:8317/healthz

再从 config.yaml 的顶层 api-keys 中复制一枚客户端密钥，请求模型列表：

curl -fsS \
  http://127.0.0.1:8317/v1/models \
  -H "X-Api-Key: <CLIENT_API_KEY>"

从返回结果中选择一个实际模型名，完成一次真实请求：

curl -fsS \
  http://127.0.0.1:8317/v1/chat/completions \
  -H "X-Api-Key: <CLIENT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_NAME>",
    "messages": [
      {"role": "user", "content": "Say hello in one sentence."}
    ]
  }'

收到模型生成的内容，说明客户端密钥、CLIProxyAPI 和上游凭据已经全部可用。

配置 AI 客户端

本机真实请求成功后，就可以配置 AI 客户端。CLIProxyAPI 提供的主要接口包括：

客户端通常会根据所选协议自动追加接口路径。客户端与 CLIProxyAPI 位于同一台机器时，根据协议填写：

API Key 填写 config.yaml 顶层 api-keys 中的任意一枚，模型名称从 /v1/models 返回结果中选择。管理 API 不属于模型调用协议；前面的最小配置保持远程管理关闭。

不要把完整接口路径当成 Base URL。例如 OpenAI Compatible 客户端填写到 /v1 即可，否则可能得到重复的 /v1/v1/...。

到这里，本机部署和客户端配置已经完成。

从其他设备访问

如果 AI 客户端也在服务器本机，不需要继续配置。只有客户端位于其他设备时，才需要为 CLIProxyAPI 增加远程入口。

可以让 Caddy 提供域名和 HTTPS，同时让 CLIProxyAPI 继续只监听 127.0.0.1:8317：

ai.example.com {
    encode zstd gzip

    @model_api path /v1/* /v1beta/* /backend-api/codex/*
    handle @model_api {
        reverse_proxy 127.0.0.1:8317
    }

    respond 404
}

这里使用 handle，会保留 /v1、/v1beta 和 /backend-api/codex 路径前缀。不要改成会删除前缀的 handle_path。

这份配置只公开模型接口，不公开 /healthz 和管理接口。把它加入 Caddy 实际加载的文件后，校验并重载：

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

远程客户端使用：

常见问题

参考资料

• CLIProxyAPI 官方仓库
• CLIProxyAPI 中文 README
• CLIProxyAPI 官方配置模板
• CLIProxyAPI 用户手册