CLIProxyAPI/README_CN.md

写给所有中国网友的

对于项目前期的确有很多用户使用上遇到各种各样的奇怪问题，大部分是因为配置或我说明文档不全导致的。

对说明文档我已经尽可能的修补，有些重要的地方我甚至已经写到了打包的配置文件里。

已经写在 README 中的功能，都是可用的，经过验证的，并且我自己每天都在使用的。

可能在某些场景中使用上效果并不是很出色，但那基本上是模型和工具的原因，比如用 Claude Code 的时候，有的模型就无法正确使用工具，比如 Gemini，就在 Claude Code 和 Codex 的下使用的相当扭捏，有时能完成大部分工作，但有时候却只说不做。

目前来说 Claude 和 GPT-5 是目前使用各种第三方CLI工具运用的最好的模型，我自己也是多个账号做均衡负载使用。

实事求是的说，最初的几个版本我根本就没有中文文档，我至今所有文档也都是使用英文更新让后让 Gemini 翻译成中文的。但是无论如何都不会出现中文文档无法理解的问题。因为所有的中英文文档我都是再三校对，并且发现未及时更改的更新的地方都快速更新掉了。

最后，烦请在发 Issue 之前请认真阅读这篇文档。

另外中文需要交流的用户可以加 QQ 群：188637136

或 Telegram 群：https://t.me/CLIProxyAPI

CLI 代理 API

English | 中文

一个为 CLI 提供 OpenAI/Gemini/Claude/Codex 兼容 API 接口的代理服务器。

现已支持通过 OAuth 登录接入 OpenAI Codex（GPT 系列）和 Claude Code。

您可以使用本地或多账户的CLI方式，通过任何与 OpenAI（包括Responses）/Gemini/Claude 兼容的客户端和SDK进行访问。

现已新增首个中国提供商：Qwen Code。

功能特性

• 为 CLI 模型提供 OpenAI/Gemini/Claude/Codex 兼容的 API 端点
• 新增 OpenAI Codex（GPT 系列）支持（OAuth 登录）
• 新增 Claude Code 支持（OAuth 登录）
• 新增 Qwen Code 支持（OAuth 登录）
• 新增 Gemini Web 支持（通过 Cookie 登录）
• 支持流式与非流式响应
• 函数调用/工具支持
• 多模态输入（文本、图片）
• 多账户支持与轮询负载均衡（Gemini、OpenAI、Claude 与 Qwen）
• 简单的 CLI 身份验证流程（Gemini、OpenAI、Claude 与 Qwen）
• 支持 Gemini AIStudio API 密钥
• 支持 Gemini CLI 多账户轮询
• 支持 Claude Code 多账户轮询
• 支持 Qwen Code 多账户轮询
• 支持 OpenAI Codex 多账户轮询
• 通过配置接入上游 OpenAI 兼容提供商（例如 OpenRouter）
• 可复用的 Go SDK（见 docs/sdk-usage.md）

安装

前置要求

• Go 1.24 或更高版本
• 有权访问 Gemini CLI 模型的 Google 账户（可选）
• 有权访问 OpenAI Codex/GPT 的 OpenAI 账户（可选）
• 有权访问 Claude Code 的 Anthropic 账户（可选）
• 有权访问 Qwen Code 的 Qwen Chat 账户（可选）

从源码构建

1. 克隆仓库：

   git clone https://github.com/luispater/CLIProxyAPI.git
   cd CLIProxyAPI
   

2. 构建应用程序：

   go build -o cli-proxy-api ./cmd/server
   

使用方法

身份验证

您可以分别为 Gemini、OpenAI 和 Claude 进行身份验证，三者可同时存在于同一个 auth-dir 中并参与负载均衡。

• Gemini（Google）：

  ./cli-proxy-api --login
  

  如果您是现有的 Gemini Code 用户，可能需要指定一个项目ID：

  ./cli-proxy-api --login --project_id <your_project_id>
  

  本地 OAuth 回调端口为 8085。

  选项：加上 --no-browser 可打印登录地址而不自动打开浏览器。本地 OAuth 回调端口为 8085。

