> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hostlinku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Desktop

> 通过 Configure Third-Party Inference 将 Claude Desktop 连接到 Hostlinku，无需额外的本地代理。

[Claude Desktop](https://claude.com/download) 可以在提供 **Configure Third-Party Inference** 菜单的版本中连接 Hostlinku。在应用中输入 base URL 和 API 密钥，然后选择该密钥的 Service Mode 可用的模型。

本指南适用于 Desktop 应用。终端或 VS Code/JetBrains 扩展请参阅 [Claude Code](https://docs.hostlinku.com/zh/integrations/claude-code.md)。此 inference 连接无需额外的本地代理，也无需修改 MCP 配置。

## 开始之前

* 从 [官方下载页面](https://claude.com/download) 安装 Claude Desktop。
* 在 [Console → API Keys](https://console.hostlinku.com/api-keys/) 创建 Hostlinku API 密钥，选择提供目标 Claude 模型的 Service Mode。
* 确保 USD 余额和密钥支出限额充足。用量由 Hostlinku 计费；请参阅 [计费与余额](https://docs.hostlinku.com/zh/billing.md)。

已验证范围

以下 Windows 截图显示模型发现和 inference 测试成功。在 Claude Desktop 的 **Code** 模式中，使用 **Fable 5.2** 的简单对话也已成功。这不代表已验证所有 Chat、Cowork、artifacts、connector 或模型功能。菜单名称和位置可能随应用版本变化。

### 启用 Developer Mode

在 Windows 上打开 **☰ → Help → Troubleshooting → Enable Developer Mode**。启用后若未出现 Developer 菜单，请完全退出应用后重新打开。

![Windows Claude Desktop：Help → Troubleshooting 中的 Enable Developer Mode](https://mintcdn.com/hostlinku/D_n6COs9jkVA6WFt/images/integrations/claude-desktop-developer-mode.webp?fit=max\&auto=format\&n=D_n6COs9jkVA6WFt\&q=85\&s=8d52f77f1d224acf4278f03098e0a0ee)

### 打开 third-party inference 设置

打开 **☰ → Developer → Configure Third-Party Inference…**。

![Windows Claude Desktop：Developer 菜单中的 Configure Third-Party Inference](https://mintcdn.com/hostlinku/D_n6COs9jkVA6WFt/images/integrations/claude-desktop-third-party-menu.webp?fit=max\&auto=format\&n=D_n6COs9jkVA6WFt\&q=85\&s=2b29c13ba052454fe69fabbb47bc78ac)

### 配置 Hostlinku 连接

在 **Connection** 中使用以下设置：

| 字段 | 值 |
| - | - |
| Provider | `Gateway` |
| Credential kind | `Static API key` |
| Gateway base URL | `https://api.hostlinku.com` |
| Gateway API key | 你的 Hostlinku API 密钥，例如 `sk-your-api-key` |
| Gateway auth scheme | `x-api-key` |

直接输入密钥，不要添加 `Bearer ` 前缀。base URL 无需附加 `/v1` 或 `/messages`。Hostlinku 已提供模型发现所需的 `GET /v1/models` 和 Anthropic Messages inference 所需的 `POST /v1/messages`。

图中的测试使用 `x-api-key`。Hostlinku 也接受 `Authorization: Bearer`，但截图并未验证该选项。此基本配置不需要 Custom inference headers。

![Claude Desktop Gateway 设置：Hostlinku URL、已遮蔽的 static key、x-api-key 和成功的连接测试](https://mintcdn.com/hostlinku/D_n6COs9jkVA6WFt/images/integrations/claude-desktop-gateway-settings.webp?fit=max\&auto=format\&n=D_n6COs9jkVA6WFt\&q=85\&s=13d5e81a7e0ccf512c2f8141d09dd096)

### 测试连接并发现模型

点击 **Test connection**。成功时会显示 **Model discovery** 和 **Inference**。若只需检查列表，可使用 **Models** 部分的 **Test model discovery**（如有）。

截图中的 **12 models** 是当时该密钥的测试结果，并非所有账户的固定数量。列表取决于密钥的 Service Mode 和模型可用性。若手动填写 **Model list**，请使用相同密钥的 `GET /v1/models` 中支持 Anthropic Messages 的 slug，不要复制其他提供商的模型列表。

### 保存并尝试对话

点击 **Save Changes**，然后点击 **Apply Changes**（如有）。按提示重启应用。在 Desktop 中打开 **Code** 会话，选择可用模型，发送 `hello` 等简单消息。

下图展示了 **Fable 5.2** 的回复。也请在 **Console → Request Logs** 中核对 API 密钥、模型、状态和费用。Test connection 本身可能消耗令牌并产生少量用量费用。

![Claude Desktop Code 模式：在 HostlinkuGateway 环境中，Fable 5.2 成功回复问候](https://mintcdn.com/hostlinku/D_n6COs9jkVA6WFt/images/integrations/claude-desktop-code-conversation.webp?fit=max\&auto=format\&n=D_n6COs9jkVA6WFt\&q=85\&s=4dca2b60c563d61ae63c22850eb8eddb)

## 功能范围

* **Inference 与 MCP 不同。** 此设置将模型请求发送到 Hostlinku；connector 或 MCP 设置不会自动更改 inference provider。
* **Gateway-managed Claude Code** 和 **Server-side Auto mode checks** 不是此 static key 配置的必要条件，本集成尚未验证这些功能。
* tool calling、vision、reasoning、上下文和 caching 取决于模型及协议路径。请参阅 [Anthropic Messages](https://docs.hostlinku.com/zh/anthropic-messages.md) 和 [模型目录](https://docs.hostlinku.com/zh/models.md)。
* 模型发现成功不保证列表中的每个模型都支持 Desktop 的所有 agent 功能。请先使用 Claude 模型执行简单任务。

## 故障排查

| 症状 | 检查项 |
| - | - |
| 缺少 Developer 或 third-party inference 菜单 | 确认 Desktop 版本提供该功能，启用 Developer Mode 后完全重启。 |
| `401` | 检查密钥是否正确、撤销或过期，以及 auth scheme 是否匹配。密钥字段中不要添加 `Bearer `。 |
| 发现列表为空或找不到模型 | 使用 Test model discovery，并通过相同密钥检查 `GET /v1/models` 和 Service Mode 对应的 slug。 |
| `400 MODEL_NOT_IN_SERVICE_MODE` | 使用提供该模型的 Service Mode 密钥。 |
| `402` | 检查可用 USD 余额和密钥支出限额。 |
| `429` | 如有 `Retry-After`，请遵循其要求并减少并发。参阅 [使用与限制](https://docs.hostlinku.com/zh/usage-and-limits.md)。 |
| 连接测试成功但 Code 会话失败 | 检查选中的模型与 Console 请求详情；简短的连接测试不能验证完整的 tool/agent 支持。 |

不要分享 API 密钥或包含凭据的配置 export。寻求帮助时，请提供 Desktop 版本、模型、Service Mode 和 request ID，不要包含密钥。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.