CLIProxyAPI

https://help.router-for.me/cn
Admin
CLIProxyAPI is a fast and lightweight API service compatible with OpenAI, Gemini, Claude, and Codex,...
Tokens:73,258
Snippets:391
Trust Score:2
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install CLIProxyAPI on Linux with a one-click script

Source: https://help.router-for.me/cn/introduction/quick-start

This bash script fetches and executes an installer for CLIProxyAPI on Linux systems. It is a convenient way to get the application running.

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

--------------------------------

### Compile CLIProxyAPI from source using Go

Source: https://help.router-for.me/cn/introduction/quick-start

These commands outline the process of cloning the CLIProxyAPI repository and building the server executable using the Go compiler for Linux, macOS, and Windows.

```bash
git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
```

```bash
# Linux, macOS
go build -o cli-proxy-api ./cmd/server
```

```bash
# Windows
go build -o cli-proxy-api.exe ./cmd/server
```

--------------------------------

### Install CLIProxyAPI on macOS using Homebrew

Source: https://help.router-for.me/cn/introduction/quick-start

This snippet shows how to install the CLIProxyAPI using the Homebrew package manager on macOS and start the service.

```bash
brew install cliproxyapi
brew services start cliproxyapi
```

--------------------------------

### Prepare Configuration File (Bash/CMD/PowerShell)

Source: https://help.router-for.me/cn/docker/docker-compose

This section explains how to create the `config.yaml` file by copying an example configuration. This file is essential for customizing the API's behavior. It provides commands for both Unix-like systems (bash) and Windows (CMD/PowerShell).

```bash
cp config.example.yaml config.yaml
```

```powershell
copy config.example.yaml config.yaml
```

--------------------------------

### Initiate iFlow Login (GET)

Source: https://help.router-for.me/cn/management/api

Starts the login process for iFlow using a GET request. The returned URL should be opened in a browser. After completion, the token is saved in the `auths/` directory. Appending `?is_webui=true` allows reusing the built-in callback forwarding from the management interface.

```APIDOC
## GET /iflow-auth-url

### Description
Starts the iFlow login process. The resulting URL should be opened in a browser to complete the authentication flow. Upon successful completion, the authentication token is stored in the `auths/` directory.

### Method
GET

### Endpoint
`/v0/management/iflow-auth-url`

### Query Parameters
- **is_webui** (boolean) - Optional - If `true`, allows reusing the built-in callback forwarding from the management interface.

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>'
  http://localhost:8317/v0/management/iflow-auth-url?is_webui=true
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation, expected to be "ok".
- **url** (string) - The URL to open in a browser to initiate the authentication flow.
- **state** (string) - A unique state identifier for the authentication process.

#### Response Example
```json
{ "status": "ok", "url": "https://...", "state": "ifl-1716206400" }
```
```

--------------------------------

### Start Docker Compose Services (Bash)

Source: https://help.router-for.me/cn/docker/docker-compose

This command starts the services defined in the `docker-compose.yaml` file in detached mode (running in the background). It's the recommended way for most users to launch the application.

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

--------------------------------

### Install CLIProxyAPI on Arch Linux from AUR

Source: https://help.router-for.me/cn/introduction/quick-start

Instructions for installing CLIProxyAPI on Arch Linux using AUR helpers like yay or paru. It also includes commands for managing the service with systemd.

```bash
# Using yay
yay -S cli-proxy-api-bin

# Using paru
paru -S cli-proxy-api-bin
```

```bash
# Start the service
systemctl --user start cli-proxy-api

# Enable on boot
systemctl --user enable cli-proxy-api
```

```bash
mkdir -p ~/.cli-proxy-api
cp /usr/share/doc/cli-proxy-api-bin/config.example.yaml ~/.cli-proxy-api/config.yaml
```

--------------------------------

### Install Docker

Source: https://help.router-for.me/cn/hands-on/tutorial-5

Installs Docker on the server using the official convenience script. This command downloads and executes the Docker installation script.

```bash
bash <(curl -fsSL https://get.docker.com)
```

--------------------------------

### Start CLIProxyAPI Server using Docker

Source: https://help.router-for.me/cn/docker/docker

This command starts the CLIProxyAPI server. It maps local configuration and authentication directories into the container and exposes port 8317.

```bash
docker run --rm -p 8317:8317 -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api eceasy/cli-proxy-api:latest
```

