CLIProxyAPI

链路概览

本教程最终形成以下调用链：

Chatbox → CLIProxyAPI → SOCKS5 代理 → CoffeeRouter → 上游模型

开始前请准备：

• 一个 CoffeeRouter 令牌，以及该令牌允许使用的准确模型 ID。
• Windows PowerShell。
• 如果需要通过代理访问 CoffeeRouter，一个已经运行的 SOCKS5 代理。本教程示例地址为 socks5://127.0.0.1:7897。
• 与 CLIProxyAPI 运行在同一台 Windows 电脑上的 Chatbox。

1. 下载并解压 CLIProxyAPI

前往 CLIProxyAPI Releases 下载最新的 Windows amd64 压缩包，文件名通常类似：

CLIProxyAPI_<版本号>_windows_amd64.zip

解压到您自己管理的目录。发行包中通常包含 cli-proxy-api.exe、config.example.yaml、README 和许可证文件。

在同一目录中新建 config.yaml，不要直接修改 config.example.yaml。后续升级时，示例文件可能被新版本覆盖；独立的 config.yaml 更便于保留和迁移配置。

CLIProxyAPI 可提供 Web 管理中心，但程序本身没有完整的原生桌面界面，Windows 建议通过 PowerShell 启动。完成本教程后，工作目录中至少应有：

• cli-proxy-api.exe
• config.yaml
• README.md 或 README_CN.md

2. 配置 config.yaml

以下是与本教程对应的最小示例。请替换三个占位值，不要在公开文档、截图或 Git 仓库中保存真实密钥：

host: "127.0.0.1"
port: 8317

remote-management:
  allow-remote: false
  secret-key: "replace-with-a-strong-management-key"
  disable-control-panel: false

auth-dir: "~/.cli-proxy-api"

api-keys:
  - "replace-with-a-strong-local-key"

debug: false
logging-to-file: true

openai-compatibility:
  - name: "coffeerouter"
    base-url: "https://www.coffeerouter.ai/v1"
    api-key-entries:
      - api-key: "sk-your-coffeerouter-key"
        proxy-url: "socks5://127.0.0.1:7897"
    models:
      - name: "your-upstream-model-id"
        alias: "your-local-model-alias"

关键字段说明：

字段	用途
host: "127.0.0.1"	只允许本机连接，避免服务直接暴露到局域网或公网
remote-management.secret-key	登录管理中心使用的独立管理密钥
顶层 api-keys	Chatbox 等本地客户端访问 CLIProxyAPI 时使用的本地 Key
base-url	CoffeeRouter OpenAI 兼容地址，必须保留一个 /v1
api-key-entries[].api-key	从 CoffeeRouter 后台获取的上游 Key
api-key-entries[].proxy-url	此上游 Key 使用的网络代理
models[].name	CoffeeRouter 中显示的真实模型 ID
models[].alias	本地客户端填写的模型名，可自行定义

本教程假设 SOCKS5 代理确实监听 127.0.0.1:7897。如果您的网络可以直接访问 CoffeeRouter，请删除 proxy-url；不要填写一个没有运行的代理端口。

3. 启动服务并打开管理后台

在 PowerShell 中进入解压目录并启动：

cd "D:\迅雷下载\CLIProxyAPI_7.2.74_windows_amd64"
.\cli-proxy-api.exe --config .\config.yaml

目录名称中的版本号只是示例，请以您实际下载的版本为准。

看到服务成功监听 127.0.0.1:8317 后，不要关闭此 PowerShell 窗口；关闭窗口或按 Ctrl+C 会停止服务。

在浏览器打开：

http://127.0.0.1:8317/management.html

使用 remote-management.secret-key 中设置的管理密钥登录。管理中心与模型请求使用的本地 Key 不是同一个密钥。

首次打开管理中心时，CLIProxyAPI 可能需要下载管理面板资源。请保持 disable-control-panel: false，并确保当前网络能够访问面板资源。

4. 在 CLIProxyAPI 中添加 CoffeeRouter

进入 AI Providers → OpenAI Compatible，新增或编辑一个提供商，填写：

配置项	填写内容
Name	coffeerouter
Base URL	https://www.coffeerouter.ai/v1
API key entry	CoffeeRouter 上游令牌，例如 sk-your-coffeerouter-key
Proxy URL	socks5://127.0.0.1:7897，仅在该代理确实运行时填写
Test model	选择当前令牌允许使用的模型

