背景

官方客户端

客户端	平台	特点
Claude Desktop	Windows / macOS	支持 MCP 插件、第三方模型接入
Claude Web	浏览器	网页版，无需安装
Claude iOS	iPhone / iPad	移动端
Claude Android	Android	移动端
Claude Code	命令行（Win/Mac/Linux）	专为编程设计的 CLI 工具

Claude Desktop 的 Third-Party Inference 功能存在两个限制：

模型名校验：要求填写真实的 Anthropic 模型名（如 claude-sonnet-4-5），私有模型名无法通过校验
API 格式不兼容：Claude Desktop 内部使用新版 Anthropic Responses API（/v1/responses），而私有网关只支持标准 OpenAI Chat Completions API（/v1/chat/completions），两者请求和响应格式均不同

本方案通过在本地运行一个 FastAPI 代理服务同时解决这两个问题。

之前有介绍过Responses API，以下是笔记本上实际操作，工具调用会消耗额外token，通过代理服务层面无法彻底优化，脚本会定时更新

目前已做成免安装版本，可以一键运行，下载链接：ClaudeProxy.zip

不想用免安装版，可以继续参照文档手动搭建。其次CC Switch v3.15.0 已支持模型映射，可以使用CC工具，功能更强，效果一样。

环境信息

操作系统：Windows
Python：3.13.2
私有模型网关：https://llm.test.com/v1
私有模型列表：
- pri-kimi-26
- pri-glm-51
- pri-deepseek-v4

架构说明

Claude Desktop → localhost:4000 (FastAPI 代理) → llm.test.com (私有模型)

FastAPI 代理的作用

FastAPI 代理是本方案的核心，主要承担以下职责：

1. Responses API → Chat Completions 格式转换


	Responses API（Claude Desktop 发出）	Chat Completions API（网关接收）
端点	`/v1/responses`	`/v1/chat/completions`
消息字段	`input`	`messages`
长度限制字段	`max_output_tokens`	`max_tokens`
响应格式	`content: [{type, text}]`	`choices: [{message: {content}}]`

代理负责在请求和响应两个方向上做格式互转，使双方无感知地正常通信。

2. 模型名称映射

Claude Desktop 填写的是 Anthropic 格式的模型名，代理将其映射为实际的私有模型名再转发：

claude-sonnet-4-5  →  pri-kimi-26
claude-haiku-4-5   →  pri-glm-51
claude-opus-4-5    →  pri-deepseek-v4

3. 工具调用支持（MCP）

代理处理完整的工具调用链路，包括：

Anthropic 工具定义格式 → OpenAI 格式转换
工具调用响应格式转换
多轮工具调用支持
工具描述截断 + schema 精简，减少 token 消耗约 20-30%

4. 其他能力

LRU 缓存：重复请求直接返回，节省 token
并发去重：相同请求同时到达时复用结果
自动重试：网关偶发错误时自动重试
流式响应：支持逐字输出
结构化日志：JSON 格式，便于分析
请求统计：访问 /stats 查看实时数据

操作步骤

第一步：创建 Python 虚拟环境

python -m venv C:\Users\ts\litellm-env

第二步：激活虚拟环境

& "C:\Users\ts\litellm-env\Scripts\Activate.ps1"

如果提示无法加载脚本，先执行以下命令，再重新激活：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

激活成功后命令行前会出现 (litellm-env) 前缀。

第三步：安装依赖

pip install fastapi uvicorn httpx pydantic-settings

第四步：创建 .env 配置文件

新建文件 C:\Users\ts\.env，填入实际配置（所有需要修改的内容都在这里，不需要改脚本）：

# 网关配置
TARGET=https://llm.test.com/v1
API_KEY=你的网关Key
PROXY_API_KEY=你自定义的代理访问Key

# 模型映射：右边填真实私有模型名
MODEL_SONNET=pri-kimi-26
MODEL_HAIKU=pri-glm-51
MODEL_OPUS=pri-deepseek-v4

# 部分参数可修改
CACHE_TTL=10
MAX_CACHE_SIZE=100
MAX_RETRIES=2
RETRY_DELAY=1.0
TOOL_DESC_MAX_LEN=100
CONNECT_TIMEOUT=5.0
READ_TIMEOUT=60.0
WRITE_TIMEOUT=10.0
LOG_FILE=proxy.log
TOOL_WHITELIST=
TOOL_BLACKLIST=

第五步：创建代理脚本

新建文件 C:\Users\ts\proxy.py，将下载的proxy.exe后缀改为proxy.py，下载链接如下：proxy.py