--------------------------------

### API Call Examples

Source: https://help.router-for.me/cn/agent-client/amp-cli

These examples show how to interact with the CLIProxyAPI using `curl`. The first example demonstrates a chat completion request using local OAuth, while the second shows how to access a management endpoint with an API key.

```bash
curl http://localhost:8317/api/provider/openai/v1/chat/completions \
  -H "Authorization: Bearer <your-cli-proxy-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

```

```bash
curl http://localhost:8317/api/user \
  -H "Authorization: Bearer <your-cli-proxy-api-key>"

```

--------------------------------

### Start CLIProxyAPI

Source: https://help.router-for.me/cn/agent-client/amp-cli

Command to start the CLIProxyAPI server using a specified configuration file.

```APIDOC
## Start CLIProxyAPI

### Description
Launch the CLIProxyAPI server, pointing it to your configuration file.

### Method
Command Line Interface (CLI)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Command
```bash
./cli-proxy-api --config config.yaml
```

### Response
N/A (Server Logs)
```

--------------------------------

### Install Git

Source: https://help.router-for.me/cn/hands-on/tutorial-5

Installs Git on a Debian-based system using apt. This is a prerequisite for cloning the project repository.

```bash
apt update && apt install git -y
```

--------------------------------

### Initiate iFlow Login URL (GET)

Source: https://help.router-for.me/cn/management/api

GET request to initiate the iFlow login process. This endpoint is used to start the standard OAuth flow for iFlow.

```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  http://localhost:8317/v0/management/iflow-auth-url
```

--------------------------------

### CLIProxyAPI Docker Configuration Example

Source: https://help.router-for.me/cn/hands-on/tutorial-5

A minimal configuration example for `config.yaml`. It sets the port, authentication directory, request retry count, quota exceeded behavior, and API keys.

```yaml
port: 8317

# 文件夹位置请根据你的实际情况填写
auth-dir: "~/.cli-proxy-api"

request-retry: 3

quota-exceeded:
  switch-project: true
  switch-preview-model: true

api-keys:
# Key 请自行设置，用于客户端访问代理
- "ABC-123456"
```

--------------------------------

### API Call Examples

Source: https://help.router-for.me/cn/agent-client/amp-cli

Examples of making API calls to the CLIProxyAPI for chat completions and management endpoints.

```APIDOC
## API Call Examples

### Description
Illustrative examples of how to make requests to the CLIProxyAPI for different purposes, including chat completions using local OAuth and accessing management endpoints.

### Method
HTTP Requests (using `curl`)

### Endpoint
`/api/provider/...` and `/api/...`

### Examples
#### Using Local OAuth for Chat Completions:
```bash
curl http://localhost:8317/api/provider/openai/v1/chat/completions \
  -H "Authorization: Bearer <your-cli-proxy-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

#### Management Endpoint (Requires API Key):
```bash
curl http://localhost:8317/api/user \
  -H "Authorization: Bearer <your-cli-proxy-api-key>"
```

### Response
Example responses depend on the specific endpoint and request.
```

--------------------------------

### Initiate Qwen Login (Device Authorization)

Source: https://help.router-for.me/cn/management/api

Starts the device authorization flow for Qwen. The returned URL should be opened in a browser. After completion, the token is saved in the `auths/` directory.

```APIDOC
## GET /qwen-auth-url

### Description
Starts the Qwen login process using a device authorization flow. The resulting URL should be opened in a browser to complete the authentication flow. Upon successful completion, the authentication token is stored in the `auths/` directory.

### Method
GET

### Endpoint
`/v0/management/qwen-auth-url`

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>'
  http://localhost:8317/v0/management/qwen-auth-url
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation, expected to be "ok".
- **url** (string) - The URL to open in a browser to initiate the authentication flow.
- **state** (string) - A unique state identifier for the authentication process.

#### Response Example
```json
{ "status": "ok", "url": "https://...", "state": "gem-1716206400" }
```
```

--------------------------------

### Initiate Antigravity Login URL

Source: https://help.router-for.me/cn/management/api

GET request to obtain the authorization URL for Antigravity. If triggered from a Web UI, appending `?is_webui=true` will start a temporary callback forwarder on port 51121 and reuse the main HTTP port for the final redirect.

```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  http://localhost:8317/v0/management/antigravity-auth-url
```

--------------------------------

### Start CLIProxyAPI Service

Source: https://help.router-for.me/cn/agent-client/amp-cli

This command starts the CLIProxyAPI service using the specified configuration file. Ensure the `config.yaml` file is correctly set up before running this command.

```bash
./cli-proxy-api --config config.yaml

