# モデル

Beeuni がモデルを選ぶ仕組みと、マネージドモデルと自分の API キーを使うモデルの料金体系。

Canonical page: https://beeuni.ai/docs/ja/project/models

Beeuniでは、各[セッション](/docs/ja/work/sessions)でモデルを実行します。このページでは、管理モデルと独自のプロバイダーキー（BYOK）の違い、Beeuniがモデルを自動選択する仕組み、知っておきたい2つの課金上の注意点を説明します。

このページは、LLM Gatewayが有効なプロジェクトに適用されます。LLM Gatewayは実験的な[機能フラグ](/docs/ja/feature-flags)で、プラットフォームが提供している環境では**デフォルトで有効**です。Settings → Feature flagsで確認または切り替えできます。

フラグをオフにする方法も完全にサポートされています。その場合、プロジェクトは**標準ハーネスのネイティブなモデル管理**を使用します。そのプロジェクトのすべてのセッションで、標準ハーネスの[harness](/docs/ja/work/harnesses)が実行されます。実験的ハーネスがモデルを呼び出すのはゲートウェイ経由のみです。

- プロバイダーAPIキー（`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、`OPENROUTER_API_KEY`など）は、通常の環境変数としてサンドボックスに渡されます。Model settingsページで追加するか、[シークレット](/docs/ja/project/secrets)として設定してください。標準ハーネスは各キーを使ってプロバイダーに自動接続します。
- モデルIDは`anthropic/claude-opus-4-8`のような、標準ハーネスネイティブの`provider/model`参照です。ゲートウェイが無効な場合、管理対象の単独IDや`beeuni/…`参照は使えません。
- モデルピッカーには、サンドボックスの起動前後で同じリストが表示されます。キーで接続されたプロバイダーと、OpenCode Zenの無料モデルです（OpenCodeはキーなしでZenに接続します）。Thinking effortはコンポーザーの思考制御で、モデル独自のバリエーションを使います。ゲートウェイのGeneration defaultsは適用されません。
- このページで扱うゲートウェイの機能（管理モデル、モデルデフォルトの連鎖、予算、ログ）は適用されません。OpenCodeがサンドボックス内でデフォルトモデルを解決します。

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

## 管理モデルとBYOK

モデルIDは次の3種類です。

- **管理モデル** — `glm-5.2`、`deepseek-v4-pro-0813`、`grok-4.6`のような単独IDです。Beeuniが認証情報を提供します。クラウドアカウントではBeeuniクレジットで支払います。
- **BYOK** — `anthropic/claude-opus-4-8`のような`provider/model`IDです。キーはお客様が用意し、プロバイダーアカウントに課金されます。
- **ChatGPT** — `codex/<id>`IDです。OAuthを使ってChatGPTプランを一度接続すれば、そのプランに課金されます。

プロジェクトのModel settingsページでBYOKキーを接続するか、プロバイダーの環境変数を[シークレット](/docs/ja/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にサインイン）

OpenCode ZenまたはOpenCode Goは、APIキーで接続するか、代わりにOpenCode Consoleアカウントでサインインできます。

1. **Customize → Models → Providers**を開き、**OpenCode Go**を見つけます。
2. **Sign in with OpenCode**を選択します。コードをコピーして**Open auth page**を選び、OpenCodeワークスペースでデバイス認証を承認します。
3. キーフィールドにプロバイダーが接続済みと表示されます。サインアウトするにはキーを削除します。

CLIからは`beeuni providers login opencode-go`を実行します。Zenの場合は`beeuni providers login opencode`です。Zenモデルは`opencode/glm-5.3-flash`のようにIDを指定して使います。モデルピッカーには表示されません。ZenとGoではそれぞれ別のログイン情報を使うため、片方にサインインしても、もう片方は接続されません。ログインの有効期間は30日で、Beeuniが期限前に更新します。OpenCodeがログインを拒否した場合、Beeuniは一度更新を試みてからリクエストを再試行します。更新にも失敗すると、リクエストは`provider_reauth_required`を返します。再度サインインしてください。

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

### Beeuni管理モデル

モデルピッカーには、トークン料金とともに**Beeuni**の下に表示されます。プラットフォームが設定済みのモデルゲートウェイを通じて認証情報を提供します。

| モデル | ID |
| --- | --- |
| GPT-6 Astra | `gpt-6-astra` |
| GPT-6 Sol（プラットフォームのデフォルト） | `gpt-6-sol` |

それ以外のモデルは、BYOKキーまたはChatGPTプランで利用できます。BYOKキーでは、たとえばAnthropicキーで`anthropic/claude-opus-5-5`など、プロバイダーのカタログ全体を利用できます。ChatGPTプランでは、たとえば`codex/gpt-6.1-sol`など、CodexがChatGPTアカウントに提供するすべてのモデルを利用できます。モデルピッカーには、各ファミリーの最新モデルがデフォルトで表示されます。

どちらのリストも自動的に更新されます。APIはmodels.dev](https://models.dev)とCodex CLIが公開するモデルリストを毎時読み込むため、新しいモデルは掲載から1時間以内に表示され、Beeuniのリリースを待つ必要はありません。プロバイダーを接続すると、ツール呼び出しに対応する最新の安定版モデルがデフォルトになります。

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

## プロバイダーまたはモデルを無効にする

**Customize → Models → Providers**を開きます。**Beeuni**の行にある**⋯**メニューを開き、**Disable provider**を選ぶと、自分のプロバイダーだけを使えます。Beeuniは他のプロバイダーと同じリストに、モデル数とクレジット課金についての説明とともに表示されます。すべてのプロバイダーで同じメニューを使います。ステータスバッジが表示されるのは、無効なプロバイダーのみです。アクセスを戻すには、メニューから**Enable provider**を選びます。

**Models**タブを開くと、モデルごとに有効・無効を切り替えられます。プロバイダーを無効にすると、後から追加されたモデルも含め、そのプロバイダーのすべてのモデルがブロックされます。プロバイダーを再び有効にしても、モデルごとの設定は保持されます。認証情報はそのまま保存されます。

プロジェクトのデフォルトモデルとそのプロバイダーは無効にできません。先に別の有効なデフォルトを選択してください。プロジェクト管理者はアクセスを変更でき、閲覧者は確認できます。

これらの設定は、保存済みのセッション選択やフォールバック候補を含め、Beeuniゲートウェイ経由の新しいリクエストに適用されます。すでに上流へ送信済みのリクエストは通常どおり完了します。無効な宛先は`provider_disabled`または`model_disabled`を返します。続行するには、有効なモデルを選択してください。標準ハーネスネイティブモードでは、このゲートウェイポリシーは適用されません。

既存の、モデルピッカーにのみ適用される表示設定は別に管理されます。モデルリストをリセットしても、明示的なアクセス制限は解除されません。

## Thinking effort

コンポーザーの思考制御は、どちらのモードでもセッションのモデル**バリエーション**を設定します。選択肢はモデルごとに公開されている段階（models.dev `reasoning_options`）であり、固定の段階設定ではありません。調整項目のないモデルには、制御項目は表示されません。`Auto`を指定すると、バリエーションが解除されます。

- ネイティブ（ゲートウェイ無効）：標準ハーネスは、プロバイダー固有のリクエストフィールドとしてバリエーションを適用します。
- ゲートウェイ有効：リクエストには`reasoning_effort`が含まれます。ゲートウェイは上流ごとに対応する値へ変換します（OpenAI → `reasoning_effort`、Claude → adaptive thinking、Amazon Bedrock上のOpenAI → Bedrockの`reasoning.effort`リクエストフィールド）。まだ変換に対応していない上流（現在のNova、Bedrock上のGrokなど）では値が破棄され、モデル独自のデフォルトで実行されます。
- Amazon Bedrockは、現在のほとんどのモデルについて、リージョン内のベアIDを受け付けません（「on-demand throughput isn't supported」）。カタログにある場合、モデルピッカーは`global.`またはリージョン別推論プロファイルのIDを優先します。また、ゲートウェイは拒否されたベアIDを、プロファイルのプレフィックスごとに1回再試行します（`global.`、`us.`）。
- サンドボックスは起動のたびにAPIからプロジェクトで利用可能なモデル一覧を取得します（`GET /v1/llm/models?scope=picker`。ウェブのモデルピッカーと同じ構成です）。そのため、モデルピッカーに表示されるモデルは、実行時にも必ず解決できます。
- モデルごとのプロジェクトデフォルトは、Customize → Models → Routing → Advanced → **Generation defaults**（`model_generation_config`）で設定します。リクエスト側で未指定のフィールドにのみ適用されるため、セッションのバリエーションが常に優先されます。

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

## モデルの自動選択方法

モデルを指定しない場合、Beeuniは次の5つのレイヤーを順番に確認して解決します。（ID `auto`も同じ動作を表しますが、現時点ではモデルピッカーから選択できません。）

1. セッション、チャネル、トリガー自体の`model:`フィールドによる明示的な固定設定。
2. このプロジェクトに対する[エージェント](/docs/ja/project/agents)のデフォルト。
3. プロジェクトのデフォルト。
4. アカウントのデフォルト。
5. プラットフォームのデフォルト。

Beeuniは、利用可能な値がある最初のレイヤーを使用します。切断されたキーや廃止されたモデルなど、保存済みのデフォルトが使えなくなっている場合は自動的にスキップされます。古いデフォルトが原因でセッションが終了することはありません。トリガーの`model:`フィールドについては、[マニフェストリファレンス](/docs/ja/project/manifest)を参照してください。

> **BYOKの課金に関する注意**
>
> 有料クラウドアカウントで見落としやすい費用が2つあります。
>
> - クレジットはモデル呼び出し、ツール、コンピューターの利用に使われます。残高は Billing、利用明細は Usage で確認できます。
> - **通知なしのフェイルオーバー。** BYOKキーがターンの途中でレート制限または課金エラーに達すると、Beeuniは管理モデルで再試行し、セッションを失敗させる代わりにクレジットを請求します。
>
> BYOKのみのプロジェクトでクレジットが請求された場合は、課金バグとして報告する前に、この2つの原因をご確認ください。

フォールバックモデルが応答すると、セッションにその旨が表示されます。コンポーザーには、モデル選択欄の横に**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**を選択します。キーごとに異なるラベルを付けてください。値は書き込み専用で、後の画面ではラベルとアクセスリストが表示されます。

新しいキーはこのプロジェクトに属します。デフォルトでは、**Everyone in this project**が利用できます。キーの**⋯ → Manage access**を開き、**Specific members**を選ぶとアクセスを制限できます。従来のアカウント全体に適用されるリソースでは、メンバーへの許可設定が維持されます。アカウントのメンバーシップ、プロジェクトの権限、エージェントのシークレット権限、セッションの選択も引き続き適用されます。
メンバーへの許可があれば、キーの値を見せることなく利用できます。キーをローテーションしても、アクセス許可とセッションの選択は維持されます。キーを削除すると、すべてのユーザーがアクセスできなくなります。

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

### セッションで使うキーを選ぶ

コンポーザーで**Session overrides → Provider keys**を開きます。プロバイダーを選び、最大10個のキーを選択します。パネル下部で**Save changes**を選択します。新しいセッションの場合、選択内容は最初のプロンプトとともに送信されます。

- 明示的に選択しない場合、既存のプロジェクトキーを引き続き利用できます。
- キーを選択しない場合、そのセッションではプロバイダーが無効になります。プロジェクトキーが再び有効になることはありません。
- 明示的な選択を解除するには、**Reset to project default**を選びます。
- 取り消し済みまたは無効なキーは利用不可として表示されます。選択から削除するか、別のキーを選ぶか、選択をリセットしてください。
- 選択済みの最後のキーを削除すると、空のプールになります。セッション設定には引き続きそのプロバイダーが表示されるため、リセットできます。
- 読み込みに失敗すると**Try again**が表示されます。継承された選択として表示されることはありません。

出力が始まる前にレート制限が発生すると、ゲートウェイは選択された別のキーを試します。部分的な回答を別のキーで再実行することはありません。すべてのキーがレート制限されている場合は、最も早いクールダウンの終了後に再試行してください。待機時間は最大60秒です。明示的なプールが設定されている場合、他のメンバーのキーや従来のプロジェクト認証情報を通知なしに借用することはありません。

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

### ChatGPTアカウント

**ChatGPT Plus/Pro**の下にある**Add account**を選択します。認証するたびに、このプロジェクトに名前付きの接続が個別に作成されます。デフォルトでは、**Everyone in this project**が利用できます。アクセスを制限するには、**Manage access → Specific members**を選びます。

セッションでは、許可されたChatGPTアカウントを複数選択できます。選択しない場合、メンバーが利用できる接続のうち最も新しいものがデフォルトになります。他のメンバーが共有する接続を使うには、明示的に選択する必要があります。メンバー自身が利用できる接続を持っていない場合は、従来のプロジェクトログインを引き続き利用できます。共有ゲートウェイキーから、その作成者の個人用ChatGPT接続を借用することはできません。

ゲートウェイが有効な場合、Google Gemini APIキーはGoogleのOpenAI互換エンドポイントを使用します。標準ハーネスネイティブモードでは、引き続きプロジェクトシークレットを使います。

以前のモデルピッカー設定で非表示にされたモデルには、**Hidden from picker**と表示されます。直接リクエストは引き続き許可されます。推論もブロックするには、そのモデルのメニューを開き、**Disable model**を選びます。

プロバイダーのモデル数リンクを選ぶと、**Models**タブが開きます。すべてのプロバイダーグループが、有効・無効の切り替えやデフォルト設定に使う同じリストに表示されます。検索するとリストを絞り込めます。モデルを管理する前に、プロバイダーを接続してください。

プロバイダーの選択内容は、セッションオーバーライドの下部にある**Save changes**をクリックするまで下書きとして保持されます。これを保存すると、デフォルトへのリセットを含め、すべてのプロバイダーの変更が保存されます。セクションの切り替えやパネルの閉じ直しをしても、下書きは失われません。ページを再読み込みすると、未保存の変更は破棄されます。

保存に失敗すると、パネルは開いたままエラーを表示します。選択内容を修正するか、再試行してください。保存済みのプロバイダーはそのまま保存され、未完了の変更はパネルに残ります。

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

## 予算

ゲートウェイの予算を設定すると、プロジェクト全体またはそのプロジェクトの特定メンバーが、1日、1週間、または1か月にモデルに使える金額を制限できます。**Block**は上限に達すると新しいリクエストを拒否し、**Warn only**はそのまま実行します。プロジェクトのModelsページで予算を設定してください。

予算上限の80%と100%に達すると、Beeuniは各期間・各しきい値につき1回、アカウントのオーナーと管理者、およびプロジェクトマネージャーにメールを送信します。

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

## Claude Codeからゲートウェイを使う

ゲートウェイはAnthropic Messages APIを`POST /v1/messages`で提供します。Claude CodeとAnthropic SDKから、ゲートウェイを通じて任意のモデルを呼び出せます。

1. **Customize → Gateway**の**Gateway**タブでキーを作成します。
2. ゲートウェイをAPIエンドポイントに指定してClaude Codeを起動します。

```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](#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` を設定してください。