Skip to main content
适用版本：Claude Desktop 2025.6 及以上（原生支持第三方推理 / Gateway，无需改包或反代）。

​
一、配置步骤

​
第 1 步：开启开发者模式

  1. 打开 Claude Desktop。
  2. 顶部菜单栏 → Help → Troubleshooting → Enable Developer Mode。
  3. 开启后 Claude Desktop 会自动重启，重启后顶部菜单栏出现 Developer 菜单。

​
第 2 步：进入第三方推理配置

  1. 菜单栏 → Developer → Configure third-party inference。
  2. 在弹出的窗口中，连接方式选择 Gateway。
开启开发者模式并进入第三方推理配置 连接方式选择 Gateway

​
第 3 步：填写 Gateway 信息

填写 Gateway 信息
Gateway base URL 填写规则（最常见错误）：
  • 最终请求 = 你填的 base URL + "/v1/messages"
  • 实际接收地址若为 https://api.gravitex.ai/v1/messages，则 base URL 填 https://api.gravitex.ai
  • 不要自己带 /v1/messages 尾巴，否则会变成 .../v1/messages/v1/messages 导致 404。

​
第 4 步：配置模型（Model）

支持 2 种方式，选其中一种即可： 第一种： 推荐开启 Model discovery（模型发现）：
  • 勾选 Auto-populate the model picker from {base URL}/v1/models at launch。
  • 点击 Test model discovery，确认能拉取到支持的模型列表。
  • 模型下拉框会自动只显示支持的模型，避免模型名填错。
第二种： 手动指定，在 Model list 中点击 + Add 添加模型，填写规则如下： 配置模型 Model discovery Tier alias 为什么重要？ Claude Desktop 内部会用 opus / sonnet / haiku / fable 这些档位别名来分配不同类型的调用（例如轻量摘要任务可能走 haiku，复杂推理走 opus）。如果你把 claude-opus-4-8 的 Tier alias 设为 opus，客户端就知道把它当 Opus 档位用；留空或选错会导致 Invalid: Model list 错误。 📌 Model list 中第一项为默认模型。建议把常用模型（如 Sonnet）放在最上面。
常见报错：底部提示 Invalid: Model list通常是以下原因之一：
  • Tier alias 未选择；
  • Model ID 与已有条目重复；
  • Model ID 格式不被客户端接受（含空格、特殊字符等）。
修复后先点 Save Changes，再点 Apply Changes。

​
第 5 步：应用并重启

  1. 点击 Apply Changes。
  2. 完全退出 Claude Desktop（macOS：Claude 菜单 → Quit Claude / Cmd+Q，并用活动监视器确认无 Claude 进程）。
  3. 重新打开 Claude Desktop。
  4. 发送一条测试消息验证。

​
二、验证是否成功

  • Claude Desktop 能正常启动，左下角显示 你的账号 · Gateway。
  • 发送消息后无 authentication / invalid api key / gateway unavailable / model_not_found 等报错。

​
三、常见问题排查

​
四、安全须知

  • API Key 等同于密码，不要写入公开文档、截图或代码仓库。
  • 导出的配置文件（.mobileconfig / .reg / .json）可能含明文 Key，仅短期保存在可信设备，用完删除。
  • 若 Key 已在聊天、截图或日志中暴露，应立即作废并重新生成。