---
title: "機能フラグ"
description: "1つのプロジェクトでBeeuniのサーフェスを有効にし、各フラグが制御する機能を確認できます。"
---

機能フラグを使うと、1つのプロジェクトでBeeuniの機能を有効にできます。どの機能もフラグの背後に置いてリリースできます。実験的、ベータ、または完全に安定した機能です。「Experimental」はフラグの安定性を示すバッジであり、システムの名前ではありません。

フラグはプロジェクトごとに設定されます。あるプロジェクトでフラグを有効にしても、別のプロジェクトや他のアカウントには影響しません。

<CardGroup>
  <Card icon="app-window" title="Apps" href="/docs/ja/feature-flags/apps">静的サイト、バンドル、Dockerfile、OCIイメージを安定したURLにデプロイします。</Card>
</CardGroup>

<a id="turn-a-flag-on"></a>

## フラグを有効にする

1. **Settings → Feature flags** を開きます。このタブには、プラットフォームがサポートするすべてのフラグが一覧表示されます。
2. 行の内容を確認します。フラグ名、安定性バッジ、説明文、そして起源（`Default on`、`Default off`、または`Overridden for this project`）が表示されます。
3. スイッチを操作します。変更は現在のプロジェクトにすぐ適用されます。

プロジェクトの`project.settings.write`権限が必要です。それ以外の呼び出し元に対して、ルートは`403`を返します。

<a id="from-the-cli"></a>

### CLIから

同じスイッチを、スクリプトやエージェントから`beeuni projects features`経由で操作できます。

```bash
beeuni projects features                # every flag: key, state, origin
beeuni projects features enable reminders
beeuni projects features disable reminders
beeuni projects features reset reminders  # drop the override; follow the platform default
beeuni projects features --json          # the full catalog as JSON
```

リンク済みまたはデフォルト以外のプロジェクトを操作するには、`--project <id>`を追加します。プラットフォームが利用不可としたフラグは、プロジェクト側の設定にかかわらずオフのままです。CLIではこれが`n/a` / `unavailable`と表示されます。

:::info[フラグの状態はリポジトリに保存されません]
プロジェクトごとのフラグ状態は、プロジェクト行のデータベースに保存されます。`beeuni.yaml`から読み込まれることはありません。有効にしたフラグは、リポジトリのクローンやフォークには引き継がれません。
:::

<a id="stability-badges"></a>

## 安定性バッジ

バッジが示すのは契約の状態であり、スイッチの状態ではありません。`stable`フラグも、明示的に有効化する必要があります。`apps`は安定していますが、デフォルトではオフです。

| バッジ | 意味 |
|---|---|
| Experimental | 機能やその契約は、まだ変更される可能性があります。 |
| Beta | 機能は動作しており、仕様が固まりつつあります。 |
| Stable | 契約は維持されます。フラグは引き続き明示的に有効化する必要があります。 |

<a id="how-a-flag-is-enforced"></a>

## フラグの適用方法

各フラグには、適用モードが1つ定義されています。

| モード | フラグがオフのときのサーバーの動作 |
|---|---|
| `routes` | HTTP機能はリクエストを`403`で拒否します。 |
| `behavioral` | 動作は発生しません。コネクタの生成、環境変数の注入、エージェントの登録は行われません。 |
| `ui-only` | サーバーは意図的に適用を行いません。フラグはクライアント側の機能のみを非表示にします。 |

`routes`による拒否の内容は、どこでも同じです。

```json
{
  "error": "Apps is not enabled for this project. Contact Beeuni to enable it.",
  "code": "feature_disabled",
  "feature": "apps"
}
```

`error`文字列が示すのはフラグ一覧であり、特定のタブではありません。一覧はSettingsの**Experimental**タブです。

メッセージ文ではなく、`code`で分岐してください。SDKはまさにこの用途のために`isFeatureDisabledError(error)`と`featureDisabledKey(error)`をエクスポートしています。

<a id="every-flag"></a>

## すべてのフラグ

登録順です。**Settings → Feature flags**に表示される順序と同じです。

Apps と Backends は Beeuni がプロジェクトごとに有効化します。利用を希望する場合は Beeuni にお問い合わせください。有効化後、Settings に **Managed by Beeuni** と表示されます。

