跳转到内容

配置:CLIProxyAPI

通过本地Chat Completions代理CLIProxyAPI将TomoriBot连接到已获授权的上游服务。

按照官方快速入门进行安装。发布压缩包包含开箱即用的可执行文件;选择对应你的操作系统与CPU架构,解压压缩包并核验其校验和。从Git克隆构建源码是可选操作。

启动CLIProxyAPI之前先完成配置。如果安装程序已经启动了系统服务,请先停止它。

在可执行文件(Windows上为cli-proxy-api.exe)同级目录下创建config.yaml。使用独立的配置文件夹是可选做法;以下示例将两个文件放在同一目录。请使用密码管理器生成至少32字节的随机内容,编码为十六进制或base64后替换客户端密钥占位符。

config-version: 8
server:
host: "127.0.0.1"
port: 8317
discovery:
enabled: false
management:
allow-remote: false
secret-key: ""
disable-control-panel: true
access:
api-keys:
- "REPLACE_WITH_RANDOM_CLIENT_KEY"
oauth:
auth-dir: "~/.cli-proxy-api"

access.api-keys下的客户端密钥用于TomoriBot向CLIProxyAPI进行身份验证。请将config.yaml与oauth.auth-dir中的凭据文件妥善私密保存,不要放入Git仓库,并将访问权限仅限制为你自己的账号与运行进程的账号。

请保持MANAGEMENT_PASSWORD未设置,也不要使用--password或管理TUI:空的管理密钥会让管理路由始终处于禁用状态,即使在隧道后方也是如此。如果你下载的版本使用了不同的配置格式,请将这些设置套用到其自带的config.example.yaml中。

选择CLIProxyAPI向模型提供方进行身份验证的方式。两种方式均共用上方的基础配置。

在包含可执行文件与config.yaml的文件夹中运行登录命令。下方示例以Antigravity为例;请替换为你的提供方对应的参数,并在登录前仔细阅读授权同意界面:

提供方登录参数
Antigravity--antigravity-login
Claude--claude-login
Codex--codex-login或--codex-device-login
Terminal window
$configPath = (Resolve-Path .\config.yaml).Path
.\cli-proxy-api.exe --config $configPath --antigravity-login

完成浏览器登录并等待终端提示成功。CLIProxyAPI会将凭据保存在oauth.auth-dir中;纯OAuth配置不需要添加上游API密钥配置块。请保持OAuth回调监听在本地,并在登录与启动时使用相同的配置路径。其他登录参数见--help与上游提供方指南。

在包含config.yaml的文件夹中启动服务器。如路径不同请替换为可执行文件的实际路径或已安装的指令;请保留--config以确保加载此配置文件。

Terminal window
$configPath = (Resolve-Path .\config.yaml).Path
.\cli-proxy-api.exe --config $configPath

保持服务器运行,继续第5步。请将server.host保持为127.0.0.1;不需要添加入站防火墙例外或路由器端口转发规则。

  1. 对于与CLIProxyAPI运行在同一台电脑上的非生产环境bot,请在TomoriBot的环境变量中设置ALLOW_PRIVATE_NETWORK=127.0.0.1:8317并重启bot。使用上方配置的本地监听地址即可,无需隧道。
  2. 运行/providers(服务器管理员)或/personal providers,按以下设置添加一个OpenAI 兼容自定义端点:
字段值
端点URLhttp://127.0.0.1:8317/v1
认证令牌来自access.api-keys的客户端密钥

选中已保存的连接,使用CLIProxyAPI提供的ID或别名添加一个文本模型,然后确认在Discord中可以正常回复。

此URL假设bot直接运行在宿主机上。在Docker中,127.0.0.1指向容器自身,因此无法通过该地址访问宿主机的监听。以生产模式运行的bot仍然需要走独立托管生产环境方案。

如何列出可用模型

在CLIProxyAPI运行期间,打开另一个终端列出其模型ID。加载客户端密钥前请先关闭PowerShell脚本记录或Shell命令追踪,完成后关闭该终端。