第六步：启动代理服务

uvicorn proxy:app --port 4000

看到以下输出说明启动成功：

Uvicorn running on http://127.0.0.1:4000

保持此 PowerShell 窗口开着不要关闭。

第七步：配置 Claude Desktop

打开 Claude Desktop → Settings → Developer → Configure Third-Party Inference，填写：


字段	值
Credential kind	Static API key
Gateway base URL	`http://localhost:4000`
Gateway API key	与 `.env` 中 `PROXY_API_KEY` 一致
Gateway auth scheme	bearer

在 Models 部分关闭 Model discovery，点击 Add model 依次添加三个模型：


Model ID	Display name
`claude-sonnet-4-5`	`Kimi-26（私有模型）`
`claude-haiku-4-5`	`GLM-51（私有模型）`
`claude-opus-4-5`	`DeepSeek-V4（私有模型）`

点击 Test connection，看到绿色提示即配置成功：

Inference — 1-token completion in xxxx ms · via static key

开机自启设置（可选）

避免每次手动启动代理，使用 pm2 管理（需要 Node.js）：

npm install -g pm2
npm install -g pm2-windows-startup
pm2-windows-startup install

pm2 start "uvicorn proxy:app --port 4000" --name claude-proxy --cwd "C:\Users\ts"
pm2 save

日常使用

每次使用前确保代理服务在运行：

& "C:\Users\ts\litellm-env\Scripts\Activate.ps1"
uvicorn proxy:app --port 4000

若已配置 pm2 开机自启，则无需手动操作，直接打开 Claude Desktop 即可。

实用接口

代理启动后可访问以下接口：


接口	说明
`http://localhost:4000/`	健康检查
`http://localhost:4000/stats`	查看请求统计、缓存命中率
`http://localhost:4000/admin/models`	查看当前模型映射（需鉴权）

后续新增模型

只需修改 .env 文件两处，无需改脚本：

1. 在 .env 中修改或新增模型映射（目前支持三个槽位）：

MODEL_SONNET=pri-kimi-26
MODEL_HAIKU=pri-glm-51
MODEL_OPUS=pri-新模型名

2. 在 Claude Desktop Model list 中添加对应的 Model ID。

重启代理后生效。

常见问题

Q：为什么不能直接在 Claude Desktop 里填私有模型名？ Claude Desktop 会校验模型名必须是真实的 Anthropic 模型名，私有模型名无法通过校验，因此需要代理层做名称映射。

Q：为什么不用 LiteLLM？ LiteLLM 与 Python 3.13 存在兼容性问题（imghdr 模块在 3.13 中被移除），且新版本会强制走 /v1/responses 接口，而私有网关只支持 /v1/chat/completions。

Q：代理服务会影响其他软件吗？ 不会。代理只监听 localhost:4000，只有主动配置指向它的软件才会使用，Cherry Studio、Chatbox 等工具直连网关，互不干扰。

Q：为什么每次请求 token 消耗较高？ Claude Desktop 会把所有已启用的 MCP 工具定义附加到每次请求中。代理已做了工具描述截断和 schema 精简，可通过 .env 中的 TOOL_DESC_MAX_LEN 调整截断长度。

Q：模型名填错了怎么排查？ 确认网关支持的模型名可执行：

python -c "
import httpx, json
r = httpx.get('https://llm.test.com/v1/models', headers={'Authorization': 'Bearer 你的网关Key'})
print(json.dumps(r.json(), indent=2, ensure_ascii=False))
"

Q：如何查看 token 消耗和缓存命中情况？ 访问 http://localhost:4000/stats 查看实时统计数据。

Claude Proxy 使用说明

软件简介

Claude Proxy 是一个本地代理服务，让 Claude Desktop 能够使用私有模型。无需安装任何环境，开箱即用。开发者：YJ

文件说明

ClaudeProxy.exe — 主程序（双击运行）
.env.template — 配置文件模板（按说明填写后改名为 .env）
.env — 配置文件（首次运行自动生成，需填写网关信息）
proxy.log — 运行日志（自动生成）
cache.pkl — 缓存文件（自动生成）
stats.json — 统计数据（自动生成）

首次使用步骤

第一步：创建配置文件

将 .env.template 复制一份，重命名为 .env（或双击运行 ClaudeProxy.exe 自动生成）
打开 .env，填写以下必填项：
- TARGET = 你的网关地址（如 https://xxx.com/v1）
- API_KEY = 你的网关 API Key
- PROXY_API_KEY = 自定义密码（后面填入 Claude Desktop）
- MODEL_SONNET = claude-sonnet-4-5 对应的私有模型名
- MODEL_HAIKU = claude-haiku-4-5 对应的私有模型名
- MODEL_OPUS = claude-opus-4-5 对应的私有模型名
保存 .env 文件

