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

# BYOK - 自带密钥

> 连接您自己的提供商密钥,然后为每个任务选择运行的模型。所有 Kodus 套餐均可用。

BYOK(自带密钥)是 **Kodus 在所有套餐中使用 LLM 的默认方式** — 社区版、团队版和企业版都一样。您连接自己的提供商账号、启用想要的模型,并为每个任务选择运行哪个模型。您直接向提供商付费,Kodus 从不对 token 加价,也从不会以明文形式看到您的密钥。

<Card title="如何对应到各套餐" icon="scale-balanced" href="/zh/how_to_use/pricing#byok-是所有套餐的默认方式">
  BYOK 在社区版免费、在团队版包含(每活跃开发 \$10/月,另外支付您自己的 token 费用)、在企业版是两个选项之一(另一个是 Kodus 托管的 API 密钥)。
</Card>

## BYOK 如何工作

BYOK 是**提供商优先**的:您连接一次提供商,把想要的模型添加到该提供商上,然后将这些模型路由到 Kody 的各个任务。`/byok` 界面有三个标签页:

<CardGroup cols={3}>
  <Card title="提供商" icon="box">
    用您的密钥连接提供商,并在每个提供商上启用模型。计数徽章显示您已连接的提供商数量。
  </Card>

  <Card title="路由" icon="code-branch">
    选择每个任务运行哪个模型 — 为所有任务设一个默认模型、一个可选的备用模型,以及按 agent 的覆盖。
  </Card>

  <Card title="预算" icon="wallet">
    为您已连接的所有模型设置一个可选的月度开销上限。
  </Card>
</CardGroup>

<Info>
  **谁可以编辑此项。** BYOK 页面**仅限 Owner** — 连接、测试和删除密钥需要 **Owner** 角色。其他角色(Billing Manager、Repo Admin、Contributor)无法访问 `/byok`。参见[工作区角色](/zh/how_to_use/workspace_roles)。
</Info>

## 连接提供商

