背景

windows安装的Claude Desktop无法添加私有模型，之前在Responses API文章里面提到过解决方法，今天就在笔记本上实测下，需要在笔记本上搭建一个代理服务即可。

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 代理服务同时解决这两个问题。

环境信息

操作系统：Windows
Python：3.13.2
私有模型网关：https://llm.test.com/v1(实际请填写内网部署的llm地址)
私有模型列表：
- 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. 兼容不同响应格式

不同私有模型返回的响应结构可能不同，代理做了兼容处理，自动识别并统一转换。

操作步骤

第一步：创建 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

第四步：创建代理脚本

新建文件 C:\Users\ts\proxy.py，内容如下（将 你的真实Key 替换为实际的 API Key）：

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
import httpx, json

app = FastAPI()

TARGET = "https://llm.test.com/v1"
API_KEY = "你的真实Key"

# 模型名称映射表：Claude Desktop 填的名字 → 实际私有模型名
MODEL_MAP = {
    "claude-sonnet-4-5": "pri-kimi-26",
    "claude-haiku-4-5":  "pri-glm-51",
    "claude-opus-4-5":   "pri-deepseek-v4",
}

@app.post("/v1/responses")
@app.post("/v1/messages")
async def proxy(request: Request):
    body = await request.json()
    requested_model = body.get("model", "claude-sonnet-4-5")
    actual_model = MODEL_MAP.get(requested_model, "pri-kimi-26")

    messages = body.get("messages", [])
    if not messages:
        input_text = body.get("input", "")
        messages = [{"role": "user", "content": input_text}]

    payload = {
        "model": actual_model,
        "messages": messages,
        "max_tokens": body.get("max_output_tokens", 1024),
        "stream": False,
    }

    async with httpx.AsyncClient(timeout=60) as client:
        resp = await client.post(
            f"{TARGET}/chat/completions",
            json=payload,
            headers={"Authorization": f"Bearer {API_KEY}"},
        )

    data = resp.json()

    # 兼容不同返回格式
    if "choices" in data:
        content = data["choices"][0]["message"]["content"]
    elif "content" in data:
        blocks = data["content"]
        content = blocks[0]["text"] if isinstance(blocks, list) else blocks
    else:
        content = str(data)

    return JSONResponse({
        "id": data.get("id", "msg_001"),
        "type": "message",
        "role": "assistant",
        "content": [{"type": "text", "text": content}],
        "model": requested_model,
        "stop_reason": "end_turn",
        "usage": data.get("usage", {})
    })

第五步：启动代理服务

uvicorn proxy:app --port 4000

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

Uvicorn running on http://0.0.0.0: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	任意填，如 `sk-any`
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 即可。

后续新增模型

如需添加更多私有模型，只需两步：

1. 在 proxy.py 的 MODEL_MAP 中添加映射：

MODEL_MAP = {
    "claude-sonnet-4-5": "pri-kimi-26",
    "claude-haiku-4-5":  "pri-glm-51",
    "claude-opus-4-5":   "pri-deepseek-v4",
    "claude-sonnet-4-6": "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：模型名填错了怎么排查？ 在代理日志中会打印实际请求的模型名和网关返回内容，确认网关支持的模型名可执行：

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))
"

Claude Desktop 接入私有模型指南

背景