```

--------------------------------

### Using Amp with CLIProxyAPI

Source: https://help.router-for.me/cn/agent-client/amp-cli

Example of how to use the Amp CLI after it has been configured to use the CLIProxyAPI.

```APIDOC
## Use Amp

### Description
Once configured, you can use the Amp CLI as usual. All requests will be routed through your CLIProxyAPI.

### Method
Command Line Interface (CLI)

### Endpoint
N/A

### Parameters
N/A

### Command Example
```bash
amp "Write a hello world program in Python"
```

### Response
N/A (CLI Output)
```

--------------------------------

### Example Usage in Cherry Studio (Code)

Source: https://help.router-for.me/cn/hands-on/tutorial-2

These examples demonstrate how to add and query Codex and Gemini CLI models within the Cherry Studio environment after successful integration with CLIProxyAPI.

```python
# Add Gemini-2.5-Pro model
# Query GPT-5-Codex model
```

--------------------------------

### Clone and Configure CLIProxyAPI

Source: https://help.router-for.me/cn/hands-on/tutorial-5

Clones the CLIProxyAPI repository from GitHub and copies the example configuration file to `config.yaml`. This sets up the project structure and initial configuration.

```bash
git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
cp config.example.yaml config.yaml
```

--------------------------------

### Troubleshooting CLIProxyAPI

Source: https://help.router-for.me/cn/agent-client/amp-cli

A guide to common issues encountered while using the CLIProxyAPI, including error messages, causes, and solutions.

```APIDOC
## Troubleshooting

### Description
This section provides solutions for common problems encountered when setting up and using the CLIProxyAPI, covering issues with routing, authentication, and configuration.

### Common Issues
| Symptom                                   | Possible Cause                     | Resolution                                                                 |
| ----------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------- |
| `/api/provider/...` 404                   | Incorrect route path               | Ensure the path matches exactly: `/api/provider/{provider}/v1...`          |
| `/api/user` 401                           | Missing/Invalid API Key            | Configure `api-keys` and send `Authorization: Bearer <key>` or `X-Api-Key: <key>` |
| `/api/user` 403                           | Localhost restriction enabled      | Run from the same machine or set `ampcode.restrict-management-to-localhost` to `false` |
| Provider returns 401/403                  | Missing/Expired OAuth token        | Re-run the relevant `--login` command (e.g., `--codex-login`)              |
| Amp gzip error                            | Response decompression issue       | Update to the latest version; automatic decompression should handle this.  |
| Model request not proxied                 | Incorrect Amp URL configuration    | Check `amp.url` setting or `AMP_URL` environment variable                  |
| CORS error                                | Protected management endpoint      | Use CLI/terminal, not a browser, for management endpoints.                 |

### Diagnostics
**Check Proxy Logs:**
```bash
# If logging-to-file: true
tail -f logs/requests.log

# If running in tmux
tmux attach-session -t proxy
```

**Temporarily Enable Debug Mode:**
```yaml
debug: true
```

**Test Basic Connectivity:**
```bash
# Check if proxy is running
curl http://localhost:8317/v1/models

# Check Amp-specific routes
curl http://localhost:8317/api/provider/openai/v1/models
```

**Verify Amp Configuration:**
```bash
# Check if Amp is using the proxy
amp config get amp.url

# Or check environment variable
echo $AMP_URL
```

