> 本文介绍如何在本地部署 CLIProxyAPI（以下简称 CPA），并完成基础配置、账号登录、Provider 管理和运行维护。
> 
> 官方仓库：[https://github\.com/router\-for\-me/CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)
> 官方文档：[https://help\.router\-for\.me/](https://help.router-for.me/)
> 

## 一、CLIProxyAPI 是什么？

CLIProxyAPI（简称CPA） 是一个本地代理服务器，可以为你的 CLI 工具和其他Agent客户端提供 OpenAI、Gemini、Claude、Codex、Grok 等兼容的 API 接口。

其可以将多个模型服务统一到一个本地地址，以便于：

- 在本地统一管理多个模型账号；

- 通过 OAuth 登录 Codex、Claude Code、Antigravity、Grok Build；

- 通过 API Key 接入 OpenAI 兼容服务；

- 管理多个账号并进行轮询；

- 通过统一的配置文件管理模型、账号、代理和日志。

注：CPA只是代理和适配层，并不会动提供模型额度。

## 二、准备工作

部署前需要准备：

1. 一台 Windows、Linux 或 macOS 设备；

2. CPA 官方程序；

3. 至少一个可用的模型账号或 API Key；

4. 一个用于保存配置和认证文件的本地目录。

## 三、Windows 安装

### 3\.1 下载程序

打开 CPA 官方 Releases 页面：

```Plain Text
[https://github.com/router-for-me/CLIProxyAPI/releases/latest](https://github.com/router-for-me/CLIProxyAPI/releases/latest)
```

下载适用于 Windows 的版本，并解压到固定目录，例如：

```Plain Text
C:\Tools\CLIProxyAPI
```

也可以使用官方推荐的 EasyCLIProxyAPI 桌面客户端，通过图形界面管理 CPA。

### 3\.2 创建配置文件

从官方仓库下载配置示例：

```Plain Text
https://github.com/router-for-me/CLIProxyAPI/blob/main/config.example.yaml
```

将文件保存为：

```Plain Text
C:\Tools\CLIProxyAPI\config.yaml
```

### 3\.3 AI Agent 辅助配置提示词

```Plain Text
请帮我下载并配置 CLIProxyAPI（CPA）

请参考官方资料：
仓库：https://github.com/router-for-me/CLIProxyAPI
文档：https://help.router-for.me/

我的环境：
- 系统：[Windows / Linux / macOS]
- CPA 目录：[填写路径]
- Provider：[Codex / Claude / Antigravity / xAI / OpenAI 兼容服务]
- 是否需要远程访问：[不需要 / 需要]

请帮我完成 CPA 的安装、配置、Provider 登录、启动和验证，不需要配置其他 AI 工具。

要求：
1. 先检查系统、CPA 程序、配置文件、认证目录和 8317 端口。
2. 默认只监听 127.0.0.1，不开放公网或局域网访问。
3. 不要索取或输出真实 API Key、密码、OAuth Token。
4. 修改文件前先备份，并保留现有有效配置。
5. 登录 Provider 时给出官方命令，并等待我完成浏览器授权。
6. 完成后验证配置、进程、端口和 Provider 状态。
7. 遇到错误时先诊断，不要盲目删除、重装或覆盖配置。
8. 最后告诉我：修改了什么、验证结果是什么、还需要我手动做什么。
```

## 四、安全与合规说明

CPA 可以通过 OAuth 登录账号，也可以在配置文件中保存 API Key。认证文件、API Key、管理密钥和配置文件都属于敏感凭据。

个人在本地使用 CPA 时，通常比将服务公开部署到公网的风险更低，但这并不代表绝对安全。设备被入侵、配置文件泄露、日志暴露、端口被转发或其他本地程序读取文件，都可能造成账号或额度风险。

使用时请注意以下事项：

1. 请使用自己拥有或获得明确授权的账号，并遵守对应服务商的使用条款和相关法律法规。

2. 不要将 OAuth 登录生成的认证文件、API Key、管理密钥或完整配置文件分享给其他人。

3. 不建议将个人账号认证后得到的 API Key 分享或共享给他人使用，尤其不要将个人订阅账号作为公共中转服务使用。

4. 本地使用时建议将服务绑定到：

```YAML
host: "127.0.0.1"
```

5. 并保持：

```YAML
remote-management:
  allow-remote: false
```

6. 不要直接将 `8317` 端口或管理页面暴露到公网。确实需要远程访问时，应额外配置访问认证、HTTPS、防火墙和访问来源限制。

7. 不要将 `~/.cli-proxy-api`、`config.yaml`、日志目录和备份文件上传到 Git 仓库、网盘或公开位置。

8. 排查问题时如果开启了调试日志或请求日志，应注意其中可能包含请求内容、响应内容或敏感信息；问题排查完成后应及时关闭并清理。

9. 如果怀疑认证信息或 API Key 已经泄露，应立即停止 CPA，撤销或重新登录相关账号，更换 CPA 的 `api-keys` 和管理密钥，并检查日志、备份文件和访问记录。

> 个人本地使用 CPA 通常不会直接触发账号风险，但这只是一般情况，不代表绝对安全。请根据账号类型、服务商规则和实际使用场景，合理、合规地使用 CPA，不要擅自共享个人账号额度或认证凭据。
> 
> 

## 五、基础配置

首次使用可以参考以下基础配置

```YAML
# 仅允许本机访问
host: "127.0.0.1"

# CPA 服务端口
port: 8317

# OAuth 凭据和认证文件保存目录
auth-dir: "~/.cli-proxy-api"

# CPA API 访问密钥
api-keys:
  - "REPLACE_WITH_A_LONG_RANDOM_API_KEY"

# 管理功能配置
remote-management:
  allow-remote: false
  secret-key: "REPLACE_WITH_MANAGEMENT_SECRET"
  disable-control-panel: false

# 调试日志
debug: false

# 是否将日志写入文件
logging-to-file: false

# 是否启用内存中的使用量统计
usage-statistics-enabled: false
```

Windows 复现本文的登录和自启动方式时，建议把 `auth-dir` 改为 `[CPA安装目录]\auths`；认证文件实际位置必须与 `config.yaml` 保持一致。

配置项说明：

本地使用时建议保持：

```YAML
host: "127.0.0.1"
allow-remote: false
```

不要在没有访问控制的情况下直接将 CPA 暴露到公网，或是局域网。

复现本教程时请特别核对实际的 `host` 和 `remote-management.allow-remote`。如果配置为 `host: "0.0.0.0"` 或 `allow-remote: true`，就不再是“仅本机访问”；个人本地使用建议按上面的安全值修改后再重启 CPA。

## 六、启动 CPA

打开 PowerShell，进入 CPA 根目录（以下路径仅为示例）：

```PowerShell
cd C:\Tools\CLIProxyAPI
```

按本文目录结构，程序位于 `bin` 子目录，使用指定配置文件启动：

```PowerShell
.\bin\cli-proxy-api.exe -config .\config.yaml
```

如果 `config.yaml` 位于程序根目录，也可以让程序按默认位置读取：

```PowerShell
.\bin\cli-proxy-api.exe
```

本地访问地址为：

```Plain Text
http://127.0.0.1:8317
```

说明：直接在 PowerShell 中启动时，关闭当前窗口会停止该进程；使用后面的 Windows 任务计划方式启动时，任务通过 `start.ps1` 拉起隐藏的 CPA 子进程，脚本结束后 CPA 会继续运行。

注意：`127.0.0.1` 是本机访问地址，不等于服务一定只监听本机。如果 `config.yaml` 中的 `host` 为 `0.0.0.0`，还可能接受来自局域网或其他网卡的连接，请按第五节的安全配置核对。

## 七、登录 OAuth Provider

CPA 支持将多个模型服务作为 Provider 登录。以下命令都需要在 CPA 根目录中执行。

### 7\.1 登录 Codex

```PowerShell
.\bin\cli-proxy-api.exe -codex-login
```

Codex OAuth 默认使用本机 `1455` 端口完成回调。

### 7\.2 登录 Claude Code

```PowerShell
.\bin\cli-proxy-api.exe -claude-login
```

Claude Code OAuth 默认使用本机 `54545` 端口完成回调。

### 7\.3 登录 Antigravity

```PowerShell
.\bin\cli-proxy-api.exe -antigravity-login
```

Antigravity OAuth 默认使用本机 `51121` 端口完成回调。

### 7\.4 登录 xAI / Grok

```PowerShell
.\bin\cli-proxy-api.exe -xai-login
```

xAI OAuth 默认使用：

```Plain Text
127.0.0.1:56121/callback
```

如果当前环境无法自动打开浏览器，可以添加：

```PowerShell
.\bin\cli-proxy-api.exe -codex-login -no-browser
```

程序会输出登录地址，再手动打开地址完成授权。

登录成功后，认证文件的实际保存位置由 `config.yaml` 中的 `auth-dir` 决定。若采用本文 Windows 示例，可使用：

```Plain Text
[CPA安装目录]\auths
```

如果未设置自定义 `auth-dir`，请以当前版本官方配置说明为准，不要仅凭系统用户名猜测目录。

## 八、配置 OpenAI 兼容 Provider

如果使用 API Key 接入第三方 OpenAI 兼容服务，可以在 `config.yaml` 中添加：

```YAML
openai-compatibility:
  - name: "my-provider"
    disabled: false
    base-url: "https://api.example.com/v1"
    api-key-entries:
      - api-key: "REPLACE_WITH_PROVIDER_API_KEY"
    models:
      - name: "upstream-model-name"
        alias: "my-model"
```

配置说明：

- `name`：Provider 名称；

- `base-url`：上游 API 地址；

- `api-key-entries`：Provider 的 API Key；

- `models.name`：上游真实模型名称；

- `models.alias`：CPA 内部使用的模型别名；

- `disabled`：是否暂时停用该 Provider。

例如：

```YAML
openai-compatibility:
  - name: "openrouter"
    disabled: false
    base-url: "https://openrouter.ai/api/v1"
    api-key-entries:
      - api-key: "REPLACE_WITH_OPENROUTER_KEY"
    models:
      - name: "moonshotai/kimi-k2:free"
        alias: "kimi-k2"
```

## 九、配置模型别名

如果模型名称较长，或者希望统一模型名称，可以使用别名：

```YAML
models:
  - name: "upstream-model-name"
    alias: "my-model"
```

之后 CPA 内部使用：

```Plain Text
my-model
```

模型别名适合以下场景：

- 在多个 Provider 之间使用统一名称；

- 后续更换 Provider 时减少配置修改；

- 为不同渠道设置容易识别的名称。

## 十、使用管理页面

如果配置中启用了管理页面：

```YAML
remote-management:
  allow-remote: false
  secret-key: "REPLACE_WITH_MANAGEMENT_SECRET"
  disable-control-panel: false
```

可以在浏览器中打开：

```Plain Text
http://127.0.0.1:8317/management.html
```

管理页面可以用于查看和管理 CPA 的运行状态。需要远程使用时管理密钥不要设置为空。

如果不需要管理 API，可以关闭管理功能：

```YAML
remote-management:
  allow-remote: false
  secret-key: ""
  disable-control-panel: false
```

## 十一、配置热更新

CPA 支持配置文件热加载。修改 `config.yaml` 后，部分配置可以立即生效，不需要重新启动程序。

如果修改了以下内容，建议重新启动 CPA：

- 服务端口；

- 监听地址；

- OAuth 登录状态；

- 认证目录；

- 进程启动方式。

重新启动：

```PowerShell
.\stop.ps1
.\start.ps1
```

## 十二、日志与使用量统计

调试问题时可以临时启用：

```YAML
debug: true
```

如果需要将日志写入文件：

```YAML
logging-to-file: true
```

从 CLIProxyAPI v6\.10\.0 开始，CPA 不再内置完整的长期使用量统计功能。

如果需要请求级监控、Token 统计、费用估算或可视化面板，应额外使用：

- CPA Usage Keeper；

- CPA\-Manager\-Plus。

> CPA 负责模型代理、账号管理和请求转发；长期使用量统计需要额外部署配套工具。
> 
> 

## 十三、常见问题

### 端口被占用

默认端口是 `8317`。可以修改为其他端口：

```YAML
port: 8318
```

修改后重新启动 CPA。

### OAuth 登录失败

检查对应回调端口是否被其他程序占用：

- Codex：1455

- Claude Code：54545

- Antigravity：51121

- xAI：56121

### 找不到配置文件

确认当前启动目录和配置文件位置：

```PowerShell
.\bin\cli-proxy-api.exe -config "C:\Tools\CLIProxyAPI\config.yaml"
```

### API Key 无效

检查：

- `api-keys` 是否填写正确；

- 客户端请求使用的 Key 是否与配置一致；

- 配置文件是否被 CPA 正确加载；

- Key 前后是否多了空格或换行。

### 找不到模型

检查 `models.name` 和 `models.alias` 是否填写正确，并确认对应 Provider 已经登录或配置了有效 API Key。

## 十四、Linux、macOS 与 Docker

Linux 官方安装方式：

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

macOS Homebrew 安装：

```Bash
brew install cliproxyapi
brew services start cliproxyapi
```

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 \
  -v /path/to/your/plugins-dir:/CLIProxyAPI/plugins \
  eceasy/cli-proxy-api:latest
```

## 十五、Windows 登录后自动启动、隐藏窗口与桌面快捷方式

本节采用 Windows 自带的任务计划程序实现登录后自启动，不依赖 VBS 引擎，不依赖第三方服务。以下路径均为示例，请替换为自己的 CPA 安装目录。

说明：本节内容是我的本地 Windows 配置示例，主要用于展示实际采用的自启动、隐藏窗口和桌面快捷方式方式，可作为参考，并非Windows 自启动的唯一方案。官方 Quick Start 对 Windows 的基础方式是下载 Release 后直接运行；请以官方资料为准：[官方 Quick Start（Windows 启动说明）](https://help.router-for.me/introduction/quick-start)、[官方基础配置](https://help.router-for.me/configuration/basic)、[官方 Releases 下载页](https://github.com/router-for-me/CLIProxyAPI/releases/latest)。

### 15\.1 准备启动脚本

在 CPA 根目录新建 `start.ps1`，内容如下。脚本会根据自身位置定位 `bin\cli-proxy-api.exe` 和 `config.yaml`，不需要把真实本地路径写死：

```PowerShell
$ErrorActionPreference = "Stop"
$root = Split-Path -Parent $MyInvocation.MyCommand.Path
$exe = Join-Path $root "bin\cli-proxy-api.exe"
$config = Join-Path $root "config.yaml"

if (-not (Test-Path -LiteralPath $exe)) {
    throw "CLIProxyAPI executable was not found: $exe"
}
if (-not (Test-Path -LiteralPath $config)) {
    throw "Configuration file was not found: $config"
}

$running = Get-CimInstance Win32_Process |
    Where-Object {
        $_.Name -eq "cli-proxy-api.exe" -and
        $_.CommandLine -like "*$config*"
    }

if ($running) {
    Write-Host "CLIProxyAPI is already running."
    exit 0
}

New-Item -ItemType Directory -Force -Path (Join-Path $root "logs") | Out-Null
$process = Start-Process `
    -FilePath $exe `
    -ArgumentList @("-config", $config) `
    -WorkingDirectory $root `
    -WindowStyle Hidden `
    -PassThru

Start-Sleep -Seconds 2
if ($process.HasExited) {
    throw "CLIProxyAPI exited during startup. Check the logs directory."
}

Write-Host "CLIProxyAPI started. PID: $($process.Id)"
Write-Host "API base URL: http://127.0.0.1:8317"
```

如果 `config.yaml` 中已经配置了 `remote-management.secret-key`，启动任务不需要再把管理密钥写入命令行或脚本。

### 15\.2 使用任务计划程序设置登录后启动

1. 按 `Win + R`，输入 `taskschd.msc`，打开任务计划程序。

2. 选择“创建任务”，名称填写：`CLIProxyAPI - Local Proxy`。

3. “常规”中选择“仅当用户登录时运行”，不需要勾选“使用最高权限运行”。

4. “触发器”添加“登录时”，用户选择当前 Windows 用户，并确认已启用。

5. “操作”选择“启动程序”：程序填写 `powershell.exe`；参数填写：`-NoProfile -ExecutionPolicy Bypass -File "[CPA安装目录]\start.ps1"`；“起始于”可以留空，因为脚本会根据自身位置定位目录。

6. 保存后右键任务选择“运行”，再按下方方法验证。

当前方式使用 Windows 自带任务计划程序和 PowerShell；其中 `-WindowStyle Hidden` 可能被部分安全软件拦截。

### 15\.3 创建桌面管理面板快捷方式

在桌面右键选择“新建 → 快捷方式”，位置填写：

```Plain Text
http://127.0.0.1:8317/management.html
```

名称可以填写“CPA 管理面板”。该快捷方式只负责打开管理页面，不负责启动 CPA；如果服务尚未运行，需要先启动任务或运行 `start.ps1`。

### 15\.4 验证是否配置成功

```PowerShell
Get-ScheduledTask -TaskName "CLIProxyAPI - Local Proxy"
Start-ScheduledTask -TaskName "CLIProxyAPI - Local Proxy"
Get-Process -Name "cli-proxy-api"
Test-NetConnection 127.0.0.1 -Port 8317
(Invoke-WebRequest "http://127.0.0.1:8317/healthz").StatusCode
```

预期结果：任务存在且已启用，CPA 进程正在运行，8317 端口可连接，健康检查返回 `200`。

### 15\.5 AI 辅助配置提示词

```Plain Text
请帮我在 Windows 上为本机 CLIProxyAPI 配置登录后自启动。

要求：使用 Windows 任务计划程序，调用 CPA 根目录的 start.ps1；脚本根据自身位置定位 bin\cli-proxy-api.exe 和 config.yaml，并用 -config 启动；使用 Start-Process -WindowStyle Hidden 隐藏窗口；不要使用 VBS、启动文件夹或第三方服务。

先检查现有任务“CLIProxyAPI - Local Proxy”，存在就修改，不要重复创建；不要读取、输出或修改真实 API Key、密码和 OAuth 凭据。完成后验证任务、进程、8317 端口和 /healthz，并说明隐藏窗口是否被安全软件拦截。
```

## 十六、官方资料

- 官方仓库：[https://github\.com/router\-for\-me/CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)

- 官方中文 README：[https://github\.com/router\-for\-me/CLIProxyAPI/blob/main/README\_CN\.md](https://github.com/router-for-me/CLIProxyAPI/blob/main/README_CN.md)

- Quick Start：[https://help\.router\-for\.me/introduction/quick\-start](https://help.router-for.me/introduction/quick-start)

- 基础配置：[https://help\.router\-for\.me/configuration/basic](https://help.router-for.me/configuration/basic)

- 配置示例：[https://github\.com/router\-for\-me/CLIProxyAPI/blob/main/config\.example\.yaml](https://github.com/router-for-me/CLIProxyAPI/blob/main/config.example.yaml)

- Codex Provider：[https://help\.router\-for\.me/configuration/provider/codex](https://help.router-for.me/configuration/provider/codex)

- Claude Code Provider：[https://help\.router\-for\.me/configuration/provider/claude\-code](https://help.router-for.me/configuration/provider/claude-code)

- xAI / Grok Provider：[https://help\.router\-for\.me/configuration/provider/xai](https://help.router-for.me/configuration/provider/xai)

- Docker 部署：[https://help\.router\-for\.me/docker/docker](https://help.router-for.me/docker/docker)

> CPA 的命令、模型名称和配置项可能会随版本更新而变化。正式部署前，请以官方仓库和官方文档的最新内容为准。
> 
> 




本文介绍如何在本地部署 CLIProxyAPI（以下简称 CPA），并完成基础配置、账号登录、Provider 管理和运行维护。  官方仓库：https://github.com/router-for-me/CLIProxyAPI 官方文档：https://help.router-for.me/

CLIProxyAPI 本地部署指南：统一接入 Codex、Claude、xAI 等模型服务

从 Windows 安装、基础配置、OAuth 登录到 Provider 管理与自启动，完整介绍 CLIProxyAPI 的本地部署与安全验证流程。

编程语言

本地部署CLIProxyAPI（CPA）教程：涵盖Windows/Linux/macOS安装、OAuth登录Codex/Claude/Antigravity/xAI、OpenAI兼容Provider配置、模型别名设置、管理面板与热更新。提供安全合规建议、Windows自启动配置、常见故障排查及Docker部署方案，助您统一管理多模型API代理服务。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

本地部署CLIProxyAPI（CPA）教程：涵盖Windows/Linux/macOS安装、OAuth登录Codex/Claude/Antigravity/xAI、OpenAI兼容Provider配置、模型别名设置、管理面板与热更新。提供安全合规建议、Windows自启动配置、常见故障排查及Docker部署方案，助您...

CLIProxyAPI 本地部署指南：统一接入 Codex、Claude、xAI 等模型服务-腾讯云开发者社区-腾讯云

CLIProxyAPI 本地部署指南：统一接入 Codex、Claude、xAI 等模型服务

CLIProxyAPI 本地部署指南：统一接入 Codex、Claude、xAI 等模型服务

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