在包含config.yaml的文件夹中运行;它会从上方配置格式中读取第一个客户端密钥。

Terminal window
$keyMatch = [regex]::Match((Get-Content -LiteralPath .\config.yaml -Raw), '(?m)^access:\r?\n api-keys:\r?\n - "([A-Za-z0-9+/=_-]+)"[ \t]*\r?$')
if (!$keyMatch.Success) { throw 'Expected a quoted client key under access.api-keys in config.yaml.' }
$engineKey = $keyMatch.Groups[1].Value
$headers = @{ Authorization = "Bearer $engineKey" }
$base = 'http://127.0.0.1:8317/v1'
$models = Invoke-RestMethod "$base/models" -Headers $headers
$models.data | Select-Object id
Remove-Variable engineKey, keyMatch, headers

返回空列表说明仍需配置上游服务。HTTP 401表示服务器已响应,但拒绝了该客户端密钥。

症状处理方式
401核对客户端密钥,注意与上游密钥区分。
404使用/v1基础路径,不要包含/chat/completions;并核对模型ID。
参数被拒绝将上下文窗口留空,并将思考等级保持在自动;在开始输出前,TomoriBot本身就会对符合条件的参数拒绝进行重试。在开启工具调用或依赖采样参数前,先检查日志中是否存在降级请求。
403、HTML登录页或隧道错误检查隧道配置。如果启用了Cloudflare Access,需要配置可选的Access与Caddy方案;Discord面板无法直接提供Access请求头。
流式输出中断检查电脑是否休眠、上游配额、隧道健康状况以及Cloudflare指南中的流式传输限制。

除非正在排查经过脱敏的本地复现问题,否则请保持请求/调试日志关闭。如果客户端密钥泄露,请在CLIProxyAPI、TomoriBot已保存的端点以及使用它的可选中继中同时轮换密钥。若上游凭据泄露,请另行撤销。

停用账号登录

在上游账号设置中撤销授权,停止代理,然后删除其本地凭据文件。仅删除文件并不会吊销令牌。

检查本地监听地址

如果无法访问本地API,请在CLIProxyAPI运行期间从另一个终端检查其监听地址:

Terminal window
Get-NetTCPConnection -LocalPort 8317 |
Select-Object LocalAddress, LocalPort, State, OwningProcess

监听地址应当只有127.0.0.1;如果看到0.0.0.0、::、*或局域网地址,请立即停止。检查现有的防火墙规则(Windows上为wf.msc);不要开放入站端口或添加路由器端口转发。Windows的TCP状态查询可能会漏掉可达的端点,因此命令包含了所有状态;上方的可选模型列表命令可直接测试API可达性。

测试本地回复

如果模型在Discord中无法回复,请在CLIProxyAPI运行期间直接测试它。加载客户端密钥前请先关闭PowerShell脚本记录或Shell命令追踪。

在包含config.yaml的文件夹中运行;它会从上方配置格式中读取第一个客户端密钥。

Terminal window
$keyMatch = [regex]::Match((Get-Content -LiteralPath .\config.yaml -Raw), '(?m)^access:\r?\n api-keys:\r?\n - "([A-Za-z0-9+/=_-]+)"[ \t]*\r?$')
if (!$keyMatch.Success) { throw 'Expected a quoted client key under access.api-keys in config.yaml.' }
$engineKey = $keyMatch.Groups[1].Value
$headers = @{ Authorization = "Bearer $engineKey" }
$base = 'http://127.0.0.1:8317/v1'
$body = @{
model = Read-Host 'Model ID to test'
messages = @(@{ role = 'user'; content = 'Reply with hello.' })
stream = $false
} | ConvertTo-Json -Depth 4
$reply = Invoke-RestMethod "$base/chat/completions" -Method Post -Headers $headers -ContentType 'application/json' -Body $body
$reply.choices.message.content
Remove-Variable engineKey, keyMatch, headers

收到生成的回复即可确认上游访问正常。仅靠套接字查询没有结果并不能证明API不可达。