| キー | 名前 | 安定性 | デフォルト |
|---|---|---|---|
| `marketplace` | Marketplace | Beta | オン |
| `connectors_api_discover` | Connectors API Discover | Experimental | オフ |
| `agentmail_email` | AgentMail Email | Experimental | オフ |
| `llm_gateway` | LLM Gateway | Experimental | オン（オペレーターがデフォルトをオフにできます） |
| `meta_agent` | Meta Agent | Experimental | オフ |
| `apps` | Apps | Stable | オフ |
| `monitors` | Monitors | Experimental | オフ |
| `reminders` | Reminders | Beta | オフ |
| `warm_sessions` | Warm Sessions | Beta | オン |
| `secrets_egress` | Network-Enforced Secrets | Experimental | オン |
| `pi_harness` | Pi Harness  | Experimental | オフ |

<a id="what-each-flag-gates"></a>

### 各フラグが制御する機能

- **`marketplace`** — コミュニティやベンダーのレジストリからスキルを閲覧、インストールします。
- **`connectors_api_discover`** — 管理対象のOAuthアプリに加えて、直接API、MCP、GraphQL、CLI、Postmanの機能を閲覧します。[Connectors](/docs/ja/connect/connectors)を参照してください。
- **`agentmail_email`** — AgentMailの受信トレイ接続を割り当て、受信メールでセッションを開始・継続できるようにします。
- **`llm_gateway`** — プロジェクトをBeeuni管理のLLMゲートウェイ経由で実行します。[Models](/docs/ja/project/models)を参照してください。
- **`meta_agent`** — 特化したセッションを起動・管理する、プラットフォーム管理のコーディネーターエージェントを追加します。
- **`apps`** — 静的サイト、バンドル、Dockerfile、OCIイメージを、安定したサーバーレスURLにデプロイします。[Apps](/docs/ja/feature-flags/apps)を参照してください。
- **`monitors`** — リポジトリから24時間365日稼働するウォッチャーを実行し、セッションにトリガーイベントを送信します。[Triggers](/docs/ja/connect/triggers)を参照してください。
- **`reminders`** — 1つのセッションに対し、1回または繰り返しの予定チェックインを行います。オフの場合、リマインダールートは`feature_disabled`を返し、既存のリマインダーも実行されません。[Reminders](/docs/ja/connect/reminders)を参照してください。
- **`warm_sessions`** — プロジェクトを開いている間、サンドボックスを1つ起動したままにし、新しいセッションをコールドブートなしで開始できるようにします。
- **`secrets_egress`** — シークレットにネットワーク適用を設定します。サンドボックスにはハンドルを保持し、Beeuniは許可済みホストへのリクエストに限り、実際の値を代わりに注入します。[Secrets](/docs/ja/project/secrets)を参照してください。
- **`pi_harness`** — このプロジェクトのセッションを、通常のセッションサンドボックス（`BEEUNI_HARNESS=pi`）内でpiエージェントハーネスを使って実行します。オンの場合、マニフェストの内容にかかわらず、新規セッションや再起動したセッションはすべてpiを起動します。オフの場合はマニフェストに従います。`runtime: pi`ならpiを起動し、それ以外は標準のエージェントランタイムを起動します。piはLLMゲートウェイ経由でのみモデルを呼び出します。`llm_gateway`がオフの場合、このフラグやマニフェストの内容にかかわらず、すべてのセッションで標準のエージェントランタイムが起動します。いずれの場合も、リポジトリ構成、エージェント、スキルは同じです。実行中のセッションは、再起動または再開するまでハーネスを維持します。piではサブエージェントが動作します。エージェントは`task`ツールを使って`general`、`explore`（読み取り専用）、または`.md`内に`mode: subagent`がある任意のプロジェクトエージェントに作業を委任し、トランスクリプトには各サブエージェントの手順がその場に表示されます。piセッションはpi.devパッケージも読み込みます。[`harnesses:`](/docs/ja/project/manifest#harnesses)を参照してください。piは標準のエージェントランタイムが提供するすべてのセッション機能に対応しているわけではありません。[Harnesses](/docs/ja/work/harnesses#what-each-harness-supports)の比較表を参照してください。

<a id="graduated-flags"></a>

### 一般提供になったフラグ

一般提供になった機能はすべてのプロジェクトで有効で、切り替えスイッチはありません。

- **Agents as principals**はスイッチのない標準動作です。エージェントセッションは、誰が実行してもエージェント自身として動作し、その上限ロールの範囲内でBeeuni権限を持ちます。[Agent permissions](/docs/ja/project/permissions)を参照してください。
- **Review Center**はフラグシステムの対象外になりました。Reviewページ、サイドバーのReview行、コマンドパレットの行はすべてのプロジェクトに表示されます。`project.review.read`と`project.review.act`の権限は引き続き適用されます。`review_center`はフラグキーではなくなりました。`PATCH /v1/projects/:id/features`は`400` `Unknown feature flag`を返し、`beeuni projects features enable
  review_center` prints that error and exits `1`となります。一般提供になる前に保存された上書き設定は影響しません。
- **Computers**はフラグシステムの対象外になりました。すべてのメンバーがプロジェクトのサイドバーから各自のコンピューターを接続できます。唯一のゲートは、プラットフォームの`TUNNEL_ENABLED`設定です。`agent_tunnel`はフラグキーではなくなりました。`PATCH /v1/projects/:id/features`は`400` `Unknown feature flag`を返します。[Computers](/docs/ja/connect/computers)を参照してください。
- **Microsoft Teams**はフラグシステムの対象外になりました。すべてのプロジェクトで**Connectors → Channels**からTeamsを接続できます。テナント管理者による同意は一度必要ですが、プロジェクト独自のボットを使用することもできます。`teams`はフラグキーではなくなりました。`PATCH /v1/projects/:id/features`は`400` `Unknown feature flag`を返します。一般提供になる前に保存された上書き設定は影響しません。[Microsoft Teams](/docs/ja/connect/teams)を参照してください。

<a id="side-effects-of-a-toggle"></a>

## スイッチによる副作用

一部のフラグは、書き込みの確定後にプラットフォームの状態を収束させます。

| フラグ | 切り替え後の動作 |
|---|---|
| `agentmail_email` | Beeuniがチャネルコネクターの生成を再実行し、フラグに応じてコネクターを表示または非表示にします。 |
| `llm_gateway` | Beeuniが新しいプロバイダーモードをアクティブなサンドボックスに反映します。 |

これらの処理は状態を収束させるためのものであり、切り替えの成功条件には含まれません。APIレスポンスは処理の完了を待ちません。各処理は1回再試行され、その後のリコンサイラーは冪等性を備え、定期的なスイープでも再実行されます。

<a id="read-and-set-a-flag-from-code"></a>

## コードからフラグを読み取る、設定する

プロジェクト詳細、またはReactフックから、プロジェクトごとの有効状態を読み取ります。

```tsx
import { useFeatureFlag } from '@beeuni/sdk/react';

function AppsNavItem({ projectId }: { projectId: string }) {
  const apps = useFeatureFlag(projectId, 'apps');
  if (!apps.enabled) return null;
  return <Link href={`/projects/${projectId}/apps`}>Apps</Link>;
}
```

`enabled`が`true`になるのは、サーバーが正確に`true`を返した場合のみです。プロジェクトIDがない場合、クエリの実行中、エラーの場合は、いずれも`false`になります。ゲートはフェイルクローズにしてください。

クライアントを使って、プロジェクトの上書き設定を行います。

```ts
const p = beeuni.project(projectId);

await p.updateFeatureFlag('apps', true);   // turn it on for this project
await p.updateFeatureFlag('apps', null);   // clear the override, inherit the default
```

`updateFeatureFlag`は`PATCH /v1/projects/:id/features`を呼び出します。`feature`は、`@beeuni/sdk`からエクスポートされ、型が`FeatureFlagKey`である`FEATURE_FLAG_KEYS`のいずれかです。SDKリファレンスを参照してください。

機能が無効な場合は、メッセージではなくコードで処理してください。

```ts
import { featureDisabledKey, isFeatureDisabledError } from '@beeuni/sdk';

try {
  await beeuni.project(projectId).apps.list();
} catch (error) {
  if (isFeatureDisabledError(error)) {
    console.log(`${featureDisabledKey(error)} is off for this project`);
  }
}
```