### Response
N/A (Troubleshooting Steps)
```

--------------------------------

### Initiate Qwen Login URL (Device Authorization)

Source: https://help.router-for.me/cn/management/api

GET request to obtain the authorization URL for Qwen, utilizing a device authorization flow. This initiates the process for Qwen authentication.

```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  http://localhost:8317/v0/management/qwen-auth-url
```

--------------------------------

### Get Full Configuration (Bash)

Source: https://help.router-for.me/cn/management/api

Retrieves the complete configuration of the service. Requires an Authorization header with a Bearer token. The response is a JSON object containing various settings.

```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/config
```

--------------------------------

### Clone Repository and Navigate Directory (Bash)

Source: https://help.router-for.me/cn/docker/docker-compose

This snippet demonstrates how to clone the CLIProxyAPI repository from GitHub and then navigate into the newly created directory. It's the initial step for setting up the project locally.

```bash
git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
```

--------------------------------

### Build Docker Image with Scripts (PowerShell/Bash)

Source: https://help.router-for.me/cn/docker/docker-compose

These scripts are for advanced users who have modified the source code and need to build a new Docker image. The PowerShell script is for Windows, while the bash script is for Linux/macOS. They facilitate building and running the application from local source code.

```powershell
.\docker-build.ps1
```

```bash
bash docker-build.sh
```

--------------------------------

### List Request Error Logs (GET /request-error-logs)

Source: https://help.router-for.me/cn/management/api

Retrieves a list of error request log files. Returns an empty list if request logging is disabled. Log files must start with 'error-' and end with '.log'. The 'modified' field is a Unix timestamp.

```json
{
  "files": [
    {
      "name": "error-2024-05-20.log",
      "size": 12345,
      "modified": 1716206400
    }
  ]
}
```

--------------------------------

### Initiate Google (Gemini CLI) Login

Source: https://help.router-for.me/cn/management/api

Starts the login process for Google (Gemini CLI). The returned URL should be opened in a browser. After completion, the token is saved in the `auths/` directory. Appending `?is_webui=true` allows reusing the built-in callback forwarding from the management interface.

```APIDOC
## GET /gemini-cli-auth-url

### Description
Starts the Google (Gemini CLI) login process. The resulting URL should be opened in a browser to complete the authentication flow. Upon successful completion, the authentication token is stored in the `auths/` directory.

### Method
GET

### Endpoint
`/v0/management/gemini-cli-auth-url`

### Query Parameters
- **project_id** (string) - Optional - The Google Cloud project ID. If not provided, the service will enumerate accessible projects and select the first one.
- **is_webui** (boolean) - Optional - If `true`, allows reusing the built-in callback forwarding from the management interface.

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>'
  'http://localhost:8317/v0/management/gemini-cli-auth-url?project_id=<PROJECT_ID>&is_webui=true'
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation, expected to be "ok".
- **url** (string) - The URL to open in a browser to initiate the authentication flow.
- **state** (string) - A unique state identifier for the authentication process.

#### Response Example
```json
{ "status": "ok", "url": "https://...", "state": "gem-1716206400" }
```

### Notes
- If `project_id` is not supplied, the service will automatically select the first available project via the Cloud Resource Manager API and mark it with `auto: true` in the token.
- The service checks if `cloudaicompanion.googleapis.com` is enabled. If not, it attempts to enable it via the Service Usage API. Failure to enable may result in errors like `project activation required: ...` from the `/get-auth-status` endpoint.
```

--------------------------------

### Get Proxy URL (GET /proxy-url)

Source: https://help.router-for.me/cn/management/api

Retrieves the configured proxy URL string. The response contains the current proxy URL.

```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/proxy-url
```

--------------------------------

### Initiate Antigravity Login

Source: https://help.router-for.me/cn/management/api

Starts the login process for Antigravity. The returned URL should be opened in a browser. After completion, the token is saved in the `auths/` directory. Appending `?is_webui=true` allows reusing the built-in callback forwarding from the management interface.

```APIDOC
## GET /antigravity-auth-url

### Description
Starts the Antigravity login process. The resulting URL should be opened in a browser to complete the authentication flow. Upon successful completion, the authentication token is stored in the `auths/` directory.

### Method
GET

### Endpoint
`/v0/management/antigravity-auth-url`

### Query Parameters
- **is_webui** (boolean) - Optional - If `true`, the service will start a temporary callback forwarder on local port `51121` and reuse the main HTTP port for the final redirect.

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>'
  http://localhost:8317/v0/management/antigravity-auth-url?is_webui=true
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation, expected to be "ok".
- **url** (string) - The URL to open in a browser to initiate the authentication flow.
- **state** (string) - A unique state identifier for the authentication process.

