diff --git a/docs/ja-JP/channels/msteams.md b/docs/ja-JP/channels/msteams.md index 9f453f309..293518c44 100644 --- a/docs/ja-JP/channels/msteams.md +++ b/docs/ja-JP/channels/msteams.md @@ -1,56 +1,56 @@ --- read_when: - - Microsoft Teams チャネル機能に取り組んでいるとき -summary: Microsoft Teams ボットサポートのステータス、機能、設定 + - Microsoft Teams チャネル機能に取り組んでいます +summary: Microsoft Teams ボットのサポート状況、機能、設定 title: Microsoft Teams x-i18n: - generated_at: "2026-04-05T12:37:26Z" + generated_at: "2026-04-12T00:18:53Z" model: gpt-5.4 provider: openai - source_hash: 99fc6e136893ec65dc85d3bc0c0d92134069a2f3b8cb4fcf66c14674399b3eaf + source_hash: 3e6841a618fb030e4c2029b3652d45dedd516392e2ae17309ff46b93648ffb79 source_path: channels/msteams.md workflow: 15 --- # Microsoft Teams -> 「ここに入る者は一切の希望を捨てよ。」 +> 「ここに足を踏み入れる者は、一切の希望を捨てよ。」 -更新日: 2026-01-21 +更新日: 2026-03-25 -ステータス: テキスト + DM 添付ファイルをサポートしています。チャネル/グループでのファイル送信には `sharePointSiteId` + Graph 権限が必要です（[グループチャットでのファイル送信](#sending-files-in-group-chats)を参照）。投票は Adaptive Cards 経由で送信されます。メッセージアクションでは、ファイル優先送信のための明示的な `upload-file` が公開されています。 +ステータス: テキスト + DM 添付ファイルをサポートしています。チャネル/グループでのファイル送信には `sharePointSiteId` + Graph 権限が必要です（[グループチャットでのファイル送信](#sending-files-in-group-chats) を参照）。Polls は Adaptive Cards 経由で送信されます。メッセージアクションでは、ファイル優先送信向けに明示的な `upload-file` が公開されています。 ## バンドル済みプラグイン -Microsoft Teams は現在の OpenClaw リリースではバンドル済みプラグインとして提供されているため、通常のパッケージビルドでは -別途インストールは不要です。 +Microsoft Teams は現在の OpenClaw リリースではバンドル済みプラグインとして提供されるため、 +通常のパッケージ版ビルドでは別途インストールは不要です。 -古いビルドや、バンドル済み Teams を含まないカスタムインストールを使っている場合は、 -手動でインストールしてください。 +古いビルドを使用している場合、またはバンドル済み Teams を含まないカスタムインストールの場合は、 +手動でインストールしてください: ```bash openclaw plugins install @openclaw/msteams ``` -ローカルチェックアウト（git リポジトリから実行している場合）: +ローカルチェックアウト（git リポジトリから実行する場合）: ```bash openclaw plugins install ./path/to/local/msteams-plugin ``` -詳細: [プラグイン](/tools/plugin) +詳細: [プラグイン](/ja-JP/tools/plugin) -## クイックセットアップ（初級者向け） +## クイックセットアップ（初心者向け） 1. Microsoft Teams プラグインが利用可能であることを確認します。 - - 現在のパッケージ版 OpenClaw リリースには、すでにバンドルされています。 + - 現在のパッケージ版 OpenClaw リリースにはすでにバンドルされています。 - 古い/カスタムインストールでは、上記のコマンドで手動追加できます。 -2. **Azure Bot** を作成します（App ID + client secret + tenant ID）。 -3. それらの認証情報で OpenClaw を設定します。 -4. 公開 URL またはトンネル経由で `/api/messages`（既定ではポート 3978）を公開します。 -5. Teams アプリパッケージをインストールし、Gateway を起動します。 +2. **Azure Bot** を作成します（App ID + クライアントシークレット + テナント ID）。 +3. その認証情報で OpenClaw を設定します。 +4. 公開 URL またはトンネル経由で `/api/messages`（デフォルトはポート 3978）を公開します。 +5. Teams アプリパッケージをインストールして Gateway を起動します。 -最小設定: +最小構成（クライアントシークレット）: ```json5 { @@ -66,17 +66,19 @@ openclaw plugins install ./path/to/local/msteams-plugin } ``` -注: グループチャットは既定でブロックされます（`channels.msteams.groupPolicy: "allowlist"`）。グループ返信を許可するには、`channels.msteams.groupAllowFrom` を設定してください（または `groupPolicy: "open"` を使って任意のメンバーを許可し、メンションゲート付きにします）。 +本番デプロイでは、クライアントシークレットの代わりに [フェデレーション認証](#federated-authentication-certificate--managed-identity)（証明書またはマネージド ID）の使用を検討してください。 -## 目的 +注意: グループチャットはデフォルトでブロックされています（`channels.msteams.groupPolicy: "allowlist"`）。グループ返信を許可するには、`channels.msteams.groupAllowFrom` を設定してください（または、メンション制御付きで任意のメンバーを許可するには `groupPolicy: "open"` を使用してください）。 + +## 目標 - Teams の DM、グループチャット、またはチャネル経由で OpenClaw とやり取りする。 - ルーティングを決定的に保つ: 返信は常に受信したチャネルに戻る。 -- チャネルでの安全な動作を既定にする（設定しない限りメンションが必要）。 +- 安全なチャネル動作をデフォルトにする（設定しない限りメンション必須）。 ## 設定の書き込み -既定では、Microsoft Teams は `/config set|unset` によってトリガーされる設定更新の書き込みを許可されています（`commands.config: true` が必要です）。 +デフォルトでは、Microsoft Teams は `/config set|unset` によってトリガーされる設定更新の書き込みを許可されています（`commands.config: true` が必要です）。 無効にするには: @@ -90,16 +92,16 @@ openclaw plugins install ./path/to/local/msteams-plugin **DM アクセス** -- 既定値: `channels.msteams.dmPolicy = "pairing"`。未知の送信者は承認されるまで無視されます。 -- `channels.msteams.allowFrom` には安定した AAD オブジェクト ID を使うべきです。 -- UPN/表示名は変更可能です。直接一致は既定で無効であり、`channels.msteams.dangerouslyAllowNameMatching: true` でのみ有効になります。 -- 認証情報に十分な権限があれば、ウィザードは Microsoft Graph 経由で名前を ID に解決できます。 +- デフォルト: `channels.msteams.dmPolicy = "pairing"`。未承認の送信者は承認されるまで無視されます。 +- `channels.msteams.allowFrom` には安定した AAD オブジェクト ID を使用してください。 +- UPN/表示名は変更可能です。直接一致はデフォルトで無効で、`channels.msteams.dangerouslyAllowNameMatching: true` を指定した場合のみ有効になります。 +- 認証情報が許可していれば、ウィザードは Microsoft Graph 経由で名前を ID に解決できます。 **グループアクセス** -- 既定値: `channels.msteams.groupPolicy = "allowlist"`（`groupAllowFrom` を追加するまでブロック）。未設定時の既定値を上書きするには `channels.defaults.groupPolicy` を使います。 +- デフォルト: `channels.msteams.groupPolicy = "allowlist"`（`groupAllowFrom` を追加しない限りブロックされます）。未設定時のデフォルトを上書きするには `channels.defaults.groupPolicy` を使います。 - `channels.msteams.groupAllowFrom` は、グループチャット/チャネルでどの送信者がトリガーできるかを制御します（`channels.msteams.allowFrom` にフォールバックします）。 -- `groupPolicy: "open"` を設定すると任意のメンバーを許可します（それでも既定ではメンションゲート付きです）。 +- 任意のメンバーを許可するには `groupPolicy: "open"` を設定します（それでもデフォルトではメンション制御されます）。 - **チャネルを一切許可しない**場合は、`channels.msteams.groupPolicy: "disabled"` を設定します。 例: @@ -117,12 +119,12 @@ openclaw plugins install ./path/to/local/msteams-plugin **Teams + チャネル許可リスト** -- `channels.msteams.teams` の下に teams と channels を列挙することで、グループ/チャネル返信の範囲を制限します。 -- キーには安定した team ID と channel conversation ID を使うべきです。 -- `groupPolicy="allowlist"` で teams 許可リストが存在する場合、列挙された teams/channels のみが受け付けられます（メンションゲート付き）。 -- 設定ウィザードは `Team/Channel` エントリを受け付け、それらを保存します。 -- 起動時に、OpenClaw は team/channel とユーザーの許可リスト名を ID に解決し（Graph 権限があれば）、 - その対応をログに出力します。未解決の team/channel 名は入力されたまま保持されますが、既定ではルーティングでは無視されます。`channels.msteams.dangerouslyAllowNameMatching: true` が有効な場合を除きます。 +- `channels.msteams.teams` の下に teams と channels を列挙して、グループ/チャネル返信の範囲を制限します。 +- キーには安定した team ID と channel conversation ID を使用してください。 +- `groupPolicy="allowlist"` で teams の許可リストが存在する場合、列挙された teams/channels のみが受け付けられます（メンション制御あり）。 +- 設定ウィザードでは `Team/Channel` エントリを受け付け、それらを保存します。 +- 起動時に、OpenClaw は team/channel およびユーザー許可リストの名前を ID に解決し（Graph 権限が許可している場合）、 + マッピングをログ出力します。解決できない team/channel 名は入力されたまま保持されますが、デフォルトではルーティングで無視されます。`channels.msteams.dangerouslyAllowNameMatching: true` が有効な場合を除きます。 例: @@ -143,16 +145,16 @@ openclaw plugins install ./path/to/local/msteams-plugin } ``` -## 動作の仕組み +## 仕組み 1. Microsoft Teams プラグインが利用可能であることを確認します。 - - 現在のパッケージ版 OpenClaw リリースには、すでにバンドルされています。 + - 現在のパッケージ版 OpenClaw リリースにはすでにバンドルされています。 - 古い/カスタムインストールでは、上記のコマンドで手動追加できます。 -2. **Azure Bot** を作成します（App ID + secret + tenant ID）。 -3. ボットを参照し、以下の RSC 権限を含む **Teams app package** を作成します。 -4. Teams アプリを team にアップロード/インストールします（または DM 用に personal スコープ）。 +2. **Azure Bot** を作成します（App ID + シークレット + テナント ID）。 +3. ボットを参照し、以下の RSC 権限を含む **Teams アプリパッケージ** を作成します。 +4. Teams アプリを team にアップロード/インストールします（または DM 用に個人スコープにインストールします）。 5. `~/.openclaw/openclaw.json`（または環境変数）で `msteams` を設定し、Gateway を起動します。 -6. Gateway は既定で `/api/messages` 上の Bot Framework webhook トラフィックを待ち受けます。 +6. Gateway はデフォルトで `/api/messages` 上の Bot Framework webhook トラフィックを待ち受けます。 ## Azure Bot セットアップ（前提条件） @@ -163,18 +165,18 @@ OpenClaw を設定する前に、Azure Bot リソースを作成する必要が 1. [Create Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot) に移動します 2. **Basics** タブに入力します: - | フィールド | 値 | + | フィールド | 値 | | ------------------ | -------------------------------------------------------- | - | **Bot handle** | ボット名。例: `openclaw-msteams`（一意である必要があります） | - | **Subscription** | Azure サブスクリプションを選択 | - | **Resource group** | 新規作成または既存を使用 | - | **Pricing tier** | 開発/テスト用は **Free** | - | **Type of App** | **Single Tenant**（推奨。以下の注を参照） | - | **Creation type** | **Create new Microsoft App ID** | + | **Bot handle** | ボット名。例: `openclaw-msteams`（一意である必要があります） | + | **Subscription** | Azure サブスクリプションを選択 | + | **Resource group** | 新規作成するか既存のものを使用 | + | **Pricing tier** | 開発/テスト用は **Free** | + | **Type of App** | **Single Tenant**（推奨 - 下記の注記を参照） | + | **Creation type** | **Create new Microsoft App ID** | -> **非推奨に関する通知:** 新しい multi-tenant bot の作成は 2025-07-31 以降非推奨になりました。新しいボットでは **Single Tenant** を使用してください。 +> **非推奨に関する通知:** 新しいマルチテナントボットの作成は 2025-07-31 以降非推奨になりました。新しいボットには **Single Tenant** を使用してください。 -3. **Review + create** → **Create** をクリックします（1〜2 分ほど待ちます） +3. **Review + create** → **Create** をクリックします（約 1〜2 分待ちます） ### ステップ 2: 認証情報を取得する @@ -184,12 +186,12 @@ OpenClaw を設定する前に、Azure Bot リソースを作成する必要が 4. **Certificates & secrets** → **New client secret** → **Value** をコピーします → これが `appPassword` です 5. **Overview** に移動します → **Directory (tenant) ID** をコピーします → これが `tenantId` です -### ステップ 3: Messaging Endpoint を設定する +### ステップ 3: メッセージングエンドポイントを設定する 1. Azure Bot → **Configuration** -2. **Messaging endpoint** に webhook URL を設定します: - - 本番環境: `https://your-domain.com/api/messages` - - ローカル開発: トンネルを使用します（以下の[ローカル開発](#local-development-tunneling)を参照） +2. **Messaging endpoint** を webhook URL に設定します: + - 本番: `https://your-domain.com/api/messages` + - ローカル開発: トンネルを使用します（下記の [ローカル開発](#local-development-tunneling) を参照） ### ステップ 4: Teams チャネルを有効にする @@ -197,28 +199,170 @@ OpenClaw を設定する前に、Azure Bot リソースを作成する必要が 2. **Microsoft Teams** → Configure → Save をクリックします 3. 利用規約に同意します +## フェデレーション認証（証明書 + マネージド ID） + +> 2026.3.24 で追加 + +本番デプロイ向けに、OpenClaw はクライアントシークレットより安全な代替手段として **フェデレーション認証** をサポートしています。利用可能な方法は 2 つあります: + +### オプション A: 証明書ベース認証 + +Entra ID アプリ登録に登録された PEM 証明書を使用します。 + +**セットアップ:** + +1. 証明書を生成または取得します（秘密鍵を含む PEM 形式）。 +2. Entra ID → App Registration → **Certificates & secrets** → **Certificates** → 公開証明書をアップロードします。 + +**設定:** + +```json5 +{ + channels: { + msteams: { + enabled: true, + appId: "", + tenantId: "", + authType: "federated", + certificatePath: "/path/to/cert.pem", + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +**環境変数:** + +- `MSTEAMS_AUTH_TYPE=federated` +- `MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem` + +### オプション B: Azure Managed Identity + +パスワードレス認証に Azure Managed Identity を使用します。これは、マネージド ID が利用可能な Azure インフラストラクチャ（AKS、App Service、Azure VM）上のデプロイに最適です。 + +**仕組み:** + +1. ボットの pod/VM にはマネージド ID（システム割り当てまたはユーザー割り当て）があります。 +2. **フェデレーション ID 資格情報** が、そのマネージド ID を Entra ID アプリ登録に関連付けます。 +3. 実行時に、OpenClaw は `@azure/identity` を使用して Azure IMDS エンドポイント（`169.254.169.254`）からトークンを取得します。 +4. そのトークンがボット認証のために Teams SDK に渡されます。 + +**前提条件:** + +- マネージド ID が有効な Azure インフラストラクチャ（AKS workload identity、App Service、VM） +- Entra ID アプリ登録上に作成されたフェデレーション ID 資格情報 +- pod/VM から IMDS（`169.254.169.254:80`）へのネットワークアクセス + +**設定（システム割り当てマネージド ID）:** + +```json5 +{ + channels: { + msteams: { + enabled: true, + appId: "", + tenantId: "", + authType: "federated", + useManagedIdentity: true, + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +**設定（ユーザー割り当てマネージド ID）:** + +```json5 +{ + channels: { + msteams: { + enabled: true, + appId: "", + tenantId: "", + authType: "federated", + useManagedIdentity: true, + managedIdentityClientId: "", + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +**環境変数:** + +- `MSTEAMS_AUTH_TYPE=federated` +- `MSTEAMS_USE_MANAGED_IDENTITY=true` +- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=`（ユーザー割り当ての場合のみ） + +### AKS Workload Identity のセットアップ + +workload identity を使用する AKS デプロイの場合: + +1. AKS クラスターで **workload identity** を有効にします。 +2. Entra ID アプリ登録上に **フェデレーション ID 資格情報** を作成します: + + ```bash + az ad app federated-credential create --id --parameters '{ + "name": "my-bot-workload-identity", + "issuer": "", + "subject": "system:serviceaccount::", + "audiences": ["api://AzureADTokenExchange"] + }' + ``` + +3. **Kubernetes service account** にアプリ client ID のアノテーションを付けます: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: my-bot-sa + annotations: + azure.workload.identity/client-id: "" + ``` + +4. workload identity を注入するために **pod** にラベルを付けます: + + ```yaml + metadata: + labels: + azure.workload.identity/use: "true" + ``` + +5. IMDS（`169.254.169.254`）への **ネットワークアクセス** を確保します — NetworkPolicy を使用している場合は、`169.254.169.254/32` のポート 80 へのトラフィックを許可する egress ルールを追加してください。 + +### 認証タイプの比較 + +| 方法 | 設定 | 長所 | 短所 | +| -------------------- | ---------------------------------------------- | ---------------------------------- | ------------------------------------- | +| **クライアントシークレット** | `appPassword` | セットアップが簡単 | シークレットのローテーションが必要、より安全性が低い | +| **証明書** | `authType: "federated"` + `certificatePath` | ネットワーク上で共有シークレットが不要 | 証明書管理のオーバーヘッドがある | +| **Managed Identity** | `authType: "federated"` + `useManagedIdentity` | パスワードレス、管理するシークレット不要 | Azure インフラストラクチャが必要 | + +**デフォルトの動作:** `authType` が設定されていない場合、OpenClaw はクライアントシークレット認証をデフォルトで使用します。既存の設定は変更なしで引き続き動作します。 + ## ローカル開発（トンネリング） -Teams は `localhost` に到達できません。ローカル開発ではトンネルを使います。 +Teams は `localhost` に到達できません。ローカル開発にはトンネルを使用してください: **オプション A: ngrok** ```bash ngrok http 3978 # https URL をコピーします。例: https://abc123.ngrok.io -# Messaging endpoint を次に設定します: https://abc123.ngrok.io/api/messages +# メッセージングエンドポイントを次に設定します: https://abc123.ngrok.io/api/messages ``` **オプション B: Tailscale Funnel** ```bash tailscale funnel 3978 -# Messaging endpoint として Tailscale funnel URL を使います +# Tailscale funnel URL をメッセージングエンドポイントとして使用します ``` ## Teams Developer Portal（代替手段） -manifest ZIP を手作業で作成する代わりに、[Teams Developer Portal](https://dev.teams.microsoft.com/apps) を使用できます。 +manifest ZIP を手動で作成する代わりに、[Teams Developer Portal](https://dev.teams.microsoft.com/apps) を使用できます: 1. **+ New app** をクリックします 2. 基本情報（名前、説明、開発者情報）を入力します @@ -228,45 +372,45 @@ manifest ZIP を手作業で作成する代わりに、[Teams Developer Portal]( 6. **Distribute** → **Download app package** をクリックします 7. Teams で: **Apps** → **Manage your apps** → **Upload a custom app** → ZIP を選択します -これは JSON manifest を手作業で編集するより簡単なことが多いです。 +これは JSON manifest を手動編集するより簡単なことが多いです。 ## ボットのテスト -**オプション A: Azure Web Chat（先に webhook を確認する）** +**オプション A: Azure Web Chat（最初に webhook を検証）** -1. Azure Portal → Azure Bot リソース → **Test in Web Chat** -2. メッセージを送信します。応答が表示されるはずです -3. これにより、Teams セットアップ前に webhook endpoint が機能していることを確認できます +1. Azure Portal → 対象の Azure Bot リソース → **Test in Web Chat** +2. メッセージを送信します - 応答が表示されるはずです +3. これにより、Teams の設定前に webhook エンドポイントが動作していることを確認できます **オプション B: Teams（アプリインストール後）** 1. Teams アプリをインストールします（サイドロードまたは組織カタログ） -2. Teams でボットを見つけ、DM を送信します +2. Teams でボットを見つけて DM を送信します 3. 受信アクティビティについて Gateway ログを確認します ## セットアップ（最小のテキスト専用） -1. **Microsoft Teams プラグインが利用可能であることを確認する** - - 現在のパッケージ版 OpenClaw リリースには、すでにバンドルされています。 - - 古い/カスタムインストールでは、手動追加できます: +1. **Microsoft Teams プラグインが利用可能であることを確認** + - 現在のパッケージ版 OpenClaw リリースにはすでにバンドルされています。 + - 古い/カスタムインストールでは、手動で追加できます: - npm から: `openclaw plugins install @openclaw/msteams` - ローカルチェックアウトから: `openclaw plugins install ./path/to/local/msteams-plugin` 2. **ボット登録** - Azure Bot を作成し（上記参照）、以下を控えます: - App ID - - Client secret（App password） - - Tenant ID（single-tenant） + - クライアントシークレット（App password） + - テナント ID（シングルテナント） -3. **Teams app manifest** - - `bot` エントリに `botId = ` を含めます。 +3. **Teams アプリ manifest** + - `botId = ` を持つ `bot` エントリを含めます。 - スコープ: `personal`、`team`、`groupChat`。 - - `supportsFiles: true`（personal スコープでのファイル処理に必要）。 + - `supportsFiles: true`（個人スコープでのファイル処理に必要）。 - RSC 権限を追加します（下記）。 - - アイコンを作成します: `outline.png`（32x32）と `color.png`（192x192）。 - - 3 つのファイルを一緒に zip 化します: `manifest.json`、`outline.png`、`color.png`。 + - アイコンを作成します: `outline.png`（32x32）および `color.png`（192x192）。 + - 3 つのファイル `manifest.json`、`outline.png`、`color.png` をまとめて zip 化します。 -4. **OpenClaw を設定する** +4. **OpenClaw を設定** ```json5 { @@ -282,59 +426,64 @@ manifest ZIP を手作業で作成する代わりに、[Teams Developer Portal]( } ``` - 設定キーの代わりに環境変数も使えます: + 設定キーの代わりに環境変数も使用できます: - `MSTEAMS_APP_ID` - `MSTEAMS_APP_PASSWORD` - `MSTEAMS_TENANT_ID` + - `MSTEAMS_AUTH_TYPE`（任意: `"secret"` または `"federated"`） + - `MSTEAMS_CERTIFICATE_PATH`（federated + 証明書） + - `MSTEAMS_CERTIFICATE_THUMBPRINT`（任意、認証には必須ではありません） + - `MSTEAMS_USE_MANAGED_IDENTITY`（federated + managed identity） + - `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID`（ユーザー割り当て MI のみ） -5. **ボット endpoint** - - Azure Bot Messaging Endpoint を次のように設定します: +5. **ボットエンドポイント** + - Azure Bot Messaging Endpoint を次に設定します: - `https://:3978/api/messages`（または選択したパス/ポート）。 -6. **Gateway を実行する** - - Teams チャネルは、バンドル済みまたは手動インストールされたプラグインが利用可能で、認証情報を含む `msteams` 設定が存在すれば自動的に起動します。 +6. **Gateway を実行** + - バンドル済みまたは手動インストール済みのプラグインが利用可能で、認証情報付きの `msteams` 設定が存在する場合、Teams チャネルは自動的に起動します。 ## メンバー情報アクション -OpenClaw は Microsoft Teams 向けに Graph ベースの `member-info` アクションを公開しており、エージェントやオートメーションが Microsoft Graph から直接チャネルメンバーの詳細（表示名、メールアドレス、ロール）を解決できます。 +OpenClaw は Microsoft Teams 向けに Graph をバックエンドとする `member-info` アクションを公開しているため、エージェントや自動化で Microsoft Graph からチャネルメンバーの詳細（表示名、メールアドレス、ロール）を直接解決できます。 要件: - `Member.Read.Group` RSC 権限（推奨 manifest にすでに含まれています） - team をまたぐ検索の場合: 管理者同意付きの `User.Read.All` Graph Application 権限 -このアクションは `channels.msteams.actions.memberInfo` で制御されます（既定: Graph 認証情報が利用可能な場合は有効）。 +このアクションは `channels.msteams.actions.memberInfo` によって制御されます（デフォルト: Graph 認証情報が利用可能な場合に有効）。 ## 履歴コンテキスト -- `channels.msteams.historyLimit` は、プロンプトに含める最近のチャネル/グループメッセージ数を制御します。 -- `messages.groupChat.historyLimit` にフォールバックします。`0` を設定すると無効になります（既定 50）。 -- 取得したスレッド履歴は送信者許可リスト（`allowFrom` / `groupAllowFrom`）でフィルタリングされるため、スレッドコンテキストのシードには許可された送信者からのメッセージのみが含まれます。 -- 引用された添付ファイルコンテキスト（Teams の返信 HTML 由来の `ReplyTo*`）は、現在は受信したまま渡されます。 -- つまり、許可リストは誰がエージェントをトリガーできるかを制御し、現在フィルタリングされるのは特定の補助的なコンテキスト経路のみです。 -- DM 履歴は `channels.msteams.dmHistoryLimit`（ユーザーターン）で制限できます。ユーザーごとの上書き: `channels.msteams.dms[""].historyLimit`。 +- `channels.msteams.historyLimit` は、直近のチャネル/グループメッセージをいくつ prompt に含めるかを制御します。 +- `messages.groupChat.historyLimit` にフォールバックします。無効化するには `0` を設定します（デフォルトは 50）。 +- 取得されたスレッド履歴は送信者の許可リスト（`allowFrom` / `groupAllowFrom`）によってフィルタリングされるため、スレッドコンテキストのシードには許可された送信者のメッセージのみが含まれます。 +- 引用された添付ファイルコンテキスト（Teams の返信 HTML に由来する `ReplyTo*`）は、現時点では受信したまま渡されます。 +- 言い換えると、許可リストは誰がエージェントをトリガーできるかを制御しますが、現時点でフィルタリングされるのは特定の補助コンテキスト経路のみです。 +- DM 履歴は `channels.msteams.dmHistoryLimit`（ユーザーターン数）で制限できます。ユーザーごとの上書き: `channels.msteams.dms[""].historyLimit`。 ## 現在の Teams RSC 権限（Manifest） -これらは Teams app manifest 内の**既存の resourceSpecific permissions** です。これらはアプリがインストールされている team/chat 内でのみ適用されます。 +これらは Teams アプリ manifest にある**既存の resourceSpecific 権限**です。これらはアプリがインストールされている team/chat 内でのみ適用されます。 **チャネル用（team スコープ）:** -- `ChannelMessage.Read.Group`（Application）- @メンションなしで全チャネルメッセージを受信 -- `ChannelMessage.Send.Group`（Application） -- `Member.Read.Group`（Application） -- `Owner.Read.Group`（Application） -- `ChannelSettings.Read.Group`（Application） -- `TeamMember.Read.Group`（Application） -- `TeamSettings.Read.Group`（Application） +- `ChannelMessage.Read.Group` (Application) - @mention なしで全チャネルメッセージを受信 +- `ChannelMessage.Send.Group` (Application) +- `Member.Read.Group` (Application) +- `Owner.Read.Group` (Application) +- `ChannelSettings.Read.Group` (Application) +- `TeamMember.Read.Group` (Application) +- `TeamSettings.Read.Group` (Application) **グループチャット用:** -- `ChatMessage.Read.Chat`（Application）- @メンションなしで全グループチャットメッセージを受信 +- `ChatMessage.Read.Chat` (Application) - @mention なしで全グループチャットメッセージを受信 -## Teams Manifest の例（機密情報削除済み） +## Teams Manifest の例（機微情報を削除済み） -必要なフィールドを含む最小で有効な例です。ID と URL は置き換えてください。 +必須フィールドを備えた最小限の有効な例です。ID と URL を置き換えてください。 ```json5 { @@ -384,146 +533,151 @@ OpenClaw は Microsoft Teams 向けに Graph ベースの `member-info` アク ### Manifest の注意点（必須フィールド） -- `bots[].botId` は Azure Bot App ID と**一致している必要があります**。 -- `webApplicationInfo.id` は Azure Bot App ID と**一致している必要があります**。 -- `bots[].scopes` には、使用する予定のサーフェス（`personal`、`team`、`groupChat`）を含める必要があります。 -- `bots[].supportsFiles: true` は personal スコープでのファイル処理に必要です。 -- `authorization.permissions.resourceSpecific` には、チャネルトラフィックが必要ならチャネルの読み取り/送信を含める必要があります。 +- `bots[].botId` は Azure Bot App ID と**必ず**一致している必要があります。 +- `webApplicationInfo.id` は Azure Bot App ID と**必ず**一致している必要があります。 +- `bots[].scopes` には使用予定のサーフェス（`personal`、`team`、`groupChat`）を含める必要があります。 +- `bots[].supportsFiles: true` は個人スコープでのファイル処理に必要です。 +- チャネルトラフィックを利用したい場合、`authorization.permissions.resourceSpecific` にはチャネルの読み取り/送信を含める必要があります。 ### 既存アプリの更新 -すでにインストール済みの Teams アプリを更新するには（たとえば RSC 権限を追加する場合）: +すでにインストール済みの Teams アプリを更新するには（例: RSC 権限を追加する場合）: -1. `manifest.json` を新しい設定で更新します +1. 新しい設定で `manifest.json` を更新します 2. **`version` フィールドをインクリメント**します（例: `1.0.0` → `1.1.0`） -3. アイコン付きで manifest を**再 zip 化**します（`manifest.json`、`outline.png`、`color.png`） +3. アイコン付きで manifest を**再度 zip 化**します（`manifest.json`、`outline.png`、`color.png`） 4. 新しい zip をアップロードします: - **オプション A（Teams Admin Center）:** Teams Admin Center → Teams apps → Manage apps → 対象アプリを見つける → Upload new version - **オプション B（サイドロード）:** Teams → Apps → Manage your apps → Upload a custom app -5. **team チャネルの場合:** 新しい権限を有効にするには、各 team でアプリを再インストールします -6. キャッシュされたアプリメタデータをクリアするため、**Teams を完全終了して再起動**します（ウィンドウを閉じるだけでは不十分です） +5. **team チャネルの場合:** 新しい権限を有効にするため、各 team でアプリを再インストールします +6. キャッシュされたアプリメタデータを消去するため、Teams を**完全に終了して再起動**します（ウィンドウを閉じるだけでは不十分です） ## 機能: RSC のみ vs Graph -### **Teams RSC のみ**の場合（アプリはインストール済み、Graph API 権限なし） +### **Teams RSC のみ**の場合（アプリインストール済み、Graph API 権限なし） 動作するもの: - チャネルメッセージの**テキスト**内容の読み取り。 -- チャネルメッセージの**テキスト**送信。 -- **personal（DM）** のファイル添付の受信。 +- チャネルメッセージの**テキスト**内容の送信。 +- **個人（DM）** のファイル添付の受信。 動作しないもの: -- チャネル/グループの**画像またはファイル内容**（ペイロードには HTML スタブしか含まれません）。 +- チャネル/グループの**画像またはファイル内容**（ペイロードには HTML スタブのみが含まれます）。 - SharePoint/OneDrive に保存された添付ファイルのダウンロード。 -- メッセージ履歴の読み取り（ライブ webhook イベントを超えるもの）。 +- メッセージ履歴の読み取り（ライブ webhook イベントを超える分）。 -### **Teams RSC + Microsoft Graph Application permissions** の場合 +### **Teams RSC + Microsoft Graph Application 権限**の場合 追加されるもの: - ホストされたコンテンツのダウンロード（メッセージに貼り付けられた画像）。 - SharePoint/OneDrive に保存されたファイル添付のダウンロード。 -- Graph 経由のチャネル/チャットメッセージ履歴の読み取り。 +- Graph 経由でのチャネル/チャットのメッセージ履歴の読み取り。 -### RSC と Graph API の比較 +### RSC vs Graph API -| 機能 | RSC 権限 | Graph API | -| ----------------------- | -------------------- | ----------------------------------- | -| **リアルタイムメッセージ** | はい（webhook 経由） | いいえ（ポーリングのみ） | -| **過去メッセージ** | いいえ | はい（履歴を問い合わせ可能） | -| **セットアップの複雑さ** | アプリ manifest のみ | 管理者同意 + トークンフローが必要 | -| **オフライン動作** | いいえ（実行中である必要あり） | はい（いつでも問い合わせ可能） | +| 機能 | RSC 権限 | Graph API | +| ----------------------- | -------------------- | ------------------------------------ | +| **リアルタイムメッセージ** | Yes (via webhook) | No (polling only) | +| **履歴メッセージ** | No | Yes (can query history) | +| **セットアップの複雑さ** | App manifest only | Requires admin consent + token flow | +| **オフライン動作** | No (must be running) | Yes (query anytime) | -**要点:** RSC はリアルタイムの受信向けであり、Graph API は過去のアクセス向けです。オフライン中に見逃したメッセージを取り込むには、`ChannelMessage.Read.All` を持つ Graph API が必要です（管理者同意が必要）。 +**要点:** RSC はリアルタイム監視用、Graph API は履歴アクセス用です。オフライン中に見逃したメッセージを追いつくには、`ChannelMessage.Read.All` を備えた Graph API が必要です（管理者同意が必要）。 -## Graph 対応メディア + 履歴（チャネルでは必須） +## Graph 対応のメディア + 履歴（チャネルで必須） -**チャネル**内で画像/ファイルが必要な場合、または**メッセージ履歴**を取得したい場合は、Microsoft Graph 権限を有効にして管理者同意を与える必要があります。 +**チャネル**で画像/ファイルが必要な場合、または**メッセージ履歴**を取得したい場合は、Microsoft Graph 権限を有効化し、管理者同意を付与する必要があります。 -1. Entra ID（Azure AD）の **App Registration** で、Microsoft Graph の **Application permissions** を追加します: +1. Entra ID (Azure AD) の **App Registration** で、Microsoft Graph の **Application 権限**を追加します: - `ChannelMessage.Read.All`（チャネル添付 + 履歴） - `Chat.Read.All` または `ChatMessage.Read.All`（グループチャット） 2. テナントに対して**管理者同意を付与**します。 -3. Teams アプリの **manifest version** を更新し、再アップロードして、**Teams 内でアプリを再インストール**します。 -4. キャッシュされたアプリメタデータをクリアするため、**Teams を完全終了して再起動**します。 +3. Teams アプリの **manifest version** を上げて、再アップロードし、**Teams でアプリを再インストール**します。 +4. キャッシュされたアプリメタデータを消去するため、**Teams を完全に終了して再起動**します。 -**ユーザーメンション向け追加権限:** 会話内のユーザーに対する @mentions は、そのままで動作します。ただし、**現在の会話にいない**ユーザーを動的に検索してメンションしたい場合は、`User.Read.All`（Application）権限を追加し、管理者同意を付与してください。 +**ユーザーメンション用の追加権限:** ユーザーの @mention は、その会話内のユーザーであればそのまま動作します。ただし、**現在の会話に含まれていない**ユーザーを動的に検索してメンションしたい場合は、`User.Read.All` (Application) 権限を追加し、管理者同意を付与してください。 ## 既知の制限 ### Webhook タイムアウト -Teams は HTTP webhook 経由でメッセージを配信します。処理に時間がかかりすぎる場合（たとえば LLM 応答が遅い場合）、次のような問題が起こることがあります。 +Teams は HTTP webhook 経由でメッセージを配信します。処理に時間がかかりすぎる場合（例: LLM の応答が遅い場合）、次のようなことが起こる可能性があります: -- Gateway のタイムアウト -- Teams によるメッセージの再試行（重複の原因） -- 返信の欠落 +- Gateway タイムアウト +- Teams がメッセージを再試行する（重複の原因） +- 返信が失われる -OpenClaw は、すばやく応答を返し、その後で proactive に返信を送ることでこれに対処していますが、非常に遅い応答では依然として問題が発生することがあります。 +OpenClaw は、すばやく応答を返してから積極的に返信を送信することでこれに対処していますが、非常に遅い応答では依然として問題が発生する可能性があります。 ### 書式設定 -Teams の markdown は Slack や Discord より制限があります。 +Teams の markdown は Slack や Discord より制限があります: - 基本的な書式は動作します: **太字**、_斜体_、`code`、リンク -- 複雑な markdown（表、ネストしたリスト）は正しくレンダリングされないことがあります -- 投票や任意のカード送信には Adaptive Cards をサポートしています（以下参照） +- 複雑な markdown（表、ネストしたリスト）は正しく表示されない場合があります +- Polls および任意のカード送信用に Adaptive Cards がサポートされています（下記参照） ## 設定 -主要な設定（共有チャネルパターンについては `/gateway/configuration` を参照）: +主な設定（共有チャネルパターンについては `/gateway/configuration` を参照）: -- `channels.msteams.enabled`: チャネルの有効/無効。 +- `channels.msteams.enabled`: チャネルを有効/無効にします。 - `channels.msteams.appId`、`channels.msteams.appPassword`、`channels.msteams.tenantId`: ボット認証情報。 -- `channels.msteams.webhook.port`（既定 `3978`） -- `channels.msteams.webhook.path`（既定 `/api/messages`） -- `channels.msteams.dmPolicy`: `pairing | allowlist | open | disabled`（既定: pairing） -- `channels.msteams.allowFrom`: DM 許可リスト（AAD オブジェクト ID 推奨）。Graph アクセスが利用可能な場合、ウィザードはセットアップ中に名前を ID に解決します。 -- `channels.msteams.dangerouslyAllowNameMatching`: 変更可能な UPN/表示名一致と、team/channel 名による直接ルーティングを再有効化するための非常用トグル。 +- `channels.msteams.webhook.port`（デフォルト `3978`） +- `channels.msteams.webhook.path`（デフォルト `/api/messages`） +- `channels.msteams.dmPolicy`: `pairing | allowlist | open | disabled`（デフォルト: pairing） +- `channels.msteams.allowFrom`: DM 許可リスト（AAD オブジェクト ID を推奨）。Graph アクセスが利用可能な場合、ウィザードはセットアップ時に名前を ID に解決します。 +- `channels.msteams.dangerouslyAllowNameMatching`: 変更可能な UPN/表示名マッチングと、team/channel 名による直接ルーティングを再有効化するための非常用トグル。 - `channels.msteams.textChunkLimit`: 送信テキストのチャンクサイズ。 -- `channels.msteams.chunkMode`: `length`（既定）または `newline`。長さでのチャンク化の前に、空行（段落境界）で分割します。 -- `channels.msteams.mediaAllowHosts`: 受信添付ファイルホストの許可リスト（既定は Microsoft/Teams ドメイン）。 -- `channels.msteams.mediaAuthAllowHosts`: メディア再試行時に Authorization ヘッダーを付けるホストの許可リスト（既定は Graph + Bot Framework ホスト）。 -- `channels.msteams.requireMention`: チャネル/グループで @mention を必須にする（既定 true）。 -- `channels.msteams.replyStyle`: `thread | top-level`（[返信スタイル](#reply-style-threads-vs-posts)を参照）。 -- `channels.msteams.teams..replyStyle`: team ごとの上書き。 -- `channels.msteams.teams..requireMention`: team ごとの上書き。 -- `channels.msteams.teams..tools`: team ごとの既定ツールポリシー上書き（`allow`/`deny`/`alsoAllow`）。チャネル上書きがない場合に使われます。 -- `channels.msteams.teams..toolsBySender`: team ごとの送信者別ツールポリシー上書き（`"*"` ワイルドカード対応）。 -- `channels.msteams.teams..channels..replyStyle`: チャネルごとの上書き。 -- `channels.msteams.teams..channels..requireMention`: チャネルごとの上書き。 +- `channels.msteams.chunkMode`: `length`（デフォルト）または `newline`。長さによる分割の前に空行（段落境界）で分割します。 +- `channels.msteams.mediaAllowHosts`: 受信添付ファイルホストの許可リスト（デフォルトは Microsoft/Teams ドメイン）。 +- `channels.msteams.mediaAuthAllowHosts`: メディア再試行時に Authorization ヘッダーを付与するホストの許可リスト（デフォルトは Graph + Bot Framework ホスト）。 +- `channels.msteams.requireMention`: チャネル/グループで @mention を必須にします（デフォルト true）。 +- `channels.msteams.replyStyle`: `thread | top-level`（[返信スタイル](#reply-style-threads-vs-posts) を参照）。 +- `channels.msteams.teams..replyStyle`: team ごとの上書き設定。 +- `channels.msteams.teams..requireMention`: team ごとの上書き設定。 +- `channels.msteams.teams..tools`: team ごとのデフォルトツールポリシー上書き（`allow`/`deny`/`alsoAllow`）。チャネル上書きがない場合に使用されます。 +- `channels.msteams.teams..toolsBySender`: team ごとの送信者別デフォルトツールポリシー上書き（`"*"` ワイルドカード対応）。 +- `channels.msteams.teams..channels..replyStyle`: チャネルごとの上書き設定。 +- `channels.msteams.teams..channels..requireMention`: チャネルごとの上書き設定。 - `channels.msteams.teams..channels..tools`: チャネルごとのツールポリシー上書き（`allow`/`deny`/`alsoAllow`）。 - `channels.msteams.teams..channels..toolsBySender`: チャネルごとの送信者別ツールポリシー上書き（`"*"` ワイルドカード対応）。 -- `toolsBySender` のキーには明示的な接頭辞を使うべきです: - `id:`、`e164:`、`username:`、`name:`（従来の接頭辞なしキーも引き続き `id:` にのみマップされます）。 -- `channels.msteams.actions.memberInfo`: Graph ベースの member info アクションを有効または無効にする（既定: Graph 認証情報がある場合は有効）。 -- `channels.msteams.sharePointSiteId`: グループチャット/チャネルでのファイルアップロード用 SharePoint site ID（[グループチャットでのファイル送信](#sending-files-in-group-chats)を参照）。 +- `toolsBySender` のキーには明示的なプレフィックスを使用してください: + `id:`、`e164:`、`username:`、`name:`（従来のプレフィックスなしキーも引き続き `id:` のみにマップされます）。 +- `channels.msteams.actions.memberInfo`: Graph をバックエンドとする member info アクションを有効または無効にします（デフォルト: Graph 認証情報が利用可能な場合に有効）。 +- `channels.msteams.authType`: 認証タイプ — `"secret"`（デフォルト）または `"federated"`。 +- `channels.msteams.certificatePath`: PEM 証明書ファイルへのパス（federated + 証明書認証）。 +- `channels.msteams.certificateThumbprint`: 証明書サムプリント（任意、認証には必須ではありません）。 +- `channels.msteams.useManagedIdentity`: managed identity 認証を有効にします（federated モード）。 +- `channels.msteams.managedIdentityClientId`: ユーザー割り当て managed identity 用の client ID。 +- `channels.msteams.sharePointSiteId`: グループチャット/チャネルでのファイルアップロード用 SharePoint site ID（[グループチャットでのファイル送信](#sending-files-in-group-chats) を参照）。 ## ルーティングとセッション -- セッションキーは標準のエージェント形式に従います（[/concepts/session](/concepts/session)を参照）: +- セッションキーは標準のエージェント形式に従います（[/concepts/session](/ja-JP/concepts/session) を参照）: - ダイレクトメッセージはメインセッションを共有します（`agent::`）。 - - チャネル/グループメッセージは conversation id を使います: + - チャネル/グループメッセージは conversation id を使用します: - `agent::msteams:channel:` - `agent::msteams:group:` ## 返信スタイル: スレッド vs 投稿 -Teams は最近、同じ基盤データモデルの上で 2 種類のチャネル UI スタイルを導入しました。 +Teams は最近、同じ基盤データモデル上で 2 つのチャネル UI スタイルを導入しました: -| スタイル | 説明 | 推奨 `replyStyle` | -| ------------------------ | --------------------------------------------------------- | ------------------------ | -| **投稿**（クラシック） | メッセージはカードとして表示され、その下にスレッド返信が並ぶ | `thread`（既定） | -| **スレッド**（Slack 風） | メッセージが Slack のように直線的に流れる | `top-level` | +| スタイル | 説明 | 推奨 `replyStyle` | +| ------------------------ | --------------------------------------------------------- | --------------------- | +| **Posts**（クラシック） | メッセージはカードとして表示され、その下にスレッド返信が表示される | `thread`（デフォルト） | +| **Threads**（Slack 風） | メッセージはより Slack のように直線的に流れる | `top-level` | -**問題:** Teams API は、チャネルがどの UI スタイルを使っているかを公開しません。誤った `replyStyle` を使うと: +**問題点:** Teams API は、チャネルがどの UI スタイルを使っているかを公開しません。誤った `replyStyle` を使うと: - Threads スタイルのチャネルで `thread` → 返信が不自然にネストされて表示される -- Posts スタイルのチャネルで `top-level` → 返信がスレッド内ではなく独立したトップレベル投稿として表示される +- Posts スタイルのチャネルで `top-level` → 返信がスレッド内ではなく別のトップレベル投稿として表示される -**解決策:** チャネルの設定に基づいて、チャネルごとに `replyStyle` を設定します。 +**解決策:** チャネルの設定方法に基づいて、チャネルごとに `replyStyle` を設定します: ```json5 { @@ -549,32 +703,32 @@ Teams は最近、同じ基盤データモデルの上で 2 種類のチャネ **現在の制限:** - **DM:** 画像とファイル添付は Teams ボットのファイル API 経由で動作します。 -- **チャネル/グループ:** 添付ファイルは M365 ストレージ（SharePoint/OneDrive）に存在します。webhook ペイロードには実際のファイルバイトではなく HTML スタブしか含まれません。チャネル添付をダウンロードするには **Graph API 権限が必要** です。 -- 明示的なファイル優先送信には、`media` / `filePath` / `path` とともに `action=upload-file` を使います。任意の `message` は付随するテキスト/コメントになり、`filename` はアップロード名を上書きします。 +- **チャネル/グループ:** 添付ファイルは M365 ストレージ（SharePoint/OneDrive）に保存されます。webhook ペイロードには実際のファイルバイトではなく HTML スタブのみが含まれます。チャネル添付をダウンロードするには **Graph API 権限が必要です**。 +- 明示的なファイル優先送信には、`media` / `filePath` / `path` とともに `action=upload-file` を使用します。任意の `message` は添付テキスト/コメントになり、`filename` はアップロード名を上書きします。 -Graph 権限がない場合、画像付きのチャネルメッセージはテキストのみとして受信されます（画像内容にはボットからアクセスできません）。 -既定では、OpenClaw は Microsoft/Teams ホスト名からのみメディアをダウンロードします。`channels.msteams.mediaAllowHosts` で上書きできます（任意のホストを許可するには `["*"]` を使います）。 -Authorization ヘッダーは `channels.msteams.mediaAuthAllowHosts` に含まれるホストに対してのみ付与されます（既定は Graph + Bot Framework ホスト）。このリストは厳格に保ってください（multi-tenant サフィックスは避けてください）。 +Graph 権限がない場合、画像を含むチャネルメッセージはテキストのみとして受信されます（画像内容にはボットからアクセスできません）。 +デフォルトでは、OpenClaw は Microsoft/Teams ホスト名からのみメディアをダウンロードします。`channels.msteams.mediaAllowHosts` で上書きできます（任意のホストを許可するには `["*"]` を使用）。 +Authorization ヘッダーは `channels.msteams.mediaAuthAllowHosts` に含まれるホストに対してのみ付与されます（デフォルトは Graph + Bot Framework ホスト）。このリストは厳密に保ってください（マルチテナントのサフィックスは避けてください）。 ## グループチャットでのファイル送信 -ボットは DM では FileConsentCard フロー（組み込み）を使ってファイルを送信できます。しかし、**グループチャット/チャネルでのファイル送信**には追加設定が必要です。 +ボットは DMs では FileConsentCard フロー（組み込み）を使ってファイルを送信できます。ただし、**グループチャット/チャネルでのファイル送信**には追加設定が必要です: -| コンテキスト | ファイル送信方法 | 必要なセットアップ | -| ------------------------ | -------------------------------------------- | ----------------------------------------------- | -| **DM** | FileConsentCard → ユーザーが承認 → ボットがアップロード | そのままで動作 | -| **グループチャット/チャネル** | SharePoint にアップロード → 共有リンク | `sharePointSiteId` + Graph 権限が必要 | -| **画像（任意のコンテキスト）** | Base64 エンコードされたインライン | そのままで動作 | +| コンテキスト | ファイル送信方法 | 必要なセットアップ | +| ------------------------ | -------------------------------------------- | ------------------------------------------------- | +| **DMs** | FileConsentCard → ユーザーが承認 → ボットがアップロード | そのままで動作 | +| **グループチャット/チャネル** | SharePoint にアップロード → 共有リンク | `sharePointSiteId` + Graph 権限が必要 | +| **画像（任意のコンテキスト）** | Base64 エンコードのインライン | そのままで動作 | ### グループチャットで SharePoint が必要な理由 -ボットには personal OneDrive ドライブがありません（`/me/drive` Graph API endpoint は application identity では動作しません）。グループチャット/チャネルでファイルを送るには、ボットは **SharePoint site** にアップロードし、共有リンクを作成します。 +ボットには個人用 OneDrive ドライブがありません（Graph API の `/me/drive` エンドポイントはアプリケーション ID では動作しません）。グループチャット/チャネルでファイルを送信するには、ボットは **SharePoint site** にアップロードし、共有リンクを作成します。 ### セットアップ -1. Entra ID（Azure AD）→ App Registration で **Graph API 権限** を追加します: - - `Sites.ReadWrite.All`（Application）- SharePoint へファイルをアップロード - - `Chat.Read.All`（Application）- 任意。ユーザーごとの共有リンクを有効化 +1. Entra ID (Azure AD) → App Registration で **Graph API 権限**を追加します: + - `Sites.ReadWrite.All` (Application) - SharePoint にファイルをアップロード + - `Chat.Read.All` (Application) - 任意、ユーザーごとの共有リンクを有効化 2. テナントに対して**管理者同意を付与**します。 @@ -589,7 +743,7 @@ Authorization ヘッダーは `channels.msteams.mediaAuthAllowHosts` に含ま curl -H "Authorization: Bearer $TOKEN" \ "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles" - # 応答には次が含まれます: "id": "contoso.sharepoint.com,guid1,guid2" + # レスポンスには次が含まれます: "id": "contoso.sharepoint.com,guid1,guid2" ``` 4. **OpenClaw を設定します:** @@ -607,38 +761,38 @@ Authorization ヘッダーは `channels.msteams.mediaAuthAllowHosts` に含ま ### 共有動作 -| 権限 | 共有動作 | -| --------------------------------------- | --------------------------------------------------------- | -| `Sites.ReadWrite.All` のみ | 組織全体の共有リンク（組織内の誰でもアクセス可能） | +| 権限 | 共有動作 | +| --------------------------------------- | ---------------------------------------------------------- | +| `Sites.ReadWrite.All` のみ | 組織全体共有リンク（組織内の全員がアクセス可能） | | `Sites.ReadWrite.All` + `Chat.Read.All` | ユーザーごとの共有リンク（チャットメンバーのみアクセス可能） | -ユーザーごとの共有の方が、チャット参加者のみがファイルにアクセスできるため、より安全です。`Chat.Read.All` 権限がない場合、ボットは組織全体共有にフォールバックします。 +ユーザーごとの共有のほうが、チャット参加者のみがファイルにアクセスできるため、より安全です。`Chat.Read.All` 権限がない場合、ボットは組織全体共有にフォールバックします。 ### フォールバック動作 -| シナリオ | 結果 | +| シナリオ | 結果 | | ------------------------------------------------- | -------------------------------------------------- | -| グループチャット + ファイル + `sharePointSiteId` 設定済み | SharePoint にアップロードし、共有リンクを送信 | -| グループチャット + ファイル + `sharePointSiteId` なし | OneDrive アップロードを試行（失敗する場合あり）、テキストのみ送信 | -| personal チャット + ファイル | FileConsentCard フロー（SharePoint なしで動作） | -| 任意のコンテキスト + 画像 | Base64 エンコードされたインライン（SharePoint なしで動作） | +| グループチャット + ファイル + `sharePointSiteId` 設定済み | SharePoint にアップロードし、共有リンクを送信 | +| グループチャット + ファイル + `sharePointSiteId` なし | OneDrive アップロードを試行（失敗する場合あり）、テキストのみ送信 | +| 個人チャット + ファイル | FileConsentCard フロー（SharePoint なしで動作） | +| 任意のコンテキスト + 画像 | Base64 エンコードのインライン（SharePoint なしで動作） | -### ファイルの保存場所 +### ファイル保存場所 -アップロードされたファイルは、設定された SharePoint site の既定ドキュメントライブラリ内の `/OpenClawShared/` フォルダに保存されます。 +アップロードされたファイルは、設定された SharePoint site の既定ドキュメントライブラリ内の `/OpenClawShared/` フォルダーに保存されます。 -## 投票（Adaptive Cards） +## Polls（Adaptive Cards） -OpenClaw は Teams の投票を Adaptive Cards として送信します（Teams ネイティブの poll API はありません）。 +OpenClaw は Teams の Polls を Adaptive Cards として送信します（Teams のネイティブな poll API はありません）。 - CLI: `openclaw message poll --channel msteams --target conversation: ...` -- 投票は Gateway によって `~/.openclaw/msteams-polls.json` に記録されます。 +- 投票は Gateway により `~/.openclaw/msteams-polls.json` に記録されます。 - 投票を記録するには Gateway がオンラインのままである必要があります。 -- 投票結果の要約はまだ自動投稿されません（必要に応じてストアファイルを確認してください）。 +- Polls はまだ結果サマリーを自動投稿しません（必要に応じて保存ファイルを確認してください）。 ## Adaptive Cards（任意） -`message` ツールまたは CLI を使って、任意の Adaptive Card JSON を Teams ユーザーまたは会話に送信できます。 +`message` ツールまたは CLI を使って、任意の Adaptive Card JSON を Teams ユーザーまたは conversation に送信できます。 `card` パラメータは Adaptive Card JSON オブジェクトを受け取ります。`card` が指定されている場合、メッセージテキストは任意です。 @@ -665,18 +819,18 @@ openclaw message send --channel msteams \ --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}' ``` -カードスキーマと例については、[Adaptive Cards documentation](https://adaptivecards.io/) を参照してください。target 形式の詳細については、以下の[ターゲット形式](#target-formats)を参照してください。 +カードスキーマと例については [Adaptive Cards documentation](https://adaptivecards.io/) を参照してください。target 形式の詳細については、下記の [Target formats](#target-formats) を参照してください。 -## ターゲット形式 +## Target formats -MSTeams の target では、ユーザーと会話を区別するために接頭辞を使います。 +MSTeams の target は、ユーザーと conversation を区別するためにプレフィックスを使用します: -| ターゲット種別 | 形式 | 例 | -| ------------------- | -------------------------------- | --------------------------------------------------- | -| ユーザー（ID 指定） | `user:` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` | -| ユーザー（名前指定） | `user:` | `user:John Smith`（Graph API が必要） | -| グループ/チャネル | `conversation:` | `conversation:19:abc123...@thread.tacv2` | -| グループ/チャネル（生値） | `` | `19:abc123...@thread.tacv2`（`@thread` を含む場合） | +| target タイプ | 形式 | 例 | +| ---------------------- | -------------------------------- | --------------------------------------------------- | +| ユーザー（ID 指定） | `user:` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` | +| ユーザー（名前指定） | `user:` | `user:John Smith`（Graph API が必要） | +| グループ/チャネル | `conversation:` | `conversation:19:abc123...@thread.tacv2` | +| グループ/チャネル（生） | `` | `19:abc123...@thread.tacv2`（`@thread` を含む場合） | **CLI の例:** @@ -684,13 +838,13 @@ MSTeams の target では、ユーザーと会話を区別するために接頭 # ID でユーザーに送信 openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello" -# 表示名でユーザーに送信（Graph API 検索をトリガー） +# 表示名でユーザーに送信（Graph API 参照をトリガー） openclaw message send --channel msteams --target "user:John Smith" --message "Hello" # グループチャットまたはチャネルに送信 openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello" -# 会話に Adaptive Card を送信 +# conversation に Adaptive Card を送信 openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \ --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello"}]}' ``` @@ -719,23 +873,23 @@ openclaw message send --channel msteams --target "conversation:19:abc...@thread. } ``` -注: `user:` 接頭辞がない場合、名前は既定でグループ/team 解決になります。表示名で人を指定する場合は、必ず `user:` を使ってください。 +注意: `user:` プレフィックスがない場合、名前はデフォルトで group/team 解決として扱われます。表示名で人を指定する場合は、必ず `user:` を使用してください。 -## Proactive メッセージング +## プロアクティブメッセージング -- Proactive メッセージは、会話参照をその時点で保存するため、ユーザーがやり取りした**後でのみ**可能です。 -- `dmPolicy` と許可リストゲートについては `/gateway/configuration` を参照してください。 +- プロアクティブメッセージは、会話参照をその時点で保存するため、ユーザーが一度やり取りした**後でのみ**可能です。 +- `dmPolicy` と許可リストによる制御については `/gateway/configuration` を参照してください。 -## Team と Channel ID（よくある落とし穴） +## Team ID と Channel ID（よくある落とし穴） -Teams URL の `groupId` クエリパラメータは、設定に使う team ID **ではありません**。代わりに URL パスから ID を抽出してください。 +Teams URL の `groupId` クエリパラメータは、設定で使用する team ID **ではありません**。代わりに URL パスから ID を抽出してください: **Team URL:** ``` https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=... └────────────────────────────┘ - Team ID（これを URL デコードします） + Team ID（これを URL デコード） ``` **Channel URL:** @@ -743,55 +897,55 @@ https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?gro ``` https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=... └─────────────────────────┘ - Channel ID（これを URL デコードします） + Channel ID（これを URL デコード） ``` -**設定用:** +**設定で使う値:** -- Team ID = `/team/` の後のパスセグメント（URL デコードしたもの。例: `19:Bk4j...@thread.tacv2`） -- Channel ID = `/channel/` の後のパスセグメント（URL デコードしたもの） -- `groupId` クエリパラメータは**無視**します +- Team ID = `/team/` の後のパスセグメント（URL デコード済み。例: `19:Bk4j...@thread.tacv2`） +- Channel ID = `/channel/` の後のパスセグメント（URL デコード済み） +- `groupId` クエリパラメータは**無視**してください ## プライベートチャネル -ボットはプライベートチャネルではサポートが限定的です。 +ボットのプライベートチャネル対応は限定的です: -| 機能 | 標準チャネル | プライベートチャネル | +| 機能 | 標準チャネル | プライベートチャネル | | ---------------------------- | ----------------- | ---------------------- | -| ボットインストール | はい | 限定的 | -| リアルタイムメッセージ（webhook） | はい | 動作しない場合あり | -| RSC 権限 | はい | 動作が異なる場合あり | -| @mentions | はい | ボットにアクセスできる場合 | -| Graph API 履歴 | はい（権限あり） | はい（権限あり） | +| ボットのインストール | Yes | Limited | +| リアルタイムメッセージ（webhook） | Yes | May not work | +| RSC 権限 | Yes | May behave differently | +| @mentions | Yes | If bot is accessible | +| Graph API 履歴 | Yes | Yes (with permissions) | **プライベートチャネルで動作しない場合の回避策:** -1. ボットとのやり取りには標準チャネルを使う -2. DM を使う - ユーザーは常にボットへ直接メッセージできます -3. 過去アクセスには Graph API を使う（`ChannelMessage.Read.All` が必要） +1. ボットとのやり取りには標準チャネルを使用する +2. DM を使用する - ユーザーは常にボットに直接メッセージできます +3. 履歴アクセスには Graph API を使用する（`ChannelMessage.Read.All` が必要） ## トラブルシューティング ### よくある問題 -- **チャネルで画像が表示されない:** Graph 権限または管理者同意が不足しています。Teams アプリを再インストールし、Teams を完全終了して再起動してください。 -- **チャネルで応答がない:** 既定ではメンションが必要です。`channels.msteams.requireMention=false` を設定するか、team/channel ごとに設定してください。 -- **バージョン不一致（Teams に古い manifest が表示される）:** アプリを削除して再追加し、Teams を完全終了して更新してください。 -- **webhook から 401 Unauthorized:** Azure JWT なしで手動テストした場合は想定内です。endpoint には到達しているが認証に失敗したことを意味します。正しくテストするには Azure Web Chat を使ってください。 +- **チャネルで画像が表示されない:** Graph 権限または管理者同意が不足しています。Teams アプリを再インストールし、Teams を完全に終了して再度開いてください。 +- **チャネルで応答がない:** デフォルトではメンションが必要です。`channels.msteams.requireMention=false` を設定するか、team/channel ごとに設定してください。 +- **バージョン不一致（Teams に古い manifest が表示される）:** アプリを削除して再追加し、更新のために Teams を完全に終了してください。 +- **webhook からの 401 Unauthorized:** Azure JWT なしで手動テストした場合は想定内です。エンドポイントには到達していますが認証に失敗しています。適切にテストするには Azure Web Chat を使用してください。 ### Manifest のアップロードエラー -- **「Icon file cannot be empty」:** manifest が 0 バイトのアイコンファイルを参照しています。有効な PNG アイコンを作成してください（`outline.png` は 32x32、`color.png` は 192x192）。 +- **「Icon file cannot be empty」:** manifest が参照しているアイコンファイルが 0 バイトです。有効な PNG アイコンを作成してください（`outline.png` は 32x32、`color.png` は 192x192）。 - **「webApplicationInfo.Id already in use」:** アプリが別の team/chat にまだインストールされています。先に見つけてアンインストールするか、反映まで 5〜10 分待ってください。 -- **アップロード時に「Something went wrong」:** 代わりに [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) 経由でアップロードし、ブラウザ DevTools（F12）→ Network タブを開いて、レスポンス本文の実際のエラーを確認してください。 -- **サイドロードに失敗する:** 「Upload a custom app」ではなく、「Upload an app to your org's app catalog」を試してください。こちらの方が sideload 制限を回避できることがよくあります。 +- **アップロード時の「Something went wrong」:** 代わりに [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) 経由でアップロードし、ブラウザの DevTools（F12）→ Network タブを開いて、実際のエラーについてレスポンス本文を確認してください。 +- **サイドロードに失敗する:** 「Upload a custom app」の代わりに「Upload an app to your org's app catalog」を試してください。これにより sideload 制限を回避できることがよくあります。 ### RSC 権限が動作しない -1. `webApplicationInfo.id` がボットの App ID と完全一致していることを確認します +1. `webApplicationInfo.id` がボットの App ID と完全に一致していることを確認します 2. アプリを再アップロードし、team/chat に再インストールします -3. 組織管理者が RSC 権限をブロックしていないか確認します -4. 正しいスコープを使っていることを確認します: teams には `ChannelMessage.Read.Group`、グループチャットには `ChatMessage.Read.Chat` +3. 組織の管理者が RSC 権限をブロックしていないか確認します +4. 正しいスコープを使用していることを確認します: teams には `ChannelMessage.Read.Group`、グループチャットには `ChatMessage.Read.Chat` ## 参考資料 @@ -800,13 +954,13 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr - [Teams app manifest schema](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) - [Receive channel messages with RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc) - [RSC permissions reference](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent) -- [Teams bot file handling](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4)（チャネル/グループでは Graph が必要） +- [Teams bot file handling](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4)（channel/group には Graph が必要） - [Proactive messaging](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages) ## 関連 -- [チャネル概要](/channels) — サポートされているすべてのチャネル -- [ペアリング](/channels/pairing) — DM 認証とペアリングフロー -- [グループ](/channels/groups) — グループチャットの動作とメンションゲート -- [チャネルルーティング](/channels/channel-routing) — メッセージのセッションルーティング -- [セキュリティ](/gateway/security) — アクセスモデルとハードニング +- [チャネル概要](/ja-JP/channels) — サポートされているすべてのチャネル +- [ペアリング](/ja-JP/channels/pairing) — DM 認証とペアリングフロー +- [グループ](/ja-JP/channels/groups) — グループチャット動作とメンション制御 +- [チャネルルーティング](/ja-JP/channels/channel-routing) — メッセージのセッションルーティング +- [セキュリティ](/ja-JP/gateway/security) — アクセスモデルとハードニング diff --git a/docs/ja-JP/plugins/sdk-agent-harness.md b/docs/ja-JP/plugins/sdk-agent-harness.md index bd4a8eefd..b3c034954 100644 --- a/docs/ja-JP/plugins/sdk-agent-harness.md +++ b/docs/ja-JP/plugins/sdk-agent-harness.md @@ -1,51 +1,51 @@ --- read_when: - - 埋め込みエージェントランタイムまたはハーネスレジストリを変更しています - - バンドル版または信頼済みプラグインからエージェントハーネスを登録しています - - Codexプラグインがモデルプロバイダーとどのように関係するかを理解する必要があります + - 組み込みエージェントランタイムまたはハーネスレジストリを変更しています + - バンドル済みまたは信頼されたプラグインからエージェントハーネスを登録しています + - Codexプラグインがモデルプロバイダーとどのように関係しているかを理解する必要があります sidebarTitle: Agent Harness -summary: 低レベルの埋め込みエージェント実行子を置き換えるプラグイン向けの実験的SDKサーフェス +summary: 低レベルの組み込みエージェント実行器を置き換えるプラグイン向けの実験的なSDKサーフェス title: エージェントハーネスプラグイン x-i18n: - generated_at: "2026-04-11T02:46:40Z" + generated_at: "2026-04-12T00:18:54Z" model: gpt-5.4 provider: openai - source_hash: 43c1f2c087230398b0162ed98449f239c8db1e822e51c7dcd40c54fa6c3374e1 + source_hash: 62b88fd24ce8b600179db27e16e8d764a2cd7a14e5c5df76374c33121aa5e365 source_path: plugins/sdk-agent-harness.md workflow: 15 --- # エージェントハーネスプラグイン -**エージェントハーネス**は、準備済みのOpenClawエージェントターン1回分に対する低レベル実行子です。これはモデルプロバイダーでも、チャネルでも、ツールレジストリでもありません。 +**エージェントハーネス**は、準備済みのOpenClawエージェントの1ターンを実行する低レベル実行器です。これはモデルプロバイダーでも、チャネルでも、ツールレジストリでもありません。 -このサーフェスは、バンドル版または信頼済みのネイティブプラグインでのみ使用してください。パラメーター型が意図的に現在の埋め込みランナーを反映しているため、この契約はまだ実験的です。 +このサーフェスは、バンドル済みまたは信頼されたネイティブプラグインにのみ使用してください。パラメーター型が意図的に現在の組み込みランナーを反映しているため、この契約はまだ実験的です。 -## ハーネスを使うべき場合 +## ハーネスを使用する場合 -モデルファミリーが独自のネイティブセッションランタイムを持ち、通常のOpenClawプロバイダートランスポートでは抽象化として不適切な場合に、エージェントハーネスを登録します。 +モデルファミリーが独自のネイティブセッションランタイムを持ち、通常のOpenClawプロバイダー転送が不適切な抽象化である場合は、エージェントハーネスを登録します。 例: - スレッドとコンパクションを管理するネイティブのコーディングエージェントサーバー -- ネイティブのプラン/reasoning/ツールイベントをストリーミングしなければならないローカルCLIまたはデーモン -- OpenClawセッションの文字起こしに加えて独自の再開IDを必要とするモデルランタイム +- ネイティブのプランニング/推論/ツールイベントをストリーミングする必要があるローカルCLIまたはデーモン +- OpenClawセッショントランスクリプトに加えて独自の再開IDが必要なモデルランタイム -新しいLLM APIを追加するだけの目的でハーネスを登録してはいけません。通常のHTTPまたはWebSocketモデルAPIであれば、[provider plugin](/ja-JP/plugins/sdk-provider-plugins)を構築してください。 +新しいLLM APIを追加するためだけにハーネスを登録しないでください。通常のHTTPまたはWebSocketモデルAPIでは、[プロバイダープラグイン](/ja-JP/plugins/sdk-provider-plugins)を構築してください。 -## コアが引き続き所有するもの +## コアが引き続き管理するもの -ハーネスが選択される前に、OpenClawはすでに以下を解決しています: +ハーネスが選択される前に、OpenClawはすでに次を解決しています。 - プロバイダーとモデル - ランタイム認証状態 -- thinkingレベルとコンテキスト予算 -- OpenClawの文字起こし/セッションファイル +- 思考レベルとコンテキスト予算 +- OpenClawトランスクリプト/セッションファイル - ワークスペース、サンドボックス、ツールポリシー - チャネル返信コールバックとストリーミングコールバック - モデルフォールバックとライブモデル切り替えポリシー -この分割は意図的なものです。ハーネスは準備済みの試行を実行しますが、プロバイダーを選択したり、チャネル配信を置き換えたり、黙ってモデルを切り替えたりはしません。 +この分離は意図的なものです。ハーネスは準備済みの試行を実行するものであり、プロバイダーを選択したり、チャネル配信を置き換えたり、モデルを黙って切り替えたりするものではありません。 ## ハーネスを登録する @@ -66,9 +66,9 @@ const myHarness: AgentHarness = { }, async runAttempt(params) { - // ネイティブスレッドを開始または再開します。 - // params.prompt、params.tools、params.images、params.onPartialReply、 - // params.onAgentEvent、およびその他の準備済み試行フィールドを使用します。 + // Start or resume your native thread. + // Use params.prompt, params.tools, params.images, params.onPartialReply, + // params.onAgentEvent, and the other prepared attempt fields. return await runMyNativeTurn(params); }, }; @@ -85,61 +85,51 @@ export default definePluginEntry({ ## 選択ポリシー -OpenClawは、プロバイダー/モデル解決後にハーネスを選択します: +OpenClawは、プロバイダー/モデルの解決後にハーネスを選択します。 -1. `OPENCLAW_AGENT_RUNTIME=`は、そのIDを持つ登録済みハーネスを強制します。 -2. `OPENCLAW_AGENT_RUNTIME=pi`は、組み込みPIハーネスを強制します。 -3. `OPENCLAW_AGENT_RUNTIME=auto`は、登録済みハーネスに、解決済みのプロバイダー/モデルをサポートしているか問い合わせます。 -4. 一致する登録済みハーネスがない場合、PIフォールバックが無効でなければOpenClawはPIを使用します。 +1. `OPENCLAW_AGENT_RUNTIME=` は、そのIDを持つ登録済みハーネスを強制します。 +2. `OPENCLAW_AGENT_RUNTIME=pi` は、組み込みのPIハーネスを強制します。 +3. `OPENCLAW_AGENT_RUNTIME=auto` は、解決済みのプロバイダー/モデルをサポートするかどうかを登録済みハーネスに問い合わせます。 +4. 一致する登録済みハーネスがない場合、PIフォールバックが無効でない限り、OpenClawはPIを使用します。 -強制されたプラグインハーネスの失敗は、実行失敗として表面化します。`auto`モードでは、 -選択されたプラグインハーネスがターンの副作用を生成する前に失敗した場合、 -OpenClawはPIにフォールバックすることがあります。代わりにそのフォールバックを確定的な失敗にしたい場合は、`OPENCLAW_AGENT_HARNESS_FALLBACK=none`または -`embeddedHarness.fallback: "none"`を設定してください。 +強制されたプラグインハーネスの失敗は、実行失敗として表面化します。`auto` モードでは、選択されたプラグインハーネスがターンの副作用を生成する前に失敗した場合、OpenClawはPIにフォールバックすることがあります。その代わりにそのフォールバックをハード失敗にするには、`OPENCLAW_AGENT_HARNESS_FALLBACK=none` または `embeddedHarness.fallback: "none"` を設定してください。 -バンドル版Codexプラグインは、ハーネスIDとして`codex`を登録します。コアはこれを -通常のプラグインハーネスIDとして扱います。Codex固有のエイリアスは共有ランタイムセレクターではなく、 -プラグインまたはオペレーター設定に属します。 +バンドル済みのCodexプラグインは、ハーネスIDとして `codex` を登録します。コアはこれを通常のプラグインハーネスIDとして扱います。Codex固有のエイリアスは、共有ランタイムセレクターではなく、プラグインまたはオペレーター設定に属します。 -## プロバイダーとハーネスの組み合わせ +## プロバイダーとハーネスのペアリング -ほとんどのハーネスは、プロバイダーもあわせて登録するべきです。プロバイダーは、 -モデル参照、認証状態、モデルメタデータ、および`/model`選択をOpenClawの他の部分から見えるようにします。 -その後、ハーネスは`supports(...)`内でそのプロバイダーを要求します。 +ほとんどのハーネスは、プロバイダーも登録するべきです。プロバイダーにより、モデル参照、認証状態、モデルメタデータ、`/model` 選択がOpenClawの他の部分から見えるようになります。その後、ハーネスは `supports(...)` でそのプロバイダーを要求します。 -バンドル版Codexプラグインはこのパターンに従っています: +バンドル済みのCodexプラグインは、このパターンに従います。 - プロバイダーID: `codex` -- ユーザーモデル参照: `codex/gpt-5.4`、`codex/gpt-5.2`、またはCodexアプリサーバーが返すその他のモデル +- ユーザーモデル参照: `codex/gpt-5.4`、`codex/gpt-5.2`、またはCodexアプリサーバーが返す別のモデル - ハーネスID: `codex` -- 認証: 合成プロバイダー可用性。CodexハーネスがネイティブのCodexログイン/セッションを所有するため -- アプリサーバーリクエスト: OpenClawは生のモデルIDをCodexに送信し、 - ハーネスがネイティブのアプリサーバープロトコルと通信します +- 認証: 合成プロバイダー可用性。CodexハーネスがネイティブのCodexログイン/セッションを管理するため +- アプリサーバーリクエスト: OpenClawは生のモデルIDをCodexに送信し、ハーネスがネイティブのアプリサーバープロトコルと通信します -Codexプラグインは追加的なものです。通常の`openai/gpt-*`参照は引き続きOpenAIプロバイダー参照であり、 -通常のOpenClawプロバイダー経路を使用し続けます。Codex管理の認証、 -Codexモデル検出、ネイティブスレッド、およびCodexアプリサーバー実行が必要な場合は`codex/gpt-*` -を選択してください。`/model`は、OpenAIプロバイダー資格情報を必要とせずに、 -Codexアプリサーバーが返すCodexモデル間を切り替えられます。 +Codexプラグインは追加的なものです。通常の `openai/gpt-*` 参照は引き続きOpenAIプロバイダー参照のままで、通常のOpenClawプロバイダーパスを使用し続けます。`codex/gpt-*` は、Codex管理の認証、Codexモデル検出、ネイティブスレッド、Codexアプリサーバー実行が必要な場合に選択してください。`/model` は、OpenAIプロバイダー資格情報を必要とせずに、Codexアプリサーバーが返すCodexモデル間を切り替えられます。 -オペレーター設定、モデルプレフィックス例、Codex専用設定については、 -[Codex Harness](/ja-JP/plugins/codex-harness)を参照してください。 +オペレーター設定、モデル接頭辞の例、Codex専用設定については、[Codexハーネス](/ja-JP/plugins/codex-harness)を参照してください。 -OpenClawはCodexアプリサーバー`0.118.0`以降を必要とします。Codexプラグインは -アプリサーバーの初期化ハンドシェイクを確認し、古いまたはバージョン未設定のサーバーをブロックすることで、 -OpenClawがテスト済みのプロトコルサーフェスに対してのみ実行されるようにします。 +OpenClawは、Codexアプリサーバー `0.118.0` 以降を必要とします。Codexプラグインはアプリサーバーの初期化ハンドシェイクを確認し、古いサーバーまたはバージョンなしのサーバーをブロックすることで、OpenClawがテスト済みのプロトコルサーフェスに対してのみ実行されるようにします。 + +### ネイティブCodexハーネスモード + +バンドル済みの `codex` ハーネスは、組み込みOpenClawエージェントターン向けのネイティブCodexモードです。最初にバンドル済みの `codex` プラグインを有効にし、設定で制限付きallowlistを使用している場合は `plugins.allow` に `codex` を含めてください。これは `openai-codex/*` とは異なります。 + +- `openai-codex/*` は、通常のOpenClawプロバイダーパスを通じてChatGPT/Codex OAuthを使用します。 +- `codex/*` は、バンドル済みのCodexプロバイダーを使用し、ターンをCodexアプリサーバー経由でルーティングします。 + +このモードが実行されると、CodexがネイティブスレッドID、再開動作、コンパクション、アプリサーバー実行を管理します。OpenClawは引き続き、チャットチャネル、表示用トランスクリプトミラー、ツールポリシー、承認、メディア配信、セッション選択を管理します。Codexアプリサーバーパスが使用されており、PIフォールバックが壊れたネイティブハーネスを隠していないことを証明する必要がある場合は、`embeddedHarness.runtime: "codex"` と `embeddedHarness.fallback: "none"` を使用してください。 ## PIフォールバックを無効にする -デフォルトでは、OpenClawは埋め込みエージェントを`agents.defaults.embeddedHarness` -が`{ runtime: "auto", fallback: "pi" }`に設定された状態で実行します。`auto`モードでは、登録済みプラグイン -ハーネスがプロバイダー/モデルの組み合わせを要求できます。一致するものがない場合、または自動選択された -プラグインハーネスが出力生成前に失敗した場合、OpenClawはPIにフォールバックします。 +デフォルトでは、OpenClawは組み込みエージェントを `agents.defaults.embeddedHarness` を `{ runtime: "auto", fallback: "pi" }` に設定して実行します。`auto` モードでは、登録済みプラグインハーネスがプロバイダー/モデルの組み合わせを要求できます。一致するものがない場合、または自動選択されたプラグインハーネスが出力を生成する前に失敗した場合、OpenClawはPIにフォールバックします。 -プラグインハーネスだけが実際に使用されていることを証明する必要がある場合は、`fallback: "none"`を設定してください。これにより自動PIフォールバックは無効になりますが、 -明示的な`runtime: "pi"`や`OPENCLAW_AGENT_RUNTIME=pi`はブロックされません。 +プラグインハーネスだけが実行されていることを証明する必要がある場合は、`fallback: "none"` を設定してください。これにより自動PIフォールバックは無効になりますが、明示的な `runtime: "pi"` または `OPENCLAW_AGENT_RUNTIME=pi` は妨げられません。 -Codex専用の埋め込み実行の場合: +Codex専用の組み込み実行の場合: ```json { @@ -155,8 +145,7 @@ Codex専用の埋め込み実行の場合: } ``` -一致するモデルを任意の登録済みプラグインハーネスに要求させつつ、OpenClawが黙ってPIにフォールバックすることは避けたい場合は、 -`runtime: "auto"`のままにしてフォールバックを無効にしてください: +登録済みの任意のプラグインハーネスが一致するモデルを要求できるようにしつつ、OpenClawがPIに黙ってフォールバックすることは望まない場合は、`runtime: "auto"` のままにしてフォールバックを無効にしてください。 ```json { @@ -171,7 +160,7 @@ Codex専用の埋め込み実行の場合: } ``` -エージェント単位の上書きも同じ形を使います: +エージェントごとのオーバーライドでも同じ形を使用します。 ```json { @@ -196,8 +185,7 @@ Codex専用の埋め込み実行の場合: } ``` -`OPENCLAW_AGENT_RUNTIME`は引き続き設定済みランタイムを上書きします。環境から -PIフォールバックを無効にするには`OPENCLAW_AGENT_HARNESS_FALLBACK=none`を使用してください。 +`OPENCLAW_AGENT_RUNTIME` は、引き続き設定されたランタイムを上書きします。環境からPIフォールバックを無効にするには、`OPENCLAW_AGENT_HARNESS_FALLBACK=none` を使用してください。 ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -205,53 +193,39 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -フォールバックを無効にすると、要求されたハーネスが -登録されていない、解決済みのプロバイダー/モデルをサポートしていない、または -ターンの副作用を生成する前に失敗した場合、セッションは早い段階で失敗します。これは -Codex専用デプロイや、Codexアプリサーバー経路が実際に使われていることを証明しなければならない -ライブテストでは意図された動作です。 +フォールバックを無効にすると、要求されたハーネスが登録されていない、解決済みのプロバイダー/モデルをサポートしていない、またはターンの副作用を生成する前に失敗した場合、セッションは早い段階で失敗します。これは、Codex専用デプロイメントや、Codexアプリサーバーパスが実際に使用されていることを証明しなければならないライブテストでは意図された動作です。 -この設定が制御するのは埋め込みエージェントハーネスだけです。画像、 -動画、音楽、TTS、PDF、その他のプロバイダー固有のモデルルーティングは無効化されません。 +この設定は、組み込みエージェントハーネスのみを制御します。画像、動画、音楽、TTS、PDF、その他のプロバイダー固有のモデルルーティングは無効にしません。 -## ネイティブセッションと文字起こしミラー +## ネイティブセッションとトランスクリプトミラー -ハーネスは、ネイティブセッションID、スレッドID、またはデーモン側の再開トークンを保持する場合があります。 -その対応付けはOpenClawセッションに明示的に関連付けたままにし、 -ユーザーに見えるassistant/tool出力をOpenClawの文字起こしへミラーし続けてください。 +ハーネスは、ネイティブセッションID、スレッドID、またはデーモン側の再開トークンを保持する場合があります。その関連付けはOpenClawセッションに明示的に結び付けたままにし、ユーザーに表示されるアシスタント/ツール出力を引き続きOpenClawトランスクリプトへミラーリングしてください。 -OpenClawの文字起こしは、以下の互換レイヤーのままです: +OpenClawトランスクリプトは、引き続き次の互換レイヤーです。 -- チャネルから見えるセッション履歴 -- 文字起こし検索とインデックス作成 -- 後続ターンで組み込みPIハーネスに戻すこと -- 汎用の`/new`、`/reset`、およびセッション削除動作 +- チャネルに表示されるセッション履歴 +- トランスクリプト検索とインデックス作成 +- 後のターンで組み込みPIハーネスに戻すこと +- 汎用的な `/new`、`/reset`、およびセッション削除の動作 -ハーネスがサイドカーの対応情報を保存する場合は、所有するOpenClawセッションがリセットされたときに -OpenClawがそれをクリアできるよう、`reset(...)`を実装してください。 +ハーネスがサイドカーの関連付けを保存する場合は、所有するOpenClawセッションがリセットされたときにOpenClawがそれを消去できるよう、`reset(...)` を実装してください。 -## ツールおよびメディア結果 +## ツールとメディアの結果 -コアはOpenClawのツール一覧を構築し、それを準備済み試行に渡します。 -ハーネスが動的ツール呼び出しを実行する場合は、チャネルメディアを自分で送信するのではなく、 -ハーネス結果の形を通じてツール結果を返してください。 +コアはOpenClawツールリストを構築し、それを準備済みの試行に渡します。ハーネスが動的ツール呼び出しを実行する場合、チャネルメディアを自分で送信するのではなく、ハーネス結果の形を通してツール結果を返してください。 -これにより、テキスト、画像、動画、音楽、TTS、承認、メッセージングツール出力が、 -PIベース実行と同じ配信経路に保たれます。 +これにより、テキスト、画像、動画、音楽、TTS、承認、メッセージングツールの出力が、PIベースの実行と同じ配信パスに保たれます。 ## 現在の制限 -- 公開インポートパスは汎用ですが、一部の試行/結果型エイリアスには互換性のためにまだ - `Pi`名が残っています。 -- サードパーティ製ハーネスのインストールは実験的です。ネイティブセッションランタイムが必要になるまでは - provider pluginを優先してください。 -- ターンをまたいだハーネス切り替えはサポートされています。ネイティブツール、承認、assistantテキスト、またはメッセージ送信が始まった後、 - ターンの途中でハーネスを切り替えないでください。 +- 公開インポートパスは汎用ですが、互換性のために一部の試行/結果型エイリアスにはまだ `Pi` という名前が残っています。 +- サードパーティ製ハーネスのインストールは実験的です。ネイティブセッションランタイムが必要になるまでは、プロバイダープラグインを優先してください。 +- ターン間でのハーネス切り替えはサポートされています。ネイティブツール、承認、アシスタントテキスト、またはメッセージ送信が始まった後に、ターンの途中でハーネスを切り替えないでください。 ## 関連 -- [SDK Overview](/ja-JP/plugins/sdk-overview) -- [Runtime Helpers](/ja-JP/plugins/sdk-runtime) -- [Provider Plugins](/ja-JP/plugins/sdk-provider-plugins) -- [Codex Harness](/ja-JP/plugins/codex-harness) -- [Model Providers](/ja-JP/concepts/model-providers) +- [SDK概要](/ja-JP/plugins/sdk-overview) +- [ランタイムヘルパー](/ja-JP/plugins/sdk-runtime) +- [プロバイダープラグイン](/ja-JP/plugins/sdk-provider-plugins) +- [Codexハーネス](/ja-JP/plugins/codex-harness) +- [モデルプロバイダー](/ja-JP/concepts/model-providers) diff --git a/docs/ja-JP/providers/openai.md b/docs/ja-JP/providers/openai.md index 979f03fc3..9f98647e0 100644 --- a/docs/ja-JP/providers/openai.md +++ b/docs/ja-JP/providers/openai.md @@ -1,50 +1,49 @@ --- read_when: - - OpenClawでOpenAI modelsを使いたいとき - - API keyの代わりにCodexサブスクリプション認証を使いたいとき -summary: OpenClawでAPI keyまたはCodexサブスクリプション経由でOpenAIを使う + - OpenClaw で OpenAI モデルを使いたい場合 + - API キーではなく Codex サブスクリプション認証を使いたい場合 + - GPT-5 エージェントの実行動作をより厳格にする必要がある場合 +summary: OpenClaw で API キーまたは Codex サブスクリプションを使って OpenAI を利用する title: OpenAI x-i18n: - generated_at: "2026-04-07T04:46:34Z" + generated_at: "2026-04-12T00:18:58Z" model: gpt-5.4 provider: openai - source_hash: 6a2ce1ce5f085fe55ec50b8d20359180b9002c9730820cd5b0e011c3bf807b64 + source_hash: 7aa06fba9ac901e663685a6b26443a2f6aeb6ec3589d939522dc87cbb43497b4 source_path: providers/openai.md workflow: 15 --- # OpenAI -OpenAIはGPT models向けの開発者APIを提供しています。Codexは、サブスクリプションアクセス用の**ChatGPT sign-in** または従量課金アクセス用の**API key** sign-inをサポートします。Codex cloudではChatGPT sign-inが必要です。 -OpenAIは、OpenClawのような外部ツールやワークフローでのサブスクリプションOAuth利用を明示的にサポートしています。 +OpenAI は GPT モデル向けの開発者 API を提供しています。Codex は、サブスクリプションアクセス用の **ChatGPT サインイン** と、従量課金アクセス用の **API キー** サインインをサポートしています。Codex cloud では ChatGPT サインインが必要です。 +OpenAI は、OpenClaw のような外部ツールやワークフローでのサブスクリプション OAuth 利用を明示的にサポートしています。 ## デフォルトの対話スタイル -OpenClawは、`openai/*` と -`openai-codex/*` の両方の実行に対して、小さなOpenAI固有のprompt overlayを追加できます。デフォルトでは、このoverlayはassistantを温かく、 -協調的で、簡潔、直接的、かつ少し感情表現豊かに保ちつつ、 -ベースのOpenClaw system promptは置き換えません。friendly overlayはまた、 -全体の出力を簡潔に保ちながら、自然に合う場面ではたまにemojiを使うことも -許可します。 +OpenClaw は、`openai/*` と +`openai-codex/*` の両方の実行に対して、小さな OpenAI 固有のプロンプトオーバーレイを追加できます。デフォルトでは、このオーバーレイにより、ベースとなる OpenClaw システムプロンプトを置き換えることなく、アシスタントを親しみやすく、 +協調的で、簡潔かつ直接的、そして少しだけ感情表現豊かに保ちます。フレンドリーなオーバーレイでは、 +全体の出力を簡潔に保ちながら、自然に合う場合に限って時折絵文字を使うことも許可されます。 設定キー: `plugins.entries.openai.config.personality` -許可される値: +使用可能な値: -- `"friendly"`: デフォルト。OpenAI固有overlayを有効にします。 -- `"on"`: `"friendly"` の別名。 -- `"off"`: overlayを無効にし、ベースのOpenClaw promptのみを使用します。 +- `"friendly"`: デフォルト。OpenAI 固有のオーバーレイを有効にします。 +- `"on"`: `"friendly"` のエイリアス。 +- `"off"`: オーバーレイを無効にし、ベースの OpenClaw プロンプトのみを使用します。 適用範囲: -- `openai/*` modelsに適用されます。 -- `openai-codex/*` modelsに適用されます。 -- 他のproviderには影響しません。 +- `openai/*` モデルに適用されます。 +- `openai-codex/*` モデルに適用されます。 +- 他のプロバイダーには影響しません。 -この動作はデフォルトで有効です。将来のローカルconfig変更でもこれを -維持したい場合は、明示的に `"friendly"` を残してください: +この動作はデフォルトで有効です。今後ローカル設定が変動しても `"friendly"` を維持したい場合は、 +明示的に指定したままにしてください: ```json5 { @@ -60,9 +59,9 @@ OpenClawは、`openai/*` と } ``` -### OpenAI prompt overlayを無効にする +### OpenAI プロンプトオーバーレイを無効にする -未変更のベースOpenClaw promptを使いたい場合は、overlayを `"off"` に設定します: +変更されていないベースの OpenClaw プロンプトを使いたい場合は、オーバーレイを `"off"` に設定します: ```json5 { @@ -78,31 +77,31 @@ OpenClawは、`openai/*` と } ``` -config CLIから直接設定することもできます: +設定 CLI から直接指定することもできます: ```bash openclaw config set plugins.entries.openai.config.personality off ``` -OpenClawはこの設定を実行時に大文字小文字を区別せず正規化するため、 -`"Off"` のような値でもfriendly overlayは無効になります。 +OpenClaw は実行時にこの設定を大文字小文字を区別せず正規化するため、 +`"Off"` のような値でもフレンドリーなオーバーレイは無効になります。 -## Option A: OpenAI API key（OpenAI Platform） +## オプション A: OpenAI API キー (OpenAI Platform) -**最適な用途:** 直接APIアクセスと従量課金。 -API keyはOpenAI dashboardから取得してください。 +**最適な用途:** 直接 API アクセスと従量課金。 +API キーは OpenAI ダッシュボードから取得してください。 ルート概要: -- `openai/gpt-5.4` = 直接のOpenAI Platform APIルート -- `OPENAI_API_KEY`（または同等のOpenAI provider設定）が必要 -- OpenClawでは、ChatGPT/Codex sign-inは `openai/*` ではなく `openai-codex/*` 経由になります +- `openai/gpt-5.4` = 直接 OpenAI Platform API ルート +- `OPENAI_API_KEY`（または同等の OpenAI プロバイダー設定）が必要 +- OpenClaw では、ChatGPT/Codex サインインは `openai/*` ではなく `openai-codex/*` を通してルーティングされます -### CLIセットアップ +### CLI セットアップ ```bash openclaw onboard --auth-choice openai-api-key -# または非対話 +# または非対話モード openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` @@ -115,28 +114,28 @@ openclaw onboard --openai-api-key "$OPENAI_API_KEY" } ``` -OpenAIの現在のAPI modelドキュメントでは、直接の -OpenAI API利用向けに `gpt-5.4` と `gpt-5.4-pro` が挙げられています。OpenClawはその両方を `openai/*` Responsesパス経由で転送します。 -OpenClawは、古い `openai/gpt-5.3-codex-spark` 行を意図的に非表示にしています。 -これは、直接のOpenAI API呼び出しではlive trafficで拒否されるためです。 +OpenAI の現在の API モデルドキュメントでは、直接の +OpenAI API 利用向けに `gpt-5.4` と `gpt-5.4-pro` が掲載されています。OpenClaw はその両方を `openai/*` Responses パス経由で転送します。 +OpenClaw は、古い `openai/gpt-5.3-codex-spark` 行を意図的に表示しません。 +これは、実際のトラフィックでは直接 OpenAI API 呼び出しで拒否されるためです。 -OpenClawは、直接のOpenAI -APIパス上で `openai/gpt-5.3-codex-spark` を公開しません。`pi-ai` には引き続きそのmodelの組み込み行がありますが、live OpenAI API -リクエストは現在それを拒否します。OpenClawではSparkはCodex専用として扱われます。 +OpenClaw は、直接 OpenAI +API パスでは `openai/gpt-5.3-codex-spark` を公開しません。`pi-ai` はこのモデルの組み込み行を引き続き同梱していますが、実際の OpenAI API +リクエストでは現在拒否されます。OpenClaw では Spark は Codex 専用として扱われます。 ## 画像生成 -バンドルされた `openai` pluginは、共有 -`image_generate` tool経由の画像生成も登録します。 +同梱の `openai` プラグインは、共有の +`image_generate` ツールを通じて画像生成も登録します。 -- デフォルト画像model: `openai/gpt-image-1` -- Generate: 1リクエストあたり最大4画像 -- Edit mode: 有効、最大5枚の参照画像 +- デフォルト画像モデル: `openai/gpt-image-1` +- 生成: 1 リクエストあたり最大 4 枚の画像 +- 編集モード: 有効、最大 5 枚の参照画像 - `size` をサポート -- 現在のOpenAI固有の注意点: OpenClawは現在 `aspectRatio` または - `resolution` の上書きをOpenAI Images APIへ転送しません +- 現在の OpenAI 固有の注意点: OpenClaw は現時点で `aspectRatio` または + `resolution` の上書きを OpenAI Images API に転送しません -OpenAIをデフォルトの画像providerとして使うには: +OpenAI をデフォルトの画像プロバイダーとして使うには: ```json5 { @@ -150,22 +149,22 @@ OpenAIをデフォルトの画像providerとして使うには: } ``` -共有toolの -パラメータ、provider選択、フェイルオーバー動作については [Image Generation](/ja-JP/tools/image-generation) を参照してください。 +共有ツールの +パラメーター、プロバイダー選択、フェイルオーバー動作については、[画像生成](/ja-JP/tools/image-generation) を参照してください。 ## 動画生成 -バンドルされた `openai` pluginは、共有 -`video_generate` tool経由の動画生成も登録します。 +同梱の `openai` プラグインは、共有の +`video_generate` ツールを通じて動画生成も登録します。 -- デフォルト動画model: `openai/sora-2` -- モード: text-to-video、image-to-video、および単一動画の参照/編集フロー -- 現在の上限: 画像1枚または動画1本の参照入力 -- 現在のOpenAI固有の注意点: OpenClawは現在、ネイティブOpenAI動画生成に対して `size` - の上書きだけを転送します。`aspectRatio`、`resolution`、`audio`、`watermark` などの未対応の任意上書きは無視され、 - tool warningとして返されます。 +- デフォルト動画モデル: `openai/sora-2` +- モード: テキストから動画、画像から動画、単一動画の参照/編集フロー +- 現在の制限: 画像または動画の参照入力は 1 件のみ +- 現在の OpenAI 固有の注意点: OpenClaw は現在、ネイティブ OpenAI 動画生成では `size` + の上書きのみを転送します。`aspectRatio`、`resolution`、`audio`、`watermark` などの未対応のオプション上書きは無視され、 + ツール警告として報告されます。 -OpenAIをデフォルトの動画providerとして使うには: +OpenAI をデフォルトの動画プロバイダーとして使うには: ```json5 { @@ -179,31 +178,31 @@ OpenAIをデフォルトの動画providerとして使うには: } ``` -共有toolの -パラメータ、provider選択、フェイルオーバー動作については [Video Generation](/ja-JP/tools/video-generation) を参照してください。 +共有ツールの +パラメーター、プロバイダー選択、フェイルオーバー動作については、[動画生成](/ja-JP/tools/video-generation) を参照してください。 -## Option B: OpenAI Code（Codex）サブスクリプション +## オプション B: OpenAI Code (Codex) サブスクリプション -**最適な用途:** API keyの代わりにChatGPT/Codexサブスクリプションアクセスを使うこと。 -Codex cloudではChatGPT sign-inが必要であり、Codex CLIはChatGPTまたはAPI keyによるsign-inをサポートします。 +**最適な用途:** API キーの代わりに ChatGPT/Codex サブスクリプションアクセスを使うこと。 +Codex cloud では ChatGPT サインインが必要で、一方 Codex CLI では ChatGPT または API キーのサインインをサポートしています。 ルート概要: -- `openai-codex/gpt-5.4` = ChatGPT/Codex OAuthルート -- 直接のOpenAI Platform API keyではなく、ChatGPT/Codex sign-inを使用 -- `openai-codex/*` に対するprovider側の制限は、ChatGPT web/app体験とは異なる場合があります +- `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth ルート +- 直接の OpenAI Platform API キーではなく、ChatGPT/Codex サインインを使用 +- `openai-codex/*` のプロバイダー側の制限は、ChatGPT の Web/アプリ体験と異なる場合があります -### CLIセットアップ（Codex OAuth） +### CLI セットアップ (Codex OAuth) ```bash -# ウィザードでCodex OAuthを実行 +# ウィザードで Codex OAuth を実行 openclaw onboard --auth-choice openai-codex -# またはOAuthを直接実行 +# または OAuth を直接実行 openclaw models auth login --provider openai-codex ``` -### 設定スニペット（Codexサブスクリプション） +### 設定スニペット (Codex サブスクリプション) ```json5 { @@ -211,43 +210,42 @@ openclaw models auth login --provider openai-codex } ``` -OpenAIの現在のCodexドキュメントでは、現在のCodex modelとして `gpt-5.4` が挙げられています。OpenClawは -これを、ChatGPT/Codex OAuth利用向けに `openai-codex/gpt-5.4` へマップします。 +OpenAI の現在の Codex ドキュメントでは、現在の Codex モデルとして `gpt-5.4` が掲載されています。OpenClaw +では、ChatGPT/Codex OAuth 利用向けにこれを `openai-codex/gpt-5.4` にマッピングしています。 このルートは `openai/gpt-5.4` とは意図的に分離されています。直接の -OpenAI Platform APIパスを使いたい場合は、API key付きの `openai/*` を使ってください。ChatGPT/Codex sign-inを使いたい場合は、`openai-codex/*` を使ってください。 +OpenAI Platform API パスを使いたい場合は、API キー付きの `openai/*` を使用してください。ChatGPT/Codex サインインを使いたい場合は、 +`openai-codex/*` を使用してください。 -オンボーディングが既存のCodex CLIログインを再利用する場合、それらの認証情報は -引き続きCodex CLIによって管理されます。有効期限切れ時には、OpenClawはまず外部のCodexソースを再読み込みし、 -providerがそれを更新できる場合は、OpenClaw専用の別コピーとして所有権を持つのではなく、 -更新後の認証情報をCodexストレージへ書き戻します。 +オンボーディングで既存の Codex CLI ログインを再利用した場合、それらの認証情報は引き続き +Codex CLI によって管理されます。有効期限切れ時、OpenClaw はまず外部の Codex ソースを再読み込みし、プロバイダー側で更新可能な場合は、 +OpenClaw 専用の別コピーを所有するのではなく、更新された認証情報を Codex ストレージへ書き戻します。 -Codex Sparkを利用できるCodexアカウントなら、OpenClawは次もサポートします: +Codex アカウントに Codex Spark の利用権限がある場合、OpenClaw は以下もサポートします: - `openai-codex/gpt-5.3-codex-spark` -OpenClawはCodex SparkをCodex専用として扱います。直接の -`openai/gpt-5.3-codex-spark` API-keyパスは公開しません。 +OpenClaw は Codex Spark を Codex 専用として扱います。直接の +`openai/gpt-5.3-codex-spark` API キーパスは公開しません。 -OpenClawは、`pi-ai` -がそれを発見した場合にも `openai-codex/gpt-5.3-codex-spark` を保持します。これは権限依存かつ実験的なものとして扱ってください。Codex Sparkは -GPT-5.4 `/fast` とは別物であり、利用可否はサインインしているCodex / -ChatGPTアカウントに依存します。 +OpenClaw は、`pi-ai` +がそれを検出した場合に `openai-codex/gpt-5.3-codex-spark` も保持します。これは利用権限依存かつ実験的なものとして扱ってください。Codex Spark は +GPT-5.4 の `/fast` とは別物であり、利用可否はサインインしている Codex / +ChatGPT アカウントに依存します。 -### Codexコンテキストウィンドウ上限 +### Codex コンテキストウィンドウ上限 -OpenClawは、Codex model metadataと実行時コンテキスト上限を別の -値として扱います。 +OpenClaw は、Codex モデルのメタデータと実行時コンテキスト上限を別の値として扱います。 -`openai-codex/gpt-5.4` では: +`openai-codex/gpt-5.4` の場合: - ネイティブ `contextWindow`: `1050000` - デフォルトの実行時 `contextTokens` 上限: `272000` -これにより、model metadataの正確性を保ちつつ、実運用ではレイテンシと品質特性が -より良い、より小さなデフォルト実行時ウィンドウを維持します。 +これにより、実際にはレイテンシーと品質の特性がより良い、より小さなデフォルト実行時 +ウィンドウを維持しつつ、モデルメタデータの正確性も保たれます。 -別の実効上限を使いたい場合は、`models.providers..models[].contextTokens` を設定してください: +有効な上限を別の値にしたい場合は、`models.providers..models[].contextTokens` を設定してください: ```json5 { @@ -266,48 +264,42 @@ OpenClawは、Codex model metadataと実行時コンテキスト上限を別の } ``` -`contextWindow` は、ネイティブmodel -metadataを宣言または上書きするときにのみ使ってください。実行時コンテキスト予算を制限したい場合は `contextTokens` を使ってください。 +`contextWindow` は、ネイティブモデルの +メタデータを宣言または上書きするときにのみ使用してください。実行時コンテキスト予算を制限したい場合は `contextTokens` を使用してください。 -### デフォルトtransport +### デフォルトのトランスポート -OpenClawはmodel streamingに `pi-ai` を使用します。`openai/*` と -`openai-codex/*` の両方で、デフォルトtransportは `"auto"`（WebSocket優先、その後 -SSEフォールバック）です。 +OpenClaw はモデルストリーミングに `pi-ai` を使用します。`openai/*` と +`openai-codex/*` の両方で、デフォルトのトランスポートは `"auto"`（まず WebSocket、次に SSE へフォールバック）です。 -`"auto"` モードでは、OpenClawは初期の再試行可能なWebSocket失敗を1回だけ再試行してから -SSEにフォールバックします。強制 `"websocket"` モードでは、フォールバックの裏に隠さず -transport errorをそのまま表示します。 +`"auto"` モードでは、OpenClaw は SSE にフォールバックする前に、初期の再試行可能な WebSocket 障害も +1 回再試行します。強制 `"websocket"` モードでは、フォールバックの背後に隠すことなくトランスポートエラーをそのまま表示します。 -`"auto"` モードで接続時または初期ターンのWebSocket失敗が発生すると、OpenClawは -そのsessionのWebSocketパスを約60秒間degradedとしてマークし、 -そのcool-down中の後続ターンは、transport間を行き来させる代わりにSSEで送信します。 +`"auto"` モードで接続または初期ターンの WebSocket 障害が発生した後、OpenClaw は +そのセッションの WebSocket パスを約 60 秒間劣化状態としてマークし、 +トランスポート間を行き来し続けるのではなく、クールダウン中の後続ターンを SSE 経由で送信します。 -ネイティブOpenAI系endpoint（`openai/*`、`openai-codex/*`、およびAzure -OpenAI Responses）では、OpenClawはリクエストに安定したsessionおよびturn identity stateも付与するため、 -再試行、再接続、SSEフォールバックが同じ -conversation identityに揃ったまま維持されます。ネイティブOpenAI系ルートでは、これには安定した -session/turn request identity headerと、それに対応するtransport metadataが含まれます。 +ネイティブ OpenAI ファミリーのエンドポイント（`openai/*`、`openai-codex/*`、および Azure +OpenAI Responses）では、OpenClaw はリクエストに安定したセッション ID とターン ID の状態も付加するため、 +再試行、再接続、SSE フォールバック時にも同じ会話 ID に整合します。ネイティブ OpenAI ファミリーのルートでは、これには安定した +セッション/ターンのリクエスト ID ヘッダーと、それに一致するトランスポートメタデータが含まれます。 -OpenClawはまた、OpenAI usage counterをtransport variant間で正規化してから -session/status surfaceに渡します。ネイティブOpenAI/Codex Responsesトラフィックは -usageを `input_tokens` / `output_tokens` または -`prompt_tokens` / `completion_tokens` のいずれかで報告する場合がありますが、 -OpenClawはそれらを `/status`、`/usage`、session logs向けに同じ入力 -および出力counterとして扱います。ネイティブ -WebSocketトラフィックで `total_tokens` が欠落している（または `0` と報告される）場合、OpenClawは -正規化された入力 + 出力合計にフォールバックするため、session/status表示は値が入ったままになります。 +OpenClaw は、セッション/ステータス画面に到達する前に、トランスポートの違いをまたいで OpenAI の使用量カウンターも正規化します。ネイティブ OpenAI/Codex Responses トラフィックでは、使用量が `input_tokens` / `output_tokens` または +`prompt_tokens` / `completion_tokens` として報告される場合がありますが、 +OpenClaw は `/status`、`/usage`、およびセッションログ向けに、これらを同じ入力および出力カウンターとして扱います。ネイティブ +WebSocket トラフィックで `total_tokens` が省略される（または `0` が報告される）場合、 +OpenClaw はセッション/ステータス表示が埋まったままになるよう、正規化された入力 + 出力の合計にフォールバックします。 `agents.defaults.models..params.transport` を設定できます: -- `"sse"`: SSEを強制 -- `"websocket"`: WebSocketを強制 -- `"auto"`: WebSocketを試し、その後SSEにフォールバック +- `"sse"`: SSE を強制 +- `"websocket"`: WebSocket を強制 +- `"auto"`: WebSocket を試し、その後 SSE にフォールバック -`openai/*`（Responses API）については、OpenClawは -WebSocket transportが使われる場合に、デフォルトでWebSocket warm-upも有効にします（`openaiWsWarmup: true`）。 +`openai/*`（Responses API）では、WebSocket トランスポートが使われる場合、 +OpenClaw はデフォルトで WebSocket ウォームアップも有効にします（`openaiWsWarmup: true`）。 -関連するOpenAIドキュメント: +関連する OpenAI ドキュメント: - [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) - [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses) @@ -329,12 +321,13 @@ WebSocket transportが使われる場合に、デフォルトでWebSocket warm-u } ``` -### OpenAI WebSocket warm-up +### OpenAI WebSocket ウォームアップ -OpenAIのドキュメントではwarm-upは任意とされています。OpenClawでは、 -WebSocket transport使用時の初回ターンのレイテンシを下げるため、`openai/*` に対してデフォルトで有効にしています。 +OpenAI のドキュメントでは、ウォームアップはオプションとして説明されています。OpenClaw は、 +WebSocket トランスポート使用時の最初のターンのレイテンシーを減らすため、 +`openai/*` ではデフォルトでこれを有効にします。 -### warm-upを無効にする +### ウォームアップを無効にする ```json5 { @@ -352,7 +345,7 @@ WebSocket transport使用時の初回ターンのレイテンシを下げるた } ``` -### warm-upを明示的に有効にする +### ウォームアップを明示的に有効にする ```json5 { @@ -370,12 +363,11 @@ WebSocket transport使用時の初回ターンのレイテンシを下げるた } ``` -### OpenAIとCodexのpriority processing +### OpenAI と Codex の優先処理 -OpenAIのAPIは `service_tier=priority` によるpriority processingを公開しています。 -OpenClawでは、ネイティブOpenAI/Codex Responses endpointにそのフィールドを渡すために -`agents.defaults.models["/"].params.serviceTier` -を設定します。 +OpenAI の API は `service_tier=priority` による優先処理を公開しています。OpenClaw +では、ネイティブ OpenAI/Codex Responses エンドポイントにそのフィールドを渡すため、 +`agents.defaults.models["/"].params.serviceTier` を設定します。 ```json5 { @@ -398,38 +390,38 @@ OpenClawでは、ネイティブOpenAI/Codex Responses endpointにそのフィ } ``` -サポートされる値は `auto`、`default`、`flex`、`priority` です。 +サポートされる値は `auto`、`default`、`flex`、および `priority` です。 -OpenClawは、ネイティブOpenAI/Codex endpointを指している場合、 +OpenClaw は、これらのモデルがネイティブ OpenAI/Codex エンドポイントを指している場合、 `params.serviceTier` を直接の `openai/*` Responses -リクエストと `openai-codex/*` Codex Responsesリクエストの両方へ転送します。 +リクエストと `openai-codex/*` Codex Responses リクエストの両方に転送します。 重要な動作: - 直接の `openai/*` は `api.openai.com` を対象にしている必要があります - `openai-codex/*` は `chatgpt.com/backend-api` を対象にしている必要があります -- いずれかのproviderを別のbase URLまたはproxy経由にした場合、OpenClawは `service_tier` をそのままにします +- どちらかのプロバイダーを別のベース URL やプロキシ経由でルーティングしている場合、OpenClaw は `service_tier` を変更しません -### OpenAI fast mode +### OpenAI 高速モード -OpenClawは、`openai/*` と -`openai-codex/*` の両session向けに共有fast-modeトグルを公開しています: +OpenClaw は、`openai/*` と +`openai-codex/*` の両方のセッション向けに共有の高速モード切り替えを公開しています: - Chat/UI: `/fast status|on|off` -- Config: `agents.defaults.models["/"].params.fastMode` +- 設定: `agents.defaults.models["/"].params.fastMode` -fast modeが有効なとき、OpenClawはそれをOpenAI priority processingへマップします: +高速モードが有効な場合、OpenClaw はそれを OpenAI の優先処理にマッピングします: -- `api.openai.com` への直接の `openai/*` Responses呼び出しは `service_tier = "priority"` を送信します -- `chatgpt.com/backend-api` への `openai-codex/*` Responses呼び出しも `service_tier = "priority"` を送信します +- `api.openai.com` への直接の `openai/*` Responses 呼び出しは `service_tier = "priority"` を送信します +- `chatgpt.com/backend-api` への `openai-codex/*` Responses 呼び出しも `service_tier = "priority"` を送信します - 既存のペイロード `service_tier` 値は保持されます -- fast modeは `reasoning` や `text.verbosity` を書き換えません +- 高速モードは `reasoning` や `text.verbosity` を書き換えません -特にGPT 5.4では、最も一般的な設定は次のとおりです: +GPT 5.4 について特に一般的な設定は次のとおりです: -- `openai/gpt-5.4` または `openai-codex/gpt-5.4` を使っているsessionで `/fast on` を送る +- `openai/gpt-5.4` または `openai-codex/gpt-5.4` を使うセッションで `/fast on` を送信する - または `agents.defaults.models["openai/gpt-5.4"].params.fastMode = true` を設定する -- Codex OAuthも使うなら、`agents.defaults.models["openai-codex/gpt-5.4"].params.fastMode = true` も設定する +- Codex OAuth も使う場合は、`agents.defaults.models["openai-codex/gpt-5.4"].params.fastMode = true` も設定する 例: @@ -454,48 +446,73 @@ fast modeが有効なとき、OpenClawはそれをOpenAI priority processingへ } ``` -session overrideはconfigより優先されます。Sessions UIでsession overrideをクリアすると、 -そのsessionは設定済みデフォルトに戻ります。 +セッションの上書き設定は config より優先されます。Sessions UI でセッション上書きをクリアすると、 +そのセッションは設定済みのデフォルトに戻ります。 -### ネイティブOpenAIとOpenAI互換ルートの違い +### ネイティブ OpenAI と OpenAI 互換ルートの違い -OpenClawは、直接のOpenAI、Codex、およびAzure OpenAI endpointを、 -汎用的なOpenAI互換 `/v1` proxyとは異なるものとして扱います: +OpenClaw は、直接の OpenAI、Codex、および Azure OpenAI エンドポイントを、 +汎用的な OpenAI 互換 `/v1` プロキシとは異なる方法で扱います: -- ネイティブ `openai/*`、`openai-codex/*`、およびAzure OpenAIルートでは、 - reasoningを明示的に無効にした場合でも `reasoning: { effort: "none" }` をそのまま維持します -- ネイティブOpenAI系ルートではtool schemaがデフォルトでstrict modeになります -- 隠しOpenClaw attribution header（`originator`、`version`、および - `User-Agent`）は、検証済みのネイティブOpenAI host - （`api.openai.com`）とネイティブCodex host（`chatgpt.com/backend-api`）でのみ付与されます -- ネイティブOpenAI/Codexルートでは、 - `service_tier`、Responses `store`、OpenAI reasoning互換ペイロード、 - prompt-cache hintのようなOpenAI専用request shapingを維持します -- proxy形式のOpenAI互換ルートでは、より緩い互換動作を維持し、 - strictなtool schema、ネイティブ専用request shaping、隠し - OpenAI/Codex attribution headerは強制しません +- ネイティブ `openai/*`、`openai-codex/*`、および Azure OpenAI ルートでは、 + 推論を明示的に無効にしたとき `reasoning: { effort: "none" }` をそのまま維持します +- ネイティブ OpenAI ファミリールートでは、ツールスキーマのデフォルトが strict mode になります +- 非表示の OpenClaw 帰属ヘッダー（`originator`、`version`、および + `User-Agent`）は、検証済みのネイティブ OpenAI ホスト + （`api.openai.com`）およびネイティブ Codex ホスト（`chatgpt.com/backend-api`）にのみ付与されます +- ネイティブ OpenAI/Codex ルートでは、`service_tier`、Responses の `store`、OpenAI の reasoning 互換ペイロード、および + プロンプトキャッシュヒントのような OpenAI 専用のリクエスト整形を維持します +- プロキシ形式の OpenAI 互換ルートでは、より緩い互換動作を維持し、 + strict なツールスキーマ、ネイティブ専用のリクエスト整形、または非表示の + OpenAI/Codex 帰属ヘッダーを強制しません -Azure OpenAIはtransportと互換動作の点ではネイティブルーティング側に残りますが、 -隠しOpenAI/Codex attribution headerは受け取りません。 +Azure OpenAI は、トランスポートと互換動作の点ではネイティブルーティングの区分に含まれますが、 +非表示の OpenAI/Codex 帰属ヘッダーは受け取りません。 -これにより、現在のネイティブOpenAI Responses動作を維持しつつ、 -古いOpenAI互換shimをサードパーティの `/v1` backendへ強制しないようにしています。 +これにより、現在のネイティブ OpenAI Responses の動作を維持しつつ、 +古い OpenAI 互換 shim をサードパーティの `/v1` バックエンドに強制しないようにしています。 -### OpenAI Responsesのサーバー側compaction +### Strict-agentic GPT モード -直接のOpenAI Responses model（`api: "openai-responses"` を使い、 -`baseUrl` が `api.openai.com` 上にある `openai/*`）では、OpenClawは現在、 -OpenAIのサーバー側compaction payload hintを自動有効化します: +`openai/*` および `openai-codex/*` の GPT-5 ファミリー実行では、OpenClaw は +より厳格な埋め込み Pi 実行コントラクトを使用できます: -- `store: true` を強制（model compatが `supportsStore: false` を設定していない限り） -- `context_management: [{ type: "compaction", compact_threshold: ... }]` を注入 +```json5 +{ + agents: { + defaults: { + embeddedPi: { + executionContract: "strict-agentic", + }, + }, + }, +} +``` -デフォルトでは、`compact_threshold` はmodel `contextWindow` の `70%` です（利用不可時は `80000`）。 +`strict-agentic` では、具体的なツールアクションが可能な場合、 +OpenClaw は計画だけのアシスタントターンを成功した進捗として扱わなくなります。即時実行を促す steer を付けてそのターンを再試行し、 +大きな作業には構造化された `update_plan` ツールを自動で有効にし、 +モデルが行動せずに計画を続ける場合は明示的なブロック状態を表示します。 -### サーバー側compactionを明示的に有効にする +このモードは、OpenAI および OpenAI Codex の GPT-5 ファミリー実行に限定されます。他のプロバイダー +および古いモデルファミリーは、他の実行時設定に明示的に参加させない限り、 +デフォルトの埋め込み Pi 動作のままです。 -互換性のあるResponses model（たとえばAzure OpenAI Responses）で -`context_management` 注入を強制したい場合に使用します: +### OpenAI Responses のサーバー側 compaction + +直接の OpenAI Responses モデル（`api: "openai-responses"` を使う `openai/*` で、 +`baseUrl` が `api.openai.com` のもの）では、OpenClaw は OpenAI のサーバー側 +compaction ペイロードヒントを自動で有効にします: + +- `store: true` を強制します（モデル互換設定で `supportsStore: false` の場合を除く） +- `context_management: [{ type: "compaction", compact_threshold: ... }]` を注入します + +デフォルトでは、`compact_threshold` はモデル `contextWindow` の `70%`（不明な場合は `80000`）です。 + +### サーバー側 compaction を明示的に有効にする + +互換性のある Responses モデル（たとえば Azure OpenAI Responses）で +`context_management` 注入を強制したい場合に使います: ```json5 { @@ -532,7 +549,7 @@ OpenAIのサーバー側compaction payload hintを自動有効化します: } ``` -### サーバー側compactionを無効にする +### サーバー側 compaction を無効にする ```json5 { @@ -550,11 +567,11 @@ OpenAIのサーバー側compaction payload hintを自動有効化します: } ``` -`responsesServerCompaction` が制御するのは `context_management` 注入だけです。 -直接のOpenAI Responses modelでは、compatが -`supportsStore: false` を設定していない限り、引き続き `store: true` を強制します。 +`responsesServerCompaction` は `context_management` 注入のみを制御します。 +直接の OpenAI Responses モデルでは、互換設定で +`supportsStore: false` が指定されていない限り、引き続き `store: true` を強制します。 ## 注意 -- Model refは常に `provider/model` を使います（[/concepts/models](/ja-JP/concepts/models) を参照）。 +- モデル参照は常に `provider/model` を使用します（[/concepts/models](/ja-JP/concepts/models) を参照）。 - 認証の詳細と再利用ルールは [/concepts/oauth](/ja-JP/concepts/oauth) にあります。