# 用自己的 API Key 配置 Voxt（BYOK）

[English](en/byok.md)

在 Voxt 里保存并测试一个语言模型服务，就能在翻译、改写以及需要润色的转录中使用它。本地 ASR 负责把声音变成文字。语言模型按所选功能处理文字。

## 先准备服务商给你的值

打开你有权限使用的服务商控制台，进入 **API Keys**，创建或复制给 Voxt 使用的 Key。由团队提供服务时，从团队指定的安全渠道领取。使用兼容 OpenAI 的自定义服务时，再从同一个服务商取得**模型 ID**和**API 地址**。这三项应属于同一套服务配置。

## 把 Key 填进 Voxt

1. 打开 Voxt 侧栏的**语言模型**（也可以在侧栏“没有语言模型”的通知里点**打开语言模型页**，或在首次设置的**模型**一步点**设置语言模型**）。选择你的服务商；使用兼容 OpenAI Chat Completions 的服务时，点 **OpenAI** 卡片。

   <div class="vx-anim" data-scene="llm-open" data-lang="zh"></div>

2. 在 **API Key** 输入框按 `⌘V` 粘贴 Key。输入后界面只显示圆点，保存时 Key 写入这台 Mac 的钥匙串，不会写进设置文件和日志。
3. 使用官方服务时，**地址**保留默认。使用其他兼容 OpenAI 的服务时，填服务商提供的 API 根地址，通常以 `/v1` 结尾，必须是 `https://`（指向本机的服务可以用 `http://`）。
4. 在**模型**下拉框选服务商的预设模型。列表里没有时选**其他模型…**，把服务商给出的准确模型 ID 粘贴到下方出现的输入框，区分大小写。

   <div class="vx-anim" data-scene="llm-fill" data-lang="zh"></div>

   有的版本里，**其他模型…**叫**自定义…**，**地址**叫**端点**，要填完整的 Chat Completions 请求地址（以 `/chat/completions` 结尾）。按你的界面填。首次设置可以保留默认的生成设置。

5. 点**测试连接**（有的版本叫**测试**），看到**连接正常**后点**保存**。测试会访问你配置的服务。自定义服务若提供不同协议，在**高级**中核对 API 格式与服务商要求一致。

   <div class="vx-anim" data-scene="llm-test" data-lang="zh"></div>

## 让功能使用这套配置

打开侧栏的**翻译**或**改写**，在该功能的**语言模型**下拉框选择刚保存的配置。在**转录**中，只有需要清理口头语或润色时才选择语言模型。用一句公开样例试一次即可确认，例如「请在周五前确认时间」。

<div class="vx-anim" data-scene="llm-use" data-lang="zh"></div>

## 测试没通过时

| 提示 | 处理 |
|---|---|
| 远程服务拒绝了这个 API Key | Key 填错、过期或被撤销，重新复制完整的 Key 粘贴 |
| 请在上方粘贴该服务的 API Key，然后再测试 | 还没有填 Key |
| 远程模型的地址不能用，请用 https://，或者指向本机的 http:// | 地址改成 `https://` 开头 |
| 找不到模型、404 | 核对模型 ID 是否逐字一致、地址是否少了 `/v1` |
| 服务拒绝请求、限流 | 到服务商控制台核对这个 Key 的权限和额度 |

修正后重新点**测试连接**。

## 交给 Agent

> 按本页打开 Voxt 的语言模型设置，根据我提供的服务商与 API 格式选择预设或自定义。填完非敏感设置后停在 API Key 字段，让我从安全渠道取出并直接粘贴。请勿读取、回显或截图这个字段。等我完成后，用 Voxt 的测试按钮检查连接，保存，再为我指定的功能选用这个配置。用非敏感示例确认成功，仅报告状态。