#### Response Example
```json
{ "status": "ok", "url": "https://...", "state": "ant-1716206400" }
```
```

--------------------------------

### Get Quota Exceeded Switch Project Status (GET /quota-exceeded/switch-project)

Source: https://help.router-for.me/cn/management/api

Retrieves the boolean status of the 'switch-project' feature for quota exceeded behavior.

```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/quota-exceeded/switch-project
```

--------------------------------

### Get Quota Exceeded Switch Preview Model Status (GET /quota-exceeded/switch-preview-model)

Source: https://help.router-for.me/cn/management/api

Retrieves the boolean status of the 'switch-preview-model' feature for quota exceeded behavior.

```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/quota-exceeded/switch-preview-model
```

--------------------------------

### Amp CLI Configuration Example (YAML)

Source: https://help.router-for.me/cn/agent-client/amp-cli

This snippet shows the basic configuration for the 'ampcode' block in `config.yaml`. It includes essential settings like API keys for client authentication and the upstream API key for authenticating with ampcode.com. It also demonstrates optional settings for restricting management routes to localhost and model mappings.

```yaml
api-keys:
  - "your-client-secret-key" # 给你的客户端使用的示例密钥

ampcode:
  # Amp 上游控制平面（管理路由必需）
  upstream-url: "https://ampcode.com"
  # CLIProxyAPI 用来向 ampcode.com 认证的 API 密钥
  # 从 https://ampcode.com/settings 获取
  upstream-api-key: "your-ampcode-api-key-goes-here"
  # 可选：将管理路由限制在 localhost（默认：false）
  restrict-management-to-localhost: false
  # 可选：将缺失的 Amp 模型映射到本地模型
  # model-mappings:
  #   - from: "claude-opus-4.5"
  #     to: "claude-sonnet-4"

```

--------------------------------

### Start CLIProxyAPI for Qwen Login (Windows)

Source: https://help.router-for.me/cn/hands-on/tutorial-1

This command initiates the Qwen authorization process for CLIProxyAPI on a Windows system. It opens a browser window for the user to log in to their Qwen account and complete the authorization. After successful authorization, the program prompts for an alias to identify the account.

```bash
cli-proxy-api --qwen-login
```

--------------------------------

### Get OAuth Excluded Models Mapping

Source: https://help.router-for.me/cn/management/api

Retrieves the current mapping of OAuth providers to their excluded model lists. This GET request requires an Authorization header.

```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  http://localhost:8317/v0/management/oauth-excluded-models
```

--------------------------------

### Get API Keys (GET /api-keys)

Source: https://help.router-for.me/cn/management/api

Retrieves the complete list of API keys used for proxy service authentication. These keys are managed within the 'auth.providers' configuration.

```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/api-keys
```

--------------------------------

### Get Usage Statistics Status (GET /usage-statistics-enabled)

Source: https://help.router-for.me/cn/management/api

Checks the current status of usage statistics collection. Returns a JSON object indicating whether usage statistics are enabled.

```json
{ "usage-statistics-enabled": true }
```

--------------------------------

### CLIProxyAPI Configuration - YAML

Source: https://help.router-for.me/cn/hands-on/tutorial-0

This YAML configuration snippet outlines various settings for the CLIProxyAPI. It includes network port, remote management options (enabling, secret key, disabling control panel), authentication directory path, debug logging, request logging, file logging, usage statistics, proxy URL, request retry count, quota exceeded behavior (account switching, preview model switching), disabling cooling periods, API keys for AIStudio, and specific configurations for Gemini, Codex, Claude, and OpenAI-compatible APIs, including base URLs, headers, proxy settings, and model aliases.

```yaml
# 端口号，CLIProxyAPI运行了个HTTP服务器，需要端口号来进行访问
port: 8317

# 远程管理配置，配合EasyCLI或者WebUI来使用
remote-management:
  # 启用远程管理的开关，如果你部署在服务器上
  # 那么需要设置为true，才能使用EasyCLI或者WebUI连接到CLIProxyAPI进行管理
  # 如果只是本地使用API进行管理的，可以保持false不动
  allow-remote: false

  # 如果想使用EasyCLI或者WebUI通过API对CLIProxyAPI进行管理，必须设置Key
  # 如果不设置，视同关闭了API管理功能，就无法使用EasyCLI或者WebUI进行连接了
  # 如果你不需要使用EasyCLI或者WebUI进行管理，可以留空
  secret-key: ""

  # 是否集成WebUI的开关
  # 设置为false，可以通过http://YOUR_SERVER_IP:8317/management.html打开WebUI
  disable-control-panel: false