<Steps>
  <Step title="打开 BYOK 设置">
    访问 [app.kodus.io/byok](https://app.kodus.io/byok)。在全新的工作区中,您会看到**连接您的第一个提供商**。
  </Step>

  <Step title="选择一个提供商">
    提供商网格分为两部分:

    * **提供商** — 只需一个 API 密钥即可连接的一等提供商(OpenAI、Anthropic、Google AI Studio、OpenRouter、Novita……)。
    * **自定义** — 指向您自己端点或运行任意模型的提供商:**OpenAI-compatible**、**Anthropic-compatible**、**Google Vertex AI** 和 **Amazon Bedrock**。它们带有 *Custom endpoint* 标记。

    已经连接的提供商会显示**Connected · N models**。
  </Step>

  <Step title="添加模型">
    选择一个提供商会打开它的**Add a model** 表单。粘贴一次 API 密钥(之后添加到该提供商的每个模型都会复用它),然后选择模型:

    * 如果 Kodus 能列出该提供商的模型,您会得到一个下拉菜单。
    * 否则(自定义端点、自托管,或未配置平台密钥时),请输入精确的模型 ID。

    自定义端点(OpenAI-compatible / Anthropic-compatible)还会先要求填写一个**基础 URL**。
  </Step>

  <Step title="调整高级设置(可选)">
    在**高级设置**下:thinking/reasoning、温度、最大输出 token 数、最大输入 token 数,以及最大并发请求数。对大多数提供商来说默认值都是合理的 — 关于 Kodus 针对每个模型锁定或隐藏的字段,请参见[推理](#推理--扩展思考)和[温度](#温度)。
  </Step>

  <Step title="测试并保存">
    点击**测试**以探测提供商,或点击**测试并保存**以运行测试并在成功后持久化。您可以往该提供商上添加任意数量的模型 — 密钥只需粘贴一次。
  </Step>
</Steps>

<Tip>
  您可以随时从提供商标签页**添加另一个提供商**。每个提供商保留自己的密钥;在已连接的提供商上启用更多模型时永远不会再次索要密钥。
</Tip>

## 保存前先测试

**测试**按钮会在配置可能破坏真实审查之前先验证它。它的具体行为取决于提供商:

| 提供商                                                                              | Test 的作用                                                                 |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Anthropic-compatible 品牌**(Kimi、Z.ai、DeepSeek)、**OpenAI-compatible**、**Novita** | 向确切的模型发送一次真实的 **1-token 聊天请求** — 与审查所做的调用完全相同。能当场捕获错误的模型 ID、受限的密钥以及端点问题。 |
| **OpenAI、Anthropic、Google(Gemini/Vertex)、OpenRouter、Bedrock**                    | 一次低成本的身份/元数据调用(list-models、token 交换或 STS)— 确认密钥和端点可用。                    |

在聊天探测这条路径上,Test 还会**根据模型自身的规则验证您配置的调优参数**,并返回一个提前的、具体的错误,而不是保存一个模型会静默忽略的配置:

* 一个 always-thinking 模型不会遵守的温度(它被固定为 `1` — 参见[温度](#温度))。
* 在一个始终推理且无法禁用推理的模型上把推理设为 **Off**。

<Info>
  由于聊天类提供商现在会实际调用真实模型,**模型 ID 中的拼写错误会在 Test 阶段被捕获**,而不是等到您第一次审查时 — 响应会返回 `Model not found`。
</Info>

## 路由:每个任务运行哪个模型

一旦您连接了两个或更多模型,**路由**标签页就决定每个任务运行什么。路由是**扁平**的:在您覆盖之前,每个任务都使用默认模型。

<Steps>
  <Step title="策略">
    今天生效的是 **Manual · you choose**(手动 · 您选择)。**Auto · Kodus optimizes**(自动 · Kodus 优化)即将推出。
  </Step>

  <Step title="默认值">
    * **Model for all tasks(所有任务的模型)** — 除非被覆盖,否则每个任务都使用的那个模型。
    * **Fallback(备用,可选)** — 一个*不同的*模型,当任务的模型失败时(密钥错误或过期、没有额度,或提供商宕机,在其自身重试之后),Kody 会在它上面重跑一次调用。
  </Step>

  <Step title="按 agent">
    不同的 Kody 任务(代码审查、Kody Rules、聊天、摘要等等)可以各自运行不同的模型 — 用更贵的模型做深度审查,用更便宜的模型做摘要。无法执行某个任务的模型会在那一行被禁用并带有提示,从而在您保存之前就阻止它。
  </Step>
</Steps>

点击**Save routing** 以持久化。**Reset agents to default** 会把每个按 agent 的覆盖都还原为默认,并清除备用(默认模型本身保留)。下方一个只读的**Per repository** 面板会镜像在代码审查设置中设定的任何按仓库的模型覆盖。

<Note>
  只连接了一个模型时,路由会被跳过 — 每个任务都使用那个模型。请连接第二个模型,让路由变得有意义。
</Note>

## 选择模型

您的提供商所提供的任何模型都可用。如果您不确定从哪里开始,以下是代码审查的稳妥选择:

<CardGroup cols={2}>
  <Card title="Claude Sonnet / Opus" icon="crown">
    **最佳平衡 / 旗舰质量。** Anthropic 的自适应扩展思考和强大的跨文件分析。密钥:[console.anthropic.com](https://console.anthropic.com/settings/keys)。
  </Card>

  <Card title="Gemini Pro" icon="brain">
    **最大上下文。** Google 的旗舰模型 — 在大型 PR 和 monorepo 上最强。密钥:[aistudio.google.com/apikey](https://aistudio.google.com/apikey)。
  </Card>

  <Card title="GPT(最新)" icon="sparkles">
    **快速且稳定。** OpenAI 的旗舰产品线 — 低延迟可靠、知识面广。密钥:[platform.openai.com/api-keys](https://platform.openai.com/api-keys)。
  </Card>

  <Card title="Kimi / GLM(编码方案)" icon="moon">
    **通过订阅最便宜。** Moonshot 的 Kimi 和 Z.ai 的 GLM 提供统一定价的编码方案,可封顶月度开销。参见下方的[连接 Kimi 和 GLM](#连接-kimi-moonshot-和-glm-zai)。
  </Card>
</CardGroup>

<Info>
  \*\*我们的默认推荐:\*\*从 **Claude Sonnet** 开始以获得最佳整体体验。如果成本是优先项,**GLM Coding Plan** 或 **Kimi Code Plan** 提供统一月费的订阅。请输入您的提供商所文档化的精确模型 ID — Kodus 会据此推导出显示名称。
</Info>

## 连接 Kimi (Moonshot) 和 GLM (Z.ai)

Moonshot 和 Z.ai 都在按 token 付费的开发者 API 之外,各自提供一个位于**不同端点**上的订阅方案。每个方案都是一个独立的账号,拥有各自的密钥 — 请选择与您手头密钥匹配的基础 URL。

<Tabs>
  <Tab title="Kimi (Moonshot AI)">
    | 方案                 | 端点                                                                                                         | 密钥来源                                                                  | 适合场景                 |
    | ------------------ | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------- |
    | **Developer API**  | `https://api.moonshot.ai/v1`(OpenAI-compatible)或 `https://api.moonshot.ai/anthropic`(Anthropic-compatible) | [platform.moonshot.ai](https://platform.moonshot.ai/console/api-keys) | 按 token 付费,并发随充值档位伸缩 |
    | **Kimi Code Plan** | `https://api.kimi.com/coding/v1`                                                                           | [kimi.com/code](https://www.kimi.com/code)                            | 带专用编码端点的订阅           |

    <Info>
      Kimi Code Plan 文档记录的上限为 30 个并发请求 — 请设置 `maxConcurrentRequests=30`。始终推理的 Kimi 变体(例如 `kimi-k2p7-code`、`kimi-k3`)会把温度锁定为 `1`,且无法关闭推理 — 参见[温度](#温度)。
    </Info>
  </Tab>

  <Tab title="GLM (Z.ai)">
    | 方案                | 端点                                    | 密钥来源                                                         | 适合场景             |
    | ----------------- | ------------------------------------- | ------------------------------------------------------------ | ---------------- |
    | **Developer API** | `https://api.z.ai/api/paas/v4/`       | [z.ai/manage-apikey](https://z.ai/manage-apikey/apikey-list) | 波动性负载,按 token 付费 |
    | **Coding Plan**   | `https://api.z.ai/api/coding/paas/v4` | [z.ai/subscribe](https://z.ai/subscribe)                     | 稳定的团队流量,统一月费     |

    <Warning>
      GLM Coding Plan 密钥**只能**在 `/api/coding/paas/v4` 上工作。Lite 和 Pro 档位通常限制为 **1 个并发请求** — 请设置 `maxConcurrentRequests=1`,仅在 Max 档位才上调(最多 30)。
    </Warning>
  </Tab>
</Tabs>

## 支持的提供商

<Tabs>
  <Tab title="OpenAI">
    \*\*最适合:\*\*最新 GPT 模型和可靠性能。

    **获取 API 密钥:**

    1. 访问 [OpenAI API Keys](https://platform.openai.com/api-keys)
    2. 为 Kodus 创建新密钥
    3. 添加计费信息
  </Tab>

  <Tab title="Google Gemini">
    \*\*最适合:\*\*大上下文审查(1M tokens)与竞争性定价。

    **获取 API 密钥:**

    1. 前往 [Google AI Studio](https://aistudio.google.com/app/apikey)
    2. 创建新密钥
    3. 在 Google Cloud Console 中启用计费
  </Tab>

  <Tab title="Anthropic Claude">
    \*\*最适合:\*\*细致的分析和自适应扩展思考。

    **获取 API 密钥:**

    1. 访问 [Anthropic Console](https://console.anthropic.com/)
    2. 创建账号并生成密钥
    3. 添加积分
  </Tab>

  <Tab title="Novita AI">
    \*\*最适合:\*\*以竞争性价格访问开源和托管模型(Llama、DeepSeek、Kimi)。

    **获取 API 密钥:**

    1. 在 [Novita AI](https://novita.ai/) 注册
    2. 导航到 API 设置
    3. 生成密钥

    <Card title="Novita 设置指南" icon="rocket" href="/zh/cookbook/novita">
      带截图的详细设置。
    </Card>
  </Tab>

  <Tab title="OpenRouter">
    \*\*最适合:\*\*通过一个计费关系访问多个模型。

    **获取 API 密钥:**

    1. 在 [OpenRouter](https://openrouter.ai/) 创建账号
    2. 添加积分
    3. 在设置中生成密钥

    <Warning>
      OpenRouter 默认会将每次请求路由到不同的上游提供商,这会导致不同调用之间出现质量和延迟漂移。请在 Advanced settings → OpenRouter routing 下**固定特定的上游**以保持行为稳定。参见[固定 OpenRouter 上游提供商](#固定-openrouter-上游提供商)。
    </Warning>
  </Tab>

  <Tab title="Google Vertex AI">
    <Info>**Beta。** 认证路径比"单一密钥"的常规方式更复杂。</Info>

    **最适合:** 已经在使用 Google Cloud、需要在既有 GCP 计费、IAM 和数据驻留保障下使用 Gemini(或 Claude)的团队。

    **如何配置:**

    1. 在连接流程中选择 **Google Vertex AI**(位于自定义下)。
    2. 把**服务账号 JSON 文件的内容**粘贴到 Service Account JSON 字段(base64 编码同样可用)。Kodus 会自动从 JSON 中提取 `project_id`。
    3. **Region** — 留空以使用全局端点(推荐)。仅在有数据驻留要求时才固定某个区域(例如 `us-east5`)。

    该服务账号需要具备在该项目中调用 Vertex AI 预测 API 的权限。Test 会探测*实际配置的模型*,因此不可用的模型/区域会在 Test 阶段失败。
  </Tab>

  <Tab title="Amazon Bedrock">
    <Info>**Beta。** 认证路径比"单一密钥"的常规方式更复杂。</Info>

    **最适合:** 已标准化到 AWS、希望模型费用计入自家 AWS 账户的团队。

    **如何配置:**

    1. 在连接流程中选择 **Amazon Bedrock**(位于自定义下)。
    2. 提供一个 **Bedrock API key**(bearer token)— 参见[如何生成 Bedrock API key](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys-generate.html)。
    3. 设置 **Region**(例如 `us-east-1`、`us-west-2`、`eu-central-1`)。

    <Accordion title="高级:改用 IAM 用户凭证">
      如果你的团队尚未迁移到 Bedrock API key,展开 **Advanced — use IAM user credentials instead**,填入静态的 access key ID 与 secret(若使用 STS 临时凭证还需 session token)。该 IAM 主体需要 `bedrock:InvokeModel` 权限。

      API key 优先:一旦设置了 bearer token,IAM 字段会被忽略。
    </Accordion>
  </Tab>

  <Tab title="OpenAI Compatible">
    \*\*最适合:\*\*专业提供商(Moonshot、Z.ai、Fireworks、Together、Groq、DeepSeek)或自托管端点。

    **如何配置:**

    1. 在连接流程中选择 **OpenAI Compatible**(位于自定义下)。
    2. 输入基础 URL(例如 `https://api.moonshot.ai/v1`、`https://api.z.ai/api/paas/v4/`、`https://api.fireworks.ai/inference/v1`)。
    3. 提供密钥和模型 ID。

    <Note>
      模型 ID 因提供商而异 — 有些使用深层路径(例如 Fireworks:`accounts/fireworks/models/kimi-k2p7-code`)。请从提供商的仪表板复制精确的 ID;Test 会发送一次真实请求,因此错误的 ID 会立即失败。
    </Note>

    <CardGroup cols={2}>
      <Card title="Z.ai (GLM) 指南" href="/zh/knowledge_base/how-to-use-z-ai-with-kodus" icon="bolt">
        包含 Coding Plan 细节的完整 Z.ai 设置。
      </Card>

      <Card title="Moonshot (Kimi) 指南" href="/zh/knowledge_base/how-to-use-moonshot-with-kodus" icon="moon">
        Kimi + Kimi Code Plan 设置。
      </Card>

      <Card title="Fireworks AI" href="/zh/knowledge_base/how-to-use-fireworks-with-kodus" icon="fire">
        Fireworks 专属设置。
      </Card>

      <Card title="Together AI" href="/zh/knowledge_base/how-to-use-together-ai-with-kodus" icon="handshake">
        Together AI 设置。
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Anthropic-compatible">
    **最适合:** 使用 Anthropic Messages API 格式(而非 OpenAI 格式)的端点 — 包括 Kimi 等的 coding-plan 端点。

    **如何配置:**

    1. 在连接流程中选择 **Anthropic-compatible**(位于自定义下)。
    2. 填入 base URL、密钥和模型 ID。

    <Note>
      base URL 按你的提供商所文档化的形式粘贴即可 — 末尾带不带 `/v1` 都可以(例如 `https://api.kimi.com/coding` 或 `https://api.kimi.com/coding/v1`)。Kodus 会在内部做归一化,因为 Anthropic 的两条 SDK 路径对 `/v1` 应该放在哪里的处理并不一致。对于已知品牌,仅凭密钥连接就能自动解析出端点。
    </Note>
  </Tab>
</Tabs>

## 推理 / 扩展思考

**Add a model** 表单在**高级设置**下提供一个 **Thinking** 开关(Off / Low / Medium / High / Custom)。可用选项反映模型实际能做什么:

* 无法推理的模型被锁定为 **Off** 并带有说明。
* 仅在某些级别推理的模型(例如 GPT-5 的 medium/high)会禁用无效的级别。
* 默认推理的模型会以 **Medium** 作为合理的起点。

### 预设级别

当您选择 Low / Medium / High 时,Kodus 会自动将该级别转换为每个提供商的原生格式:

| 提供商                                                             | "medium" 如何映射                                         |
| --------------------------------------------------------------- | ----------------------------------------------------- |
| **Anthropic**(Claude 自适应)                                       | `thinking: { type: "adaptive" }` + `effort: "medium"` |
| **Google**(Gemini)                                              | `thinkingConfig: { thinkingLevel: "medium" }`         |
| **OpenAI**(GPT-5 / o-series)                                    | `reasoningEffort: "medium"`                           |
| **OpenRouter**                                                  | `reasoning: { effort: "medium" }`                     |
| **OpenAI-compatible / Anthropic-compatible**(Kimi、GLM、DeepSeek) | `thinking: { type: "enabled" }` — 二元开/关,级别被忽略         |

<Note>
  Kimi 和 GLM 目前将推理暴露为单一的开/关标志。选择 Low、Medium 或 High 都会发出相同的 payload(启用 thinking)。**始终推理的变体**(Kimi `k2p7-code`/`k3`、GLM-5.3)会无条件推理 — 它们无法被设为 Off,表单会禁用该选项。
</Note>

### 自定义 JSON 覆盖

在 Thinking 开关中选择 **Custom** 会显示一个 JSON 文本框。直接粘贴提供商选项 — **Kodus 会自动把它们包裹在当前提供商的命名空间下**。您无需了解 Vercel AI SDK 的路由规则。

在以下情况使用:

* 您需要为 Claude 设置特定的 `budgetTokens` 值(而不是预设的 effort 映射)
* 您希望针对 OpenAI-compatible 提供商按模型启用/禁用 thinking
* 您想设置推理之外的字段 — **缓存、服务档位、安全设置、`user` 标签等**。覆盖会被合并进 `providerOptions`,因此任何适配器字段都可以透传
* 提供商发布了一个 Kodus 尚未包裹的新字段

#### 示例(直接粘贴 — 无需命名空间)

<Tabs>
  <Tab title="Anthropic">
    将 Claude 的思考预算精确覆盖为 20,000 tokens:

    ```json theme={null}
    {
      "thinking": { "type": "enabled", "budgetTokens": 20000 }
    }
    ```

    启用提示缓存(非推理示例):

    ```json theme={null}
    {
      "cacheControl": { "type": "ephemeral" }
    }
    ```
  </Tab>

  <Tab title="Google Gemini">
    显式思考预算(Gemini 2.5)或级别(Gemini 3+):

    ```json theme={null}
    {
      "thinkingConfig": { "thinkingBudget": 16000 }
    }
    ```

    调整安全设置:

    ```json theme={null}
    {
      "safetySettings": [
        { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "BLOCK_NONE" }
      ]
    }
    ```
  </Tab>

  <Tab title="OpenAI">
    结合 OpenAI 特有字段的推理配置:

    ```json theme={null}
    {
      "reasoningEffort": "high",
      "serviceTier": "flex",
      "store": false,
      "user": "kodus-review"
    }
    ```
  </Tab>

  <Tab title="OpenRouter">
    强制推理并忽略特定上游:

    ```json theme={null}
    {
      "reasoning": { "effort": "high" },
      "ignore": ["deepinfra"]
    }
    ```
  </Tab>

  <Tab title="OpenAI-compatible(Kimi、GLM 等)">
    启用 thinking 并带上预算提示:

    ```json theme={null}
    {
      "thinking": { "type": "enabled", "budget_tokens": 25000 }
    }
    ```

    显式禁用 thinking(仅在支持它的模型上):

    ```json theme={null}
    {
      "thinking": { "type": "disabled" }
    }
    ```

    <Warning>
      上游提供商不识别的字段(例如某台服务器忽略的 `budget_tokens`)会被静默丢弃。请查阅提供商文档确认他们接受什么。
    </Warning>
  </Tab>
</Tabs>

#### 手动指定命名空间(进阶用户)

如果您的 JSON 顶层已经以一个已知的命名空间键开头(即下方映射表中的任意键),Kodus 会保持原样不动。当您想混合多个提供商命名空间或希望显式书写时很有用:

```json theme={null}
{
  "openrouter": {
    "reasoning": { "effort": "high" },
    "provider": { "order": ["moonshot"], "allow_fallbacks": false }
  }
}
```

在底层,Kodus 使用以下命名空间映射:

| BYOK 提供商                             | 命名空间键                                            |
| ------------------------------------ | ------------------------------------------------ |
| `anthropic` / `anthropic_compatible` | `anthropic`                                      |
| `google_gemini`                      | `google`                                         |
| `google_vertex`                      | Gemini 用 `google`，Vertex 上的 Claude 用 `anthropic` |
| `openai`                             | `openai`                                         |
| `openai_compatible`                  | `openaiCompatible`                               |
| `azure`                              | `azure`                                          |
| `amazon_bedrock`                     | `amazonBedrock`（也接受 `bedrock`）                   |
| `novita`                             | `novita`                                         |
| `open_router`                        | `openrouter`                                     |

#### 注意事项

* **仅支持有效的 JSON。** 遗漏逗号或尾随逗号会破坏解析,Kodus 会忽略覆盖。
* **优先级:**JSON 覆盖会**完全替换** effort 预设对应的命名空间块 — 如果您覆盖了 `anthropic.thinking` 但漏掉 `anthropic.effort`,那个字段就不会被发送。OpenRouter routing(固定提供商 / 允许回退)是唯一例外:它会与您在 `openrouter` 下的覆盖进行深度合并。
* **未知提供商 = 不自动包裹。** 如果您的 BYOK 提供商不在上表中,Kodus 会原样透传 JSON。

## 温度

温度位于**高级设置**下,该字段会根据模型的规则自适应 — 规则由提供商设定,而非表单猜测:

| 模型                                                  | 温度字段                                                                        |
| --------------------------------------------------- | --------------------------------------------------------------------------- |
| 大多数模型                                               | **可编辑**(0 = 确定性,2 = 富有创意)。                                                  |
| 始终推理的 Anthropic 协议模型(Kimi `k2p7-code`/`k3`、GLM-5.3) | **锁定为 `1`。** 该协议在思考时把温度固定为 1,因此 1 是唯一合理的值 — 字段显示一把锁,无论存储的是什么,Kodus 都发送 `1`。 |
| Claude 4.7+ 与 OpenAI GPT-5 / o-series               | **隐藏。** 这些模型移除了温度,并拒绝任何设置温度的请求 — 请改用思考级别来引导它们。                              |

<Info>
  在聊天探测类提供商上,[Test](#保存前先测试) 会根据这些规则验证您设置的温度,并在保存前返回错误 — 这样您就永远不会持久化一个模型不会遵守的值。
</Info>

## 固定 OpenRouter 上游提供商

OpenRouter 是一个路由器 — 当您请求某个模型(例如 `moonshotai/kimi-k2`)时,它会将调用转发到若干上游提供商之一(Moonshot 直连、Together、Groq、Fireworks、Novita……)。每次调用都可能落到不同的后端。这很方便,但会引入隐性的差异:

* **质量漂移** — 上游以不同精度运行(FP8、INT4、完整),对相同提示会给出微妙不同的输出
* **工具调用不一致** — 一些后端对函数调用的支持方式不同,会导致格式错误的工具使用
* **推理格式差异** — 一个上游支持 `reasoning_effort`,另一个只支持 `thinking.enabled`,还有的两者都忽略
* **延迟波动** — 随着路由变化,p50 可能在两次调用之间从 800ms 跳到 4s
* **速率限制意外** — 您会在自己未显式选择的后端上撞到配额

### 如何固定

当您的 BYOK 提供商是 **OpenRouter** 时,Advanced settings 面板会显示一个 **OpenRouter routing** 区块,包含两个字段:

* **Pin providers (in order)** — 上游名称的逗号分隔列表(例如 `moonshot, together`)。OpenRouter 会按顺序尝试,并使用第一个可用的。
* **Allow fallbacks** — 关闭时,若没有任何被固定的提供商可用,请求会硬失败。开启时(默认),OpenRouter 可以回退到任意其他服务该模型的上游。

<Tip>
  为了获得**稳定**的配置,请只固定一个提供商并关闭回退(`Pin: moonshot`、`Allow fallbacks: off`)。请求将始终命中同一个上游,或响亮地失败 — 不会有隐性的质量变化。代价是一旦那个上游宕机就完全没有韧性;请搭配一个不同的路由备用模型(例如 Anthropic)来吸收中断。
</Tip>

<Warning>
  上游名称必须与 OpenRouter 的目录一致。请在 [openrouter.ai/docs/features/provider-routing](https://openrouter.ai/docs/features/provider-routing) 上查看提供商标签 — 常见值包括 `moonshot`、`together`、`groq`、`fireworks`、`novita`。
</Warning>

在底层,Kodus 会把以下内容发送到 Vercel AI SDK 的调用中:

```json theme={null}
{
  "openrouter": {
    "provider": {
      "order": ["moonshot", "together"],
      "allow_fallbacks": false
    }
  }
}
```

### 进阶:原始 JSON 覆盖

如果您需要 `order` 和 `allow_fallbacks` 之外的字段(例如 `ignore`、`data_collection`、`require_parameters`),请在 Advanced settings 中将 **Thinking** 切换到 **Custom**,并粘贴完整的路由 payload — 它会与任何推理配置一起被合并进 `providerOptions`:

```json theme={null}
{
  "openrouter": {
    "provider": {
      "order": ["moonshot"],
      "allow_fallbacks": false,
      "ignore": ["deepinfra"],
      "data_collection": "deny"
    },
    "reasoning": { "effort": "medium" }
  }
}
```

## 并发与速率限制

`maxConcurrentRequests` 字段(**高级设置**下)限制 Kodus 并行向您的提供商发送的未完成请求数。多数情况下默认值即可 — 但有严格并发限制的订阅方案需要显式设置。

### 应设置的值

| 提供商 / 方案                                     | 值       | 原因                                    |
| -------------------------------------------- | ------- | ------------------------------------- |
| **GLM Coding Plan(Lite/Pro)**                | `1`     | 订阅只允许一个请求在途。超过会触发 429。                |
| **GLM Coding Plan(Max)**                     | 最多 `30` | Max 最多允许 30 并发 — 在此上调以用满全部预算。         |
| **Kimi Code Plan**                           | `30`    | Moonshot 在编码端点的文档上限。                  |
| **GLM Developer API**                        | *(空)*   | 限制按密钥伸缩;没有合理的全局默认值。                   |
| **Kimi Developer API**                       | *(空)*   | 随您的充值档位伸缩(Tier 1 ≈ 50,Tier 5 ≈ 1000)。 |
| **Anthropic / OpenAI / Google / OpenRouter** | *(空)*   | 提供商自行强制 TPM/RPM;Kodus 不设上限。           |

### 何时调整

<CardGroup cols={2}>
  <Card title="上调" icon="arrow-up">
    * Moonshot/OpenRouter 上有高档位充值,并希望在大型 PR 上获得更高吞吐
    * 把 GLM Coding Plan 升到了 **Max** 并希望用满 30 并发预算
    * 多文件 PR 上审查感觉被串行化,而您并未看到 429
  </Card>

  <Card title="下调" icon="arrow-down">
    * 您在审查日志中看到 `429` 或 `Too much concurrency` 错误
    * 提供商仪表板提示速率限制警告
    * 希望在更多 PR 之间节省 Coding Plan 窗口(5 小时/每周)
  </Card>
</CardGroup>

<Tip>
  **并发 vs. RPM vs. TPM。** `maxConcurrentRequests` 仅限制并行在途请求。许多提供商还另行强制 **RPM**(每分钟请求数)和 **TPM**(每分钟 token 数)限制。如果并发看起来没问题但您在撞 RPM/TPM,通常解法是升级档位或跨时间分散负载 — 而不是调 `maxConcurrentRequests`。
</Tip>

<Note>
  **与备用模型的交互。** 当任务的模型撞到 429 并且 Kody 故障转移到路由备用模型时,备用模型自身的 `maxConcurrentRequests` 生效。将备用配置到不同提供商上并设一个宽松的值,是在主模型使用紧张订阅时吸收突发流量的好办法。
</Note>

## 最佳实践

### 安全

<CardGroup cols={2}>
  <Card title="专用密钥" icon="shield-check">
    为 Kodus 创建独立的 API 密钥,便于审计使用情况和轮换密钥。
  </Card>

  <Card title="定期轮换" icon="arrows-rotate">
    定期轮换密钥,并在 BYOK 设置中更新。
  </Card>

  <Card title="监控使用" icon="chart-bar">
    检查您的提供商仪表板是否有异常模式。
  </Card>

  <Card title="安全存储" icon="lock">
    切勿将密钥提交到代码仓库。Kodus 对密钥进行静态和传输中加密存储。
  </Card>
</CardGroup>

### 路由策略

* 为默认和备用使用**不同的提供商**(例如默认用 Anthropic,备用用 Google)。可防止提供商特定的中断。
* 带有紧张并发限制的订阅(GLM Coding Plan Lite/Pro、Kimi Code Plan)不适合单独使用 — 请配对一个按 token 付费的备用,避免突发 PR 把资源吃光。
* 在**按 agent** 下,把繁重任务(深度代码审查)路由到您最强的模型,把轻量任务(摘要、聊天)路由到更便宜的模型。

## 故障排查

<AccordionGroup>
  <Accordion title="点击 Test 时出现 'Invalid API key'">
    * 复制密钥时不要带多余的空格、引号或尾随换行。
    * 确认计费已启用且账户有余额。
    * 对于 GLM Coding Plan / Kimi Code Plan 密钥,请确认**基础 URL** 与方案匹配 — 订阅密钥不适用于开发者 API 端点,反之亦然。
  </Accordion>

  <Accordion title="点击 Test 时出现 'Model not found'">
    * 对于聊天探测类提供商(Anthropic-compatible、OpenAI-compatible、Novita),Test 会向模型发送一次真实请求,因此错误或拼写有误的模型 ID 会在这里失败 — 这是预期行为,也比在审查时才失败更好。
    * 请从提供商的仪表板复制精确的模型 ID。有些提供商使用深层路径(例如 Fireworks `accounts/fireworks/models/kimi-k2p7-code`)或对版本有不同拼法(`k2p7` 与 `k2.7`)。
  </Accordion>

  <Accordion title="点击 Test 时出现 'Endpoint not found'">
    * 验证基础 URL 与提供商完全匹配(对某些提供商来说,尾部斜杠很重要)。
    * 对于 OpenAI-compatible 提供商,端点通常是 `{baseURL}/chat/completions`(Kodus 会补上该路径)。
  </Accordion>

  <Accordion title="Test 拒绝我设置的温度或推理">
    * 有些模型固定温度或始终推理(Kimi `k2p7-code`/`k3`、GLM-5.3;Claude 4.7+/GPT-5 则完全移除温度)。Test 会根据模型的规则验证您的调优参数并返回具体消息 — 请照做(让温度保持未设置或使用要求的值;不要在始终推理的模型上把推理设为 Off)。参见[温度](#温度)。
  </Accordion>

  <Accordion title="'Rate limited' 或 'Too much concurrency'">
    * 在高级设置中降低**最大并发请求数**。
    * 在 GLM Coding Plan Lite/Pro 上,保持 **1 个并发**。如果需要更高吞吐,升级到 Max(30 并发)。
    * 在 Kimi Code Plan 上,文档上限为 **30 并发**。
  </Accordion>

  <Accordion title="自托管环境变量未显示">
    * 如果 Kodus 通过 `.env`(自托管固定模式)配置,BYOK 界面会显示一个蓝色信息横幅,标明当前活动的提供商/模型 — 出于安全考虑,密钥不会显示。
    * 连接一个模型并保存会覆盖 `.env` 配置。
  </Accordion>

  <Accordion title="高或意外的成本">
    * 推理会增加 token 消耗。如果成本飙升,将 **Thinking** 从 Medium 降到 Low,或在**按 agent** 下把繁重任务路由到更便宜的模型。
    * 查看提供商仪表板中的按模型分解,并在**预算**标签页下设置上限。
  </Accordion>
</AccordionGroup>

## 常见问题

<AccordionGroup>
  <Accordion title="我可以随时切换提供商吗?">
    可以。更改会在下一次审查生效 — 无需重新部署。
  </Accordion>

  <Accordion title="如果我的 API 密钥用完积分会怎样?">
    如果配置了路由备用模型,审查会自动切换到备用。没有备用时审查会失败并返回错误。请始终配置备用模型。
  </Accordion>

  <Accordion title="默认 / 备用系统如何工作?">
    每个任务都使用默认模型,除非您在路由中按 agent 覆盖它。如果任务的模型失败(速率限制、5xx、超时、密钥错误),Kody 会在备用模型上重试一次。您只为真正处理调用的那个提供商付费。
  </Accordion>

  <Accordion title="不同任务可以使用不同模型吗?">
    可以 — 这正是**路由 → 按 agent** 的用途。把深度代码审查路由到强模型,把摘要或聊天路由到更便宜的模型。要让路由有意义,您至少需要连接两个模型。
  </Accordion>

  <Accordion title="你们是否安全存储我们的 API 密钥?">
    是的。密钥在静态和传输中加密,从不以明文记录。BYOK 状态端点从不返回原始密钥。
  </Accordion>

  <Accordion title="我可以使用自托管 LLM(例如 Ollama、vLLM)吗?">
    可以 — 通过 **OpenAI Compatible** 提供商(位于自定义下)。输入端点的基础 URL、它暴露的模型 ID,以及占位 API 密钥(多数自托管运行时忽略密钥请求头,但仍要求提供)。
  </Accordion>
</AccordionGroup>