连接 Claude Desktop

基于官方的 使用 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）：

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

2. 选择认证方式

Claude Desktop 提供多种方式。shunt 可以直接配合静态密钥（以及它的凭据 helper 变体），也支持由 shunt 自身充当设备码授权服务器的 bootstrap 登录；使用外部 IdP JWT 的 SSO 是网关侧的能力，shunt 不支持这种入站认证。

静态 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 都可以使用：

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

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

Bootstrap 登录（设备码）

Claude Desktop 可以从 bootstrap URL 获取配置，并通过针对同一服务器的 OAuth 设备码 grant 让用户登录（Anthropic 的 bootstrap 指南，“Bootstrap server as authorization server (device code)” 模式）。shunt 支持该模式：每位用户在 shunt 的 /device 页面用密码或你的 OIDC IdP 登录一次，Desktop 随后把这个 bearer 也用于推理。设备上除 Claude Desktop 外无需安装任何东西，也不必在各台机器上维护 helper 脚本路径。

1. 启用网关登录。 配置 [server.gateway]，包括 public_url、签名密钥，以及静态用户或 OIDC IdP。该模式要求 shunt 前面有带 TLS 的真实主机名：Anthropic 的指南将 bootstrap 端点描述为 HTTPS，而打包发布的 Desktop 应用会从响应键中丢弃回环 URL（127.0.0.1、localhost、[::1]）。

2. 让 shunt 指向模板。

[server.gateway.desktop_bootstrap]
template = "/etc/shunt/claude-desktop-bootstrap.json"   # 仅支持文件路径

该文件必须存在且是 JSON 对象，否则配置加载（以及 shunt check）会失败。shunt 在每次请求时读取它，因此修改无需重启即可生效。可以使用 Desktop 自己的 JSON 导出所生成的嵌套 v2 格式，也可以使用扁平 v1 格式；shunt 原样返回：

{
  "$schemaVersion": 2,
  "inference": {
    "provider": "gateway",
    "baseUrl": "https://shunt.example.corp",
    "credential": { "kind": "interactive" }
  },
  "otlp": {
    "resourceAttributes": { "user.email": "${user.email}" }
  }
}

扁平 v1 的等价写法是 {"inferenceProvider":"gateway","inferenceGatewayBaseUrl":"https://shunt.example.corp","inferenceCredentialKind":"interactive","otlpResourceAttributes":{"user.email":"${user.email}"}}。

• 网关 base URL 必须是 shunt 的 public_url。 没有 bootstrapOidc 时，Desktop 会丢弃与 bootstrapUrl 不同源的网关 base URL。同源并使用 interactive 凭据时，Desktop 才会把 bootstrap bearer 复用于推理（从 1.34493.0 起还会用 refresh grant 续期），用户只需登录一次。
• 占位符。 字符串值中的 ${user.email}、${user.sub}、${user.name} 会替换为已登录用户的值。未知的 ${...} 标记保持原样，对象键从不替换。
• 返回所有希望生效的键。 响应中的键就是实际生效的配置：模板中省略的键会被取消设置，而不是从 MDM 继承。

3. 分发种子文件。 每位用户通过 Developer → Configure Third-Party Inference… → Import configuration 导入：

{
  "bootstrapUrl": "https://shunt.example.corp/user/bootstrap",
  "trustBootstrapDelivery": true
}

bootstrapUrl 的 origin 必须与 public_url 的 origin 相同。Desktop 会去掉末尾的 /user/bootstrap 来找到 shunt 的 OAuth 发现文档，执行设备码登录，然后用签发的 bearer 请求 GET /user/bootstrap。当 bootstrap 响应向一台由本地文件配置的设备下发 base URL、helper 或 marketplace 值时，Desktop 通常会弹出 “Apply settings from your organization?” 对话框，trustBootstrapDelivery 可以跳过它。Desktop 只接受来自 MDM 或本地文件的该键，从不接受来自 bootstrap 响应的值。

谁会拿到配置。 授权判断复用 [[server.gateway.policies]]：没有 policy 时，所有已登录用户都有权获取；有 policy 时，用户被某条 policy 的 match.emails 列出，或存在 catch-all policy（无 match），才有权获取。其他用户收到 403。未配置 desktop_bootstrap 时该路由返回 404。响应带有 ETag，因此 Desktop 的后台复查（默认每 10 分钟一次）通常只产生一次 304。

Desktop 只在内存中保留响应。如果启动时无法连接 shunt，Desktop 会以降级的登录状态启动 —— 这与推理本来就有的依赖相同。在 Desktop 中退出登录只在本地生效：shunt 不公布 revocation 端点。各状态码见端点参考。

3. 选择模型

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

发现过滤器。 Claude Desktop 的自动发现只显示可识别为 Claude 的 id —— 即 tier 命名的 id（claude-sonnet-*、claude-opus-*、claude-haiku-*、claude-fable-*）。shunt 的内置目录是 Anthropic API 与参考 Claude apps gateway 所提供列表的超集 —— 其中有十四个 tier 命名的 id，因此 Claude Desktop 会显示全部模型。这是回退用的快照;当 shunt 能够访问你的 Anthropic 上游时,会改为提供该调用方自己的实际列表(参见模型发现)。

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

维护的 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 作为后备方案。