# 认证文件存放目录，用于存放Gemini CLI、Gemini Web、Qwen Code、Codex的认证文件
# 默认设置，是在你当前账户目录下的.cli-proxy-api文件夹，适配Windows和Linux环境
# 程序首次启动时会自动创建该文件夹
# Windows下默认为C:\Users\你的用户名\.cli-proxy-api
# Linux下默认为/home/你的用户名/.cli-proxy-api
# 如果在Windows环境下使用非默认位置，需要参照这样的格式修改填写"Z:\\CLIProxyAPI\\auths"
auth-dir: "~/.cli-proxy-api"

# 是否在日志中启用Debug信息，默认不启用，需要作者配合排错的时候打开就行
debug: false

# 隐藏配置，可以记录每一个请求和响应，并保存到logs目录下
# 每条日志体积可能会高达10MB+，硬盘不够大请不要开启
request-log: false

# 是否将日志重定向到日志文件中
# 默认启用，日志会保存在程序目录下的logs文件夹中
# 如果关闭的话，会在控制台显示日志
logging-to-file: true

# 开关使用统计，默认启用
# 需要使用API来查看使用量，可以用EeasyCLI或者WebUI来查看
usage-statistics-enabled: true

# 如果你要使用代理，那么需要进行以下的设置，支持socks5/http/https协议
# 按照这样的格式"socks5://user:pass@192.168.1.1:1080/"填写
proxy-url: ""

# 当请求碰到403, 408, 500, 502, 503, 504这些错误码的时候，程序自动重试请求的次数
request-retry: 3

# 模型受到限制之后的处理行为
quota-exceeded:
  # 多账号轮询的核心配置
  # 设置为true时，例如一个账号触发了429，程序会自动切换到下一个账号重新发起请求
  # 设置为false时，程序会把429的错误信息发给客户端，结束当前请求
  # 也就是说，当设置为true时，只要轮询的账号里至少有一个号是正常的，客户端这里就不会报错
  # 而设置false时，则需要客户端来进行重试或中止操作
  switch-project: true 
  # Gemini CLI独占配置，适用于Gemini 2.5 Pro和Gemini 2.5 Flash模型
  # 当正式版配额用完之后，会自动切换到Preview模型，保持开启即可
  switch-preview-model: true

# 隐藏配置，可以关闭重试时的间隔时间，根据需要进行设置
# 例如某模型触发429后，程序会暂时停用它，且每次再触发都会增加停用时间，最多延长到30分钟
# 默认情况下，停用期内会跳过该模型
# 设置true后，无论该模型是否处于停用期，仍会每次都向该模型发起请求，不再跳过
disable-cooling: false

# 各种AI客户端访问CLIProxyAPI所需要填写的Key，就在这里设置，和后边的各种Key不要弄混淆了
# 通俗点讲，这里的Key是CLIProxyAPI作为服务器所需要设置的
# 后边的各种Key是CLIProxyAPI作为客户端去访问服务器所需要的
api-keys:
  - "your-api-key-1"
  - "your-api-key-2"

# AIStudio的鉴权开关，设置为true，会使用上述的api-keys对AIStudio Build APP接入进行鉴权
ws-auth: false

# Gemini 的官方 API Key 设置项。旧的 generative-language-api-key 会在加载时自动迁移为此字段并从配置文件移除。
# 不设置base-url时，使用官方端点接入；设置了base-url，可以接入第三方中转。
# 使用Cloudflare AI Gateway接入时，可以通过设置headers进行鉴权。
# 针对每个Key，还能够设置proxy-url，通过代理进行连接。
gemini-api-key:
  - api-key: "AIzaSy...01"
    base-url: "https://generativelanguage.googleapis.com"
    headers:
      X-Custom-Header: "custom-value"
    proxy-url: "socks5://proxy.example.com:1080"
  - api-key: "AIzaSy...02"

# Codex的API Key，各种中转站提供的Codex的key和base-url参数，填在这里就可以接入了
# 针对每个Key，还能够设置proxy-url，通过代理进行连接
codex-api-key:
  - api-key: "sk-atSM..."
    base-url: "https://www.example.com"
    proxy-url: "socks5://proxy.example.com:1080"

# Claude的API Key，使用官方Key的时候，不要填base-url，使用第三方中转的，填base-url
# 针对每个Key，还能够设置proxy-url，通过代理进行连接
claude-api-key:
  - api-key: "sk-atSM..."
  - api-key: "sk-atSM..."
    base-url: "https://www.example.com"
    proxy-url: "socks5://proxy.example.com:1080"
    models:
      # 中转商提供的模型名称
      - name: "claude-3-5-sonnet-20241022"
        # 模型别名，是在客户端中实际设置的模型名
        alias: "claude-sonnet-latest"

