连接 Claude Desktop

将 Claude Desktop 的第三方推理指向 shunt、配置认证并选择模型。

基于官方的使用 LLM 网关部署 Claude Desktop 指南 —— shunt 就是你要指向的那个网关。shunt 实现了 Anthropic Messages API（支持流式传输和工具使用的 POST /v1/messages）以及可选的 GET /v1/models，这正是 Claude Desktop 第三方推理所期望的网关契约。

1. 将 Claude Desktop 指向 shunt

在 Developer → Configure Third-Party Inference… 中，将 Inference provider 设置为 Gateway，并将 Gateway base URL 设置为正在运行的 shunt（默认绑定 127.0.0.1:3001）：

Claude Desktop 键	值
`inferenceProvider`	`gateway`
`inferenceGatewayBaseUrl`	`http://127.0.0.1:3001`（或你的公开 shunt URL）

shunt 提供纯 HTTP；除回环部署外，都应像共享网关一样，在前置服务中终止 TLS 或通过隧道访问。

2. 选择认证方式

Claude Desktop 提供三种方式。shunt 可以直接配合静态密钥（以及它的凭据 helper 变体）；按用户 SSO 是网关侧的能力，shunt 不支持这种入站认证。

Claude Desktop 方式	shunt 侧	说明
静态 API 密钥（`inferenceGatewayApiKey`）	`[server.auth]` 客户端 token	推荐。
凭据 helper（`inferenceCredentialHelper`）	输出 `[server.auth]` 客户端 token 的可执行文件	适用于已经签发网关凭据的组织。
交互式 SSO（`inferenceGatewayOidc` + `inferenceCredentialKind: interactive`）	不支持入站	shunt 验证静态 token，而不是外部 IdP JWT —— 见下文。

静态 API 密钥（推荐）

在 shunt 上启用 [server.auth]，并为每位用户分配一个客户端 token：

[server.auth]
header = "x-shunt-token"          # 默认
tokens_env = "SHUNT_CLIENT_TOKENS"

将该 token 填入 Claude Desktop 的 inferenceGatewayApiKey。shunt 接受通过 Authorization: Bearer 或 x-api-key 传入的客户端 token，因此两种 Gateway auth scheme 都可以使用：

Claude Desktop 键	值
`inferenceGatewayApiKey`	你的 shunt 客户端 token
`inferenceGatewayAuthScheme`	`bearer`（默认）或 `x-api-key`

未配置 [server.auth] 时，shunt 不要求入站凭据（适合个人回环网关）；Claude Desktop 仍要求填写该字段，因此可以输入任意占位值。

该 token 会门控 GET /v1/models 和注入凭据的模型（映射/池化模型）；透传模型保持开放，并携带运营者自己的提供方凭据。

3. 选择模型

shunt 提供 GET /v1/models，因此 Claude Desktop 会在启动时自动发现并填充模型选择器。显示哪些模型由以下两项因素决定。

发现过滤器。 Claude Desktop 的自动发现只显示可识别为 Claude 的 id —— 即 tier 命名的 id（claude-sonnet-*、claude-opus-*、claude-haiku-*、claude-fable-*）。shunt 的内置目录与参考 Claude apps gateway 完全一致 —— 其中有九个 tier 命名的 id，因此 Claude Desktop 会显示全部模型：

// GET /v1/models — 内置目录（auto_include_builtin_models），全部采用 tier 命名
// （每个条目还带有 "type": "model"）
{ "data": [
  { "id": "claude-opus-4-6" },   { "id": "claude-sonnet-4-5-20250929" },
  { "id": "claude-haiku-4-5-20251001" }, { "id": "claude-fable-5" },
  { "id": "claude-opus-4-8" },   { "id": "claude-opus-4-7" },
  { "id": "claude-opus-4-1-20250805" },  { "id": "claude-sonnet-5" },
  { "id": "claude-sonnet-4-6" }
], "has_more": false, "first_id": null, "last_id": null }

维护的 claude-<slug>-via-<provider> 别名（可用于 Claude Code 的模式）会被 Claude Desktop 丢弃 —— 见模型发现 → Claude Desktop 只识别 tier 命名的 id。

公开非 Anthropic 后端。 有两种方式：

映射一个 tier 命名的 id，通过 [[routes]] 的 upstream_model 让在 Desktop 中选择该 id 时解析到你的后端：

[[routes]]
model = "claude-sonnet-5"        # Claude Desktop 识别的 tier 命名 id
provider = "codex"
upstream_model = "gpt-5.6-sol"   # 真实后端 slug

在 Desktop 侧覆盖发现，通过显式的 inferenceModels 列表填写 shunt 实际路由的确切 id。如果每个条目都是完整 id，Claude Desktop 会跳过 /v1/models 请求。

4. 验证

确认 shunt 能使用客户端 token 响应发现和推理请求：

# 发现 —— 设置 [server.auth] 后由 token 门控
curl -s "$SHUNT_URL/v1/models" -H "Authorization: Bearer $SHUNT_CLIENT_TOKEN" | jq '.data[].id'

# 你映射的 tier 命名 id -> 分流到后端
curl -s -X POST "$SHUNT_URL/v1/messages" \
  -H "Authorization: Bearer $SHUNT_CLIENT_TOKEN" \
  -H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

然后打开 Claude Desktop；模型选择器中应列出 tier 命名的条目。如果选择器为空，说明发现结果已被过滤掉（id 不是 tier 命名）或无法访问 /v1/models —— 请显式设置 inferenceModels 作为后备方案。