• Gemini Web (通过 Cookie): 此方法通过模拟浏览器行为，使用从 Gemini 网站获取的 Cookie 进行身份验证。

  ./cli-proxy-api --gemini-web-auth
  

  程序将提示您输入 __Secure-1PSID 和 __Secure-1PSIDTS 的值。请从您的浏览器开发者工具中获取这些 Cookie。

• OpenAI（Codex/GPT，OAuth）：

  ./cli-proxy-api --codex-login
  

  选项：加上 --no-browser 可打印登录地址而不自动打开浏览器。本地 OAuth 回调端口为 1455。

• Claude（Anthropic，OAuth）：

  ./cli-proxy-api --claude-login
  

  选项：加上 --no-browser 可打印登录地址而不自动打开浏览器。本地 OAuth 回调端口为 54545。

• Qwen（Qwen Chat，OAuth）：

  ./cli-proxy-api --qwen-login
  

  选项：加上 --no-browser 可打印登录地址而不自动打开浏览器。使用 Qwen Chat 的 OAuth 设备登录流程。

启动服务器

身份验证完成后，启动服务器：

./cli-proxy-api

默认情况下，服务器在端口 8317 上运行。

API 端点

列出模型

GET http://localhost:8317/v1/models

聊天补全

POST http://localhost:8317/v1/chat/completions

请求体示例：

{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": "你好，你好吗？"
    }
  ],
  "stream": true
}

说明：

• 使用 "gemini-" 模型（例如 "gemini-2.5-pro"）来调用 Gemini，使用 "gpt-" 模型（例如 "gpt-5"）来调用 OpenAI，使用 "claude-" 模型（例如 "claude-3-5-sonnet-20241022"）来调用 Claude，或者使用 "qwen-" 模型（例如 "qwen3-coder-plus"）来调用 Qwen。代理服务会自动将请求路由到相应的提供商。

Claude 消息（SSE 兼容）

POST http://localhost:8317/v1/messages

与 OpenAI 库一起使用

您可以通过将基础 URL 设置为本地服务器来将此代理与任何 OpenAI 兼容的库一起使用：

Python（使用 OpenAI 库）

from openai import OpenAI

client = OpenAI(
    api_key="dummy",  # 不使用但必需
    base_url="http://localhost:8317/v1"
)

# Gemini 示例
gemini = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=[{"role": "user", "content": "你好，你好吗？"}]
)

# Codex/GPT 示例
gpt = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "用一句话总结这个项目"}]
)

# Claude 示例（使用 messages 端点）
import requests
claude_response = requests.post(
    "http://localhost:8317/v1/messages",
    json={
        "model": "claude-3-5-sonnet-20241022",
        "messages": [{"role": "user", "content": "用一句话总结这个项目"}],
        "max_tokens": 1000
    }
)

print(gemini.choices[0].message.content)
print(gpt.choices[0].message.content)
print(claude_response.json())

JavaScript/TypeScript

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'dummy', // 不使用但必需
  baseURL: 'http://localhost:8317/v1',
});

// Gemini
const gemini = await openai.chat.completions.create({
  model: 'gemini-2.5-pro',
  messages: [{ role: 'user', content: '你好，你好吗？' }],
});

// Codex/GPT
const gpt = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [{ role: 'user', content: '用一句话总结这个项目' }],
});

// Claude 示例（使用 messages 端点）
const claudeResponse = await fetch('http://localhost:8317/v1/messages', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'claude-3-5-sonnet-20241022',
    messages: [{ role: 'user', content: '用一句话总结这个项目' }],
    max_tokens: 1000
  })
});

console.log(gemini.choices[0].message.content);
console.log(gpt.choices[0].message.content);
console.log(await claudeResponse.json());

支持的模型

• gemini-2.5-pro
• gemini-2.5-flash
• gemini-2.5-flash-lite
• gpt-5
• gpt-5-codex
• claude-opus-4-1-20250805
• claude-opus-4-20250514
• claude-sonnet-4-20250514
• claude-3-7-sonnet-20250219
• claude-3-5-haiku-20241022
• qwen3-coder-plus
• qwen3-coder-flash
• Gemini 模型在需要时自动切换到对应的 preview 版本

配置

服务器默认使用位于项目根目录的 YAML 配置文件（config.yaml）。您可以使用 --config 标志指定不同的配置文件路径：

  ./cli-proxy-api --config /path/to/your/config.yaml

