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

本文介绍如何在本地部署 CLIProxyAPI（以下简称 CPA），并完成基础配置、账号登录、Provider 管理和运行维护。

官方仓库：https://github.com/router-for-me/CLIProxyAPI
官方文档：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 页面：

https://github.com/router-for-me/CLIProxyAPI/releases/latest

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

C:\Tools\CLIProxyAPI

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

3.2 创建配置文件

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

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

将文件保存为：

C:\Tools\CLIProxyAPI\config.yaml

3.3 AI Agent 辅助配置提示词

请帮我下载并配置 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. 本地使用时建议将服务绑定到：

host: "127.0.0.1"

1. 并保持：

remote-management:
  allow-remote: false

1. 不要直接将 8317 端口或管理页面暴露到公网。确实需要远程访问时，应额外配置访问认证、HTTPS、防火墙和访问来源限制。
2. 不要将 ~/.cli-proxy-api、config.yaml、日志目录和备份文件上传到 Git 仓库、网盘或公开位置。
3. 排查问题时如果开启了调试日志或请求日志，应注意其中可能包含请求内容、响应内容或敏感信息；问题排查完成后应及时关闭并清理。
4. 如果怀疑认证信息或 API Key 已经泄露，应立即停止 CPA，撤销或重新登录相关账号，更换 CPA 的 api-keys 和管理密钥，并检查日志、备份文件和访问记录。

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

五、基础配置

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

# 仅允许本机访问
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 保持一致。

配置项说明：

<sheet sheet-id="CmcUdr" token="EasfsREl6hypVLtaL2fcMaTQnEe"></sheet>

本地使用时建议保持：

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 根目录（以下路径仅为示例）：

cd C:\Tools\CLIProxyAPI

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

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

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

.\bin\cli-proxy-api.exe

本地访问地址为：

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

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

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

7.2 登录 Claude Code

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

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

7.3 登录 Antigravity

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

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

7.4 登录 xAI / Grok

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

xAI OAuth 默认使用：

127.0.0.1:56121/callback

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

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

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

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

[CPA安装目录]\auths

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

八、配置 OpenAI 兼容 Provider

如果使用 API Key 接入第三方 OpenAI 兼容服务，可以在 config.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。

例如：

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"

九、配置模型别名

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

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

之后 CPA 内部使用：

my-model

模型别名适合以下场景：

• 在多个 Provider 之间使用统一名称；
• 后续更换 Provider 时减少配置修改；
• 为不同渠道设置容易识别的名称。

十、使用管理页面

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

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

可以在浏览器中打开：

http://127.0.0.1:8317/management.html

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

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

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

十一、配置热更新

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

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

• 服务端口；
• 监听地址；
• OAuth 登录状态；
• 认证目录；
• 进程启动方式。

重新启动：

.\stop.ps1
.\start.ps1

十二、日志与使用量统计

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

debug: true

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

logging-to-file: true

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

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

• CPA Usage Keeper；
• CPA-Manager-Plus。

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

十三、常见问题

端口被占用

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

port: 8318

修改后重新启动 CPA。

OAuth 登录失败

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

• Codex：1455
• Claude Code：54545
• Antigravity：51121
• xAI：56121

找不到配置文件

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

.\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 官方安装方式：

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

macOS Homebrew 安装：

brew install cliproxyapi
brew services start cliproxyapi

Docker 启动：

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 启动说明）、官方基础配置、官方 Releases 下载页。

15.1 准备启动脚本

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

$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 创建桌面管理面板快捷方式

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

http://127.0.0.1:8317/management.html

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

15.4 验证是否配置成功

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 辅助配置提示词

请帮我在 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
• 官方中文 README：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/configuration/basic
• 配置示例：https://github.com/router-for-me/CLIProxyAPI/blob/main/config.example.yaml
• Codex Provider：https://help.router-for.me/configuration/provider/codex
• Claude Code Provider：https://help.router-for.me/configuration/provider/claude-code
• xAI / Grok Provider：https://help.router-for.me/configuration/provider/xai
• Docker 部署：https://help.router-for.me/docker/docker

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