第二步：启动代理

双击 ClaudeProxy.exe，系统托盘出现图标即表示启动成功：

绿色图标：代理运行中（显示已运行时长）
红色图标：代理已停止

第三步：配置 Claude Desktop

进入：Settings → Developer → Configure Third-Party Inference

填写：

Credential kind: Static API key
Gateway base URL: http://localhost:4000
Gateway API key: 与 .env 中 PROXY_API_KEY 一致
Gateway auth scheme: bearer

关闭 Model discovery，手动添加模型：

claude-sonnet-4-5（可自定义显示名）
claude-haiku-4-5
claude-opus-4-5

点击 Test connection，出现绿色提示即成功。

托盘菜单说明

启动代理：启动代理服务
停止代理：停止代理服务
查看统计：打开统计页面
查看日志：打开 proxy.log
编辑配置：打开 .env
检测网关：手动检测连通性
开机自启：开关自启动
关于：查看版本与运行时长
退出：退出程序

统计页面（http://localhost:4000/stats）

1. 运行状态

运行时长、总请求数、缓存命中率、网关错误次数

2. Token 使用统计

输入/输出/总 Token 累计与平均消耗

3. 模型映射

Claude Desktop 模型名与私有模型对应关系

4. MCP 工具管理（重要）

支持三种过滤模式：

不过滤：所有工具发给模型（token 消耗最高）
白名单：仅勾选的工具发给模型（最省 token）
黑名单：勾选的工具不发给模型

操作步骤：

发送一条消息，等待工具列表出现
选择过滤模式
勾选需要保留或过滤的工具
点击保存设置
设置即时生效并写入 .env

.env 配置说明

必填项

TARGET=https://your-gateway.com/v1
API_KEY=your_key
PROXY_API_KEY=your_password
MODEL_SONNET=your-model-1
MODEL_HAIKU=your-model-2
MODEL_OPUS=your-model-3

可选项（默认值）

CACHE_TTL=10
MAX_CACHE_SIZE=100
MAX_RETRIES=2
RETRY_DELAY=1.0
TOOL_DESC_MAX_LEN=100
CONNECT_TIMEOUT=5.0
READ_TIMEOUT=60.0
WRITE_TIMEOUT=10.0
LOG_FILE=proxy.log
TOOL_WHITELIST=
TOOL_BLACKLIST=

Token 消耗说明

若简单消息消耗数万 token，通常是：

Claude Desktop 安装大量 MCP 插件
工具定义占用大量 token（55 个工具约 6 万 token）

解决方法：

打开统计页面
发送消息查看工具列表
使用黑名单过滤不需要的工具
或在 Claude Desktop 禁用不需要的 MCP 插件

修改配置后如何生效

方法一：编辑配置 → 保存，代理自动重启
方法二：停止代理 → 启动代理

常见问题

托盘无图标：等待 3–5 秒或查看 proxy.log
提示“请先在 .env 中填写真实配置”：填写真实网关地址与 Key
端口 4000 被占用：关闭占用程序或检查是否已运行代理
显示连接失败：检查托盘图标、API Key、proxy.log
自动重启失败：超过 3 次后停止，查看 proxy.log
日志太大：自动轮转，或手动删除
卸载：退出程序并删除文件夹

背景

官方客户端

环境信息

架构说明

FastAPI 代理的作用

1. Responses API → Chat Completions 格式转换

2. 模型名称映射

3. 工具调用支持（MCP）

4. 其他能力

操作步骤

第一步：创建 Python 虚拟环境

第二步：激活虚拟环境

第三步：安装依赖

第四步：创建 .env 配置文件

第五步：创建代理脚本

第六步：启动代理服务

第七步：配置 Claude Desktop

开机自启设置（可选）

日常使用

实用接口

后续新增模型

常见问题

Claude Proxy 使用说明

软件简介

文件说明

首次使用步骤

第一步：创建配置文件

第二步：启动代理

第三步：配置 Claude Desktop

托盘菜单说明

统计页面（http://localhost:4000/stats）

1. 运行状态

2. Token 使用统计

3. 模型映射

4. MCP 工具管理（重要）

.env 配置说明

必填项

可选项（默认值）

Token 消耗说明

修改配置后如何生效

常见问题

results matching ""

No results matching ""