配置选项

参数	类型	默认值	描述
port	integer	8317	服务器将监听的端口号。
auth-dir	string	"~/.cli-proxy-api"	存储身份验证令牌的目录。支持使用 ~ 来表示主目录。如果你使用Windows，建议设置成C:/cli-proxy-api/。
proxy-url	string	""	代理URL。支持socks5/http/https协议。例如：socks5://user:pass@192.168.1.1:1080/
request-retry	integer	0	请求重试次数。如果HTTP响应码为403、408、500、502、503或504，将会触发重试。
remote-management.allow-remote	boolean	false	是否允许远程（非localhost）访问管理接口。为false时仅允许本地访问；本地访问同样需要管理密钥。
remote-management.secret-key	string	""	管理密钥。若配置为明文，启动时会自动进行bcrypt加密并写回配置文件。若为空，管理接口整体不可用（404）。
quota-exceeded	object	{}	用于处理配额超限的配置。
quota-exceeded.switch-project	boolean	true	当配额超限时，是否自动切换到另一个项目。
quota-exceeded.switch-preview-model	boolean	true	当配额超限时，是否自动切换到预览模型。
debug	boolean	false	启用调试模式以获取详细日志。
api-keys	string[]	[]	可用于验证请求的API密钥列表。
generative-language-api-key	string[]	[]	生成式语言API密钥列表。
force-gpt-5-codex	bool	false	强制将 GPT-5 调用转换成 GPT-5 Codex。
codex-api-key	object	{}	Codex API密钥列表。
codex-api-key.api-key	string	""	Codex API密钥。
codex-api-key.base-url	string	""	自定义的Codex API端点
claude-api-key	object	{}	Claude API密钥列表。
claude-api-key.api-key	string	""	Claude API密钥。
claude-api-key.base-url	string	""	自定义的Claude API端点，如果您使用第三方的API端点。
openai-compatibility	object[]	[]	上游OpenAI兼容提供商的配置（名称、基础URL、API密钥、模型）。
openai-compatibility.*.name	string	""	提供商的名称。它将被用于用户代理（User Agent）和其他地方。
openai-compatibility.*.base-url	string	""	提供商的基础URL。
openai-compatibility.*.api-keys	string[]	[]	提供商的API密钥。如果需要，可以添加多个密钥。如果允许未经身份验证的访问，则可以省略。
openai-compatibility.*.models	object[]	[]	实际的模型名称。
openai-compatibility.*.models.*.name	string	""	提供商支持的模型。
openai-compatibility.*.models.*.alias	string	""	在API中使用的别名。
gemini-web	object	{}	Gemini Web 客户端的特定配置。
gemini-web.context	boolean	true	是否启用会话上下文重用，以实现连续对话。
gemini-web.code-mode	boolean	false	是否启用代码模式，优化代码相关任务的响应。
gemini-web.max-chars-per-request	integer	1,000,000	单次请求发送给 Gemini Web 的最大字符数。
gemini-web.disable-continuation-hint	boolean	false	当提示被拆分时，是否禁用连续提示的暗示。
gemini-web.token-refresh-seconds	integer	540	后台 Cookie 自动刷新的间隔（秒）。

配置文件示例

# 服务器端口
port: 8317

# 管理 API 设置
remote-management:
  # 是否允许远程（非localhost）访问管理接口。为false时仅允许本地访问（但本地访问同样需要管理密钥）。
  allow-remote: false

  # 管理密钥。若配置为明文，启动时会自动进行bcrypt加密并写回配置文件。
  # 所有管理请求（包括本地）都需要该密钥。
  # 若为空，/v0/management 整体处于 404（禁用）。
  secret-key: ""

# 身份验证目录（支持 ~ 表示主目录）。如果你使用Windows，建议设置成`C:/cli-proxy-api/`。
auth-dir: "~/.cli-proxy-api"

# 启用调试日志
debug: false

# 代理URL。支持socks5/http/https协议。例如：socks5://user:pass@192.168.1.1:1080/
proxy-url: ""

# 请求重试次数。如果HTTP响应码为403、408、500、502、503或504，将会触发重试。
request-retry: 3


