CLIProxyAPI 简明部署指南

---
title: "CLIProxyAPI 简明部署指南"
published_at: "2026-08-25"
updated_at: "2026-08-25"
language: "zh"
---

# CLIProxyAPI 简明部署指南

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

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

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

## 安装 CLIProxyAPI

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

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

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

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

| 路径 | 作用 |
| --- | --- |
| `$HOME/cliproxyapi/cli-proxy-api` | 当前使用的主程序 |
| `$HOME/cliproxyapi/config.yaml` | 主配置文件 |
| `$HOME/cliproxyapi/<版本号>/` | 当前版本的完整发布文件 |
| `$HOME/.config/systemd/user/cliproxyapi.service` | 用户级 systemd 服务 |
| `$HOME/.cli-proxy-api/` | OAuth 登录后保存账号凭据的目录 |

## 完成最小配置

打开主配置文件：

```bash
nano "$HOME/cliproxyapi/config.yaml"
```

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

同时确认以下运行边界：

```yaml
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。这里有两类不同凭据：

| 凭据 | 用途 |
| --- | --- |
| 顶层 `api-keys` | AI 客户端访问 CLIProxyAPI |
| OAuth 凭据或上游 API Key | CLIProxyAPI 访问模型服务 |

两者不能混用。

## 接入上游模型

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

### 使用 OAuth 账号

进入安装目录：

```bash
cd "$HOME/cliproxyapi"
```

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

```bash
# 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 参数，可以直接查看：

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

### 使用上游 API Key

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

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

```yaml
# 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，则使用：

```yaml
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 的配置见 [官方配置模板](https://github.com/router-for-me/CLIProxyAPI/blob/main/config.example.yaml)。

## 启动服务

启用并启动用户级服务：

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

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

```bash
sudo loginctl enable-linger "$USER"
```

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

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

## 完成本机验证

先确认进程存活：

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

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

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

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

```bash
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 提供的主要接口包括：

| 用途或协议 | 接口 |
| --- | --- |
| 模型列表 | `GET /v1/models` |
| OpenAI Chat Completions | `POST /v1/chat/completions` |
| OpenAI Completions | `POST /v1/completions` |
| OpenAI Responses | `POST /v1/responses` |
| OpenAI Responses Compact | `POST /v1/responses/compact` |
| Anthropic Messages | `POST /v1/messages` |
| Anthropic Token Count | `POST /v1/messages/count_tokens` |
| Gemini Models | `GET /v1beta/models` |
| Gemini Generate Content | `POST /v1beta/models/{model}:generateContent` |
| Gemini Stream Generate | `POST /v1beta/models/{model}:streamGenerateContent` |
| Gemini Interactions | `POST /v1beta/interactions` |
| Codex Direct | `POST /backend-api/codex/responses` |
| Codex Compact | `POST /backend-api/codex/responses/compact` |
| 管理 API | `/v0/management/*`，不供 AI 客户端调用 |

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

| 协议 | Base URL | 客户端追加的主要路径 |
| --- | --- | --- |
| OpenAI Compatible | `http://127.0.0.1:8317/v1` | `/models`、`/chat/completions`、`/responses` |
| Anthropic Compatible | `http://127.0.0.1:8317` | `/v1/messages` |
| Gemini Native | `http://127.0.0.1:8317` | `/v1beta/models/...` |
| Codex Direct | `http://127.0.0.1:8317/backend-api/codex` | `/responses`、`/responses/compact` |

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`：

```caddyfile
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 实际加载的文件后，校验并重载：

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

远程客户端使用：

| 协议 | Base URL |
| --- | --- |
| OpenAI Compatible | `https://ai.example.com/v1` |
| Anthropic Compatible | `https://ai.example.com` |
| Gemini Native | `https://ai.example.com` |
| Codex Direct | `https://ai.example.com/backend-api/codex` |

## 常见问题

| 现象 | 检查内容 |
| --- | --- |
| 返回 401 | 客户端应使用顶层 `api-keys`，不是 OAuth 凭据或上游 API Key |
| `/v1/models` 为空 | 检查 OAuth 登录、`auth-dir`，或者 API Key 配置块和模型名 |
| 请求路径出现重复 `/v1` | Base URL 只填写到协议根路径，不要填写完整接口地址 |
| 本机可用，其他设备不可用 | 检查域名、Caddy、防火墙和远程客户端的 Base URL |
| 服务启动但模型请求失败 | 查看用户服务日志，再检查模型名和上游凭据 |

## 参考资料

- [CLIProxyAPI 官方仓库](https://github.com/router-for-me/CLIProxyAPI)
- [CLIProxyAPI 中文 README](https://github.com/router-for-me/CLIProxyAPI/blob/main/README_CN.md)
- [CLIProxyAPI 官方配置模板](https://github.com/router-for-me/CLIProxyAPI/blob/main/config.example.yaml)
- [CLIProxyAPI 用户手册](https://help.router-for.me/cn/)