# 各种OpenAI兼容的都可以在这里接入，不多解释了
openai-compatibility:
  - name: "openrouter"
    base-url: "https://openrouter.ai/api/v1"
    # 旧字段 api-keys 会在加载时自动迁移为 api-key-entries。
    api-key-entries:
      - api-key: "sk-or-v1-...b780"
        proxy-url: "socks5://proxy.example.com:1080"
      - api-key: "sk-or-v1-...b781"
    models:
    	# OpenAI兼容供应商提供的模型名称
      - name: "moonshotai/kimi-k2:free"
      	# 模型别名，是在客户端中实际设置的模型名
        alias: "kimi-k2"

```

--------------------------------

### Request Logging Configuration

Source: https://help.router-for.me/cn/management/api

Endpoints to get and set the boolean value for request logging.

```APIDOC
## GET /request-log

### Description
Retrieves the current boolean value indicating if request logging is enabled.

### Method
GET

### Endpoint
/v0/management/request-log

### Parameters
None

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/request-log
```

### Response
#### Success Response (200)
- **request-log** (boolean) - True if request logging is enabled, false otherwise.

#### Response Example
```json
{ "request-log": false }
```

## PUT/PATCH /request-log

### Description
Sets the boolean value for request logging.

### Method
PUT/PATCH

### Endpoint
/v0/management/request-log

### Parameters
#### Request Body
- **value** (boolean) - Required - True to enable request logging, false to disable.

### Request Example
```bash
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  -d '{"value":true}' \
  http://localhost:8317/v0/management/request-log
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the operation status, e.g., "ok".

#### Response Example
```json
{ "status": "ok" }
```
```

--------------------------------

### Max Retry Interval Configuration

Source: https://help.router-for.me/cn/management/api

Endpoints to get and set the maximum retry interval in seconds.

```APIDOC
## GET /max-retry-interval

### Description
Retrieves the maximum retry interval in seconds.

### Method
GET

### Endpoint
/v0/management/max-retry-interval

### Parameters
None

### Request Example
```bash
curl -H 'Authorization: BearER <MANAGEMENT_KEY>' \
  http://localhost:8317/v0/management/max-retry-interval
```

### Response
#### Success Response (200)
- **max-retry-interval** (integer) - The maximum retry interval in seconds.

#### Response Example
```json
{ "max-retry-interval": 30 }
```

## PUT/PATCH /max-retry-interval

### Description
Sets the maximum retry interval in seconds.

### Method
PUT/PATCH

### Endpoint
/v0/management/max-retry-interval

### Parameters
#### Request Body
- **value** (integer) - Required - The new maximum retry interval in seconds.

### Request Example
```bash
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: BearER <MANAGEMENT_KEY>' \
  -d '{"value":60}' \
  http://localhost:8317/v0/management/max-retry-interval
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the operation status, e.g., "ok".

#### Response Example
```json
{ "status": "ok" }
```
```

--------------------------------

### Authenticate with AI Models via Docker Compose (Bash)

Source: https://help.router-for.me/cn/docker/docker-compose

This set of commands allows users to authenticate with various AI models directly within the running Docker container. Each command targets a specific AI provider, using the `cli-proxy-api` service and the `-no-browser` flag for headless authentication.

```bash
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --login
```

```bash
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --codex-login
```

```bash
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --claude-login
```

```bash
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --qwen-login
```

```bash
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --iflow-login
```

```bash
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --antigravity-login
```

--------------------------------

### Request Retry Configuration

Source: https://help.router-for.me/cn/management/api

Endpoints to get and set the integer value for request retry counts.

```APIDOC
## GET /request-retry

### Description
Retrieves the current integer value for request retry counts.

### Method
GET

### Endpoint
/v0/management/request-retry

### Parameters
None

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/request-retry
```

### Response
#### Success Response (200)
- **request-retry** (integer) - The current number of retries allowed.

#### Response Example
```json
{ "request-retry": 3 }
```

## PUT/PATCH /request-retry

### Description
Sets the integer value for request retry counts.

### Method
PUT/PATCH

### Endpoint
/v0/management/request-retry

### Parameters
#### Request Body
- **value** (integer) - Required - The new number of retries to set.

