# Table of Contents - [CLIProxyAPI](#cliproxyapi) - [CLIProxyAPI](#cliproxyapi) - [What is CLIProxyAPI? | CLIProxyAPI](#what-is-cliproxyapi-cliproxyapi) - [Quick Start | CLIProxyAPI](#quick-start-cliproxyapi) - [快速开始 | CLIProxyAPI](#-cliproxyapi) - [CLIProxyAPI是什么？ | CLIProxyAPI](#cliproxyapi-cliproxyapi) - [Basic Configuration | CLIProxyAPI](#basic-configuration-cliproxyapi) - [Configuration Options | CLIProxyAPI](#configuration-options-cliproxyapi) - [Authentication Directory | CLIProxyAPI](#authentication-directory-cliproxyapi) - [Hot Reloading | CLIProxyAPI](#hot-reloading-cliproxyapi) - [Git-backed Configuration and Token Store | CLIProxyAPI](#git-backed-configuration-and-token-store-cliproxyapi) - [PostgreSQL-backed Configuration and Token Store | CLIProxyAPI](#postgresql-backed-configuration-and-token-store-cliproxyapi) - [Object Storage-backed Configuration and Token Store | CLIProxyAPI](#object-storage-backed-configuration-and-token-store-cliproxyapi) - [Gemini CLI (Gemini via OAuth): | CLIProxyAPI](#gemini-cli-gemini-via-oauth-cliproxyapi) - [Antigravity (Antigravity via OAuth): | CLIProxyAPI](#antigravity-antigravity-via-oauth-cliproxyapi) - [Claude Code (Anthropic via OAuth): | CLIProxyAPI](#claude-code-anthropic-via-oauth-cliproxyapi) - [Codex (OpenAI via OAuth): | CLIProxyAPI](#codex-openai-via-oauth-cliproxyapi) - [AI Studio Instructions | CLIProxyAPI](#ai-studio-instructions-cliproxyapi) - [iFlow (iFlow via OAuth): | CLIProxyAPI](#iflow-iflow-via-oauth-cliproxyapi) - [OpenAI Compatibility Providers | CLIProxyAPI](#openai-compatibility-providers-cliproxyapi) - [Qwen (Qwen Chat via OAuth): | CLIProxyAPI](#qwen-qwen-chat-via-oauth-cliproxyapi) - [Claude Code Compatibility Providers | CLIProxyAPI](#claude-code-compatibility-providers-cliproxyapi) - [Gemini Compatibility Providers | CLIProxyAPI](#gemini-compatibility-providers-cliproxyapi) - [Thinking Budgets via Model Name Parentheses | CLIProxyAPI](#thinking-budgets-via-model-name-parentheses-cliproxyapi) - [Codex Compatibility Providers | CLIProxyAPI](#codex-compatibility-providers-cliproxyapi) - [Web UI | CLIProxyAPI](#web-ui-cliproxyapi) - [Desktop GUI | CLIProxyAPI](#desktop-gui-cliproxyapi) - [Claude Code | CLIProxyAPI](#claude-code-cliproxyapi) - [Management API | CLIProxyAPI](#management-api-cliproxyapi) - [Codex | CLIProxyAPI](#codex-cliproxyapi) - [Gemini CLI | CLIProxyAPI](#gemini-cli-cliproxyapi) - [Factory Droid | CLIProxyAPI](#factory-droid-cliproxyapi) - [Run with Docker | CLIProxyAPI](#run-with-docker-cliproxyapi) - [Zero: Detailed Configuration Explanation | CLIProxyAPI](#zero-detailed-configuration-explanation-cliproxyapi) - [Amp CLI | CLIProxyAPI](#amp-cli-cliproxyapi) - [Run with Docker Compose | CLIProxyAPI](#run-with-docker-compose-cliproxyapi) - [Four: Relay Forwarding Integration | CLIProxyAPI](#four-relay-forwarding-integration-cliproxyapi) - [Five: Docker Server Deployment | CLIProxyAPI](#five-docker-server-deployment-cliproxyapi) - [Zero-Cost Deployment: HuggingFace (Database Storage) | CLIProxyAPI](#zero-cost-deployment-huggingface-database-storage-cliproxyapi) - [Six: The Beginner's Favorite GUI | CLIProxyAPI](#six-the-beginner-s-favorite-gui-cliproxyapi) - [Zero-Cost Deployment: ClawCloud (Built-in Storage) | CLIProxyAPI](#zero-cost-deployment-clawcloud-built-in-storage-cliproxyapi) - [Two: Gemini CLI + Codex Hands-on | CLIProxyAPI](#two-gemini-cli-codex-hands-on-cliproxyapi) - [Zero-Cost Deployment (AIStudio Reverse Proxy) | CLIProxyAPI](#zero-cost-deployment-aistudio-reverse-proxy-cliproxyapi) - [Zero-Cost Deployment: Render (Git Storage) | CLIProxyAPI](#zero-cost-deployment-render-git-storage-cliproxyapi) - [AmpCode Usage Guide | CLIProxyAPI](#ampcode-usage-guide-cliproxyapi) - [Zero-Cost Deployment: Railway (Object Storage) | CLIProxyAPI](#zero-cost-deployment-railway-object-storage-cliproxyapi) - [Three: NanoBanana Hands-on | CLIProxyAPI](#three-nanobanana-hands-on-cliproxyapi) - [One: Project Introduction + Qwen Hands-on | CLIProxyAPI](#one-project-introduction-qwen-hands-on-cliproxyapi) - [凭证目录 | CLIProxyAPI](#-cliproxyapi) - [热更新 | CLIProxyAPI](#-cliproxyapi) - [配置选项 | CLIProxyAPI](#-cliproxyapi) - [PostgreSQL 支持的配置与令牌存储 | CLIProxyAPI](#postgresql-cliproxyapi) - [Git 支持的配置与令牌存储 | CLIProxyAPI](#git-cliproxyapi) - [基础配置 | CLIProxyAPI](#-cliproxyapi) - [Gemini CLI (Gemini OAuth 登录): | CLIProxyAPI](#gemini-cli-gemini-oauth-cliproxyapi) - [Claude Code (Anthropic OAuth 登录): | CLIProxyAPI](#claude-code-anthropic-oauth-cliproxyapi) - [对象存储驱动的配置与令牌存储 | CLIProxyAPI](#-cliproxyapi) - [Codex (OpenAI OAuth 登录): | CLIProxyAPI](#codex-openai-oauth-cliproxyapi) - [反重力 (反重力 OAuth 登录): | CLIProxyAPI](#-oauth-cliproxyapi) - [Qwen (Qwen Chat OAuth 登录): | CLIProxyAPI](#qwen-qwen-chat-oauth-cliproxyapi) - [OpenAI 兼容供应商 | CLIProxyAPI](#openai-cliproxyapi) - [AI Studio 使用说明 | CLIProxyAPI](#ai-studio-cliproxyapi) - [iFlow (iFlow OAuth 登录): | CLIProxyAPI](#iflow-iflow-oauth-cliproxyapi) - [Claude Code 兼容供应商 | CLIProxyAPI](#claude-code-cliproxyapi) - [Web UI | CLIProxyAPI](#web-ui-cliproxyapi) - [Gemini 兼容供应商 | CLIProxyAPI](#gemini-cliproxyapi) - [通过模型名括号设置思考量 | CLIProxyAPI](#-cliproxyapi) - [Codex 兼容供应商 | CLIProxyAPI](#codex-cliproxyapi) - [桌面客户端 | CLIProxyAPI](#-cliproxyapi) - [Gemini CLI | CLIProxyAPI](#gemini-cli-cliproxyapi) - [Codex | CLIProxyAPI](#codex-cliproxyapi) - [Claude Code | CLIProxyAPI](#claude-code-cliproxyapi) - [Factory Droid | CLIProxyAPI](#factory-droid-cliproxyapi) - [管理 API | CLIProxyAPI](#-api-cliproxyapi) - [Amp CLI | CLIProxyAPI](#amp-cli-cliproxyapi) - [使用 Docker Compose 运行 | CLIProxyAPI](#-docker-compose-cliproxyapi) - [叁：NanoBanana实战 | CLIProxyAPI](#-nanobanana-cliproxyapi) - [使用 Docker 运行 | CLIProxyAPI](#-docker-cliproxyapi) - [陆：新人最爱GUI | CLIProxyAPI](#-gui-cliproxyapi) - [零：配置详细解说 | CLIProxyAPI](#-cliproxyapi) - [贰：Gemini CLI+Codex实战 | CLIProxyAPI](#-gemini-cli-codex-cliproxyapi) - [伍：Docker服务器部署 | CLIProxyAPI](#-docker-cliproxyapi) - [肆：中转转发接入篇 | CLIProxyAPI](#-cliproxyapi) - [零成本部署：HuggingFace (数据库存储) | CLIProxyAPI](#-huggingface-cliproxyapi) - [零成本部署：Railway (对象存储) | CLIProxyAPI](#-railway-cliproxyapi) - [零成本部署：ClawCloud (自带存储) | CLIProxyAPI](#-clawcloud-cliproxyapi) - [零成本部署：Render (Git存储) | CLIProxyAPI](#-render-git-cliproxyapi) - [零成本部署AIStudio反代 | CLIProxyAPI](#-aistudio-cliproxyapi) - [AmpCode食用指南 | CLIProxyAPI](#ampcode-cliproxyapi) - [壹：项目介绍+Qwen实战 | CLIProxyAPI](#-qwen-cliproxyapi) --- # CLIProxyAPI [Skip to content](https://help.router-for.me/#VPContent) CLIProxyAPI =========== An OpenAI/Gemini/Claude/Codex compatible API service [What is CLIProxyAPI?](https://help.router-for.me/introduction/what-is-cliproxyapi.html) [Quick Start](https://help.router-for.me/introduction/quick-start.html) [GitHub](https://github.com/router-for-me/CLIProxyAPI) All Protocols ------------- Support all protocols: Chat Completions / Response / Gemini / Claude One Protocol ------------ Use a single protocol to access all models Fast ---- Fast and lightweight --- # CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/#VPContent) CLIProxyAPI =========== 一个 OpenAI/Gemini/Claude/Codex 兼容的 API 服务 [CLIProxyAPI是什么？](https://help.router-for.me/cn/introduction/what-is-cliproxyapi.html) [快速开始](https://help.router-for.me/cn/introduction/quick-start.html) [GitHub](https://github.com/router-for-me/CLIProxyAPI) 所有协议 ---- 支持所有协议：Chat Completions / Response / Gemini / Claude 一个协议 ---- 使用一个协议访问所有模型 快速 -- 快速且轻盈 --- # What is CLIProxyAPI? | CLIProxyAPI [Skip to content](https://help.router-for.me/introduction/what-is-cliproxyapi.html#VPContent) On this page What is CLIProxyAPI? [​](https://help.router-for.me/introduction/what-is-cliproxyapi.html#what-is-cliproxyapi) =============================================================================================================== **CLIProxyAPI** is a proxy server that provides OpenAI/Gemini/Claude/Codex compatible API interfaces for CLI. You can use local or multi-account CLI access with OpenAI(include Responses)/Gemini/Claude-compatible clients and SDKs. Features [​](https://help.router-for.me/introduction/what-is-cliproxyapi.html#features) ---------------------------------------------------------------------------------------- * OpenAI/Gemini/Claude compatible API endpoints for CLI models * Gemini CLI support via OAuth login * Antigravity support via OAuth login * OpenAI Codex support (GPT models) via OAuth login * Claude Code support via OAuth login * Qwen Code support via OAuth login * iFlow support via OAuth login * Streaming and non-streaming responses * Function calling/tools support * Multimodal input support (text and images) * Multiple accounts with round-robin load balancing (Gemini, OpenAI, Claude, Qwen and iFlow) * Simple CLI authentication flows (Gemini, OpenAI, Claude, Qwen and iFlow) * Generative Language API Key support * Gemini CLI multi-account load balancing * Antigravity multi-account load balancing * Claude Code multi-account load balancing * Qwen Code multi-account load balancing * iFlow multi-account load balancing * OpenAI Codex multi-account load balancing * OpenAI-compatible upstream providers via config (e.g., OpenRouter) Supported Models [​](https://help.router-for.me/introduction/what-is-cliproxyapi.html#supported-models) -------------------------------------------------------------------------------------------------------- * gemini-3-pro-preview * gemini-3-pro-image-preview * gemini-2.5-pro * gemini-2.5-flash * gemini-2.5-flash-lite * gemini-2.5-flash-image * gemini-2.5-flash-image-preview * gemini-pro-latest * gemini-flash-latest * gemini-flash-lite-latest * gpt-5 * gpt-5-codex * claude-opus-4-1-20250805 * claude-opus-4-20250514 * claude-sonnet-4-20250514 * claude-sonnet-4-5-20250929 * claude-haiku-4-5-20251001 * claude-3-7-sonnet-20250219 * claude-3-5-haiku-20241022 * qwen3-coder-plus * qwen3-coder-flash * qwen3-max * qwen3-vl-plus * deepseek-v3.2 * deepseek-v3.1 * deepseek-r1 * deepseek-v3 * kimi-k2 * glm-4.6 * tstars2.0 * And other iFlow-supported models * Gemini models auto-switch to preview variants when needed --- # Quick Start | CLIProxyAPI [Skip to content](https://help.router-for.me/introduction/quick-start.html#VPContent) On this page Quick Start [​](https://help.router-for.me/introduction/quick-start.html#quick-start) ====================================================================================== macOS [​](https://help.router-for.me/introduction/quick-start.html#macos) -------------------------------------------------------------------------- bash brew install cliproxyapi brew services start cliproxyapi Linux [​](https://help.router-for.me/introduction/quick-start.html#linux) -------------------------------------------------------------------------- ### One-Click Installer Script [​](https://help.router-for.me/introduction/quick-start.html#one-click-installer-script) bash curl -fsSL https://raw.githubusercontent.com/brokechubb/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bash Thanks to [brokechubb](https://github.com/brokechubb) for building the Linux installer! ### Arch Linux (AUR) [​](https://help.router-for.me/introduction/quick-start.html#arch-linux-aur) If you are an Arch Linux user, you can install directly from the AUR: bash # Using yay yay -S cli-proxy-api-bin # Using paru paru -S cli-proxy-api-bin After installation, you can manage the service via systemd: bash # Start the service systemctl --user start cli-proxy-api # Enable auto-start on boot systemctl --user enable cli-proxy-api > ⚠️ **Note**: A configuration file is required before starting the service. You can create it by copying the example configuration: > > bash > > mkdir -p ~/.cli-proxy-api > cp /usr/share/doc/cli-proxy-api-bin/config.example.yaml ~/.cli-proxy-api/config.yaml Windows [​](https://help.router-for.me/introduction/quick-start.html#windows) ------------------------------------------------------------------------------ You can download the latest release from [here](https://github.com/router-for-me/CLIProxyAPI/releases) and run it directly. Or You can download our desktop GUI app from [here](https://github.com/router-for-me/EasyCLI/releases) and run it directly. Docker [​](https://help.router-for.me/introduction/quick-start.html#docker) ---------------------------------------------------------------------------- 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 Building from Source [​](https://help.router-for.me/introduction/quick-start.html#building-from-source) -------------------------------------------------------------------------------------------------------- 1. Clone the repository: bash git clone https://github.com/router-for-me/CLIProxyAPI.git cd CLIProxyAPI 2. Build the application: Linux, macOS: bash go build -o cli-proxy-api ./cmd/server Windows: bash go build -o cli-proxy-api.exe ./cmd/server --- # 快速开始 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/introduction/quick-start.html#VPContent) 页面导航 快速开始 [​](https://help.router-for.me/cn/introduction/quick-start.html#%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B) =========================================================================================================== macOS [​](https://help.router-for.me/cn/introduction/quick-start.html#macos) ----------------------------------------------------------------------------- bash brew install cliproxyapi brew services start cliproxyapi Linux [​](https://help.router-for.me/cn/introduction/quick-start.html#linux) ----------------------------------------------------------------------------- ### 一键安装脚本 [​](https://help.router-for.me/cn/introduction/quick-start.html#%E4%B8%80%E9%94%AE%E5%AE%89%E8%A3%85%E8%84%9A%E6%9C%AC) bash curl -fsSL https://raw.githubusercontent.com/brokechubb/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bash 感谢 [brokechubb](https://github.com/brokechubb) 开发的 Linux 安装器！ ### Arch Linux (AUR) [​](https://help.router-for.me/cn/introduction/quick-start.html#arch-linux-aur) 如果你是 Arch Linux 用户，可以直接从 AUR 安装： bash # 使用 yay yay -S cli-proxy-api-bin # 使用 paru paru -S cli-proxy-api-bin 安装完成后，你可以通过 systemd 管理服务： bash # 启动服务 systemctl --user start cli-proxy-api # 设置开机自启 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 Windows [​](https://help.router-for.me/cn/introduction/quick-start.html#windows) --------------------------------------------------------------------------------- 你可以在 [这里](https://github.com/router-for-me/CLIProxyAPI/releases) 下载最新版本并直接运行。 或者 你可以在 [这里](https://github.com/router-for-me/EasyCLI/releases) 下载我们的桌面图形程序并直接运行。 Docker [​](https://help.router-for.me/cn/introduction/quick-start.html#docker) ------------------------------------------------------------------------------- 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 源码编译 [​](https://help.router-for.me/cn/introduction/quick-start.html#%E6%BA%90%E7%A0%81%E7%BC%96%E8%AF%91) ----------------------------------------------------------------------------------------------------------- 1. 克隆仓库: bash git clone https://github.com/router-for-me/CLIProxyAPI.git cd CLIProxyAPI 2. 构建程序: Linux, macOS: bash go build -o cli-proxy-api ./cmd/server Windows: bash go build -o cli-proxy-api.exe ./cmd/server --- # CLIProxyAPI是什么？ | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/introduction/what-is-cliproxyapi.html#VPContent) 回到顶部 CLIProxyAPI是什么？ [​](https://help.router-for.me/cn/introduction/what-is-cliproxyapi.html#cliproxyapi%E6%98%AF%E4%BB%80%E4%B9%88) ================================================================================================================================ **CLIProxyAPI** 是一个为 CLI 提供 OpenAI/Gemini/Claude/Codex 兼容 API 接口的代理服务器。 您可以使用本地或多账户的CLI方式，通过任何与 OpenAI（包括Responses）/Gemini/Claude 兼容的客户端和SDK进行访问。 功能特性 [​](https://help.router-for.me/cn/introduction/what-is-cliproxyapi.html#%E5%8A%9F%E8%83%BD%E7%89%B9%E6%80%A7) ------------------------------------------------------------------------------------------------------------------- * 为 CLI 模型提供 OpenAI/Gemini/Claude/Codex 兼容的 API 端点 * Gemini CLI 支持（OAuth 登录） * 反重力 支持（OAuth 登录） * OpenAI Codex（GPT 系列）支持（OAuth 登录） * Claude Code 支持（OAuth 登录） * Qwen Code 支持（OAuth 登录） * iFlow 支持（OAuth 登录） * 支持流式与非流式响应 * 函数调用/工具支持 * 多模态输入（文本、图片） * 多账户支持与轮询负载均衡（Gemini、OpenAI、Claude、Qwen 与 iFlow） * 简单的 CLI 身份验证流程（Gemini、OpenAI、Claude、Qwen 与 iFlow） * 支持 Gemini AIStudio API 密钥 * 支持 AI Studio Build 多账户轮询 * 支持 Gemini CLI 多账户轮询 * 支持 反重力 多账户轮询 * 支持 Claude Code 多账户轮询 * 支持 Qwen Code 多账户轮询 * 支持 iFlow 多账户轮询 * 支持 OpenAI Codex 多账户轮询 * 通过配置接入上游 OpenAI 兼容提供商（例如 OpenRouter） 支持的模型 [​](https://help.router-for.me/cn/introduction/what-is-cliproxyapi.html#%E6%94%AF%E6%8C%81%E7%9A%84%E6%A8%A1%E5%9E%8B) ----------------------------------------------------------------------------------------------------------------------------- * gemini-3-pro-preview * gemini-3-pro-image-preview * gemini-2.5-pro * gemini-2.5-flash * gemini-2.5-flash-lite * gemini-2.5-flash-image * gemini-2.5-flash-image-preview * gemini-pro-latest * gemini-flash-latest * gemini-flash-lite-latest * gpt-5 * gpt-5-codex * claude-opus-4-1-20250805 * claude-opus-4-20250514 * claude-sonnet-4-20250514 * claude-sonnet-4-5-20250929 * claude-haiku-4-5-20251001 * claude-3-7-sonnet-20250219 * claude-3-5-haiku-20241022 * qwen3-coder-plus * qwen3-coder-flash * qwen3-max * qwen3-vl-plus * deepseek-v3.2 * deepseek-v3.1 * deepseek-r1 * deepseek-v3 * kimi-k2 * glm-4.6 * tstars2.0 * 以及其他 iFlow 支持的模型 * Gemini 模型在需要时自动切换到对应的 preview 版本 --- # Basic Configuration | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/basic.html#VPContent) Return to top Basic Configuration [​](https://help.router-for.me/configuration/basic.html#basic-configuration) ================================================================================================= Configuration File [​](https://help.router-for.me/configuration/basic.html#configuration-file) ----------------------------------------------------------------------------------------------- The server reads a YAML configuration file (`config.yaml`) from the project root by default. Use `--config` to point to another file: bash ./cli-proxy-api --config /path/to/your/config.yaml ### Example Configuration [​](https://help.router-for.me/configuration/basic.html#example-configuration) yaml # Server host/interface to bind to. Default is empty ("") to bind all interfaces (IPv4 + IPv6). # Use "127.0.0.1" or "localhost" to restrict access to local machine only. host: "" # Server port port: 8317 # TLS settings for HTTPS. When enabled, the server listens with the provided certificate and key. tls: enable: false cert: "" key: "" # Management API settings remote-management: # Whether to allow remote (non-localhost) management access. # When false, only localhost can access management endpoints (a key is still required). allow-remote: false # Management key. If a plaintext value is provided here, it will be hashed on startup. # All management requests (even from localhost) require this key. # Leave empty to disable the Management API entirely (404 for all /v0/management routes). secret-key: "" # Disable the bundled management control panel asset download and HTTP route when true. disable-control-panel: false # GitHub repository for the management control panel. Accepts a repository URL or releases API URL. panel-github-repository: "https://github.com/router-for-me/Cli-Proxy-API-Management-Center" # Authentication directory (supports ~ for home directory) auth-dir: "~/.cli-proxy-api" # API keys for authentication api-keys: - "your-api-key-1" - "your-api-key-2" - "your-api-key-3" # Enable debug logging debug: false # When true, disable high-overhead HTTP middleware features to reduce per-request memory usage under high concurrency. commercial-mode: false # When true, write application logs to rotating files instead of stdout logging-to-file: false # Maximum total size (MB) of log files under the logs directory. When exceeded, the oldest log # files are deleted until within the limit. Set to 0 to disable. logs-max-total-size-mb: 0 # When false, disable in-memory usage statistics aggregation usage-statistics-enabled: false # Proxy URL. Supports socks5/http/https protocols. Example: socks5://user:pass@192.168.1.1:1080/ proxy-url: "" # When true, unprefixed model requests only use credentials without a prefix (except when prefix == model name). force-model-prefix: false # Number of times to retry a request. Retries will occur if the HTTP response code is 403, 408, 500, 502, 503, or 504. request-retry: 3 # Maximum wait time in seconds for a cooled-down credential before triggering a retry. max-retry-interval: 30 # Quota exceeded behavior quota-exceeded: switch-project: true # Whether to automatically switch to another project when a quota is exceeded switch-preview-model: true # Whether to automatically switch to a preview model when a quota is exceeded # Routing strategy for selecting credentials when multiple match. routing: strategy: "round-robin" # round-robin (default), fill-first # When true, enable authentication for the WebSocket API (/v1/ws). ws-auth: false # When > 0, emit blank lines every N seconds for non-streaming responses to prevent idle timeouts. nonstream-keepalive-interval: 0 # When true, enable official Codex instructions injection for Codex API requests. # When false (default), CodexInstructionsForModel returns immediately without modification. codex-instructions-enabled: false # Streaming behavior (SSE keep-alives + safe bootstrap retries). streaming: keepalive-seconds: 15 # Default: 0 (disabled). <= 0 disables keep-alives. bootstrap-retries: 1 # Default: 0 (disabled). Retries before first byte is sent. # Gemini API keys gemini-api-key: - api-key: "AIzaSy...01" prefix: "test" # optional: require calls like "test/gemini-3-pro-preview" to target this credential base-url: "https://generativelanguage.googleapis.com" headers: X-Custom-Header: "custom-value" proxy-url: "socks5://proxy.example.com:1080" models: - name: "gemini-2.5-flash" # upstream model name alias: "gemini-flash" # client alias mapped to the upstream model excluded-models: - "gemini-2.5-pro" # exclude specific models from this provider (exact match) - "gemini-2.5-*" # wildcard matching prefix (e.g. gemini-2.5-flash, gemini-2.5-pro) - "*-preview" # wildcard matching suffix (e.g. gemini-3-pro-preview) - "*flash*" # wildcard matching substring (e.g. gemini-2.5-flash-lite) - api-key: "AIzaSy...02" # Codex API keys codex-api-key: - api-key: "sk-atSM..." prefix: "test" # optional: require calls like "test/gpt-5-codex" to target this credential base-url: "https://www.example.com" # use the custom codex API endpoint headers: X-Custom-Header: "custom-value" proxy-url: "socks5://proxy.example.com:1080" # optional: per-key proxy override models: - name: "gpt-5-codex" # upstream model name alias: "codex-latest" # client alias mapped to the upstream model excluded-models: - "gpt-5.1" # exclude specific models (exact match) - "gpt-5-*" # wildcard matching prefix (e.g. gpt-5-medium, gpt-5-codex) - "*-mini" # wildcard matching suffix (e.g. gpt-5-codex-mini) - "*codex*" # wildcard matching substring (e.g. gpt-5-codex-low) # Claude API keys claude-api-key: - api-key: "sk-atSM..." # use the official claude API key, no need to set the base url - api-key: "sk-atSM..." prefix: "test" # optional: require calls like "test/claude-sonnet-latest" to target this credential base-url: "https://www.example.com" # use the custom claude API endpoint headers: X-Custom-Header: "custom-value" proxy-url: "socks5://proxy.example.com:1080" # optional: per-key proxy override models: - name: "claude-3-5-sonnet-20241022" # upstream model name alias: "claude-sonnet-latest" # client alias mapped to the upstream model excluded-models: - "claude-opus-4-5-20251101" # exclude specific models (exact match) - "claude-3-*" # wildcard matching prefix (e.g. claude-3-7-sonnet-20250219) - "*-thinking" # wildcard matching suffix (e.g. claude-opus-4-5-thinking) - "*haiku*" # wildcard matching substring (e.g. claude-3-5-haiku-20241022) cloak: # optional: request cloaking for non-Claude-Code clients mode: "auto" # "auto" (default): cloak only when client is not Claude Code # "always": always apply cloaking # "never": never apply cloaking strict-mode: false # false (default): prepend Claude Code prompt to user system messages # true: strip all user system messages, keep only Claude Code prompt sensitive-words: # optional: words to obfuscate with zero-width characters - "API" - "proxy" # OpenAI compatibility providers openai-compatibility: - name: "openrouter" # The name of the provider; it will be used in the user agent and other places. prefix: "test" # optional: require calls like "test/kimi-k2" to target this provider's credentials base-url: "https://openrouter.ai/api/v1" # The base URL of the provider. headers: X-Custom-Header: "custom-value" api-key-entries: - api-key: "sk-or-v1-...b780" proxy-url: "socks5://proxy.example.com:1080" # optional: per-key proxy override - api-key: "sk-or-v1-...b781" # without proxy-url models: # The models supported by the provider. - name: "moonshotai/kimi-k2:free" # The actual model name. alias: "kimi-k2" # The alias used in the API. # Vertex API keys (Vertex-compatible endpoints, use API key + base URL) vertex-api-key: - api-key: "vk-123..." # x-goog-api-key header prefix: "test" # optional: require calls like "test/vertex-pro" to target this credential base-url: "https://example.com/api" # e.g. https://zenmux.ai/api proxy-url: "socks5://proxy.example.com:1080" # optional per-key proxy override headers: X-Custom-Header: "custom-value" models: # optional: map aliases to upstream model names - name: "gemini-2.5-flash" # upstream model name alias: "vertex-flash" # client-visible alias - name: "gemini-2.5-pro" alias: "vertex-pro" # Amp Integration ampcode: # Configure upstream URL for Amp CLI OAuth and management features upstream-url: "https://ampcode.com" # Optional: Override API key for Amp upstream (otherwise uses env or file) upstream-api-key: "" # Per-client upstream API key mapping # Maps client API keys (from top-level api-keys) to different Amp upstream API keys. # Useful when different clients need to use different Amp accounts/quotas. # If a client key isn't mapped, falls back to upstream-api-key (default behavior). upstream-api-keys: - upstream-api-key: "amp_key_for_team_a" # Upstream key to use for these clients api-keys: # Client keys that use this upstream key - "your-api-key-1" - "your-api-key-2" - upstream-api-key: "amp_key_for_team_b" api-keys: - "your-api-key-3" # Restrict Amp management routes (/api/auth, /api/user, etc.) to localhost only (default: false) restrict-management-to-localhost: false # Force model mappings to run before checking local API keys (default: false) force-model-mappings: false # Amp Model Mappings # Route unavailable Amp models to alternative models available in your local proxy. # Useful when Amp CLI requests models you don't have access to (e.g., Claude Opus 4.5) # but you have a similar model available (e.g., Claude Sonnet 4). model-mappings: - from: "claude-opus-4-5-20251101" # Model requested by Amp CLI to: "gemini-claude-opus-4-5-thinking" # Route to this available model instead - from: "claude-sonnet-4-5-20250929" to: "gemini-claude-sonnet-4-5-thinking" - from: "claude-haiku-4-5-20251001" to: "gemini-2.5-flash" # Global OAuth model name aliases (per channel) # These aliases rename model IDs for both model listing and request routing. # Supported channels: gemini-cli, vertex, aistudio, antigravity, claude, codex, qwen, iflow. # NOTE: Aliases do not apply to gemini-api-key, codex-api-key, claude-api-key, openai-compatibility, vertex-api-key, or ampcode. # You can repeat the same name with different aliases to expose multiple client model names. oauth-model-alias: antigravity: - name: "rev19-uic3-1p" alias: "gemini-2.5-computer-use-preview-10-2025" - name: "gemini-3-pro-image" alias: "gemini-3-pro-image-preview" - name: "gemini-3-pro-high" alias: "gemini-3-pro-preview" - name: "gemini-3-flash" alias: "gemini-3-flash-preview" - name: "claude-sonnet-4-5" alias: "gemini-claude-sonnet-4-5" - name: "claude-sonnet-4-5-thinking" alias: "gemini-claude-sonnet-4-5-thinking" - name: "claude-opus-4-5-thinking" alias: "gemini-claude-opus-4-5-thinking" # gemini-cli: # - name: "gemini-2.5-pro" # original model name under this channel # alias: "g2.5p" # client-visible alias # fork: true # when true, keep original and also add the alias as an extra model (default: false) # vertex: # - name: "gemini-2.5-pro" # alias: "g2.5p" # aistudio: # - name: "gemini-2.5-pro" # alias: "g2.5p" # claude: # - name: "claude-sonnet-4-5-20250929" # alias: "cs4.5" # codex: # - name: "gpt-5" # alias: "g5" # qwen: # - name: "qwen3-coder-plus" # alias: "qwen-plus" # iflow: # - name: "glm-4.7" # alias: "glm-god" # OAuth provider excluded models oauth-excluded-models: gemini-cli: - "gemini-2.5-pro" # exclude specific models (exact match) - "gemini-2.5-*" # wildcard matching prefix (e.g. gemini-2.5-flash, gemini-2.5-pro) - "*-preview" # wildcard matching suffix (e.g. gemini-3-pro-preview) - "*flash*" # wildcard matching substring (e.g. gemini-2.5-flash-lite) vertex: - "gemini-3-pro-preview" aistudio: - "gemini-3-pro-preview" antigravity: - "gemini-3-pro-preview" claude: - "claude-3-5-haiku-20241022" codex: - "gpt-5-codex-mini" qwen: - "vision-model" iflow: - "tstars2.0" # Optional payload configuration payload: default: # Default rules only set parameters when they are missing in the payload. - models: - name: "gemini-2.5-pro" # Supports wildcards (e.g., "gemini-*") protocol: "gemini" # restricts the rule to a specific protocol, options: openai, gemini, claude, codex, antigravity params: # JSON path (gjson/sjson syntax) -> value "generationConfig.thinkingConfig.thinkingBudget": 32768 default-raw: # Default raw rules set parameters using raw JSON when missing (must be valid JSON). - models: - name: "gemini-2.5-pro" # Supports wildcards (e.g., "gemini-*") protocol: "gemini" # restricts the rule to a specific protocol, options: openai, gemini, claude, codex, antigravity params: # JSON path (gjson/sjson syntax) -> raw JSON value (strings are used as-is, must be valid JSON) "generationConfig.responseJsonSchema": "{\"type\":\"object\",\"properties\":{\"answer\":{\"type\":\"string\"}}}" override: # Override rules always set parameters, overwriting any existing values. - models: - name: "gpt-*" # Supports wildcards (e.g., "gpt-*") protocol: "codex" # restricts the rule to a specific protocol, options: openai, gemini, claude, codex, antigravity params: # JSON path (gjson/sjson syntax) -> value "reasoning.effort": "high" override-raw: # Override raw rules always set parameters using raw JSON (must be valid JSON). - models: - name: "gpt-*" # Supports wildcards (e.g., "gpt-*") protocol: "codex" # restricts the rule to a specific protocol, options: openai, gemini, claude, codex, antigravity params: # JSON path (gjson/sjson syntax) -> raw JSON value (strings are used as-is, must be valid JSON) "response_format": "{\"type\":\"json_schema\",\"json_schema\":{\"name\":\"answer\",\"schema\":{\"type\":\"object\"}}}" filter: # Filter rules remove specified parameters from the payload. - models: - name: "gemini-2.5-pro" # Supports wildcards (e.g., "gemini-*") protocol: "gemini" # restricts the rule to a specific protocol, options: openai, gemini, claude, codex, antigravity params: # JSON paths (gjson/sjson syntax) to remove from the payload - "generationConfig.thinkingConfig.thinkingBudget" - "generationConfig.responseJsonSchema" --- # Configuration Options | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/options.html#VPContent) Return to top Configuration Options [​](https://help.router-for.me/configuration/options.html#configuration-options) ======================================================================================================= Defaults stay aligned with `config.example.yaml`. Core [​](https://help.router-for.me/configuration/options.html#core) --------------------------------------------------------------------- | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `host` | string | `""` | Bind address; `""` listens on all IPv4/IPv6; use `127.0.0.1` to restrict to localhost. | | `port` | integer | `8317` | Server port. | | `tls.enable` | boolean | `false` | Enable HTTPS. | | `tls.cert` | string | `""` | TLS certificate path. | | `tls.key` | string | `""` | TLS private key path. | | `auth-dir` | string | `"~/.cli-proxy-api"` | Credential storage directory; `~` supported. | | `api-keys` | string\[\] | `[]` | Built-in API keys. | | `debug` | boolean | `false` | Verbose logging. | | `commercial-mode` | boolean | `false` | Disable high-overhead middleware to lower memory. | | `logging-to-file` | boolean | `false` | Write rotating log files instead of stdout. | | `logs-max-total-size-mb` | integer | `0` | Log directory size cap; 0 disables limiting. | | `usage-statistics-enabled` | boolean | `false` | Enable in-memory usage aggregation. | | `proxy-url` | string | `""` | Global proxy (socks5/http/https). | | `force-model-prefix` | boolean | `false` | Unprefixed model requests use only unprefixed credentials. | | `request-retry` | integer | `3` | Retries on 403/408/500/502/503/504. | | `max-retry-interval` | integer | `30` | Max wait (seconds) for cooled-down credential before retry. | | `routing.strategy` | string | `"round-robin"` | Credential selection when multiple match: `round-robin` or `fill-first`. | | `ws-auth` | boolean | `false` | Require auth for `/v1/ws`. | | `nonstream-keepalive-interval` | integer | `0` | Non-SSE blank line interval (seconds) to prevent idle timeout; 0 disables. | | `codex-instructions-enabled` | boolean | `false` | Enable official Codex instructions injection for Codex API requests. | | `streaming.keepalive-seconds` | integer | `0` | SSE keep-alive interval; ≤0 disables. | | `streaming.bootstrap-retries` | integer | `0` | Safe retries before first byte. | Management API [​](https://help.router-for.me/configuration/options.html#management-api) ----------------------------------------------------------------------------------------- | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `remote-management.allow-remote` | boolean | `false` | Permit non-localhost management access. | | `remote-management.secret-key` | string | `""` | Management key; plaintext is hashed on startup; empty disables all `/v0/management` (404). | | `remote-management.disable-control-panel` | boolean | `false` | Disable bundled management UI assets/routes. | | `remote-management.panel-github-repository` | string | `"https://github.com/router-for-me/Cli-Proxy-API-Management-Center"` | Repo or releases API for the management UI bundle. | Quota & Routing [​](https://help.router-for.me/configuration/options.html#quota-routing) ----------------------------------------------------------------------------------------- | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `quota-exceeded.switch-project` | boolean | `true` | Auto-switch project on quota exhaustion. | | `quota-exceeded.switch-preview-model` | boolean | `true` | Auto-switch to preview model on exhaustion. | Provider Credentials (arrays; default `[]`) [​](https://help.router-for.me/configuration/options.html#provider-credentials-arrays-default) ------------------------------------------------------------------------------------------------------------------------------------------- ### Gemini [​](https://help.router-for.me/configuration/options.html#gemini) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `gemini-api-key.*.api-key` | string | `""` | API key. | | `gemini-api-key.*.prefix` | string | `""` | Optional prefix; call as `prefix/model`. | | `gemini-api-key.*.base-url` | string | `"https://generativelanguage.googleapis.com"` | Custom endpoint. | | `gemini-api-key.*.headers` | object | `{}` | Extra headers for that endpoint. | | `gemini-api-key.*.proxy-url` | string | `""` | Per-key proxy override. | | `gemini-api-key.*.models.*.name` | string | `""` | Upstream model name. | | `gemini-api-key.*.models.*.alias` | string | `""` | Client alias. | | `gemini-api-key.*.excluded-models` | string\[\] | `[]` | Models to exclude (wildcards supported). | ### Codex [​](https://help.router-for.me/configuration/options.html#codex) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `codex-api-key.*.api-key` | string | `""` | API key. | | `codex-api-key.*.prefix` | string | `""` | Optional prefix. | | `codex-api-key.*.base-url` | string | `""` | Custom Codex endpoint. | | `codex-api-key.*.headers` | object | `{}` | Extra headers. | | `codex-api-key.*.proxy-url` | string | `""` | Per-key proxy override. | | `codex-api-key.*.models.*.name` | string | `""` | Upstream model name. | | `codex-api-key.*.models.*.alias` | string | `""` | Client alias. | | `codex-api-key.*.excluded-models` | string\[\] | `[]` | Models to exclude (wildcards). | ### Claude [​](https://help.router-for.me/configuration/options.html#claude) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `claude-api-key.*.api-key` | string | `""` | API key. | | `claude-api-key.*.prefix` | string | `""` | Optional prefix. | | `claude-api-key.*.base-url` | string | `""` | Custom Claude endpoint. | | `claude-api-key.*.headers` | object | `{}` | Extra headers. | | `claude-api-key.*.proxy-url` | string | `""` | Per-key proxy override. | | `claude-api-key.*.models.*.name` | string | `""` | Upstream model name. | | `claude-api-key.*.models.*.alias` | string | `""` | Client alias. | | `claude-api-key.*.excluded-models` | string\[\] | `[]` | Models to exclude (wildcards). | | `claude-api-key.*.cloak.mode` | string | `"auto"` | Cloaking mode: `auto` (non-Claude Code only), `always`, `never`. | | `claude-api-key.*.cloak.strict-mode` | boolean | `false` | `true` strips user system messages, keeps only Claude Code prompt. | | `claude-api-key.*.cloak.sensitive-words` | string\[\] | `[]` | Words to obfuscate with zero-width characters. | ### OpenAI Compatibility [​](https://help.router-for.me/configuration/options.html#openai-compatibility) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `openai-compatibility.*.name` | string | `""` | Provider name (used in UA, etc.). | | `openai-compatibility.*.prefix` | string | `""` | Optional prefix. | | `openai-compatibility.*.base-url` | string | `""` | Provider base URL. | | `openai-compatibility.*.headers` | object | `{}` | Extra headers. | | `openai-compatibility.*.api-key-entries.*.api-key` | string | `""` | API key. | | `openai-compatibility.*.api-key-entries.*.proxy-url` | string | `""` | Per-key proxy override. | | `openai-compatibility.*.models.*.name` | string | `""` | Upstream model name. | | `openai-compatibility.*.models.*.alias` | string | `""` | Client alias. | ### Vertex [​](https://help.router-for.me/configuration/options.html#vertex) | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `vertex-api-key.*.api-key` | string | `""` | `x-goog-api-key` value. | | `vertex-api-key.*.prefix` | string | `""` | Optional prefix. | | `vertex-api-key.*.base-url` | string | `""` | Vertex-compatible endpoint. | | `vertex-api-key.*.proxy-url` | string | `""` | Per-key proxy override. | | `vertex-api-key.*.headers` | object | `{}` | Extra headers. | | `vertex-api-key.*.models.*.name` | string | `""` | Upstream model name. | | `vertex-api-key.*.models.*.alias` | string | `""` | Client alias. | Amp Integration (`ampcode`) [​](https://help.router-for.me/configuration/options.html#amp-integration-ampcode) --------------------------------------------------------------------------------------------------------------- | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `ampcode.upstream-url` | string | `""` | Upstream URL for Amp CLI OAuth/management. | | `ampcode.upstream-api-key` | string | `""` | Override API key for Amp upstream. | | `ampcode.upstream-api-keys[].upstream-api-key` | string | `""` | Upstream key for mapped clients. | | `ampcode.upstream-api-keys[].api-keys` | string\[\] | `[]` | Client keys routed to that upstream key. | | `ampcode.restrict-management-to-localhost` | boolean | `false` | Restrict Amp management routes to localhost. | | `ampcode.force-model-mappings` | boolean | `false` | Force model mappings before checking local API keys. | | `ampcode.model-mappings[].from` | string | `""` | Amp-requested model. | | `ampcode.model-mappings[].to` | string | `""` | Local available model to route to. | OAuth Model Controls [​](https://help.router-for.me/configuration/options.html#oauth-model-controls) ----------------------------------------------------------------------------------------------------- | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `oauth-model-alias` | object | `{}` | Rename models per channel (gemini-cli, vertex, aistudio, antigravity, claude, codex, qwen, iflow). | | `oauth-model-alias.*.*.fork` | boolean | `false` | When `true`, keep original and add alias as extra model. | | `oauth-excluded-models` | object | `{}` | Exclude models per channel; wildcards supported. | Payload Rules [​](https://help.router-for.me/configuration/options.html#payload-rules) --------------------------------------------------------------------------------------- | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `payload.default[].models[].name` | string | `""` | Matching model name (wildcards ok). | | `payload.default[].models[].protocol` | string | `""` | Restrict to protocol: `openai`/`gemini`/`claude`/`codex`/`antigravity`. | | `payload.default[].params` | object | `{}` | JSON path → value applied when missing. | | `payload.default-raw[].models[].name` | string | `""` | Matching model name (wildcards). | | `payload.default-raw[].models[].protocol` | string | `""` | Restrict to protocol. | | `payload.default-raw[].params` | object | `{}` | JSON path → raw JSON value applied when missing (must be valid JSON). | | `payload.override[].models[].name` | string | `""` | Matching model name (wildcards). | | `payload.override[].models[].protocol` | string | `""` | Restrict to protocol. | | `payload.override[].params` | object | `{}` | JSON path → value always overwritten. | | `payload.override-raw[].models[].name` | string | `""` | Matching model name (wildcards). | | `payload.override-raw[].models[].protocol` | string | `""` | Restrict to protocol. | | `payload.override-raw[].params` | object | `{}` | JSON path → raw JSON value always overwritten (must be valid JSON). | | `payload.filter[].models[].name` | string | `""` | Matching model name (wildcards). | | `payload.filter[].models[].protocol` | string | `""` | Restrict to protocol. | | `payload.filter[].params` | string\[\] | `[]` | JSON paths to remove from payload. | --- # Authentication Directory | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/auth-dir.html#VPContent) Return to top Authentication Directory [​](https://help.router-for.me/configuration/auth-dir.html#authentication-directory) ============================================================================================================== The `auth-dir` parameter specifies where authentication tokens are stored. When you run the login command, the application will create JSON files in this directory containing the authentication tokens for your Google accounts. Multiple accounts can be used for load balancing. --- # Hot Reloading | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/hot-reloading.html#VPContent) Return to top Hot Reloading [​](https://help.router-for.me/configuration/hot-reloading.html#hot-reloading) ============================================================================================= The server watches the config file and the `auth-dir` for changes and reloads clients and settings automatically. You can add or remove `Gemini CLI` / `Codex` / `Cluade Code` / `Qwen Code` / `iFlow` token JSON files while the server is running; no restart is required. --- # Git-backed Configuration and Token Store | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/storage/git.html#VPContent) Return to top Git-backed Configuration and Token Store [​](https://help.router-for.me/configuration/storage/git.html#git-backed-configuration-and-token-store) ================================================================================================================================================= The application can be configured to use a Git repository as a backend for storing both the `config.yaml` file and the authentication tokens from the `auth-dir`. This allows for centralized management and versioning of your configuration. To enable this feature, set the `GITSTORE_GIT_URL` environment variable to the URL of your Git repository. **Environment Variables** | Variable | Required | Default | Description | | --- | --- | --- | --- | | `MANAGEMENT_PASSWORD` | Yes | | The password for management webui. | | `GITSTORE_GIT_URL` | Yes | | The HTTPS URL of the Git repository to use. | | `GITSTORE_LOCAL_PATH` | No | Current working directory | The local path where the Git repository will be cloned. Inside Docker, this defaults to `/CLIProxyAPI`. | | `GITSTORE_GIT_USERNAME` | No | | The username for Git authentication. | | `GITSTORE_GIT_TOKEN` | No | | The personal access token (or password) for Git authentication. | **How it Works** 1. **Cloning:** On startup, the application clones the remote Git repository to the `GITSTORE_LOCAL_PATH`. 2. **Configuration:** It then looks for a `config.yaml` inside a `config` directory within the cloned repository. 3. **Bootstrapping:** If `config/config.yaml` does not exist in the repository, the application will copy the local `config.example.yaml` to that location, commit, and push it to the remote repository as an initial configuration. You must have `config.example.yaml` available. 4. **Token Sync:** The `auth-dir` is also managed within this repository. Any changes to authentication tokens (e.g., through a new login) are automatically committed and pushed to the remote Git repository. --- # PostgreSQL-backed Configuration and Token Store | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/storage/pgsql.html#VPContent) Return to top PostgreSQL-backed Configuration and Token Store [​](https://help.router-for.me/configuration/storage/pgsql.html#postgresql-backed-configuration-and-token-store) ================================================================================================================================================================= You can also persist configuration and authentication data in PostgreSQL when running CLIProxyAPI in hosted environments that favor managed databases over local files. **Environment Variables** | Variable | Required | Default | Description | | --- | --- | --- | --- | | `MANAGEMENT_PASSWORD` | Yes | | Password for the management web UI (required when remote management is enabled). | | `PGSTORE_DSN` | Yes | | PostgreSQL connection string (e.g. `postgresql://user:pass@host:5432/db`). | | `PGSTORE_SCHEMA` | No | public | Schema where the tables will be created. Leave empty to use the default schema. | | `PGSTORE_LOCAL_PATH` | No | Current working directory | Root directory for the local mirror; the server writes to `/pgstore`. If unset and CWD is unavailable, `/tmp/pgstore` is used. | **How it Works** 1. **Initialization:** On startup the server connects via `PGSTORE_DSN`, ensures the schema exists, and creates the `config_store` / `auth_store` tables when missing. 2. **Local Mirror:** A writable cache at `/pgstore` mirrors `config/config.yaml` and `auths/` so the rest of the application can reuse the existing file-based logic. 3. **Bootstrapping:** If no configuration row exists, `config.example.yaml` seeds the database using the fixed identifier `config`. 4. **Token Sync:** Changes flow both ways—file updates are written to PostgreSQL and database records are mirrored back to disk so watchers and management APIs continue to operate. --- # Object Storage-backed Configuration and Token Store | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/storage/s3.html#VPContent) Return to top Object Storage-backed Configuration and Token Store [​](https://help.router-for.me/configuration/storage/s3.html#object-storage-backed-configuration-and-token-store) ====================================================================================================================================================================== An S3-compatible object storage service can host configuration and authentication records. **Environment Variables** | Variable | Required | Default | Description | | --- | --- | --- | --- | | `MANAGEMENT_PASSWORD` | Yes | | Password for the management web UI (required when remote management is enabled). | | `OBJECTSTORE_ENDPOINT` | Yes | | Object storage endpoint. Include `http://` or `https://` to force the protocol (omitted scheme → HTTPS). | | `OBJECTSTORE_BUCKET` | Yes | | Bucket that stores `config/config.yaml` and `auths/*.json`. | | `OBJECTSTORE_ACCESS_KEY` | Yes | | Access key ID for the object storage account. | | `OBJECTSTORE_SECRET_KEY` | Yes | | Secret key for the object storage account. | | `OBJECTSTORE_LOCAL_PATH` | No | Current working directory | Root directory for the local mirror; the server writes to `/objectstore`. If unset, defaults to current CWD. | **How it Works** 1. **Startup:** The endpoint is parsed (respecting any scheme prefix), a MinIO-compatible client is created in path-style mode, and the bucket is created when missing. 2. **Local Mirror:** A writable cache at `/objectstore` mirrors `config/config.yaml` and `auths/`. 3. **Bootstrapping:** When `config/config.yaml` is absent in the bucket, the server copies `config.example.yaml`, uploads it, and uses it as the initial configuration. 4. **Sync:** Changes to configuration or auth files are uploaded to the bucket, and remote updates are mirrored back to disk, keeping watchers and management APIs in sync. --- # Gemini CLI (Gemini via OAuth): | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/provider/gemini-cli.html#VPContent) Return to top Gemini CLI (Gemini via OAuth): [​](https://help.router-for.me/configuration/provider/gemini-cli.html#gemini-cli-gemini-via-oauth) ================================================================================================================================== bash ./cli-proxy-api --login If you are an existing `Gemini Code` user, you may need to specify a project ID: bash ./cli-proxy-api --login --project_id The local OAuth callback uses port `8085`. Options: add `--no-browser` to print the login URL instead of opening a browser. The local OAuth callback uses port `8085`. --- # Antigravity (Antigravity via OAuth): | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/provider/antigravity.html#VPContent) Return to top Antigravity (Antigravity via OAuth): [​](https://help.router-for.me/configuration/provider/antigravity.html#antigravity-antigravity-via-oauth) =============================================================================================================================================== bash ./cli-proxy-api --antigravity-login The local OAuth callback uses port `51121`. Options: add `--no-browser` to print the login URL instead of opening a browser. The local OAuth callback uses port `51121`. --- # Claude Code (Anthropic via OAuth): | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/provider/claude-code.html#VPContent) Return to top Claude Code (Anthropic via OAuth): [​](https://help.router-for.me/configuration/provider/claude-code.html#claude-code-anthropic-via-oauth) =========================================================================================================================================== bash ./cli-proxy-api --claude-login Options: add `--no-browser` to print the login URL instead of opening a browser. The local OAuth callback uses port `54545`. --- # Codex (OpenAI via OAuth): | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/provider/codex.html#VPContent) Return to top Codex (OpenAI via OAuth): [​](https://help.router-for.me/configuration/provider/codex.html#codex-openai-via-oauth) =================================================================================================================== bash ./cli-proxy-api --codex-login Options: add `--no-browser` to print the login URL instead of opening a browser. The local OAuth callback uses port `1455`. --- # AI Studio Instructions | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/provider/ai-studio.html#VPContent) Return to top AI Studio Instructions [​](https://help.router-for.me/configuration/provider/ai-studio.html#ai-studio-instructions) ==================================================================================================================== You can use this service as a backend for [this AI Studio App](https://aistudio.google.com/apps/drive/1CPW7FpWGsDZzkaYgYOyXQ_6FWgxieLmL) . Follow the steps below to configure it: 1. **Start the CLIProxyAPI Service**: Ensure your CLIProxyAPI instance is running, either locally or remotely. 2. **Access the AI Studio App**: Log in to your Google account in your browser, then open the following link: * [https://aistudio.google.com/apps/drive/1CPW7FpWGsDZzkaYgYOyXQ\_6FWgxieLmL](https://aistudio.google.com/apps/drive/1CPW7FpWGsDZzkaYgYOyXQ_6FWgxieLmL) **Note**: If you are using the Brave browser, you may need to disable its shields feature as it can block the WebSocket connection. This issue can also occur with other ad-blockers. Connection Configuration [​](https://help.router-for.me/configuration/provider/ai-studio.html#connection-configuration) ------------------------------------------------------------------------------------------------------------------------ By default, the AI Studio App attempts to connect to a local CLIProxyAPI instance at `ws://127.0.0.1:8317`. * **Connecting to a Remote Service**: If you need to connect to a remotely deployed CLIProxyAPI, modify the `config.ts` file in the AI Studio App to update the `WEBSOCKET_PROXY_URL` value. * Use the `wss://` protocol if your remote service has SSL enabled. * Use the `ws://` protocol if SSL is not enabled. Authentication Configuration [​](https://help.router-for.me/configuration/provider/ai-studio.html#authentication-configuration) -------------------------------------------------------------------------------------------------------------------------------- By default, WebSocket connections to CLIProxyAPI do not require authentication. * **Enable Authentication on the CLIProxyAPI Server**: In your `config.yaml` file, set `ws_auth` to `true`. * **Configure Authentication on the AI Studio Client**: In the `config.ts` file of the AI Studio App, set the `JWT_TOKEN` value to your authentication token. --- # iFlow (iFlow via OAuth): | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/provider/iflow.html#VPContent) Return to top iFlow (iFlow via OAuth): [​](https://help.router-for.me/configuration/provider/iflow.html#iflow-iflow-via-oauth) ================================================================================================================= bash ./cli-proxy-api --iflow-login Options: add `--no-browser` to print the login URL instead of opening a browser. The local OAuth callback uses port `11451`. --- # OpenAI Compatibility Providers | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/provider/openai-compatibility.html#VPContent) Return to top OpenAI Compatibility Providers [​](https://help.router-for.me/configuration/provider/openai-compatibility.html#openai-compatibility-providers) =============================================================================================================================================== Configure upstream OpenAI-compatible providers (e.g., OpenRouter) via `openai-compatibility`. * name: provider identifier used internally * base-url: provider base URL * api-key-entries: list of API key entries with optional per-key proxy configuration (recommended and persisted) * models: list of mappings from upstream model `name` to local `alias` > Compatibility: legacy `api-keys` are migrated into `api-key-entries` on load and removed when the config is saved; use `api-key-entries` going forward. Example with per-key proxy support: yaml openai-compatibility: - name: "openrouter" base-url: "https://openrouter.ai/api/v1" api-key-entries: - api-key: "sk-or-v1-...b780" proxy-url: "socks5://proxy.example.com:1080" - api-key: "sk-or-v1-...b781" models: - name: "moonshotai/kimi-k2:free" alias: "kimi-k2" Usage: Call OpenAI's endpoint `/v1/chat/completions` with `model` set to the alias (e.g., `kimi-k2`). The proxy routes to the configured provider/model automatically. --- # Qwen (Qwen Chat via OAuth): | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/provider/qwen-code.html#VPContent) Return to top Qwen (Qwen Chat via OAuth): [​](https://help.router-for.me/configuration/provider/qwen-code.html#qwen-qwen-chat-via-oauth) =========================================================================================================================== bash ./cli-proxy-api --qwen-login Options: add `--no-browser` to print the login URL instead of opening a browser. Use the Qwen Chat's OAuth device flow. --- # Claude Code Compatibility Providers | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/provider/claude-code-compatibility.html#VPContent) Return to top Claude Code Compatibility Providers [​](https://help.router-for.me/configuration/provider/claude-code-compatibility.html#claude-code-compatibility-providers) ============================================================================================================================================================== Configure upstream Claude Code compatible providers via `claude-api-key`. * api-key: API key for the provider * base-url: provider base URL * proxy-url: optional proxy URL for the provider * models: list of mappings from upstream model `name` to local `alias` Example: yaml claude-api-key: - api-key: "sk-atSM..." # use the official claude API key, no need to set the base url - api-key: "sk-atSM..." base-url: "https://www.example.com" # use the custom claude API endpoint proxy-url: "socks5://proxy.example.com:1080" # optional: per-key proxy override models: - name: "claude-3-5-sonnet-20241022" # upstream model name alias: "claude-sonnet-latest" # client alias mapped to the upstream model NOTE If you set the `api-key` only, the `base-url` will be set to `https://api.anthropic.com` automatically. The `base-url` is only needed if you are using a third-party Claude Code compatible provider. --- # Gemini Compatibility Providers | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/provider/gemini-compatibility.html#VPContent) Return to top Gemini Compatibility Providers [​](https://help.router-for.me/configuration/provider/gemini-compatibility.html#gemini-compatibility-providers) =============================================================================================================================================== Configure upstream Gemini compatible providers via `gemini-api-key`. * api-key: API key for the provider * base-url: provider base URL * proxy-url: optional proxy URL for the provider * headers: optional extra HTTP headers sent to the overridden Gemini endpoint only Example: yaml 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" # use the official Gemini API key, no need to set the base url NOTE If you set the `api-key` only, the `base-url` will be set to `https://generativelanguage.googleapis.com` automatically. The `base-url` is only needed if you are using a third-party Gemini-compatible provider. --- # Thinking Budgets via Model Name Parentheses | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/thinking.html#VPContent) Return to top Thinking Budgets via Model Name Parentheses [​](https://help.router-for.me/configuration/thinking.html#thinking-budgets-via-model-name-parentheses) ==================================================================================================================================================== Append `(value)` to the model name to control the thinking budget or reasoning effort. The proxy strips the parentheses before routing and applies the derived settings to the request. Accepted Values [​](https://help.router-for.me/configuration/thinking.html#accepted-values) -------------------------------------------------------------------------------------------- * `(number)`: explicit thinking budget (provider-native tokens); clamped to the model’s supported range. * `(level)`: preset reasoning effort (case-insensitive): | Level | Approx. Budget | Purpose | | --- | --- | --- | | `minimal` | 512 | Lowest cost reasoning | | `low` | 1024 | Fast reasoning | | `medium` | 8192 | Default reasoning depth | | `high` | 24576 | Deep reasoning | | `xhigh` | 32768 | Extra-deep reasoning | | `auto` | Dynamic (-1 when allowed, else mid/min) | Let the provider choose | | `none` | 0 (clamped to min when zero is disallowed) | Disable thinking | * Empty `()` is ignored. For `provider://model` forms, place the parentheses after the model (e.g., `openrouter://gemini-3-pro-preview(high)`). How It’s Applied [​](https://help.router-for.me/configuration/thinking.html#how-it-s-applied) ---------------------------------------------------------------------------------------------- * Only models that advertise thinking keep these settings; unsupported models simply drop the suffix without injecting thinking fields. * Gemini (standard & CLI): writes `generationConfig.thinkingConfig.thinkingBudget` (or `request.generationConfig.thinkingConfig...` for CLI) after clamping. `include_thoughts` is left unchanged. Models with default thinking (e.g., `gemini-3-pro-preview`) still auto-enable thinking when missing; the parentheses budget overrides the default. * Claude API: when a budget/level is provided, sets `thinking.type=enabled` with normalized `thinking.budget_tokens` and bumps `max_tokens` if needed. * OpenAI/Codex/Qwen/iFlow/OpenRouter: reasoning levels/`auto`/`none` overwrite `reasoning_effort` (chat) or `reasoning.effort` (Responses). Numeric budgets do not change reasoning\_effort for these protocols. * Level-based models enforce their supported effort levels; unsupported values return HTTP 400. Examples [​](https://help.router-for.me/configuration/thinking.html#examples) ------------------------------------------------------------------------------ * Dynamic budget with Gemini: bash curl -X POST http://localhost:8317/v1/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3-pro-preview(auto)", "messages": [{ "role": "user", "content": "Summarize the key points" }] }' # Normalizes to gemini-3-pro-preview and sets thinkingBudget=-1 (clamped if dynamic is not allowed); include_thoughts stays unchanged. * High reasoning effort for Responses: bash curl -X POST http://localhost:8317/v1/responses \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.1(high)", "input": "List three improvements" }' # Routes as gpt-5.1 and overwrites reasoning.effort="high". * Disable thinking (clamped when zero is not allowed): bash model=claude-sonnet-4.5(none) # Sets thinking.budget_tokens to 0 when allowed; otherwise clamps to the model minimum. --- # Codex Compatibility Providers | CLIProxyAPI [Skip to content](https://help.router-for.me/configuration/provider/codex-compatibility.html#VPContent) Return to top Codex Compatibility Providers [​](https://help.router-for.me/configuration/provider/codex-compatibility.html#codex-compatibility-providers) ============================================================================================================================================ Configure upstream Codex compatible providers via `codex-api-key`. * api-key: API key for the provider * base-url: provider base URL * proxy-url: optional proxy URL for the provider Example: yaml codex-api-key: - api-key: "sk-atSM..." base-url: "https://www.example.com" # use the custom codex API endpoint proxy-url: "socks5://proxy.example.com:1080" # optional: per-key proxy override --- # Web UI | CLIProxyAPI [Skip to content](https://help.router-for.me/management/webui.html#VPContent) Return to top Web UI [​](https://help.router-for.me/management/webui.html#web-ui) ==================================================================== Project URL: [Cli-Proxy-API-Management-Center](https://github.com/router-for-me/Cli-Proxy-API-Management-Center) An official web-based management center for CLIProxyAPI. Base path: `http://localhost:8317/management.html` Set `remote-management.disable-control-panel` to `true` if you prefer to host the management UI elsewhere; the server will skip downloading `management.html` and `/management.html` will return 404. You can set the `MANAGEMENT_STATIC_PATH` environment variable to choose the directory where `management.html` is stored. Use a custom Web UI [​](https://help.router-for.me/management/webui.html#use-a-custom-web-ui) ---------------------------------------------------------------------------------------------- You can point the server to your own GitHub repository for the management panel: yaml remote-management: panel-github-repository: "https://github.com/your-org/your-management-ui" * Repository URL form: `https://github.com//`; the server automatically converts it to `https://api.github.com/repos///releases/latest`. * API URL form: set it directly to `https://api.github.com/repos///releases/latest`. * The updater periodically checks the latest release, looks for an asset named `management.html`, and downloads it to the static directory (default `static/` beside the config file or the path set via `MANAGEMENT_STATIC_PATH`). If the asset includes a `digest` field (`sha256:` recommended), it will be used for integrity validation. How to publish a custom Web UI on GitHub [​](https://help.router-for.me/management/webui.html#how-to-publish-a-custom-web-ui-on-github) ---------------------------------------------------------------------------------------------------------------------------------------- 1. Build your custom panel and produce a single `management.html` (bundle assets into one file if possible). 2. Create a GitHub repository and push your code. 3. Create a release (the updater targets `latest`) and upload assets: * Must include **`management.html`**. * Strongly recommended: add a `digest` metadata field with `sha256:` for checksum verification. 4. Set `remote-management.panel-github-repository` in CLIProxyAPI to the repository URL or the API URL. 5. Restart or hot-reload the config; the server will fetch and replace the management panel automatically. --- # Desktop GUI | CLIProxyAPI [Skip to content](https://help.router-for.me/management/gui.html#VPContent) Return to top Desktop GUI [​](https://help.router-for.me/management/gui.html#desktop-gui) ============================================================================ Project URL: [EasyCLI](https://github.com/router-for-me/EasyCLI) A cross-platform desktop GUI client for CLIProxyAPI. --- # Claude Code | CLIProxyAPI [Skip to content](https://help.router-for.me/agent-client/claude-code.html#VPContent) Return to top Claude Code [​](https://help.router-for.me/agent-client/claude-code.html#claude-code) ====================================================================================== Start CLIProxyAPI server, and then set these environment variables: * `ANTHROPIC_BASE_URL` * `ANTHROPIC_AUTH_TOKEN` * `ANTHROPIC_DEFAULT_OPUS_MODEL` * `ANTHROPIC_DEFAULT_SONNET_MODEL` * `ANTHROPIC_DEFAULT_HAIKU_MODEL` Or set these environment variables for version 1.x.x * `ANTHROPIC_MODEL` * `ANTHROPIC_SMALL_FAST_MODEL` Using Gemini models: bash export ANTHROPIC_BASE_URL=http://127.0.0.1:8317 export ANTHROPIC_AUTH_TOKEN=sk-dummy # version 2.x.x export ANTHROPIC_DEFAULT_OPUS_MODEL=gemini-2.5-pro export ANTHROPIC_DEFAULT_SONNET_MODEL=gemini-2.5-flash export ANTHROPIC_DEFAULT_HAIKU_MODEL=gemini-2.5-flash-lite # version 1.x.x export ANTHROPIC_MODEL=gemini-2.5-pro export ANTHROPIC_SMALL_FAST_MODEL=gemini-2.5-flash Using OpenAI GPT 5 models: bash export ANTHROPIC_BASE_URL=http://127.0.0.1:8317 export ANTHROPIC_AUTH_TOKEN=sk-dummy # version 2.x.x export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5(high) export ANTHROPIC_DEFAULT_SONNET_MODEL=gpt-5(medium) export ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-5(minimal) # we don't recommend using gpt-5(minimal), use qwen3-coder-flash or gemini-2.5-flash-lite instead # version 1.x.x export ANTHROPIC_MODEL=gpt-5 export ANTHROPIC_SMALL_FAST_MODEL=gpt-5(minimal) # we don't recommend using gpt-5(minimal), use qwen3-coder-flash or gemini-2.5-flash-lite instead Using OpenAI GPT 5 Codex models: bash export ANTHROPIC_BASE_URL=http://127.0.0.1:8317 export ANTHROPIC_AUTH_TOKEN=sk-dummy # version 2.x.x export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5-codex(high) export ANTHROPIC_DEFAULT_SONNET_MODEL=gpt-5-codex(medium) export ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-5-codex(low) # we don't recommend using gpt-5-codex(low), use qwen3-coder-flash or gemini-2.5-flash-lite instead # version 1.x.x export ANTHROPIC_MODEL=gpt-5-codex export ANTHROPIC_SMALL_FAST_MODEL=gpt-5-codex(low) # we don't recommend using gpt-5-codex(low), use qwen3-coder-flash or gemini-2.5-flash-lite instead Using Claude models: bash export ANTHROPIC_BASE_URL=http://127.0.0.1:8317 export ANTHROPIC_AUTH_TOKEN=sk-dummy # version 2.x.x export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-1-20250805 export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5-20250929 export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-3-5-haiku-20241022 # version 1.x.x export ANTHROPIC_MODEL=claude-sonnet-4-20250514 export ANTHROPIC_SMALL_FAST_MODEL=claude-3-5-haiku-20241022 Using Qwen models: bash export ANTHROPIC_BASE_URL=http://127.0.0.1:8317 export ANTHROPIC_AUTH_TOKEN=sk-dummy # version 2.x.x export ANTHROPIC_DEFAULT_OPUS_MODEL=qwen3-coder-plus export ANTHROPIC_DEFAULT_SONNET_MODEL=qwen3-coder-plus export ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen3-coder-flash # version 1.x.x export ANTHROPIC_MODEL=qwen3-coder-plus export ANTHROPIC_SMALL_FAST_MODEL=qwen3-coder-flash Using iFlow models: bash export ANTHROPIC_BASE_URL=http://127.0.0.1:8317 export ANTHROPIC_AUTH_TOKEN=sk-dummy # version 2.x.x export ANTHROPIC_DEFAULT_OPUS_MODEL=qwen3-max export ANTHROPIC_DEFAULT_SONNET_MODEL=qwen3-coder-plus export ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen3-235b-a22b-instruct # version 1.x.x export ANTHROPIC_MODEL=qwen3-max export ANTHROPIC_SMALL_FAST_MODEL=qwen3-235b-a22b-instruct --- # Management API | CLIProxyAPI [Skip to content](https://help.router-for.me/management/api.html#VPContent) Return to top Management API [​](https://help.router-for.me/management/api.html#management-api) ================================================================================== Base path: `http://localhost:8317/v0/management` This API manages the CLI Proxy API’s runtime configuration and authentication files. All changes are persisted to the YAML config file and hot‑reloaded by the service. Note: The following options cannot be modified via API and must be set in the config file (restart if needed): * `allow-remote-management` * `remote-management-key` (if plaintext is detected at startup, it is automatically bcrypt‑hashed and written back to the config) Authentication [​](https://help.router-for.me/management/api.html#authentication) ---------------------------------------------------------------------------------- * All requests (including localhost) must provide a valid management key. * Remote access requires enabling remote management in the config: `allow-remote-management: true`. * Provide the management key (in plaintext) via either: * `Authorization: Bearer ` * `X-Management-Key: ` Additional notes: * Setting the `MANAGEMENT_PASSWORD` environment variable registers an additional plaintext management secret and forces remote management to stay enabled even when `allow-remote-management` is false. The value is never persisted and must be sent via the same `Authorization`/`X-Management-Key` headers. * When the proxy starts with `cliproxy run --password ` or via the SDK’s `WithLocalManagementPassword`, localhost clients (`127.0.0.1`/`::1`) may present that local-only password through the same headers; it only lives in memory and is not written to disk. * The Management API returns 404 only when both `remote-management.secret-key` is empty and `MANAGEMENT_PASSWORD` is unset. * For remote IPs, 5 consecutive authentication failures trigger a temporary ban (~30 minutes) before further attempts are allowed. If a plaintext key is detected in the config at startup, it will be bcrypt‑hashed and written back to the config file automatically. Request/Response Conventions [​](https://help.router-for.me/management/api.html#request-response-conventions) -------------------------------------------------------------------------------------------------------------- * Content-Type: `application/json` (unless otherwise noted). * Boolean/int/string updates: request body is `{ "value": }`. * Array PUT: either a raw array (e.g. `["a","b"]`) or `{ "items": [ ... ] }`. * Array PATCH: supports `{ "old": "k1", "new": "k2" }` or `{ "index": 0, "value": "k2" }`. * Object-array PATCH: supports matching by index or by key field (specified per endpoint). Endpoints [​](https://help.router-for.me/management/api.html#endpoints) ------------------------------------------------------------------------ ### Usage Statistics [​](https://help.router-for.me/management/api.html#usage-statistics) * GET `/usage` — Retrieve aggregated in-memory request metrics * Response: json { "usage": { "total_requests": 24, "success_count": 22, "failure_count": 2, "total_tokens": 13890, "requests_by_day": { "2024-05-20": 12 }, "requests_by_hour": { "09": 4, "18": 8 }, "tokens_by_day": { "2024-05-20": 9876 }, "tokens_by_hour": { "09": 1234, "18": 865 }, "apis": { "POST /v1/chat/completions": { "total_requests": 12, "total_tokens": 9021, "models": { "gpt-4o-mini": { "total_requests": 8, "total_tokens": 7123, "details": [\ {\ "timestamp": "2024-05-20T09:15:04.123456Z",\ "source": "openai",\ "auth_index": "a1b2c3d4e5f67890",\ "tokens": {\ "input_tokens": 523,\ "output_tokens": 308,\ "reasoning_tokens": 0,\ "cached_tokens": 0,\ "total_tokens": 831\ },\ "failed": false\ }\ ] } } } } }, "failed_requests": 2 } * Notes: * Statistics are recalculated for every request that reports token usage; data resets when the server restarts. * Hourly counters fold all days into the same hour bucket (`00`–`23`). * The top-level `failed_requests` repeats `usage.failure_count` for convenience when polling. * GET `/usage/export` — Export a complete usage snapshot (backup/migration) * Response: json { "version": 1, "exported_at": "2025-12-26T03:49:51Z", "usage": { "total_requests": 24, "success_count": 22, "failure_count": 2, "total_tokens": 13890, "requests_by_day": {}, "requests_by_hour": {}, "tokens_by_day": {}, "tokens_by_hour": {}, "apis": {} } } * Notes: * `exported_at` is UTC time (RFC 3339). * The `usage` object uses the same schema as `GET /usage`’s `usage` field. * POST `/usage/import` — Import and merge a usage snapshot into memory (deduplicated) * Request: bash curl -X POST -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ --data-binary @usage-export.json \ http://localhost:8317/v0/management/usage/import * Response: json { "added": 10, "skipped": 2, "total_requests": 123, "failed_requests": 4 } * Notes: * This endpoint merges (does not overwrite); duplicate request details are skipped and counted in `skipped`. * You may POST the full JSON returned by `GET /usage/export` directly (`exported_at` is ignored). * `version` currently supports `1` (and also accepts omitted/`0` for compatibility). ### Config [​](https://help.router-for.me/management/api.html#config) * GET `/config` — Get the full config * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/config * Response: 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 response no longer includes `generative-language-api-key`; use `GET /generative-language-api-key` if you need a pure-string view. * When no configuration is loaded yet the handler returns `{}`. ### Latest Version [​](https://help.router-for.me/management/api.html#latest-version) * GET `/latest-version` — Fetch the latest release version string (no asset download) * Request: bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/latest-version * Response: json { "latest-version": "v1.2.3" } * Notes: * Data is retrieved from `https://api.github.com/repos/router-for-me/CLIProxyAPI/releases/latest` with `User-Agent: CLIProxyAPI`. * When `proxy-url` is set, the request honors that proxy; the endpoint only returns the version value and does not download release assets. ### Debug [​](https://help.router-for.me/management/api.html#debug) * GET `/debug` — Get the current debug state * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/debug * Response: json { "debug": false } * PUT/PATCH `/debug` — Set debug (boolean) * Request: bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":true}' \ http://localhost:8317/v0/management/debug * Response: json { "status": "ok" } ### Config YAML [​](https://help.router-for.me/management/api.html#config-yaml) * GET `/config.yaml` — Download the persisted YAML file as-is * Response headers: * `Content-Type: application/yaml; charset=utf-8` * `Cache-Control: no-store` * Response body: raw YAML stream preserving comments/formatting. * PUT `/config.yaml` — Replace the config with a YAML document * Request: bash curl -X PUT -H 'Content-Type: application/yaml' \ -H 'Authorization: Bearer ' \ --data-binary @config.yaml \ http://localhost:8317/v0/management/config.yaml * Response: json { "ok": true, "changed": ["config"] } * Notes: * The server validates the YAML by loading it before persisting; invalid configs return `422` with `{ "error": "invalid_config", "message": "..." }`. * Write failures return `500` with `{ "error": "write_failed", "message": "..." }`. ### Logging to File [​](https://help.router-for.me/management/api.html#logging-to-file) * GET `/logging-to-file` — Check whether file logging is enabled * Response: json { "logging-to-file": true } * PUT/PATCH `/logging-to-file` — Enable or disable file logging * Request: bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":false}' \ http://localhost:8317/v0/management/logging-to-file * Response: json { "status": "ok" } ### Log Files [​](https://help.router-for.me/management/api.html#log-files) * GET `/logs` — Stream recent log lines * Query params: * `after` (optional): Unix timestamp; only lines newer than this are returned. * Response: json { "lines": ["2024-05-20 12:00:00 info request accepted"], "line-count": 125, "latest-timestamp": 1716206400 } * Notes: * Requires file logging to be enabled; otherwise returns `{ "error": "logging to file disabled" }` with `400`. * When no log file exists yet the response contains empty `lines` and `line-count: 0`. * `latest-timestamp` is the largest parsed timestamp from this batch; if no timestamp is found it echoes the provided `after` (or `0`), so clients can pass it back unchanged for incremental polling. * `line-count` reflects the total number of lines scanned (including those filtered out by `after`) and can be used to detect whether new log data arrived. * DELETE `/logs` — Remove rotated log files and truncate the active log * Response: json { "success": true, "message": "Logs cleared successfully", "removed": 3 } ### Request Error Logs [​](https://help.router-for.me/management/api.html#request-error-logs) * GET `/request-error-logs` — List error request log files when request logging is disabled * Response: json { "files": [\ {\ "name": "error-2024-05-20.log",\ "size": 12345,\ "modified": 1716206400\ }\ ] } * Notes: * When `request-log` is enabled, this endpoint always returns an empty list. * Files are discovered under the same log directory and must start with `error-` and end with `.log`. * `modified` is the last modification time as a Unix timestamp. * GET `/request-error-logs/:name` — Download a specific error request log * Request: bash curl -H 'Authorization: Bearer ' \ -OJ 'http://localhost:8317/v0/management/request-error-logs/error-2024-05-20.log' * Notes: * `name` must be a safe filename (no `/` or `\`) and match an existing `error-*.log` entry; otherwise the server returns a validation or not-found error. * The handler performs a safety check to ensure the resolved path stays inside the log directory before streaming the file. ### Usage Statistics Toggle [​](https://help.router-for.me/management/api.html#usage-statistics-toggle) * GET `/usage-statistics-enabled` — Check whether telemetry collection is active * Response: json { "usage-statistics-enabled": true } * PUT/PATCH `/usage-statistics-enabled` — Enable or disable collection * Request: bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":true}' \ http://localhost:8317/v0/management/usage-statistics-enabled * Response: json { "status": "ok" } ### Proxy Server URL [​](https://help.router-for.me/management/api.html#proxy-server-url) * GET `/proxy-url` — Get the proxy URL string * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/proxy-url * Response: json { "proxy-url": "socks5://user:pass@127.0.0.1:1080/" } * PUT/PATCH `/proxy-url` — Set the proxy URL string * Request (PUT): bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":"socks5://user:pass@127.0.0.1:1080/"}' \ http://localhost:8317/v0/management/proxy-url * Request (PATCH): bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":"http://127.0.0.1:8080"}' \ http://localhost:8317/v0/management/proxy-url * Response: json { "status": "ok" } * DELETE `/proxy-url` — Clear the proxy URL * Request: bash curl -H 'Authorization: Bearer ' -X DELETE http://localhost:8317/v0/management/proxy-url * Response: json { "status": "ok" } ### Quota Exceeded Behavior [​](https://help.router-for.me/management/api.html#quota-exceeded-behavior) * GET `/quota-exceeded/switch-project` * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/quota-exceeded/switch-project * Response: json { "switch-project": true } * PUT/PATCH `/quota-exceeded/switch-project` — Boolean * Request: bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":false}' \ http://localhost:8317/v0/management/quota-exceeded/switch-project * Response: json { "status": "ok" } * GET `/quota-exceeded/switch-preview-model` * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/quota-exceeded/switch-preview-model * Response: json { "switch-preview-model": true } * PUT/PATCH `/quota-exceeded/switch-preview-model` — Boolean * Request: bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":true}' \ http://localhost:8317/v0/management/quota-exceeded/switch-preview-model * Response: json { "status": "ok" } ### API Keys (proxy service auth) [​](https://help.router-for.me/management/api.html#api-keys-proxy-service-auth) These endpoints update the inline `config-api-key` provider inside the `auth.providers` section of the configuration. Legacy top-level `api-keys` remain in sync automatically. * GET `/api-keys` — Return the full list * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/api-keys * Response: json { "api-keys": ["k1","k2","k3"] } * PUT `/api-keys` — Replace the full list * Request: bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '["k1","k2","k3"]' \ http://localhost:8317/v0/management/api-keys * Response: json { "status": "ok" } * PATCH `/api-keys` — Modify one item (`old/new` or `index/value`) * Request (by old/new): bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"old":"k2","new":"k2b"}' \ http://localhost:8317/v0/management/api-keys * Request (by index/value): bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"index":0,"value":"k1b"}' \ http://localhost:8317/v0/management/api-keys * Response: json { "status": "ok" } * DELETE `/api-keys` — Delete one (`?value=` or `?index=`) * Request (by value): bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/api-keys?value=k1' * Request (by index): bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/api-keys?index=0' * Response: json { "status": "ok" } ### Gemini API Key [​](https://help.router-for.me/management/api.html#gemini-api-key) * GET `/gemini-api-key` * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/gemini-api-key * Response: json { "gemini-api-key": [\ {"api-key":"AIzaSy...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":"AIzaSy...02","proxy-url":"socks5://proxy.example.com:1080","excluded-models":["gemini-pro-vision"]}\ ] } * PUT `/gemini-api-key` * Request (array form): bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '[{"api-key":"AIzaSy-1","headers":{"X-Custom-Header":"vendor-value"},"excluded-models":["gemini-1.5-flash"]},{"api-key":"AIzaSy-2","base-url":"https://custom.example.com","excluded-models":["gemini-pro-vision"]}]' \ http://localhost:8317/v0/management/gemini-api-key * Response: json { "status": "ok" } * PATCH `/gemini-api-key` * Request (update by index): bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"index":0,"value":{"api-key":"AIzaSy-1","base-url":"https://custom.example.com","headers":{"X-Custom-Header":"custom-value"},"proxy-url":"","excluded-models":["gemini-1.5-pro","gemini-pro-vision"]}}' \ http://localhost:8317/v0/management/gemini-api-key * Request (update by api-key match): bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"match":"AIzaSy-1","value":{"api-key":"AIzaSy-1","headers":{"X-Custom-Header":"custom-value"},"proxy-url":"socks5://proxy.example.com:1080","excluded-models":["gemini-1.5-pro-latest"]}}' \ http://localhost:8317/v0/management/gemini-api-key * Response: json { "status": "ok" } * DELETE `/gemini-api-key` * Request (by api-key): bash curl -H 'Authorization: Bearer ' -X DELETE \ 'http://localhost:8317/v0/management/gemini-api-key?api-key=AIzaSy-1' * Request (by index): bash curl -H 'Authorization: Bearer ' -X DELETE \ 'http://localhost:8317/v0/management/gemini-api-key?index=0' * Response: json { "status": "ok" } * Notes: * `excluded-models` is optional; the server lowercases, trims, deduplicates, and drops blank entries before saving. ### Codex API KEY (object array) [​](https://help.router-for.me/management/api.html#codex-api-key-object-array) * GET `/codex-api-key` — List all * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/codex-api-key * Response: json { "codex-api-key": [ { "api-key": "sk-a", "base-url": "https://codex.example.com/v1", "proxy-url": "socks5://proxy.example.com:1080", "headers": { "X-Team": "cli" }, "excluded-models": ["gpt-4o-mini"] } ] } * PUT `/codex-api-key` — Replace the list * Request: bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '[{"api-key":"sk-a","base-url":"https://codex.example.com/v1","proxy-url":"socks5://proxy.example.com:1080","headers":{"X-Team":"cli"},"excluded-models":["gpt-4o-mini","gpt-4.1-mini"]},{"api-key":"sk-b","base-url":"https://custom.example.com","proxy-url":"","headers":{"X-Env":"prod"},"excluded-models":["gpt-3.5-turbo"]}]' \ http://localhost:8317/v0/management/codex-api-key * Response: json { "status": "ok" } * PATCH `/codex-api-key` — Modify one (by `index` or `match`) * Request (by index): bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com","proxy-url":"","headers":{"X-Env":"stage"},"excluded-models":["gpt-3.5-turbo-instruct"]}}' \ http://localhost:8317/v0/management/codex-api-key * Request (by match): bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":"https://codex.example.com/v1","proxy-url":"socks5://proxy.example.com:1080","headers":{"X-Team":"cli"},"excluded-models":["gpt-4o-mini","gpt-4.1"]}}' \ http://localhost:8317/v0/management/codex-api-key * Response: json { "status": "ok" } * DELETE `/codex-api-key` — Delete one (`?api-key=` or `?index=`) * Request (by api-key): bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?api-key=sk-b2' * Request (by index): bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?index=0' * Response: json { "status": "ok" } * Notes: * `base-url` is required; submitting an empty `base-url` in PUT/PATCH removes the entry. * `headers` lets you attach custom HTTP headers per key. Empty keys/values are stripped automatically. * `excluded-models` accepts model identifiers to block for this provider; the server lowercases, trims, deduplicates, and drops blank entries. ### Request Retry Count [​](https://help.router-for.me/management/api.html#request-retry-count) * GET `/request-retry` — Get integer * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/request-retry * Response: json { "request-retry": 3 } * PUT/PATCH `/request-retry` — Set integer * Request: bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":5}' \ http://localhost:8317/v0/management/request-retry * Response: json { "status": "ok" } ### Max Retry Interval [​](https://help.router-for.me/management/api.html#max-retry-interval) * GET `/max-retry-interval` — Get the maximum retry interval in seconds * Request: bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/max-retry-interval * Response: json { "max-retry-interval": 30 } * PUT/PATCH `/max-retry-interval` — Set the maximum retry interval in seconds * Request: bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":60}' \ http://localhost:8317/v0/management/max-retry-interval * Response: json { "status": "ok" } ### Request Log [​](https://help.router-for.me/management/api.html#request-log) * GET `/request-log` — Get boolean * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/request-log * Response: json { "request-log": false } * PUT/PATCH `/request-log` — Set boolean * Request: bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":true}' \ http://localhost:8317/v0/management/request-log * Response: json { "status": "ok" } ### WebSocket Authentication (`ws-auth`) [​](https://help.router-for.me/management/api.html#websocket-authentication-ws-auth) * GET `/ws-auth` — Check whether the WebSocket gateway enforces authentication * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/ws-auth * Response: json { "ws-auth": true } * PUT/PATCH `/ws-auth` — Enable or disable authentication for `/ws/*` endpoints * Request: bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":false}' \ http://localhost:8317/v0/management/ws-auth * Response: json { "status": "ok" } * Notes: * When toggled from `false` → `true`, the server terminates any existing WebSocket sessions so that reconnections must supply valid API credentials. * Disabling authentication leaves current sessions untouched but future connections will skip the auth middleware until re-enabled. ### Claude API KEY (object array) [​](https://help.router-for.me/management/api.html#claude-api-key-object-array) * GET `/claude-api-key` — List all * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/claude-api-key * Response: json { "claude-api-key": [ { "api-key": "sk-a", "base-url": "https://example.com/api", "proxy-url": "socks5://proxy.example.com:1080", "headers": { "X-Workspace": "team-a" }, "excluded-models": ["claude-3-opus"] } ] } * PUT `/claude-api-key` — Replace the list * Request: bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '[{"api-key":"sk-a","proxy-url":"socks5://proxy.example.com:1080","headers":{"X-Workspace":"team-a"},"excluded-models":["claude-3-opus"]},{"api-key":"sk-b","base-url":"https://c.example.com","proxy-url":"","headers":{"X-Env":"prod"},"excluded-models":["claude-3-sonnet","claude-3-5-haiku"]}]' \ http://localhost:8317/v0/management/claude-api-key * Response: json { "status": "ok" } * PATCH `/claude-api-key` — Modify one (by `index` or `match`) * Request (by index): bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com","proxy-url":"","headers":{"X-Env":"stage"},"excluded-models":["claude-3.7-sonnet"]}}' \ http://localhost:8317/v0/management/claude-api-key * Request (by match): bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":"","proxy-url":"socks5://proxy.example.com:1080","headers":{"X-Workspace":"team-a"},"excluded-models":["claude-3-opus","claude-3.5-sonnet"]}}' \ http://localhost:8317/v0/management/claude-api-key * Response: json { "status": "ok" } * DELETE `/claude-api-key` — Delete one (`?api-key=` or `?index=`) * Request (by api-key): bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?api-key=sk-b2' * Request (by index): bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?index=0' * Response: json { "status": "ok" } * Notes: * `headers` is optional; empty/blank pairs are removed automatically. To drop a header, simply omit it in your update payload. * `excluded-models` lets you block specific Claude models for a key; the server lowercases, trims, deduplicates, and removes blank entries. ### OpenAI Compatibility Providers (object array) [​](https://help.router-for.me/management/api.html#openai-compatibility-providers-object-array) * GET `/openai-compatibility` — List all * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/openai-compatibility * Response: json { "openai-compatibility": [ { "name": "openrouter", "base-url": "https://openrouter.ai/api/v1", "api-key-entries": [ { "api-key": "sk", "proxy-url": "" } ], "models": [], "headers": { "X-Provider": "openrouter" } } ] } * PUT `/openai-compatibility` — Replace the list * Request: bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '[{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[{"name":"m","alias":"a"}],"headers":{"X-Provider":"openrouter"}}]' \ http://localhost:8317/v0/management/openai-compatibility * Response: json { "status": "ok" } * PATCH `/openai-compatibility` — Modify one (by `index` or `name`) * Request (by name): bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"name":"openrouter","value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[],"headers":{"X-Provider":"openrouter"}}}' \ http://localhost:8317/v0/management/openai-compatibility * Request (by index): bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"index":0,"value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[],"headers":{"X-Provider":"openrouter"}}}' \ http://localhost:8317/v0/management/openai-compatibility * Response: json { "status": "ok" } * Notes: * Legacy `api-keys` input remains accepted; keys are migrated into `api-key-entries` automatically so the legacy field will eventually remain empty in responses. * `headers` lets you define provider-wide HTTP headers; blank keys/values are dropped. * Providers without a `base-url` are removed. Sending a PATCH with `base-url` set to an empty string deletes that provider. * DELETE `/openai-compatibility` — Delete (`?name=` or `?index=`) * Request (by name): bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?name=openrouter' * Request (by index): bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?index=0' * Response: json { "status": "ok" } ### OAuth Excluded Models [​](https://help.router-for.me/management/api.html#oauth-excluded-models) Configure per-provider model blocks for OAuth-based providers. Keys are provider identifiers, values are string arrays of model names to exclude. * GET `/oauth-excluded-models` — Get the current map * Request: bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/oauth-excluded-models * Response: json { "oauth-excluded-models": { "openai": ["gpt-4.1-mini"], "iflow": ["deepseek-v3.1", "glm-4.5"] } } * PUT `/oauth-excluded-models` — Replace the full map * Request: bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"openai":["gpt-4.1-mini"],"iflow":["deepseek-v3.1","glm-4.5"]}' \ http://localhost:8317/v0/management/oauth-excluded-models * Response: json { "status": "ok" } * Notes: * The body can also be wrapped as `{ "items": { ... } }`; in both cases empty/blank model names are trimmed out. * PATCH `/oauth-excluded-models` — Upsert or delete a single provider entry * Request (upsert): bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"provider":"iflow","models":["deepseek-v3.1","glm-4.5"]}' \ http://localhost:8317/v0/management/oauth-excluded-models * Request (delete provider by sending empty models): bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"provider":"iflow","models":[]}' \ http://localhost:8317/v0/management/oauth-excluded-models * Response: json { "status": "ok" } * Notes: * `provider` is normalized to lowercase. Sending an empty `models` list removes that provider; if the provider does not exist, a `404` is returned. * DELETE `/oauth-excluded-models` — Delete all models for a provider * Request: bash curl -H 'Authorization: Bearer ' \ -X DELETE 'http://localhost:8317/v0/management/oauth-excluded-models?provider=iflow' * Response: json { "status": "ok" } ### Auth File Management [​](https://help.router-for.me/management/api.html#auth-file-management) Manage JSON token files under `auth-dir`: list, download, upload, delete. * GET `/auth-files` — List * Request: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/auth-files * Response (when the runtime auth manager is available): json { "files": [\ {\ "id": "claude-user@example.com",\ "name": "claude-user@example.com.json",\ "provider": "claude",\ "label": "Claude Prod",\ "status": "ready",\ "status_message": "ok",\ "disabled": false,\ "unavailable": false,\ "runtime_only": false,\ "source": "file",\ "path": "/abs/path/auths/claude-user@example.com.json",\ "size": 2345,\ "modtime": "2025-08-30T12:34:56Z",\ "email": "user@example.com",\ "account_type": "anthropic",\ "account": "workspace-1",\ "created_at": "2025-08-30T12:00:00Z",\ "updated_at": "2025-08-31T01:23:45Z",\ "last_refresh": "2025-08-31T01:23:45Z"\ }\ ] } * Notes: * Entries are sorted case-insensitively by `name`. `status`, `status_message`, `disabled`, and `unavailable` mirror the runtime auth manager so you can see whether a credential is healthy. * `runtime_only: true` indicates the credential only exists in memory (for example Git/Postgres/ObjectStore backends); `source` switches to `memory`. When a `.json` file exists on disk, `source=file` and the response includes `path`/`size`/`modtime`. * `email`, `account_type`, `account`, and `last_refresh` are pulled from the JSON metadata (keys such as `last_refresh`, `lastRefreshedAt`, `last_refreshed_at`, etc.). * If the runtime auth manager is unavailable the handler falls back to scanning `auth-dir`, returning only `name`, `size`, `modtime`, `type`, and `email`. * `runtime_only` entries cannot be downloaded or deleted via the file endpoints—they must be revoked from the upstream provider or a different API. * GET `/auth-files/download?name=` — Download a single file * Request: bash curl -H 'Authorization: Bearer ' -OJ 'http://localhost:8317/v0/management/auth-files/download?name=acc1.json' * Notes: * `name` must be a `.json` filename. Only `source=file` entries have a backing file to export; `runtime_only` credentials cannot be downloaded. * POST `/auth-files` — Upload * Request (multipart): bash curl -X POST -F 'file=@/path/to/acc1.json' \ -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/auth-files * Request (raw JSON): bash curl -X POST -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d @/path/to/acc1.json \ 'http://localhost:8317/v0/management/auth-files?name=acc1.json' * Response: json { "status": "ok" } * Notes: * The core auth manager must be active; otherwise the API returns `503` with `{ "error": "core auth manager unavailable" }`. * Both multipart and raw JSON uploads must use filenames ending in `.json`; upon success the credential is registered with the runtime auth manager immediately. * DELETE `/auth-files?name=` — Delete a single file * Request: bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/auth-files?name=acc1.json' * Response: json { "status": "ok" } * Notes: * Only on-disk `.json` files are removed; after a successful deletion the runtime manager is instructed to disable the corresponding credential. `runtime_only` entries are unaffected. * DELETE `/auth-files?all=true` — Delete all `.json` files under `auth-dir` * Request: bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/auth-files?all=true' * Response: json { "status": "ok", "deleted": 3 } * Notes: * Only files on disk are counted and removed; each successful deletion also triggers a disable call into the runtime auth manager. Purely in-memory entries stay untouched. ### Vertex Credential Import [​](https://help.router-for.me/management/api.html#vertex-credential-import) Mirrors the CLI `vertex-import` helper and stores Google service account JSON as `vertex-.json` files inside `auth-dir`. * POST `/vertex/import` — Upload a Vertex service account key * Request (multipart): bash curl -X POST \ -H 'Authorization: Bearer ' \ -F 'file=@/path/to/my-project-sa.json' \ -F 'location=us-central1' \ http://localhost:8317/v0/management/vertex/import * Response: json { "status": "ok", "auth-file": "/abs/path/auths/vertex-my-project.json", "project_id": "my-project", "email": "svc@my-project.iam.gserviceaccount.com", "location": "us-central1" } * Notes: * Uploads must be sent as `multipart/form-data` using the `file` field. The payload is validated and `private_key` is normalized; malformed JSON or missing `project_id` yields `400`. * The optional `location` form (or query) field overrides the default `us-central1` region recorded in the credential metadata. * The handler persists the credential via the same token store as other auth uploads; failures return `500` with `{ "error": "save_failed", ... }`. ### Login/OAuth URLs [​](https://help.router-for.me/management/api.html#login-oauth-urls) These endpoints initiate provider login flows and return a URL to open in a browser. Tokens are saved under `auths/` once the flow completes. For Anthropic, Codex, Gemini CLI, Antigravity, and iFlow you can append `?is_webui=true` to reuse the embedded callback forwarder when launching from the management UI. * GET `/anthropic-auth-url` — Start Anthropic (Claude) login * Request: bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/anthropic-auth-url * Response: json { "status": "ok", "url": "https://...", "state": "anth-1716206400" } * Notes: * Add `?is_webui=true` when triggering from the built-in UI to reuse the local callback service. * GET `/codex-auth-url` — Start Codex login * Request: bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/codex-auth-url * Response: json { "status": "ok", "url": "https://...", "state": "codex-1716206400" } * GET `/gemini-cli-auth-url` — Start Google (Gemini CLI) login * Query params: * `project_id` (optional): Google Cloud project ID. * Request: bash curl -H 'Authorization: Bearer ' \ 'http://localhost:8317/v0/management/gemini-cli-auth-url?project_id=' * Response: json { "status": "ok", "url": "https://...", "state": "gem-1716206400" } * Notes: * When `project_id` is omitted, the server queries Cloud Resource Manager for accessible projects, picks the first available one, and stores it in the token file (marked with `auto: true`). * The flow checks and, if needed, enables `cloudaicompanion.googleapis.com` via the Service Usage API; failures surface through `/get-auth-status` as errors such as `project activation required: ...`. * GET `/antigravity-auth-url` — Start Antigravity login * Request: bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/antigravity-auth-url * Response: json { "status": "ok", "url": "https://...", "state": "ant-1716206400" } * Notes: * Add `?is_webui=true` when triggering from the built-in UI so the server starts a temporary local callback forwarder on port `51121` and reuses the main HTTP port for the final redirect. * GET `/qwen-auth-url` — Start Qwen login (device flow) * Request: bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/qwen-auth-url * Response: json { "status": "ok", "url": "https://...", "state": "gem-1716206400" } * GET `/iflow-auth-url` — Start iFlow login * Request: bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/iflow-auth-url * Response: json { "status": "ok", "url": "https://...", "state": "ifl-1716206400" } * POST `/iflow-auth-url` — Authenticate using an existing iFlow cookie * Request body: bash curl -X POST -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"cookie":""}' \ http://localhost:8317/v0/management/iflow-auth-url * Successful response: json { "status": "ok", "saved_path": "/abs/path/auths/iflow-user.json", "email": "user@example.com", "expired": "2025-05-20T10:00:00Z", "type": "cookie" } * Notes: * The `cookie` field is required and must be non-empty; invalid or malformed cookies return `400` with `{ "status": "error", "error": "..." }`. * On success the server normalizes the cookie, exchanges it for an API token, persists it as an `iflow-*.json` auth file, and returns the saved path and basic metadata. * GET `/get-auth-status?state=` — Poll OAuth flow status * Request: bash curl -H 'Authorization: Bearer ' \ 'http://localhost:8317/v0/management/get-auth-status?state=' * Response examples: json { "status": "wait" } json { "status": "ok" } json { "status": "error", "error": "Authentication failed" } * Notes: * The `state` query parameter must match the value returned by the login endpoint. Once a flow reaches `status: "ok"` or `status: "error"`, the server deletes the state; subsequent polls receive `{ "status": "ok" }` to signal completion. * `status: "wait"` indicates the flow is still waiting for a callback or token exchange—continue polling as needed. Error Responses [​](https://help.router-for.me/management/api.html#error-responses) ------------------------------------------------------------------------------------ Generic error format: * 400 Bad Request: `{ "error": "invalid body" }` * 401 Unauthorized: `{ "error": "missing management key" }` or `{ "error": "invalid management key" }` * 403 Forbidden: `{ "error": "remote management disabled" }` * 404 Not Found: `{ "error": "item not found" }` or `{ "error": "file not found" }` * 422 Unprocessable Entity: `{ "error": "invalid_config", "message": "..." }` * 500 Internal Server Error: `{ "error": "failed to save config: ..." }` * 503 Service Unavailable: `{ "error": "core auth manager unavailable" }` Notes [​](https://help.router-for.me/management/api.html#notes) ---------------------------------------------------------------- * Changes are written back to the YAML config file and hot‑reloaded by the file watcher and clients. * `allow-remote-management` and `remote-management-key` cannot be changed via the API; configure them in the config file. --- # Codex | CLIProxyAPI [Skip to content](https://help.router-for.me/agent-client/codex.html#VPContent) Return to top Codex [​](https://help.router-for.me/agent-client/codex.html#codex) ==================================================================== Start CLIProxyAPI server, and then edit the `~/.codex/config.toml` and `~/.codex/auth.json` files. config.toml: toml # Disables all user confirmation prompts for actions. Extremely dangerous—remove this setting if you're new to Codex. # approval_policy = "never" # Grants unrestricted system access: AI can read/write any file and execute network-enabled commands. Highly risky—remove this setting if you're new to Codex. # sandbox_mode = "danger-full-access" model_provider = "cliproxyapi" model = "gpt-5-codex" # Or gpt-5, you can also use any of the models that we support. model_reasoning_effort = "high" [model_providers.cliproxyapi] name = "cliproxyapi" base_url = "http://127.0.0.1:8317/v1" wire_api = "responses" auth.json: json { "OPENAI_API_KEY": "sk-dummy" } --- # Gemini CLI | CLIProxyAPI [Skip to content](https://help.router-for.me/agent-client/gemini-cli.html#VPContent) Return to top Gemini CLI [​](https://help.router-for.me/agent-client/gemini-cli.html#gemini-cli) =================================================================================== Start CLIProxyAPI server, and choose one of the following configurations depending on your authentication method. Login with Google (OAuth) [​](https://help.router-for.me/agent-client/gemini-cli.html#login-with-google-oauth) --------------------------------------------------------------------------------------------------------------- Set the `CODE_ASSIST_ENDPOINT` environment variable to the URL of the CLI Proxy API server. bash export CODE_ASSIST_ENDPOINT="http://127.0.0.1:8317" The server will relay the `loadCodeAssist`, `onboardUser`, and `countTokens` requests. And automatically load balance the text generation requests between the multiple accounts. NOTE This feature only allows local access because there is currently no way to authenticate the requests. 127.0.0.1 is hardcoded for load balancing. Use Gemini API Key [​](https://help.router-for.me/agent-client/gemini-cli.html#use-gemini-api-key) --------------------------------------------------------------------------------------------------- Configure the Gemini API base URL and API key: bash export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:8317" export GEMINI_API_KEY="sk-dummy" NOTE Unlike OAuth mode, this mode allows CLIProxyAPI to be configured as any IP address or domain. --- # Factory Droid | CLIProxyAPI [Skip to content](https://help.router-for.me/agent-client/droid.html#VPContent) Return to top Factory Droid [​](https://help.router-for.me/agent-client/droid.html#factory-droid) ==================================================================================== Start CLIProxyAPI server, and then edit the `~/.factory/config.json`. config.json: json { "custom_models": [\ {\ "model": "gemini-2.5-pro",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "claude-sonnet-4-5-20250929",\ "base_url": "http://127.0.0.1:8317",\ "api_key": "sk-dummy",\ "provider": "anthropic"\ },\ {\ "model": "claude-opus-4-1-20250805",\ "base_url": "http://127.0.0.1:8317",\ "api_key": "sk-dummy",\ "provider": "anthropic"\ },\ {\ "model": "claude-sonnet-4-20250514",\ "base_url": "http://127.0.0.1:8317",\ "api_key": "sk-dummy",\ "provider": "anthropic"\ },\ {\ "model": "gpt-5",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5(minimal)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5(low)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5(medium)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5(high)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5-codex",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5-codex(low)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5-codex(medium)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5-codex(high)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ }\ ] } --- # Run with Docker | CLIProxyAPI [Skip to content](https://help.router-for.me/docker/docker.html#VPContent) Return to top Run with Docker [​](https://help.router-for.me/docker/docker.html#run-with-docker) =================================================================================== Run the following command to login (Gemini OAuth on port 8085): bash docker run --rm -p 8085:8085 -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api eceasy/cli-proxy-api:latest /CLIProxyAPI/CLIProxyAPI --login Run the following command to login (OpenAI OAuth on port 1455): bash docker run --rm -p 1455:1455 -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api eceasy/cli-proxy-api:latest /CLIProxyAPI/CLIProxyAPI --codex-login Run the following command to logi (Claude OAuth on port 54545): bash docker run -rm -p 54545:54545 -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api eceasy/cli-proxy-api:latest /CLIProxyAPI/CLIProxyAPI --claude-login Run the following command to login (Qwen OAuth): bash docker run -it -rm -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api eceasy/cli-proxy-api:latest /CLIProxyAPI/CLIProxyAPI --qwen-login Run the following command to login (iFlow OAuth on port 11451): bash docker run --rm -p 11451:11451 -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api eceasy/cli-proxy-api:latest /CLIProxyAPI/CLIProxyAPI --iflow-login Run the following command to login (Antigravity OAuth on port 51121): bash docker run --rm -p 51121:51121 -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api eceasy/cli-proxy-api:latest /CLIProxyAPI/CLIProxyAPI --antigravity-login Run the following command to start the server: 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 --- # Zero: Detailed Configuration Explanation | CLIProxyAPI [Skip to content](https://help.router-for.me/hands-on/tutorial-0.html#VPContent) Return to top Zero: Detailed Configuration Explanation [​](https://help.router-for.me/hands-on/tutorial-0.html#zero-detailed-configuration-explanation) ========================================================================================================================================== This article provides a detailed explanation of the configuration items in the configuration file of the [CLIProxyAPI project](https://github.com/router-for-me/CLIProxyAPI) , for users to refer to when they have questions. Friendly reminder: The configuration file supports hot reloading. Modifications to the configuration file take effect immediately without restarting the program. # Port number, CLIProxyAPI runs an HTTP server and needs a port number for access port: 8317 # Remote management configuration, used with EasyCLI or WebUI remote-management: # Switch to enable remote management. If you deploy it on a server, # you need to set it to true to use EasyCLI or WebUI to connect to CLIProxyAPI # for management. # If you only use the API for local management, you can keep it as false. allow-remote: false # If you want to use EasyCLI or WebUI to manage CLIProxyAPI through the API, # you must set a Key. # If it is not set, it is considered that the API management function is # disabled, and you cannot use EasyCLI or WebUI to connect. # If you do not need to use EasyCLI or WebUI for management, you can leave it # blank. secret-key: "" # Switch to integrate WebUI. # Set to false, you can open WebUI through # http://YOUR_SERVER_IP:8317/management.html disable-control-panel: false # Directory for storing authentication files, used to store authentication files # for Gemini CLI, Gemini Web, Qwen Code, and Codex. # The default setting is the .cli-proxy-api folder in your current account # directory, which is compatible with Windows and Linux environments. # The program will automatically create this folder when it starts for the first # time. # The default in Windows is C:\Users\your_username\.cli-proxy-api # The default in Linux is /home/your_username/.cli-proxy-api # If you use a non-default location in a Windows environment, you need to # modify it in this format "Z:\\CLIProxyAPI\\auths" auth-dir: "~/.cli-proxy-api" # Whether to enable Debug information in the log, it is disabled by default. # You only need to turn it on when the author needs to cooperate in # troubleshooting. debug: false # Hidden configuration, which can record every request and response and save it # to the logs directory. # The size of each log may be as high as 10MB+. Please do not enable it if your # hard disk is not large enough. request-log: false # Whether to redirect the log to a log file. # It is enabled by default, and the log will be saved in the logs folder in the # program directory. # If it is turned off, the log will be displayed in the console. logging-to-file: true # Switch for usage statistics, enabled by default. # You need to use the API to view the usage, you can use EasyCLI or WebUI to # view it. usage-statistics-enabled: true # If you want to use a proxy, you need to make the following settings, which # support socks5/http/https protocols. # Fill in according to this format "socks5://user:pass@192.168.1.1:1080/" proxy-url: "" # The number of times the program automatically retries the request when it # encounters error codes such as 403, 408, 500, 502, 503, 504. request-retry: 3 # Processing behavior after the model is restricted. quota-exceeded: # The core configuration of multi-account polling. # When set to true, for example, if an account triggers a 429, the program # will automatically switch to the next account to re-initiate the request. # When set to false, the program will send the 429 error message to the # client and end the current request. # That is to say, when it is set to true, as long as at least one of the # polling accounts is normal, the client will not report an error. # When it is set to false, the client needs to retry or abort the operation. switch-project: true # Gemini CLI exclusive configuration, applicable to Gemini 2.5 Pro and # Gemini 2.5 Flash models. # When the official version quota is used up, it will automatically switch to # the Preview model. Just keep it on. switch-preview-model: true # Hidden configuration, you can turn off the interval time during retries, and # set it as needed. # For example, after a model triggers 429, the program will temporarily disable # it, and each time it is triggered again, the deactivation time will be # increased, up to a maximum of 30 minutes. # By default, the model will be skipped during the deactivation period. # After setting it to true, the request will still be sent to the model every # time, regardless of whether the model is in the deactivation period, and it # will no longer be skipped. disable-cooling: false # The keys required for various AI clients to access CLIProxyAPI are set here. # Do not confuse them with the various keys below. # In layman's terms, the Key here is what CLIProxyAPI needs to set as a # server. # The various keys below are what CLIProxyAPI needs as a client to access the # server. api-keys: - "your-api-key-1" - "your-api-key-2" # AIStudio authentication switch. When set to true, the above api-keys will be # used to authenticate AIStudio Build APP access. ws-auth: false # Gemini API key configuration. Legacy `generative-language-api-key` values are auto-migrated here and removed from the config file on save. # When base-url is not set, the official endpoint is used for access. When # base-url is set, a third-party relay can be accessed. # When accessing through Cloudflare AI Gateway, authentication can be performed # by setting headers. # For each Key, you can also set proxy-url to connect through a proxy. 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's API Key. The key and base-url parameters of Codex provided by # various relay stations can be filled in here to access. # For each Key, you can also set proxy-url to connect through a proxy. codex-api-key: - api-key: "sk-atSM..." base-url: "https://www.example.com" proxy-url: "socks5://proxy.example.com:1080" # Claude's API Key. When using the official Key, do not fill in base-url. For # third-party relays, fill in base-url. # For each Key, you can also set proxy-url to connect through a proxy. 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: # Model name provided by the relay provider - name: "claude-3-5-sonnet-20241022" # Model alias, which is the model name actually set in the client alias: "claude-sonnet-latest" # All OpenAI compatible ones can be accessed here, no more explanation. openai-compatibility: - name: "openrouter" base-url: "https://openrouter.ai/api/v1" # Legacy api-keys are migrated into api-key-entries on load. api-key-entries: - api-key: "sk-or-v1-...b780" proxy-url: "socks5://proxy.example.com:1080" - api-key: "sk-or-v1-...b781" models: # Model name provided by the OpenAI compatible provider - name: "moonshotai/kimi-k2:free" # Model alias, which is the model name actually set in the client alias: "kimi-k2" --- # Amp CLI | CLIProxyAPI [Skip to content](https://help.router-for.me/agent-client/amp-cli.html#VPContent) Return to top Amp CLI [​](https://help.router-for.me/agent-client/amp-cli.html#amp-cli) ========================================================================== This guide explains how to use CLIProxyAPI with Amp CLI and Amp IDE extensions, enabling you to use your existing Google/ChatGPT/Claude subscriptions (via OAuth) with Amp's CLI. Overview [​](https://help.router-for.me/agent-client/amp-cli.html#overview) ---------------------------------------------------------------------------- The Amp CLI integration adds specialized routing to support Amp's API patterns while maintaining full compatibility with all existing CLIProxyAPI features. This allows you to use both traditional CLIProxyAPI features and Amp CLI with the same proxy server. ### Key Features [​](https://help.router-for.me/agent-client/amp-cli.html#key-features) * **Provider route aliases**: Maps Amp's `/api/provider/{provider}/v1...` patterns to CLIProxyAPI handlers * **Management proxy**: Forwards account management requests to Amp's control plane using a secure upstream API key. * **Smart fallback**: Automatically routes unconfigured models to ampcode.com * **Security-first**: Management routes require API key auth (optional localhost restriction) * **Automatic gzip handling**: Decompresses responses from Amp upstream ### What You Can Do [​](https://help.router-for.me/agent-client/amp-cli.html#what-you-can-do) * Use Amp CLI with your Google account (Gemini 3 Pro Preview, Gemini 2.5 Pro, Gemini 2.5 Flash) * Use Amp CLI with your ChatGPT Plus/Pro subscription (GPT-5, GPT-5 Codex models) * Use Amp CLI with your Claude Pro/Max subscription (Claude Sonnet 4.5, Opus 4.1) * Use Amp IDE extensions (VS Code, Cursor, Windsurf, etc.) with the same proxy * Run multiple CLI tools (Factory + Amp) through one proxy server * Route unconfigured models automatically through ampcode.com ### Which Providers Should You Authenticate? [​](https://help.router-for.me/agent-client/amp-cli.html#which-providers-should-you-authenticate) **Important**: The providers you need to authenticate depend on which models and features your installed version of Amp currently uses. Amp employs different providers for various agent modes and specialized subagents: * **Smart mode**: Uses Google/Gemini models (Gemini 3 Pro) * **Rush mode**: Uses Anthropic/Claude models (Claude Haiku 4.5) * **Oracle subagent**: Uses OpenAI/GPT models (GPT-5 medium reasoning) * **Librarian subagent**: Uses Anthropic/Claude models (Claude Sonnet 4.5) * **Search subagent**: Uses Anthropic/Claude models (Claude Haiku 4.5) * **Review feature**: Uses Google/Gemini models (Gemini 2.5 Flash-Lite) For the most current information about which models Amp uses, see the **[Amp Models Documentation](https://ampcode.com/models) **. #### Fallback Behavior [​](https://help.router-for.me/agent-client/amp-cli.html#fallback-behavior) CLIProxyAPI uses a smart fallback system: 1. **Provider authenticated locally** (`--login`, `--codex-login`, `--claude-login`): * Requests use **your OAuth subscription** (ChatGPT Plus/Pro, Claude Pro/Max, Google account) * You benefit from your subscription's included usage quotas * No Amp credits consumed 2. **Provider NOT authenticated locally**: * Requests automatically forward to **ampcode.com** * Uses Amp's backend provider connections * **Requires Amp credits** if the provider is paid (OpenAI, Anthropic paid tiers) * May result in errors if Amp credit balance is insufficient **Recommendation**: Authenticate all providers you have subscriptions for to maximize value and minimize Amp credit usage. If you don't have subscriptions to all providers Amp uses, ensure you have sufficient Amp credits available for fallback requests. Architecture [​](https://help.router-for.me/agent-client/amp-cli.html#architecture) ------------------------------------------------------------------------------------ ### Request Flow [​](https://help.router-for.me/agent-client/amp-cli.html#request-flow) Amp CLI/IDE ↓ ├─ Provider API requests (/api/provider/{provider}/v1/...) │ ↓ │ ├─ Model configured locally? │ │ YES → Use local OAuth tokens (OpenAI/Claude/Gemini handlers) │ │ NO → Forward to ampcode.com (reverse proxy) │ ↓ │ Response │ └─ Management requests (/api/auth, /api/user, /api/threads, ...) ↓ ├─ Authenticate with CLIProxyAPI's `api-keys` ↓ ├─ Optional localhost restriction ↓ └─ Reverse proxy to ampcode.com (using `upstream-api-key`) ↓ Response (auto-decompressed if gzipped) ### Components [​](https://help.router-for.me/agent-client/amp-cli.html#components) The Amp integration is implemented as a modular routing module (`internal/api/modules/amp/`) with these components: 1. **Route Aliases** (`routes.go`): Maps Amp-style paths to standard handlers 2. **Reverse Proxy** (`proxy.go`): Forwards management requests to ampcode.com 3. **Fallback Handler** (`fallback_handlers.go`): Routes unconfigured models to ampcode.com 4. **Secret Management** (`secret.go`): Multi-source API key resolution with caching 5. **Main Module** (`amp.go`): Orchestrates registration and configuration Configuration [​](https://help.router-for.me/agent-client/amp-cli.html#configuration) -------------------------------------------------------------------------------------- ### Basic Configuration [​](https://help.router-for.me/agent-client/amp-cli.html#basic-configuration) Add the `ampcode` block to your `config.yaml` (as of v6.5.37, legacy `amp-upstream-*` keys are auto-migrated and rewritten to this structure on load): yaml # API keys for clients (e.g., Amp CLI, VS Code) to authenticate with CLIProxyAPI api-keys: - "your-client-secret-key" # Example key for your clients ampcode: # Amp upstream control plane (required for management routes) upstream-url: "https://ampcode.com" # API key for CLIProxyAPI to authenticate with ampcode.com # Get this from https://ampcode.com/settings upstream-api-key: "your-ampcode-api-key-goes-here" # Optional: restrict management routes to localhost (default: false) restrict-management-to-localhost: false # Optional: map missing Amp models to local ones # model-mappings: # - from: "claude-opus-4.5" # to: "claude-sonnet-4" ### Security Settings [​](https://help.router-for.me/agent-client/amp-cli.html#security-settings) #### API Key Auth for Management Routes [​](https://help.router-for.me/agent-client/amp-cli.html#api-key-auth-for-management-routes) As of v6.6.15, Amp management routes (`/api/auth`, `/api/user`, `/api/threads`, `/threads`, etc.) are protected by CLIProxyAPI's standard API key authentication middleware. * If you configure `api-keys` in `config.yaml` (recommended), these routes require a valid API key in the request (`Authorization: Bearer ` or `X-Api-Key: `), otherwise they return `401 Unauthorized`. * After local authentication succeeds, the proxy strips the client's `Authorization`/`X-Api-Key` and uses `ampcode.upstream-api-key` to call the upstream ampcode.com service. #### `ampcode.restrict-management-to-localhost` [​](https://help.router-for.me/agent-client/amp-cli.html#ampcode-restrict-management-to-localhost) **Default: `false`** When enabled, management routes (`/api/auth`, `/api/user`, `/api/threads`, etc.) only accept connections from localhost (127.0.0.1, ::1). This prevents: * Drive-by browser attacks * Remote access to management endpoints * CORS-based attacks * Header spoofing attacks (e.g., `X-Forwarded-For: 127.0.0.1`) #### How It Works [​](https://help.router-for.me/agent-client/amp-cli.html#how-it-works) This restriction uses the **actual TCP connection address** (`RemoteAddr`), not HTTP headers like `X-Forwarded-For`. This prevents header spoofing attacks but has important implications: * ✅ **Works for direct connections**: Running CLIProxyAPI directly on your machine or server * ⚠️ **May not work behind reverse proxies**: If deploying behind nginx, Cloudflare, or other proxies, the connection will appear to come from the proxy's IP, not localhost #### Reverse Proxy Deployments [​](https://help.router-for.me/agent-client/amp-cli.html#reverse-proxy-deployments) If you need to run CLIProxyAPI behind a reverse proxy (nginx, Caddy, Cloudflare Tunnel, etc.): 1. **Keep the localhost restriction disabled (default)**: yaml ampcode: restrict-management-to-localhost: false 2. **Ensure API key auth is enabled** (recommended): * Configure `api-keys` in `config.yaml` and have clients send the key * Combine with firewall/VPN/zero-trust controls to reduce exposure 3. **Example nginx configuration** (blocks external access to management routes): nginx location /api/auth { deny all; } location /api/user { deny all; } location /api/threads { deny all; } location /api/internal { deny all; } **Note**: `ampcode.restrict-management-to-localhost` is an extra hardening option; behind reverse proxies it is typically kept `false`. Setup [​](https://help.router-for.me/agent-client/amp-cli.html#setup) ---------------------------------------------------------------------- ### 1\. Configure CLIProxyAPI [​](https://help.router-for.me/agent-client/amp-cli.html#_1-configure-cliproxyapi) Create or edit `config.yaml`. You will need two types of API keys: 1. `api-keys`: For clients like Amp CLI to connect to your CLIProxyAPI instance. 2. `ampcode.upstream-api-key`: For CLIProxyAPI to connect to the `ampcode.com` backend. Get this from **[https://ampcode.com/settings](https://ampcode.com/settings) **. yaml port: 8317 auth-dir: "~/.cli-proxy-api" # API keys for clients (e.g., Amp CLI) to use api-keys: - "your-client-secret-key" # You can change this secret # Amp integration ampcode: upstream-url: "https://ampcode.com" # Your personal API key from ampcode.com upstream-api-key: "paste-your-ampcode-api-key-here" restrict-management-to-localhost: false # Other standard settings... debug: false logging-to-file: true ### 2\. Authenticate with Providers [​](https://help.router-for.me/agent-client/amp-cli.html#_2-authenticate-with-providers) Run OAuth login for the providers you want to use: **Google Account (Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 3 Pro Preview):** bash ./cli-proxy-api --login **ChatGPT Plus/Pro (GPT-5, GPT-5 Codex):** bash ./cli-proxy-api --codex-login **Claude Pro/Max (Claude Sonnet 4.5, Opus 4.1):** bash ./cli-proxy-api --claude-login Tokens are saved to: * Gemini: `~/.cli-proxy-api/gemini-.json` * OpenAI Codex: `~/.cli-proxy-api/codex-.json` * Claude: `~/.cli-proxy-api/claude-.json` ### 3\. Start the Proxy [​](https://help.router-for.me/agent-client/amp-cli.html#_3-start-the-proxy) bash ./cli-proxy-api --config config.yaml ### 4\. Configure Amp CLI [​](https://help.router-for.me/agent-client/amp-cli.html#_4-configure-amp-cli) #### Option A: Settings File [​](https://help.router-for.me/agent-client/amp-cli.html#option-a-settings-file) Amp CLI uses two configuration files: 1. **Settings file**: `~/.config/amp/settings.json` - General settings 2. **Secrets file**: `~/.local/share/amp/secrets.json` - Sensitive credentials (API keys) Edit `~/.config/amp/settings.json` for the URL: json { "amp.url": "http://localhost:8317" } Edit `~/.local/share/amp/secrets.json` for the API key: json { "apiKey@http://localhost:8317": "your-client-secret-key" } #### Option B: Environment Variable [​](https://help.router-for.me/agent-client/amp-cli.html#option-b-environment-variable) bash export AMP_URL=http://localhost:8317 export AMP_API_KEY=your-client-secret-key With this configuration, the `amp login` command is no longer necessary. ### 5\. Use Amp [​](https://help.router-for.me/agent-client/amp-cli.html#_5-use-amp) You are now ready to use Amp. All requests will be routed through your proxy. bash amp "Write a hello world program in Python" ### 6\. (Optional) Configure Amp IDE Extension [​](https://help.router-for.me/agent-client/amp-cli.html#_6-optional-configure-amp-ide-extension) The proxy also works with Amp IDE extensions for VS Code, Cursor, Windsurf, etc. 1. Open Amp extension settings in your IDE. 2. Set **Amp URL** to `http://localhost:8317`. 3. Set **Amp API Key** to the key you configured (e.g., `your-client-secret-key`). 4. Start using Amp in your IDE. Both CLI and IDE can use the proxy simultaneously. Usage [​](https://help.router-for.me/agent-client/amp-cli.html#usage) ---------------------------------------------------------------------- ### Supported Routes [​](https://help.router-for.me/agent-client/amp-cli.html#supported-routes) #### Provider Aliases (Always Available) [​](https://help.router-for.me/agent-client/amp-cli.html#provider-aliases-always-available) These routes work even without `ampcode.upstream-url` configured: * `/api/provider/openai/v1/chat/completions` * `/api/provider/openai/v1/responses` * `/api/provider/anthropic/v1/messages` * `/api/provider/google/v1beta/models/:action` Amp CLI calls these routes with your OAuth-authenticated models configured in CLIProxyAPI. #### Management Routes (Require `ampcode.upstream-url`) [​](https://help.router-for.me/agent-client/amp-cli.html#management-routes-require-ampcode-upstream-url) These routes are proxied to ampcode.com: * `/api/auth` - Authentication * `/api/user` - User profile * `/api/meta` - Metadata * `/api/threads` - Conversation threads * `/api/telemetry` - Usage telemetry * `/api/internal` - Internal APIs **Security**: Requires an API key; `ampcode.restrict-management-to-localhost` is optional (default: false). ### Model Fallback Behavior [​](https://help.router-for.me/agent-client/amp-cli.html#model-fallback-behavior) When Amp requests a model: 1. **Check local configuration**: Does CLIProxyAPI have OAuth tokens for this model's provider? 2. **If YES**: Route to local handler (use your OAuth subscription) 3. **If NO**: Forward to ampcode.com (use Amp's default routing) This enables seamless mixed usage: * Models you've configured (Gemini, ChatGPT, Claude) → Your OAuth subscriptions * Models you haven't configured → Amp's default providers ### Example API Calls [​](https://help.router-for.me/agent-client/amp-cli.html#example-api-calls) **Chat completion with local OAuth:** bash curl http://localhost:8317/api/provider/openai/v1/chat/completions \ -H "Authorization: Bearer " \ -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 " Troubleshooting [​](https://help.router-for.me/agent-client/amp-cli.html#troubleshooting) ------------------------------------------------------------------------------------------ ### Common Issues [​](https://help.router-for.me/agent-client/amp-cli.html#common-issues) | Symptom | Likely Cause | Fix | | --- | --- | --- | | 404 on `/api/provider/...` | Incorrect route path | Ensure exact path: `/api/provider/{provider}/v1...` | | 401 on `/api/user` | Missing/invalid API key | Configure `api-keys` and send `Authorization: Bearer ` or `X-Api-Key: ` | | 403 on `/api/user` | Localhost restriction enabled and request is remote | Run from the same machine or set `ampcode.restrict-management-to-localhost` to `false` | | 401/403 from provider | Missing/expired OAuth | Re-run `--codex-login` or `--claude-login` | | Amp gzip errors | Response decompression issue | Update to latest build; auto-decompression should handle this | | Models not using proxy | Wrong Amp URL | Verify `amp.url` setting or `AMP_URL` environment variable | | CORS errors | Protected management endpoint | Use CLI/terminal, not browser | ### Diagnostics [​](https://help.router-for.me/agent-client/amp-cli.html#diagnostics) **Check proxy logs:** bash # If logging-to-file: true tail -f logs/requests.log # If running in tmux tmux attach-session -t proxy **Enable debug mode** (temporarily): yaml debug: true **Test basic connectivity:** bash # Check if proxy is running curl http://localhost:8317/v1/models # Check Amp-specific route curl http://localhost:8317/api/provider/openai/v1/models **Verify Amp configuration:** bash # Check if Amp is using proxy amp config get amp.url # Or check environment echo $AMP_URL ### Security Checklist [​](https://help.router-for.me/agent-client/amp-cli.html#security-checklist) * ✅ Configure and protect `api-keys` (management routes require an API key) * ✅ Enable `ampcode.restrict-management-to-localhost: true` for extra hardening when possible (default: false) * ✅ Don't expose proxy publicly (bind to localhost or use firewall/VPN) * ✅ Securely store your `ampcode.upstream-api-key` in the config file. * ✅ Rotate OAuth tokens periodically by re-running login commands * ✅ Store config and auth-dir on encrypted disk if handling sensitive data * ✅ Keep proxy binary up to date for security fixes Additional Resources [​](https://help.router-for.me/agent-client/amp-cli.html#additional-resources) ---------------------------------------------------------------------------------------------------- * [Amp CLI Official Manual](https://ampcode.com/manual) --- # Run with Docker Compose | CLIProxyAPI [Skip to content](https://help.router-for.me/docker/docker-compose.html#VPContent) Return to top Run with Docker Compose [​](https://help.router-for.me/docker/docker-compose.html#run-with-docker-compose) =========================================================================================================== 1. Clone the repository and navigate into the directory: bash git clone https://github.com/router-for-me/CLIProxyAPI.git cd CLIProxyAPI 2. Prepare the configuration file: Create a `config.yaml` file by copying the example and customize it to your needs. bash cp config.example.yaml config.yaml _(Note for Windows users: You can use `copy config.example.yaml config.yaml` in CMD or PowerShell.)_ 3. Start the service: * **For most users (recommended):** Run the following command to start the service using the pre-built image from Docker Hub. The service will run in the background. bash docker compose up -d * **For advanced users:** If you have modified the source code and need to build a new image, use the interactive helper scripts: * For Windows (PowerShell): powershell .\docker-build.ps1 * For Linux/macOS: bash bash docker-build.sh The script will prompt you to choose how to run the application: * **Option 1: Run using Pre-built Image (Recommended)**: Pulls the latest official image from the registry and starts the container. This is the easiest way to get started. * **Option 2: Build from Source and Run (For Developers)**: Builds the image from the local source code, tags it as `cli-proxy-api:local`, and then starts the container. This is useful if you are making changes to the source code. 4. To authenticate with providers, run the login command inside the container: * **Gemini**: bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --login * **OpenAI (Codex)**: bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --codex-login * **Claude**: bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --claude-login * **Qwen**: bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --qwen-login * **iFlow**: bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --iflow-login * **Antigravity**: bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --antigravity-login 5. To view the server logs: bash docker compose logs -f 6. To stop the application: bash docker compose down --- # Four: Relay Forwarding Integration | CLIProxyAPI [Skip to content](https://help.router-for.me/hands-on/tutorial-4.html#VPContent) Return to top Four: Relay Forwarding Integration [​](https://help.router-for.me/hands-on/tutorial-4.html#four-relay-forwarding-integration) ============================================================================================================================== In the previous articles, we have successfully integrated Qwen, Codex, Gemini CLI, and Gemini Web through OAuth or Cookie methods. In this tutorial, we will go a step further and learn how to conveniently integrate various AI relay services into CLIProxyAPI. First, let's review the configuration file we used before: yaml port: 8317 # Please fill in the folder location according to your actual situation auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: # Please set the Key yourself, used for client access to the proxy - "ABC-123456" After the initial configuration, we have not changed it. Now, it's time to expand this file. Let's first add a Claude relay service. To do this, we first need to obtain the `base-url` of the service, which can usually be found in the official documentation or tutorials of the corresponding service provider. Taking 88code as an example, the following information can be found in its official tutorial: ![](https://img.072899.xyz/2025/09/11c41d79d62c02df1ac5d5998c75d3e5.png) From the figure, we can know that the `base-url` of the 88code relay Claude service is `https://www.88code.org/api`. We add the `claude-api-key` field to the configuration file: yaml port: 8317 auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: - "ABC-123456" claude-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/api" Similarly, 88code also provides Codex services. We use the same method to find its `base-url`: ![](https://img.072899.xyz/2025/09/28e5ce297bca540e052863860dd9eb2c.png) Then, add the `codex-api-key` field to the configuration file: yaml port: 8317 auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: - "ABC-123456" claude-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/api" codex-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/openai/v1" For other service providers, you can also add them in a similar way. For example, I have a few PackyCode's Codex API Keys here, and I will add them to the configuration together: yaml port: 8317 auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: - "ABC-123456" claude-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/api" - api-key: "sk-4cXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://api.packycode.com" - api-key: "sk-HpYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY" base-url: "https://api.packycode.com" codex-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/openai/v1" - api-key: "fk-4cXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://oai-api.fkclaude.com/v1" - api-key: "sk-amXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://codex-api.packycode.com/v1" - api-key: "sk-sTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://codex-api.packycode.com/v1" Please note that even for multiple `api-key`s from the same service provider and using the same `base-url`, you need to declare the `base-url` separately for each `api-key`, and it cannot be omitted. In addition, CLIProxyAPI also supports access to any provider compatible with the OpenAI interface, which needs to be configured through the `openai-compatibility` field. The specific steps will not be repeated here. You can directly refer to the configuration file example below for configuration: yaml port: 8317 auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: - "ABC-123456" claude-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/api" codex-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/openai/v1" - api-key: "fk-4cXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://oai-api.fkclaude.com/v1" - api-key: "sk-amXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://codex-api.packycode.com/v1" - api-key: "sk-sTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://codex-api.packycode.com/v1" openai-compatibility: - name: "openrouter" base-url: "https://openrouter.ai/api/v1" api-keys: - "sk-or-v1-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" - "sk-or-v1-bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" models: - name: "deepseek/deepseek-chat-v3.1:free" alias: "deepseek-v3.1" - name: "deepseek/deepseek-r1-0528:free" alias: "deepseek-r1-0528" - name: "x-ai/grok-4-fast:free" alias: "grok-4-fast" - name: "groq" base-url: "https://api.groq.com/openai/v1" api-keys: - "gsk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" models: - name: "deepseek-r1-distill-llama-70b" alias: "deepseek-r1-70b" As you can see, the configuration logic of `openai-compatibility` is slightly different from before: all `api-key`s under the same provider share the same `base-url`. So far, the configuration is complete. The remaining model connectivity verification is left for readers to test by themselves. --- # Five: Docker Server Deployment | CLIProxyAPI [Skip to content](https://help.router-for.me/hands-on/tutorial-5.html#VPContent) Return to top Five: Docker Server Deployment [​](https://help.router-for.me/hands-on/tutorial-5.html#five-docker-server-deployment) ====================================================================================================================== In the previous series of articles, we introduced how to use CLIProxyAPI on a local computer. This article will go a step further and explain how to complete the deployment on a server through Docker. ### **1\. Environment Preparation** [​](https://help.router-for.me/hands-on/tutorial-5.html#_1-environment-preparation) Before you start, please make sure you have a usable VPS (Virtual Private Server). This article will use the **Debian 13** system as an example for demonstration. At the same time, please make sure that **Git** and **Docker** are already installed on your server. If they are not installed yet, you can install them with the following commands: **1\. Install Git** bash apt update && apt install git -y **2\. Install Docker** You can use the one-click script provided by the official to install: bash bash <(curl -fsSL [https://get.docker.com](https://get.docker.com)) ### **2\. Deploy CLIProxyAPI** [​](https://help.router-for.me/hands-on/tutorial-5.html#_2-deploy-cliproxyapi) After the preparations are ready, please execute the following commands in order to clone the project and initialize the configuration. bash git clone https://github.com/router-for-me/CLIProxyAPI.git cd CLIProxyAPI cp config.example.yaml config.yaml ![](https://img.072899.xyz/2025/09/60714b62a0f5b3ea896ab5461ecec150.png) At this time, we can open the `config.yaml` file for editing. This tutorial will use the following minimal configuration as an example: yaml port: 8317 # Please fill in the folder location according to your actual situation auth-dir: "~/.cli-proxy-api" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: # Please set the Key yourself, used for client access to the proxy - "ABC-123456" > **Please note:** When deploying with Docker, it is recommended to keep the default setting of `auth-dir` without modification. After editing the `config.yaml` file, we execute the following command to execute the Docker container build script. bash bash docker-build.sh The script will provide two options: ![](https://img.072899.xyz/2025/09/f0f543ef4004f3f81c029f442b54c8bc.png) * **Option 1:** Run directly using the pre-built image on Docker Hub (`docker compose up -d`), which is fast. * **Option 2:** Compile the image locally on the server and then run it, which is suitable for scenarios that require custom modifications. In this tutorial, we choose **Option 1** to quickly start the service. After a while, the service will start successfully. ![](https://img.072899.xyz/2025/09/44609a9a0746c138f570202bd2825366.png) ### **3\. View Logs** [​](https://help.router-for.me/hands-on/tutorial-5.html#_3-view-logs) Although the script prompts to use `docker compose logs -f` to view the logs, since the program redirects the logs to a file by default, you need to use the following command to **view the logs in real time**: bash tail -f ./logs/main.log ### **4\. Add OAuth Authentication** [​](https://help.router-for.me/hands-on/tutorial-5.html#_4-add-oauth-authentication) Now the program is running normally. If you need to add a relay Key, you only need to edit the configuration file as described in the previous article. This time, we will focus on how to add an authorization authentication file through OAuth. #### **Step 1: Generate an authentication link on the server side** [​](https://help.router-for.me/hands-on/tutorial-5.html#step-1-generate-an-authentication-link-on-the-server-side) Taking adding **Codex** as an example, please execute the following command in the project root directory: bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --codex-login The program will generate a command to establish an SSH tunnel. Please copy the entire command starting with `ssh` at the arrow. ![](https://img.072899.xyz/2025/09/42f152ef068cea1df603b29934b6e814.png) #### **Step 2: Establish an SSH tunnel locally** [​](https://help.router-for.me/hands-on/tutorial-5.html#step-2-establish-an-ssh-tunnel-locally) In the terminal or command line tool of **your own computer**, paste the command you just copied. ![](https://img.072899.xyz/2025/09/1c27a2d2e3bc1ad823a040a50cb8e143.png) > **Special note:** You need to replace the port number after the `-p` parameter in the command ( `22` in the example) with the **actual SSH port** of your VPS. After pressing Enter, enter the SSH login password of the server. After a successful connection, please keep this terminal window open, and then return to the terminal where you just operated the server. ![](https://img.072899.xyz/2025/09/e25d23bc9b129cc9bbc6f4e1a674fed5.png) #### **Step 3: Complete authorization through the browser** [​](https://help.router-for.me/hands-on/tutorial-5.html#step-3-complete-authorization-through-the-browser) Copy the link pointed to by the arrow on the server terminal ![](https://img.072899.xyz/2025/09/5ddcbc39551201f61b906703034af3d8.png) Open this link in the browser of your local computer, log in with your ChatGPT account and authorize ![](https://img.072899.xyz/2025/09/a4ed389a080bce529c47bda6f3129189.png) After successful authorization, you will see the following screen: ![](https://img.072899.xyz/2025/09/507c93b6fc900eae5c6c5b486b399561.png) At the same time, the server's terminal will also show that the authentication file has been successfully saved. ![](https://img.072899.xyz/2025/09/a34bb04a63f7f75f687a2a626035dccd.png) So far, the authentication of Codex is all completed. For other services that require OAuth authorization, such as Gemini-CLI and Claude, the operation process is exactly the same. ### **5\. Principle Summary** [​](https://help.router-for.me/hands-on/tutorial-5.html#_5-principle-summary) Finally, let's summarize the principle of this remote OAuth authentication process: The OAuth authentication of Gemini-CLI, Claude, and Codex all require a "Callback" process to receive the authorization token. Due to security restrictions, the callback address of the service provider is usually forced to be set to `localhost`. When we execute the authorization command in the Docker container, there is no browser environment in the container, and we must open the authorization web page on the local computer. But after successful authorization, the browser will try to access `localhost`, which will only access our own computer, and cannot pass the token to the program on the remote server. The role of **SSH Tunnel** is to build a bridge: it forwards all network requests on a certain port of our local computer (for example, `1455`) to the same port of the server through an encrypted SSH connection. In this way, when the browser accesses the local `http://localhost:1455`, the request is actually forwarded to the CLIProxyAPI program that is listening on port `1455` on the server, thus cleverly completing the remote authentication. As an alternative to SSH Tunnel, you can also manually replace `localhost` with the IP or domain name of your server when the browser jumps to the `localhost` callback link. However, please note that this method requires you to correctly configure the server's firewall or reverse proxy to ensure that the callback request can be correctly received, otherwise the authentication may fail. ### **6\. Client Use** [​](https://help.router-for.me/hands-on/tutorial-5.html#_6-client-use) After completing the above configuration, when using the client, you only need to point the request endpoint address to your server's `IP:port` (for example, `http://YOUR_SERVER_IP:8317`), and the rest of the operations are exactly the same as local use. So far, you have mastered the complete process of deploying CLIProxyAPI on the server through Docker. Go and enjoy the convenience brought by AI! --- # Zero-Cost Deployment: HuggingFace (Database Storage) | CLIProxyAPI [Skip to content](https://help.router-for.me/hands-on/tutorial-8.html#VPContent) Return to top Zero-Cost Deployment: HuggingFace (Database Storage) [​](https://help.router-for.me/hands-on/tutorial-8.html#zero-cost-deployment-huggingface-database-storage) ================================================================================================================================================================ In the previous articles of the "No VPS?" series, we discussed how to achieve persistence of configuration and authentication information for CLIProxyAPI using local volumes (ClawCloud), GitHub (Render), and object storage buckets (Railway). This article will focus on how to achieve the same goal through a PostgreSQL database. In addition, considering that the container deployment mechanism of HuggingFace is different from conventional platforms, and some friends want to understand its deployment process, this article will explain it in detail. This tutorial will take the PostgreSQL service provided by Railway as an example. The process of using other database providers is similar, and you can explore it yourself. ### 1\. Prepare the PostgreSQL database [​](https://help.router-for.me/hands-on/tutorial-8.html#_1-prepare-the-postgresql-database) First, log in to your Railway account, create a new instance in the workspace, and select **Database** -> **Add PostgreSQL** ![](https://img.072899.xyz/2025/10/dab21cb1671989f6781eed1eba03c985.png) ![](https://img.072899.xyz/2025/10/9580732f1e15d365db8a3dd07442b3fd.png) After the instance is created, click to enter the database management page, and click **Connect** under the **Database** tab ![](https://img.072899.xyz/2025/10/f177a3cc1cb30146d9b16475179fd5f0.png) Please copy and save the **Connection URL** under the **Public Network** tab, which will be used in subsequent steps ![](https://img.072899.xyz/2025/10/107a359a8a490b18a325779432a71582.png) ### 2\. Deploy on HuggingFace [​](https://help.router-for.me/hands-on/tutorial-8.html#_2-deploy-on-huggingface) First, please visit the [CLIProxyAPI project template](https://huggingface.co/spaces/hkfires/CLIProxyAPI) that I have established in advance, and then as shown in the figure below, click **Duplicate this Space** in the drop-down menu to copy the project ![](https://img.072899.xyz/2025/10/0febf3a57ae4f8384dfff6d6e38614ce.png) On the configuration page, please follow the instructions below: * Modify the **Space name** (if this is your first project, you don't need to modify it) * Set **Visibility** to **Public** to ensure that the service can be accessed remotely after deployment * Fill in the management password you plan to use for WebUI in `MANAGEMENT_PASSWORD` * Paste the previously copied database connection URL in `PGSTORE_DSN` After filling in all the information, click **Duplicate Space** > **Additional note**: The reason why the two environment variables `MANAGEMENT_STATIC_PATH` and `PGSTORE_LOCAL_PATH` need to be set to `/tmp` is that the security mechanism of HuggingFace sets the root directory of the container to read-only permission. Through these two variables, we can point the path of the database cache file and the management page static resources to the writable `/tmp` directory, thereby ensuring the normal operation of the program. ![](https://img.072899.xyz/2025/10/a4b88ee81e6eefd0721b301c9bc4f5e8.png) Wait a moment, when you see information similar to the following in the log, it means that the deployment has been successfully completed ![](https://img.072899.xyz/2025/10/98550ed355e70b9776498558bd6c599a.png) At this time, you can access the WebUI through `https://-.hf.space/management.html`. For example, my access address is `https://hkfires-cliproxyapi.hf.space/management.html`. Enter the management password you previously set in the environment variables to log in successfully ![](https://img.072899.xyz/2025/10/e8fa8144c51bfc6125a8cb218cf528dd.png) So far, the entire deployment process is complete. For subsequent usage, you can refer to the **"Use EasyCLI for remote OAuth authentication"** section in the "Zero-Cost Deployment (ClawCloud)" tutorial. --- # Six: The Beginner's Favorite GUI | CLIProxyAPI [Skip to content](https://help.router-for.me/hands-on/tutorial-6.html#VPContent) Return to top Six: The Beginner's Favorite GUI [​](https://help.router-for.me/hands-on/tutorial-6.html#six-the-beginner-s-favorite-gui) ========================================================================================================================== In previous articles, we have introduced how to run CLIProxyAPI step by step through the command line. In fact, CLIProxyAPI also has two supporting projects: EasyCLI and WebUI. * **EasyCLI repository address**: `https://github.com/router-for-me/EasyCLI` * **WebUI repository address**: `https://github.com/router-for-me/Cli-Proxy-API-Management-Center` These two projects aim to lower the barrier to entry for ordinary users. EasyCLI is a desktop client, and WebUI is a web management interface. They both work by connecting to CLIProxyAPI. I have not provided a GUI tutorial before because the old version required users to deploy or install it themselves, which was relatively cumbersome. Starting from version `6.0.19`, the author has integrated WebUI into the main program. Therefore, users can now directly configure it through the built-in web interface. This article will briefly introduce how to enable and access WebUI. The usage of EasyCLI will be detailed in a subsequent article on container cloud deployment. #### 1\. Enable WebUI [​](https://help.router-for.me/hands-on/tutorial-6.html#_1-enable-webui) First, we need to adjust the original basic configuration and add the remote management part. The complete example configuration is as follows: yaml port: 8317 auth-dir: "~/.cli-proxy-api" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: - "ABC-123456" # The remote management part added this time remote-management: allow-remote: true # The KEY for remote management, which should be distinguished from the api-keys above secret-key: "MGT-123456" disable-control-panel: false **Please note**: After modifying the configuration, you need to restart the program for it to take effect (the new version supports automatic hot reloading). #### 2\. Access WebUI [​](https://help.router-for.me/hands-on/tutorial-6.html#_2-access-webui) After the program starts successfully, visit `http://YOUR_SERVER_IP:8317/management.html` in your browser, and enter the previously set password `MGT-123456` in the management key to open the WebUI interface. ![](https://img.072899.xyz/2025/10/37b12b67193ec67774e2f657e38eefc9.png) #### 3\. Important Notes [​](https://help.router-for.me/hands-on/tutorial-6.html#_3-important-notes) The interface design of WebUI is intuitive, and you can explore various functions on your own. However, it is important to note that the OAuth authentication function in WebUI only supports CLIProxyAPI instances running locally (for example, `localhost` or `127.0.0.1`). For instances deployed on a remote server, due to the security policy restrictions of the OAuth service provider, authentication cannot be completed directly through WebUI. --- # Zero-Cost Deployment: ClawCloud (Built-in Storage) | CLIProxyAPI [Skip to content](https://help.router-for.me/hands-on/tutorial-7.html#VPContent) Return to top Zero-Cost Deployment: ClawCloud (Built-in Storage) [​](https://help.router-for.me/hands-on/tutorial-7.html#zero-cost-deployment-clawcloud-built-in-storage) ============================================================================================================================================================ Some time ago, I published an article "Five: Docker Server Deployment". Many netizens reported that they did not have a VPS and hoped that I could provide a tutorial on deploying on a container cloud. In fact, since `CLIProxyAPI` supports Docker deployment, it can naturally run seamlessly on the container cloud. However, if it is run directly on the container cloud, there will be the following two main problems: * **Configuration file persistence**: For the configuration file required for program startup, the container cloud often solves it by mapping the configuration file content to a specific file. Although it can run, if you have modified the configuration file, once the container restarts, all changes will be lost. This loss of configuration is unacceptable to us. * **Complex OAuth authentication**: For providers that require OAuth authentication, in the Docker environment of a VPS, we can forward the authentication callback results to the server through an SSH tunnel. However, a pure container cloud environment usually does not support SSH tunnels, and it needs to be completed by adding multiple ports and manually modifying the domain name during callback, which is a very tedious process. Therefore, after `CLIProxyAPI` is updated to adapt to the deployment of the container cloud, this tutorial will guide you step by step on how to complete the deployment on the container cloud. The container cloud platform used in this tutorial is [ClawCloud Run](https://run.claw.cloud/) . Log in to the platform with a Github account that has been registered for more than 180 days to get a monthly recurring credit of $5. The `CLIProxyAPI` we deployed only consumes about $0.05 per day, which is more than enough. Other container cloud platforms are basically the same, please refer to this process for your own deployment. After logging in to ClawCloud Run, we click **App Launchpad** ![](https://img.072899.xyz/2025/10/080dfe9fd2c214ff9e507bd4d2bd5caa.png) Click **Create APP** ![](https://img.072899.xyz/2025/10/d44ca8835fac8cfc6b7a82a3ea4d95c9.png) First, we fill in the basic information * **Application Name**: Customizable, here fill in `cliproxyapi` * **Image Name**: `eceasy/cli-proxy-api:latest` * **Network**: Change the container port to `8317`, and open **Public Access** at the same time ![](https://img.072899.xyz/2025/10/1a4941e799911d181d658de450f6e5d7.png) Scroll down the page, in the advanced settings, we need to fill in: * **Command**: `/CLIProxyAPI/CLIProxyAPI --config /data/config.yaml` * **Environment Variables**: `DEPLOY=cloud` * **Local Storage**: `/data` ![](https://img.072899.xyz/2025/10/3370f4146f19e92087f188dac5184575.png) See the figure below for how to fill in environment variables and storage | ![](https://img.072899.xyz/2025/10/e854143ef56bd6a71a922cad921c08b2.png) | ![](https://img.072899.xyz/2025/10/d966536ab7dd785ffc36355fdb2536cc.png) | | --- | --- | After confirming that all information is filled in correctly, click **Deploy Application** in the upper right corner, and the application will start to deploy ![](https://img.072899.xyz/2025/10/dc49813c993e84e68af74747332b247b.png) Wait a moment, and the application can be deployed successfully. When the **Public Address** status becomes **Available**, the corresponding URL is the one we use to access `CLIProxyAPI`. Please save it for later use. ![](https://img.072899.xyz/2025/10/6502f6ce1d9a4f63c132966ae9c37064.png) While waiting for the deployment, we can prepare the `config.yaml` configuration file first. The example used this time is as follows. Please note: `remote-management.secret-key` is the key for remote management, and `api-keys` is the key used by the AI client to connect to `CLIProxyAPI`. Be careful to distinguish them. yaml port: 8317 remote-management: allow-remote: true secret-key: "ABCD-1234" disable-control-panel: false auth-dir: "/data/auths" debug: false logging-to-file: false usage-statistics-enabled: false request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: - "EFGH-5678" When the container status becomes **Active** ![](https://img.072899.xyz/2025/10/99cce03e91ceb4eca44b8a055d0b874a.png) We click the button in the figure to open the previously added **Local Storage** ![](https://img.072899.xyz/2025/10/6ce689a58a74037594e31f5d8e587af7.png) Click **Upload** in the upper right corner, select the `config.yaml` file you just prepared and upload it ![](https://img.072899.xyz/2025/10/d550a6d94c9a5f02852e2f12091ff2a0.png) After the upload is complete, click **Restart** to restart the container ![](https://img.072899.xyz/2025/10/e4e4e077371cff0f77d097ccf9b07da6.png) Wait a moment, after the container status becomes **Active** again, we can see that a new file has been generated in **Local Storage** ![](https://img.072899.xyz/2025/10/877144ceae6bdc3acc180f18e309c9ef.png) At the same time, click the **Logs** tab, you can see the log information as shown in the figure below ![](https://img.072899.xyz/2025/10/5da47dbaaace9befc61d18ffcca5298a.png) ![](https://img.072899.xyz/2025/10/af2ed8594a0626ca24dcf3427ff2e103.png) So far, `CLIProxyAPI` has successfully completed the entire deployment process. * * * **Use EasyCLI for remote OAuth authentication** Next, we use another official project [EasyCLI](https://github.com/router-for-me/EasyCLI) to perform remote OAuth addition. `EasyCLI` is a supporting project of `CLIProxyAPI`, which provides a graphical user interface (GUI) to manage `CLIProxyAPI`. Its biggest highlight is that it supports the complete OAuth authentication and authorization process (not just uploading authorization files, but also handling the entire authorization callback process), which is something that `CLIProxyAPI`'s own WebUI cannot do. Please go to the [EasyCLI program release page](https://github.com/router-for-me/EasyCLI/releases) to download the version suitable for your operating system (the author provides Mac, Linux, and Windows versions). This tutorial takes the Windows x64 version as an example. After opening the program, select **Remote** and enter the URL we recorded before ![](https://img.072899.xyz/2025/10/f1d6dce519e20cae93abaac261f4d269.png) Enter the `remote-management.secret-key` set in `config.yaml` for the password (in this example, it is `ABCD-1234`) Click **Authentication Files** -> **New** in order ![](https://img.072899.xyz/2025/10/00cbb95dfeab2b8047b8270292fbe2cc.png) This time we will still use adding Gemini CLI as an example for demonstration. For preparations, please refer to "Two: Gemini CLI + Codex Hands-on" Enter **Project ID**, click **Confirm** ![](https://img.072899.xyz/2025/10/994a104817d51e39f811ad190d6190d5.png) The OAuth link will appear on the page, click **Open Link** ![](https://img.072899.xyz/2025/10/361f9b6568609e589c959ca572de8955.png) The program will automatically open the browser and jump to the OAuth link, and `EasyCLI` itself will enter the callback receiving state ![](https://img.072899.xyz/2025/10/a10dab06835d7bc5d15af8cc1ca607ed.png) In the opened browser page, we log in to the account and complete the authorization and authentication process ![](https://img.072899.xyz/2025/10/d1dc0fe737eb8b0ce9f348f2f45871f1.png) After completion, you can see the newly generated configuration file in the **Authentication Files** list ![](https://img.072899.xyz/2025/10/d713a77479b41f4035f1bf66b2e538f6.png) **Verification** Let's test it with Cherry Studio again. As shown in the figure, fill in the API key and API address according to the configuration file content ![](https://img.072899.xyz/2025/10/8021ac702f232ded423b186dbcb50a90.png) Success! ![](https://img.072899.xyz/2025/10/5d0684f8cfecb1bc503f5189822911a3.png) The rest of the functions of `EasyCLI` are left for you to explore. In fact, except for the OAuth authentication part, the other functions of `EasyCLI` are basically the same as the system's built-in WebUI. You can also perform other configuration management by visiting `https://your-CLIProxyAPI-access-link/management.html` (for an introduction to WebUI, please refer to this article "Six: The Beginner's Favorite GUI", although the introduction is also relatively short =.=) --- # Two: Gemini CLI + Codex Hands-on | CLIProxyAPI [Skip to content](https://help.router-for.me/hands-on/tutorial-2.html#VPContent) Return to top Two: Gemini CLI + Codex Hands-on [​](https://help.router-for.me/hands-on/tutorial-2.html#two-gemini-cli-codex-hands-on) ======================================================================================================================== In the previous article, we successfully converted Qwen Code into an API and called it in Cherry Studio through a simple configuration on CLIProxyAPI. I believe that by reading this, you have a preliminary understanding of the powerful functions and convenience of this tool. In this tutorial, we will continue to explore and integrate Codex and Gemini CLI. It should be noted that the configuration file used in this operation is the same as the one in the previous Qwen tutorial. yaml port: 8317 # Please fill in the folder location according to your actual situation auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: # Please set the Key yourself, used for client access to the proxy - "ABC-123456" ### Configure Codex [​](https://help.router-for.me/hands-on/tutorial-2.html#configure-codex) First, let's configure Codex. The OAuth authorization process for Codex is very similar to the previous Qwen. Enter `cli-proxy-api --codex-login` in the terminal command line, and the system will automatically open the ChatGPT authorization page. Please log in with your ChatGPT account. ![](https://img.072899.xyz/2025/09/8d78b93fcfb3e111a93f6437f9a6acfa.png) If it is a ChatGPT Team account, you need to select the corresponding workspace. The page for successful authorization is as follows: ![](https://img.072899.xyz/2025/09/86518a31294a769281c7c5ef8946550e.png) Back in the terminal command line, you can see that the authentication file has been successfully generated and saved. ![](https://img.072899.xyz/2025/09/c4c9613c9b086a9d8af70d0cf31d75f9.png) If you have multiple ChatGPT accounts, just repeat the same operation a few times. It should be noted that currently Codex can only be used by paid ChatGPT members, and free users do not have permission. ### Configure Gemini CLI [​](https://help.router-for.me/hands-on/tutorial-2.html#configure-gemini-cli) Next, let's add Gemini CLI. Gemini CLI is completely free, but some users may encounter problems during the configuration process. Therefore, here I will take you through the entire authorization and authentication process step by step, starting from creating a Google Cloud project. First, please log in to [https://console.cloud.google.com/](https://console.cloud.google.com/) with your Google account. After successful login, click the position shown in the figure: ![](https://img.072899.xyz/2025/09/75416d68babdacc8ddd9bfd652a49b38.png) Click "New Project". ![](https://img.072899.xyz/2025/09/566e57546c8bcd73d7ce41e56581b4a5.png) After naming the project, click "Create". ![](https://img.072899.xyz/2025/09/9e90a699265fc1dcfb7755f7c1858b73.png) According to the position in the first step, select the project you just created. ![](https://img.072899.xyz/2025/09/a84803f955e057f34723227bdf55b145.png) First, copy the project ID in the red box for later use, and then click the position indicated by the arrow in the upper left corner. ![](https://img.072899.xyz/2025/09/c1d1617812ecea50c3a63dfb76eb5c04.png) Click "APIs & Services" -> "Enabled APIs & services" in order. ![](https://img.072899.xyz/2025/09/782d8096de6276f24fc8ca444ee2910d.png) Click "ENABLE APIS AND SERVICES". ![](https://img.072899.xyz/2025/09/1c0e48d7434bc76d37ef769d86684595.png) Enter `cloudaicompanion.googleapis.com` in the search box shown in the figure, and then click the searched "Gemini for Google Cloud". ![](https://img.072899.xyz/2025/09/a52b17b80635df9e46b8d5b49957e3d6.png) Click "Enable". ![](https://img.072899.xyz/2025/09/58afcf1004138c4c1d63474030d49dff.png) So far, all the preliminary preparations for Google Cloud have been completed. Now, let's go back to the directory where the CLIProxyAPI program is located, open the terminal command line, and enter `cli-proxy-api --login --project_id [your project ID]`. For example, in this case, it is `cli-proxy-api --login --project_id mimetic-planet-473413-v7`. Then the authorization page will pop up. Please log in with the Google account that you just used for preparation. ![](https://img.072899.xyz/2025/09/51ca74eb061751336d110b3421c43548.png) The page for successful verification is as follows: ![](https://img.072899.xyz/2025/09/346f6add9a943f0c324afbad856cc3bf.png) Back in the terminal command line, you can see that the authentication file has been successfully saved. ![](https://img.072899.xyz/2025/09/8682dc8a08bffd34d7900819e1073960.png) Some readers may be curious why the command line information after successful verification of Codex and Gemini CLI is different from that of Qwen. The answer is that when verifying Codex and Gemini CLI, CLIProxyAPI will listen to a specific port locally to receive callbacks, so the verification is always successful at one time. When verifying Qwen, CLIProxyAPI will directly obtain authorization information from Qwen's verification server, so there will be up to 60 attempts. ### Verify the model [​](https://help.router-for.me/hands-on/tutorial-2.html#verify-the-model) Let's verify the Codex and Gemini CLI we just added through OAuth. Add the model in Cherry Studio as shown below: ![](https://img.072899.xyz/2025/09/db8e65c9548213303da43cc214ee5000.png) Try Gemini-2.5-Pro: ![](https://img.072899.xyz/2025/09/a2fc6ce45adcf334a2908984a8db428d.png) Let's ask GPT-5-Codex again: ![](https://img.072899.xyz/2025/09/c07a3dbd57f728186ad835fa5afdde6d.png) So far, all models have been successfully integrated. Have you learned it? --- # Zero-Cost Deployment (AIStudio Reverse Proxy) | CLIProxyAPI [Skip to content](https://help.router-for.me/hands-on/tutorial-11.html#VPContent) Return to top Zero-Cost Deployment (AIStudio Reverse Proxy) [​](https://help.router-for.me/hands-on/tutorial-11.html#zero-cost-deployment-aistudio-reverse-proxy) ==================================================================================================================================================== > **Please note:** The deployment solution in this tutorial needs to be used with `CLIProxyAPI`. Before you begin, please ensure you have a running instance of `CLIProxyAPI`. Starting from v6.3.x, CLIProxyAPI supports connecting to AI Providers via WebSocket, with AIStudio being the first one supported. However, this method requires a browser to be always open to run the WebSocket communication program on AIStudioBuild, which can be inconvenient. If you choose to deploy it on a VPS, you will face the issue of high memory requirements for the VPS. To solve this problem, I spent some time trying various headless browser solutions. Ultimately, I chose to use Docker for deployment on HuggingFace, which takes full advantage of the large memory of HuggingFace's free instances to achieve zero-cost deployment. ### Step 1: Configure the AIStudioBuild Application [​](https://help.router-for.me/hands-on/tutorial-11.html#step-1-configure-the-aistudiobuild-application) You need to configure the WebSocket communication program on AIStudioBuild according to your `CLIProxyAPI` settings: Open the official [sample program](https://aistudio.google.com/apps/drive/1CPW7FpWGsDZzkaYgYOyXQ_6FWgxieLmL) , copy it, and then you **must** modify the two places marked in the red box in the image. Specifically, if `wsauth` is set to `true` in `CLIProxyAPI`, you need to set `JWT_TOKEN` to the `api-keys` value intended for authentication in `CLIProxyAPI`. Set `WEBSOCKET_PROXY_URL` to the address of your `CLIProxyAPI`, for example: `wss://mycap.example.com/v1/ws`. After configuring, save it and keep the link to this application for later use. ![](https://img.072899.xyz/2025/11/359a2572d0206c20dba7fe12a136d6e8.png) When using multiple accounts, you need to perform an additional step: set the application's access permission to `Public`. ![](https://img.072899.xyz/2025/11/69c6395d1a98c38c68bc6c8dd46b3014.png) **Security Warning:** After setting it to `Public`, please keep your link safe. **Do not** share this link publicly to avoid leaking authorization information. ### Step 2: Prepare AIStudio Cookie [​](https://help.router-for.me/hands-on/tutorial-11.html#step-2-prepare-aistudio-cookie) For this step, it is recommended to use your browser's private mode. Log in to [https://aistudio.google.com/](https://aistudio.google.com/) and copy the Cookie from the browser's developer tools. The specific location is shown in the image below: ![](https://img.072899.xyz/2025/11/51f860bf363cab01aa4c3fd5181b7f72.png) ### Step 3 (1): Deploy HuggingFace Space [​](https://help.router-for.me/hands-on/tutorial-11.html#step-3-1-deploy-huggingface-space) Open [https://huggingface.co/spaces/hkfires/AIStudioBuildWS](https://huggingface.co/spaces/hkfires/AIStudioBuildWS) and duplicate the Space. Fill in the `CAMOUFOX_INSTANCE_URL` field with the link to the program you prepared in Step 1, and fill in the `USER_COOKIE_1` field with the Cookie you prepared in Step 2. Then, click "Duplicate Space". ![](https://img.072899.xyz/2025/11/04e84ce3b0f2abe7ae9e717ac8b5aa0b.png) Wait for HuggingFace to complete the build. When you see logs like the following, the deployment is successful: ![](https://img.072899.xyz/2025/11/e818f38cfb272c1fc10ca97c2ef23c6b.png) If you have multiple accounts, refer to `USER_COOKIE_1` and add environment variables like `USER_COOKIE_2`, `USER_COOKIE_3`, etc., in the HuggingFace Space settings. **Important Reminder:** Cookies are sensitive information. Please **be sure to use "Secrets"** (not "Variables") to store them to prevent leakage. ### Step 3 (2): Server Docker Deployment [​](https://help.router-for.me/hands-on/tutorial-11.html#step-3-2-server-docker-deployment) If you have your own server (VPS), you can also use Docker Compose for deployment. 1. **Download the Code** bash git clone https://github.com/hkfires/AIStudioBuildWS.git cd AIStudioBuildWS 2. **Configure Environment Variables** Copy `.env.example` to `.env` and fill in the necessary information (`CAMOUFOX_INSTANCE_URL` and `USER_COOKIE_1`, etc.). You can also place Cookie files in JSON format (any filename) in the `cookies` directory, and the program will automatically read them. bash cp .env.example .env nano .env 3. **Start the Service** bash docker compose up -d --build After a successful deployment, you should see logs similar to the following in `CLIProxyAPI`. At this point, the entire deployment is complete. ![](https://img.072899.xyz/2025/11/e0db39f81a3bbb956cbe9364e656a76f.png) ### Reference Project [​](https://help.router-for.me/hands-on/tutorial-11.html#reference-project) [https://github.com/cliouo/aistudio-build-proxy-all](https://github.com/cliouo/aistudio-build-proxy-all) --- # Zero-Cost Deployment: Render (Git Storage) | CLIProxyAPI [Skip to content](https://help.router-for.me/hands-on/tutorial-10.html#VPContent) Return to top Zero-Cost Deployment: Render (Git Storage) [​](https://help.router-for.me/hands-on/tutorial-10.html#zero-cost-deployment-render-git-storage) ============================================================================================================================================= After the release of yesterday's article "Zero-Cost Deployment (ClawCloud)", I went on to test the Render platform and found that its free plan does not include persistent storage. After reporting this to the author of CLIProxyAPI, he updated the version overnight, adding the function of persistent storage through Git. In this way, we can save the configuration files and authentication files in a private GitHub repository, without relying on the persistent storage of the container cloud. Next, this article will guide you step by step on how to deploy CLIProxyAPI on a container service without persistent storage (such as Render's free plan). As for the part of OAuth authentication through EasyCLI, it is exactly the same as the deployment on ClawCloud, please refer to the previous article. ### 1\. Github Preparation [​](https://help.router-for.me/hands-on/tutorial-10.html#_1-github-preparation) First, we need to create an empty repository on GitHub. The repository name can be customized, but it **must** be set to **private**, otherwise the sensitive information such as the API Key you add will be exposed. ![](https://img.072899.xyz/2025/10/311e26cb4da97cafd7bb3b924440e858.png) After creating the repository, note down the URL address of the repository. Next, we click on the personal avatar in the upper right corner of the page, enter **Settings**, and then click **Developer Settings** at the bottom of the left menu. ![](https://img.072899.xyz/2025/10/a79377c7af3c80ec58ad853d12762b6c.png) Next, click **Personal access tokens** -> **Fine-grained tokens** in order, and then click **Generate new token** in the upper right corner. ![](https://img.072899.xyz/2025/10/90fa44065df641c7599b8d16e84edf60.png) Fill in the **Token name** as shown in the figure (customizable), select the expiration time according to your needs (**Expiration**), and select **Only select repositories** in **Repository access**, and then select the blank repository we just created. ![](https://img.072899.xyz/2025/10/74b5484e44a28293335160a9d42bb190.png) Scroll down the page, find **Contents** in **Permissions** -> **Add permissions**, add it and change its permission from `Read-only` to `Read and write`. ![](https://img.072899.xyz/2025/10/825aafe9f3a52fc431a3ec54829777de.png) After confirming that the permission settings are correct, click **Generate token** at the bottom of the page. ![](https://img.072899.xyz/2025/10/0b5f56df634cea1e3552b8560c7f175a.png) At this time, the generated Token will be displayed on the page. Please note that **this Token will only be displayed once**. After the page is closed, it will not be viewable. Please be sure to copy and save it properly. ![](https://img.072899.xyz/2025/10/a04fc4a6a75cab2222ba28d46e4463e9.png) So far, the preparation work for GitHub is complete. ### 2\. Render Deployment [​](https://help.router-for.me/hands-on/tutorial-10.html#_2-render-deployment) First, please make sure you have registered a Render account. After logging in, create a new project and select **New Web Service**. ![](https://img.072899.xyz/2025/10/0398d8d1483fe65d556727ec23075eaf.png) Select **Existing Image** in the deployment method, enter `eceasy/cli-proxy-api:latest` in the **Image URL**, and then click **Connect**. ![](https://img.072899.xyz/2025/10/4ee784242be93bee942f0eea64d51af5.png) Enter the service name (**Name**, customizable), select the region (**Region**, you can choose according to your personal preference), and make sure the instance type is **Free**. ![](https://img.072899.xyz/2025/10/90d6fb2b4a5d401d02a917f82396c304.png) Next, we need to add 4 environment variables: * `GITSTORE_GIT_URL`: Your GitHub repository address * `GITSTORE_GIT_USERNAME`: Your GitHub username * `GITSTORE_GIT_TOKEN`: The Personal Access Token you just created * `MANAGEMENT_PASSWORD`: The password for logging in to the management interface After entering, click **Deploy Web Service** at the bottom of the page. ![](https://img.072899.xyz/2025/10/d4b39d6e4f10a19ada98e4af0e505df9.png) Wait for the deployment log to scroll. When the status becomes **Live** and the log shows `Available at your primary URL：XXXX`, the program has successfully started. ![](https://img.072899.xyz/2025/10/f77a35fa4f805e78fbcff663c6cf5aae.png) Use the URL provided by Render and add `/management.html` after it to enter the WebUI. Enter the `MANAGEMENT_PASSWORD` you set to log in. ![](https://img.072899.xyz/2025/10/af84a3b0d2cc0197f2b4ecb3497c802e.png) At this time, if you check your GitHub repository again, you will find that two folders have been automatically generated in it. ![](https://img.072899.xyz/2025/10/03bbde6090e53ae3362a624badd35319.png) So far, the entire process of deploying CLIProxyAPI on Render is complete. Other similar container cloud platforms can also be deployed using this method, and you can explore them yourself. ### 3\. Precautions [​](https://help.router-for.me/hands-on/tutorial-10.html#_3-precautions) 1. CLIProxyAPI added this function after v6.2.2. If you want to specify the image version, the selected version should be at least `eceasy/cli-proxy-api:v6.2.2`. 2. After deploying in this way, the `remote-management` part of the configuration file will no longer be effective, and the management password will be based on the environment variable. This means that if you want to modify the management password, you need to directly modify the environment variable `MANAGEMENT_PASSWORD`. 3. Using GitHub to store configuration files and authentication files does not mean that they can be shared and called in multiple container instances at the same time. Please be sure to avoid this situation to avoid conflicts. 4. Please note that any manual changes made directly in the GitHub repository while the container is running will be invalid. If you really need to modify it manually, please be sure to stop the container service first. 5. It is recommended to use WebUI or EasyCLI to manage the configuration. Using EasyCLI can also perform remote authentication of OAuth. For specific methods, please refer to the relevant content in "Zero-Cost Deployment (ClawCloud)" mentioned at the beginning of this article. --- # AmpCode Usage Guide | CLIProxyAPI [Skip to content](https://help.router-for.me/hands-on/tutorial-12.html#VPContent) Return to top AmpCode Usage Guide [​](https://help.router-for.me/hands-on/tutorial-12.html#ampcode-usage-guide) ================================================================================================== You might not have heard of **AmpCode** (probably because there's no "free lunch" channel?). In fact, AmpCode has established itself in the AI programming field with its unique philosophy. Its core feature is **efficiency first, cost second**—users don't need to worry about model selection; the system automatically calls the best model for the job. Therefore, AmpCode does not natively support model switching, let alone using third-party models. AmpCode mainly has two modes: * **Free Mode:** Free use of the Claude Haiku 4.5 model, at the cost of including ads (is this the only Agent tool with ads currently?). * **Smart Mode:** Automatically selects the strongest model combination available. At this point in time (December 2025), Smart Mode typically calls Claude Opus 4.5 for complex tasks, Claude Haiku 4.5 for high-frequency simple responses, and uses GPT 5.1 as a SubAgent for multi-dimensional logical completion. This article will teach you how to combine **AmpCode + CLIProxyAPI** to achieve the goal of "using your own models in AmpCode". ### 1\. Configure CLIProxyAPI [​](https://help.router-for.me/hands-on/tutorial-12.html#_1-configure-cliproxyapi) First, we need a configured CLIProxyAPI. For specific deployment methods, please refer to my previous CLIProxyAPI tutorial series, which I won't repeat here. After the regular configuration of CLIProxyAPI, we need to add the following AmpCode-related settings to the configuration file: yaml ampcode: upstream-url: "https://ampcode.com" restrict-management-to-localhost: false upstream-api-key: "sgamp_user_XXXX" force-model-mappings: false model-mappings: - from: claude-opus-4-5-20251101 to: gemini-claude-sonnet-4-5 - from: claude-sonnet-4-5-20250929 to: gemini-claude-sonnet-4-5 - from: claude-haiku-4-5-20251001 to: qwen3-coder-flash **Configuration Item Explanation:** * `upstream-url`, `restrict-management-to-localhost`, `upstream-api-key`: If you have an AmpCode account and want to view session information in the official dashboard, please fill in these three items. The `upstream-api-key` can be copied from the AmpCode dashboard (as shown below). ~If you don't have an AmpCode account, just delete these three lines.~ **Note:** After a recent update to the AmpCode client, filling in upstream information is now mandatory, so this part is required. ![](https://img.072899.xyz/2025/12/1e6e2eab382f693c3c70c2017e7e7c8f.png) * `model-mappings` **(Important!)**: This is the most critical part of the configuration. We need to understand the processing logic of CLIProxyAPI: When AmpCode requests a specific model (e.g., `claude-opus-4-5-20251101`), CLIProxyAPI will first look it up in the registered model list. * **Case A:** If the model exists, request that model directly (model-mappings does not take effect). * **Case B:** If the model does not exist, CLIProxyAPI should have reported an error, but by configuring model-mappings, we can **redirect** the request to a model we specify (e.g., `gemini-claude-sonnet-4-5`). > **An example to help understand:** > > Suppose AmpCode requests `claude-opus-4-5-20251101`. If this model exists in CLIProxyAPI, then AmpCode will use the `claude-opus-4-5-20251101` model in CLIProxyAPI; If this model is not configured in CLIProxyAPI, the system will trigger the `model-mappings` rule and hand over the request to `gemini-claude-sonnet-4-5` for response. Through the above rules, we have successfully achieved "grafting", taking over AmpCode's requests with our own models. > > (If you still have doubts about this logic, it is recommended to read the above paragraph a few more times~) * `force-model-mappings`: This is a boolean value (`true` or `false`), defaulting to `false`. When set to `true`, CLIProxyAPI will **force** the application of redirection rules in `model-mappings`, **even if "Case A" is met** (i.e., the `from` model itself exists in CLIProxyAPI). This option is very suitable for scenarios where you need to **temporarily override** or **unify management** of model requests. For example, even if you have already configured `claude-opus-4-5-20251101` in your CLIProxyAPI, you can still force all its requests to be redirected to `gemini-claude-sonnet-4-5` by enabling this option. Once the above configuration is completed, the CLIProxyAPI side is ready. ### 2\. Configure AmpCode Client [​](https://help.router-for.me/hands-on/tutorial-12.html#_2-configure-ampcode-client) AmpCode supports multi-platform clients. You can choose according to your usage habits. The following will explain two ways: configuring the command line tool (Amp CLI) and the VSCode extension. #### Method 1: Configure Amp CLI [​](https://help.router-for.me/hands-on/tutorial-12.html#method-1-configure-amp-cli) The following takes installing Amp CLI in **WSL2 Debian** as an example for reference. ![](https://img.072899.xyz/2025/12/7979738f3bd96c95c20d06889a74f29e.png) Copy the official installation script to install: `curl -fsSL https://ampcode.com/install.sh | bash` **Note:** Do not run it immediately after installation; we need to edit the environment variables. Enter `nano ~/.bashrc` and add the following content at the bottom of the file: bash export AMP_URL="http://Your-CPA-Deployment-Address:Port" export AMP_API_KEY="Your-API-Key-Set-In-CPA" After saving and exiting, run `source ~/.bashrc` to make the configuration take effect. #### Method 2: Configure VSCode Extension [​](https://help.router-for.me/hands-on/tutorial-12.html#method-2-configure-vscode-extension) If you are more accustomed to developing in VSCode, AmpCode also provides an official extension. 1. **Install Extension**: Search for and install the `AmpCode` extension in the VSCode Extension Marketplace. ![](https://img.072899.xyz/2025/12/d62cd472a9e7837929308a732c479ea5.png) 2. **Open Settings**: Search for `Preferences: Open User Settings (JSON)` via the Command Palette (`Ctrl+Shift+P`) to open the `settings.json` file. 3. **Add Configuration**: Add the following configuration to `settings.json`, pointing `amp.url` to your CLIProxyAPI service address: json { // ... other configurations "amp.url": "http://Your-CPA-Deployment-Address:Port" } 4. **Login**: After configuration is complete, click the AmpCode icon in the sidebar. The extension interface will display the URL you configured. Enter the `api-keys` you set in CLIProxyAPI in the red box to log in and use (note that it is not the Key provided by the official AmpCode website). ![](https://img.072899.xyz/2025/12/98ceb48e3b4c10f0d86a2f138838ff26.png) ### 3\. Verify Results [​](https://help.router-for.me/hands-on/tutorial-12.html#_3-verify-results) Regardless of which client you use, the verification method is similar: * **For Amp CLI users:** Type `amp` and try sending a prompt. If everything goes well, you will see the following interface: ![](https://img.072899.xyz/2025/12/bba2d9f3010ca2a78db6ac5c63b6645c.png) * **For VSCode Extension users:** After successful login, send a prompt in the AmpCode chat window, and the extension will return results normally. ![](https://img.072899.xyz/2025/12/c6af979f543fffc6d43b9e88ed7e01c8.png) At the same time, in the background logs of CLIProxyAPI, we can also clearly see that the corresponding request has been successfully forwarded: ![](https://img.072899.xyz/2025/12/3e15d2ef067d8a6deaa8e629465cbfa8.png) Mission accomplished! --- # Zero-Cost Deployment: Railway (Object Storage) | CLIProxyAPI [Skip to content](https://help.router-for.me/hands-on/tutorial-9.html#VPContent) Return to top Zero-Cost Deployment: Railway (Object Storage) [​](https://help.router-for.me/hands-on/tutorial-9.html#zero-cost-deployment-railway-object-storage) ==================================================================================================================================================== Following the first two articles in the "No VPS?" series, I have tried some other container clouds. Coinciding with the addition of S3 bucket support to the CLIProxyAPI program, this article will introduce a new combination: using the Railway container service and deploying with a ClawCloud S3 bucket. Before you start, please make sure you have accounts for [ClawCloud](https://run.claw.cloud/) and [Railway](https://railway.com/) . ### 1\. Create a ClawCloud bucket [​](https://help.router-for.me/hands-on/tutorial-9.html#_1-create-a-clawcloud-bucket) After logging in to ClawCloud, click to enter **Object Storage** ![](https://img.072899.xyz/2025/10/8350104852042e43ba4c3dad25fd0004.png) Next, click **Create bucket** ![](https://img.072899.xyz/2025/10/9f5953f5a406a21d2ff914cfa01638c9.png) Enter a custom bucket name (the name must be in lowercase), and then click **Create** in the upper right corner ![](https://img.072899.xyz/2025/10/39db7fd3e8ca4a57c46191be889e0f15.png) At this point, the bucket has been created. Next, we need to record the following 4 key parameters: the full name of the bucket (shown in the red box in the figure), Access Key, Secret Key, and External address ![](https://img.072899.xyz/2025/10/ef6c22c9cc50eee9152e4c95454786dd.png) ![](https://img.072899.xyz/2025/10/a3931df797a65db7afecf18cb66e66ce.png) These 4 parameters will be used to set environment variables respectively. In addition, we also need to set an additional `MANAGEMENT_PASSWORD` (the password for logging in to the WebUI). Please organize this information in the following format and save it properly: OBJECTSTORE_ENDPOINT=External value OBJECTSTORE_ACCESS_KEY=Access Key value OBJECTSTORE_SECRET_KEY=Secret Key value OBJECTSTORE_BUCKET=Full bucket name MANAGEMENT_PASSWORD=Password to access WebUI ### 2\. Manual deployment on Railway [​](https://help.router-for.me/hands-on/tutorial-9.html#_2-manual-deployment-on-railway) In the Railway project dashboard, click **Create**, and select **Docker image** ![](https://img.072899.xyz/2025/10/f9dfb05a9991e5a228fa18629168588c.png) Enter `eceasy/cli-proxy-api:latest` and press Enter. After a while, a new container will appear in the workspace ![](https://img.072899.xyz/2025/10/dec39863e684dd39f63acd1ebbe401e9.png) Click this newly created container, and select **Variables** -> **Raw Editor** in the right panel ![](https://img.072899.xyz/2025/10/d3d5d5b5144d2016ff4d8ddf8953a819.png) Paste the environment variables we prepared earlier, and then click **Update Variables** ![](https://img.072899.xyz/2025/10/accaf8ea92a57371cf1d1994be59cd9f.png) Click the **Deploy** button to start deployment ![](https://img.072899.xyz/2025/10/6889a73eb138f8e1dca7ab0fb4b79b21.png) After waiting for the deployment to complete (the "Deployment successful" prompt appears), click to enter the **Settings** tab ![](https://img.072899.xyz/2025/10/a1059beca1671b505b4909c36ae51f68.png) In the **Public Networking** section, click **Generate Domain** ![](https://img.072899.xyz/2025/10/e3d3efbcc34db844c81ee1eefda48e22.png) Set the port number to `8317`, and then click **Generate Domain** ![](https://img.072899.xyz/2025/10/6ddb5ee7884c2c239b02edca10ca2668.png) At this time, Railway will generate a public access address for you. You can access the WebUI interface of CLIProxyAPI through this address. If you can open the web page, the deployment is successful. ![](https://img.072899.xyz/2025/10/d216af36328e62147889108799278561.png) ### 3\. Railway template deployment [​](https://help.router-for.me/hands-on/tutorial-9.html#_3-railway-template-deployment) In addition, Railway also supports one-click deployment through templates. You can directly click the button below to start (note: this link contains AFF) [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/0uGPyR?referralCode=JC4tEx&utm_medium=integration&utm_source=template&utm_campaign=generic) If you use template deployment, please note that you need to confirm whether the service port is `8317` after the deployment is complete. If not, you need to modify it manually. The specific modification steps are as follows: ![](https://img.072899.xyz/2025/10/e741f1f62e4726a16e75b1264ad4438e.png) ![](https://img.072899.xyz/2025/10/ba2c7d7bac37b3bcdd3aebb220c6fb0b.png) ![](https://img.072899.xyz/2025/10/39b49aea18026f80834bf0ee22d405a3.png) So far, all deployment processes have been completed. For subsequent usage, you can refer to the **"Use EasyCLI for remote OAuth authentication"** section in the "Zero-Cost Deployment (ClawCloud)" tutorial. **Additional note**: In addition to ClawCloud, any object storage service compatible with the S3 API (such as Cloudflare R2) can theoretically be used as an alternative. --- # Three: NanoBanana Hands-on | CLIProxyAPI [Skip to content](https://help.router-for.me/hands-on/tutorial-3.html#VPContent) Return to top Three: NanoBanana Hands-on [​](https://help.router-for.me/hands-on/tutorial-3.html#three-nanobanana-hands-on) ============================================================================================================== > **Important Notice: Since Gemini CLI now fully covers Gemini Web and is completely free, CLIProxyAPI will remove Gemini Web support starting from version 6.2.X. If you still want to use Gemini Web, you can use version 6.1.X. The following tutorial is based on version 6.1.X** After the hands-on practice in the first two issues, we have successfully integrated `Qwen Code`, `Gemini CLI`, and `Codex` on `CLIProxyAPI`. This issue will introduce how to add Gemini Web's Cookie to make `CLIProxyAPI` support the `NanoBanana` model. Gemini's `NanoBanana` model is highly praised for its excellent image processing capabilities. However, Google does not provide a free API for this model. Now, with `CLIProxyAPI`, we can use `NanoBanana` in the form of a free API by integrating Gemini Web. We have two ways to obtain authentication information: ### The first method [​](https://help.router-for.me/hands-on/tutorial-3.html#the-first-method) First, log in to the Gemini official website ([https://gemini.google.com/app](https://gemini.google.com/app) ) with your Google account. It is understood that ordinary accounts have 100 image generation quotas per day, while Pro accounts have 1000. After successful login, press F12 in the browser to open the developer tools and switch to the "Network" tab. ![](https://img.072899.xyz/2025/09/074fcf1c455e99185ceeada71a27bd8c.png) Enter `List` in the filter box, and then hover the mouse over your user avatar. After a while, the `ListAccounts` entry should appear in the list below. If it does not appear, please refresh the page and try again. ![](https://img.072899.xyz/2025/09/7cb7104fa93a6b6a6903e0745d3b5573.png) Click `ListAccounts`, find `Cookie` in "Headers" -> "Request Headers", and copy its value completely. ![](https://img.072899.xyz/2025/09/c2ba085f10fcb145aff7e9d5081b9382.png) Go back to the directory where the `CLIProxyAPI` program is located, open the terminal or command line, and enter the command `cli-proxy-api --gemini-web-auth`. According to the prompt, paste the `Cookie` value we just copied and press Enter, you will see a message of successful verification, and the `Cookie` has been automatically saved. ![](https://img.072899.xyz/2025/09/e149d07875cb8dab12de95f82d2b3e45.png) ### The second method [​](https://help.router-for.me/hands-on/tutorial-3.html#the-second-method) If you are using a macOS system, or if the first method of authentication fails, you may need to manually enter the values of `__Secure-1PSID` and `__Secure-1PSIDTS`. Please switch to the "Application" tab and copy these two values as shown in the figure. ![](https://img.072899.xyz/2025/09/e5b5debae5ec74a31a1b527e506895e7.png) ![](https://img.072899.xyz/2025/09/7767f178e1186358f1a9a498108e5ac0.png) When performing verification on the command line, manually fill in these two values according to the prompts to complete the verification. ![](https://img.072899.xyz/2025/09/b02fb7704d5c67385d781f9d9893e0b2.png) ### Verification steps [​](https://help.router-for.me/hands-on/tutorial-3.html#verification-steps) Next, we will perform verification. It should be noted that the program currently only supports text-to-image or image-to-text operations through OpenAI compatible interfaces and Gemini native interfaces. Therefore, the provider type `OpenAI Response` we previously set in `Cherry Studio` needs to be changed to `OpenAI`. ![](https://img.072899.xyz/2025/09/48892cc3ce1e3c4379b694afa45c5d35.png) Add the model `NanoBanana` (ie `gemini-2.5-flash-image-preview`). ![](https://img.072899.xyz/2025/09/4674845c6412ec6f5366d109070047fc.png) Now, let's test it in `Cherry Studio`! ![](https://img.072899.xyz/2025/09/fdd35aa92224cd76cbf888ce3ff2cce2.png) Perfectly meets our requirements, enjoy the "banana"! ### Precautions [​](https://help.router-for.me/hands-on/tutorial-3.html#precautions) * ~At this stage, please avoid adding multiple Gemini Web accounts in `CLIProxyAPI`. Because when there are multiple accounts, the program will poll calls, which may break the continuity of the conversation and cause the request to fail.~ After the 6.0.17 version update, the program supports Gemini Web sticky sessions, and multiple accounts can be added. * In `Cherry Studio`, **do not** add the `NanoBanana` model under the `OpenAI Response` provider type. It is known that `Cherry Studio` has a bug in this case, which will cause the program to crash. --- # One: Project Introduction + Qwen Hands-on | CLIProxyAPI [Skip to content](https://help.router-for.me/hands-on/tutorial-1.html#VPContent) Return to top One: Project Introduction + Qwen Hands-on [​](https://help.router-for.me/hands-on/tutorial-1.html#one-project-introduction-qwen-hands-on) ========================================================================================================================================== CLIProxyAPI is an open-source AI proxy tool written in Go. Perhaps because of its unpretentious name, many people may still be unfamiliar with it. Before I came across it, in order to "get for free" the Gemini model, I had tinkered with several reverse proxy tools such as AIStudioProxyAPI, AIStudio-Build-Proxy, and Gemini-FastAPI, but they all had some unsatisfactory aspects. Until I discovered CLIProxyAPI and used it extensively for several months, I can say with certainty: whether in terms of performance, functionality, or applicability, it is the best AI proxy tool I have ever used, bar none. It's no exaggeration to call it a "divine tool". > **Official repository address**: [https://github.com/router-for-me/CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) ### **What exactly can it do?** [​](https://help.router-for.me/hands-on/tutorial-1.html#what-exactly-can-it-do) | Software Features | Supported Models | | --- | --- | | Provides OpenAI/Gemini/Claude/Codex compatible API endpoints for CLI models | gemini-2.5-pro | | Added OpenAI Codex (GPT series) support (OAuth login) | gemini-2.5-flash | | Added Claude Code support (OAuth login) | gemini-2.5-flash-lite | | Added Qwen Code support (OAuth login) | gemini-2.5-flash-image-preview | | Added iFlow support (OAuth login) | gpt-5 | | Added Gemini Web support (login via Cookie) | gpt-5-codex | | Supports streaming and non-streaming responses | claude-opus-4-1-20250805 | | Function calling/tool support | claude-opus-4-20250514 | | Multimodal input (text, images) | claude-sonnet-4-20250514 | | Multi-account support and round-robin load balancing (Gemini, OpenAI, Claude, Qwen, and iFlow) | claude-sonnet-4-5-20250929 | | Simple CLI authentication process (Gemini, OpenAI, Claude, Qwen, and iFlow) | claude-3-7-sonnet-20250219 | | Supports Gemini AIStudio API keys | claude-3-5-haiku-20241022 | | Supports Gemini CLI multi-account polling | qwen3-coder-plus | | Supports Claude Code multi-account polling | qwen3-coder-flash | | Supports Qwen Code multi-account polling | qwen3-max | | Supports iFlow multi-account polling | qwen3-vl-plus | | Supports OpenAI Codex multi-account polling | deepseek-v3.2 | | Connect to upstream OpenAI-compatible providers (e.g., OpenRouter) through configuration | deepseek-v3.1 | | Reusable Go SDK | deepseek-r1 | | | deepseek-v3 | | | kimi-k2 | | | glm-4.6 | | | tstars2.0 | | | and other models supported by iFlow | In short, the core advantages of CLIProxyAPI include: * **No need to install Gemini CLI** to convert its authorization into a universal API Key, allowing you to call the full-featured Gemini 2.5 Pro, Gemini 2.5 Flash, and Gemini 2.5 Flash Lite models in any application. When the official model quota is exhausted, it automatically switches to the Preview model (e.g., `gemini-2.5-pro-preview-05-06`), allowing you to use up to 1000 calls per day, easily achieving "Gemini freedom". * **No need to install Qwen Code** to convert its authorization into a universal API Key, allowing you to call Qwen3 Coder Plus and Qwen3 Coder Flash models anywhere, achieving "Qwen3 Coder freedom". * **No need to install Codex** to convert its authorization into a universal API Key, allowing you to call GPT-5 and GPT-5-Codex models anywhere. Especially with the current promotion of free Team accounts, it's easy to achieve "GPT freedom". * **Convert the Gemini web version into an API Key** to call web-based models like Nano Banana anywhere (client support required. According to user sharing, the free version of Gemini web accounts can be called about 100 times a day, while Gemini Pro users can reach up to 1000 times). * **Powerful load balancing capability**. CLIProxyAPI supports integrating multiple accounts from different sources (whether API Keys or OAuth authorizations) for load balancing and round-robin polling, which means you can easily double your call quota. * **Extremely low resource consumption**. It is worth mentioning that the program consumes very few system resources. The program itself is only about 10MB, memory usage at startup is less than 10MB, and the peak memory usage over a long period is only about 100MB, so it can run smoothly on almost any computer. The program is very simple to use. The official not only provides binary files and Docker deployment methods for various platforms, but also provides EasyCLI and WebUI, which are very friendly to novices. All settings are managed through the `config.yaml` configuration file and support hot reloading—modifications take effect immediately without restarting the program. For a complete explanation of the configuration items, see "Zero: Detailed Configuration Explanation". ### **Hands-on Tutorial: Converting Qwen Code to an API Key** [​](https://help.router-for.me/hands-on/tutorial-1.html#hands-on-tutorial-converting-qwen-code-to-an-api-key) Below, we will use converting Qwen Code to an API Key on the Windows platform as an example to demonstrate the specific usage of CLIProxyAPI. 1. **Download and Unzip** First, download the pre-compiled executable file from the official repository and unzip it to any folder. In this example, I placed it in the `Z:\CLIProxyAPI` directory. We only need the two files shown in the figure. ![](https://img.072899.xyz/2025/09/b247eb98e0172c799c452d647ab09836.png) 2. **Edit the Configuration File** Rename `config.example.yaml` to `config.yaml`, then open it with a text editor, and only need to keep and modify the following basic configuration items: yaml port: 8317 # Please fill in the folder location according to your actual situation auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: # Please set the Key yourself, used for client access to the proxy - "ABC-123456" 3. **Get Authorization** Open a terminal in the `CLIProxyAPI` directory, enter `cli-proxy-api --qwen-login` and press Enter. The program will automatically open a browser. Please log in to your Qwen account in the browser and complete the authorization. ![](https://img.072899.xyz/2025/09/ec2e867f5a8de1d24969cb5225cdaa9e.png) After completing the authorization, return to the terminal, and the program will try to obtain authentication information. After success, it will ask you to enter an email or nickname (as shown by the red arrow in the figure). This is just an alias used to identify the account and can be filled in arbitrarily. I filled in `qwen-example` here. After pressing Enter, you can see that the authentication file has been successfully generated and saved to the location specified by `auth-dir` in the configuration file. ![](https://img.072899.xyz/2025/09/8d37d893884910db77bd4498373a4922.png) > **Tip**: If the system does not automatically open the browser, don't worry. Manually copy the URL marked in the red box in the terminal and paste it into the browser to complete the authorization. 4. **Start the Proxy Service** The above steps complete the account authentication. Now, let's officially start the proxy service. Double-click the executable file (`cli-proxy-api.exe`), and the following window appears, indicating that the startup is successful. ![](https://img.072899.xyz/2025/09/9e75a484a7f0713c6b56f1fd9a749195.png) 5. **Configure and Test in the Client** At this point, everything is ready. Below we use Cherry Studio for testing. * Add a new model provider in Cherry Studio. ![](https://img.072899.xyz/2025/09/2a2d401e75d02421861e136a6e377f5b.png) * The model provider type can be any type other than Azure. Here we take `OpenAI-Response` as an example. The provider name can be customized, for example, `CLIProxyAPI`. ![](https://img.072899.xyz/2025/09/3161b549ee3877342f178b2828a30dc6.png) * **API Key**: Fill in the Key we set ourselves in `config.yaml`, which is `ABC-123456` in this example. * **API Address**: Fill in the address and port of our local service. Remember the port number `8317` in the configuration file? Here we fill in `http://127.0.0.1:8317`. ![](https://img.072899.xyz/2025/09/5f9638b5f5e5c14d4a818b7362167083.png) * Click "Manage Models", and you can see the Qwen Code model loaded through the proxy. ![](https://img.072899.xyz/2025/09/9a5d68865bfd1d5fa1cf7778860e6a76.png) * After adding the model, let's test it. ![](https://img.072899.xyz/2025/09/83fd73b257efa9e50ce11bf03cb597d6.png) As you can see, the model has successfully returned a message. Isn't the whole configuration process very simple? --- # 凭证目录 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/auth-dir.html#VPContent) 回到顶部 凭证目录 [​](https://help.router-for.me/cn/configuration/auth-dir.html#%E5%87%AD%E8%AF%81%E7%9B%AE%E5%BD%95) ========================================================================================================= `auth-dir` 参数指定凭证目录的存储位置。 当您运行登录命令时，应用程序将在此目录中创建包含 Google 账户身份验证令牌的 JSON 文件。多个账户可用于轮询。 --- # 热更新 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/hot-reloading.html#VPContent) 回到顶部 热更新 [​](https://help.router-for.me/cn/configuration/hot-reloading.html#%E7%83%AD%E6%9B%B4%E6%96%B0) ==================================================================================================== 服务会监听配置文件与 `auth-dir` 目录的变化并自动重新加载客户端与配置。 您可以在运行中新增或移除 `Gemini CLI` / `Codex` / `Cluade Code` / `Qwen Code` / `iFlow` 的令牌 JSON 文件，无需重启服务。 --- # 配置选项 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/options.html#VPContent) 回到顶部 配置选项 [​](https://help.router-for.me/cn/configuration/options.html#%E9%85%8D%E7%BD%AE%E9%80%89%E9%A1%B9) ======================================================================================================== 以下默认值与 `config.example.yaml` 保持同步。 基础 [​](https://help.router-for.me/cn/configuration/options.html#%E5%9F%BA%E7%A1%80) ------------------------------------------------------------------------------------ | 参数 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `host` | string | `""` | 绑定地址；`""` 监听所有 IPv4/IPv6；用 `127.0.0.1` 仅限本机。 | | `port` | integer | `8317` | 服务器监听端口。 | | `tls.enable` | boolean | `false` | 是否启用 HTTPS。 | | `tls.cert` | string | `""` | TLS 证书路径。 | | `tls.key` | string | `""` | TLS 私钥路径。 | | `auth-dir` | string | `"~/.cli-proxy-api"` | 身份凭据目录，支持 `~`。 | | `api-keys` | string\[\] | `[]` | 内置 API 密钥列表。 | | `debug` | boolean | `false` | 调试日志。 | | `commercial-mode` | boolean | `false` | 关闭高开销中间件以降低内存。 | | `logging-to-file` | boolean | `false` | 写入滚动日志文件而非 stdout。 | | `logs-max-total-size-mb` | integer | `0` | 日志目录大小上限，0 表示不限制。 | | `usage-statistics-enabled` | boolean | `false` | 是否启用内存用量统计。 | | `proxy-url` | string | `""` | 全局代理，支持 socks5/http/https。 | | `force-model-prefix` | boolean | `false` | 无前缀的模型请求仅使用无前缀凭据。 | | `request-retry` | integer | `3` | 403/408/500/502/503/504 时的重试次数。 | | `max-retry-interval` | integer | `30` | 冷却凭据等待秒数上限，超出即触发重试。 | | `routing.strategy` | string | `"round-robin"` | 多匹配凭据的选择策略：`round-robin` 或 `fill-first`。 | | `ws-auth` | boolean | `false` | 是否为 `/v1/ws` 启用认证。 | | `nonstream-keepalive-interval` | integer | `0` | 非 SSE 流每隔 N 秒发送空行防止空闲超时；0 禁用。 | | `codex-instructions-enabled` | boolean | `false` | 是否为 Codex API 请求启用官方 Codex 指令注入。 | | `streaming.keepalive-seconds` | integer | `0` | SSE 保活间隔，≤0 禁用。 | | `streaming.bootstrap-retries` | integer | `0` | 首字节前的安全重试次数。 | 管理 API [​](https://help.router-for.me/cn/configuration/options.html#%E7%AE%A1%E7%90%86-api) -------------------------------------------------------------------------------------------- | 参数 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `remote-management.allow-remote` | boolean | `false` | 是否允许非 localhost 访问管理接口。 | | `remote-management.secret-key` | string | `""` | 管理密钥；明文将启动时哈希；为空则整体 404。 | | `remote-management.disable-control-panel` | boolean | `false` | true 时禁用内置管理面板资源与路由。 | | `remote-management.panel-github-repository` | string | `"https://github.com/router-for-me/Cli-Proxy-API-Management-Center"` | 管理面板资源仓库或 releases API 地址。 | 配额与路由 [​](https://help.router-for.me/cn/configuration/options.html#%E9%85%8D%E9%A2%9D%E4%B8%8E%E8%B7%AF%E7%94%B1) ------------------------------------------------------------------------------------------------------------------ | 参数 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `quota-exceeded.switch-project` | boolean | `true` | 配额超限时自动切换项目。 | | `quota-exceeded.switch-preview-model` | boolean | `true` | 配额超限时自动切换预览模型。 | 提供商凭据（均为数组，未配置时默认 `[]`） [​](https://help.router-for.me/cn/configuration/options.html#%E6%8F%90%E4%BE%9B%E5%95%86%E5%87%AD%E6%8D%AE-%E5%9D%87%E4%B8%BA%E6%95%B0%E7%BB%84-%E6%9C%AA%E9%85%8D%E7%BD%AE%E6%97%B6%E9%BB%98%E8%AE%A4) -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Gemini [​](https://help.router-for.me/cn/configuration/options.html#gemini) | 参数 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `gemini-api-key.*.api-key` | string | `""` | API Key。 | | `gemini-api-key.*.prefix` | string | `""` | 可选前缀，需以 `prefix/model` 访问。 | | `gemini-api-key.*.base-url` | string | `"https://generativelanguage.googleapis.com"` | 自定义端点。 | | `gemini-api-key.*.headers` | object | `{}` | 仅对该端点附加的自定义请求头。 | | `gemini-api-key.*.proxy-url` | string | `""` | 覆盖全局代理。 | | `gemini-api-key.*.models.*.name` | string | `""` | 上游模型名。 | | `gemini-api-key.*.models.*.alias` | string | `""` | 客户端别名。 | | `gemini-api-key.*.excluded-models` | string\[\] | `[]` | 排除匹配的模型（支持通配符）。 | ### Codex [​](https://help.router-for.me/cn/configuration/options.html#codex) | 参数 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `codex-api-key.*.api-key` | string | `""` | API Key。 | | `codex-api-key.*.prefix` | string | `""` | 可选前缀。 | | `codex-api-key.*.base-url` | string | `""` | 自定义 Codex 端点。 | | `codex-api-key.*.headers` | object | `{}` | 自定义请求头。 | | `codex-api-key.*.proxy-url` | string | `""` | 覆盖全局代理。 | | `codex-api-key.*.models.*.name` | string | `""` | 上游模型名。 | | `codex-api-key.*.models.*.alias` | string | `""` | 客户端别名。 | | `codex-api-key.*.excluded-models` | string\[\] | `[]` | 排除模型（支持通配符）。 | ### Claude [​](https://help.router-for.me/cn/configuration/options.html#claude) | 参数 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `claude-api-key.*.api-key` | string | `""` | API Key。 | | `claude-api-key.*.prefix` | string | `""` | 可选前缀。 | | `claude-api-key.*.base-url` | string | `""` | 自定义 Claude 端点。 | | `claude-api-key.*.headers` | object | `{}` | 自定义请求头。 | | `claude-api-key.*.proxy-url` | string | `""` | 覆盖全局代理。 | | `claude-api-key.*.models.*.name` | string | `""` | 上游模型名。 | | `claude-api-key.*.models.*.alias` | string | `""` | 客户端别名。 | | `claude-api-key.*.excluded-models` | string\[\] | `[]` | 排除模型（支持通配符）。 | | `claude-api-key.*.cloak.mode` | string | `"auto"` | 伪装模式：`auto`（仅非 Claude Code）、`always`、`never`。 | | `claude-api-key.*.cloak.strict-mode` | boolean | `false` | `true` 时删除用户系统消息，仅保留 Claude Code 提示。 | | `claude-api-key.*.cloak.sensitive-words` | string\[\] | `[]` | 需用零宽字符混淆的敏感词。 | ### OpenAI 兼容提供商 [​](https://help.router-for.me/cn/configuration/options.html#openai-%E5%85%BC%E5%AE%B9%E6%8F%90%E4%BE%9B%E5%95%86) | 参数 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `openai-compatibility.*.name` | string | `""` | 提供商名称（用于 UA 等）。 | | `openai-compatibility.*.prefix` | string | `""` | 可选前缀。 | | `openai-compatibility.*.base-url` | string | `""` | 提供商基础 URL。 | | `openai-compatibility.*.headers` | object | `{}` | 额外请求头。 | | `openai-compatibility.*.api-key-entries.*.api-key` | string | `""` | API Key。 | | `openai-compatibility.*.api-key-entries.*.proxy-url` | string | `""` | 针对该密钥的代理。 | | `openai-compatibility.*.models.*.name` | string | `""` | 上游模型名。 | | `openai-compatibility.*.models.*.alias` | string | `""` | 客户端别名。 | ### Vertex [​](https://help.router-for.me/cn/configuration/options.html#vertex) | 参数 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `vertex-api-key.*.api-key` | string | `""` | `x-goog-api-key` 值。 | | `vertex-api-key.*.prefix` | string | `""` | 可选前缀。 | | `vertex-api-key.*.base-url` | string | `""` | Vertex 兼容端点。 | | `vertex-api-key.*.proxy-url` | string | `""` | 针对该密钥的代理。 | | `vertex-api-key.*.headers` | object | `{}` | 额外请求头。 | | `vertex-api-key.*.models.*.name` | string | `""` | 上游模型名。 | | `vertex-api-key.*.models.*.alias` | string | `""` | 客户端别名。 | Amp 集成 (`ampcode`) [​](https://help.router-for.me/cn/configuration/options.html#amp-%E9%9B%86%E6%88%90-ampcode) ---------------------------------------------------------------------------------------------------------------- | 参数 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `ampcode.upstream-url` | string | `""` | Amp CLI OAuth/管理上游地址。 | | `ampcode.upstream-api-key` | string | `""` | 覆盖用的 Amp 上游 API Key。 | | `ampcode.upstream-api-keys[].upstream-api-key` | string | `""` | 为特定客户端映射的上游 Key。 | | `ampcode.upstream-api-keys[].api-keys` | string\[\] | `[]` | 需要映射到该上游 Key 的客户端密钥。 | | `ampcode.restrict-management-to-localhost` | boolean | `false` | 是否将 Amp 管理路由限制为 localhost。 | | `ampcode.force-model-mappings` | boolean | `false` | 是否在检查本地 API 密钥前强制执行模型映射。 | | `ampcode.model-mappings[].from` | string | `""` | Amp 请求的模型名。 | | `ampcode.model-mappings[].to` | string | `""` | 本地可用模型名。 | OAuth 模型别名 [​](https://help.router-for.me/cn/configuration/options.html#oauth-%E6%A8%A1%E5%9E%8B%E5%88%AB%E5%90%8D) -------------------------------------------------------------------------------------------------------------------- | 参数 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `oauth-model-alias` | object | `{}` | 按渠道为模型重命名（gemini-cli、vertex、aistudio、antigravity、claude、codex、qwen、iflow）。 | | `oauth-model-alias.*.*.fork` | boolean | `false` | 为 `true` 时保留原名并同时添加别名作为额外模型。 | | `oauth-excluded-models` | object | `{}` | 按渠道排除模型，支持通配符。 | Payload 规则 [​](https://help.router-for.me/cn/configuration/options.html#payload-%E8%A7%84%E5%88%99) ---------------------------------------------------------------------------------------------------- | 参数 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `payload.default[].models[].name` | string | `""` | 匹配的模型名（可通配）。 | | `payload.default[].models[].protocol` | string | `""` | 限定协议：`openai`/`gemini`/`claude`/`codex`/`antigravity`。 | | `payload.default[].params` | object | `{}` | 缺省时写入的 JSON 路径 → 值。 | | `payload.default-raw[].models[].name` | string | `""` | 匹配的模型名（可通配）。 | | `payload.default-raw[].models[].protocol` | string | `""` | 限定协议。 | | `payload.default-raw[].params` | object | `{}` | 缺省时写入的原始 JSON 路径 → 值（必须是有效 JSON）。 | | `payload.override[].models[].name` | string | `""` | 匹配的模型名（可通配）。 | | `payload.override[].models[].protocol` | string | `""` | 限定协议。 | | `payload.override[].params` | object | `{}` | 总是覆盖的 JSON 路径 → 值。 | | `payload.override-raw[].models[].name` | string | `""` | 匹配的模型名（可通配）。 | | `payload.override-raw[].models[].protocol` | string | `""` | 限定协议。 | | `payload.override-raw[].params` | object | `{}` | 总是覆盖的原始 JSON 路径 → 值（必须是有效 JSON）。 | | `payload.filter[].models[].name` | string | `""` | 匹配的模型名（可通配）。 | | `payload.filter[].models[].protocol` | string | `""` | 限定协议。 | | `payload.filter[].params` | string\[\] | `[]` | 要删除的 JSON 路径列表。 | --- # PostgreSQL 支持的配置与令牌存储 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/storage/pgsql.html#VPContent) 回到顶部 PostgreSQL 支持的配置与令牌存储 [​](https://help.router-for.me/cn/configuration/storage/pgsql.html#postgresql-%E6%94%AF%E6%8C%81%E7%9A%84%E9%85%8D%E7%BD%AE%E4%B8%8E%E4%BB%A4%E7%89%8C%E5%AD%98%E5%82%A8) ================================================================================================================================================================================================ 在托管环境中运行服务时，可以选择使用 PostgreSQL 来保存配置与令牌，借助托管数据库减轻本地文件管理压力。 **环境变量** | 变量 | 必需 | 默认值 | 描述 | | --- | --- | --- | --- | | `MANAGEMENT_PASSWORD` | 是 | | 管理面板密码（启用远程管理时必需）。 | | `PGSTORE_DSN` | 是 | | PostgreSQL 连接串，例如 `postgresql://user:pass@host:5432/db`。 | | `PGSTORE_SCHEMA` | 否 | public | 创建表时使用的 schema；留空则使用默认 schema。 | | `PGSTORE_LOCAL_PATH` | 否 | 当前工作目录 | 本地镜像根目录，服务将在 `<值>/pgstore` 下写入缓存；若无法获取工作目录则退回 `/tmp/pgstore`。 | **工作原理** 1. **初始化：** 启动时通过 `PGSTORE_DSN` 连接数据库，确保 schema 存在，并在缺失时创建 `config_store` 与 `auth_store`。 2. **本地镜像：** 在 `/pgstore` 下建立可写缓存，复用 `config/config.yaml` 与 `auths/` 目录。 3. **引导：** 若数据库中无配置记录，会使用 `config.example.yaml` 初始化，并以固定标识 `config` 写入。 4. **令牌同步：** 配置与令牌的更改会写入 PostgreSQL，同时数据库中的内容也会反向同步至本地镜像，便于文件监听与管理接口继续工作。 --- # Git 支持的配置与令牌存储 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/storage/git.html#VPContent) 回到顶部 Git 支持的配置与令牌存储 [​](https://help.router-for.me/cn/configuration/storage/git.html#git-%E6%94%AF%E6%8C%81%E7%9A%84%E9%85%8D%E7%BD%AE%E4%B8%8E%E4%BB%A4%E7%89%8C%E5%AD%98%E5%82%A8) ================================================================================================================================================================================ 应用程序可配置为使用 Git 仓库作为后端，用于存储 `config.yaml` 配置文件和来自 `auth-dir` 目录的身份验证令牌。这允许对您的配置进行集中管理和版本控制。 要启用此功能，请将 `GITSTORE_GIT_URL` 环境变量设置为您的 Git 仓库的 URL。 **环境变量** | 变量 | 必需 | 默认值 | 描述 | | --- | --- | --- | --- | | `MANAGEMENT_PASSWORD` | 是 | | 管理面板密码 | | `GITSTORE_GIT_URL` | 是 | | 要使用的 Git 仓库的 HTTPS URL。 | | `GITSTORE_LOCAL_PATH` | 否 | 当前工作目录 | 将克隆 Git 仓库的本地路径。在 Docker 内部，此路径默认为 `/CLIProxyAPI`。 | | `GITSTORE_GIT_USERNAME` | 否 | | 用于 Git 身份验证的用户名。 | | `GITSTORE_GIT_TOKEN` | 否 | | 用于 Git 身份验证的个人访问令牌（或密码）。 | **工作原理** 1. **克隆：** 启动时，应用程序会将远程 Git 仓库克隆到 `GITSTORE_LOCAL_PATH`。 2. **配置：** 然后，它会在克隆的仓库内的 `config` 目录中查找 `config.yaml` 文件。 3. **引导：** 如果仓库中不存在 `config/config.yaml`，应用程序会将本地的 `config.example.yaml` 复制到该位置，然后提交并推送到远程仓库作为初始配置。您必须确保 `config.example.yaml` 文件可用。 4. **令牌同步：** `auth-dir` 也在此仓库中管理。对身份验证令牌的任何更改（例如，通过新的登录）都会自动提交并推送到远程 Git 仓库。 --- # 基础配置 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/basic.html#VPContent) 回到顶部 基础配置 [​](https://help.router-for.me/cn/configuration/basic.html#%E5%9F%BA%E7%A1%80%E9%85%8D%E7%BD%AE) ====================================================================================================== 配置文件 [​](https://help.router-for.me/cn/configuration/basic.html#%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6) ------------------------------------------------------------------------------------------------------ 服务器默认使用项目根目录的 YAML 配置文件（`config.yaml`）。可通过 `--config` 指定其他路径： bash ./cli-proxy-api --config /path/to/your/config.yaml ### 配置文件示例 [​](https://help.router-for.me/cn/configuration/basic.html#%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E7%A4%BA%E4%BE%8B) yaml # 服务器绑定主机/接口，默认空字符串同时绑定 IPv4/IPv6。 # 使用 "127.0.0.1" 或 "localhost" 可限制仅本机访问。 host: "" # 服务器端口 port: 8317 # TLS 设置：启用后使用提供的证书与私钥监听 HTTPS。 tls: enable: false cert: "" key: "" # 管理 API 设置 remote-management: # 是否允许远程（非 localhost）访问管理接口。 # 为 false 时仅允许 localhost，仍需管理密钥。 allow-remote: false # 管理密钥。若填写明文，启动时会自动哈希后生效。 # 所有管理请求（包括本地）都需要该密钥。 # 留空则完全禁用管理 API（所有 /v0/management 路由返回 404）。 secret-key: "" # 为 true 时禁用内置管理面板资源下载与路由。 disable-control-panel: false # 管理面板的 GitHub 仓库，可填写仓库 URL 或 releases API URL。 panel-github-repository: "https://github.com/router-for-me/Cli-Proxy-API-Management-Center" # 认证目录（支持 ~ 展开为主目录） auth-dir: "~/.cli-proxy-api" # 用于请求认证的 API 密钥 api-keys: - "your-api-key-1" - "your-api-key-2" - "your-api-key-3" # 是否启用调试日志 debug: false # 为 true 时禁用高开销 HTTP 中间件以降低高并发下的内存占用 commercial-mode: false # 为 true 时将应用日志写入滚动文件而非 stdout logging-to-file: false # 日志目录的最大总大小（MB）；超过后会删除最旧的日志。0 表示不限制。 logs-max-total-size-mb: 0 # 为 false 时禁用内存用量统计聚合 usage-statistics-enabled: false # 代理地址。支持 socks5/http/https，例如 socks5://user:pass@192.168.1.1:1080/ proxy-url: "" # 为 true 时，无前缀模型请求只会匹配无前缀凭据（除非前缀与模型名相同）。 force-model-prefix: false # 请求重试次数；当响应码为 403/408/500/502/503/504 时重试。 request-retry: 3 # 冷却中的凭据等待的最长时间（秒），超过则触发重试。 max-retry-interval: 30 # 配额超限时的处理 quota-exceeded: switch-project: true # 配额超限时是否自动切换其他项目 switch-preview-model: true # 配额超限时是否自动切换预览模型 # 多凭据匹配时的路由策略 routing: strategy: "round-robin" # 轮询（默认）或 fill-first # 是否为 WebSocket API (/v1/ws) 启用认证 ws-auth: false # 当 > 0 时，为非流式响应每隔 N 秒发送空行以防止空闲超时 nonstream-keepalive-interval: 0 # 当为 true 时，为 Codex API 请求启用官方 Codex 指令注入 # 当为 false（默认）时，CodexInstructionsForModel 立即返回而不修改 codex-instructions-enabled: false # 流式传输行为（SSE keep-alive 与安全启动重试） streaming: keepalive-seconds: 15 # 默认：0（禁用）；≤0 关闭 keep-alive。 bootstrap-retries: 1 # 默认：0（禁用）；首字节前的重试次数。 # Gemini API 密钥 gemini-api-key: - api-key: "AIzaSy...01" prefix: "test" # 可选：需要以 "test/gemini-3-pro-preview" 访问 base-url: "https://generativelanguage.googleapis.com" headers: X-Custom-Header: "custom-value" proxy-url: "socks5://proxy.example.com:1080" models: - name: "gemini-2.5-flash" # 上游模型名 alias: "gemini-flash" # 客户端别名 excluded-models: - "gemini-2.5-pro" # 精确排除 - "gemini-2.5-*" # 前缀通配 - "*-preview" # 后缀通配 - "*flash*" # 子串通配 - api-key: "AIzaSy...02" # Codex API 密钥 codex-api-key: - api-key: "sk-atSM..." prefix: "test" # 可选：需以 "test/gpt-5-codex" 访问 base-url: "https://www.example.com" # 自定义 Codex 端点 headers: X-Custom-Header: "custom-value" proxy-url: "socks5://proxy.example.com:1080" # 可选：单独代理 models: - name: "gpt-5-codex" # 上游模型名 alias: "codex-latest" # 客户端别名 excluded-models: - "gpt-5.1" # 精确排除 - "gpt-5-*" # 前缀通配 - "*-mini" # 后缀通配 - "*codex*" # 子串通配 # Claude API 密钥 claude-api-key: - api-key: "sk-atSM..." # 使用官方 Claude API 时无需 base-url - api-key: "sk-atSM..." prefix: "test" # 可选：需以 "test/claude-sonnet-latest" 访问 base-url: "https://www.example.com" # 自定义 Claude 端点 headers: X-Custom-Header: "custom-value" proxy-url: "socks5://proxy.example.com:1080" # 可选：单独代理 models: - name: "claude-3-5-sonnet-20241022" # 上游模型名 alias: "claude-sonnet-latest" # 客户端别名 excluded-models: - "claude-opus-4-5-20251101" # 精确排除 - "claude-3-*" # 前缀通配 - "*-thinking" # 后缀通配 - "*haiku*" # 子串通配 cloak: # 可选：为非 Claude Code 客户端进行请求伪装 mode: "auto" # "auto"（默认）：仅当客户端不是 Claude Code 时伪装 # "always"：始终应用伪装 # "never"：从不应用伪装 strict-mode: false # false（默认）：将 Claude Code 提示前置到用户系统消息 # true：删除所有用户系统消息，仅保留 Claude Code 提示 sensitive-words: # 可选：用零宽字符混淆的词汇 - "API" - "proxy" # OpenAI 兼容提供商 openai-compatibility: - name: "openrouter" # 提供商名称，用于 UA 等 prefix: "test" # 可选：需以 "test/kimi-k2" 访问 base-url: "https://openrouter.ai/api/v1" # 提供商基础 URL headers: X-Custom-Header: "custom-value" api-key-entries: - api-key: "sk-or-v1-...b780" proxy-url: "socks5://proxy.example.com:1080" # 可选：单独代理 - api-key: "sk-or-v1-...b781" # 无代理 models: # 提供商支持的模型 - name: "moonshotai/kimi-k2:free" # 上游模型名 alias: "kimi-k2" # 客户端别名 # Vertex API 密钥（Vertex 兼容端点，使用 API key + base URL） vertex-api-key: - api-key: "vk-123..." # x-goog-api-key 头 prefix: "test" # 可选前缀 base-url: "https://example.com/api" # 例如 https://zenmux.ai/api proxy-url: "socks5://proxy.example.com:1080" # 可选单独代理 headers: X-Custom-Header: "custom-value" models: # 可选：别名到上游模型 - name: "gemini-2.5-flash" # 上游模型名 alias: "vertex-flash" # 客户端别名 - name: "gemini-2.5-pro" alias: "vertex-pro" # Amp 集成 ampcode: # Amp CLI OAuth 与管理功能的上游地址 upstream-url: "https://ampcode.com" # 可选：覆盖 Amp 上游 API Key（否则使用环境变量或文件） upstream-api-key: "" # 按客户端的上游 API Key 映射 # 将顶层 api-keys 中的客户端密钥映射到不同的 Amp 上游密钥。 # 若未匹配到则回退到 upstream-api-key。 upstream-api-keys: - upstream-api-key: "amp_key_for_team_a" # 供这些客户端使用的上游密钥 api-keys: # 使用该上游密钥的客户端密钥 - "your-api-key-1" - "your-api-key-2" - upstream-api-key: "amp_key_for_team_b" api-keys: - "your-api-key-3" # 是否将 Amp 管理路由 (/api/auth, /api/user 等) 仅限 localhost（默认 false） restrict-management-to-localhost: false # 是否在检查本地 API 密钥前强制执行模型映射（默认 false） force-model-mappings: false # Amp 模型映射：当请求的模型不可用时路由到本地可用模型 # 适用于 Amp CLI 请求不可用模型（如 Claude Opus 4.5）但本地有相似模型的情况 model-mappings: - from: "claude-opus-4-5-20251101" # Amp 请求的模型 to: "gemini-claude-opus-4-5-thinking" # 路由到的可用模型 - from: "claude-sonnet-4-5-20250929" to: "gemini-claude-sonnet-4-5-thinking" - from: "claude-haiku-4-5-20251001" to: "gemini-2.5-flash" # 全局 OAuth 模型名称别名（按渠道） # 这些别名同时用于模型列表和请求路由的模型 ID 重命名。 # 支持的渠道：gemini-cli、vertex、aistudio、antigravity、claude、codex、qwen、iflow。 # 注意：别名不适用于 gemini-api-key、codex-api-key、claude-api-key、openai-compatibility、vertex-api-key 或 ampcode。 # 您可以使用不同的别名重复相同的名称，以暴露多个客户端模型名称。 oauth-model-alias: antigravity: - name: "rev19-uic3-1p" alias: "gemini-2.5-computer-use-preview-10-2025" - name: "gemini-3-pro-image" alias: "gemini-3-pro-image-preview" - name: "gemini-3-pro-high" alias: "gemini-3-pro-preview" - name: "gemini-3-flash" alias: "gemini-3-flash-preview" - name: "claude-sonnet-4-5" alias: "gemini-claude-sonnet-4-5" - name: "claude-sonnet-4-5-thinking" alias: "gemini-claude-sonnet-4-5-thinking" - name: "claude-opus-4-5-thinking" alias: "gemini-claude-opus-4-5-thinking" # gemini-cli: # - name: "gemini-2.5-pro" # 该渠道下的原始模型名 # alias: "g2.5p" # 客户端可见别名 # fork: true # 为 true 时保留原名并同时增加别名作为额外模型（默认：false） # vertex: # - name: "gemini-2.5-pro" # alias: "g2.5p" # aistudio: # - name: "gemini-2.5-pro" # alias: "g2.5p" # claude: # - name: "claude-sonnet-4-5-20250929" # alias: "cs4.5" # codex: # - name: "gpt-5" # alias: "g5" # qwen: # - name: "qwen3-coder-plus" # alias: "qwen-plus" # iflow: # - name: "glm-4.7" # alias: "glm-god" # OAuth 提供商的模型排除列表 oauth-excluded-models: gemini-cli: - "gemini-2.5-pro" # 精确排除 - "gemini-2.5-*" # 前缀通配 - "*-preview" # 后缀通配 - "*flash*" # 子串通配 vertex: - "gemini-3-pro-preview" aistudio: - "gemini-3-pro-preview" antigravity: - "gemini-3-pro-preview" claude: - "claude-3-5-haiku-20241022" codex: - "gpt-5-codex-mini" qwen: - "vision-model" iflow: - "tstars2.0" # 可选的 payload 配置 payload: default: # 默认规则仅在 payload 中缺少参数时设置 - models: - name: "gemini-2.5-pro" # 支持通配符（如 "gemini-*"） protocol: "gemini" # 将规则限制为特定协议，选项：openai、gemini、claude、codex、antigravity params: # JSON 路径（gjson/sjson 语法）-> 值 "generationConfig.thinkingConfig.thinkingBudget": 32768 default-raw: # 默认原始规则在缺少时使用原始 JSON 设置参数（必须是有效的 JSON） - models: - name: "gemini-2.5-pro" # 支持通配符（如 "gemini-*"） protocol: "gemini" # 将规则限制为特定协议，选项：openai、gemini、claude、codex、antigravity params: # JSON 路径（gjson/sjson 语法）-> 原始 JSON 值（字符串按原样使用，必须是有效的 JSON） "generationConfig.responseJsonSchema": "{\"type\":\"object\",\"properties\":{\"answer\":{\"type\":\"string\"}}}" override: # 覆盖规则总是设置参数，覆盖任何现有值 - models: - name: "gpt-*" # 支持通配符（如 "gpt-*"） protocol: "codex" # 将规则限制为特定协议，选项：openai、gemini、claude、codex、antigravity params: # JSON 路径（gjson/sjson 语法）-> 值 "reasoning.effort": "high" override-raw: # 覆盖原始规则总是使用原始 JSON 设置参数（必须是有效的 JSON） - models: - name: "gpt-*" # 支持通配符（如 "gpt-*"） protocol: "codex" # 将规则限制为特定协议，选项：openai、gemini、claude、codex、antigravity params: # JSON 路径（gjson/sjson 语法）-> 原始 JSON 值（字符串按原样使用，必须是有效的 JSON） "response_format": "{\"type\":\"json_schema\",\"json_schema\":{\"name\":\"answer\",\"schema\":{\"type\":\"object\"}}}" filter: # 过滤规则从 payload 中删除指定的参数 - models: - name: "gemini-2.5-pro" # 支持通配符（如 "gemini-*"） protocol: "gemini" # 将规则限制为特定协议，选项：openai、gemini、claude、codex、antigravity params: # 要从 payload 中删除的 JSON 路径（gjson/sjson 语法） - "generationConfig.thinkingConfig.thinkingBudget" - "generationConfig.responseJsonSchema" --- # Gemini CLI (Gemini OAuth 登录): | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/provider/gemini-cli.html#VPContent) 回到顶部 Gemini CLI (Gemini OAuth 登录): [​](https://help.router-for.me/cn/configuration/provider/gemini-cli.html#gemini-cli-gemini-oauth-%E7%99%BB%E5%BD%95) =================================================================================================================================================== bash ./cli-proxy-api --login 如果您是现有的 `Gemini Code` 用户，可能需要指定一个项目ID： bash ./cli-proxy-api --login --project_id 本地 OAuth 回调端口为 `8085`。 选项：加上 `--no-browser` 可打印登录地址而不自动打开浏览器。本地 OAuth 回调端口为 `8085`。 --- # Claude Code (Anthropic OAuth 登录): | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/provider/claude-code.html#VPContent) 回到顶部 Claude Code (Anthropic OAuth 登录): [​](https://help.router-for.me/cn/configuration/provider/claude-code.html#claude-code-anthropic-oauth-%E7%99%BB%E5%BD%95) ============================================================================================================================================================ bash ./cli-proxy-api --claude-login 选项：加上 `--no-browser` 可打印登录地址而不自动打开浏览器。本地 OAuth 回调端口为 `54545`。 --- # 对象存储驱动的配置与令牌存储 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/storage/s3.html#VPContent) 回到顶部 对象存储驱动的配置与令牌存储 [​](https://help.router-for.me/cn/configuration/storage/s3.html#%E5%AF%B9%E8%B1%A1%E5%AD%98%E5%82%A8%E9%A9%B1%E5%8A%A8%E7%9A%84%E9%85%8D%E7%BD%AE%E4%B8%8E%E4%BB%A4%E7%89%8C%E5%AD%98%E5%82%A8) =============================================================================================================================================================================================================== 可以选择使用 S3 兼容的对象存储来托管配置与鉴权数据。 **环境变量** | 变量 | 是否必填 | 默认值 | 说明 | | --- | --- | --- | --- | | `MANAGEMENT_PASSWORD` | 是 | | 管理面板密码（启用远程管理时必需）。 | | `OBJECTSTORE_ENDPOINT` | 是 | | 对象存储访问端点。可带 `http://` 或 `https://` 前缀指定协议（省略则默认 HTTPS）。 | | `OBJECTSTORE_BUCKET` | 是 | | 用于存放 `config/config.yaml` 与 `auths/*.json` 的 Bucket 名称。 | | `OBJECTSTORE_ACCESS_KEY` | 是 | | 对象存储账号的访问密钥 ID。 | | `OBJECTSTORE_SECRET_KEY` | 是 | | 对象存储账号的访问密钥 Secret。 | | `OBJECTSTORE_LOCAL_PATH` | 否 | 当前工作目录 (CWD) | 本地镜像根目录；服务会写入到 `<值>/objectstore`。 | **工作流程** 1. **启动阶段：** 解析端点地址（识别协议前缀），创建 MinIO 兼容客户端并使用 Path-Style 模式，如 Bucket 不存在会自动创建。 2. **本地镜像：** 在 `/objectstore` 维护可写缓存，同步 `config/config.yaml` 与 `auths/`。 3. **初始化：** 若 Bucket 中缺少配置文件，将以 `config.example.yaml` 为模板生成 `config/config.yaml` 并上传。 4. **双向同步：** 本地变更会上传到对象存储，同时远端对象也会拉回到本地，保证文件监听、管理 API 与 CLI 命令行为一致。 --- # Codex (OpenAI OAuth 登录): | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/provider/codex.html#VPContent) 回到顶部 Codex (OpenAI OAuth 登录): [​](https://help.router-for.me/cn/configuration/provider/codex.html#codex-openai-oauth-%E7%99%BB%E5%BD%95) ==================================================================================================================================== bash ./cli-proxy-api --codex-login 选项：加上 `--no-browser` 可打印登录地址而不自动打开浏览器。本地 OAuth 回调端口为 `1455`。 --- # 反重力 (反重力 OAuth 登录): | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/provider/antigravity.html#VPContent) 回到顶部 反重力 (反重力 OAuth 登录): [​](https://help.router-for.me/cn/configuration/provider/antigravity.html#%E5%8F%8D%E9%87%8D%E5%8A%9B-%E5%8F%8D%E9%87%8D%E5%8A%9B-oauth-%E7%99%BB%E5%BD%95) ================================================================================================================================================================================ bash ./cli-proxy-api --antigravity-login 本地 OAuth 回调端口为 `51121`。 选项：加上 `--no-browser` 可打印登录地址而不自动打开浏览器。本地 OAuth 回调端口为 `51121`。 --- # Qwen (Qwen Chat OAuth 登录): | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/provider/qwen-code.html#VPContent) 回到顶部 Qwen (Qwen Chat OAuth 登录): [​](https://help.router-for.me/cn/configuration/provider/qwen-code.html#qwen-qwen-chat-oauth-%E7%99%BB%E5%BD%95) ============================================================================================================================================ bash ./cli-proxy-api --qwen-login 选项：加上 `--no-browser` 可打印登录地址而不自动打开浏览器。使用 Qwen Chat 的 OAuth 设备登录流程。 --- # OpenAI 兼容供应商 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/provider/openai-compatibility.html#VPContent) 回到顶部 OpenAI 兼容供应商 [​](https://help.router-for.me/cn/configuration/provider/openai-compatibility.html#openai-%E5%85%BC%E5%AE%B9%E4%BE%9B%E5%BA%94%E5%95%86) ====================================================================================================================================================== ### OpenAI 兼容上游提供商 [​](https://help.router-for.me/cn/configuration/provider/openai-compatibility.html#openai-%E5%85%BC%E5%AE%B9%E4%B8%8A%E6%B8%B8%E6%8F%90%E4%BE%9B%E5%95%86) 通过 `openai-compatibility` 配置上游 OpenAI 兼容提供商（例如 OpenRouter）。 * name：内部识别名 * base-url：提供商基础地址 * api-key-entries：API密钥条目列表，支持可选的每密钥代理配置（推荐且为持久化格式） * models：将上游模型 `name` 映射为本地可用 `alias` > 兼容说明：旧字段 `api-keys` 会在加载时自动迁移为 `api-key-entries`，保存配置时会被移除；请直接使用 `api-key-entries`。 支持每密钥代理配置的示例： yaml openai-compatibility: - name: "openrouter" base-url: "https://openrouter.ai/api/v1" api-key-entries: - api-key: "sk-or-v1-...b780" proxy-url: "socks5://proxy.example.com:1080" - api-key: "sk-or-v1-...b781" models: - name: "moonshotai/kimi-k2:free" alias: "kimi-k2" 使用方式：在 `/v1/chat/completions` 中将 `model` 设为别名（如 `kimi-k2`），代理将自动路由到对应提供商与模型。 --- # AI Studio 使用说明 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/provider/ai-studio.html#VPContent) 回到顶部 AI Studio 使用说明 [​](https://help.router-for.me/cn/configuration/provider/ai-studio.html#ai-studio-%E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E) ======================================================================================================================================= 您可以将本服务 (CLIProxyAPI) 作为后端，配合 [这个 AI Studio 应用](https://aistudio.google.com/apps/drive/1CPW7FpWGsDZzkaYgYOyXQ_6FWgxieLmL) 使用。请遵循以下步骤进行配置： 1. **启动 CLIProxyAPI 服务**：确保您的 CLIProxyAPI 实例正在本地或远程运行。 2. **访问 AI Studio 应用**：在浏览器中登录您的 Google 账户，然后打开以下链接： * [https://aistudio.google.com/apps/drive/1CPW7FpWGsDZzkaYgYOyXQ\_6FWgxieLmL](https://aistudio.google.com/apps/drive/1CPW7FpWGsDZzkaYgYOyXQ_6FWgxieLmL) 连接配置 [​](https://help.router-for.me/cn/configuration/provider/ai-studio.html#%E8%BF%9E%E6%8E%A5%E9%85%8D%E7%BD%AE) ------------------------------------------------------------------------------------------------------------------- 默认情况下，AI Studio 应用会尝试连接到本地的 CLIProxyAPI (`ws://127.0.0.1:8317`)。 * **连接到远程服务**： 如果您需要连接到远程部署的 CLIProxyAPI，请修改 AI Studio 应用中的 `config.ts` 文件，更新 `WEBSOCKET_PROXY_URL` 的值。 * 如果您的远程服务启用了 SSL，请使用 `wss://` 协议。 * 如果未启用 SSL，请使用 `ws://` 协议。 认证配置 [​](https://help.router-for.me/cn/configuration/provider/ai-studio.html#%E8%AE%A4%E8%AF%81%E9%85%8D%E7%BD%AE) ------------------------------------------------------------------------------------------------------------------- 默认情况下，CLIProxyAPI 的 WebSocket 连接不要求认证。 * **在 CLIProxyAPI 服务端启用认证**： 在您的 `config.yaml` 文件中，将 `ws_auth` 设置为 `true`。 * **在 AI Studio 客户端配置认证**： 在 AI Studio 应用的 `config.ts` 文件中，设置 `JWT_TOKEN` 的值为您的认证令牌。 --- # iFlow (iFlow OAuth 登录): | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/provider/iflow.html#VPContent) 回到顶部 iFlow (iFlow OAuth 登录): [​](https://help.router-for.me/cn/configuration/provider/iflow.html#iflow-iflow-oauth-%E7%99%BB%E5%BD%95) ================================================================================================================================== bash ./cli-proxy-api --iflow-login 选项：加上 `--no-browser` 可打印登录地址而不自动打开浏览器。本地 OAuth 回调端口为 `11451`。 --- # Claude Code 兼容供应商 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/provider/claude-code-compatibility.html#VPContent) 回到顶部 Claude Code 兼容供应商 [​](https://help.router-for.me/cn/configuration/provider/claude-code-compatibility.html#claude-code-%E5%85%BC%E5%AE%B9%E4%BE%9B%E5%BA%94%E5%95%86) ===================================================================================================================================================================== 通过 `claude-api-key` 配置上游 Claude Code 兼容供应商。 * api-key: 上游供应商的API key * base-url: 上游供应商的端点覆盖地址 * proxy-url: 代理服务器地址（可选） * models: 从上游供应商模型 `名称` 映射到本地 `别名` 的列表 Example: yaml claude-api-key: - api-key: "sk-atSM..." # 如果是使用官方 Claude API,无需设置 base-url - api-key: "sk-atSM..." base-url: "https://www.example.com" # 使用第三方 Claude API 中转服务端点 proxy-url: "socks5://proxy.example.com:1080" # 可选：针对该密钥的代理设置 models: - name: "claude-3-5-sonnet-20241022" # 上游模型名称 alias: "claude-sonnet-latest" # 上游模型的本地别名 NOTE 如果您只设置了 `api-key`，则 `base-url` 将自动设置为 `https://api.anthropic.com`。 `base-url` 仅仅在您使用第三方 Claude Code 兼容供应商时才需要设置。 --- # Web UI | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/management/webui.html#VPContent) 回到顶部 Web UI [​](https://help.router-for.me/cn/management/webui.html#web-ui) ======================================================================= 项目地址：[Cli-Proxy-API-Management-Center](https://github.com/router-for-me/Cli-Proxy-API-Management-Center) 一个官方的基于Web的CLIProxyAPI管理界面。 基础路径：`http://localhost:8317/management.html` 设置 `remote-management.disable-control-panel` 为 `true` 时，服务器将跳过下载 `management.html`，且 `/management.html` 会返回 404，从而禁用内置管理界面。 你可以通过设置环境变量 `MANAGEMENT_STATIC_PATH` 来指定 `management.html` 的存储目录。 使用自定义 Web UI [​](https://help.router-for.me/cn/management/webui.html#%E4%BD%BF%E7%94%A8%E8%87%AA%E5%AE%9A%E4%B9%89-web-ui) --------------------------------------------------------------------------------------------------------------------------- 现在支持从自定义 GitHub 仓库获取管理面板。配置示例： yaml remote-management: panel-github-repository: "https://github.com/your-org/your-management-ui" * 仓库地址写法：`https://github.com//`，程序会自动转换成 `https://api.github.com/repos///releases/latest` 调用。 * 也可以直接写 API 地址：`https://api.github.com/repos///releases/latest`。 * 后台会定期检查最新 Release，查找名为 `management.html` 的资产并下载到静态目录（默认是配置文件同级的 `static/`，或 `MANAGEMENT_STATIC_PATH` 指定的目录）。如资产包含 `digest` 字段（推荐使用 `sha256:`），会用于哈希校验。 在 GitHub 发布自定义 Web UI 的规范 [​](https://help.router-for.me/cn/management/webui.html#%E5%9C%A8-github-%E5%8F%91%E5%B8%83%E8%87%AA%E5%AE%9A%E4%B9%89-web-ui-%E7%9A%84%E8%A7%84%E8%8C%83) ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. 构建自定义管理面板，生成单个 `management.html`（建议将静态资源打包进同一个文件）。 2. 创建 GitHub 仓库并推送代码。 3. 创建 Release（使用 `latest` 会被自动检测），上传资产文件： * 必须包含文件名 **`management.html`**。 * 推荐在资产元数据中填写 `digest` 字段，格式 `sha256:<文件哈希>`，方便校验完整性。 4. 在 CLIProxyAPI 配置中设置 `remote-management.panel-github-repository` 为该仓库地址或对应的 API 地址。 5. 重启或热加载配置后，服务器会自动拉取最新的管理面板。 --- # Gemini 兼容供应商 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/provider/gemini-compatibility#VPContent) 回到顶部 Gemini 兼容供应商 [​](https://help.router-for.me/cn/configuration/provider/gemini-compatibility#gemini-%E5%85%BC%E5%AE%B9%E4%BE%9B%E5%BA%94%E5%95%86) ================================================================================================================================================= 通过 `gemini-api-key` 配置上游 Gemini 兼容供应商。 * api-key: 上游供应商的API key * base-url: 上游供应商的端点覆盖地址 * proxy-url: 代理服务器地址（可选） * headers: 可选的额外 HTTP 头部，仅在访问覆盖后的 Gemini 端点时发送。 Example: yaml 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" # 如果是使用官方 Gemini API,无需设置 base-url NOTE 如果您只设置了 `api-key`，则 `base-url` 将自动设置为 `https://generativelanguage.googleapis.com`。 `base-url` 仅仅在您使用第三方 Gemini 兼容供应商时才需要设置。 --- # 通过模型名括号设置思考量 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/thinking#VPContent) 回到顶部 通过模型名括号设置思考量 [​](https://help.router-for.me/cn/configuration/thinking#%E9%80%9A%E8%BF%87%E6%A8%A1%E5%9E%8B%E5%90%8D%E6%8B%AC%E5%8F%B7%E8%AE%BE%E7%BD%AE%E6%80%9D%E8%80%83%E9%87%8F) ==================================================================================================================================================================================== 在模型名称末尾追加 `(值)` 来控制思考预算或推理等级。代理会在路由前移除括号，并将解析结果写入请求。 可用取值 [​](https://help.router-for.me/cn/configuration/thinking#%E5%8F%AF%E7%94%A8%E5%8F%96%E5%80%BC) ---------------------------------------------------------------------------------------------------- * `(数字)`：显式思考预算（提供商原生 token），按模型支持区间夹紧。 * `(等级)`：预设推理等级（不区分大小写）： | 等级 | 约等于预算 | 说明 | | --- | --- | --- | | `minimal` | 512 | 低成本推理 | | `low` | 1024 | 快速推理 | | `medium` | 8192 | 默认推理深度 | | `high` | 24576 | 深度推理 | | `xhigh` | 32768 | 更深推理 | | `auto` | 动态（允许则为 -1，否则取中点/下限） | 由上游自动分配 | | `none` | 0（若不允许 0 则夹紧到最小值） | 关闭思考 | * 空括号 `()` 会被忽略。`provider://model` 形式请在模型名后加括号，例如 `openrouter://gemini-3-pro-preview(high)`。 应用规则 [​](https://help.router-for.me/cn/configuration/thinking#%E5%BA%94%E7%94%A8%E8%A7%84%E5%88%99) ---------------------------------------------------------------------------------------------------- * 仅对声明支持思考的模型生效；不支持的模型只会移除括号，不注入思考字段。 * Gemini（标准与 CLI）：按夹紧后的值写入 `generationConfig.thinkingConfig.thinkingBudget`（或 `request.generationConfig.thinkingConfig...`），不会改动 `include_thoughts`。自带默认思考的模型（如 `gemini-3-pro-preview`）在缺省情况下仍会自动启用思考，括号中的预算会覆盖默认值。 * Claude API：提供预算/等级时会设置 `thinking.type=enabled` 并填入归一化后的 `thinking.budget_tokens`，必要时提升 `max_tokens`。 * OpenAI/Codex/Qwen/iFlow/OpenRouter：等级/`auto`/`none` 会覆盖 `reasoning_effort`（chat）或 `reasoning.effort`（Responses）；纯数字预算不会为这些协议改写 reasoning\_effort。 * 使用离散等级的模型会校验等级，不支持的取值会返回 400。 使用示例 [​](https://help.router-for.me/cn/configuration/thinking#%E4%BD%BF%E7%94%A8%E7%A4%BA%E4%BE%8B) ---------------------------------------------------------------------------------------------------- * 动态思考预算（Gemini）： bash curl -X POST http://localhost:8317/v1/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3-pro-preview(auto)", "messages": [{ "role": "user", "content": "帮我总结要点" }] }' # 归一为 gemini-3-pro-preview，写入 thinkingBudget=-1（若不支持动态则按模型区间夹紧），不修改 include_thoughts。 * OpenAI Responses 高等级推理： bash curl -X POST http://localhost:8317/v1/responses \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.1(high)", "input": "列出三个改进点" }' # 路由为 gpt-5.1，并覆盖 reasoning.effort="high"。 * 关闭思考（若不允许 0 则会夹紧到最小值）： bash model=claude-sonnet-4.5(none) # 若模型允许则写入 thinking.budget_tokens=0，否则夹紧到模型最小值。 --- # Codex 兼容供应商 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/configuration/provider/codex-compatibility#VPContent) 回到顶部 Codex 兼容供应商 [​](https://help.router-for.me/cn/configuration/provider/codex-compatibility#codex-%E5%85%BC%E5%AE%B9%E4%BE%9B%E5%BA%94%E5%95%86) ============================================================================================================================================== 通过 `codex-api-key` 配置上游 Codex 兼容供应商。 * api-key: 上游供应商的API key * base-url: 上游供应商的端点覆盖地址 * proxy-url: 代理服务器地址（可选） Example: yaml codex-api-key: - api-key: "sk-atSM..." base-url: "https://www.example.com" # 使用第三方 Codex API 中转服务端点 proxy-url: "socks5://proxy.example.com:1080" # 可选：针对该密钥的代理设置 --- # 桌面客户端 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/management/gui#VPContent) 回到顶部 桌面客户端 [​](https://help.router-for.me/cn/management/gui#%E6%A1%8C%E9%9D%A2%E5%AE%A2%E6%88%B7%E7%AB%AF) ====================================================================================================== 项目地址： [EasyCLI](https://github.com/router-for-me/EasyCLI) 一个跨平台的 CLIProxyAPI 桌面客户端。 --- # Gemini CLI | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/agent-client/gemini-cli#VPContent) 回到顶部 Gemini CLI [​](https://help.router-for.me/cn/agent-client/gemini-cli#gemini-cli) ================================================================================= 启动 CLIProxyAPI 服务器，根据您的认证方式选择以下配置之一。 Login with Google (OAuth) [​](https://help.router-for.me/cn/agent-client/gemini-cli#login-with-google-oauth) ------------------------------------------------------------------------------------------------------------- 将 `CODE_ASSIST_ENDPOINT` 环境变量设置为 CLIProxyAPI 服务器的 URL。 bash export CODE_ASSIST_ENDPOINT="http://127.0.0.1:8317" 服务器将中继 `loadCodeAssist`、`onboardUser` 和 `countTokens` 请求。并自动在多个账户之间轮询文本生成请求。 NOTE 此功能仅允许本地访问，因为找不到一个可以验证请求的方法。 所以只能强制只有 `127.0.0.1` 可以访问。 Use Gemini API Key [​](https://help.router-for.me/cn/agent-client/gemini-cli#use-gemini-api-key) ------------------------------------------------------------------------------------------------- 配置 Gemini API Base URL 和 API Key： bash export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:8317" export GEMINI_API_KEY="sk-dummy" NOTE 与 OAuth 模式不同，此模式下允许 CLIProxyAPI 配置为任何 IP 地址或域名。 --- # Codex | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/agent-client/codex#VPContent) 回到顶部 Codex [​](https://help.router-for.me/cn/agent-client/codex#codex) ================================================================== 启动 CLIProxyAPI 服务器, 修改 `~/.codex/config.toml` 和 `~/.codex/auth.json` 文件。 config.toml: toml # 无需确认是否执行操作，危险指令，初次接触codex不建议开启，移除#号即可开启 # approval_policy = "never" # 沙箱模式超高权限，危险指令，初次接触codex不建议开启，移除#号即可开启 # sandbox_mode = "danger-full-access" model_provider = "cliproxyapi" model = "gpt-5-codex" # 或者是gpt-5，你也可以使用任何我们支持的模型 model_reasoning_effort = "high" [model_providers.cliproxyapi] name = "cliproxyapi" base_url = "http://127.0.0.1:8317/v1" wire_api = "responses" auth.json: json { "OPENAI_API_KEY": "sk-dummy" } --- # Claude Code | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/agent-client/claude-code#VPContent) 回到顶部 Claude Code [​](https://help.router-for.me/cn/agent-client/claude-code#claude-code) ==================================================================================== 启动 CLIProxyAPI 服务器, 设置如下系统环境变量： * `ANTHROPIC_BASE_URL` * `ANTHROPIC_AUTH_TOKEN` * `ANTHROPIC_DEFAULT_OPUS_MODEL` * `ANTHROPIC_DEFAULT_SONNET_MODEL` * `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或对应 1.x.x 版本设置如下系统环境变量： * `ANTHROPIC_MODEL` * `ANTHROPIC_SMALL_FAST_MODEL` 使用 Gemini 模型： bash export ANTHROPIC_BASE_URL=http://127.0.0.1:8317 export ANTHROPIC_AUTH_TOKEN=sk-dummy # 2.x.x 版本 export ANTHROPIC_DEFAULT_OPUS_MODEL=gemini-2.5-pro export ANTHROPIC_DEFAULT_SONNET_MODEL=gemini-2.5-flash export ANTHROPIC_DEFAULT_HAIKU_MODEL=gemini-2.5-flash-lite # 1.x.x 版本 export ANTHROPIC_MODEL=gemini-2.5-pro export ANTHROPIC_SMALL_FAST_MODEL=gemini-2.5-flash 使用 OpenAI GPT 5 模型： bash export ANTHROPIC_BASE_URL=http://127.0.0.1:8317 export ANTHROPIC_AUTH_TOKEN=sk-dummy # 2.x.x 版本 export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5(high) export ANTHROPIC_DEFAULT_SONNET_MODEL=gpt-5(medium) export ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-5(minimal) # 不推荐使用 gpt-5(minimal)，建议使用 qwen3-coder-flash 或者 gemini-2.5-flash-lite 代替 # 1.x.x 版本 export ANTHROPIC_MODEL=gpt-5 export ANTHROPIC_SMALL_FAST_MODEL=gpt-5(minimal) # 不推荐使用 gpt-5(minimal)，建议使用 qwen3-coder-flash 或者 gemini-2.5-flash-lite 代替 使用 OpenAI GPT 5 Codex 模型: bash export ANTHROPIC_BASE_URL=http://127.0.0.1:8317 export ANTHROPIC_AUTH_TOKEN=sk-dummy # 2.x.x 版本 export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5-codex(high) export ANTHROPIC_DEFAULT_SONNET_MODEL=gpt-5-codex(medium) export ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-5-codex(low) # 不推荐使用 gpt-5-codex(low)，建议使用 qwen3-coder-flash 或者 gemini-2.5-flash-lite 代替 # 1.x.x 版本 export ANTHROPIC_MODEL=gpt-5-codex export ANTHROPIC_SMALL_FAST_MODEL=gpt-5-codex(low) # 不推荐使用 gpt-5-codex(low)，建议使用 qwen3-coder-flash 或者 gemini-2.5-flash-lite 代替 使用 Claude 模型： bash export ANTHROPIC_BASE_URL=http://127.0.0.1:8317 export ANTHROPIC_AUTH_TOKEN=sk-dummy # 2.x.x 版本 export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-1-20250805 export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5-20250929 export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-3-5-haiku-20241022 # 1.x.x 版本 export ANTHROPIC_MODEL=claude-sonnet-4-20250514 export ANTHROPIC_SMALL_FAST_MODEL=claude-3-5-haiku-20241022 使用 Qwen 模型： bash export ANTHROPIC_BASE_URL=http://127.0.0.1:8317 export ANTHROPIC_AUTH_TOKEN=sk-dummy # 2.x.x 版本 export ANTHROPIC_DEFAULT_OPUS_MODEL=qwen3-coder-plus export ANTHROPIC_DEFAULT_SONNET_MODEL=qwen3-coder-plus export ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen3-coder-flash # 1.x.x 版本 export ANTHROPIC_MODEL=qwen3-coder-plus export ANTHROPIC_SMALL_FAST_MODEL=qwen3-coder-flash 使用 iFlow 模型： bash export ANTHROPIC_BASE_URL=http://127.0.0.1:8317 export ANTHROPIC_AUTH_TOKEN=sk-dummy # 2.x.x 版本 export ANTHROPIC_DEFAULT_OPUS_MODEL=qwen3-max export ANTHROPIC_DEFAULT_SONNET_MODEL=qwen3-coder-plus export ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen3-235b-a22b-instruct # 1.x.x 版本 export ANTHROPIC_MODEL=qwen3-max export ANTHROPIC_SMALL_FAST_MODEL=qwen3-235b-a22b-instruct --- # Factory Droid | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/agent-client/droid#VPContent) 回到顶部 Factory Droid [​](https://help.router-for.me/cn/agent-client/droid#factory-droid) ================================================================================== 启动 CLIProxyAPI 服务器，然后编辑 `~/.factory/config.json` 文件。 config.json: json { "custom_models": [\ {\ "model": "gemini-2.5-pro",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "claude-sonnet-4-5-20250929",\ "base_url": "http://127.0.0.1:8317",\ "api_key": "sk-dummy",\ "provider": "anthropic"\ },\ {\ "model": "claude-opus-4-1-20250805",\ "base_url": "http://127.0.0.1:8317",\ "api_key": "sk-dummy",\ "provider": "anthropic"\ },\ {\ "model": "claude-sonnet-4-20250514",\ "base_url": "http://127.0.0.1:8317",\ "api_key": "sk-dummy",\ "provider": "anthropic"\ },\ {\ "model": "gpt-5",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5(minimal)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5(low)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5(medium)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5(high)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5-codex",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5-codex(low)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5-codex(medium)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ },\ {\ "model": "gpt-5-codex(high)",\ "base_url": "http://127.0.0.1:8317/v1",\ "api_key": "sk-dummy",\ "provider": "openai"\ }\ ] } --- # 管理 API | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/management/api#VPContent) 回到顶部 管理 API [​](https://help.router-for.me/cn/management/api#%E7%AE%A1%E7%90%86-api) ================================================================================ 基础路径：`http://localhost:8317/v0/management` 该 API 用于管理 CLIProxyAPI 的运行时配置与认证文件。所有变更会持久化写入 YAML 配置文件，并由服务自动热重载。 注意：以下选项不能通过 API 修改，需在配置文件中设置（如有必要可重启）： * `allow-remote-management` * `remote-management-key`（若在启动时检测到明文，会自动进行 bcrypt 加密并写回配置） 认证 [​](https://help.router-for.me/cn/management/api#%E8%AE%A4%E8%AF%81) ------------------------------------------------------------------------ * 所有请求（包括本地访问）都必须提供有效的管理密钥. * 远程访问需要在配置文件中开启远程访问： `allow-remote-management: true` * 通过以下任意方式提供管理密钥（明文）： * `Authorization: Bearer ` * `X-Management-Key: ` 若在启动时检测到配置中的管理密钥为明文，会自动使用 bcrypt 加密并回写到配置文件中。 其它说明： * 设置环境变量 `MANAGEMENT_PASSWORD` 会将其视为额外的明文管理密钥，并强制启用远程管理（即便 `allow-remote-management` 为 false）。该值不会写入配置，需要通过 `Authorization` / `X-Management-Key` 头部直接发送。 * 通过 `cliproxy run --password ` 或 SDK 的 `WithLocalManagementPassword` 启动服务后，来自 `127.0.0.1`/`::1` 的请求可使用该“本地密码”替代远程密钥，同样通过上述头部传递；该密码仅存在于运行时内存。 * 仅当 `remote-management.secret-key` 为空且未设置 `MANAGEMENT_PASSWORD` 时，管理 API 才会整体被禁用（所有 `/v0/management` 路由均返回 404）。 * 对于远程 IP，连续 5 次认证失败会触发临时封禁（约 30 分钟）。 请求/响应约定 [​](https://help.router-for.me/cn/management/api#%E8%AF%B7%E6%B1%82-%E5%93%8D%E5%BA%94%E7%BA%A6%E5%AE%9A) ------------------------------------------------------------------------------------------------------------------ * Content-Type：`application/json`（除非另有说明）。 * 布尔/整数/字符串更新：请求体为 `{ "value": }`。 * 数组 PUT：既可使用原始数组（如 `["a","b"]`），也可使用 `{ "items": [ ... ] }`。 * 数组 PATCH：支持 `{ "old": "k1", "new": "k2" }` 或 `{ "index": 0, "value": "k2" }`。 * 对象数组 PATCH：支持按索引或按关键字段匹配（各端点中单独说明）。 端点说明 [​](https://help.router-for.me/cn/management/api#%E7%AB%AF%E7%82%B9%E8%AF%B4%E6%98%8E) -------------------------------------------------------------------------------------------- ### Usage（请求统计） [​](https://help.router-for.me/cn/management/api#usage-%E8%AF%B7%E6%B1%82%E7%BB%9F%E8%AE%A1) * GET `/usage` — 获取内存中的请求统计 * 响应： json { "usage": { "total_requests": 24, "success_count": 22, "failure_count": 2, "total_tokens": 13890, "requests_by_day": { "2024-05-20": 12 }, "requests_by_hour": { "09": 4, "18": 8 }, "tokens_by_day": { "2024-05-20": 9876 }, "tokens_by_hour": { "09": 1234, "18": 865 }, "apis": { "POST /v1/chat/completions": { "total_requests": 12, "total_tokens": 9021, "models": { "gpt-4o-mini": { "total_requests": 8, "total_tokens": 7123, "details": [\ {\ "timestamp": "2024-05-20T09:15:04.123456Z",\ "source": "openai",\ "auth_index": "a1b2c3d4e5f67890",\ "tokens": {\ "input_tokens": 523,\ "output_tokens": 308,\ "reasoning_tokens": 0,\ "cached_tokens": 0,\ "total_tokens": 831\ },\ "failed": false\ }\ ] } } } } }, "failed_requests": 2 } * 说明： * 仅统计带有 token 使用信息的请求，服务重启后数据会被清空。 * 小时维度会将所有日期折叠到 `00`–`23` 的统一小时桶中。 * 顶层字段 `failed_requests` 与 `usage.failure_count` 相同，便于轮询。 * GET `/usage/export` — 导出完整的请求统计快照（用于备份/迁移） * 响应： json { "version": 1, "exported_at": "2025-12-26T03:49:51Z", "usage": { "total_requests": 24, "success_count": 22, "failure_count": 2, "total_tokens": 13890, "requests_by_day": {}, "requests_by_hour": {}, "tokens_by_day": {}, "tokens_by_hour": {}, "apis": {} } } * 说明： * `exported_at` 为 UTC 时间（RFC 3339）。 * `usage` 的结构与 `GET /usage` 返回的 `usage` 字段一致。 * POST `/usage/import` — 导入并合并请求统计快照到内存（自动去重） * 请求： bash curl -X POST -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ --data-binary @usage-export.json \ http://localhost:8317/v0/management/usage/import * 响应： json { "added": 10, "skipped": 2, "total_requests": 123, "failed_requests": 4 } * 说明： * 该接口为“合并”而非覆盖；重复请求明细会被跳过并计入 `skipped`。 * 可直接使用 `GET /usage/export` 的响应 JSON 作为请求体（其中 `exported_at` 会被忽略）。 * `version` 当前支持 `1`（也接受省略/`0` 作为兼容）。 ### Config [​](https://help.router-for.me/cn/management/api#config) * GET `/config` — 获取完整的配置 * 请求: bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/config * 响应: 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"}]}]} * 说明： * 返回中不再包含 `generative-language-api-key`；若需纯字符串视图，可使用专用的 `GET /generative-language-api-key` 接口。 * 若服务尚未加载配置文件，则返回空对象 `{}`。 ### 最新版本 [​](https://help.router-for.me/cn/management/api#%E6%9C%80%E6%96%B0%E7%89%88%E6%9C%AC) * GET `/latest-version` — 查询最新发行版本号（仅返回版本字符串，不下载资源） * 请求： bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/latest-version * 响应： json { "latest-version": "v1.2.3" } * 说明： * 版本信息来源 `https://api.github.com/repos/router-for-me/CLIProxyAPI/releases/latest`，请求头使用 `User-Agent: CLIProxyAPI`。 * 若配置了 `proxy-url`，查询会复用该代理；仅返回版本号，不会下载发布资产。 ### Debug [​](https://help.router-for.me/cn/management/api#debug) * GET `/debug` — 获取当前 debug 状态 * 请求： bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/debug * 响应： json { "debug": false } * PUT/PATCH `/debug` — 设置 debug（布尔值） * 请求： bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":true}' \ http://localhost:8317/v0/management/debug * 响应： json { "status": "ok" } ### Config YAML [​](https://help.router-for.me/cn/management/api#config-yaml) * GET `/config.yaml` — 原样下载持久化的 YAML 配置 * 响应头： * `Content-Type: application/yaml; charset=utf-8` * `Cache-Control: no-store` * 响应体：保留注释与格式的原始 YAML 流。 * PUT `/config.yaml` — 使用 YAML 文档整体替换配置 * 请求： bash curl -X PUT -H 'Content-Type: application/yaml' \ -H 'Authorization: Bearer ' \ --data-binary @config.yaml \ http://localhost:8317/v0/management/config.yaml * 响应： json { "ok": true, "changed": ["config"] } * 说明： * 服务会先加载 YAML 验证其有效性，校验失败返回 `422` 以及 `{ "error": "invalid_config", "message": "..." }`。 * 写入失败会返回 `500`，格式 `{ "error": "write_failed", "message": "..." }`。 ### 文件日志开关 [​](https://help.router-for.me/cn/management/api#%E6%96%87%E4%BB%B6%E6%97%A5%E5%BF%97%E5%BC%80%E5%85%B3) * GET `/logging-to-file` — 查看是否启用文件日志 * 响应： json { "logging-to-file": true } * PUT/PATCH `/logging-to-file` — 开启或关闭文件日志 * 请求： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":false}' \ http://localhost:8317/v0/management/logging-to-file * 响应： json { "status": "ok" } ### 日志文件 [​](https://help.router-for.me/cn/management/api#%E6%97%A5%E5%BF%97%E6%96%87%E4%BB%B6) * GET `/logs` — 获取合并后的最新日志行 * 查询参数： * `after`（可选）：Unix 时间戳，仅返回该时间之后的日志。 * 响应： json { "lines": ["2024-05-20 12:00:00 info request accepted"], "line-count": 125, "latest-timestamp": 1716206400 } * 说明： * 需要先启用文件日志，否则会以 `400` 返回 `{ "error": "logging to file disabled" }`。 * 若当前没有日志文件，返回的 `lines` 为空数组、`line-count` 为 `0`。 * `latest-timestamp` 是本轮扫描到的最大时间戳；若日志无时间戳，则返回输入的 `after`（或 `0`），可直接作为下一次轮询的 `after`。 * `line-count` 为本轮遍历的行总数，包含被 `after` 过滤掉的旧日志，可帮助判断日志是否有新增。 * DELETE `/logs` — 删除轮换日志并清空主日志 * 响应： json { "success": true, "message": "Logs cleared successfully", "removed": 3 } ### 请求错误日志 [​](https://help.router-for.me/cn/management/api#%E8%AF%B7%E6%B1%82%E9%94%99%E8%AF%AF%E6%97%A5%E5%BF%97) * GET `/request-error-logs` — 在关闭请求日志时列出错误请求日志文件 * 响应： json { "files": [\ {\ "name": "error-2024-05-20.log",\ "size": 12345,\ "modified": 1716206400\ }\ ] } * 说明： * 当 `request-log` 为 `true` 时，该接口始终返回空列表。 * 文件来自同一日志目录，文件名必须以 `error-` 开头并以 `.log` 结尾。 * `modified` 为最后修改时间的 Unix 时间戳。 * GET `/request-error-logs/:name` — 下载指定错误请求日志文件 * 请求： bash curl -H 'Authorization: Bearer ' \ -OJ 'http://localhost:8317/v0/management/request-error-logs/error-2024-05-20.log' * 说明： * `name` 必须是安全文件名（不能包含 `/` 或 `\`），且必须与现有的 `error-*.log` 条目匹配，否则会返回校验错误或未找到错误。 * 处理函数会在发送文件前校验解析后的完整路径，确保其仍位于日志目录之内。 ### Usage 统计开关 [​](https://help.router-for.me/cn/management/api#usage-%E7%BB%9F%E8%AE%A1%E5%BC%80%E5%85%B3) * GET `/usage-statistics-enabled` — 查看是否启用请求统计 * 响应： json { "usage-statistics-enabled": true } * PUT/PATCH `/usage-statistics-enabled` — 启用或关闭统计 * 请求： bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":true}' \ http://localhost:8317/v0/management/usage-statistics-enabled * 响应： json { "status": "ok" } ### 代理服务器 URL [​](https://help.router-for.me/cn/management/api#%E4%BB%A3%E7%90%86%E6%9C%8D%E5%8A%A1%E5%99%A8-url) * GET `/proxy-url` — 获取代理 URL 字符串 * 请求： bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/proxy-url * 响应： json { "proxy-url": "socks5://user:[email protected]:1080/" } * PUT/PATCH `/proxy-url` — 设置代理 URL 字符串 * 请求（PUT）： bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":"socks5://user:[email protected]:1080/"}' \ http://localhost:8317/v0/management/proxy-url * 请求（PATCH）： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":"http://127.0.0.1:8080"}' \ http://localhost:8317/v0/management/proxy-url * 响应： json { "status": "ok" } * DELETE `/proxy-url` — 清空代理 URL * 请求： bash curl -H 'Authorization: Bearer ' -X DELETE http://localhost:8317/v0/management/proxy-url * 响应： json { "status": "ok" } ### 超出配额行为 [​](https://help.router-for.me/cn/management/api#%E8%B6%85%E5%87%BA%E9%85%8D%E9%A2%9D%E8%A1%8C%E4%B8%BA) * GET `/quota-exceeded/switch-project` * 请求： bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/quota-exceeded/switch-project * 响应： json { "switch-project": true } * PUT/PATCH `/quota-exceeded/switch-project` — 布尔值 * 请求： bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":false}' \ http://localhost:8317/v0/management/quota-exceeded/switch-project * 响应： json { "status": "ok" } * GET `/quota-exceeded/switch-preview-model` * 请求： bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/quota-exceeded/switch-preview-model * 响应： json { "switch-preview-model": true } * PUT/PATCH `/quota-exceeded/switch-preview-model` — 布尔值 * 请求： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":true}' \ http://localhost:8317/v0/management/quota-exceeded/switch-preview-model * 响应： json { "status": "ok" } ### API Keys（代理服务认证） [​](https://help.router-for.me/cn/management/api#api-keys-%E4%BB%A3%E7%90%86%E6%9C%8D%E5%8A%A1%E8%AE%A4%E8%AF%81) 这些接口会更新配置中 `auth.providers` 内置的 `config-api-key` 提供方，旧版顶层 `api-keys` 会自动保持同步。 * GET `/api-keys` — 返回完整列表 * 请求： bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/api-keys * 响应： json { "api-keys": ["k1","k2","k3"] } * PUT `/api-keys` — 完整改写列表 * 请求： bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '["k1","k2","k3"]' \ http://localhost:8317/v0/management/api-keys * 响应： json { "status": "ok" } * PATCH `/api-keys` — 修改其中一个（`old/new` 或 `index/value`） * 请求（按 old/new）： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"old":"k2","new":"k2b"}' \ http://localhost:8317/v0/management/api-keys * 请求（按 index/value）： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"index":0,"value":"k1b"}' \ http://localhost:8317/v0/management/api-keys * 响应： json { "status": "ok" } * DELETE `/api-keys` — 删除其中一个（`?value=` 或 `?index=`） * 请求（按值删除）： bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/api-keys?value=k1' * 请求（按索引删除）： bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/api-keys?index=0' * 响应： json { "status": "ok" } ### Gemini API Key [​](https://help.router-for.me/cn/management/api#gemini-api-key) * GET `/gemini-api-key` * 请求： bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/gemini-api-key * 响应： json { "gemini-api-key": [\ {"api-key":"AIzaSy...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":"AIzaSy...02","proxy-url":"socks5://proxy.example.com:1080","excluded-models":["gemini-pro-vision"]}\ ] } * PUT `/gemini-api-key` * 请求（数组形式）： bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '[{"api-key":"AIzaSy-1","headers":{"X-Custom-Header":"vendor-value"},"excluded-models":["gemini-1.5-flash"]},{"api-key":"AIzaSy-2","base-url":"https://custom.example.com","excluded-models":["gemini-pro-vision"]}]' \ http://localhost:8317/v0/management/gemini-api-key * 响应： json { "status": "ok" } * PATCH `/gemini-api-key` * 请求（按索引更新）： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"index":0,"value":{"api-key":"AIzaSy-1","base-url":"https://custom.example.com","headers":{"X-Custom-Header":"custom-value"},"proxy-url":"","excluded-models":["gemini-1.5-pro","gemini-pro-vision"]}}' \ http://localhost:8317/v0/management/gemini-api-key * 请求（按 api-key 匹配更新）： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"match":"AIzaSy-1","value":{"api-key":"AIzaSy-1","headers":{"X-Custom-Header":"custom-value"},"proxy-url":"socks5://proxy.example.com:1080","excluded-models":["gemini-1.5-pro-latest"]}}' \ http://localhost:8317/v0/management/gemini-api-key * 响应： json { "status": "ok" } * DELETE `/gemini-api-key` * 请求（按 api-key 删除）： bash curl -H 'Authorization: Bearer ' -X DELETE \ 'http://localhost:8317/v0/management/gemini-api-key?api-key=AIzaSy-1' * 请求（按索引删除）： bash curl -H 'Authorization: Bearer ' -X DELETE \ 'http://localhost:8317/v0/management/gemini-api-key?index=0' * 响应： json { "status": "ok" } * 说明： * `excluded-models` 为可选字段，服务端会先转小写、去除首尾空白、去重并忽略空字符串后再保存。 ### Codex API KEY（对象数组） [​](https://help.router-for.me/cn/management/api#codex-api-key-%E5%AF%B9%E8%B1%A1%E6%95%B0%E7%BB%84) * GET `/codex-api-key` — 列出全部 * 请求： bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/codex-api-key * 响应： json { "codex-api-key": [ { "api-key": "sk-a", "base-url": "https://codex.example.com/v1", "proxy-url": "socks5://proxy.example.com:1080", "headers": { "X-Team": "cli" }, "excluded-models": ["gpt-4o-mini"] } ] } * PUT `/codex-api-key` — 完整改写列表 * 请求： bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '[{"api-key":"sk-a","base-url":"https://codex.example.com/v1","proxy-url":"socks5://proxy.example.com:1080","headers":{"X-Team":"cli"},"excluded-models":["gpt-4o-mini","gpt-4.1-mini"]},{"api-key":"sk-b","base-url":"https://custom.example.com","proxy-url":"","headers":{"X-Env":"prod"},"excluded-models":["gpt-3.5-turbo"]}]' \ http://localhost:8317/v0/management/codex-api-key * 响应： json { "status": "ok" } * PATCH `/codex-api-key` — 修改其中一个（按 `index` 或 `match`） * 请求（按索引）： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com","proxy-url":"","headers":{"X-Env":"stage"},"excluded-models":["gpt-3.5-turbo-instruct"]}}' \ http://localhost:8317/v0/management/codex-api-key * 请求（按匹配）： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":"https://codex.example.com/v1","proxy-url":"socks5://proxy.example.com:1080","headers":{"X-Team":"cli"},"excluded-models":["gpt-4o-mini","gpt-4.1"]}}' \ http://localhost:8317/v0/management/codex-api-key * 响应： json { "status": "ok" } * DELETE `/codex-api-key` — 删除其中一个（`?api-key=` 或 `?index=`） * 请求（按 api-key）： bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?api-key=sk-b2' * 请求（按索引）： bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/codex-api-key?index=0' * 响应： json { "status": "ok" } * 说明： * `base-url` 必填；若 PUT/PATCH 中将 `base-url` 留空，则该条目会被视为删除。 * `headers` 支持自定义请求头，服务端会自动去除空白键值对。 * `excluded-models` 可用于屏蔽该提供商下的指定模型，服务端会先转小写、去除首尾空白、去重并忽略空字符串。 ### 请求重试次数 [​](https://help.router-for.me/cn/management/api#%E8%AF%B7%E6%B1%82%E9%87%8D%E8%AF%95%E6%AC%A1%E6%95%B0) * GET `/request-retry` — 获取整数 * 请求： bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/request-retry * 响应： json { "request-retry": 3 } * PUT/PATCH `/request-retry` — 设置整数 * 请求： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":5}' \ http://localhost:8317/v0/management/request-retry * 响应： json { "status": "ok" } ### 最大重试间隔 [​](https://help.router-for.me/cn/management/api#%E6%9C%80%E5%A4%A7%E9%87%8D%E8%AF%95%E9%97%B4%E9%9A%94) * GET `/max-retry-interval` — 获取最大重试间隔（秒） * 请求： bash curl -H 'Authorization: BearER ' \ http://localhost:8317/v0/management/max-retry-interval * 响应： json { "max-retry-interval": 30 } * PUT/PATCH `/max-retry-interval` — 设置最大重试间隔（秒） * 请求： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: BearER ' \ -d '{"value":60}' \ http://localhost:8317/v0/management/max-retry-interval * 响应： json { "status": "ok" } ### 请求日志开关 [​](https://help.router-for.me/cn/management/api#%E8%AF%B7%E6%B1%82%E6%97%A5%E5%BF%97%E5%BC%80%E5%85%B3) * GET `/request-log` — 获取布尔值 * 请求： bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/request-log * 响应： json { "request-log": false } * PUT/PATCH `/request-log` — 设置布尔值 * 请求： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":true}' \ http://localhost:8317/v0/management/request-log * 响应： json { "status": "ok" } ### WebSocket 鉴权（`ws-auth`） [​](https://help.router-for.me/cn/management/api#websocket-%E9%89%B4%E6%9D%83-ws-auth) * GET `/ws-auth` — 查看 WebSocket 网关是否启用鉴权 * 请求： bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/ws-auth * 响应： json { "ws-auth": true } * PUT/PATCH `/ws-auth` — 切换 `/ws/*` 路由是否强制鉴权 * 请求： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"value":false}' \ http://localhost:8317/v0/management/ws-auth * 响应： json { "status": "ok" } * 说明： * 当从 `false` 切换为 `true` 时，服务会主动断开所有现有的 WebSocket 连接，确保重连时必须携带有效的 API 凭据。 * 关闭鉴权不会影响已建立的连接，但新的连接会跳过鉴权流程，直到再次开启。 ### Claude API KEY（对象数组） [​](https://help.router-for.me/cn/management/api#claude-api-key-%E5%AF%B9%E8%B1%A1%E6%95%B0%E7%BB%84) * GET `/claude-api-key` — 列出全部 * 请求： bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/claude-api-key * 响应： json { "claude-api-key": [ { "api-key": "sk-a", "base-url": "https://example.com/api", "proxy-url": "socks5://proxy.example.com:1080", "headers": { "X-Workspace": "team-a" }, "excluded-models": ["claude-3-opus"] } ] } * PUT `/claude-api-key` — 完整改写列表 * 请求： bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '[{"api-key":"sk-a","proxy-url":"socks5://proxy.example.com:1080","headers":{"X-Workspace":"team-a"},"excluded-models":["claude-3-opus"]},{"api-key":"sk-b","base-url":"https://c.example.com","proxy-url":"","headers":{"X-Env":"prod"},"excluded-models":["claude-3-sonnet","claude-3-5-haiku"]}]' \ http://localhost:8317/v0/management/claude-api-key * 响应： json { "status": "ok" } * PATCH `/claude-api-key` — 修改其中一个（按 `index` 或 `match`） * 请求（按索引）： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"index":1,"value":{"api-key":"sk-b2","base-url":"https://c.example.com","proxy-url":"","headers":{"X-Env":"stage"},"excluded-models":["claude-3.7-sonnet"]}}' \ http://localhost:8317/v0/management/claude-api-key * 请求（按匹配）： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"match":"sk-a","value":{"api-key":"sk-a","base-url":"","proxy-url":"socks5://proxy.example.com:1080","headers":{"X-Workspace":"team-a"},"excluded-models":["claude-3-opus","claude-3.5-sonnet"]}}' \ http://localhost:8317/v0/management/claude-api-key * 响应： json { "status": "ok" } * DELETE `/claude-api-key` — 删除其中一个（`?api-key=` 或 `?index=`） * 请求（按 api-key）： bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?api-key=sk-b2' * 请求（按索引）： bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/claude-api-key?index=0' * 响应： json { "status": "ok" } * 说明： * `headers` 为可选的键值对，服务端会自动去除空白键/值；若需要移除某个头，在请求中省略该字段即可。 * `excluded-models` 可用于屏蔽对应 Claude 模型，服务端会先转小写、去除首尾空白、去重并忽略空字符串。 ### OpenAI 兼容提供商（对象数组） [​](https://help.router-for.me/cn/management/api#openai-%E5%85%BC%E5%AE%B9%E6%8F%90%E4%BE%9B%E5%95%86-%E5%AF%B9%E8%B1%A1%E6%95%B0%E7%BB%84) * GET `/openai-compatibility` — 列出全部 * 请求： bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/openai-compatibility * 响应： json { "openai-compatibility": [ { "name": "openrouter", "base-url": "https://openrouter.ai/api/v1", "api-key-entries": [ { "api-key": "sk", "proxy-url": "" } ], "models": [], "headers": { "X-Provider": "openrouter" } } ] } * PUT `/openai-compatibility` — 完整改写列表 * 请求： bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '[{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[{"name":"m","alias":"a"}],"headers":{"X-Provider":"openrouter"}}]' \ http://localhost:8317/v0/management/openai-compatibility * 响应： json { "status": "ok" } * PATCH `/openai-compatibility` — 修改其中一个（按 `index` 或 `name`） * 请求（按名称）： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"name":"openrouter","value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[],"headers":{"X-Provider":"openrouter"}}}' \ http://localhost:8317/v0/management/openai-compatibility * 请求（按索引）： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"index":0,"value":{"name":"openrouter","base-url":"https://openrouter.ai/api/v1","api-key-entries":[{"api-key":"sk","proxy-url":""}],"models":[],"headers":{"X-Provider":"openrouter"}}}' \ http://localhost:8317/v0/management/openai-compatibility * 响应： json { "status": "ok" } * 说明： * 仍可提交遗留的 `api-keys` 字段，但所有密钥会自动迁移到 `api-key-entries` 中，返回结果中的 `api-keys` 会逐步留空。 * `headers` 可用于为某个兼容提供商统一追加 HTTP 头，服务端会自动去除空白键值。 * `base-url` 不能为空；若 PUT/PATCH 将 `base-url` 设为空字符串，则该提供商会被删除。 * DELETE `/openai-compatibility` — 删除（`?name=` 或 `?index=`） * 请求（按名称）： bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?name=openrouter' * 请求（按索引）： bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/openai-compatibility?index=0' * 响应： json { "status": "ok" } ### OAuth 排除模型 [​](https://help.router-for.me/cn/management/api#oauth-%E6%8E%92%E9%99%A4%E6%A8%A1%E5%9E%8B) 用于为基于 OAuth 的提供商配置需要排除的模型列表。键为提供商标识字符串，值为字符串数组。 * GET `/oauth-excluded-models` — 获取当前映射 * 请求： bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/oauth-excluded-models * 响应： json { "oauth-excluded-models": { "openai": ["gpt-4.1-mini"], "iflow": ["deepseek-v3.1", "glm-4.5"] } } * PUT `/oauth-excluded-models` — 完整替换整张映射表 * 请求： bash curl -X PUT -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"openai":["gpt-4.1-mini"],"iflow":["deepseek-v3.1","glm-4.5"]}' \ http://localhost:8317/v0/management/oauth-excluded-models * 响应： json { "status": "ok" } * 说明： * 请求体也可以为 `{ "items": { ... } }` 形式；无论哪种形式，空白模型名称都会被自动过滤。 * PATCH `/oauth-excluded-models` — 新增/更新或删除单个提供商条目 * 请求（新增或更新）： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"provider":"iflow","models":["deepseek-v3.1","glm-4.5"]}' \ http://localhost:8317/v0/management/oauth-excluded-models * 请求（通过空数组删除提供商）： bash curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"provider":"iflow","models":[]}' \ http://localhost:8317/v0/management/oauth-excluded-models * 响应： json { "status": "ok" } * 说明： * `provider` 会被标准化为小写。若传入空的 `models` 数组，则表示删除该提供商；如提供商不存在，则返回 `404`。 * DELETE `/oauth-excluded-models` — 删除某个提供商的全部排除模型 * 请求： bash curl -H 'Authorization: Bearer ' \ -X DELETE 'http://localhost:8317/v0/management/oauth-excluded-models?provider=iflow' * 响应： json { "status": "ok" } ### 认证文件管理 [​](https://help.router-for.me/cn/management/api#%E8%AE%A4%E8%AF%81%E6%96%87%E4%BB%B6%E7%AE%A1%E7%90%86) 管理 `auth-dir` 下的 JSON 令牌文件：列出、下载、上传、删除。 * GET `/auth-files` — 列表 * 请求： bash curl -H 'Authorization: Bearer ' http://localhost:8317/v0/management/auth-files * 响应（运行时认证管理器可用时）： json { "files": [\ {\ "id": "[email protected]",\ "name": "[email protected]",\ "provider": "claude",\ "label": "Claude Prod",\ "status": "ready",\ "status_message": "ok",\ "disabled": false,\ "unavailable": false,\ "runtime_only": false,\ "source": "file",\ "path": "/abs/path/auths/[email protected]",\ "size": 2345,\ "modtime": "2025-08-30T12:34:56Z",\ "email": "[email protected]",\ "account_type": "anthropic",\ "account": "workspace-1",\ "created_at": "2025-08-30T12:00:00Z",\ "updated_at": "2025-08-31T01:23:45Z",\ "last_refresh": "2025-08-31T01:23:45Z"\ }\ ] } * 说明： * 列表对 `name` 做不区分大小写的排序；`status`、`status_message`、`disabled`、`unavailable` 直接反映运行时认证状态，便于识别失效凭据。 * `runtime_only=true` 表示该凭据仅存在于运行时存储（例如 Git/PG/ObjectStore 或远程导入），`source` 会是 `memory`；若存在对应磁盘文件则 `source=file` 并补充 `path`/`size`/`modtime`。 * `email`、`account_type`、`account`、`last_refresh` 来源于 JSON 内的元数据（自动兼容 `last_refresh`／`lastRefreshedAt` 等字段）。 * 当核心认证管理器不可用时会退回到扫描 `auth-dir`，此时仅返回 `name`、`size`、`modtime`、`type`、`email` 字段。 * `runtime_only` 数据无法通过下载/删除端点处理，需要在对应提供商后台或通过其他 API 撤销。 * GET `/auth-files/download?name=` — 下载单个文件 * 请求： bash curl -H 'Authorization: Bearer ' -OJ 'http://localhost:8317/v0/management/auth-files/download?name=acc1.json' * 说明： * `name` 必须是 `.json` 文件名，且仅能下载 `source=file` 的条目；`runtime_only` 凭据没有磁盘文件无法导出。 * POST `/auth-files` — 上传 * 请求（multipart）： bash curl -X POST -F 'file=@/path/to/acc1.json' \ -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/auth-files * 请求（原始 JSON）： bash curl -X POST -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d @/path/to/acc1.json \ 'http://localhost:8317/v0/management/auth-files?name=acc1.json' * 响应： json { "status": "ok" } * 说明： * 需确保核心认证管理器已启用，否则会以 `503` 返回 `{ "error": "core auth manager unavailable" }`。 * multipart 与原始 JSON 两种上传方式都要求文件名以 `.json` 结尾，并会立即注册到运行时认证管理器中。 * DELETE `/auth-files?name=` — 删除单个文件 * 请求： bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/auth-files?name=acc1.json' * 响应： json { "status": "ok" } * 说明： * 仅删除磁盘上的 `.json` 文件，并在成功删除后通知运行时管理器禁用对应凭据；`runtime_only` 条目不会被该端点移除。 * DELETE `/auth-files?all=true` — 删除 `auth-dir` 下所有 `.json` 文件 * 请求： bash curl -H 'Authorization: Bearer ' -X DELETE 'http://localhost:8317/v0/management/auth-files?all=true' * 响应： json { "status": "ok", "deleted": 3 } * 说明： * 仅统计并删除磁盘文件，成功后同样会对被移除的凭据执行禁用；对纯内存条目无影响。 ### Vertex 凭据导入 [​](https://help.router-for.me/cn/management/api#vertex-%E5%87%AD%E6%8D%AE%E5%AF%BC%E5%85%A5) 等同 CLI `vertex-import`，用于上传 Google 服务账号 JSON，并在 `auth-dir` 下生成 `vertex-.json`。 * POST `/vertex/import` — 上传 Vertex 服务账号密钥 * 请求（multipart）： bash curl -X POST \ -H 'Authorization: Bearer ' \ -F 'file=@/path/to/my-project-sa.json' \ -F 'location=us-central1' \ http://localhost:8317/v0/management/vertex/import * 响应： json { "status": "ok", "auth-file": "/abs/path/auths/vertex-my-project.json", "project_id": "my-project", "email": "[email protected]", "location": "us-central1" } * 说明： * 必须使用 `multipart/form-data` 并通过 `file` 字段上传完整的服务账号 JSON。若 JSON 无效或缺少 `project_id`/`private_key` 会返回 `400`。 * `location` 表单（或查询）字段可选，未提供时保存为 `us-central1`，后续可在生成的文件中手动调整。 * 服务会自动规范化 `private_key`，写入 `vertex` 标签并通过 token store 持久化；若持久化失败，将以 `500` 返回 `{ "error": "save_failed", ... }`。 ### 登录/授权 URL [​](https://help.router-for.me/cn/management/api#%E7%99%BB%E5%BD%95-%E6%8E%88%E6%9D%83-url) 以下端点用于发起各提供商的登录流程，并返回需要在浏览器中打开的 URL。流程完成后，令牌会保存到 `auths/` 目录。 对于 Anthropic、Codex、Gemini CLI、Antigravity 与 iFlow，可附加 `?is_webui=true` 以便从管理界面复用内置回调转发。 * GET `/anthropic-auth-url` — 开始 Anthropic（Claude）登录 * 请求： bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/anthropic-auth-url * 响应： json { "status": "ok", "url": "https://...", "state": "anth-1716206400" } * 说明： * 若从 Web UI 触发，可添加 `?is_webui=true` 复用本地回调服务。 * GET `/codex-auth-url` — 开始 Codex 登录 * 请求： bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/codex-auth-url * 响应： json { "status": "ok", "url": "https://...", "state": "codex-1716206400" } * GET `/gemini-cli-auth-url` — 开始 Google（Gemini CLI）登录 * 查询参数： * `project_id`（可选）：Google Cloud 项目 ID。 * 请求： bash curl -H 'Authorization: Bearer ' \ 'http://localhost:8317/v0/management/gemini-cli-auth-url?project_id=' * 响应： json { "status": "ok", "url": "https://...", "state": "gem-1716206400" } * 说明： * 若未提供 `project_id`，服务会通过 Cloud Resource Manager API 枚举可访问的项目并自动选择首个可用项目，写入的 token 会包含该项目 ID 以及 `auto: true` 标记。 * 登录过程中会检测 `cloudaicompanion.googleapis.com` 是否已启用，若未启用则调用 Service Usage API 尝试开启；若开启失败，`/get-auth-status` 会返回 `project activation required: ...` 之类的错误提示。 * GET `/antigravity-auth-url` — 开始 Antigravity 登录 * 请求： bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/antigravity-auth-url * 响应： json { "status": "ok", "url": "https://...", "state": "ant-1716206400" } * 说明： * 若从 Web UI 触发，可添加 `?is_webui=true`，服务会在本地 `51121` 端口启动临时回调转发器，并复用主 HTTP 端口接收最终重定向。 * GET `/qwen-auth-url` — 开始 Qwen 登录（设备授权流程） * 请求： bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/qwen-auth-url * 响应： json { "status": "ok", "url": "https://...", "state": "gem-1716206400" } * GET `/iflow-auth-url` — 开始 iFlow 登录 * 请求： bash curl -H 'Authorization: Bearer ' \ http://localhost:8317/v0/management/iflow-auth-url * 响应： json { "status": "ok", "url": "https://...", "state": "ifl-1716206400" } * POST `/iflow-auth-url` — 使用已有 iFlow Cookie 登录 * 请求体： bash curl -X POST -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{"cookie":""}' \ http://localhost:8317/v0/management/iflow-auth-url * 成功响应： json { "status": "ok", "saved_path": "/abs/path/auths/iflow-user.json", "email": "[email protected]", "expired": "2025-05-20T10:00:00Z", "type": "cookie" } * 说明： * `cookie` 字段必填且不能为空，若缺失或格式不合法，会以 `400` 返回 `{ "status": "error", "error": "..." }`。 * 成功后服务会规范化 Cookie，换取 API token，将其保存为 `iflow-*.json` 认证文件，并返回保存路径与基础元信息。 * GET `/get-auth-status?state=` — 轮询 OAuth 流程状态 * 请求： bash curl -H 'Authorization: Bearer ' \ 'http://localhost:8317/v0/management/get-auth-status?state=' * 响应示例： json { "status": "wait" } json { "status": "ok" } json { "status": "error", "error": "Authentication failed" } * 说明： * `state` 参数必须与登录端点返回的值一致；若状态进入 `ok` 或 `error`，服务会清除该 state，再次轮询会收到 `{ "status": "ok" }` 表示流程已收尾。 * `status: "wait"` 表示仍在等待回调或令牌交换，可按需继续轮询。 错误响应 [​](https://help.router-for.me/cn/management/api#%E9%94%99%E8%AF%AF%E5%93%8D%E5%BA%94) -------------------------------------------------------------------------------------------- 通用错误格式： * 400 Bad Request: `{ "error": "invalid body" }` * 401 Unauthorized: `{ "error": "missing management key" }` 或 `{ "error": "invalid management key" }` * 403 Forbidden: `{ "error": "remote management disabled" }` * 404 Not Found: `{ "error": "item not found" }` 或 `{ "error": "file not found" }` * 422 Unprocessable Entity: `{ "error": "invalid_config", "message": "..." }` * 500 Internal Server Error: `{ "error": "failed to save config: ..." }` * 503 Service Unavailable: `{ "error": "core auth manager unavailable" }` 说明 [​](https://help.router-for.me/cn/management/api#%E8%AF%B4%E6%98%8E) ------------------------------------------------------------------------ * 变更会写回 YAML 配置文件，并由文件监控器热重载配置与客户端。 * `allow-remote-management` 与 `remote-management-key` 不能通过 API 修改，需在配置文件中设置。 --- # Amp CLI | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/agent-client/amp-cli#VPContent) 回到顶部 Amp CLI [​](https://help.router-for.me/cn/agent-client/amp-cli#amp-cli) ======================================================================== 本指南介绍如何将 CLIProxyAPI 与 Amp CLI 及 Amp IDE 扩展配合使用，让你能够通过 OAuth 在 Amp CLI 中使用现有的 Google/ChatGPT/Claude 订阅。 概述 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E6%A6%82%E8%BF%B0) ------------------------------------------------------------------------------ Amp CLI 集成通过增加专用路由来支持 Amp 的 API 调用模式，同时仍与现有 CLIProxyAPI 功能保持完全兼容。因此，你可以在同一台代理服务器上同时使用传统的 CLIProxyAPI 功能和 Amp CLI。 ### 主要特性 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E4%B8%BB%E8%A6%81%E7%89%B9%E6%80%A7) * **提供商路由别名**：将 Amp 的 `/api/provider/{provider}/v1...` 路径模式映射到 CLIProxyAPI 的处理程序。 * **管理代理**：通过安全的上游 API 密钥，将账户管理请求转发到 Amp 控制平面。 * **智能回退**：自动将未配置的模型路由到 ampcode.com。 * **安全优先**：管理路由需要 API 密钥认证（可选：限制到 localhost）。 * **自动处理 gzip**：自动解压来自 Amp 上游的响应。 ### 你可以做什么 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E4%BD%A0%E5%8F%AF%E4%BB%A5%E5%81%9A%E4%BB%80%E4%B9%88) * 将 Amp CLI 与你的 Google 账户配合使用（Gemini 3 Pro Preview、Gemini 2.5 Pro、Gemini 2.5 Flash） * 将 Amp CLI 与你的 ChatGPT Plus/Pro 订阅配合使用（GPT-5、GPT-5 Codex 模型） * 将 Amp CLI 与你的 Claude Pro/Max 订阅配合使用（Claude Sonnet 4.5、Opus 4.1） * 将 Amp IDE 扩展（VS Code、Cursor、Windsurf 等）与同一个代理配合使用 * 在同一个代理服务器下运行多个 CLI 工具（Factory + Amp） * 自动将未配置的模型路由到 ampcode.com ### 你应该对哪些提供商进行 OAuth 登录？ [​](https://help.router-for.me/cn/agent-client/amp-cli#%E4%BD%A0%E5%BA%94%E8%AF%A5%E5%AF%B9%E5%93%AA%E4%BA%9B%E6%8F%90%E4%BE%9B%E5%95%86%E8%BF%9B%E8%A1%8C-oauth-%E7%99%BB%E5%BD%95) **重要提示**：你需要对哪些提供商进行 OAuth 登录，取决于你安装的 Amp 版本当前使用的模型和功能。Amp 会为不同的代理模式和专用子代理使用不同的提供商： * **Smart 模式**：使用 Google/Gemini 模型（Gemini 3 Pro） * **Rush 模式**：使用 Anthropic/Claude 模型（Claude Haiku 4.5） * **Oracle 子代理**：使用 OpenAI/GPT 模型（GPT-5 medium reasoning） * **Librarian 子代理**：使用 Anthropic/Claude 模型（Claude Sonnet 4.5） * **Search 子代理**：使用 Anthropic/Claude 模型（Claude Haiku 4.5） * **Review 功能**：使用 Google/Gemini 模型（Gemini 2.5 Flash-Lite） 有关 Amp 使用哪些模型的最新信息，请参阅 **[Amp 模型文档](https://ampcode.com/models) **。 #### 回退行为 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E5%9B%9E%E9%80%80%E8%A1%8C%E4%B8%BA) CLIProxyAPI 采用智能回退机制： 1. **已在本地完成该提供商的 OAuth 登录**（`--login`、`--codex-login`、`--claude-login`）： * 请求会使用**你的 OAuth 订阅**（ChatGPT Plus/Pro、Claude Pro/Max、Google 账户） * 你可以使用订阅自带的用量配额 * 不消耗 Amp 点数 2. **未在本地完成该提供商的 OAuth 登录**： * 请求会自动转发到 **ampcode.com** * 使用 Amp 后端的提供商连接 * 如果该提供商为付费服务（OpenAI、Anthropic 付费层级），则**需要 Amp 点数** * 如果 Amp 点数余额不足，可能会导致报错 **建议**：对你拥有订阅的所有提供商都进行 OAuth 登录，以最大化订阅价值并尽量减少 Amp 点数消耗。如果你未订阅 Amp 使用的全部提供商，请确保你有足够的 Amp 点数用于回退请求。 架构 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E6%9E%B6%E6%9E%84) ------------------------------------------------------------------------------ ### 请求流程 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E8%AF%B7%E6%B1%82%E6%B5%81%E7%A8%8B) Amp CLI/IDE ↓ ├─ 提供商 API 请求 (/api/provider/{provider}/v1/...) │ ↓ │ ├─ 模型在本地配置了吗？ │ │ 是 → 使用本地 OAuth 令牌（OpenAI/Claude/Gemini 处理程序） │ │ 否 → 转发到 ampcode.com（反向代理） │ ↓ │ 响应 │ └─ 管理请求 (/api/auth, /api/user, /api/threads, ...) ↓ ├─ 使用 CLIProxyAPI 的 `api-keys` 进行认证 ↓ ├─ 可选：限制为 localhost ↓ └─ 反向代理到 ampcode.com（使用 `upstream-api-key`） ↓ 响应（若为 gzip 压缩则自动解压） ### 组件 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E7%BB%84%E4%BB%B6) Amp 集成是作为一个模块化的路由模块（`internal/api/modules/amp/`）实现的，包含以下组件： 1. **路由别名** (`routes.go`)：将 Amp 风格的路径映射到标准处理程序 2. **反向代理** (`proxy.go`)：将管理请求转发到 ampcode.com 3. **回退处理程序** (`fallback_handlers.go`)：将未配置的模型路由到 ampcode.com 4. **密钥管理** (`secret.go`)：带缓存的多源 API 密钥解析 5. **主模块** (`amp.go`)：协调注册和配置 配置 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E9%85%8D%E7%BD%AE) ------------------------------------------------------------------------------ ### 基础配置 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E5%9F%BA%E7%A1%80%E9%85%8D%E7%BD%AE) 将 `ampcode` 块添加到你的 `config.yaml` 中（从 v6.5.37 开始，旧版的 `amp-upstream-*` 键会在加载时自动迁移并重写为该结构）： yaml # 供客户端（例如 Amp CLI、VS Code）向 CLIProxyAPI 认证的 API 密钥 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" ### 安全设置 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E5%AE%89%E5%85%A8%E8%AE%BE%E7%BD%AE) #### 管理路由的 API 密钥认证 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E7%AE%A1%E7%90%86%E8%B7%AF%E7%94%B1%E7%9A%84-api-%E5%AF%86%E9%92%A5%E8%AE%A4%E8%AF%81) 从 v6.6.15 版本开始，Amp 管理路由（`/api/auth`、`/api/user`、`/api/threads`、`/threads` 等）由 CLIProxyAPI 的标准 API 密钥认证中间件保护。 * 如果你在 `config.yaml` 中配置了 `api-keys`（推荐），这些路由要求请求携带有效的 API 密钥（`Authorization: Bearer ` 或 `X-Api-Key: `），否则返回 `401 Unauthorized`。 * 本地认证成功后，代理会移除客户端的 `Authorization`/`X-Api-Key`，并使用 `ampcode.upstream-api-key` 调用上游的 ampcode.com 服务。 #### `ampcode.restrict-management-to-localhost` [​](https://help.router-for.me/cn/agent-client/amp-cli#ampcode-restrict-management-to-localhost) **默认值：`false`** 启用后，管理路由（`/api/auth`、`/api/user`、`/api/threads` 等）只接受来自 localhost（127.0.0.1、::1）的连接。这可以防止： * 浏览器“路过式”攻击（Drive-by browser attacks） * 对管理端点的远程访问 * 基于 CORS 的攻击 * 请求头欺骗攻击（例如 `X-Forwarded-For: 127.0.0.1`） #### 工作原理 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E5%B7%A5%E4%BD%9C%E5%8E%9F%E7%90%86) 此限制使用**实际的 TCP 连接地址** (`RemoteAddr`)，而不是像 `X-Forwarded-For` 这样的 HTTP 头部。这可以防止头部欺骗攻击，但有重要的影响： * ✅ **适用于直接连接**：直接在你的机器或服务器上运行 CLIProxyAPI * ⚠️ **在反向代理后可能无法工作**：如果部署在 nginx、Cloudflare 或其他代理之后，连接将看起来来自代理的 IP，而不是 localhost #### 反向代理部署 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86%E9%83%A8%E7%BD%B2) 如果你需要在反向代理（nginx, Caddy, Cloudflare Tunnel 等）后面运行 CLIProxyAPI： 1. **保持 localhost 限制为禁用状态（默认）**： yaml ampcode: restrict-management-to-localhost: false 2. **确保已启用 API 密钥认证**（推荐）： * 在 `config.yaml` 中配置 `api-keys`，并让客户端发送密钥 * 结合防火墙/VPN/零信任控制来减少暴露面 3. **nginx 配置示例**（阻止对管理路由的外部访问）： nginx location /api/auth { deny all; } location /api/user { deny all; } location /api/threads { deny all; } location /api/internal { deny all; } **注意**：`ampcode.restrict-management-to-localhost` 是一个额外的加固选项；在反向代理后面，通常保持为 `false`。 设置 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E8%AE%BE%E7%BD%AE) ------------------------------------------------------------------------------ ### 1\. 配置 CLIProxyAPI [​](https://help.router-for.me/cn/agent-client/amp-cli#_1-%E9%85%8D%E7%BD%AE-cliproxyapi) 创建或编辑 `config.yaml`。你需要准备两类 API 密钥： 1. `api-keys`：供像 Amp CLI 这样的客户端连接到你的 CLIProxyAPI 实例。 2. `ampcode.upstream-api-key`：供 CLIProxyAPI 连接到 `ampcode.com` 后端。请从 **[https://ampcode.com/settings](https://ampcode.com/settings) ** 获取。 yaml port: 8317 auth-dir: "~/.cli-proxy-api" # 供客户端（例如 Amp CLI）使用的 API 密钥 api-keys: - "your-client-secret-key" # 你可以更改此密钥 # Amp 集成 ampcode: upstream-url: "https://ampcode.com" # 你在 ampcode.com 的个人 API 密钥 upstream-api-key: "paste-your-ampcode-api-key-here" restrict-management-to-localhost: false # 其他标准设置... debug: false logging-to-file: true ### 2\. 对提供商进行 OAuth 登录 [​](https://help.router-for.me/cn/agent-client/amp-cli#_2-%E5%AF%B9%E6%8F%90%E4%BE%9B%E5%95%86%E8%BF%9B%E8%A1%8C-oauth-%E7%99%BB%E5%BD%95) 对你想使用的提供商进行 OAuth 登录： **Google 账户 (Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 3 Pro Preview):** bash ./cli-proxy-api --login **ChatGPT Plus/Pro (GPT-5, GPT-5 Codex):** bash ./cli-proxy-api --codex-login **Claude Pro/Max (Claude Sonnet 4.5, Opus 4.1):** bash ./cli-proxy-api --claude-login 令牌会保存到： * Gemini: `~/.cli-proxy-api/gemini-.json` * OpenAI Codex: `~/.cli-proxy-api/codex-.json` * Claude: `~/.cli-proxy-api/claude-.json` ### 3\. 启动代理 [​](https://help.router-for.me/cn/agent-client/amp-cli#_3-%E5%90%AF%E5%8A%A8%E4%BB%A3%E7%90%86) bash ./cli-proxy-api --config config.yaml ### 4\. 配置 Amp CLI [​](https://help.router-for.me/cn/agent-client/amp-cli#_4-%E9%85%8D%E7%BD%AE-amp-cli) #### 选项 A：设置文件 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E9%80%89%E9%A1%B9-a-%E8%AE%BE%E7%BD%AE%E6%96%87%E4%BB%B6) Amp CLI 使用两个配置文件： 1. **设置文件**：`~/.config/amp/settings.json` - 通用设置 2. **密钥文件**：`~/.local/share/amp/secrets.json` - 敏感凭证（API 密钥） 编辑 `~/.config/amp/settings.json` 配置 URL： json { "amp.url": "http://localhost:8317" } 编辑 `~/.local/share/amp/secrets.json` 配置 API 密钥： json { "apiKey@http://localhost:8317": "your-client-secret-key" } #### 选项 B：环境变量 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E9%80%89%E9%A1%B9-b-%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F) bash export AMP_URL=http://localhost:8317 export AMP_API_KEY=your-client-secret-key 有了这个配置，`amp login` 命令就不再需要了。 ### 5\. 使用 Amp [​](https://help.router-for.me/cn/agent-client/amp-cli#_5-%E4%BD%BF%E7%94%A8-amp) 现在你已经准备好使用 Amp 了。所有请求都将通过你的代理进行路由。 bash amp "用 Python 写一个 hello world 程序" ### 6\. (可选) 配置 Amp IDE 扩展 [​](https://help.router-for.me/cn/agent-client/amp-cli#_6-%E5%8F%AF%E9%80%89-%E9%85%8D%E7%BD%AE-amp-ide-%E6%89%A9%E5%B1%95) 该代理也适用于 VS Code、Cursor、Windsurf 等 Amp IDE 扩展。 1. 在你的 IDE 中打开 Amp 扩展设置。 2. 将 **Amp URL** 设置为 `http://localhost:8317`。 3. 将 **Amp API Key** 设置为你配置的密钥（例如 `your-client-secret-key`）。 4. 开始在你的 IDE 中使用 Amp。 CLI 和 IDE 可以同时使用该代理。 用法 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E7%94%A8%E6%B3%95) ------------------------------------------------------------------------------ ### 支持的路由 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E6%94%AF%E6%8C%81%E7%9A%84%E8%B7%AF%E7%94%B1) #### 提供商别名（始终可用） [​](https://help.router-for.me/cn/agent-client/amp-cli#%E6%8F%90%E4%BE%9B%E5%95%86%E5%88%AB%E5%90%8D-%E5%A7%8B%E7%BB%88%E5%8F%AF%E7%94%A8) 即使没有配置 `ampcode.upstream-url`，这些路由也能工作： * `/api/provider/openai/v1/chat/completions` * `/api/provider/openai/v1/responses` * `/api/provider/anthropic/v1/messages` * `/api/provider/google/v1beta/models/:action` Amp CLI 调用这些路由时，会使用你在 CLIProxyAPI 中为对应提供商配置的 OAuth 令牌。 #### 管理路由（需要 `ampcode.upstream-url`） [​](https://help.router-for.me/cn/agent-client/amp-cli#%E7%AE%A1%E7%90%86%E8%B7%AF%E7%94%B1-%E9%9C%80%E8%A6%81-ampcode-upstream-url) 这些路由会通过反向代理转发到 ampcode.com： * `/api/auth` - 认证 * `/api/user` - 用户资料 * `/api/meta` - 元数据 * `/api/threads` - 对话线程 * `/api/telemetry` - 用量遥测 * `/api/internal` - 内部 API **安全**：需要一个 API 密钥；`ampcode.restrict-management-to-localhost` 是可选的（默认：false）。 ### 模型回退行为 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E6%A8%A1%E5%9E%8B%E5%9B%9E%E9%80%80%E8%A1%8C%E4%B8%BA) 当 Amp 请求一个模型时： 1. **检查本地配置**：CLIProxyAPI 是否有该模型提供商的 OAuth 令牌？ 2. **如果有**：路由到本地处理程序（使用你的 OAuth 订阅） 3. **如果没有**：转发到 ampcode.com（使用 Amp 的默认路由） 这实现了无缝的混合使用： * 你已配置的模型（Gemini, ChatGPT, Claude）→ 你的 OAuth 订阅 * 你未配置的模型 → Amp 的默认提供商 ### API 调用示例 [​](https://help.router-for.me/cn/agent-client/amp-cli#api-%E8%B0%83%E7%94%A8%E7%A4%BA%E4%BE%8B) **使用本地 OAuth 进行聊天补全：** bash curl http://localhost:8317/api/provider/openai/v1/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5", "messages": [{"role": "user", "content": "Hello"}] }' **管理端点（需要 API 密钥）：** bash curl http://localhost:8317/api/user \ -H "Authorization: Bearer " 故障排查 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E6%95%85%E9%9A%9C%E6%8E%92%E6%9F%A5) -------------------------------------------------------------------------------------------------- ### 常见问题 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98) | 症状 | 可能的原因 | 解决方法 | | --- | --- | --- | | `/api/provider/...` 404 | 路由路径不正确 | 确保路径完全匹配：`/api/provider/{provider}/v1...` | | `/api/user` 401 | 缺少/无效的 API 密钥 | 配置 `api-keys` 并发送 `Authorization: Bearer ` 或 `X-Api-Key: ` | | `/api/user` 403 | 启用了 localhost 限制且请求来自远程 | 从同一台机器运行或将 `ampcode.restrict-management-to-localhost` 设置为 `false` | | 提供商返回 401/403 | 缺少/过期的 OAuth | 重新运行 `--codex-login` 或 `--claude-login` | | Amp gzip 错误 | 响应解压缩问题 | 更新到最新版本；自动解压应能处理此问题 | | 模型请求未走代理 | Amp URL 配置错误 | 检查 `amp.url` 设置或 `AMP_URL` 环境变量 | | CORS 错误 | 受保护的管理端点 | 使用 CLI/终端，而不是浏览器 | ### 诊断 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E8%AF%8A%E6%96%AD) **检查代理日志：** bash # 如果 logging-to-file: true tail -f logs/requests.log # 如果在 tmux 中运行 tmux attach-session -t proxy **临时启用调试模式**： yaml debug: true **测试基础连通性：** bash # 检查代理是否正在运行 curl http://localhost:8317/v1/models # 检查 Amp 专用路由 curl http://localhost:8317/api/provider/openai/v1/models **验证 Amp 配置：** bash # 检查 Amp 是否正在使用代理 amp config get amp.url # 或检查环境变量 echo $AMP_URL ### 安全检查清单 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E5%AE%89%E5%85%A8%E6%A3%80%E6%9F%A5%E6%B8%85%E5%8D%95) * ✅ 配置并保护 `api-keys`（管理路由需要 API 密钥认证） * ✅ 在可能的情况下启用 `ampcode.restrict-management-to-localhost: true` 以进行额外加固（默认：false） * ✅ 不要将代理公网暴露（绑定到 localhost 或使用防火墙/VPN） * ✅ 在配置文件中安全地存储你的 `ampcode.upstream-api-key` * ✅ 定期重新运行登录命令以轮换 OAuth 令牌 * ✅ 如果处理敏感数据，将配置文件和 `auth-dir` 存储在加密磁盘上 * ✅ 保持代理二进制文件为最新版本，以获取安全修复 其他资源 [​](https://help.router-for.me/cn/agent-client/amp-cli#%E5%85%B6%E4%BB%96%E8%B5%84%E6%BA%90) -------------------------------------------------------------------------------------------------- * [Amp CLI 官方手册](https://ampcode.com/manual) --- # 使用 Docker Compose 运行 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/docker/docker-compose#VPContent) 回到顶部 使用 Docker Compose 运行 [​](https://help.router-for.me/cn/docker/docker-compose#%E4%BD%BF%E7%94%A8-docker-compose-%E8%BF%90%E8%A1%8C) =================================================================================================================================== 1. 克隆仓库并进入目录： bash git clone https://github.com/router-for-me/CLIProxyAPI.git cd CLIProxyAPI 2. 准备配置文件： 通过复制示例文件来创建 `config.yaml` 文件，并根据您的需求进行自定义。 bash cp config.example.yaml config.yaml _（Windows 用户请注意：您可以在 CMD 或 PowerShell 中使用 `copy config.example.yaml config.yaml`。）_ 3. 启动服务： * **适用于大多数用户（推荐）：** 运行以下命令，使用 Docker Hub 上的预构建镜像启动服务。服务将在后台运行。 bash docker compose up -d * **适用于进阶用户：** 如果您修改了源代码并需要构建新镜像，请使用交互式辅助脚本： * 对于 Windows (PowerShell): powershell .\docker-build.ps1 * 对于 Linux/macOS: bash bash docker-build.sh 脚本将提示您选择运行方式： * **选项 1：使用预构建的镜像运行 (推荐)**：从镜像仓库拉取最新的官方镜像并启动容器。这是最简单的开始方式。 * **选项 2：从源码构建并运行 (适用于开发者)**：从本地源代码构建镜像，将其标记为 `cli-proxy-api:local`，然后启动容器。如果您需要修改源代码，此选项很有用。 4. 要在容器内运行登录命令进行身份验证： * **Gemini**: bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --login * **OpenAI (Codex)**: bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --codex-login * **Claude**: bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --claude-login * **Qwen**: bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --qwen-login * **iFlow**: bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --iflow-login * **Antigravity**: bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --antigravity-login 5. 查看服务器日志： bash docker compose logs -f 6. 停止应用程序： bash docker compose down --- # 叁：NanoBanana实战 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/hands-on/tutorial-3#VPContent) 回到顶部 叁：NanoBanana实战 [​](https://help.router-for.me/cn/hands-on/tutorial-3#%E5%8F%81-nanobanana%E5%AE%9E%E6%88%98) ============================================================================================================= > **重要通知：因为现在 Gemini CLI 已经完整覆盖了 Gemini Web，并且全免费，所以自 6.2.X 版本起 CLIProxyAPI 将移除 Gemini Web 支持，如果还有想用 Gemini Web 的可以使用 6.1.X 版本，以下教程基于 6.1.X 版本** 经过前两期的实战，我们已成功在 `CLIProxyAPI` 上集成了 `Qwen Code`、`Gemini CLI` 和 `Codex`。本期内容将介绍如何通过添加 Gemini Web 的 Cookie，使 `CLIProxyAPI` 支持 `NanoBanana` 模型。 Gemini 的 `NanoBanana` 模型因其出色的图像处理能力而备受赞誉。然而，Google 并未提供该模型的免费 API。而现在，使用 `CLIProxyAPI`之后，我们就可以通过集成 Gemini Web，从而以免费 API 的形式使用 `NanoBanana` 啦。 我们有两种方法可以获取认证信息： ### 第一种方法 [​](https://help.router-for.me/cn/hands-on/tutorial-3#%E7%AC%AC%E4%B8%80%E7%A7%8D%E6%96%B9%E6%B3%95) 首先，使用您的 Google 账号登录 Gemini 官网 ([https://gemini.google.com/app](https://gemini.google.com/app) )。据了解，普通账号每天有 100 次图像生成配额，Pro 账号则有 1000 次。登录成功后，在浏览器中按 F12 打开开发者工具，并切换到“网络” (Network) 选项卡。 ![](https://img.072899.xyz/2025/09/074fcf1c455e99185ceeada71a27bd8c.png) 在筛选框中输入 `List`，然后将鼠标悬停在您的用户头像上。片刻之后，下方列表中应出现 `ListAccounts` 的条目。如果未出现，请刷新页面重试。 ![](https://img.072899.xyz/2025/09/7cb7104fa93a6b6a6903e0745d3b5573.png) 点击 `ListAccounts`，在“标头” (Headers) -> “请求标头” (Request Headers) 中找到 `Cookie`，并完整复制其值。 ![](https://img.072899.xyz/2025/09/c2ba085f10fcb145aff7e9d5081b9382.png) 回到 `CLIProxyAPI` 程序所在的目录，打开终端或命令行，输入命令 `cli-proxy-api --gemini-web-auth`。根据提示，粘贴我们刚才复制的 `Cookie` 值并回车，即可看到验证成功的消息，`Cookie` 已被自动保存。 ![](https://img.072899.xyz/2025/09/e149d07875cb8dab12de95f82d2b3e45.png) ### 第二种方法 [​](https://help.router-for.me/cn/hands-on/tutorial-3#%E7%AC%AC%E4%BA%8C%E7%A7%8D%E6%96%B9%E6%B3%95) 如果您使用的是 macOS 系统，或者第一种方法认证失败，那么可能需要手动输入 `__Secure-1PSID` 和 `__Secure-1PSIDTS` 的值。请切换到“应用” (Application) 选项卡，并依次复制图示中的这两个值。 ![](https://img.072899.xyz/2025/09/e5b5debae5ec74a31a1b527e506895e7.png) ![](https://img.072899.xyz/2025/09/7767f178e1186358f1a9a498108e5ac0.png) 在命令行执行验证时，根据提示手动填入这两个值即可完成验证。 ![](https://img.072899.xyz/2025/09/b02fb7704d5c67385d781f9d9893e0b2.png) ### 验证步骤 [​](https://help.router-for.me/cn/hands-on/tutorial-3#%E9%AA%8C%E8%AF%81%E6%AD%A5%E9%AA%A4) 接下来我们进行验证。需要注意的是，目前程序仅支持通过 OpenAI 兼容接口和 Gemini 原生接口进行文生图或图文生图的操作。因此，我们之前在 `Cherry Studio` 中设置的提供商类型 `OpenAI Response` 需要修改为 `OpenAI`。 ![](https://img.072899.xyz/2025/09/48892cc3ce1e3c4379b694afa45c5d35.png) 添加模型 `NanoBanana` (即 `gemini-2.5-flash-image-preview`)。 ![](https://img.072899.xyz/2025/09/4674845c6412ec6f5366d109070047fc.png) 现在，在 `Cherry Studio` 中测试一下吧！ ![](https://img.072899.xyz/2025/09/fdd35aa92224cd76cbf888ce3ff2cce2.png) 完美地满足了我们的要求，尽情享受“香蕉”吧！ ### 注意事项 [​](https://help.router-for.me/cn/hands-on/tutorial-3#%E6%B3%A8%E6%84%8F%E4%BA%8B%E9%A1%B9) * ~现阶段请避免在 `CLIProxyAPI` 中添加多个 Gemini Web 账户。因为当存在多个账户时，程序会轮询调用，这可能会破坏会話的连续性，导致请求失败。~ 6.0.17版本更新之后，程序支持 Gemini Web 粘性会话，可以添加多个账户了。 * 在 `Cherry Studio` 中，**切勿**在 `OpenAI Response` 提供商类型下添加 `NanoBanana` 模型。已知 `Cherry Studio` 在此情况下存在 Bug，会导致程序崩溃。 --- # 使用 Docker 运行 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/docker/docker#VPContent) 回到顶部 使用 Docker 运行 [​](https://help.router-for.me/cn/docker/docker#%E4%BD%BF%E7%94%A8-docker-%E8%BF%90%E8%A1%8C) =========================================================================================================== 运行以下命令进行登录（Gemini OAuth，端口 8085）： bash docker run --rm -p 8085:8085 -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api eceasy/cli-proxy-api:latest /CLIProxyAPI/CLIProxyAPI --login 运行以下命令进行登录（OpenAI OAuth，端口 1455）： bash docker run --rm -p 1455:1455 -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api eceasy/cli-proxy-api:latest /CLIProxyAPI/CLIProxyAPI --codex-login 运行以下命令进行登录（Claude OAuth，端口 54545）： bash docker run --rm -p 54545:54545 -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api eceasy/cli-proxy-api:latest /CLIProxyAPI/CLIProxyAPI --claude-login 运行以下命令进行登录（Qwen OAuth）： bash docker run -it -rm -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api eceasy/cli-proxy-api:latest /CLIProxyAPI/CLIProxyAPI --qwen-login 运行以下命令进行登录（iFlow OAuth，端口 11451）： bash docker run --rm -p 11451:11451 -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api eceasy/cli-proxy-api:latest /CLIProxyAPI/CLIProxyAPI --iflow-login 运行以下命令进行登录（Antigravity OAuth，端口 51121）： bash docker run --rm -p 51121:51121 -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml -v /path/to/your/auth-dir:/root/.cli-proxy-api eceasy/cli-proxy-api:latest /CLIProxyAPI/CLIProxyAPI --antigravity-login 运行以下命令启动服务器： 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 --- # 陆：新人最爱GUI | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/hands-on/tutorial-6#VPContent) 回到顶部 陆：新人最爱GUI [​](https://help.router-for.me/cn/hands-on/tutorial-6#%E9%99%86-%E6%96%B0%E4%BA%BA%E6%9C%80%E7%88%B1gui) =================================================================================================================== 在之前的文章中，我们已经介绍了如何通过命令行逐步运行 CLIProxyAPI。其实 CLIProxyAPI 还有配套的两个项目：EasyCLI 和 WebUI。 * **EasyCLI 仓库地址**：`https://github.com/router-for-me/EasyCLI` * **WebUI 仓库地址**：`https://github.com/router-for-me/Cli-Proxy-API-Management-Center` 这两个项目旨在降低普通用户的使用门槛。EasyCLI 是桌面客户端，而 WebUI 是 Web 管理界面，它们都通过连接 CLIProxyAPI 来工作。 我此前未提供 GUI 教程，是因为旧版本需要用户自行部署或安装，操作相对繁琐。从 `6.0.19` 版本开始，作者已将 WebUI 集成到主程序中。因此，用户现在可以直接通过内置的 Web 界面进行配置。 本文将简要介绍如何启用并访问 WebUI。关于 EasyCLI 的使用方法，将在后续关于容器云部署的文章中详细介绍。 #### 一、启用 WebUI [​](https://help.router-for.me/cn/hands-on/tutorial-6#%E4%B8%80%E3%80%81%E5%90%AF%E7%94%A8-webui) 首先，我们需要在原有的基础配置上进行调整，添加远程管理部分。完整的示例配置如下： yaml port: 8317 auth-dir: "~/.cli-proxy-api" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: - "ABC-123456" # 本次添加的远程管理部分 remote-management: allow-remote: true # 用于远程管理的KEY，和上边的api-keys要区分开 secret-key: "MGT-123456" disable-control-panel: false **请注意**：修改配置后，需要重启程序才能生效（新版本支持自动热重载）。 #### 二、访问 WebUI [​](https://help.router-for.me/cn/hands-on/tutorial-6#%E4%BA%8C%E3%80%81%E8%AE%BF%E9%97%AE-webui) 程序成功启动后，在浏览器中访问 `http://YOUR_SERVER_IP:8317/management.html` ，在管理密钥中输入之前设置的密码 `MGT-123456` 即可打开 WebUI 界面。 ![](https://img.072899.xyz/2025/10/37b12b67193ec67774e2f657e38eefc9.png) #### 三、重要注意事项 [​](https://help.router-for.me/cn/hands-on/tutorial-6#%E4%B8%89%E3%80%81%E9%87%8D%E8%A6%81%E6%B3%A8%E6%84%8F%E4%BA%8B%E9%A1%B9) WebUI 的界面设计直观，你可以自行探索各项功能。但需要特别注意的是，WebUI 中的 OAuth 认证功能仅支持本地运行（例如 `localhost` 或 `127.0.0.1`）的 CLIProxyAPI 实例。对于部署在远程服务器上的实例，由于 OAuth 服务商的安全策略限制，将无法通过 WebUI 直接完成认证。 --- # 零：配置详细解说 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/hands-on/tutorial-0#VPContent) 回到顶部 零：配置详细解说 [​](https://help.router-for.me/cn/hands-on/tutorial-0#%E9%9B%B6-%E9%85%8D%E7%BD%AE%E8%AF%A6%E7%BB%86%E8%A7%A3%E8%AF%B4) ================================================================================================================================= 这篇文章是对[CLIProxyAPI项目](https://github.com/router-for-me/CLIProxyAPI) 配置文件中各配置项的详细解读，供程序使用者有疑问时参阅 温馨提示：配置文件支持热重载，修改配置文件是即时生效的，不需要重启程序。 # 端口号，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:[email protected]: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" --- # 贰：Gemini CLI+Codex实战 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/hands-on/tutorial-2#VPContent) 回到顶部 贰：Gemini CLI+Codex实战 [​](https://help.router-for.me/cn/hands-on/tutorial-2#%E8%B4%B0-gemini-cli-codex%E5%AE%9E%E6%88%98) ========================================================================================================================= 在之前的文章中，我们通过在 CLIProxyAPI 上的简单配置，成功将 Qwen Code 转换成了 API 并在 Cherry Studio 中调用。相信读到这里的你，已经对这款工具的强大功能和便捷性有了初步认识。 在本篇教程中，我们将继续探讨，并把 Codex 和 Gemini CLI 也集成进来。 需要说明的是，本次操作所使用的配置文件与上一篇 Qwen 教程中的是同一个 yaml port: 8317 # 文件夹位置请根据你的实际情况填写 auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: # Key请自行设置，用于客户端访问代理 - "ABC-123456" ### 配置 Codex [​](https://help.router-for.me/cn/hands-on/tutorial-2#%E9%85%8D%E7%BD%AE-codex) 首先，我们来配置 Codex。Codex 的 OAuth 授权流程与之前的 Qwen 非常相似。在终端命令行中输入 `cli-proxy-api --codex-login`，系统会自动打开 ChatGPT 的授权页面，请使用你的 ChatGPT 账号登录。 ![](https://img.072899.xyz/2025/09/8d78b93fcfb3e111a93f6437f9a6acfa.png) 如果是 ChatGPT Team 账号，则需要选择对应的工作空间。授权成功的页面如下： ![](https://img.072899.xyz/2025/09/86518a31294a769281c7c5ef8946550e.png) 回到终端命令行，可以看到认证文件已成功生成并保存。 ![](https://img.072899.xyz/2025/09/c4c9613c9b086a9d8af70d0cf31d75f9.png) 如果你有多个 ChatGPT 账号，只需重复几次同样的操作即可。 需要注意的是，目前 Codex 需要付费的 ChatGPT 会员才能够使用，免费用户并没有权限哦。 ### 配置 Gemini CLI [​](https://help.router-for.me/cn/hands-on/tutorial-2#%E9%85%8D%E7%BD%AE-gemini-cli) 接下来，我们来添加 Gemini CLI。Gemini CLI 是完全免费的，但有些用户在配置过程中可能会遇到问题。因此，在这里我将从创建 Google Cloud 项目开始，一步步带你完成整个授权认证过程。 首先，请用你的 Google 账号登录 [https://console.cloud.google.com/。登录成功后，点击图中所示位置：](https://console.cloud.google.com/%E3%80%82%E7%99%BB%E5%BD%95%E6%88%90%E5%8A%9F%E5%90%8E%EF%BC%8C%E7%82%B9%E5%87%BB%E5%9B%BE%E4%B8%AD%E6%89%80%E7%A4%BA%E4%BD%8D%E7%BD%AE%EF%BC%9A) ![](https://img.072899.xyz/2025/09/75416d68babdacc8ddd9bfd652a49b38.png) 点击“新建项目”。 ![](https://img.072899.xyz/2025/09/566e57546c8bcd73d7ce41e56581b4a5.png) 给项目命名后，点击“创建”。 ![](https://img.072899.xyz/2025/09/9e90a699265fc1dcfb7755f7c1858b73.png) 按照第一步的位置，选择刚刚创建的项目。 ![](https://img.072899.xyz/2025/09/a84803f955e057f34723227bdf55b145.png) 先把红框内的项目 ID 复制下来备用，然后点击左上角箭头所指的位置。 ![](https://img.072899.xyz/2025/09/c1d1617812ecea50c3a63dfb76eb5c04.png) 依次点击“API和服务” -> “已启用的API和服务”。 ![](https://img.072899.xyz/2025/09/782d8096de6276f24fc8ca444ee2910d.png) 点击“启用API和服务”。 ![](https://img.072899.xyz/2025/09/1c0e48d7434bc76d37ef769d86684595.png) 在图示的搜索框内输入 `cloudaicompanion.googleapis.com`，然后点击搜索到的“Gemini for Google Cloud”。 ![](https://img.072899.xyz/2025/09/a52b17b80635df9e46b8d5b49957e3d6.png) 点击“启用”。 ![](https://img.072899.xyz/2025/09/58afcf1004138c4c1d63474030d49dff.png) 至此，Google Cloud 前期的准备工作就全部完成了。现在，我们回到 CLIProxyAPI 程序所在的目录，打开终端命令行，输入 `cli-proxy-api --login --project_id [你的项目ID]`。例如，在本例中就是 `cli-proxy-api --login --project_id mimetic-planet-473413-v7`。 随后会弹出授权页面，请使用刚才完成准备工作的 Google 账号登录。 ![](https://img.072899.xyz/2025/09/51ca74eb061751336d110b3421c43548.png) 验证成功的页面如下： ![](https://img.072899.xyz/2025/09/346f6add9a943f0c324afbad856cc3bf.png) 回到终端命令行，可以看到认证文件已被成功保存。 ![](https://img.072899.xyz/2025/09/8682dc8a08bffd34d7900819e1073960.png) 有些读者可能会好奇，为什么 Codex 和 Gemini CLI 在验证成功后的命令行信息，与 Qwen 有所不同？答案是，在验证 Codex 和 Gemini CLI 时，CLIProxyAPI 会在本地监听一个特定端口以接收回调，因此验证总是一次成功。而在验证 Qwen 时，CLIProxyAPI 会直接从 Qwen 的验证服务器来获取授权信息，因此最多会有 60 次的尝试请求。 ### 验证模型 [​](https://help.router-for.me/cn/hands-on/tutorial-2#%E9%AA%8C%E8%AF%81%E6%A8%A1%E5%9E%8B) 我们再来验证一下刚才通过 OAuth 添加的 Codex 和 Gemini CLI。在 Cherry Studio 中添加模型，如下所示： ![](https://img.072899.xyz/2025/09/db8e65c9548213303da43cc214ee5000.png) 试试 Gemini-2.5-Pro： ![](https://img.072899.xyz/2025/09/a2fc6ce45adcf334a2908984a8db428d.png) 再来问问 GPT-5-Codex： ![](https://img.072899.xyz/2025/09/c07a3dbd57f728186ad835fa5afdde6d.png) 至此，所有模型都已成功集成。你学会了吗？ --- # 伍：Docker服务器部署 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/hands-on/tutorial-5#VPContent) 回到顶部 伍：Docker服务器部署 [​](https://help.router-for.me/cn/hands-on/tutorial-5#%E4%BC%8D-docker%E6%9C%8D%E5%8A%A1%E5%99%A8%E9%83%A8%E7%BD%B2) =================================================================================================================================== 在之前的系列文章中，我们介绍了如何在本地电脑上使用 CLIProxyAPI。本文将更进一步，讲解如何在服务器上通过 Docker 完成部署。 ### **一、 环境准备** [​](https://help.router-for.me/cn/hands-on/tutorial-5#%E4%B8%80%E3%80%81-%E7%8E%AF%E5%A2%83%E5%87%86%E5%A4%87) 在开始之前，请确保你拥有一台可用的 VPS（虚拟专用服务器）。本文将以 **Debian 13** 系统为例进行演示。 同时，请确保你的服务器上已经安装了 **Git** 和 **Docker**。 如果尚未安装，可以通过以下命令进行安装： **1\. 安装 Git** bash apt update && apt install git -y **2\. 安装 Docker** 可以使用官方提供的一键脚本进行安装： bash bash <(curl -fsSL [https://get.docker.com](https://get.docker.com)) ### **二、 部署 CLIProxyAPI** [​](https://help.router-for.me/cn/hands-on/tutorial-5#%E4%BA%8C%E3%80%81-%E9%83%A8%E7%BD%B2-cliproxyapi) 准备工作就绪后，请依次执行以下命令来克隆项目并初始化配置。 bash git clone https://github.com/router-for-me/CLIProxyAPI.git cd CLIProxyAPI cp config.example.yaml config.yaml ![](https://img.072899.xyz/2025/09/60714b62a0f5b3ea896ab5461ecec150.png) 此时，我们可以打开 `config.yaml` 文件进行编辑。本教程将采用以下最小化配置作为示例： 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" > **请注意：** 当使用 Docker 部署时，建议保持 `auth-dir` 的默认设置，无需修改。 编辑完 `config.yaml` 文件后，我们执行以下命令来执行 Docker 容器构建脚本。 bash bash docker-build.sh 脚本会提供两个选项： ![](https://img.072899.xyz/2025/09/f0f543ef4004f3f81c029f442b54c8bc.png) * **选项 1：** 直接使用 Docker Hub 上的预构建镜像运行 (`docker compose up -d`)，速度快。 * **选项 2：** 在服务器本地编译镜像然后再运行，适合需要自定义修改的场景。 在本教程中，我们选择**选项 1**，以快速启动服务，稍待片刻，服务便成功启动了。 ![](https://img.072899.xyz/2025/09/44609a9a0746c138f570202bd2825366.png) ### **三、 查看日志** [​](https://help.router-for.me/cn/hands-on/tutorial-5#%E4%B8%89%E3%80%81-%E6%9F%A5%E7%9C%8B%E6%97%A5%E5%BF%97) 尽管脚本提示使用 `docker compose logs -f` 查看日志，但由于程序默认会将日志重定向到文件，因此**实时查看日志**需要使用以下命令： bash tail -f ./logs/main.log ### **四、 添加 OAuth 认证** [​](https://help.router-for.me/cn/hands-on/tutorial-5#%E5%9B%9B%E3%80%81-%E6%B7%BB%E5%8A%A0-oauth-%E8%AE%A4%E8%AF%81) 现在程序已经在正常运行了。如果需要添加中转 Key，只需按照之前文章介绍的方法编辑配置文件即可，这一次，我们重点讲解如何通过 OAuth 添加授权认证文件。 #### **步骤一：在服务器端生成认证链接** [​](https://help.router-for.me/cn/hands-on/tutorial-5#%E6%AD%A5%E9%AA%A4%E4%B8%80-%E5%9C%A8%E6%9C%8D%E5%8A%A1%E5%99%A8%E7%AB%AF%E7%94%9F%E6%88%90%E8%AE%A4%E8%AF%81%E9%93%BE%E6%8E%A5) 以添加 **Codex** 为例，请在项目根目录下执行以下命令： bash docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --codex-login 程序会生成一段用于建立 SSH 隧道的命令，请复制箭头处 `ssh` 开头的整段命令。 ![](https://img.072899.xyz/2025/09/42f152ef068cea1df603b29934b6e814.png) #### **步骤二：在本地建立 SSH 隧道** [​](https://help.router-for.me/cn/hands-on/tutorial-5#%E6%AD%A5%E9%AA%A4%E4%BA%8C-%E5%9C%A8%E6%9C%AC%E5%9C%B0%E5%BB%BA%E7%AB%8B-ssh-%E9%9A%A7%E9%81%93) 在**你自己电脑**的终端或命令行工具中，粘贴刚才复制的命令。 ![](https://img.072899.xyz/2025/09/1c27a2d2e3bc1ad823a040a50cb8e143.png) > **特别注意：** 需要将命令中 `-p` 参数后的端口号（示例中的 `22`）替换为你 VPS 的**实际 SSH 端口**。 回车后输入服务器的 SSH 登录密码。成功连接后，请保持此终端窗口不要关闭，然后回到刚才操作服务器的终端上。 ![](https://img.072899.xyz/2025/09/e25d23bc9b129cc9bbc6f4e1a674fed5.png) #### **步骤三：通过浏览器完成授权** [​](https://help.router-for.me/cn/hands-on/tutorial-5#%E6%AD%A5%E9%AA%A4%E4%B8%89-%E9%80%9A%E8%BF%87%E6%B5%8F%E8%A7%88%E5%99%A8%E5%AE%8C%E6%88%90%E6%8E%88%E6%9D%83) 复制服务器终端上箭头指向的链接 ![](https://img.072899.xyz/2025/09/5ddcbc39551201f61b906703034af3d8.png) 在你本地电脑的浏览器中打开这个链接，用你的 ChatGPT 账号登录并授权 ![](https://img.072899.xyz/2025/09/a4ed389a080bce529c47bda6f3129189.png) 授权成功后，会看到如下画面： ![](https://img.072899.xyz/2025/09/507c93b6fc900eae5c6c5b486b399561.png) 同时，服务器的终端上也会显示认证文件已成功保存 ![](https://img.072899.xyz/2025/09/a34bb04a63f7f75f687a2a626035dccd.png) 至此，Codex 的认证就全部完成了。对于 Gemini-CLI 和 Claude 等其他需要 OAuth 授权的服务，操作流程完全相同。 ### **五、 原理总结** [​](https://help.router-for.me/cn/hands-on/tutorial-5#%E4%BA%94%E3%80%81-%E5%8E%9F%E7%90%86%E6%80%BB%E7%BB%93) 最后，我们来总结一下这个远程 OAuth 认证流程的原理： Gemini-CLI、Claude 和 Codex 的 OAuth 认证都需要一个“回调”（Callback）过程来接收授权令牌。由于安全限制，服务商的回调地址通常强制设置为 `localhost`。 当我们在 Docker 容器中执行授权命令时，容器内没有浏览器环境，我们必须在本地电脑上打开授权网页。但授权成功后，浏览器会尝试访问 `localhost`，这只会访问到我们自己的电脑，而无法将令牌传递给远在服务器上的程序。 **SSH 隧道（SSH Tunnel）** 的作用就是搭建一座桥梁：它将我们本地电脑的某个端口（例如 `1455`）上的所有网络请求，通过加密的 SSH 连接，转发到服务器的同一端口上。这样，当浏览器访问本地的 `http://localhost:1455` 时，请求实际上被转发给了服务器上正在监听 `1455` 端口的 CLIProxyAPI 程序，从而巧妙地完成了远程认证。 作为 SSH Tunnel 的替代方案，你也可以在浏览器跳转到 `localhost` 回调链接时，手动将其中的 `localhost` 替换为你服务器的 IP 或域名。不过，请注意，这种方法需要你正确配置服务器的防火墙或反向代理，以确保回调请求能够被正确接收，否则可能会认证失败。 ### **六、 客户端使用** [​](https://help.router-for.me/cn/hands-on/tutorial-5#%E5%85%AD%E3%80%81-%E5%AE%A2%E6%88%B7%E7%AB%AF%E4%BD%BF%E7%94%A8) 完成以上配置后，在客户端使用时，只需将请求的端点（Endpoint）地址指向你服务器的 `IP:端口`（例如 `http://YOUR_SERVER_IP:8317`）即可，其余操作与本地使用完全相同。 至此，你已经掌握了在服务器上通过 Docker 部署 CLIProxyAPI 的完整流程，快去享受 AI 带来的便利吧！ --- # 肆：中转转发接入篇 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/hands-on/tutorial-4#VPContent) 回到顶部 肆：中转转发接入篇 [​](https://help.router-for.me/cn/hands-on/tutorial-4#%E8%82%86-%E4%B8%AD%E8%BD%AC%E8%BD%AC%E5%8F%91%E6%8E%A5%E5%85%A5%E7%AF%87) =========================================================================================================================================== 在前几篇文章中，我们已经成功通过 OAuth 或 Cookie 方式接入了 Qwen、Codex、Gemini CLI 和 Gemini Web。在本篇教程中，我们将更进一步，学习如何便捷地将各类 AI 中转服务接入 CLIProxyAPI。 首先，让我们回顾一下之前使用的配置文件： yaml port: 8317 # 文件夹位置请根据你的实际情况填写 auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: # Key请自行设置，用于客户端访问代理 - "ABC-123456" 初次配置后，我们一直没有改动过它。现在，是时候对这个文件进行一些扩展了。 我们先来添加一个 Claude 的中转服务。为此，我们首先需要获取该服务的 `base-url`，这个地址通常可以在相应服务商的官方文档或教程中找到。 以 88code 为例，在其官方教程中可以找到如下信息： ![](https://img.072899.xyz/2025/09/11c41d79d62c02df1ac5d5998c75d3e5.png) 从图中可以获知，88code 中转 Claude 服务的 `base-url` 是 `https://www.88code.org/api`。 我们在配置文件中加入 `claude-api-key` 字段： yaml port: 8317 auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: - "ABC-123456" claude-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/api" 同样地，88code 也提供了 Codex 服务。我们依照相同的方法，找到其 `base-url`： ![](https://img.072899.xyz/2025/09/28e5ce297bca540e052863860dd9eb2c.png) 然后，在配置文件中添加 `codex-api-key` 字段： yaml port: 8317 auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: - "ABC-123456" claude-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/api" codex-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/openai/v1" 对于其他服务商，也可以采用类似的方式进行添加。例如，我这里还有几个 PackyCode 的 Codex API Key，我将它们一并加入配置： yaml port: 8317 auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: - "ABC-123456" claude-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/api" - api-key: "sk-4cXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://api.packycode.com" - api-key: "sk-HpYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY" base-url: "https://api.packycode.com" codex-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/openai/v1" - api-key: "fk-4cXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://oai-api.fkclaude.com/v1" - api-key: "sk-amXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://codex-api.packycode.com/v1" - api-key: "sk-sTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://codex-api.packycode.com/v1" 请注意，即使是同一服务商、使用相同 `base-url` 的多个 `api-key`，也需要为每一条 `api-key` 单独声明 `base-url`，不可省略。 此外，CLIProxyAPI 还支持接入任何兼容 OpenAI 接口的供应商，这需要通过 `openai-compatibility` 字段来配置。在此不再赘述具体步骤，大家可以直接参考下方的配置文件示例进行配置： yaml port: 8317 auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: - "ABC-123456" claude-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/api" codex-api-key: - api-key: "88_XXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://www.88code.org/openai/v1" - api-key: "fk-4cXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://oai-api.fkclaude.com/v1" - api-key: "sk-amXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://codex-api.packycode.com/v1" - api-key: "sk-sTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" base-url: "https://codex-api.packycode.com/v1" openai-compatibility: - name: "openrouter" base-url: "https://openrouter.ai/api/v1" api-keys: - "sk-or-v1-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" - "sk-or-v1-bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" models: - name: "deepseek/deepseek-chat-v3.1:free" alias: "deepseek-v3.1" - name: "deepseek/deepseek-r1-0528:free" alias: "deepseek-r1-0528" - name: "x-ai/grok-4-fast:free" alias: "grok-4-fast" - name: "groq" base-url: "https://api.groq.com/openai/v1" api-keys: - "gsk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" models: - name: "deepseek-r1-distill-llama-70b" alias: "deepseek-r1-70b" 可以看到，`openai-compatibility` 的配置逻辑与之前略有不同：同一供应商（Provider）下的所有 `api-key` 共享同一个 `base-url`。 至此，配置就完成了。剩下的模型连通性验证，就留给各位读者自行测试了。 --- # 零成本部署：HuggingFace (数据库存储) | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/hands-on/tutorial-8#VPContent) 回到顶部 零成本部署：HuggingFace (数据库存储) [​](https://help.router-for.me/cn/hands-on/tutorial-8#%E9%9B%B6%E6%88%90%E6%9C%AC%E9%83%A8%E7%BD%B2-huggingface-%E6%95%B0%E6%8D%AE%E5%BA%93%E5%AD%98%E5%82%A8) ========================================================================================================================================================================================= 在《没有VPS？》系列的前几篇文章中，我们分别探讨了如何利用本地卷 (ClawCloud)、GitHub (Render) 及对象存储桶 (Railway) 为 CLIProxyAPI 实现配置与认证信息的持久化。本文将聚焦于如何通过 PostgreSQL 数据库达成同样的目标。此外，考虑到 HuggingFace 的容器部署机制与常规平台有所不同，且有朋友希望了解其部署流程，本文将一并进行详细说明。 本教程将以 Railway 提供的 PostgreSQL 服务为例，使用其他数据库提供商的流程也大同小异，大家可自行探索。 ### 一、准备 PostgreSQL 数据库 [​](https://help.router-for.me/cn/hands-on/tutorial-8#%E4%B8%80%E3%80%81%E5%87%86%E5%A4%87-postgresql-%E6%95%B0%E6%8D%AE%E5%BA%93) 首先，登录你的 Railway 账号，在工作空间中创建一个新实例，选择 **Database** -> **Add PostgreSQL** ![](https://img.072899.xyz/2025/10/dab21cb1671989f6781eed1eba03c985.png) ![](https://img.072899.xyz/2025/10/9580732f1e15d365db8a3dd07442b3fd.png) 等待实例创建完成后，点击进入数据库管理页面，点击 **Database** 选项卡下的 **Connect** ![](https://img.072899.xyz/2025/10/f177a3cc1cb30146d9b16475179fd5f0.png) 请复制并保存 **Public Network** 选项卡下的 **Connection URL**，后续步骤将会用到 ![](https://img.072899.xyz/2025/10/107a359a8a490b18a325779432a71582.png) ### 二、在 HuggingFace 上部署 [​](https://help.router-for.me/cn/hands-on/tutorial-8#%E4%BA%8C%E3%80%81%E5%9C%A8-huggingface-%E4%B8%8A%E9%83%A8%E7%BD%B2) 首先，请访问我预先建立好的 [CLIProxyAPI 项目模板](https://huggingface.co/spaces/hkfires/CLIProxyAPI) ，然后如下图所示，点击下拉菜单中的 **Duplicate this Space** 来复制项目 ![](https://img.072899.xyz/2025/10/0febf3a57ae4f8384dfff6d6e38614ce.png) 在配置页面中，请按以下说明操作： * 修改 **Space name**（如果这是你的第一个项目，则无需修改） * 将 **Visibility** 设置为 **Public**，以确保服务部署后能够远程访问 * 在 `MANAGEMENT_PASSWORD` 中填入你计划用于 WebUI 的管理密码 * 在 `PGSTORE_DSN` 中粘贴先前复制的数据库连接 URL 全部信息填写完毕后，点击 **Duplicate Space** > **补充说明**：`MANAGEMENT_STATIC_PATH` 与 `PGSTORE_LOCAL_PATH` 这两个环境变量之所以需要设置为 `/tmp`，是因为 HuggingFace 的安全机制将容器的根目录设置为只读权限。通过这两个变量，我们可以将数据库缓存文件和管理页面静态资源的路径指向可写的 `/tmp` 目录，从而确保程序正常运行。 ![](https://img.072899.xyz/2025/10/a4b88ee81e6eefd0721b301c9bc4f5e8.png) 稍等片刻，当你在日志中看到类似下方的信息时，即表示部署已顺利完成 ![](https://img.072899.xyz/2025/10/98550ed355e70b9776498558bd6c599a.png) 此时，你便可以通过 `https://<你的HuggingFace用户名>-<项目名称>.hf.space/management.html` 访问 WebUI。例如，我的访问地址是 `https://hkfires-cliproxyapi.hf.space/management.html`。输入你先前在环境变量中设定的管理密码即可成功登录 ![](https://img.072899.xyz/2025/10/e8fa8144c51bfc6125a8cb218cf528dd.png) 至此，整个部署流程便已完成。关于后续的使用方法，你可以参考《零成本部署（ClawCloud）》教程中的 **“使用 EasyCLI 进行远程 OAuth 认证”** 部分。 --- # 零成本部署：Railway (对象存储) | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/hands-on/tutorial-9#VPContent) 回到顶部 零成本部署：Railway (对象存储) [​](https://help.router-for.me/cn/hands-on/tutorial-9#%E9%9B%B6%E6%88%90%E6%9C%AC%E9%83%A8%E7%BD%B2-railway-%E5%AF%B9%E8%B1%A1%E5%AD%98%E5%82%A8) ======================================================================================================================================================================= 继《没有VPS？》系列前两篇文章之后，我又尝试了一些容器云。恰逢 CLIProxyAPI 程序增加了对 S3 存储桶的支持，因此本文将介绍一种全新的组合：使用 Railway 容器服务并搭配 ClawCloud S3 存储桶进行部署。 在开始之前，请确保你已拥有 [ClawCloud](https://run.claw.cloud/) 和 [Railway](https://railway.com/) 的账号。 ### 一、创建 ClawCloud 存储桶 [​](https://help.router-for.me/cn/hands-on/tutorial-9#%E4%B8%80%E3%80%81%E5%88%9B%E5%BB%BA-clawcloud-%E5%AD%98%E5%82%A8%E6%A1%B6) 登录 ClawCloud 后，点击进入 **Object Storage** ![](https://img.072899.xyz/2025/10/8350104852042e43ba4c3dad25fd0004.png) 接着，点击 **Create bucket** ![](https://img.072899.xyz/2025/10/9f5953f5a406a21d2ff914cfa01638c9.png) 输入一个自定义的存储桶名称（名称要求小写），然后点击右上角的 **Create** ![](https://img.072899.xyz/2025/10/39db7fd3e8ca4a57c46191be889e0f15.png) 至此，存储桶便已创建完成。接下来，我们需要记录以下 4 个关键参数：存储桶全名（图中红框所示）、Access Key、Secret Key 以及 External 地址 ![](https://img.072899.xyz/2025/10/ef6c22c9cc50eee9152e4c95454786dd.png) ![](https://img.072899.xyz/2025/10/a3931df797a65db7afecf18cb66e66ce.png) 这 4 个参数将分别用于设置环境变量。此外，我们还需额外设定一个 `MANAGEMENT_PASSWORD`（用于登录 WebUI 的密码）。请将这些信息整理为以下格式并妥善保存： OBJECTSTORE_ENDPOINT=External值 OBJECTSTORE_ACCESS_KEY=Access Key值 OBJECTSTORE_SECRET_KEY=Secret Key值 OBJECTSTORE_BUCKET=存储桶全称 MANAGEMENT_PASSWORD=访问WebUI的密码 ### 二、Railway 手动部署 [​](https://help.router-for.me/cn/hands-on/tutorial-9#%E4%BA%8C%E3%80%81railway-%E6%89%8B%E5%8A%A8%E9%83%A8%E7%BD%B2) 在 Railway 的项目仪表盘中，点击 **Create**，选择 **Docker image** ![](https://img.072899.xyz/2025/10/f9dfb05a9991e5a228fa18629168588c.png) 输入 `eceasy/cli-proxy-api:latest` 后按回车键。稍等片刻，工作区内便会出现一个新的容器 ![](https://img.072899.xyz/2025/10/dec39863e684dd39f63acd1ebbe401e9.png) 点击这个新创建的容器，在右侧面板中选择 **Variables** -> **Raw Editor** ![](https://img.072899.xyz/2025/10/d3d5d5b5144d2016ff4d8ddf8953a819.png) 将我们先前准备好的环境变量粘贴进去，然后点击 **Update Variables** ![](https://img.072899.xyz/2025/10/accaf8ea92a57371cf1d1994be59cd9f.png) 点击 **Deploy** 按钮开始部署 ![](https://img.072899.xyz/2025/10/6889a73eb138f8e1dca7ab0fb4b79b21.png) 等待部署完成（出现 "Deployment successful" 提示）后，点击进入 **Settings** 标签页 ![](https://img.072899.xyz/2025/10/a1059beca1671b505b4909c36ae51f68.png) 在 **Public Networking** 部分，点击 **Generate Domain** ![](https://img.072899.xyz/2025/10/e3d3efbcc34db844c81ee1eefda48e22.png) 将端口号设置为 `8317`，然后点击 **Generate Domain** ![](https://img.072899.xyz/2025/10/6ddb5ee7884c2c239b02edca10ca2668.png) 此时，Railway 会为你生成一个公开访问地址，通过该地址即可访问 CLIProxyAPI 的 WebUI 界面了，能够打开网页，就算部署成功了 ![](https://img.072899.xyz/2025/10/d216af36328e62147889108799278561.png) ### 三、Railway 模板部署 [​](https://help.router-for.me/cn/hands-on/tutorial-9#%E4%B8%89%E3%80%81railway-%E6%A8%A1%E6%9D%BF%E9%83%A8%E7%BD%B2) 此外，Railway 也支持通过模板一键部署。你可以直接点击下方按钮开始（注：此链接包含AFF） [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/0uGPyR?referralCode=JC4tEx&utm_medium=integration&utm_source=template&utm_campaign=generic) 若使用模板部署，请注意，在部署完成后需要确认服务端口是否为 `8317`。不是的话需要自己手动修改，具体修改步骤如下图所示： ![](https://img.072899.xyz/2025/10/e741f1f62e4726a16e75b1264ad4438e.png) ![](https://img.072899.xyz/2025/10/ba2c7d7bac37b3bcdd3aebb220c6fb0b.png) ![](https://img.072899.xyz/2025/10/39b49aea18026f80834bf0ee22d405a3.png) 至此，全部部署流程均已完成。后续使用方法可参照《零成本部署（ClawCloud）》教程中的 **“使用 EasyCLI 进行远程 OAuth 认证”** 部分。 **补充说明**：除了 ClawCloud，任何兼容 S3 API 的对象存储服务（如 Cloudflare R2）理论上都可以作为替代方案。 --- # 零成本部署：ClawCloud (自带存储) | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/hands-on/tutorial-7#VPContent) 回到顶部 零成本部署：ClawCloud (自带存储) [​](https://help.router-for.me/cn/hands-on/tutorial-7#%E9%9B%B6%E6%88%90%E6%9C%AC%E9%83%A8%E7%BD%B2-clawcloud-%E8%87%AA%E5%B8%A6%E5%AD%98%E5%82%A8) =========================================================================================================================================================================== 前段时间，我发了一篇文章《伍：Docker服务器部署》，许多网友反馈由于没有VPS，希望我能提供一个在容器云上部署的教程。 实际上，`CLIProxyAPI` 既然支持 Docker 部署，自然也能无缝地在容器云上运行。但若将其直接运行在容器云上，会存在以下两个主要问题： * **配置文件持久化**：对于程序启动所需的配置文件，容器云往往是通过把配置文件内容映射到特定文件来解决，虽然可以运行，但如果你对配置文件做过修改，一旦容器重启，所有变更都会丢失。这种配置丢失的情况是我们不能接受的。 * **OAuth 认证复杂**：对于需要 OAuth 认证的供应商，在 VPS 的 Docker 环境下，我们可以通过 SSH 隧道将认证回调结果转发到服务器上。而纯容器云环境通常不支持 SSH 隧道，需要通过添加多个端口并在回调时手动修改域名来完成，整个过程非常繁琐。 因此，在 `CLIProxyAPI` 对容器云的部署进行适配更新后，本教程将一步步指导你如何在容器云上完成部署。 本次教程演示使用的容器云平台是 [ClawCloud Run](https://run.claw.cloud/) 。在该平台使用注册时长超过180天的 Github 账号登录，即可获得每月5美元的循环额度。我们部署的 `CLIProxyAPI` 每天仅消耗约0.05美元，这个额度绰绰有余。其他容器云平台基本上大同小异，请参考该流程自行部署。 登录 ClawCloud Run 之后，我们点击 **App Launchpad** ![](https://img.072899.xyz/2025/10/080dfe9fd2c214ff9e507bd4d2bd5caa.png) 点击 **Create APP** ![](https://img.072899.xyz/2025/10/d44ca8835fac8cfc6b7a82a3ea4d95c9.png) 首先我们填写基础信息 * **应用名称 (Application Name)**：可自定义，此处填写 `cliproxyapi` * **镜像名称 (Image Name)**：`eceasy/cli-proxy-api:latest` * **网络 (Network)**：容器端口修改为 `8317`，同时打开 **Public Access** ![](https://img.072899.xyz/2025/10/1a4941e799911d181d658de450f6e5d7.png) 页面向下拉动，在高级设置中，我们需要填写： * **启动命令 (Command)**：`/CLIProxyAPI/CLIProxyAPI --config /data/config.yaml` * **环境变量 (Environment Variables)**：`DEPLOY=cloud` * **持久化存储 (Local Storage)**：`/data` ![](https://img.072899.xyz/2025/10/3370f4146f19e92087f188dac5184575.png) 环境变量和存储的填写方法参看下图 | ![](https://img.072899.xyz/2025/10/e854143ef56bd6a71a922cad921c08b2.png) | ![](https://img.072899.xyz/2025/10/d966536ab7dd785ffc36355fdb2536cc.png) | | --- | --- | 确认所有信息填写无误后，点击右上角的 **Deploy Application**，应用将开始部署 ![](https://img.072899.xyz/2025/10/dc49813c993e84e68af74747332b247b.png) 稍等片刻，应用即可部署成功。当 **Public Address** 状态变为 **Available** 时，其对应的就是我们访问 `CLIProxyAPI` 的网址，请保存备用 ![](https://img.072899.xyz/2025/10/6502f6ce1d9a4f63c132966ae9c37064.png) 在等待部署的过程中，我们可以先准备 `config.yaml` 配置文件。本次使用的示例如下，请注意：`remote-management.secret-key` 是远程管理的密钥，而 `api-keys` 是 AI 客户端连接 `CLIProxyAPI` 所使用的密钥，要注意区分 yaml port: 8317 remote-management: allow-remote: true secret-key: "ABCD-1234" disable-control-panel: false auth-dir: "/data/auths" debug: false logging-to-file: false usage-statistics-enabled: false request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: - "EFGH-5678" 当容器状态变为 **Active** 之后 ![](https://img.072899.xyz/2025/10/99cce03e91ceb4eca44b8a055d0b874a.png) 我们点击图中的按钮，打开之前添加的 **Local Storage** ![](https://img.072899.xyz/2025/10/6ce689a58a74037594e31f5d8e587af7.png) 点击右上角的 **Upload**，选择刚才准备好的 `config.yaml` 文件并上传 ![](https://img.072899.xyz/2025/10/d550a6d94c9a5f02852e2f12091ff2a0.png) 上传完成后，点击 **Restart** 重启容器 ![](https://img.072899.xyz/2025/10/e4e4e077371cff0f77d097ccf9b07da6.png) 稍等片刻，待容器状态再次变为 **Active** 后，我们可以看到 **Local Storage** 中已生成了新的文件 ![](https://img.072899.xyz/2025/10/877144ceae6bdc3acc180f18e309c9ef.png) 同时，点击 **Logs** 标签页，可以看到如下图所示的日志信息 ![](https://img.072899.xyz/2025/10/5da47dbaaace9befc61d18ffcca5298a.png) ![](https://img.072899.xyz/2025/10/af2ed8594a0626ca24dcf3427ff2e103.png) 至此，`CLIProxyAPI` 便成功完成了整个部署流程。 * * * **使用 EasyCLI 进行远程 OAuth 认证** 接下来，我们使用官方的另一个项目 [EasyCLI](https://github.com/router-for-me/EasyCLI) 来进行远程 OAuth 添加。 `EasyCLI` 是 `CLIProxyAPI` 的配套项目，提供了一个图形用户界面（GUI）来管理 `CLIProxyAPI`。其最大亮点是支持完整的 OAuth 认证授权流程（不仅是上传授权文件，而是能处理整个授权回调过程），这是 `CLIProxyAPI` 自带的 WebUI 无法做到的。 请前往 [EasyCLI 程序发布页面](https://github.com/router-for-me/EasyCLI/releases) 下载适合你操作系统的版本（作者提供了 Mac、Linux、Windows 版本）。本教程以 Windows x64 版本为例。 打开程序后，选择 **Remote**，输入我们之前记录下的 URL 网址 ![](https://img.072899.xyz/2025/10/f1d6dce519e20cae93abaac261f4d269.png) 密码输入 `config.yaml` 中设置的 `remote-management.secret-key`（本例中是 `ABCD-1234`） 依次点击 **Authentication Files** -> **New** ![](https://img.072899.xyz/2025/10/00cbb95dfeab2b8047b8270292fbe2cc.png) 本次我们仍以添加 Gemini CLI 为例进行演示，准备工作可参照《贰：Gemini CLI+Codex实战》 输入 **Project ID**，点击 **Confirm** ![](https://img.072899.xyz/2025/10/994a104817d51e39f811ad190d6190d5.png) 页面中会出现 OAuth 链接，点击 **Open Link** ![](https://img.072899.xyz/2025/10/361f9b6568609e589c959ca572de8955.png) 程序会自动打开浏览器并跳转到 OAuth 链接，同时 `EasyCLI` 自身会进入回调接收状态 ![](https://img.072899.xyz/2025/10/a10dab06835d7bc5d15af8cc1ca607ed.png) 在打开的浏览器页面中，我们登录账号并完成授权认证过程 ![](https://img.072899.xyz/2025/10/d1dc0fe737eb8b0ce9f348f2f45871f1.png) 完成后，在 **Authentication Files** 列表中就可以看到新生成的配置文件了 ![](https://img.072899.xyz/2025/10/d713a77479b41f4035f1bf66b2e538f6.png) **验证** 我们再用 Cherry Studio 测试一下。如图所示，根据配置文件内容填写 API 密钥和 API 地址 ![](https://img.072899.xyz/2025/10/8021ac702f232ded423b186dbcb50a90.png) 成功！ ![](https://img.072899.xyz/2025/10/5d0684f8cfecb1bc503f5189822911a3.png) `EasyCLI` 的其余功能就交给各位自行探索了。实际上，除了 OAuth 认证部分，`EasyCLI` 的其他功能与系统内置的 WebUI 基本一致。你也可以通过访问 `https://你的CLIProxyAPI访问链接/management.html` 来进行其他配置管理（关于 WebUI 的介绍可参考这篇文章《陆：新人最爱GUI》，虽然介绍也相对简短=。=） --- # 零成本部署：Render (Git存储) | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/hands-on/tutorial-10#VPContent) 回到顶部 零成本部署：Render (Git存储) [​](https://help.router-for.me/cn/hands-on/tutorial-10#%E9%9B%B6%E6%88%90%E6%9C%AC%E9%83%A8%E7%BD%B2-render-git%E5%AD%98%E5%82%A8) ======================================================================================================================================================== 在昨天的文章《零成本部署（ClawCloud）》发布后，我接着测试了 Render 平台，发现其免费计划不包含持久化存储。在将此情况反馈给 CLIProxyAPI 的作者后，他连夜更新了版本，新增了通过 Git 进行持久化存储的功能。这样一来，我们便能将配置文件和认证文件保存在 GitHub 的私有仓库中，不需要依赖容器云的持久化存储了。 接下来，本文将一步步地指导你如何在没有持久化存储的容器服务（例如 Render 的免费计划）上部署 CLIProxyAPI。至于通过 EasyCLI 进行 OAuth 认证的部分，与在 ClawCloud 上的部署完全一致，请参阅前一篇文章。 ### 一、Github 准备工作 [​](https://help.router-for.me/cn/hands-on/tutorial-10#%E4%B8%80%E3%80%81github-%E5%87%86%E5%A4%87%E5%B7%A5%E4%BD%9C) 首先，我们需要在 GitHub 上创建一个空的仓库。仓库名称可自定义，但**务必**设为**私有**，否则你添加的 API Key 等敏感信息就会裸奔了 ![](https://img.072899.xyz/2025/10/311e26cb4da97cafd7bb3b924440e858.png) 创建仓库后，记下仓库的 URL 地址。接下来我们点击页面右上角的个人头像，进入 **Settings**，然后点击左侧菜单最下方的 **Developer Settings** ![](https://img.072899.xyz/2025/10/a79377c7af3c80ec58ad853d12762b6c.png) 接着，依次点击 **Personal access tokens** -> **Fine-grained tokens**，然后点击右上角的 **Generate new token** ![](https://img.072899.xyz/2025/10/90fa44065df641c7599b8d16e84edf60.png) 如图所示填写 **Token name**（可自定义），根据你的需求选择过期时间（**Expiration**），并在 **Repository access** 中选择 **Only select repositories**，然后选中我们刚刚创建的那个空白仓库 ![](https://img.072899.xyz/2025/10/74b5484e44a28293335160a9d42bb190.png) 将页面向下拉动，在 **Permissions** -> **Add permissions** 中找到 **Contents**，添加并将其权限从 `Read-only` 修改为 `Read and write` ![](https://img.072899.xyz/2025/10/825aafe9f3a52fc431a3ec54829777de.png) 确认权限设置无误后，点击页面底部的 **Generate token** ![](https://img.072899.xyz/2025/10/0b5f56df634cea1e3552b8560c7f175a.png) 此时页面上会显示生成的 Token。请注意，**此 Token 仅会显示一次**，页面关闭后将无法查看，请务必复制并妥善保存 ![](https://img.072899.xyz/2025/10/a04fc4a6a75cab2222ba28d46e4463e9.png) 至此，GitHub 的准备工作就完成了。 ### 二、Render 部署 [​](https://help.router-for.me/cn/hands-on/tutorial-10#%E4%BA%8C%E3%80%81render-%E9%83%A8%E7%BD%B2) 首先，请确保你已注册 Render 账户。登录后，新建项目并选择 **New Web Service** ![](https://img.072899.xyz/2025/10/0398d8d1483fe65d556727ec23075eaf.png) 在部署方式中选择 **Existing Image**，在 **Image URL** 中输入 `eceasy/cli-proxy-api:latest`，然后点击 **Connect** ![](https://img.072899.xyz/2025/10/4ee784242be93bee942f0eea64d51af5.png) 输入服务名称（**Name**，可自定义），选择区域（**Region**，可根据个人偏好选择），并确保实例类型为 **Free** ![](https://img.072899.xyz/2025/10/90d6fb2b4a5d401d02a917f82396c304.png) 接下来，我们需要添加 4 个环境变量： * `GITSTORE_GIT_URL`: 你的 GitHub 仓库地址 * `GITSTORE_GIT_USERNAME`: 你的 GitHub 用户名 * `GITSTORE_GIT_TOKEN`: 你刚刚创建的 Personal Access Token * `MANAGEMENT_PASSWORD`: 用于登录管理界面的密码 输入完成后，点击页面底部的 **Deploy Web Service** ![](https://img.072899.xyz/2025/10/d4b39d6e4f10a19ada98e4af0e505df9.png) 等待部署日志滚动，当状态变为 **Live** 时，并且日志中出现`Available at your primary URL：XXXX`之后，程序就成功启动了 ![](https://img.072899.xyz/2025/10/f77a35fa4f805e78fbcff663c6cf5aae.png) 使用 Render 提供的 URL，在其后添加 `/management.html`，即可进入 WebUI。输入你设定的 `MANAGEMENT_PASSWORD` 即可登录 ![](https://img.072899.xyz/2025/10/af84a3b0d2cc0197f2b4ecb3497c802e.png) 此时再查看你的 GitHub 仓库，会发现里边已自动生成了两个文件夹 ![](https://img.072899.xyz/2025/10/03bbde6090e53ae3362a624badd35319.png) 至此，在 Render 上部署 CLIProxyAPI 的全流程已完成。其他类似的容器云平台也可采用此方法进行部署，大家可自行探索。 ### 三、注意事项 [​](https://help.router-for.me/cn/hands-on/tutorial-10#%E4%B8%89%E3%80%81%E6%B3%A8%E6%84%8F%E4%BA%8B%E9%A1%B9) 1. CLIProxyAPI 在 v6.2.2 之后才新增了这个功能，如果你想指定镜像版本的话，选择的版本至少为`eceasy/cli-proxy-api:v6.2.2`。 2. 使用此方式部署后，配置文件中的 `remote-management` 部分将不再生效，管理密码以环境变量为准。这意味着，若要修改管理密码，你需要直接修改环境变量 `MANAGEMENT_PASSWORD`。 3. 使用 GitHub 存储配置文件和认证文件，不代表可以在多个容器实例中同时共享和调用，请务必避免这种情况，以免发生冲突。 4. 请注意，当容器正在运行时，直接在 GitHub 仓库中所做的任何手动更改都将是无效的。如确需手动修改，请务必先停止容器服务。 5. 推荐使用 WebUI 或 EasyCLI 来管理配置。使用 EasyCLI 还能进行 OAuth 的远程认证，具体方法可参考本文开头提到的《零成本部署（ClawCloud）》中的相关内容。 --- # 零成本部署AIStudio反代 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/hands-on/tutorial-11#VPContent) 回到顶部 零成本部署AIStudio反代 [​](https://help.router-for.me/cn/hands-on/tutorial-11#%E9%9B%B6%E6%88%90%E6%9C%AC%E9%83%A8%E7%BD%B2aistudio%E5%8F%8D%E4%BB%A3) ================================================================================================================================================ > **请注意：** 本教程的部署方案需配合 `CLIProxyAPI` 使用。在开始之前，请确保你已有一个正在运行的 `CLIProxyAPI` 实例。 CLIProxyAPI 自 v6.3.x 版本起，开始支持通过 WebSocket 方式接入 AI Provider，并首个支持了 AIStudio。 然而，这种方式需要一个始终开启的浏览器来运行 AIStudioBuild 上的 WebSocket 通信程序，这总归有些不便。如果选择将其部署在 VPS 上，又会面临 VPS 内存要求较高的问题。 为了解决这个问题，我花了点时间尝试多种无头浏览器方案。最终，我选择使用 Docker 在 HuggingFace 上进行部署，此举能充分利用 HuggingFace 免费实例的大内存优势，实现零成本部署。 ### 第一步：配置 AIStudioBuild 应用 [​](https://help.router-for.me/cn/hands-on/tutorial-11#%E7%AC%AC%E4%B8%80%E6%AD%A5-%E9%85%8D%E7%BD%AE-aistudiobuild-%E5%BA%94%E7%94%A8) 需要根据你的 `CLIProxyAPI` 的设置，配置好 AIStudioBuild 上的 WebSocket 通信程序：打开官方提供的[示例程序](https://aistudio.google.com/apps/drive/1CPW7FpWGsDZzkaYgYOyXQ_6FWgxieLmL) ，复制该程序后**需**修改图中红框处的两个地方。其中，如果 `CLIProxyAPI` 中设置了 `wsauth` 为 `true`，那么就需要设置 `JWT_TOKEN`为 `CLIProxyAPI` 中的拟用于鉴权的 `api-keys` 值；设置 `WEBSOCKET_PROXY_URL` 为 `CLIProxyAPI` 所在的地址，例如：`wss://mycap.example.com/v1/ws`。设置完成后保存，并记录这个应用的链接备用。 ![](https://img.072899.xyz/2025/11/359a2572d0206c20dba7fe12a136d6e8.png) 多账户使用时，需要多操作一个步骤，将该应用访问权限设置为 `Public`。 ![](https://img.072899.xyz/2025/11/69c6395d1a98c38c68bc6c8dd46b3014.png) **安全警告：** 设置为 `Public` 后，请务必妥善保管你的链接。**切勿**将此链接公开分享，以免导致授权信息泄露。 ### 第二步：准备 AIStudio Cookie [​](https://help.router-for.me/cn/hands-on/tutorial-11#%E7%AC%AC%E4%BA%8C%E6%AD%A5-%E5%87%86%E5%A4%87-aistudio-cookie) 这一步推荐使用浏览器的隐私模式，登录 [https://aistudio.google.com/](https://aistudio.google.com/) ，在浏览器的开发者工具中复制 Cookie 即可，具体位置如下图所示： ![](https://img.072899.xyz/2025/11/51f860bf363cab01aa4c3fd5181b7f72.png) ### 第三步（1）：部署 HuggingFace Space [​](https://help.router-for.me/cn/hands-on/tutorial-11#%E7%AC%AC%E4%B8%89%E6%AD%A5-1-%E9%83%A8%E7%BD%B2-huggingface-space) 打开 [https://huggingface.co/spaces/hkfires/AIStudioBuildWS](https://huggingface.co/spaces/hkfires/AIStudioBuildWS) ，复制该 Space。在 `CAMOUFOX_INSTANCE_URL` 处填入第一步准备的程序的链接，在 `USER_COOKIE_1` 处填入第二步准备的 Cookie，点击 Duplicate Space。 ![](https://img.072899.xyz/2025/11/04e84ce3b0f2abe7ae9e717ac8b5aa0b.png) 等待 HuggingFace 构建完成，出现如下日志，即部署成功： ![](https://img.072899.xyz/2025/11/e818f38cfb272c1fc10ca97c2ef23c6b.png) 如果有多个账户，参考 `USER_COOKIE_1`，在 HuggingFace Space 的设置中依次增加 `USER_COOKIE_2`、`USER_COOKIE_3` 等环境变量即可。 **重要提醒：** Cookie 属于敏感信息，请**务必使用 "Secrets"** (而不是 "Variables") 来存储，以防止 Cookie 外泄。 ### 第三步（2）：服务器 Docker 部署 [​](https://help.router-for.me/cn/hands-on/tutorial-11#%E7%AC%AC%E4%B8%89%E6%AD%A5-2-%E6%9C%8D%E5%8A%A1%E5%99%A8-docker-%E9%83%A8%E7%BD%B2) 如果你拥有自己的服务器（VPS），也可以使用 Docker Compose 进行部署。 1. **下载代码** bash git clone https://github.com/hkfires/AIStudioBuildWS.git cd AIStudioBuildWS 2. **配置环境变量** 复制 `.env.example` 为 `.env`，并填入必要信息（`CAMOUFOX_INSTANCE_URL` 和 `USER_COOKIE_1` 等）。 也可以在 `cookies` 目录下放置 JSON 格式的 Cookie 文件（文件名任意），程序会自动读取。 bash cp .env.example .env nano .env 3. **启动服务** bash docker compose up -d --build 部署成功后，我们应该在 `CLIProxyAPI` 的中看到类似如下的日志。至此，整个部署全部完成。 ![](https://img.072899.xyz/2025/11/e0db39f81a3bbb956cbe9364e656a76f.png) ### 参考项目 [​](https://help.router-for.me/cn/hands-on/tutorial-11#%E5%8F%82%E8%80%83%E9%A1%B9%E7%9B%AE) [https://github.com/cliouo/aistudio-build-proxy-all](https://github.com/cliouo/aistudio-build-proxy-all) --- # AmpCode食用指南 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/hands-on/tutorial-12#VPContent) 回到顶部 AmpCode食用指南 [​](https://help.router-for.me/cn/hands-on/tutorial-12#ampcode%E9%A3%9F%E7%94%A8%E6%8C%87%E5%8D%97) ================================================================================================================ 今天提到的 **AmpCode** 可能国内很少有人听过（大概是因为没有“白嫖”渠道？）。其实 AmpCode 凭借其独特的理念在 AI 编程领域已占有一席之地。它最核心的特点是**效率优先，成本次之**——用户无需关心模型选择，系统会自动调用当前最佳的模型来完成工作。因此，AmpCode 原生并不支持模型切换，更不用说使用第三方模型了。 AmpCode 主要有两种模式： * **Free 模式：** 免费使用 Claude Haiku 4.5 模型，代价是包含广告（这可能是目前唯一带广告的 Agent 工具？）。 * **Smart 模式：** 自动选用当下最强的模型组合。在这个时间节点（2025年12月），Smart 模式通常会调用 Claude Opus 4.5 处理复杂任务，Claude Haiku 4.5 负责高频简单响应，并由 GPT 5.1 作为 SubAgent 进行多维度的逻辑补全。 这篇文章将教大家如何搭配 **AmpCode + CLIProxyAPI**，实现“在 AmpCode 中使用自己模型”的目标。 ### 1\. 配置 CLIProxyAPI [​](https://help.router-for.me/cn/hands-on/tutorial-12#_1-%E9%85%8D%E7%BD%AE-cliproxyapi) 首先我们需要一个配置好的 CLIProxyAPI。具体的部署方法可以参考我之前的 CLIProxyAPI 系列教程，这里不再赘述。 常规配置完 CLIProxyAPI 之后，我们需要在配置文件中加入以下 AmpCode 相关的设置： ampcode: upstream-url: "https://ampcode.com" restrict-management-to-localhost: false upstream-api-key: "sgamp_user_XXXX" force-model-mappings: false model-mappings: - from: claude-opus-4-5-20251101 to: gemini-claude-sonnet-4-5 - from: claude-sonnet-4-5-20250929 to: gemini-claude-sonnet-4-5 - from: claude-haiku-4-5-20251001 to: qwen3-coder-flash **配置项说明：** * `upstream-url`, `restrict-management-to-localhost`, `upstream-api-key`： 如果你拥有 AmpCode 账号，并希望在官网后台查看会话信息，请填入这三项。其中 `upstream-api-key` 可以在 AmpCode 后台复制（如下图）。~如果你没有 AmpCode 账号，直接删除这三行即可。~ **注意：** AmpCode 客户端最近更新后，已强制要求填写上游信息，因此现在此部分为必填项。 ![](https://img.072899.xyz/2025/12/1e6e2eab382f693c3c70c2017e7e7c8f.png) * `model-mappings` **（重点敲黑板！）**： 这是配置中最关键的部分。我们需要理解 CLIProxyAPI 的处理逻辑： 当 AmpCode 请求某个特定模型（例如 `claude-opus-4-5-20251101`）时，CLIProxyAPI 会优先在已注册的模型列表中查找。 * **情况 A：** 如果该模型存在，直接请求该模型（model-mappings 不生效）。 * **情况 B：** 如果该模型不存在，CLIProxyAPI 本该报错，但通过配置 model-mappings，我们可以将请求**重定向**到我们指定的模型（例如 `gemini-claude-sonnet-4-5`）。 > **举个栗子帮助理解：** > > 假设 AmpCode 请求 `claude-opus-4-5-20251101`，如果在 CLIProxyAPI 里有这个模型，那么 AmpCode 就会使用 CLIProxyAPI 中的 `claude-opus-4-5-20251101` 模型； 如果 CLIProxyAPI 里并没有配置这个模型，系统就会触发 `model-mappings` 规则，把请求转交给 `gemini-claude-sonnet-4-5` 来响应。 通过以上规则，我们就成功实现了“移花接木”，用自己的模型接管了 AmpCode 的请求。 > > （如果对这个逻辑还有疑问，建议把上面这段话多读几遍~） * `force-model-mappings`： 这是一个布尔值（`true` 或 `false`），默认为 `false`。 当设置为 `true` 时，CLIProxyAPI 会**强制**应用 `model-mappings` 中的重定向规则，**即使“情况 A”满足**（即 `from` 模型本身存在于 CLIProxyAPI 中）。 这个选项非常适合需要**临时覆盖**或**统一管理**模型请求的场景。例如，即使你的 CLIProxyAPI 中已经配置了 `claude-opus-4-5-20251101`，你依然可以通过开启此选项，将其所有请求强制转到 `gemini-claude-sonnet-4-5`。 完成以上配置，CLIProxyAPI 这一侧就算准备就绪了。 ### 2\. 配置 AmpCode 客户端 [​](https://help.router-for.me/cn/hands-on/tutorial-12#_2-%E9%85%8D%E7%BD%AE-ampcode-%E5%AE%A2%E6%88%B7%E7%AB%AF) AmpCode 支持多平台客户端，你可以根据自己的使用习惯选择，以下会讲解配置命令行工具（Amp CLI）与 VSCode 插件两种方式。 #### 方式一：配置 Amp CLI [​](https://help.router-for.me/cn/hands-on/tutorial-12#%E6%96%B9%E5%BC%8F%E4%B8%80-%E9%85%8D%E7%BD%AE-amp-cli) 以下以在 **WSL2 Debian** 中安装 Amp CLI 为例供大家参考。 ![](https://img.072899.xyz/2025/12/7979738f3bd96c95c20d06889a74f29e.png) 复制官方提供的安装脚本进行安装： `curl -fsSL https://ampcode.com/install.sh | bash` **注意：** 安装完成后先不要运行，我们需要编辑环境变量。 输入 `nano ~/.bashrc`，在文件最底部添加如下内容： export AMP_URL="http://你的CPA部署地址:端口" export AMP_API_KEY="你在CPA中设定的api-keys" 保存并退出后，运行 `source ~/.bashrc` 使配置生效。 #### 方式二：配置 VSCode 插件 [​](https://help.router-for.me/cn/hands-on/tutorial-12#%E6%96%B9%E5%BC%8F%E4%BA%8C-%E9%85%8D%E7%BD%AE-vscode-%E6%8F%92%E4%BB%B6) 如果你更习惯在 VSCode 中进行开发，AmpCode 也提供了官方插件。 1. **安装插件**：在 VSCode 扩展商店中搜索并安装 `AmpCode` 插件。 ![](https://img.072899.xyz/2025/12/d62cd472a9e7837929308a732c479ea5.png) 2. **打开设置**：通过命令面板 (`Ctrl+Shift+P`) 搜索 `Preferences: Open User Settings (JSON)`，打开 `settings.json` 文件。 3. **添加配置**：在 `settings.json` 中添加以下配置，将 `amp.url` 指向你的 CLIProxyAPI 服务地址： json { // ... 其他配置 "amp.url": "http://你的CPA部署地址:端口" } 4. **登录**：配置完成后，点击侧边栏的 AmpCode 图标。插件界面会显示你配置的 URL，在红框处输入你在 CLIProxyAPI 中设定的 `api-keys` 即可登录使用（注意不是 AmpCode 官网提供的 Key）。 ![](https://img.072899.xyz/2025/12/98ceb48e3b4c10f0d86a2f138838ff26.png) ### 3\. 验证结果 [​](https://help.router-for.me/cn/hands-on/tutorial-12#_3-%E9%AA%8C%E8%AF%81%E7%BB%93%E6%9E%9C) 无论你使用哪种客户端，验证方式都是类似的： * **对于 Amp CLI 用户：** 输入 `amp` 并尝试发送一段提示词，如果一切顺利，你将看到如下界面： ![](https://img.072899.xyz/2025/12/bba2d9f3010ca2a78db6ac5c63b6645c.png) * **对于 VSCode 插件用户：** 登录成功后，在 AmpCode 的聊天窗口中发送提示词，插件会正常返回结果。 ![](https://img.072899.xyz/2025/12/c6af979f543fffc6d43b9e88ed7e01c8.png) 同时，在 CLIProxyAPI 的后台日志中，我们也能清晰地看到对应的请求已被成功转发： ![](https://img.072899.xyz/2025/12/3e15d2ef067d8a6deaa8e629465cbfa8.png) 大功告成！ --- # 壹：项目介绍+Qwen实战 | CLIProxyAPI [跳转到内容](https://help.router-for.me/cn/hands-on/tutorial-1#VPContent) 回到顶部 壹：项目介绍+Qwen实战 [​](https://help.router-for.me/cn/hands-on/tutorial-1#%E5%A3%B9-%E9%A1%B9%E7%9B%AE%E4%BB%8B%E7%BB%8D-qwen%E5%AE%9E%E6%88%98) =========================================================================================================================================== CLIProxyAPI 是一款使用 Go 语言编写的开源 AI 代理工具。也许是因为名字朴实无华，许多人可能对它还很陌生。在遇到它之前，为了能“白嫖” Gemini 模型，我曾先后折腾过 AIStudioProxyAPI、AIStudio-Build-Proxy、Gemini-FastAPI 等多款反代工具，但它们或多或少都有些不尽如人意的地方。 直到我发现了 CLIProxyAPI 并深度使用了几个月，我可以肯定地说：无论是在性能、功能还是适用性上，它都是我用过最出色的 AI 代理工具，没有之一。称之为“神器”也毫不为过。 > **官方仓库地址**：[https://github.com/router-for-me/CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) ### **它究竟能做什么？** [​](https://help.router-for.me/cn/hands-on/tutorial-1#%E5%AE%83%E7%A9%B6%E7%AB%9F%E8%83%BD%E5%81%9A%E4%BB%80%E4%B9%88) | 软件功能特性 | 支持的模型 | | --- | --- | | 为 CLI 模型提供 OpenAI/Gemini/Claude/Codex 兼容的 API 端点 | gemini-2.5-pro | | 新增 OpenAI Codex（GPT 系列）支持（OAuth 登录） | gemini-2.5-flash | | 新增 Claude Code 支持（OAuth 登录） | gemini-2.5-flash-lite | | 新增 Qwen Code 支持（OAuth 登录） | gemini-2.5-flash-image-preview | | 新增 iFlow 支持（OAuth 登录） | gpt-5 | | 新增 Gemini Web 支持（通过 Cookie 登录） | gpt-5-codex | | 支持流式与非流式响应 | claude-opus-4-1-20250805 | | 函数调用/工具支持 | claude-opus-4-20250514 | | 多模态输入（文本、图片） | claude-sonnet-4-20250514 | | 多账户支持与轮询负载均衡（Gemini、OpenAI、Claude、Qwen 与 iFlow） | claude-sonnet-4-5-20250929 | | 简单的 CLI 身份验证流程（Gemini、OpenAI、Claude、Qwen 与 iFlow） | claude-3-7-sonnet-20250219 | | 支持 Gemini AIStudio API 密钥 | claude-3-5-haiku-20241022 | | 支持 Gemini CLI 多账户轮询 | qwen3-coder-plus | | 支持 Claude Code 多账户轮询 | qwen3-coder-flash | | 支持 Qwen Code 多账户轮询 | qwen3-max | | 支持 iFlow 多账户轮询 | qwen3-vl-plus | | 支持 OpenAI Codex 多账户轮询 | deepseek-v3.2 | | 通过配置接入上游 OpenAI 兼容提供商（例如 OpenRouter） | deepseek-v3.1 | | 可复用的 Go SDK | deepseek-r1 | | | deepseek-v3 | | | kimi-k2 | | | glm-4.6 | | | tstars2.0 | | | 以及其他 iFlow 支持的模型 | 简单来说，CLIProxyAPI 的核心优势包括： * **无需安装 Gemini CLI**，即可将其授权转换为通用的 API Key，从而在任何应用中调用功能完整的 Gemini 2.5 Pro、Gemini 2.5 Flash、Gemini 2.5 Flash Lite 模型。当正式版模型配额用尽后，它会自动切换到 Preview 模型（如 `gemini-2.5-pro-preview-05-06`），基本能用足每天 1000 次的调用配额，轻松实现“Gemini 自由”。 * **无需安装 Qwen Code**，即可将其授权转换为通用的 API Key，在任何地方调用 Qwen3 Coder Plus、Qwen3 Coder Flash 模型，实现“Qwen3 Coder 自由”。 * **无需安装 Codex**，即可将其授权转换为通用的 API Key，在任何地方调用 GPT-5、GPT-5-Codex 模型。尤其在目前可以免费开设 Team 账户的活动下，轻松实现“GPT 自由”。 * **将 Gemini 网页版转换为 API Key**，在任何地方调用 Nano Banana 等网页版模型（需客户端支持。据网友分享，免费版 Gemini 网页账户每天可调用约 100 次，而 Gemini Pro 用户则高达 1000 次）。 * **强大的负载均衡能力**。CLIProxyAPI 支持将不同来源（无论是 API Key 还是 OAuth 授权）的多个账户整合在一起进行负载均衡轮询，这意味着你可以轻松地将调用配额翻倍。 * **极低的资源消耗**。值得一提的是，该程序对系统资源的消耗极低。程序本身仅 10MB 左右，启动时内存占用不到 10MB，长时间峰值内存占用也仅有 100MB 左右，几乎任何电脑都能流畅运行。 程序的使用非常简单。官方不仅提供了适用于各平台的二进制文件和 Docker 部署方式，还提供了 EasyCLI 和 WebUI，对新手十分友好。所有设置均通过 `config.yaml` 配置文件管理，且支持热重载——修改配置后即时生效，无需重启程序。完整的配置项解说详见《零：配置详细解说》。 ### **实战教程：转换 Qwen Code 为 API Key** [​](https://help.router-for.me/cn/hands-on/tutorial-1#%E5%AE%9E%E6%88%98%E6%95%99%E7%A8%8B-%E8%BD%AC%E6%8D%A2-qwen-code-%E4%B8%BA-api-key) 下面，我们以在 Windows 平台下将 Qwen Code 转换为 API Key 为例，演示 CLIProxyAPI 的具体使用方法。 1. **下载并解压** 首先，从官方仓库下载预编译的可执行文件，并将其解压到任意文件夹。在本例中，我将其放在 `Z:\CLIProxyAPI` 目录下。我们只需要用到图中的两个文件。 ![](https://img.072899.xyz/2025/09/b247eb98e0172c799c452d647ab09836.png) 2. **编辑配置文件** 将 `config.example.yaml` 重命名为 `config.yaml`，然后用文本编辑器打开，仅需保留并修改以下基础配置项： yaml port: 8317 # 文件夹位置请根据你的实际情况填写 auth-dir: "Z:\\CLIProxyAPI\\auths" request-retry: 3 quota-exceeded: switch-project: true switch-preview-model: true api-keys: # Key请自行设置，用于客户端访问代理 - "ABC-123456" 3. **获取授权** 在 `CLIProxyAPI` 目录下打开终端，输入 `cli-proxy-api --qwen-login` 后回车。程序会自动打开浏览器，请在浏览器中登录你的 Qwen 账户并完成授权。 ![](https://img.072899.xyz/2025/09/ec2e867f5a8de1d24969cb5225cdaa9e.png) 完成授权后，回到终端，程序会尝试获取认证信息。成功后，会要求输入邮箱或昵称（如图中红色箭头所示）。这只是一个用于标识账户的别名，可以随意填写。我这里填的是 `qwen-example`。回车后，可以看到认证文件已成功生成，并保存到了配置文件 `auth-dir` 指定的位置。 ![](https://img.072899.xyz/2025/09/8d37d893884910db77bd4498373a4922.png) > **提示**：如果系统没有自动弹出浏览器，请不必担心。手动复制终端中红框标出的网址，粘贴到浏览器中打开即可完成授权。 4. **启动代理服务** 以上步骤完成了账户认证。现在，我们来正式启动代理服务。直接双击可执行文件 (`cli-proxy-api.exe`)，出现以下窗口即代表启动成功。 ![](https://img.072899.xyz/2025/09/9e75a484a7f0713c6b56f1fd9a749195.png) 5. **在客户端中配置和测试** 至此，一切准备就绪。下面我们使用 Cherry Studio 来进行测试。 * 在 Cherry Studio 中添加一个新的模型提供商。 ![](https://img.072899.xyz/2025/09/2a2d401e75d02421861e136a6e377f5b.png) * 模型提供商类型可以选择除 Azure 之外的任意类型。这里我们以 `OpenAI-Response` 为例，供应商名称可自定义，例如 `CLIProxyAPI`。 ![](https://img.072899.xyz/2025/09/3161b549ee3877342f178b2828a30dc6.png) * **API密钥**：填写我们在 `config.yaml` 中自己设置的 Key，本例中为 `ABC-123456`。 * **API地址**：填写我们本地服务的地址和端口。还记得配置文件中的端口号 `8317` 吗？这里我们填入 `http://127.0.0.1:8317`。 ![](https://img.072899.xyz/2025/09/5f9638b5f5e5c14d4a818b7362167083.png) * 点击“管理模型”，你就可以看到通过代理加载的 Qwen Code 模型了。 ![](https://img.072899.xyz/2025/09/9a5d68865bfd1d5fa1cf7778860e6a76.png) * 添加模型后，我们来测试一下。 ![](https://img.072899.xyz/2025/09/83fd73b257efa9e50ce11bf03cb597d6.png) 可以看到，模型已成功返回消息。整个配置过程是不是很简单？ ---