分享Claude Code Desktop配置文件解决模型显示不全问题

背景

Claude Code Desktop 是 Anthropic 推出的桌面端 AI 编程助手，旨在为开发者提供高效的代码生成、重构及调试体验。随着 Anthropic 不断推出新的模型版本（如 Claude 3.5 Haiku、Claude 3.7 Sonnet 以及最新的 Claude 4 系列），官方客户端有时会出现模型列表显示不全、无法识别新模型或配置同步滞后等问题。

许多高级用户选择通过 Claude Code Gateway（网关）来管理模型调用，以便获得更灵活的访问控制和成本优化。然而，当使用第三方网关或自定义配置时，Claude Code Desktop 往往无法自动识别所有可用的新模型，导致用户在界面下拉菜单中找不到最新发布的模型。为了解决这一“模型显示不全”的痛点，社区用户分享了一套 JSON 格式的配置文件，通过手动导入的方式强制客户端识别并显示特定的模型列表。

核心内容

该分享的核心在于提供一段完整的 JSON 配置代码，用于覆盖或补充 Claude Code Desktop 的默认模型配置。用户需要在开启开发者模式后，通过菜单路径 Developer => Configure Third-Party Inference… => 对话框右上角配置 => Import configuration… 导入此文件。

配置文件的结构主要包含以下几个关键部分：

1. 网关连接信息：

   • inferenceGatewayBaseUrl：指定推理网关的基础 URL（示例中为占位符 https://xxxxxxx，用户需替换为实际地址）。
   • inferenceGatewayApiKey：指定访问网关所需的 API 密钥（示例中为占位符 sk-XXXXXXXXXX）。
   • inferenceProvider：设置为 "gateway"，表明使用外部网关而非官方直接连接。
   • inferenceCredentialKind：设置为 "static"，表示使用静态密钥认证。

2. 模型列表定义 (inferenceModels)： 这是配置的核心，列出了客户端应显示的模型及其属性。每个模型对象包含：

   • name：模型的唯一标识符（ID），通常对应 Anthropic 官方模型 ID。
   • labelOverride：在客户端界面中显示的名称，优化了可读性（例如将 claude-3-5-haiku-20241022 显示为 Claude 3.5 Haiku）。
   • anthropicFamilyTier：指定模型所属的家族层级，如 haiku、sonnet 或 opus，这有助于客户端对模型进行分类管理。
   • isFamilyDefault：布尔值，标记该模型是否为该家族（Tier）的默认选择。例如，Haiku 家族默认选中 claude-3-5-haiku-20241022，Sonnet 家族默认选中 claude-sonnet-4-6，Opus 家族默认选中 claude-opus-4-7。
   • supports1m：布尔值，标记模型是否支持 100 万 token 的上下文窗口。此字段在最新的 Claude 4 系列模型（如 Sonnet 4.6、Opus 4.6+、Fable 5）中被显式设置为 true。

3. 网络与安全策略：

   • coworkEgressAllowedHosts：设置为 ["*"]，允许所有主机出站连接，确保网关通信不受防火墙或代理限制。
   • disableDeploymentModeChooser：设置为 true，禁用部署模式选择器，简化界面操作，强制使用配置好的网关模式。

4. 涵盖的模型范围： 配置中列出了从旧版到最新版的广泛模型，包括：

   • Haiku 系列：claude-3-5-haiku-20241022
   • Sonnet 系列：claude-3-7-sonnet-20250219、claude-sonnet-4-20250514、claude-sonnet-4-5-20250929、claude-sonnet-4-6
   • Opus 系列：claude-opus-4-20250514、claude-opus-4-1-20250805、claude-opus-4-5-20251101、claude-opus-4-6、claude-opus-4-7、claude-opus-4-8
   • Fable 系列：claude-fable-5

   值得注意的是，配置中包含了大量未来日期（如 2025 年）的模型 ID，这表明该配置旨在支持尚未正式广泛普及或处于预览阶段的模型，或者反映了社区对模型迭代速度的预判。

关键要点

• 解决显示滞后问题：官方客户端更新模型列表可能存在延迟，手动导入 JSON 配置可立即让客户端识别新发布的模型 ID。
• 自定义显示名称：通过 labelOverride 字段，用户可以将晦涩的技术 ID（如 claude-sonnet-4-6）转换为更友好的用户界面名称（如 Claude Sonnet 4.6）。
• 明确默认模型：通过 isFamilyDefault: true 设置，用户可以将自己偏好的模型（如 Sonnet 4.6 或 Opus 4.7）设为各家族的默认启动模型，减少每次手动选择的麻烦。
• 支持长上下文标记：对于支持 100 万 token 上下文的新模型（如 Claude 4 系列及 Fable 5），显式设置 supports1m: true 可能有助于客户端正确配置上下文窗口参数或向用户展示相关能力标识。
• 网关兼容性：该配置专为使用 Gateway 作为推理提供商的场景设计，通过 inferenceProvider: "gateway" 和静态密钥认证实现。
• 模型迭代迅速：配置中列出的模型涵盖了从 2024 年底到 2025 年中的多个版本，反映了 Anthropic 模型发布的密集节奏，特别是 Claude 4 系列和 Fable 系列的快速迭代。

意义与影响

1. 提升开发者体验：对于依赖 Claude Code Desktop 进行日常编码的开发者而言，能够即时访问最新模型意味着可以利用最新的技术特性（如更强的推理能力、更长的上下文窗口）来提高工作效率。手动配置虽然繁琐，但一旦设置完成，可长期受益。
2. 社区驱动的生态补充：此类配置文件的分享体现了开源社区和开发者社群的互助精神。在官方工具功能尚未完善或更新不及时的情况下，社区通过共享配置方案填补了空白，加速了新技术的普及。
3. 灵活性与控制权：该方案赋予了用户更高的控制权。用户不再被动等待官方更新，而是可以主动定义哪些模型可用、哪些是默认选项，甚至可以根据成本或性能需求灵活切换不同的网关后端。
4. 对模型管理的启示：随着 AI 模型版本迭代速度加快，客户端软件需要更灵活的配置机制来适应这种变化。此案例表明，支持外部 JSON 配置导入是解决模型列表同步问题的有效途径，未来类似工具可能会更加重视此类可配置性。
5. 潜在风险注意：用户在使用此类配置时需确保 inferenceGatewayBaseUrl 和 ApiKey 的安全性，避免泄露。同时，由于配置中包含大量未来日期的模型 ID，用户需确认其网关是否真正支持这些模型，否则可能导致调用失败。