在 Custom models 中添加需要使用的模型：

• name：填写 CoffeeRouter 中显示的上游真实模型 ID。
• alias：填写给本地客户端使用的名称，例如 coffee-claude-opus-4-8。
• 可以添加多个模型；每个模型都应使用唯一 alias。

保存后返回列表。状态正常时应显示 Active，并显示对应的模型数和 Key 数，例如 Models 1、Keys 1。

5. 理清两个 API Key 和代理

模型请求链路中有两个 API Key：

1. CLIProxyAPI 本地 Key：自行生成，写入顶层 api-keys；Chatbox 请求本机 8317 端口时使用。
2. CoffeeRouter 上游 Key：在 CoffeeRouter 后台生成，写入 openai-compatibility[].api-key-entries[].api-key；CLIProxyAPI 请求 CoffeeRouter 时使用。

此外，remote-management.secret-key 是第三个独立的管理密钥，只用于登录管理后台，不参与模型请求。

本教程的网络代理为：

socks5://127.0.0.1:7897

它负责 CLIProxyAPI 到 CoffeeRouter 的网络连接，不应填写到 Chatbox 中。请先确认对应代理程序正在监听端口 7897。

6. 使用 PowerShell 验证本地链路

先检查 8317 端口：

Test-NetConnection 127.0.0.1 -Port 8317

TcpTestSucceeded = True 表示本机端口已监听，但不代表上游模型一定可用。继续发送一个实际请求：

$localKey = "replace-with-a-strong-local-key"
$body = @{
    model = "your-local-model-alias"
    messages = @(
        @{ role = "user"; content = "Reply only OK" }
    )
    stream = $false
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
    -Uri "http://127.0.0.1:8317/v1/chat/completions" `
    -Method Post `
    -Headers @{ Authorization = "Bearer $localKey" } `
    -ContentType "application/json" `
    -Body $body

请将 $localKey 替换为顶层 api-keys 中的本地 Key，将模型替换为您配置的 alias。返回内容中出现 OK，表示完整链路已经打通。

成功链路为：

本地请求 → CLIProxyAPI → SOCKS5 → CoffeeRouter → 上游模型

7. 在 Chatbox 中配置并测试

在 Chatbox 中进入 Settings → Model Provider → Add → Add Custom Provider，填写：

配置项	填写内容
Name	CLIProxyAPI
API Mode	OpenAI API Compatible
API Key	CLIProxyAPI 顶层 api-keys 中的本地 Key
API Host	http://127.0.0.1:8317/v1
API Path	/chat/completions
Model	CLIProxyAPI 中配置的模型 alias

Chatbox 中不要填写 CoffeeRouter 上游 Key。真实上游 Key 只保存在 CLIProxyAPI 的 api-key-entries 中。

点击 Check 或 Fetch 验证配置，回到聊天页面选择对应模型并发送测试消息。

127.0.0.1 只代表当前设备。本教程要求 Chatbox 和 CLIProxyAPI 运行在同一台电脑上；如果 Chatbox 在另一台设备上，不能继续使用这个地址，也不建议直接把管理后台暴露到局域网或公网。

常见问题与安全提示

管理后台返回 404

确认 remote-management.secret-key 不是空值，并且 disable-control-panel 为 false。首次打开时还需确保管理面板资源可以正常下载。

8317 端口检测失败

确认 PowerShell 启动窗口仍在运行，检查 config.yaml 是否有 YAML 缩进错误，并确认端口没有被其他程序占用。

返回 401 或 Invalid API Key

客户端请求本机接口时必须使用顶层 api-keys 中的本地 Key；CoffeeRouter 上游 Key 只能填写在 api-key-entries 中。

请求超时或无法连接 CoffeeRouter

如果设置了 socks5://127.0.0.1:7897，请确认代理程序和端口确实可用。不需要代理时删除 proxy-url 后再测试。

提示模型不存在

检查本地请求使用的是模型 alias，并确认对应 name 与 CoffeeRouter 令牌管理页显示的模型 ID 完全一致。

官方资料

• CLIProxyAPI 官方仓库
• 最新版本与 Windows 下载
• 官方配置模板
• CLIProxyAPI 官方指南