---
title: "模型"
description: "Beeuni 如何选择模型，以及托管模型和自带密钥模型的计费方式。"
---

Beeuni 在模型上运行每个 [会话](/docs/zh/work/sessions)。本页介绍托管模型与自带提供商密钥（BYOK）的区别、Beeuni 如何自动选择模型，以及两个需要注意的计费问题。

本页适用于已启用 LLM Gateway 的项目。LLM Gateway 是一项实验性[功能标志](/docs/zh/feature-flags)，在平台提供该功能的地方**默认开启**——可在 Settings → Feature flags 中查看或切换。

关闭此标志也是完全受支持的使用方式。此时项目将使用 **标准运行器 原生模型管理**。该项目的每个会话都运行标准运行器[harness](/docs/zh/work/harnesses)：实验运行器 只会通过网关调用模型。

- 你的提供商 API 密钥（`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、
  `OPENROUTER_API_KEY` 等）会作为普通环境变量注入沙盒——可在模型设置页中添加，或将其设为[密钥](/docs/zh/project/secrets)。标准运行器 会自动使用密钥连接各个提供商。
- 模型 ID 使用标准运行器原生的 `provider/model` 引用，例如 `anthropic/claude-opus-4-8`。关闭网关后，不存在托管模型裸 ID 和 `beeuni/…` 引用。
- 沙盒启动前后，模型选择器显示的列表相同：通过你的密钥连接的提供商，以及 OpenCode Zen 的免费模型（OpenCode 无需密钥即可连接）。思考强度是编辑器的思考控制（模型自身的变体）；网关的 Generation defaults 不适用。
- 本页介绍的网关功能——托管模型、模型默认值链、预算、日志——均不适用；OpenCode 会在沙盒中解析默认模型。

<a id="managed-models-and-byok"></a>

## 托管模型和 BYOK

模型 ID 有以下三种形式：

- **托管模型**——裸 ID，例如 `glm-5.2`、`deepseek-v4-pro-0813` 或
  `grok-4.6`。Beeuni 提供凭据。云账户使用 Beeuni 点数付费。
- **BYOK**——`provider/model` ID，例如 `anthropic/claude-opus-4-8`。你提供密钥，由你的提供商账户付费。
- **ChatGPT**——`codex/<id>` ID。你通过 OAuth 连接一次 ChatGPT 套餐，由该套餐付费。

在项目的模型设置页连接 BYOK 密钥，或直接将提供商环境变量设为[密钥](/docs/zh/project/secrets)。

每个提供商读取自己的密钥。有些提供商在 models.dev 上共用一个环境变量，例如 OpenCode Zen（`opencode`）和 OpenCode Go（`opencode-go`）都列出 `OPENCODE_API_KEY`。该名称由其所属提供商保留。其他提供商使用 `<PROVIDER_ID>_API_KEY`：OpenCode Go 读取 `OPENCODE_GO_API_KEY`，Z.ai Coding Plan 读取 `ZAI_CODING_PLAN_API_KEY`，Moonshot China 读取 `MOONSHOTAI_CN_API_KEY`。因此，Zen 密钥不会列出 Go 模型。连接表单和 `beeuni providers set` 会使用正确的名称。

<a id="opencode-zen-and-go-sign-in-with-opencode"></a>

### OpenCode Zen 和 Go（使用 OpenCode 登录）

使用 API 密钥连接 OpenCode Zen 或 OpenCode Go，也可以改用 OpenCode Console 账户登录：

1. 打开 **Customize → Models → Providers**，找到 **OpenCode Go**。
2. 选择 **Sign in with OpenCode**。复制代码，选择 **Open auth page**，然后在 OpenCode 工作区中批准此设备。
3. 密钥字段会显示提供商已连接。移除密钥即可退出登录。

使用 CLI：`beeuni providers login opencode-go`；使用 `beeuni providers
login opencode` 登录 Zen。Zen 模型通过 ID 使用，例如 `opencode/glm-5.3-flash`；它们不会显示在选择器中。Zen 和 Go 各自拥有独立的登录状态，因此登录其中一个不会连接另一个。登录有效期为 30 天，Beeuni 会在登录过期前续期。OpenCode 拒绝登录时，Beeuni 会续期一次并重试请求。如果续期也失败，请求会返回 `provider_reauth_required`：请重新登录。

<a id="beeuni-managed-models"></a>

### Beeuni 托管模型

选择器会在 **Beeuni** 下列出这些模型及其 Token 费率。平台通过已配置的模型网关提供凭据。

| 模型 | ID |
| --- | --- |
| GPT-6 Astra | `gpt-6-astra` |
| GPT-6 Sol（平台默认） | `gpt-6-sol` |

其他模型可通过 BYOK 密钥或 ChatGPT 套餐使用。BYOK 密钥可使用其提供商的完整目录，例如，使用 Anthropic 密钥即可使用 `anthropic/claude-opus-5-5`。ChatGPT 套餐可使用 Codex 向 ChatGPT 账户提供的所有模型，例如 `codex/gpt-6.1-sol`。选择器默认显示每个系列中最新的模型。

两个列表都会自动更新。API 每小时读取一次 [models.dev](https://models.dev) 和 Codex CLI 发布的模型列表，因此新模型列出后一小时内就会出现，无需发布 Beeuni 更新。连接提供商后，其最新的稳定工具调用模型会成为默认模型。

<a id="disable-providers-or-models"></a>

## 禁用提供商或模型

打开 **Customize → Models → Providers**。在 **Beeuni** 行中打开 **⋯** 菜单，然后选择 **Disable provider**，即可仅使用自己的提供商。Beeuni 会与其他提供商一起显示在同一列表中，并注明模型数量和点数计费说明。所有提供商都使用相同的菜单。只有已禁用的提供商会显示状态徽标。要恢复访问权限，请从菜单中选择 **Enable provider**。

打开 **Models** 选项卡，可启用或禁用单个模型。禁用某个提供商会阻止其所有模型，包括之后添加的模型。重新启用提供商后，单个模型的选择会保留。凭据会一直保存。

无法禁用项目默认模型及其提供商。请先选择其他已启用的默认模型。项目管理员可以更改访问权限；读取者可以查看。

这些设置适用于通过 Beeuni 网关发出的新请求，包括已保存的会话选择和回退候选项。已发送给上游的请求会正常完成。对已禁用目标的请求会返回 `provider_disabled` 或 `model_disabled`；请选择已启用的模型以继续。标准运行器 原生模式不使用此网关策略。

原有的仅影响选择器显示的偏好设置仍然独立。重置模型列表不会移除明确设置的访问限制。

<a id="thinking-effort"></a>

## 思考强度

在两种模式下，编辑器的思考控制都会将会话的模型设为相应的**变体**。可选项是模型自身发布的等级（models.dev `reasoning_options`），并非固定的级别列表；没有此控制项的模型不会显示控件。`Auto` 会清除变体。

- 原生模式（网关关闭）：标准运行器 会将该变体作为提供商自身的请求字段应用。
- 网关开启：请求会携带 `reasoning_effort`；网关会针对不同上游进行映射（OpenAI → `reasoning_effort`，Claude → 自适应思考，Amazon Bedrock 上的 OpenAI → Bedrock 的 `reasoning.effort` 请求字段）。对于暂时无法映射的上游（目前包括 Nova、Bedrock 上的 Grok），该值会被丢弃，模型按自身默认设置运行。
- Amazon Bedrock 会拒绝大多数当前模型的裸区域内 ID（“不支持按需吞吐量”）。目录中包含 `global.` / 区域推理配置文件 ID 时，选择器会优先使用该 ID；网关则会针对每个配置文件前缀（`global.`、`us.`）对被拒绝的裸 ID 重试一次。
- 沙盒每次启动时都会从 API 获取项目可提供的模型集合（`GET /v1/llm/models?scope=picker`，与 Web 选择器使用相同的组合方式），因此选择器提供的模型在运行环境中始终可以解析。
- 每个模型的项目默认值位于 Customize → Models → Routing → Advanced → **Generation defaults**（`model_generation_config`）。仅当请求未设置某字段时才会填入，因此会话的变体始终优先。

<a id="how-auto-picks-a-model"></a>

## 自动模型选择方式

不指定模型时，Beeuni 会按顺序通过以下五层来解析模型。（ID `auto` 对应相同的行为，但目前还不能在模型选择器中选择。）

1. 显式指定——会话、频道或触发器自身的 `model:` 字段。
2. [代理](/docs/zh/project/agents)针对该项目的默认模型。
3. 项目的默认模型。
4. 账户的默认模型。
5. 平台默认模型。

Beeuni 会使用第一个存在且仍可提供服务的值。已保存的默认模型如果无法继续使用——例如密钥断开连接或模型已退役——会自动跳过。会话不会因默认值失效而中断。触发器的 `model:` 字段请参阅[清单参考](/docs/zh/project/manifest)。

:::warning[BYOK 的计费注意事项]
在付费云账户上，有两项费用容易被忽略：

- 额度用于模型调用、工具和电脑运行。余额请查看 Billing，用量明细请查看 Usage。
- **静默故障转移。** 如果你的 BYOK 密钥在一轮对话中触发速率限制或计费错误，Beeuni 会改用托管模型重试，并从你的点数中扣费，而不是让会话失败。

如果你在仅使用 BYOK 的项目中看到点数扣费，请先检查这两种情况，再报告计费问题。
:::

使用回退模型作答时，会话会说明这一点。编辑器会在模型选择器旁显示 **Running on** 和模型名称。每轮的详情会列出实际作答的模型、被替换的模型，以及 Beeuni 对该轮的计费。**Customize → Models → Costs** 会将这笔费用计入实际作答的模型。

<a id="per-project-model-enablement"></a>

## 按项目启用模型

项目可控制模型选择器提供哪些模型。默认情况下，每个系列中最新的模型都会自动提供。Beeuni 托管模型，以及项目默认设置或路由策略引用的任何模型，始终会被提供——保护规则不会将其移除。

你可以在 **Manage models** 页面（Customize → Models）中为单个模型覆盖默认设置。例外设置按项目保存并立即生效。会话模型选择器和命令面板会隐藏你关闭的模型；随着目录扩展，新模型仍默认开启。

启用设置决定显示哪些模型，而非哪些模型可以提供服务：明确指定已禁用模型的请求（例如通过原始 API 发出的请求）仍会运行。无法关闭项目的默认模型——请先设置其他默认模型。

<a id="provider-keys-and-member-access"></a>

## 提供商密钥与成员访问权限

关闭 **Pooled provider secrets** 后，已连接的提供商密钥适用于整个项目。针对这些项目密钥设置个人覆盖项会返回 `llm_credentials_project_wide`。

启用 Settings → Feature flags 中的 **Pooled provider secrets** 和 **LLM Gateway**，即可使用提供商密钥资源。打开 **Customize → Models → Providers**，然后在提供商旁选择 **Add key**。为每个密钥指定不同的标签。密钥值只允许写入；后续页面会显示其标签和访问列表。

新密钥属于当前项目。默认情况下，**此项目中的所有人**均可使用。打开密钥的 **⋯ → Manage access**，然后选择 **Specific members** 来限制访问。旧版账户级资源会保留其成员授权。账户成员资格、项目权限、代理的密钥权限以及会话选择仍然适用。
成员授权允许使用密钥，但不会泄露密钥。轮换密钥会保留访问权限和会话选择。删除密钥会撤销所有人的访问权限。

<a id="choose-keys-for-a-session"></a>

### 为会话选择密钥

打开编辑器中的 **Session overrides → Provider keys**。选择提供商，然后最多选择十个密钥。在面板底部选择 **Save changes**。新会话会在发送第一条提示时一并提交所选密钥。

- 未明确选择时，现有项目密钥仍可使用。
- 不选择任何密钥会在当前会话中禁用该提供商，不会恢复使用项目密钥。
- **Reset to project default** 会移除明确的选择。
- 已撤销或未启用的密钥会显示为不可用。请将其从选择中移除、选择其他密钥，或重置选择。
- 删除最后一个已选密钥会留下一个空池。会话设置仍会显示该提供商，以便你重置选择。
- 读取失败时会显示 **Try again**。失败的读取结果不会显示为继承的选择。

在输出开始前遇到速率限制时，网关会尝试另一个已选密钥。网关绝不会在不同密钥间重放部分答案。如果所有密钥都受到速率限制，请在最早的冷却时间后重试，等待时间最多为 60 秒。明确指定的密钥池不会静默借用其他成员的密钥或旧版项目凭据。

<a id="chatgpt-accounts"></a>

### ChatGPT 账户

在 **ChatGPT Plus/Pro** 下选择 **Add account**。每次授权都会在此项目中创建一个独立的命名连接。默认情况下，**此项目中的所有人**均可使用。使用 **Manage access → Specific members** 限制访问权限。

会话可以选择多个已授权的 ChatGPT 账户。未选择时，默认使用该成员最新的可用连接。使用其他成员共享的连接需要明确选择。如果成员没有自己的可用连接，旧版项目登录仍可使用。共享的网关密钥无法借用创建者的私人 ChatGPT 连接。

启用网关时，Google Gemini API 密钥会使用 Google 的 OpenAI 兼容端点。标准运行器 原生模式继续使用项目密钥。

受旧版选择器偏好设置隐藏的模型会显示 **Hidden from picker**。仍允许直接请求。打开该模型的菜单并选择 **Disable model**，即可同时阻止推理。

提供商的模型数量链接会打开 **Models** 选项卡。所有提供商分组都会显示在同一个列表中，可在此启用或禁用模型并设置默认值。搜索可缩小列表范围。管理模型前，请先连接提供商。

提供商选择会暂存为草稿，直到你在会话覆盖设置页脚中点击 **Save changes**。此操作会保存所有提供商的更改，包括重置为默认值。你可以切换分区，也可以关闭后重新打开面板，而不会丢失这些草稿。重新加载页面会丢弃未保存的更改。如果保存失败，面板会保持打开并显示错误。请修正选择或重试。已保存的提供商仍会保留已保存状态；未完成的更改会留在面板中。

<a id="budgets"></a>

## 预算

网关预算可限制项目或其中一位成员在每天、每周或每月的模型支出。达到限额时，**Block** 会拒绝新请求；**Warn only** 则允许请求继续运行。请在项目的 Models 页面中设置预算。

达到预算限额的 80% 和 100% 时，Beeuni 会在每个周期内针对每个阈值各发送一次邮件给账户所有者、管理员和项目经理。

<a id="use-the-gateway-from-claude-code"></a>

## 在 Claude Code 中使用网关

网关在 `POST /v1/messages` 提供 Anthropic Messages API。Claude Code 和 Anthropic SDK 可以通过它调用任何网关模型。

1. 在 **Customize → Gateway** 的 **Gateway** 选项卡中创建密钥。
2. 启动 Claude Code，并将网关设为 API 端点：

```bash
ANTHROPIC_BASE_URL=https://gateway.beeuni.ai \
ANTHROPIC_AUTH_TOKEN=beeuni_gw_... \
claude --model kimi-k3
```

网关会从 `Authorization: Bearer` 或 `x-api-key` 读取密钥，因此 `ANTHROPIC_API_KEY` 也可使用。

网关会为每个提供商转换以下 Claude Code 字段：

- `thinking: {type: "adaptive"}` 与 `output_config.effort` 一起使用时会变成
  `reasoning_effort`。请参阅 [思考力度](#thinking-effort)。
- 最终 `message_delta` 上的用量包含 `input_tokens`、
  `cache_read_input_tokens` 和 `cache_creation_input_tokens`。Claude Code
  会使用它们进行 `/context` 和自动压缩。
- 工具返回的图像（例如屏幕截图的 `Read`）会在工具结果之后，通过用户消息发送给模型。
- 提供商流在完成前结束时，会返回一个 `api_error` 事件，
  因此 Claude Code 会重试该轮请求。

限制：

- `/v1/messages/count_tokens` 会返回 `404`。随后 Claude Code 会根据字符数估算
  令牌数。
- 推理文本不会以 `thinking` 块的形式返回。
- ChatGPT 模型（`codex/*`）需要与
  **此项目中的所有人**共享的 ChatGPT 连接。网关密钥无法使用私人连接。
- Claude Code 无法为每个模型单独设置上下文窗口。请将
  `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 设置为你使用的最小窗口。