# 配额超限行为
quota-exceeded:
   switch-project: true # 当配额超限时是否自动切换到另一个项目
   switch-preview-model: true # 当配额超限时是否自动切换到预览模型

# Gemini Web 客户端配置
gemini-web:
  context: true # 启用会话上下文重用
  code-mode: false # 启用代码模式
  max-chars-per-request: 1000000 # 单次请求最大字符数
  token-refresh-seconds: 540 # Cookie 刷新间隔（秒）

# 用于本地身份验证的 API 密钥
api-keys:
  - "your-api-key-1"
  - "your-api-key-2"

# AIStduio Gemini API 的 API 密钥
generative-language-api-key:
  - "AIzaSy...01"
  - "AIzaSy...02"
  - "AIzaSy...03"
  - "AIzaSy...04"

# 强制将 GPT-5 调用转换成 GPT-5 Codex.
force-gpt-5-codex: true

# Codex API 密钥
codex-api-key:
  - api-key: "sk-atSM..."
    base-url: "https://www.example.com" # 第三方 Codex API 中转服务端点

# Claude API 密钥
claude-api-key:
  - api-key: "sk-atSM..." # 如果使用官方 Claude API，无需设置 base-url
  - api-key: "sk-atSM..."
    base-url: "https://www.example.com" # 第三方 Claude API 中转服务端点

# OpenAI 兼容提供商
openai-compatibility:
  - name: "openrouter" # 提供商的名称；它将被用于用户代理和其它地方。
    base-url: "https://openrouter.ai/api/v1" # 提供商的基础URL。
    api-keys: # 提供商的API密钥。如果需要，可以添加多个密钥。如果允许未经身份验证的访问，则可以省略。
      - "sk-or-v1-...b780"
      - "sk-or-v1-...b781"
    models: # 提供商支持的模型。
      - name: "moonshotai/kimi-k2:free" # 实际的模型名称。
        alias: "kimi-k2" # 在API中使用的别名。

OpenAI 兼容上游提供商

通过 openai-compatibility 配置上游 OpenAI 兼容提供商（例如 OpenRouter）。

• name：内部识别名
• base-url：提供商基础地址
• api-keys：可选，多密钥轮询（若提供商支持无鉴权可省略）
• models：将上游模型 name 映射为本地可用 alias

示例：

openai-compatibility:
  - name: "openrouter"
    base-url: "https://openrouter.ai/api/v1"
    api-keys:
      - "sk-or-v1-...b780"
      - "sk-or-v1-...b781"
    models:
      - name: "moonshotai/kimi-k2:free"
        alias: "kimi-k2"

使用方式：在 /v1/chat/completions 中将 model 设为别名（如 kimi-k2），代理将自动路由到对应提供商与模型。

并且，对于这些与OpenAI兼容的提供商模型，您始终可以通过将CODE_ASSIST_ENDPOINT设置为 http://127.0.0.1:8317 来使用Gemini CLI。

身份验证目录

auth-dir 参数指定身份验证令牌的存储位置。当您运行登录命令时，应用程序将在此目录中创建包含 Google 账户身份验证令牌的 JSON 文件。多个账户可用于轮询。

API 密钥

api-keys 参数允许您定义可用于验证对代理服务器请求的 API 密钥列表。在向 API 发出请求时，您可以在 Authorization 标头中包含其中一个密钥：

Authorization: Bearer your-api-key-1

官方生成式语言 API

generative-language-api-key 参数允许您定义可用于验证对官方 AIStudio Gemini API 请求的 API 密钥列表。

热更新

服务会监听配置文件与 auth-dir 目录的变化并自动重新加载客户端与配置。您可以在运行中新增/移除 Gemini/OpenAI 的令牌 JSON 文件，无需重启服务。

Gemini CLI 多账户负载均衡

启动 CLI 代理 API 服务器，然后将 CODE_ASSIST_ENDPOINT 环境变量设置为 CLI 代理 API 服务器的 URL。

export CODE_ASSIST_ENDPOINT="http://127.0.0.1:8317"

服务器将中继 loadCodeAssist、onboardUser 和 countTokens 请求。并自动在多个账户之间轮询文本生成请求。

Note

此功能仅允许本地访问，因为找不到一个可以验证请求的方法。 所以只能强制只有 127.0.0.1 可以访问。