### Request Example
```bash
curl -X PATCH -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MANAGEMENT_KEY>' \
  -d '{"value":5}' \
  http://localhost:8317/v0/management/request-retry
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the operation status, e.g., "ok".

#### Response Example
```json
{ "status": "ok" }
```
```

--------------------------------

### GET /config

Source: https://help.router-for.me/cn/management/api

Retrieves the complete configuration of the service. If the configuration has not yet been loaded, an empty object is returned.

```APIDOC
## GET /config

### Description
Retrieves the complete configuration of the service. If the configuration has not yet been loaded, an empty object is returned.

### Method
GET

### Endpoint
/v0/management/config

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -H 'Authorization: Bearer <MANAGEMENT_KEY>' http://localhost:8317/v0/management/config
```

### Response
#### Success Response (200)
- **debug** (boolean) - Indicates if debug mode is enabled.
- **proxy-url** (string) - The proxy URL if configured.
- **api-keys** (array) - A list of API keys.
- **ampcode** (object) - Ampcode configuration.
- **quota-exceeded** (object) - Quota exceeded settings.
- **gemini-api-key** (array) - Gemini API key configurations.
- **request-log** (boolean) - Whether request logging is enabled.
- **request-retry** (integer) - Number of request retries.
- **claude-api-key** (array) - Claude API key configurations.
- **codex-api-key** (array) - Codex API key configurations.
- **openai-compatibility** (array) - OpenAI compatibility configurations.

#### Response Example
```json
{
  "debug": true,
  "proxy-url": "",
  "api-keys": ["1...5", "JS...W"],
  "ampcode": {
    "upstream-url": "https://ampcode.com",
    "restrict-management-to-localhost": true
  },
  "quota-exceeded": {
    "switch-project": true,
    "switch-preview-model": true
  },
  "gemini-api-key": [
    {
      "api-key": "AI...01",
      "base-url": "https://generativelanguage.googleapis.com",
      "headers": {
        "X-Custom-Header": "custom-value"
      },
      "proxy-url": "",
      "excluded-models": ["gemini-1.5-pro", "gemini-1.5-flash"]
    },
    {
      "api-key": "AI...02",
      "proxy-url": "socks5://proxy.example.com:1080",
      "excluded-models": ["gemini-pro-vision"]
    }
  ],
  "request-log": true,
  "request-retry": 3,
  "claude-api-key": [
    {
      "api-key": "cr...56",
      "base-url": "https://example.com/api",
      "proxy-url": "socks5://proxy.example.com:1080",
      "models": [
        {
          "name": "claude-3-5-sonnet-20241022",
          "alias": "claude-sonnet-latest"
        }
      ],
      "excluded-models": ["claude-3-opus"]
    },
    {
      "api-key": "cr...e3",
      "base-url": "http://example.com:3000/api",
      "proxy-url": ""
    },
    {
      "api-key": "sk-...q2",
      "base-url": "https://example.com",
      "proxy-url": ""
    }
  ],
  "codex-api-key": [
    {
      "api-key": "sk...01",
      "base-url": "https://example/v1",
      "proxy-url": "",
      "excluded-models": ["gpt-4o-mini"]
    }
  ],
  "openai-compatibility": [
    {
      "name": "openrouter",
      "base-url": "https://openrouter.ai/api/v1",
      "api-key-entries": [
        {
          "api-key": "sk...01",
          "proxy-url": ""
        }
      ],
      "models": [
        {
          "name": "moonshotai/kimi-k2:free",
          "alias": "kimi-k2"
        }
      ]
    },
    {
      "name": "iflow",
      "base-url": "https://apis.iflow.cn/v1",
      "api-key-entries": [
        {
          "api-key": "sk...7e",
          "proxy-url": "socks5://proxy.example.com:1080"
        }
      ],
      "models": [
        {
          "name": "deepseek-v3.1",
          "alias": "deepseek-v3.1"
        },
        {
          "name": "glm-4.5",
          "alias": "glm-4.5"
        },
        {
          "name": "kimi-k2",
          "alias": "kimi-k2"
        }
      ]
    }
  ]
}
```

### Notes
- The `generative-language-api-key` field is no longer included. For a plain string view, use the dedicated `GET /generative-language-api-key` endpoint.
- If the service has not loaded the configuration file, an empty object `{}` will be returned.
```
Tokens:
Raw