Claude Code 的使用方法

启动 CLI Proxy API 服务器, 设置如下系统环境变量 ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL, ANTHROPIC_SMALL_FAST_MODEL

使用 Gemini 模型：

export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export ANTHROPIC_AUTH_TOKEN=sk-dummy
export ANTHROPIC_MODEL=gemini-2.5-pro
export ANTHROPIC_SMALL_FAST_MODEL=gemini-2.5-flash

使用 OpenAI GPT 5 模型：

export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export ANTHROPIC_AUTH_TOKEN=sk-dummy
export ANTHROPIC_MODEL=gpt-5
export ANTHROPIC_SMALL_FAST_MODEL=gpt-5-minimal

使用 OpenAI GPT 5 Codex 模型:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export ANTHROPIC_AUTH_TOKEN=sk-dummy
export ANTHROPIC_MODEL=gpt-5-codex
export ANTHROPIC_SMALL_FAST_MODEL=gpt-5-codex-low

使用 Claude 模型：

export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export ANTHROPIC_AUTH_TOKEN=sk-dummy
export ANTHROPIC_MODEL=claude-sonnet-4-20250514
export ANTHROPIC_SMALL_FAST_MODEL=claude-3-5-haiku-20241022

使用 Qwen 模型：

export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export ANTHROPIC_AUTH_TOKEN=sk-dummy
export ANTHROPIC_MODEL=qwen3-coder-plus
export ANTHROPIC_SMALL_FAST_MODEL=qwen3-coder-flash

Codex 多账户负载均衡

启动 CLI Proxy API 服务器, 修改 ~/.codex/config.toml 和 ~/.codex/auth.json 文件。

config.toml:

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:

{
  "OPENAI_API_KEY": "sk-dummy"
}

使用 Docker 运行

运行以下命令进行登录（Gemini OAuth，端口 8085）：

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

运行以下命令进行登录（Gemini Web Cookie）：

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 --gemini-web-auth

运行以下命令进行登录（OpenAI OAuth，端口 1455）：

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

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

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

运行以下命令启动服务器：

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

使用 Docker Compose 运行

1. 克隆仓库并进入目录：

   git clone https://github.com/luispater/CLIProxyAPI.git
   cd CLIProxyAPI
   

2. 准备配置文件： 通过复制示例文件来创建 config.yaml 文件，并根据您的需求进行自定义。

   cp config.example.yaml config.yaml
   

   （Windows 用户请注意：您可以在 CMD 或 PowerShell 中使用 copy config.example.yaml config.yaml。）

3. 启动服务：

   • 适用于大多数用户（推荐）： 运行以下命令，使用 Docker Hub 上的预构建镜像启动服务。服务将在后台运行。

     docker compose up -d
     

   • 适用于进阶用户： 如果您修改了源代码并需要构建新镜像，请使用交互式辅助脚本：
     • 对于 Windows (PowerShell):

       .\docker-build.ps1
       

     • 对于 Linux/macOS:

       bash docker-build.sh
       

     脚本将提示您选择运行方式：
     • 选项 1：使用预构建的镜像运行 (推荐)：从镜像仓库拉取最新的官方镜像并启动容器。这是最简单的开始方式。
     • 选项 2：从源码构建并运行 (适用于开发者)：从本地源代码构建镜像，将其标记为 cli-proxy-api:local，然后启动容器。如果您需要修改源代码，此选项很有用。

4. 要在容器内运行登录命令进行身份验证：

   • Gemini:

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

   • Gemini Web:

   docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI --gemini-web-auth
   

   • OpenAI (Codex):

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

   • Claude:

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

   • Qwen:

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

5. 查看服务器日志：

   docker compose logs -f
   

6. 停止应用程序：

   docker compose down
   

管理 API 文档

请参见 MANAGEMENT_API_CN.md

SDK 文档

• 使用文档：docs/sdk-usage_CN.md（English: docs/sdk-usage.md）
• 高级（执行器与翻译器）：docs/sdk-advanced_CN.md（English: docs/sdk-advanced.md）
• 自定义 Provider 示例：examples/custom-provider

贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 仓库
2. 创建您的功能分支（git checkout -b feature/amazing-feature）
3. 提交您的更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开 Pull Request

许可证

此项目根据 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。