chore(i18n): refresh ja-JP translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
5d962d1e67
commit
590b6034e3
File diff suppressed because it is too large
Load Diff
@ -1,18 +1,18 @@
|
||||
---
|
||||
read_when:
|
||||
- Slack のセットアップまたは Slack のソケット/HTTP モードのデバッグ
|
||||
summary: Slack のセットアップとランタイム動作（Socket Mode + HTTP Request URLs）
|
||||
- Slack の設定、または Slack のソケット/HTTP モードのデバッグ
|
||||
summary: Slack のセットアップと実行時の動作（ソケットモード + HTTP リクエスト URL）
|
||||
title: Slack
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T04:58:17Z"
|
||||
generated_at: "2026-05-04T07:02:57Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 2be45f03511a64373b1f4316c59800eeeef8baccb4c00454b49999258b2e546b
|
||||
source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228
|
||||
source_path: channels/slack.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
DM とチャンネル向けに、Slack アプリ連携で本番運用可能です。デフォルトモードはソケットモードです。HTTPリクエストURLにも対応しています。
|
||||
DM とチャンネル向けに Slack アプリ連携経由で本番運用可能です。デフォルトのモードは Socket Mode です。HTTP Request URLs もサポートされています。
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="ペアリング" icon="link" href="/ja-JP/channels/pairing">
|
||||
@ -22,28 +22,28 @@ DM とチャンネル向けに、Slack アプリ連携で本番運用可能で
|
||||
ネイティブコマンドの動作とコマンドカタログ。
|
||||
</Card>
|
||||
<Card title="チャンネルのトラブルシューティング" icon="wrench" href="/ja-JP/channels/troubleshooting">
|
||||
チャンネル横断の診断と修復手順。
|
||||
チャンネル横断の診断と修復プレイブック。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## クイックセットアップ
|
||||
|
||||
<Tabs>
|
||||
<Tab title="ソケットモード（デフォルト）">
|
||||
<Tab title="Socket Mode (デフォルト)">
|
||||
<Steps>
|
||||
<Step title="新しい Slack アプリを作成する">
|
||||
Slack アプリ設定で **[新しいアプリを作成](https://api.slack.com/apps/new)** ボタンを押します。
|
||||
Slack アプリ設定で **[Create New App](https://api.slack.com/apps/new)** ボタンを押します。
|
||||
|
||||
- **マニフェストから** を選び、アプリ用のワークスペースを選択します
|
||||
- 下の [サンプルマニフェスト](#manifest-and-scope-checklist) を貼り付け、作成へ進みます
|
||||
- `connections:write` を持つ **アプリレベルトークン**（`xapp-...`）を生成します
|
||||
- アプリをインストールし、表示された **ボットトークン**（`xoxb-...`）をコピーします
|
||||
- **from a manifest** を選択し、アプリ用のワークスペースを選択します
|
||||
- 下の [マニフェスト例](#manifest-and-scope-checklist) を貼り付け、作成に進みます
|
||||
- `connections:write` を指定して **App-Level Token** (`xapp-...`) を生成します
|
||||
- アプリをインストールし、表示された **Bot Token** (`xoxb-...`) をコピーします
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="OpenClaw を設定する">
|
||||
|
||||
推奨の SecretRef セットアップ:
|
||||
推奨の SecretRef 設定:
|
||||
|
||||
```bash
|
||||
export SLACK_APP_TOKEN=xapp-...
|
||||
@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run
|
||||
openclaw config patch --file ./slack.socket.patch.json5
|
||||
```
|
||||
|
||||
環境変数フォールバック（デフォルトアカウントのみ）:
|
||||
env フォールバック (デフォルトアカウントのみ):
|
||||
|
||||
```bash
|
||||
SLACK_APP_TOKEN=xapp-...
|
||||
@ -84,21 +84,21 @@ openclaw gateway
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="HTTPリクエストURL">
|
||||
<Tab title="HTTP Request URLs">
|
||||
<Steps>
|
||||
<Step title="新しい Slack アプリを作成する">
|
||||
Slack アプリ設定で **[新しいアプリを作成](https://api.slack.com/apps/new)** ボタンを押します。
|
||||
Slack アプリ設定で **[Create New App](https://api.slack.com/apps/new)** ボタンを押します。
|
||||
|
||||
- **マニフェストから** を選び、アプリ用のワークスペースを選択します
|
||||
- [サンプルマニフェスト](#manifest-and-scope-checklist) を貼り付け、作成前にURLを更新します
|
||||
- リクエスト検証用の **署名シークレット** を保存します
|
||||
- アプリをインストールし、表示された **ボットトークン**（`xoxb-...`）をコピーします
|
||||
- **from a manifest** を選択し、アプリ用のワークスペースを選択します
|
||||
- [マニフェスト例](#manifest-and-scope-checklist) を貼り付け、作成前に URL を更新します
|
||||
- リクエスト検証用の **Signing Secret** を保存します
|
||||
- アプリをインストールし、表示された **Bot Token** (`xoxb-...`) をコピーします
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="OpenClaw を設定する">
|
||||
|
||||
推奨の SecretRef セットアップ:
|
||||
推奨の SecretRef 設定:
|
||||
|
||||
```bash
|
||||
export SLACK_BOT_TOKEN=xoxb-...
|
||||
@ -121,9 +121,9 @@ openclaw config patch --file ./slack.http.patch.json5
|
||||
```
|
||||
|
||||
<Note>
|
||||
複数アカウントのHTTPでは一意のWebhookパスを使用してください
|
||||
複数アカウントの HTTP には一意の webhook パスを使用する
|
||||
|
||||
登録が衝突しないように、各アカウントへ個別の `webhookPath`（デフォルトは `/slack/events`）を指定してください。
|
||||
登録が衝突しないように、各アカウントに個別の `webhookPath` (デフォルト `/slack/events`) を指定します。
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
@ -140,9 +140,9 @@ openclaw gateway
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## ソケットモードのトランスポート調整
|
||||
## Socket Mode トランスポート調整
|
||||
|
||||
OpenClaw はソケットモードで、Slack SDK クライアントのpongタイムアウトをデフォルトで15秒に設定します。ワークスペースまたはホスト固有の調整が必要な場合にのみ、トランスポート設定を上書きしてください。
|
||||
OpenClaw は Socket Mode で、デフォルトで Slack SDK クライアントの pong タイムアウトを 15 秒に設定します。ワークスペースまたはホスト固有の調整が必要な場合にのみ、トランスポート設定を上書きしてください。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -159,13 +159,13 @@ OpenClaw はソケットモードで、Slack SDK クライアントのpongタイ
|
||||
}
|
||||
```
|
||||
|
||||
これは、Slack websocket のpongタイムアウトやserver-pingタイムアウトがログに記録されるソケットモードのワークスペース、またはイベントループの枯渇が既知のホストでのみ使用してください。`clientPingTimeout` は SDK がクライアントpingを送信した後のpong待機時間です。`serverPingTimeout` は Slack サーバーpingの待機時間です。アプリメッセージとイベントはアプリケーション状態のままであり、トランスポートの生存確認シグナルではありません。
|
||||
これは、Slack websocket の pong/server-ping タイムアウトをログに記録する Socket Mode ワークスペース、または既知のイベントループ枯渇があるホストでのみ使用してください。`clientPingTimeout` は SDK がクライアント ping を送信した後の pong 待機時間です。`serverPingTimeout` は Slack サーバー ping の待機時間です。アプリメッセージとイベントは、トランスポートの生存性シグナルではなく、アプリケーション状態のままです。
|
||||
|
||||
## マニフェストとスコープのチェックリスト
|
||||
|
||||
基本の Slack アプリマニフェストは、ソケットモードとHTTPリクエストURLで同じです。異なるのは `settings` ブロック（およびスラッシュコマンドの `url`）だけです。
|
||||
基本の Slack アプリマニフェストは Socket Mode と HTTP Request URLs で同じです。異なるのは `settings` ブロック (およびスラッシュコマンドの `url`) だけです。
|
||||
|
||||
基本マニフェスト（ソケットモードのデフォルト）:
|
||||
基本マニフェスト (Socket Mode デフォルト):
|
||||
|
||||
```json
|
||||
{
|
||||
@ -240,7 +240,7 @@ OpenClaw はソケットモードで、Slack SDK クライアントのpongタイ
|
||||
}
|
||||
```
|
||||
|
||||
**HTTPリクエストURLモード** では、`settings` をHTTP版に置き換え、各スラッシュコマンドに `url` を追加します。公開URLが必要です。
|
||||
**HTTP Request URLs モード** では、`settings` を HTTP バリアントに置き換え、各スラッシュコマンドに `url` を追加します。公開 URL が必要です。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -284,22 +284,22 @@ OpenClaw はソケットモードで、Slack SDK クライアントのpongタイ
|
||||
|
||||
### 追加のマニフェスト設定
|
||||
|
||||
上記のデフォルトを拡張するさまざまな機能を公開します。
|
||||
上記のデフォルトを拡張する別の機能を公開します。
|
||||
|
||||
デフォルトのマニフェストでは、Slack App Home の **ホーム** タブが有効になり、`app_home_opened` を購読します。ワークスペースメンバーがホームタブを開くと、OpenClaw は `views.publish` で安全なデフォルトのホームビューを公開します。会話ペイロードや非公開設定は含まれません。Slack DM 向けに **メッセージ** タブは有効なままです。
|
||||
デフォルトのマニフェストでは、Slack App Home の **Home** タブが有効になり、`app_home_opened` をサブスクライブします。ワークスペースメンバーが Home タブを開くと、OpenClaw は `views.publish` で安全なデフォルトの Home ビューを公開します。会話ペイロードや非公開設定は含まれません。**Messages** タブは Slack DM 用に有効なままです。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="任意のネイティブスラッシュコマンド">
|
||||
|
||||
単一の設定済みコマンドの代わりに複数の [ネイティブスラッシュコマンド](#commands-and-slash-behavior) を使えますが、いくつか注意点があります。
|
||||
ニュアンスのある単一の設定済みコマンドの代わりに、複数の [ネイティブスラッシュコマンド](#commands-and-slash-behavior) を使用できます。
|
||||
|
||||
- `/status` コマンドは予約済みのため、`/status` の代わりに `/agentstatus` を使用してください。
|
||||
- 同時に利用可能にできるスラッシュコマンドは25個までです。
|
||||
- `/status` コマンドは予約されているため、`/status` の代わりに `/agentstatus` を使用します。
|
||||
- 一度に利用可能にできるスラッシュコマンドは 25 個以下です。
|
||||
|
||||
既存の `features.slash_commands` セクションを [利用可能なコマンド](/ja-JP/tools/slash-commands#command-list) の一部に置き換えます。
|
||||
既存の `features.slash_commands` セクションを、[利用可能なコマンド](/ja-JP/tools/slash-commands#command-list) のサブセットに置き換えます。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="ソケットモード（デフォルト）">
|
||||
<Tab title="Socket Mode (デフォルト)">
|
||||
|
||||
```json
|
||||
{
|
||||
@ -422,8 +422,8 @@ OpenClaw はソケットモードで、Slack SDK クライアントのpongタイ
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="HTTPリクエストURL">
|
||||
上記のソケットモードと同じ `slash_commands` リストを使用し、すべての項目に `"url": "https://gateway-host.example.com/slack/events"` を追加します。例:
|
||||
<Tab title="HTTP Request URLs">
|
||||
上の Socket Mode と同じ `slash_commands` リストを使用し、すべてのエントリに `"url": "https://gateway-host.example.com/slack/events"` を追加します。例:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -443,19 +443,19 @@ OpenClaw はソケットモードで、Slack SDK クライアントのpongタイ
|
||||
}
|
||||
```
|
||||
|
||||
リスト内のすべてのコマンドで同じ `url` 値を繰り返します。
|
||||
リスト内のすべてのコマンドでその `url` 値を繰り返します。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="任意の authorship スコープ（書き込み操作）">
|
||||
<Accordion title="任意の作成者表示スコープ（書き込み操作）">
|
||||
送信メッセージでデフォルトの Slack アプリ ID ではなく、アクティブなエージェント ID（カスタムユーザー名とアイコン）を使いたい場合は、`chat:write.customize` bot スコープを追加します。
|
||||
|
||||
絵文字アイコンを使う場合、Slack は `:emoji_name:` 構文を想定します。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="任意の user-token スコープ（読み取り操作）">
|
||||
<Accordion title="任意のユーザートークンスコープ（読み取り操作）">
|
||||
`channels.slack.userToken` を設定する場合、一般的な読み取りスコープは次のとおりです。
|
||||
|
||||
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
|
||||
@ -473,29 +473,34 @@ OpenClaw はソケットモードで、Slack SDK クライアントのpongタイ
|
||||
|
||||
- Socket Mode には `botToken` + `appToken` が必要です。
|
||||
- HTTP モードには `botToken` + `signingSecret` が必要です。
|
||||
- `botToken`, `appToken`, `signingSecret`, `userToken` は、プレーンテキスト文字列または SecretRef オブジェクトを受け付けます。
|
||||
- 設定トークンは env フォールバックより優先されます。
|
||||
- `botToken`、`appToken`、`signingSecret`、`userToken` はプレーンテキスト
|
||||
文字列または SecretRef オブジェクトを受け付けます。
|
||||
- 設定内のトークンは env フォールバックを上書きします。
|
||||
- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env フォールバックはデフォルトアカウントにのみ適用されます。
|
||||
- `userToken`（`xoxp-...`）は設定専用（env フォールバックなし）で、デフォルトでは読み取り専用の動作（`userTokenReadOnly: true`）になります。
|
||||
- `userToken`（`xoxp-...`）は設定専用（env フォールバックなし）で、デフォルトでは読み取り専用動作（`userTokenReadOnly: true`）です。
|
||||
|
||||
ステータススナップショットの動作:
|
||||
|
||||
- Slack アカウント検査は、認証情報ごとの `*Source` と `*Status` フィールド（`botToken`, `appToken`, `signingSecret`, `userToken`）を追跡します。
|
||||
- ステータスは `available`, `configured_unavailable`, `missing` のいずれかです。
|
||||
- `configured_unavailable` は、そのアカウントが SecretRef または別の非インラインシークレットソースを通じて設定されているものの、現在のコマンドまたはランタイムパスでは実際の値を解決できなかったことを意味します。
|
||||
- HTTP モードでは `signingSecretStatus` が含まれます。Socket Mode では必要なペアは `botTokenStatus` + `appTokenStatus` です。
|
||||
- Slack アカウント検査は、認証情報ごとの `*Source` および `*Status`
|
||||
フィールド（`botToken`、`appToken`、`signingSecret`、`userToken`）を追跡します。
|
||||
- ステータスは `available`、`configured_unavailable`、または `missing` です。
|
||||
- `configured_unavailable` は、アカウントが SecretRef
|
||||
または別の非インラインのシークレットソースを通じて設定されているものの、現在のコマンド/runtime パスでは
|
||||
実際の値を解決できなかったことを意味します。
|
||||
- HTTP モードでは `signingSecretStatus` が含まれます。Socket Mode では
|
||||
必須のペアは `botTokenStatus` + `appTokenStatus` です。
|
||||
|
||||
<Tip>
|
||||
アクションやディレクトリ読み取りでは、設定されている場合に user token が優先されることがあります。書き込みでは bot token が引き続き優先されます。user-token 書き込みは、`userTokenReadOnly: false` で、かつ bot token が利用できない場合にのみ許可されます。
|
||||
actions/directory の読み取りでは、設定されている場合に user token が優先されることがあります。書き込みでは bot token が引き続き優先されます。user-token 書き込みは、`userTokenReadOnly: false` で bot token が利用できない場合にのみ許可されます。
|
||||
</Tip>
|
||||
|
||||
## アクションとゲート
|
||||
|
||||
Slack アクションは `channels.slack.actions.*` で制御されます。
|
||||
|
||||
現在の Slack ツールで利用できるアクショングループ:
|
||||
現在の Slack ツールで利用可能なアクショングループ:
|
||||
|
||||
| グループ | デフォルト |
|
||||
| グループ | デフォルト |
|
||||
| ---------- | ------- |
|
||||
| messages | 有効 |
|
||||
| reactions | 有効 |
|
||||
@ -503,7 +508,7 @@ Slack アクションは `channels.slack.actions.*` で制御されます。
|
||||
| memberInfo | 有効 |
|
||||
| emojiList | 有効 |
|
||||
|
||||
現在の Slack メッセージアクションには、`send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, `emoji-list` があります。`download-file` は受信ファイルプレースホルダーに表示される Slack ファイル ID を受け取り、画像の場合は画像プレビューを、それ以外のファイル種別の場合はローカルファイルメタデータを返します。
|
||||
現在の Slack メッセージアクションには、`send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info`、`emoji-list` があります。`download-file` はインバウンドファイルプレースホルダーに表示される Slack ファイル ID を受け付け、画像の場合は画像プレビューを、それ以外のファイルタイプの場合はローカルファイルメタデータを返します。
|
||||
|
||||
## アクセス制御とルーティング
|
||||
|
||||
@ -513,50 +518,50 @@ Slack アクションは `channels.slack.actions.*` で制御されます。
|
||||
|
||||
- `pairing`（デフォルト）
|
||||
- `allowlist`
|
||||
- `open`（`channels.slack.allowFrom` に `"*"` が含まれている必要があります）
|
||||
- `open`（`channels.slack.allowFrom` に `"*"` を含める必要があります）
|
||||
- `disabled`
|
||||
|
||||
DM フラグ:
|
||||
|
||||
- `dm.enabled`（デフォルト true）
|
||||
- `dm.enabled`（デフォルトは true）
|
||||
- `channels.slack.allowFrom`
|
||||
- `dm.allowFrom`（レガシー）
|
||||
- `dm.groupEnabled`（グループ DM のデフォルトは false）
|
||||
- `dm.groupChannels`（任意の MPIM 許可リスト）
|
||||
|
||||
複数アカウントでの優先順位:
|
||||
マルチアカウントの優先順位:
|
||||
|
||||
- `channels.slack.accounts.default.allowFrom` は `default` アカウントにのみ適用されます。
|
||||
- 名前付きアカウントは、自身の `allowFrom` が未設定の場合に `channels.slack.allowFrom` を継承します。
|
||||
- 名前付きアカウントは `channels.slack.accounts.default.allowFrom` を継承しません。
|
||||
|
||||
レガシーの `channels.slack.dm.policy` と `channels.slack.dm.allowFrom` は、互換性のために引き続き読み取られます。`openclaw doctor --fix` は、アクセスを変更せずに実行できる場合、それらを `dmPolicy` と `allowFrom` に移行します。
|
||||
レガシーの `channels.slack.dm.policy` と `channels.slack.dm.allowFrom` は互換性のため引き続き読み取られます。`openclaw doctor --fix` は、アクセスを変更せずに実行できる場合、それらを `dmPolicy` と `allowFrom` に移行します。
|
||||
|
||||
DM でのペアリングには `openclaw pairing approve slack <code>` を使います。
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="チャンネルポリシー">
|
||||
`channels.slack.groupPolicy` はチャンネル処理を制御します。
|
||||
`channels.slack.groupPolicy` はチャンネルの処理を制御します。
|
||||
|
||||
- `open`
|
||||
- `allowlist`
|
||||
- `disabled`
|
||||
|
||||
チャンネル許可リストは `channels.slack.channels` 配下にあり、設定キーとして**安定した Slack チャンネル ID**（例: `C12345678`）を使う必要があります。
|
||||
チャンネル許可リストは `channels.slack.channels` の下にあり、設定キーとして**安定した Slack チャンネル ID**（例: `C12345678`）を使う必要があります。
|
||||
|
||||
ランタイム上の注意: `channels.slack` が完全に存在しない場合（env のみのセットアップ）、ランタイムは `groupPolicy="allowlist"` にフォールバックし、警告をログに出力します（`channels.defaults.groupPolicy` が設定されている場合でも同様です）。
|
||||
Runtime 注記: `channels.slack` が完全に存在しない場合（env のみのセットアップ）、runtime は `groupPolicy="allowlist"` にフォールバックし、警告をログに記録します（`channels.defaults.groupPolicy` が設定されている場合でも）。
|
||||
|
||||
名前/ID 解決:
|
||||
|
||||
- チャンネル許可リストエントリと DM 許可リストエントリは、トークンアクセスで許可される場合、起動時に解決されます
|
||||
- 未解決のチャンネル名エントリは設定されたまま保持されますが、デフォルトではルーティングでは無視されます
|
||||
- 受信認可とチャンネルルーティングはデフォルトで ID 優先です。直接のユーザー名/スラッグ照合には `channels.slack.dangerouslyAllowNameMatching: true` が必要です
|
||||
- チャンネル許可リストのエントリと DM 許可リストのエントリは、トークンアクセスで可能な場合、起動時に解決されます
|
||||
- 解決できないチャンネル名エントリは設定されたまま保持されますが、デフォルトではルーティングで無視されます
|
||||
- インバウンド認可とチャンネルルーティングはデフォルトで ID 優先です。直接のユーザー名/slug マッチングには `channels.slack.dangerouslyAllowNameMatching: true` が必要です
|
||||
|
||||
<Warning>
|
||||
名前ベースのキー（`#channel-name` または `channel-name`）は `groupPolicy: "allowlist"` では一致しません。チャンネル検索はデフォルトで ID 優先のため、名前ベースのキーでは正常にルーティングされず、そのチャンネル内のすべてのメッセージがサイレントにブロックされます。これは、チャンネルキーがルーティングに不要で、名前ベースのキーが機能しているように見える `groupPolicy: "open"` とは異なります。
|
||||
名前ベースのキー（`#channel-name` または `channel-name`）は `groupPolicy: "allowlist"` では一致しません。チャンネル検索はデフォルトで ID 優先のため、名前ベースのキーでは正常にルーティングされることはなく、そのチャンネル内のすべてのメッセージは静かにブロックされます。これは、ルーティングにチャンネルキーが不要で、名前ベースのキーが機能しているように見える `groupPolicy: "open"` とは異なります。
|
||||
|
||||
キーには必ず Slack チャンネル ID を使ってください。確認するには、Slack でチャンネルを右クリック → **Copy link** — URL の末尾に ID（`C...`）が表示されます。
|
||||
常に Slack チャンネル ID をキーとして使ってください。見つけるには、Slack でチャンネルを右クリック → **リンクをコピー** — URL の末尾に ID（`C...`）が表示されます。
|
||||
|
||||
正しい例:
|
||||
|
||||
@ -573,7 +578,7 @@ Slack アクションは `channels.slack.actions.*` で制御されます。
|
||||
}
|
||||
```
|
||||
|
||||
誤った例（`groupPolicy: "allowlist"` ではサイレントにブロックされます）:
|
||||
誤り（`groupPolicy: "allowlist"` の下で暗黙的にブロックされます）:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -591,28 +596,28 @@ Slack アクションは `channels.slack.actions.*` で制御されます。
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="メンションとチャンネルユーザー">
|
||||
チャンネルメッセージはデフォルトでメンションによってゲートされます。
|
||||
<Tab title="Mentions and channel users">
|
||||
チャンネルメッセージはデフォルトでメンションによって制限されます。
|
||||
|
||||
メンションソース:
|
||||
メンションのソース:
|
||||
|
||||
- 明示的なアプリメンション（`<@botId>`）
|
||||
- bot ユーザーがそのユーザーグループのメンバーである場合の Slack ユーザーグループメンション（`<!subteam^S...>`）。`usergroups:read` が必要です
|
||||
- ボットユーザーがそのユーザーグループのメンバーである場合の Slack ユーザーグループメンション（`<!subteam^S...>`）。`usergroups:read` が必要です
|
||||
- メンション正規表現パターン（`agents.list[].groupChat.mentionPatterns`、フォールバックは `messages.groupChat.mentionPatterns`）
|
||||
- bot への暗黙的な返信スレッド動作（`thread.requireExplicitMention` が `true` の場合は無効）
|
||||
- ボットへの返信スレッドの暗黙的な動作（`thread.requireExplicitMention` が `true` の場合は無効）
|
||||
|
||||
チャンネルごとの制御（`channels.slack.channels.<id>`。名前は起動時解決または `dangerouslyAllowNameMatching` 経由のみ）:
|
||||
チャンネルごとの制御（`channels.slack.channels.<id>`。名前は起動時の解決または `dangerouslyAllowNameMatching` 経由のみ）:
|
||||
|
||||
- `requireMention`
|
||||
- `users`（許可リスト）
|
||||
- `users`（allowlist）
|
||||
- `allowBots`
|
||||
- `skills`
|
||||
- `systemPrompt`
|
||||
- `tools`, `toolsBySender`
|
||||
- `toolsBySender` キー形式: `id:`, `e164:`, `username:`, `name:`, または `"*"` ワイルドカード
|
||||
（レガシーの接頭辞なしキーは引き続き `id:` のみにマップされます）
|
||||
- `tools`、`toolsBySender`
|
||||
- `toolsBySender` のキー形式: `id:`、`e164:`、`username:`、`name:`、または `"*"` ワイルドカード
|
||||
（レガシーのプレフィックスなしキーは引き続き `id:` のみにマップされます）
|
||||
|
||||
`allowBots` はチャンネルとプライベートチャンネルでは保守的です。bot が作成したルームメッセージは、送信元 bot がそのルームの `users` 許可リストに明示的に記載されている場合、または `channels.slack.allowFrom` の明示的な Slack 所有者 ID の少なくとも 1 つが現在ルームメンバーである場合にのみ受け付けられます。ワイルドカードや表示名の所有者エントリは、所有者の存在を満たしません。所有者の存在確認には Slack `conversations.members` を使います。アプリにルーム種別に対応する読み取りスコープ（公開チャンネルは `channels:read`、プライベートチャンネルは `groups:read`）があることを確認してください。メンバー検索に失敗した場合、OpenClaw は bot が作成したルームメッセージを破棄します。
|
||||
`allowBots` はチャンネルとプライベートチャンネルでは保守的です。ボットが作成したルームメッセージは、送信元ボットがそのルームの `users` allowlist に明示的に列挙されている場合、または `channels.slack.allowFrom` からの明示的な Slack オーナー ID が少なくとも 1 つ現在ルームメンバーである場合にのみ受け付けられます。ワイルドカードと表示名のオーナーエントリは、オーナーの存在条件を満たしません。オーナーの存在確認には Slack `conversations.members` を使用します。アプリにルーム種別に対応する読み取りスコープ（パブリックチャンネルは `channels:read`、プライベートチャンネルは `groups:read`）があることを確認してください。メンバー検索に失敗した場合、OpenClaw はボットが作成したルームメッセージを破棄します。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -620,65 +625,84 @@ Slack アクションは `channels.slack.actions.*` で制御されます。
|
||||
## スレッド、セッション、返信タグ
|
||||
|
||||
- DM は `direct` として、チャンネルは `channel` として、MPIM は `group` としてルーティングされます。
|
||||
- Slack ルートバインディングは、生のピア ID に加えて、`channel:C12345678`, `user:U12345678`, `<@U12345678>` などの Slack ターゲット形式を受け付けます。
|
||||
- Slack ルートバインディングは、生のピア ID に加えて `channel:C12345678`、`user:U12345678`、`<@U12345678>` などの Slack ターゲット形式を受け付けます。
|
||||
- デフォルトの `session.dmScope=main` では、Slack DM はエージェントのメインセッションに集約されます。
|
||||
- チャンネルセッション: `agent:<agentId>:slack:channel:<channelId>`。
|
||||
- スレッド返信は、該当する場合にスレッドセッションサフィックス（`:thread:<threadTs>`）を作成できます。
|
||||
- スレッド返信では、該当する場合にスレッドセッション接尾辞（`:thread:<threadTs>`）を作成できます。
|
||||
- `channels.slack.thread.historyScope` のデフォルトは `thread` です。`thread.inheritParent` のデフォルトは `false` です。
|
||||
- `channels.slack.thread.initialHistoryLimit` は、新しいスレッドセッションが開始するときに取得する既存スレッドメッセージ数を制御します（デフォルトは `20`。無効にするには `0` を設定します）。
|
||||
- `channels.slack.thread.requireExplicitMention`（デフォルト `false`）: `true` の場合、bot がすでにスレッドに参加していても、bot はスレッド内の明示的な `@bot` メンションにのみ応答するよう、暗黙的なスレッドメンションを抑制します。これがない場合、bot が参加したスレッド内の返信は `requireMention` ゲートをバイパスします。
|
||||
- `channels.slack.thread.initialHistoryLimit` は、新しいスレッドセッションの開始時に取得される既存スレッドメッセージ数を制御します（デフォルトは `20`。無効にするには `0` を設定）。
|
||||
- `channels.slack.thread.requireExplicitMention`（デフォルト `false`）: `true` の場合、暗黙的なスレッドメンションを抑制し、ボットがすでにスレッドに参加していても、スレッド内の明示的な `@bot` メンションにのみボットが応答します。これがない場合、ボットが参加したスレッド内の返信は `requireMention` の制限をバイパスします。
|
||||
|
||||
返信スレッド制御:
|
||||
返信スレッドの制御:
|
||||
|
||||
- `channels.slack.replyToMode`: `off|first|all|batched`（デフォルト `off`）
|
||||
- `channels.slack.replyToModeByChatType`: `direct|group|channel` ごと
|
||||
- 直接チャット向けのレガシーフォールバック: `channels.slack.dm.replyToMode`
|
||||
- ダイレクトチャット向けのレガシーフォールバック: `channels.slack.dm.replyToMode`
|
||||
|
||||
手動返信タグがサポートされています。
|
||||
手動返信タグがサポートされています:
|
||||
|
||||
- `[[reply_to_current]]`
|
||||
- `[[reply_to:<id>]]`
|
||||
|
||||
<Note>
|
||||
`replyToMode="off"` は、明示的な `[[reply_to_*]]` タグを含む Slack の**すべて**の返信スレッドを無効にします。これは、`"off"` モードでも明示的なタグが引き続き尊重される Telegram とは異なります。Slack スレッドはメッセージをチャンネルから隠しますが、Telegram の返信はインラインで表示されたままです。
|
||||
`replyToMode="off"` は、明示的な `[[reply_to_*]]` タグを含む Slack の**すべての**返信スレッド化を無効にします。これは、明示的なタグが `"off"` モードでも引き続き尊重される Telegram とは異なります。Slack スレッドはチャンネルからメッセージを非表示にしますが、Telegram の返信はインラインで表示されたままです。
|
||||
</Note>
|
||||
|
||||
## Ack リアクション
|
||||
|
||||
`ackReaction` は、OpenClaw が受信メッセージを処理している間、確認応答の絵文字を送信します。
|
||||
`ackReaction` は、OpenClaw が受信メッセージを処理している間に確認用絵文字を送信します。
|
||||
|
||||
解決順序:
|
||||
|
||||
- `channels.slack.accounts.<accountId>.ackReaction`
|
||||
- `channels.slack.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- エージェント ID の絵文字フォールバック（`agents.list[].identity.emoji`、それ以外は "👀"）
|
||||
- エージェント ID 絵文字フォールバック（`agents.list[].identity.emoji`、なければ「👀」）
|
||||
|
||||
注記:
|
||||
注:
|
||||
|
||||
- Slack はショートコード（例: `"eyes"`）を想定します。
|
||||
- Slack アカウントまたは全体でリアクションを無効にするには `""` を使います。
|
||||
- Slack はショートコード（例: `"eyes"`）を想定しています。
|
||||
- Slack アカウントまたはグローバルでリアクションを無効にするには `""` を使用します。
|
||||
|
||||
## テキストストリーミング
|
||||
|
||||
`channels.slack.streaming` はライブプレビューの動作を制御します。
|
||||
`channels.slack.streaming` はライブプレビューの動作を制御します:
|
||||
|
||||
- `off`: ライブプレビューストリーミングを無効にします。
|
||||
- `partial`（デフォルト）: プレビューテキストを最新の部分出力で置き換えます。
|
||||
- `block`: チャンク化されたプレビュー更新を追加します。
|
||||
- `progress`: 生成中は進行状況テキストを表示し、その後に最終テキストを送信します。
|
||||
- `streaming.preview.toolProgress`: 下書きプレビューが有効な場合、ツール/進行状況更新を同じ編集済みプレビューメッセージにルーティングします（デフォルト: `true`）。別々のツール/進行状況メッセージを維持するには `false` を設定します。
|
||||
- `block`: 分割されたプレビュー更新を追加します。
|
||||
- `progress`: 生成中は進行状況テキストを表示し、その後で最終テキストを送信します。
|
||||
- `streaming.preview.toolProgress`: 下書きプレビューが有効な場合、ツール/進行状況の更新を同じ編集済みプレビューメッセージにルーティングします（デフォルト: `true`）。個別のツール/進行状況メッセージを保持するには `false` に設定します。
|
||||
- `streaming.preview.commandText` / `streaming.progress.commandText`: 生のコマンド/実行テキストを隠しつつ、コンパクトなツール進行状況行を保持するには `status` に設定します（デフォルト: `raw`）。
|
||||
|
||||
コンパクトな進行状況行を保持しながら、生のコマンド/実行テキストを非表示にします:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"slack": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`channels.slack.streaming.nativeTransport` は、`channels.slack.streaming.mode` が `partial` の場合の Slack ネイティブテキストストリーミングを制御します（デフォルト: `true`）。
|
||||
|
||||
- ネイティブテキストストリーミングと Slack アシスタントスレッドステータスを表示するには、返信スレッドが利用可能である必要があります。スレッド選択は引き続き `replyToMode` に従います。
|
||||
- ネイティブストリーミングが利用できない場合、または返信スレッドが存在しない場合でも、チャンネル、グループチャット、トップレベル DM ルートは通常の下書きプレビューを使用できます。
|
||||
- トップレベルの Slack DM はデフォルトでスレッド外のままなので、Slack のスレッド形式のネイティブストリーム/ステータスプレビューは表示されません。代わりに OpenClaw は DM に下書きプレビューを投稿して編集します。
|
||||
- メディアと非テキストペイロードは通常の配信にフォールバックします。
|
||||
- メディア/エラーの最終出力は保留中のプレビュー編集をキャンセルします。対象となるテキスト/ブロックの最終出力は、プレビューをその場で編集できる場合にのみフラッシュされます。
|
||||
- 返信の途中でストリーミングに失敗した場合、OpenClaw は残りのペイロードについて通常の配信にフォールバックします。
|
||||
- ネイティブストリーミングを利用できない場合、または返信スレッドが存在しない場合でも、チャンネル、グループチャット、トップレベル DM ルートは通常の下書きプレビューを使用できます。
|
||||
- トップレベルの Slack DM はデフォルトでスレッド外に留まるため、Slack のスレッド形式のネイティブストリーム/ステータスプレビューは表示されません。代わりに OpenClaw が DM に下書きプレビューを投稿して編集します。
|
||||
- メディアと非テキストペイロードは通常配信にフォールバックします。
|
||||
- メディア/エラーの最終結果は保留中のプレビュー編集をキャンセルします。対象となるテキスト/ブロックの最終結果は、プレビューをその場で編集できる場合にのみフラッシュされます。
|
||||
- 返信途中でストリーミングが失敗した場合、OpenClaw は残りのペイロードを通常配信にフォールバックします。
|
||||
|
||||
Slack ネイティブテキストストリーミングの代わりに下書きプレビューを使う:
|
||||
Slack ネイティブテキストストリーミングの代わりに下書きプレビューを使用します:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -696,12 +720,12 @@ Slack ネイティブテキストストリーミングの代わりに下書き
|
||||
レガシーキー:
|
||||
|
||||
- `channels.slack.streamMode`（`replace | status_final | append`）は `channels.slack.streaming.mode` に自動移行されます。
|
||||
- boolean の `channels.slack.streaming` は `channels.slack.streaming.mode` と `channels.slack.streaming.nativeTransport` に自動移行されます。
|
||||
- boolean `channels.slack.streaming` は `channels.slack.streaming.mode` と `channels.slack.streaming.nativeTransport` に自動移行されます。
|
||||
- レガシーの `channels.slack.nativeStreaming` は `channels.slack.streaming.nativeTransport` に自動移行されます。
|
||||
|
||||
## Typing リアクションフォールバック
|
||||
## タイピングリアクションのフォールバック
|
||||
|
||||
`typingReaction` は、OpenClaw が返信を処理している間に受信 Slack メッセージへ一時的なリアクションを追加し、実行が終了するとそれを削除します。これは、デフォルトの "is typing..." ステータスインジケーターを使うスレッド返信の外で特に役立ちます。
|
||||
`typingReaction` は、OpenClaw が返信を処理している間、受信した Slack メッセージに一時的なリアクションを追加し、実行が完了するとそれを削除します。これはデフォルトの「is typing...」ステータスインジケーターを使うスレッド返信以外で最も役立ちます。
|
||||
|
||||
解決順序:
|
||||
|
||||
@ -710,16 +734,16 @@ Slack ネイティブテキストストリーミングの代わりに下書き
|
||||
|
||||
注記:
|
||||
|
||||
- Slack はショートコード（例: `"hourglass_flowing_sand"`）を想定します。
|
||||
- リアクションはベストエフォートで、返信または失敗パスの完了後にクリーンアップが自動的に試行されます。
|
||||
- Slack はショートコードを想定します（例: `"hourglass_flowing_sand"`）。
|
||||
- リアクションはベストエフォートであり、返信または失敗パスの完了後に自動的なクリーンアップが試行されます。
|
||||
|
||||
## メディア、チャンク分割、配信
|
||||
## メディア、チャンク化、配信
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="受信添付ファイル">
|
||||
Slack のファイル添付は、Slack がホストするプライベート URL（トークン認証付きリクエストフロー）からダウンロードされ、取得に成功してサイズ制限が許す場合はメディアストアに書き込まれます。ファイルプレースホルダーには Slack の `fileId` が含まれるため、エージェントは `download-file` で元のファイルを取得できます。
|
||||
Slack ファイル添付は、Slack がホストするプライベート URL（トークン認証付きリクエストフロー）からダウンロードされ、取得が成功しサイズ制限が許す場合にメディアストアへ書き込まれます。ファイルプレースホルダーには Slack の `fileId` が含まれるため、エージェントは `download-file` で元のファイルを取得できます。
|
||||
|
||||
ダウンロードには、制限付きのアイドルタイムアウトと合計タイムアウトが使われます。Slack ファイルの取得が停止または失敗した場合でも、OpenClaw はメッセージの処理を継続し、ファイルプレースホルダーにフォールバックします。
|
||||
ダウンロードには、制限付きのアイドルタイムアウトと合計タイムアウトが使われます。Slack ファイル取得が停止または失敗した場合、OpenClaw はメッセージの処理を継続し、ファイルプレースホルダーにフォールバックします。
|
||||
|
||||
ランタイムの受信サイズ上限は、`channels.slack.mediaMaxMb` で上書きされない限り、デフォルトで `20MB` です。
|
||||
|
||||
@ -728,25 +752,25 @@ Slack ネイティブテキストストリーミングの代わりに下書き
|
||||
<Accordion title="送信テキストとファイル">
|
||||
- テキストチャンクは `channels.slack.textChunkLimit`（デフォルト 4000）を使います
|
||||
- `channels.slack.chunkMode="newline"` は段落優先の分割を有効にします
|
||||
- ファイル送信は Slack アップロード API を使い、スレッド返信（`thread_ts`）を含められます
|
||||
- 送信メディアの上限は、設定されている場合は `channels.slack.mediaMaxMb` に従います。それ以外の場合、チャンネル送信はメディアパイプラインの MIME 種別デフォルトを使います
|
||||
- ファイル送信は Slack アップロード API を使い、スレッド返信（`thread_ts`）を含めることができます
|
||||
- 送信メディア上限は、設定されている場合は `channels.slack.mediaMaxMb` に従います。それ以外の場合、チャンネル送信はメディアパイプラインの MIME 種別デフォルトを使います
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="配信ターゲット">
|
||||
推奨される明示的なターゲット:
|
||||
<Accordion title="配信先">
|
||||
推奨される明示的な送信先:
|
||||
|
||||
- DM には `user:<id>`
|
||||
- チャンネルには `channel:<id>`
|
||||
|
||||
テキストまたはブロックのみの Slack DM はユーザー ID に直接投稿できます。ファイルアップロードとスレッド送信では具体的な会話 ID が必要なため、まず Slack 会話 API で DM を開きます。
|
||||
テキスト/ブロックのみの Slack DM はユーザー ID に直接投稿できます。ファイルアップロードとスレッド送信では、具体的な会話 ID が必要なため、まず Slack conversation API で DM を開きます。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## コマンドとスラッシュの動作
|
||||
|
||||
スラッシュコマンドは、Slack では単一の設定済みコマンド、または複数のネイティブコマンドとして表示されます。コマンドのデフォルトを変更するには、`channels.slack.slashCommand` を設定します。
|
||||
スラッシュコマンドは、Slack では単一の設定済みコマンドまたは複数のネイティブコマンドとして表示されます。コマンドのデフォルトを変更するには、`channels.slack.slashCommand` を設定します:
|
||||
|
||||
- `enabled: false`
|
||||
- `name: "openclaw"`
|
||||
@ -757,32 +781,32 @@ Slack ネイティブテキストストリーミングの代わりに下書き
|
||||
/openclaw /help
|
||||
```
|
||||
|
||||
ネイティブコマンドには Slack アプリで [追加のマニフェスト設定](#additional-manifest-settings) が必要で、代わりに `channels.slack.commands.native: true`、またはグローバル設定の `commands.native: true` で有効化します。
|
||||
ネイティブコマンドには Slack アプリで [追加のマニフェスト設定](#additional-manifest-settings) が必要で、代わりに `channels.slack.commands.native: true` またはグローバル設定の `commands.native: true` で有効にします。
|
||||
|
||||
- Slack ではネイティブコマンドの自動モードが **オフ** のため、`commands.native: "auto"` は Slack ネイティブコマンドを有効化しません。
|
||||
- Slack ではネイティブコマンドの自動モードは **オフ** であるため、`commands.native: "auto"` は Slack ネイティブコマンドを有効にしません。
|
||||
|
||||
```txt
|
||||
/help
|
||||
```
|
||||
|
||||
ネイティブ引数メニューは、選択されたオプション値をディスパッチする前に確認モーダルを表示する適応型レンダリング戦略を使います。
|
||||
ネイティブ引数メニューは、選択されたオプション値をディスパッチする前に確認モーダルを表示する適応型レンダリング戦略を使います:
|
||||
|
||||
- 最大 5 個のオプション: ボタンブロック
|
||||
- 6-100 個のオプション: 静的セレクトメニュー
|
||||
- 100 個を超えるオプション: インタラクティビティオプションハンドラーが利用可能な場合、非同期オプションフィルタリング付き外部セレクト
|
||||
- 6〜100 個のオプション: 静的選択メニュー
|
||||
- 100 個を超えるオプション: インタラクティビティオプションハンドラーが利用可能な場合、非同期オプションフィルタリング付きの外部選択
|
||||
- Slack の制限超過: エンコードされたオプション値はボタンにフォールバックします
|
||||
|
||||
```txt
|
||||
/think
|
||||
```
|
||||
|
||||
スラッシュセッションは `agent:<agentId>:slack:slash:<userId>` のような分離キーを使い、引き続き `CommandTargetSessionKey` を使ってコマンド実行をターゲット会話セッションへルーティングします。
|
||||
スラッシュセッションは `agent:<agentId>:slack:slash:<userId>` のような分離キーを使い、`CommandTargetSessionKey` を使って対象会話セッションへコマンド実行を引き続きルーティングします。
|
||||
|
||||
## インタラクティブ返信
|
||||
|
||||
Slack は、エージェントが作成したインタラクティブ返信コントロールをレンダリングできますが、この機能はデフォルトでは無効です。
|
||||
Slack はエージェント作成のインタラクティブな返信コントロールをレンダリングできますが、この機能はデフォルトで無効です。
|
||||
|
||||
グローバルに有効化します。
|
||||
グローバルに有効にします:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -796,7 +820,7 @@ Slack は、エージェントが作成したインタラクティブ返信コ
|
||||
}
|
||||
```
|
||||
|
||||
または、1 つの Slack アカウントだけで有効化します。
|
||||
または、1 つの Slack アカウントだけで有効にします:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -814,29 +838,29 @@ Slack は、エージェントが作成したインタラクティブ返信コ
|
||||
}
|
||||
```
|
||||
|
||||
有効化すると、エージェントは Slack 専用の返信ディレクティブを出力できます。
|
||||
有効にすると、エージェントは Slack 専用の返信ディレクティブを出力できます:
|
||||
|
||||
- `[[slack_buttons: Approve:approve, Reject:reject]]`
|
||||
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
|
||||
|
||||
これらのディレクティブは Slack Block Kit にコンパイルされ、クリックや選択を既存の Slack インタラクションイベントパス経由で戻します。
|
||||
これらのディレクティブは Slack Block Kit にコンパイルされ、クリックまたは選択を既存の Slack interaction イベントパス経由でルーティングします。
|
||||
|
||||
注記:
|
||||
|
||||
- これは Slack 固有の UI です。他のチャンネルは Slack Block Kit ディレクティブを独自のボタンシステムに変換しません。
|
||||
- インタラクティブコールバック値は、エージェントが作成した生の値ではなく、OpenClaw が生成した不透明トークンです。
|
||||
- 生成されたインタラクティブブロックが Slack Block Kit の制限を超える場合、OpenClaw は無効なブロックペイロードを送信する代わりに、元のテキスト返信へフォールバックします。
|
||||
- 生成されたインタラクティブブロックが Slack Block Kit の制限を超える場合、OpenClaw は無効な blocks ペイロードを送信する代わりに、元のテキスト返信にフォールバックします。
|
||||
|
||||
## Slack での Exec 承認
|
||||
|
||||
Slack は、Web UI やターミナルへフォールバックする代わりに、インタラクティブボタンとインタラクションを備えたネイティブ承認クライアントとして機能できます。
|
||||
Slack は、Web UI やターミナルへのフォールバックの代わりに、インタラクティブボタンとインタラクションを備えたネイティブ承認クライアントとして動作できます。
|
||||
|
||||
- Exec 承認は、ネイティブ DM/チャンネルルーティングに `channels.slack.execApprovals.*` を使います。
|
||||
- Exec 承認はネイティブ DM/チャンネルルーティングに `channels.slack.execApprovals.*` を使います。
|
||||
- Plugin 承認は、リクエストがすでに Slack に届いていて承認 ID 種別が `plugin:` の場合、同じ Slack ネイティブボタン画面を通じて引き続き解決できます。
|
||||
- 承認者の認可は引き続き強制されます。承認者として識別されたユーザーだけが、Slack 経由でリクエストを承認または拒否できます。
|
||||
|
||||
これは他のチャンネルと同じ共有承認ボタン画面を使います。Slack アプリ設定で `interactivity` が有効な場合、承認プロンプトは会話内に直接 Block Kit ボタンとしてレンダリングされます。
|
||||
それらのボタンが存在する場合、それらが主要な承認 UX です。OpenClaw は、ツール結果がチャット承認を利用できない、または手動承認が唯一のパスであることを示す場合にのみ、手動の `/approve` コマンドを含めるべきです。
|
||||
それらのボタンが存在する場合、それらが主要な承認 UX です。OpenClaw は、ツール結果がチャット承認は利用できない、または手動承認が唯一の経路だと示す場合に限り、手動の `/approve` コマンドを含めるべきです。
|
||||
|
||||
設定パス:
|
||||
|
||||
@ -845,9 +869,8 @@ Slack は、Web UI やターミナルへフォールバックする代わりに
|
||||
- `channels.slack.execApprovals.target`（`dm` | `channel` | `both`、デフォルト: `dm`）
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人の
|
||||
承認者が解決される場合、ネイティブ Exec 承認を自動的に有効化します。Slack をネイティブ承認クライアントとして明示的に無効化するには、`enabled: false` を設定します。
|
||||
承認者が解決される場合にネイティブ承認を強制的に有効化するには、`enabled: true` を設定します。
|
||||
Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人の承認者が解決される場合、ネイティブ Exec 承認を自動的に有効にします。Slack をネイティブ承認クライアントとして明示的に無効にするには `enabled: false` を設定します。
|
||||
承認者が解決される場合にネイティブ承認を強制的にオンにするには、`enabled: true` を設定します。
|
||||
|
||||
明示的な Slack Exec 承認設定がない場合のデフォルト動作:
|
||||
|
||||
@ -859,8 +882,7 @@ Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人
|
||||
}
|
||||
```
|
||||
|
||||
明示的な Slack ネイティブ設定が必要なのは、承認者を上書きする、フィルターを追加する、または
|
||||
送信元チャット配信にオプトインする場合だけです。
|
||||
明示的な Slack ネイティブ設定が必要なのは、承認者を上書きする、フィルターを追加する、または発信元チャットへの配信を選択する場合だけです:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -876,32 +898,32 @@ Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人
|
||||
}
|
||||
```
|
||||
|
||||
共有 `approvals.exec` 転送は別です。Exec 承認プロンプトを他のチャットや明示的な帯域外ターゲットにもルーティングする必要がある場合にのみ使います。共有 `approvals.plugin` 転送も別です。Slack ネイティブボタンは、それらのリクエストがすでに Slack に届いている場合、引き続き Plugin 承認を解決できます。
|
||||
共有 `approvals.exec` 転送は別物です。Exec 承認プロンプトを他のチャットまたは明示的な帯域外ターゲットにもルーティングする必要がある場合にだけ使ってください。共有 `approvals.plugin` 転送も別物です。Slack ネイティブボタンは、それらのリクエストがすでに Slack に届いている場合、Plugin 承認を引き続き解決できます。
|
||||
|
||||
同じチャット内の `/approve` も、すでにコマンドをサポートしている Slack チャンネルと DM で機能します。承認転送モデル全体については、[Exec 承認](/ja-JP/tools/exec-approvals) を参照してください。
|
||||
同じチャットでの `/approve` も、すでにコマンドをサポートする Slack チャンネルと DM で機能します。承認転送モデル全体については [Exec 承認](/ja-JP/tools/exec-approvals) を参照してください。
|
||||
|
||||
## イベントと運用上の動作
|
||||
## イベントと運用時の動作
|
||||
|
||||
- メッセージの編集/削除はシステムイベントにマッピングされます。
|
||||
- スレッドブロードキャスト（「チャンネルにも送信」スレッド返信）は通常のユーザーメッセージとして処理されます。
|
||||
- スレッドブロードキャスト（「Also send to channel」スレッド返信）は通常のユーザーメッセージとして処理されます。
|
||||
- リアクションの追加/削除イベントはシステムイベントにマッピングされます。
|
||||
- メンバーの参加/退出、チャンネルの作成/名前変更、ピンの追加/削除イベントはシステムイベントにマッピングされます。
|
||||
- `configWrites` が有効な場合、`channel_id_changed` はチャンネル設定キーを移行できます。
|
||||
- チャンネルトピック/目的メタデータは信頼できないコンテキストとして扱われ、ルーティングコンテキストに注入される可能性があります。
|
||||
- チャンネルのトピック/目的メタデータは信頼できないコンテキストとして扱われ、ルーティングコンテキストに注入されることがあります。
|
||||
- スレッド開始メッセージと初期スレッド履歴コンテキストのシードは、該当する場合、設定された送信者許可リストでフィルタリングされます。
|
||||
- ブロックアクションとモーダルインタラクションは、リッチなペイロードフィールドを持つ構造化された `Slack interaction: ...` システムイベントを出力します。
|
||||
- ブロックアクションとモーダルインタラクションは、豊富なペイロードフィールドを持つ構造化された `Slack interaction: ...` システムイベントを出力します:
|
||||
- ブロックアクション: 選択値、ラベル、ピッカー値、`workflow_*` メタデータ
|
||||
- モーダル `view_submission` と `view_closed` イベント。ルーティングされたチャンネルメタデータとフォーム入力を含みます
|
||||
- ルーティングされたチャンネルメタデータとフォーム入力を含むモーダル `view_submission` および `view_closed` イベント
|
||||
|
||||
## 設定リファレンス
|
||||
|
||||
主要リファレンス: [設定リファレンス - Slack](/ja-JP/gateway/config-channels#slack)。
|
||||
主なリファレンス: [設定リファレンス - Slack](/ja-JP/gateway/config-channels#slack)。
|
||||
|
||||
<Accordion title="重要度の高い Slack フィールド">
|
||||
<Accordion title="シグナルの高い Slack フィールド">
|
||||
|
||||
- モード/認証: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
|
||||
- DM アクセス: `dm.enabled`, `dmPolicy`, `allowFrom`（レガシー: `dm.policy`, `dm.allowFrom`）, `dm.groupEnabled`, `dm.groupChannels`
|
||||
- 互換性トグル: `dangerouslyAllowNameMatching`（緊急回避用。必要な場合を除きオフのままにしてください）
|
||||
- 互換性トグル: `dangerouslyAllowNameMatching`（緊急回避用。必要な場合を除きオフのままにする）
|
||||
- チャンネルアクセス: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
|
||||
- スレッド/履歴: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
- 配信: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress`
|
||||
@ -913,10 +935,10 @@ Slack は、`enabled` が未設定または `"auto"` で、少なくとも 1 人
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="チャンネルで返信がない">
|
||||
次の順に確認してください。
|
||||
次の順に確認してください:
|
||||
|
||||
- `groupPolicy`
|
||||
- チャンネル許可リスト（`channels.slack.channels`） — **キーはチャンネル ID**（`C12345678`）である必要があり、名前（`#channel-name`）ではありません。チャンネルルーティングはデフォルトで ID 優先のため、`groupPolicy: "allowlist"` では名前ベースのキーは暗黙的に失敗します。ID を見つけるには、Slack でチャンネルを右クリック → **リンクをコピー** — URL 末尾の `C...` 値がチャンネル ID です。
|
||||
- チャンネル許可リスト（`channels.slack.channels`）— **キーはチャンネル ID**（`C12345678`）である必要があり、名前（`#channel-name`）ではありません。チャンネルルーティングはデフォルトで ID 優先のため、`groupPolicy: "allowlist"` では名前ベースのキーは静かに失敗します。ID を見つけるには、Slack でチャンネルを右クリック → **Copy link** — URL 末尾の `C...` 値がチャンネル ID です。
|
||||
- `requireMention`
|
||||
- チャンネルごとの `users` 許可リスト
|
||||
|
||||
@ -931,14 +953,12 @@ openclaw doctor
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="DM メッセージが無視される">
|
||||
確認してください。
|
||||
確認してください:
|
||||
|
||||
- `channels.slack.dm.enabled`
|
||||
- `channels.slack.dmPolicy`（またはレガシーの `channels.slack.dm.policy`）
|
||||
- `channels.slack.dmPolicy`（またはレガシー `channels.slack.dm.policy`）
|
||||
- ペアリング承認 / 許可リストエントリ
|
||||
- Slack Assistant DM イベント: `drop message_changed` に言及する詳細ログは、
|
||||
通常、Slack がメッセージメタデータ内に復元可能な人間の送信者を含まない
|
||||
編集済み Assistant スレッドイベントを送信したことを意味します
|
||||
- Slack Assistant DM イベント: `drop message_changed` に言及する詳細ログは、通常、メッセージメタデータ内に復元可能な人間の送信者がない編集済み Assistant スレッドイベントを Slack が送信したことを意味します
|
||||
|
||||
```bash
|
||||
openclaw pairing list slack
|
||||
@ -947,28 +967,28 @@ openclaw pairing list slack
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Socket mode が接続しない">
|
||||
Slack アプリ設定で、ボット + アプリトークンと Socket Mode の有効化を検証してください。
|
||||
Slack アプリ設定で bot + app トークンと Socket Mode の有効化を検証してください。
|
||||
|
||||
`openclaw channels status --probe --json` が `botTokenStatus` または
|
||||
`appTokenStatus: "configured_unavailable"` を表示する場合、その Slack アカウントは
|
||||
`appTokenStatus: "configured_unavailable"` を示す場合、その Slack アカウントは
|
||||
設定されていますが、現在のランタイムが SecretRef に基づく値を解決できませんでした。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="HTTP モードがイベントを受信しない">
|
||||
検証してください。
|
||||
<Accordion title="HTTP mode がイベントを受信しない">
|
||||
検証してください:
|
||||
|
||||
- 署名シークレット
|
||||
- signing secret
|
||||
- Webhook パス
|
||||
- Slack リクエスト URL（Events + Interactivity + Slash Commands）
|
||||
- HTTP アカウントごとに一意の `webhookPath`
|
||||
- Slack Request URL（Events + Interactivity + Slash Commands）
|
||||
- HTTP アカウントごとに一意な `webhookPath`
|
||||
|
||||
アカウントスナップショットに `signingSecretStatus: "configured_unavailable"` が表示される場合、その HTTP アカウントは設定されていますが、現在のランタイムが SecretRef に基づく署名シークレットを解決できませんでした。
|
||||
アカウントスナップショットに `signingSecretStatus: "configured_unavailable"` が表示される場合、その HTTP アカウントは設定されていますが、現在のランタイムが SecretRef に基づく signing secret を解決できませんでした。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="ネイティブ/スラッシュコマンドが発火しない">
|
||||
どちらを意図していたか確認してください。
|
||||
<Accordion title="ネイティブ/スラッシュコマンドが起動しない">
|
||||
意図していたものを確認してください:
|
||||
|
||||
- Slack に登録された一致するスラッシュコマンドを使うネイティブコマンドモード（`channels.slack.commands.native: true`）
|
||||
- または単一スラッシュコマンドモード（`channels.slack.slashCommand.enabled: true`）
|
||||
@ -978,62 +998,62 @@ openclaw pairing list slack
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 添付ファイルのビジョンリファレンス
|
||||
## 添付ファイルの vision リファレンス
|
||||
|
||||
Slack ファイルのダウンロードに成功し、サイズ制限が許す場合、Slack はダウンロード済みメディアをエージェントターンに添付できます。画像ファイルはメディア理解パス経由で渡すことも、ビジョン対応の返信モデルへ直接渡すこともできます。他のファイルは、画像入力として扱われるのではなく、ダウンロード可能なファイルコンテキストとして保持されます。
|
||||
Slack ファイルのダウンロードが成功しサイズ制限が許す場合、Slack はダウンロード済みメディアをエージェントターンに添付できます。画像ファイルはメディア理解パスを通すか、vision 対応の返信モデルへ直接渡すことができます。他のファイルは画像入力として扱われるのではなく、ダウンロード可能なファイルコンテキストとして保持されます。
|
||||
|
||||
### サポートされるメディアタイプ
|
||||
|
||||
| メディア種別 | ソース | 現在の動作 | 注記 |
|
||||
| メディアタイプ | ソース | 現在の動作 | 注記 |
|
||||
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| JPEG / PNG / GIF / WebP 画像 | Slack ファイル URL | ダウンロードされ、ビジョン対応の処理用にターンへ添付される | ファイルごとの上限: `channels.slack.mediaMaxMb` (デフォルト 20 MB) |
|
||||
| PDF ファイル | Slack ファイル URL | ダウンロードされ、`download-file` や `pdf` などのツール向けにファイルコンテキストとして公開される | Slack インバウンドは PDF を画像ビジョン入力へ自動変換しない |
|
||||
| その他のファイル | Slack ファイル URL | 可能な場合はダウンロードされ、ファイルコンテキストとして公開される | バイナリファイルは画像入力として扱われない |
|
||||
| スレッド返信 | スレッド開始メッセージのファイル | 返信に直接メディアがない場合、ルートメッセージのファイルをコンテキストとして取り込める | ファイルのみの開始メッセージでは添付プレースホルダーを使用する |
|
||||
| 複数画像メッセージ | 複数の Slack ファイル | 各ファイルが個別に評価される | Slack の処理は 1 メッセージあたり 8 ファイルに制限される |
|
||||
| JPEG / PNG / GIF / WebP 画像 | Slack ファイル URL | ダウンロードされ、ビジョン対応の処理向けにターンへ添付されます | ファイルごとの上限: `channels.slack.mediaMaxMb`（デフォルト 20 MB） |
|
||||
| PDF ファイル | Slack ファイル URL | ダウンロードされ、`download-file` や `pdf` などのツール向けのファイルコンテキストとして公開されます | Slack インバウンドは PDF を画像ビジョン入力へ自動変換しません |
|
||||
| その他のファイル | Slack ファイル URL | 可能な場合はダウンロードされ、ファイルコンテキストとして公開されます | バイナリファイルは画像入力として扱われません |
|
||||
| スレッド返信 | スレッド開始ファイル | 返信に直接メディアがない場合、ルートメッセージのファイルをコンテキストとしてハイドレートできます | ファイルのみの開始メッセージは添付プレースホルダーを使用します |
|
||||
| 複数画像メッセージ | 複数の Slack ファイル | 各ファイルは独立して評価されます | Slack 処理はメッセージごとに最大 8 ファイルまでに制限されます |
|
||||
|
||||
### インバウンドパイプライン
|
||||
|
||||
ファイル添付を含む Slack メッセージが到着した場合:
|
||||
ファイル添付を含む Slack メッセージが届いた場合:
|
||||
|
||||
1. OpenClaw は bot トークン (`xoxb-...`) を使用して Slack のプライベート URL からファイルをダウンロードする。
|
||||
2. 成功すると、ファイルはメディアストアに書き込まれる。
|
||||
3. ダウンロードされたメディアパスとコンテンツタイプがインバウンドコンテキストに追加される。
|
||||
4. 画像対応のモデル/ツールパスは、そのコンテキストの画像添付を使用できる。
|
||||
5. 非画像ファイルは、それを処理できるツール向けにファイルメタデータまたはメディア参照として引き続き利用できる。
|
||||
1. OpenClaw は bot トークン（`xoxb-...`）を使用して、Slack のプライベート URL からファイルをダウンロードします。
|
||||
2. 成功すると、ファイルはメディアストアに書き込まれます。
|
||||
3. ダウンロードされたメディアパスとコンテンツタイプがインバウンドコンテキストに追加されます。
|
||||
4. 画像対応のモデル/ツールパスは、そのコンテキストの画像添付を使用できます。
|
||||
5. 画像以外のファイルは、それらを処理できるツール向けに、ファイルメタデータまたはメディア参照として引き続き利用できます。
|
||||
|
||||
### スレッドルート添付の継承
|
||||
|
||||
メッセージがスレッド内に到着した場合 (`thread_ts` の親を持つ):
|
||||
メッセージがスレッド内に届いた場合（`thread_ts` 親を持つ場合）:
|
||||
|
||||
- 返信自体に直接メディアがなく、含まれるルートメッセージにファイルがある場合、Slack はルートファイルをスレッド開始コンテキストとして取り込める。
|
||||
- 直接の返信添付は、ルートメッセージの添付より優先される。
|
||||
- ファイルのみでテキストがないルートメッセージは、フォールバックがそのファイルを引き続き含められるように、添付プレースホルダーで表される。
|
||||
- 返信自体に直接メディアがなく、含まれているルートメッセージにファイルがある場合、Slack はルートファイルをスレッド開始コンテキストとしてハイドレートできます。
|
||||
- 直接の返信添付は、ルートメッセージ添付より優先されます。
|
||||
- ファイルのみでテキストのないルートメッセージは、フォールバックがそのファイルを引き続き含められるように、添付プレースホルダーで表されます。
|
||||
|
||||
### 複数添付の処理
|
||||
|
||||
1 つの Slack メッセージに複数のファイル添付が含まれる場合:
|
||||
|
||||
- 各添付はメディアパイプラインを通じて個別に処理される。
|
||||
- ダウンロードされたメディア参照はメッセージコンテキストに集約される。
|
||||
- 処理順序はイベントペイロード内の Slack のファイル順に従う。
|
||||
- 1 つの添付のダウンロードに失敗しても、他の添付はブロックされない。
|
||||
- 各添付はメディアパイプラインを通じて独立して処理されます。
|
||||
- ダウンロードされたメディア参照は、メッセージコンテキストに集約されます。
|
||||
- 処理順序は、イベントペイロード内の Slack のファイル順序に従います。
|
||||
- 1 つの添付のダウンロード失敗は、他の添付をブロックしません。
|
||||
|
||||
### サイズ、ダウンロード、モデルの制限
|
||||
|
||||
- **サイズ上限**: デフォルトは 1 ファイルあたり 20 MB。`channels.slack.mediaMaxMb` で設定可能。
|
||||
- **ダウンロード失敗**: Slack が提供できないファイル、期限切れ URL、アクセス不能なファイル、サイズ超過のファイル、Slack 認証/ログイン HTML レスポンスは、未対応形式として報告されるのではなくスキップされる。
|
||||
- **ビジョンモデル**: 画像解析は、ビジョンをサポートしている場合はアクティブな返信モデルを使用し、または `agents.defaults.imageModel` で設定された画像モデルを使用する。
|
||||
- **サイズ上限**: デフォルトはファイルごとに 20 MB。`channels.slack.mediaMaxMb` で設定できます。
|
||||
- **ダウンロード失敗**: Slack が配信できないファイル、期限切れ URL、アクセス不能なファイル、サイズ超過ファイル、Slack の認証/ログイン HTML レスポンスは、未対応形式として報告されるのではなくスキップされます。
|
||||
- **ビジョンモデル**: 画像分析は、アクティブな返信モデルがビジョンをサポートする場合はそれを使用し、それ以外の場合は `agents.defaults.imageModel` に設定された画像モデルを使用します。
|
||||
|
||||
### 既知の制限
|
||||
|
||||
| シナリオ | 現在の動作 | 回避策 |
|
||||
| シナリオ | 現在の動作 | 回避策 |
|
||||
| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| 期限切れの Slack ファイル URL | ファイルはスキップされ、エラーは表示されない | Slack でファイルを再アップロードする |
|
||||
| ビジョンモデルが設定されていない | 画像添付はメディア参照として保存されるが、画像として解析されない | `agents.defaults.imageModel` を設定するか、ビジョン対応の返信モデルを使用する |
|
||||
| 非常に大きな画像 (デフォルトで > 20 MB) | サイズ上限によりスキップされる | Slack が許可する場合は `channels.slack.mediaMaxMb` を増やす |
|
||||
| 転送/共有された添付 | テキストおよび Slack ホストの画像/ファイルメディアはベストエフォート | OpenClaw スレッドで直接再共有する |
|
||||
| PDF 添付 | ファイル/メディアコンテキストとして保存され、画像ビジョンへ自動的にはルーティングされない | ファイルメタデータには `download-file` を使用し、PDF 解析には `pdf` ツールを使用する |
|
||||
| 期限切れの Slack ファイル URL | ファイルはスキップされ、エラーは表示されません | Slack でファイルを再アップロードします |
|
||||
| ビジョンモデルが設定されていない | 画像添付はメディア参照として保存されますが、画像として分析されません | `agents.defaults.imageModel` を設定するか、ビジョン対応の返信モデルを使用します |
|
||||
| 非常に大きい画像（デフォルトでは 20 MB 超） | サイズ上限によりスキップされます | Slack が許可する場合は `channels.slack.mediaMaxMb` を増やします |
|
||||
| 転送/共有された添付 | テキストと Slack ホストの画像/ファイルメディアはベストエフォートです | OpenClaw スレッドで直接再共有します |
|
||||
| PDF 添付 | ファイル/メディアコンテキストとして保存され、画像ビジョン経由では自動的にルーティングされません | ファイルメタデータには `download-file` を使用し、PDF 分析には `pdf` ツールを使用します |
|
||||
|
||||
### 関連ドキュメント
|
||||
|
||||
@ -1046,22 +1066,22 @@ Slack ファイルのダウンロードに成功し、サイズ制限が許す
|
||||
## 関連
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Pairing" icon="link" href="/ja-JP/channels/pairing">
|
||||
Slack ユーザーを Gateway にペアリングする。
|
||||
<Card title="ペアリング" icon="link" href="/ja-JP/channels/pairing">
|
||||
Slack ユーザーを Gateway にペアリングします。
|
||||
</Card>
|
||||
<Card title="Groups" icon="users" href="/ja-JP/channels/groups">
|
||||
チャンネルおよびグループ DM の動作。
|
||||
<Card title="グループ" icon="users" href="/ja-JP/channels/groups">
|
||||
チャネルとグループ DM の動作。
|
||||
</Card>
|
||||
<Card title="Channel routing" icon="route" href="/ja-JP/channels/channel-routing">
|
||||
インバウンドメッセージをエージェントへルーティングする。
|
||||
<Card title="チャネルルーティング" icon="route" href="/ja-JP/channels/channel-routing">
|
||||
インバウンドメッセージをエージェントへルーティングします。
|
||||
</Card>
|
||||
<Card title="Security" icon="shield" href="/ja-JP/gateway/security">
|
||||
脅威モデルと強化。
|
||||
<Card title="セキュリティ" icon="shield" href="/ja-JP/gateway/security">
|
||||
脅威モデルと堅牢化。
|
||||
</Card>
|
||||
<Card title="Configuration" icon="sliders" href="/ja-JP/gateway/configuration">
|
||||
設定のレイアウトと優先順位。
|
||||
<Card title="設定" icon="sliders" href="/ja-JP/gateway/configuration">
|
||||
設定レイアウトと優先順位。
|
||||
</Card>
|
||||
<Card title="Slash commands" icon="terminal" href="/ja-JP/tools/slash-commands">
|
||||
<Card title="スラッシュコマンド" icon="terminal" href="/ja-JP/tools/slash-commands">
|
||||
コマンドカタログと動作。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -4,33 +4,33 @@ read_when:
|
||||
summary: Telegram ボットのサポート状況、機能、設定
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:27:13Z"
|
||||
generated_at: "2026-05-04T07:02:50Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 528ace9dae29eda22f98cc1436ec16146eb9d83edc73aa6db1ab8283f4f873c0
|
||||
source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
本番運用に対応し、grammY 経由の bot DM とグループで利用できます。デフォルトのモードはロングポーリングです。webhook モードは任意です。
|
||||
grammY 経由のボット DM とグループで本番環境対応です。ロングポーリングが既定のモードです。Webhook モードは任意です。
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="ペアリング" icon="link" href="/ja-JP/channels/pairing">
|
||||
Telegram のデフォルト DM ポリシーはペアリングです。
|
||||
Telegram の既定の DM ポリシーはペアリングです。
|
||||
</Card>
|
||||
<Card title="チャンネルのトラブルシューティング" icon="wrench" href="/ja-JP/channels/troubleshooting">
|
||||
チャンネル横断の診断と修復プレイブック。
|
||||
<Card title="チャネルのトラブルシューティング" icon="wrench" href="/ja-JP/channels/troubleshooting">
|
||||
チャネル横断の診断と修復プレイブックです。
|
||||
</Card>
|
||||
<Card title="Gateway 設定" icon="settings" href="/ja-JP/gateway/configuration">
|
||||
完全なチャンネル設定パターンと例。
|
||||
完全なチャネル設定パターンと例です。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## クイックセットアップ
|
||||
|
||||
<Steps>
|
||||
<Step title="BotFather で bot トークンを作成する">
|
||||
Telegram を開き、**@BotFather** とチャットします（ハンドルが正確に `@BotFather` であることを確認してください）。
|
||||
<Step title="BotFather でボットトークンを作成する">
|
||||
Telegram を開いて **@BotFather** とチャットします（ハンドルが正確に `@BotFather` であることを確認してください）。
|
||||
|
||||
`/newbot` を実行し、プロンプトに従って、トークンを保存します。
|
||||
|
||||
@ -51,12 +51,12 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
env フォールバック: `TELEGRAM_BOT_TOKEN=...`（デフォルトアカウントのみ）。
|
||||
Telegram は `openclaw channels login telegram` を使用**しません**。config/env でトークンを設定してから、gateway を起動してください。
|
||||
環境変数フォールバック: `TELEGRAM_BOT_TOKEN=...`（既定アカウントのみ）。
|
||||
Telegram は `openclaw channels login telegram` を使用しません。設定/env でトークンを構成してから、Gateway を起動してください。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Gateway を起動して最初の DM を承認する">
|
||||
<Step title="Gateway を起動し、最初の DM を承認する">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -68,81 +68,81 @@ openclaw pairing approve telegram <CODE>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="bot をグループに追加する">
|
||||
bot をグループに追加してから、アクセスモデルに合わせて `channels.telegram.groups` と `groupPolicy` を設定します。
|
||||
<Step title="ボットをグループに追加する">
|
||||
ボットをグループに追加してから、アクセスモデルに合わせて `channels.telegram.groups` と `groupPolicy` を設定します。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
トークンの解決順序はアカウントを考慮します。実際には、config 値が env フォールバックより優先され、`TELEGRAM_BOT_TOKEN` はデフォルトアカウントにのみ適用されます。
|
||||
トークン解決順序はアカウントを考慮します。実際には、設定値が環境変数フォールバックより優先され、`TELEGRAM_BOT_TOKEN` は既定アカウントにのみ適用されます。
|
||||
</Note>
|
||||
|
||||
## Telegram 側の設定
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="プライバシーモードとグループの可視性">
|
||||
Telegram bot はデフォルトで **プライバシーモード** になっており、受信できるグループメッセージが制限されます。
|
||||
Telegram ボットは既定で **プライバシーモード** になっており、受信するグループメッセージが制限されます。
|
||||
|
||||
bot がすべてのグループメッセージを見る必要がある場合は、次のいずれかを行います。
|
||||
ボットがすべてのグループメッセージを確認する必要がある場合は、次のいずれかを行います。
|
||||
|
||||
- `/setprivacy` でプライバシーモードを無効化する
|
||||
- bot をグループ管理者にする
|
||||
- `/setprivacy` でプライバシーモードを無効にする、または
|
||||
- ボットをグループ管理者にする。
|
||||
|
||||
プライバシーモードを切り替える場合は、各グループで bot を削除してから再追加し、Telegram に変更を適用させます。
|
||||
プライバシーモードを切り替えるときは、Telegram が変更を適用するように、各グループでボットを削除してから再追加してください。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="グループ権限">
|
||||
管理者ステータスは Telegram のグループ設定で制御されます。
|
||||
|
||||
管理者 bot はすべてのグループメッセージを受信します。これは常時有効なグループ動作に便利です。
|
||||
管理者ボットはすべてのグループメッセージを受信します。これは、常時有効なグループ動作に役立ちます。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="便利な BotFather の切り替え">
|
||||
<Accordion title="役立つ BotFather の切り替え設定">
|
||||
|
||||
- `/setjoingroups` でグループへの追加を許可/拒否する
|
||||
- `/setprivacy` でグループの可視性動作を設定する
|
||||
- グループ追加を許可/拒否するには `/setjoingroups`
|
||||
- グループ可視性の動作には `/setprivacy`
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## アクセス制御と有効化
|
||||
## アクセス制御とアクティベーション
|
||||
|
||||
<Tabs>
|
||||
<Tab title="DM ポリシー">
|
||||
`channels.telegram.dmPolicy` はダイレクトメッセージのアクセスを制御します。
|
||||
`channels.telegram.dmPolicy` はダイレクトメッセージアクセスを制御します。
|
||||
|
||||
- `pairing`（デフォルト）
|
||||
- `pairing`（既定）
|
||||
- `allowlist`（`allowFrom` に少なくとも 1 つの送信者 ID が必要）
|
||||
- `open`（`allowFrom` に `"*"` を含める必要がある）
|
||||
- `open`（`allowFrom` に `"*"` を含める必要があります）
|
||||
- `disabled`
|
||||
|
||||
`allowFrom: ["*"]` と組み合わせた `dmPolicy: "open"` は、bot のユーザー名を見つけた、または推測した任意の Telegram アカウントが bot にコマンドを送れるようにします。意図的に公開する bot で、ツールを厳しく制限している場合にのみ使用してください。単一所有者の bot では、数値ユーザー ID を使った `allowlist` を使用してください。
|
||||
`dmPolicy: "open"` と `allowFrom: ["*"]` を組み合わせると、ボットユーザー名を見つけた、または推測した任意の Telegram アカウントがボットにコマンドを送信できます。厳しく制限されたツールを持つ意図的に公開されたボットにのみ使用してください。単一所有者のボットでは、数値ユーザー ID を指定した `allowlist` を使用するべきです。
|
||||
|
||||
`channels.telegram.allowFrom` は数値の Telegram ユーザー ID を受け付けます。`telegram:` / `tg:` プレフィックスは受け付けられ、正規化されます。
|
||||
複数アカウント config では、制限的なトップレベルの `channels.telegram.allowFrom` は安全境界として扱われます。アカウントレベルの `allowFrom: ["*"]` エントリは、マージ後の有効なアカウント allowlist に明示的なワイルドカードがまだ含まれていない限り、そのアカウントを公開しません。
|
||||
空の `allowFrom` と組み合わせた `dmPolicy: "allowlist"` はすべての DM をブロックし、config 検証で拒否されます。
|
||||
マルチアカウント設定では、制限的なトップレベルの `channels.telegram.allowFrom` は安全境界として扱われます。アカウントレベルの `allowFrom: ["*"]` エントリは、マージ後の有効なアカウント許可リストに明示的なワイルドカードがまだ含まれていない限り、そのアカウントを公開状態にはしません。
|
||||
空の `allowFrom` を持つ `dmPolicy: "allowlist"` はすべての DM をブロックし、設定検証で拒否されます。
|
||||
セットアップでは数値ユーザー ID のみを求めます。
|
||||
アップグレード後の config に `@username` allowlist エントリが含まれる場合は、`openclaw doctor --fix` を実行して解決してください（ベストエフォート。Telegram bot トークンが必要です）。
|
||||
以前にペアリングストアの allowlist ファイルに依存していた場合、`openclaw doctor --fix` は allowlist フローで `channels.telegram.allowFrom` にエントリを復元できます（たとえば `dmPolicy: "allowlist"` に明示的な ID がまだない場合）。
|
||||
アップグレード後、設定に `@username` の許可リストエントリが含まれている場合は、`openclaw doctor --fix` を実行して解決してください（ベストエフォート。Telegram ボットトークンが必要です）。
|
||||
以前にペアリングストアの許可リストファイルに依存していた場合、`openclaw doctor --fix` は許可リストフロー内でエントリを `channels.telegram.allowFrom` に復元できます（たとえば、`dmPolicy: "allowlist"` に明示的な ID がまだない場合）。
|
||||
|
||||
単一所有者の bot では、以前のペアリング承認に依存する代わりに、明示的な数値 `allowFrom` ID を指定した `dmPolicy: "allowlist"` を優先し、アクセスポリシーを config 内で永続化してください。
|
||||
単一所有者のボットでは、以前のペアリング承認に依存する代わりに、明示的な数値 `allowFrom` ID を指定した `dmPolicy: "allowlist"` を推奨します。これにより、アクセスポリシーを設定内で永続化できます。
|
||||
|
||||
一般的な誤解: DM ペアリング承認は「この送信者はどこでも承認されている」という意味ではありません。
|
||||
ペアリングは DM アクセスを付与します。コマンド所有者がまだ存在しない場合、最初に承認されたペアリングは `commands.ownerAllowFrom` も設定し、所有者専用コマンドと exec 承認に明示的な操作者アカウントを持たせます。
|
||||
グループ送信者の承認は、引き続き明示的な config allowlist から取得されます。
|
||||
「一度承認されれば DM とグループコマンドの両方が動作する」ようにしたい場合は、数値の Telegram ユーザー ID を `channels.telegram.allowFrom` に入れてください。所有者専用コマンドについては、`commands.ownerAllowFrom` に `telegram:<your user id>` が含まれていることを確認してください。
|
||||
よくある混同: DM のペアリング承認は「この送信者がどこでも認可されている」という意味ではありません。
|
||||
ペアリングは DM アクセスを付与します。コマンド所有者がまだ存在しない場合、最初に承認されたペアリングは `commands.ownerAllowFrom` も設定し、所有者専用コマンドと exec 承認に明示的なオペレーターアカウントを持たせます。
|
||||
グループ送信者の認可は、引き続き明示的な設定許可リストから行われます。
|
||||
「一度認可されれば、DM とグループコマンドの両方が機能する」ようにしたい場合は、数値の Telegram ユーザー ID を `channels.telegram.allowFrom` に入れてください。所有者専用コマンドでは、`commands.ownerAllowFrom` に `telegram:<your user id>` が含まれていることを確認してください。
|
||||
|
||||
### Telegram ユーザー ID を見つける
|
||||
### Telegram ユーザー ID の確認
|
||||
|
||||
より安全な方法（サードパーティ bot なし）:
|
||||
より安全な方法（サードパーティボットなし）:
|
||||
|
||||
1. 自分の bot に DM します。
|
||||
1. 自分のボットに DM します。
|
||||
2. `openclaw logs --follow` を実行します。
|
||||
3. `from.id` を読み取ります。
|
||||
|
||||
公式 Bot API メソッド:
|
||||
公式 Bot API の方法:
|
||||
|
||||
```bash
|
||||
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
@ -152,31 +152,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="グループポリシーと allowlist">
|
||||
2 つの制御が組み合わせて適用されます。
|
||||
<Tab title="グループポリシーと許可リスト">
|
||||
2 つの制御が一緒に適用されます。
|
||||
|
||||
1. **許可されるグループ**（`channels.telegram.groups`）
|
||||
- `groups` config なし:
|
||||
- `groupPolicy: "open"` の場合: どのグループもグループ ID チェックを通過できる
|
||||
- `groupPolicy: "allowlist"`（デフォルト）の場合: `groups` エントリ（または `"*"`）を追加するまでグループはブロックされる
|
||||
- `groups` が設定されている場合: allowlist として動作する（明示的な ID または `"*"`）
|
||||
- `groups` 設定なし:
|
||||
- `groupPolicy: "open"` の場合: 任意のグループがグループ ID チェックを通過できます
|
||||
- `groupPolicy: "allowlist"`（既定）の場合: `groups` エントリ（または `"*"`）を追加するまでグループはブロックされます
|
||||
- `groups` が設定されている場合: 許可リストとして動作します（明示的な ID または `"*"`）
|
||||
|
||||
2. **グループ内で許可される送信者**（`channels.telegram.groupPolicy`）
|
||||
- `open`
|
||||
- `allowlist`（デフォルト）
|
||||
- `allowlist`（既定）
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` はグループ送信者フィルタリングに使用されます。設定されていない場合、Telegram は `allowFrom` にフォールバックします。
|
||||
`groupAllowFrom` エントリは数値の Telegram ユーザー ID にしてください（`telegram:` / `tg:` プレフィックスは正規化されます）。
|
||||
`groupAllowFrom` はグループ送信者のフィルタリングに使用されます。設定されていない場合、Telegram は `allowFrom` にフォールバックします。
|
||||
`groupAllowFrom` エントリは数値の Telegram ユーザー ID である必要があります（`telegram:` / `tg:` プレフィックスは正規化されます）。
|
||||
Telegram グループまたはスーパーグループのチャット ID を `groupAllowFrom` に入れないでください。負のチャット ID は `channels.telegram.groups` に属します。
|
||||
数値でないエントリは送信者承認では無視されます。
|
||||
セキュリティ境界（`2026.2.25+`）: グループ送信者認証は DM ペアリングストア承認を継承**しません**。
|
||||
数値でないエントリは送信者認可では無視されます。
|
||||
セキュリティ境界（`2026.2.25+`）: グループ送信者の認可は DM ペアリングストア承認を継承しません。
|
||||
ペアリングは DM 専用のままです。グループでは、`groupAllowFrom` またはグループごと/トピックごとの `allowFrom` を設定してください。
|
||||
`groupAllowFrom` が未設定の場合、Telegram はペアリングストアではなく config の `allowFrom` にフォールバックします。
|
||||
単一所有者の bot 向けの実用的なパターン: 自分のユーザー ID を `channels.telegram.allowFrom` に設定し、`groupAllowFrom` は未設定のままにして、対象グループを `channels.telegram.groups` で許可します。
|
||||
ランタイム注記: `channels.telegram` が完全に存在しない場合、`channels.defaults.groupPolicy` が明示的に設定されていない限り、ランタイムは fail-closed の `groupPolicy="allowlist"` をデフォルトにします。
|
||||
`groupAllowFrom` が未設定の場合、Telegram はペアリングストアではなく、設定の `allowFrom` にフォールバックします。
|
||||
単一所有者のボットでの実用的なパターン: 自分のユーザー ID を `channels.telegram.allowFrom` に設定し、`groupAllowFrom` は未設定のままにして、対象グループを `channels.telegram.groups` で許可します。
|
||||
ランタイムメモ: `channels.telegram` が完全に存在しない場合、`channels.defaults.groupPolicy` が明示的に設定されていない限り、ランタイムはフェイルクローズの `groupPolicy="allowlist"` を既定にします。
|
||||
|
||||
例: 1 つの特定グループ内の任意のメンバーを許可する:
|
||||
例: 特定の 1 つのグループ内の任意のメンバーを許可する:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
例: 1 つの特定グループ内で特定ユーザーのみを許可する:
|
||||
例: 特定の 1 つのグループ内で特定のユーザーだけを許可する:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -211,22 +211,22 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
<Warning>
|
||||
よくある間違い: `groupAllowFrom` は Telegram グループの allowlist ではありません。
|
||||
よくある間違い: `groupAllowFrom` は Telegram グループの許可リストではありません。
|
||||
|
||||
- `-1001234567890` のような負の Telegram グループまたはスーパーグループのチャット ID は `channels.telegram.groups` に入れます。
|
||||
- 許可されたグループ内でどの人が bot を起動できるかを制限したい場合は、`8734062810` のような Telegram ユーザー ID を `groupAllowFrom` に入れます。
|
||||
- 許可されたグループの任意のメンバーが bot と会話できるようにしたい場合にのみ、`groupAllowFrom: ["*"]` を使用します。
|
||||
- 許可されたグループ内でボットをトリガーできる人を制限したい場合は、`8734062810` のような Telegram ユーザー ID を `groupAllowFrom` に入れます。
|
||||
- 許可されたグループの任意のメンバーがボットと会話できるようにしたい場合にのみ、`groupAllowFrom: ["*"]` を使用します。
|
||||
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="メンション動作">
|
||||
グループ返信はデフォルトでメンションが必要です。
|
||||
グループ返信には既定でメンションが必要です。
|
||||
|
||||
メンションは次から取得できます。
|
||||
メンションは次のいずれかです。
|
||||
|
||||
- ネイティブの `@botusername` メンション
|
||||
- ネイティブの `@botusername` メンション、または
|
||||
- 次のメンションパターン:
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
@ -236,9 +236,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
これらはセッション状態のみを更新します。永続化には config を使用してください。
|
||||
これらはセッション状態のみを更新します。永続化には設定を使用してください。
|
||||
|
||||
永続 config の例:
|
||||
永続設定の例:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -252,26 +252,26 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
グループチャット ID を取得する:
|
||||
グループチャット ID の取得:
|
||||
|
||||
- グループメッセージを `@userinfobot` / `@getidsbot` に転送する
|
||||
- または `openclaw logs --follow` から `chat.id` を読み取る
|
||||
- または Bot API の `getUpdates` を調べる
|
||||
- または Bot API の `getUpdates` を確認する
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## ランタイム動作
|
||||
|
||||
- Telegram は gateway プロセスが所有します。
|
||||
- ルーティングは決定的です。Telegram の受信は Telegram に返信されます（モデルがチャンネルを選ぶことはありません）。
|
||||
- 受信メッセージは、返信メタデータとメディアプレースホルダーを含む共有チャンネルエンベロープに正規化されます。
|
||||
- グループセッションはグループ ID で分離されます。フォーラムトピックは `:topic:<threadId>` を追加してトピックを分離します。
|
||||
- DM メッセージは `message_thread_id` を含むことができます。OpenClaw は返信のためにスレッド ID を保持しますが、デフォルトでは DM をフラットなセッションに保ちます。意図的に DM トピックのセッション分離をしたい場合は、`channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct.<chatId>.threadReplies: "inbound"`、`requireTopic: true`、または一致するトピック config を設定してください。
|
||||
- ロングポーリングは grammY runner を使用し、チャットごと/スレッドごとの順序付けを行います。全体の runner sink 並行実行数は `agents.defaults.maxConcurrent` を使用します。
|
||||
- ロングポーリングは各 gateway プロセス内で保護され、同時に 1 つのアクティブな poller だけが bot トークンを使用できます。それでも `getUpdates` 409 競合が表示される場合は、別の OpenClaw gateway、スクリプト、または外部 poller が同じトークンを使用している可能性があります。
|
||||
- ロングポーリングの watchdog 再起動は、デフォルトで 120 秒間 `getUpdates` の liveness が完了しなかった場合にトリガーされます。デプロイメントで長時間実行中の作業中に誤った polling-stall 再起動がまだ発生する場合のみ、`channels.telegram.pollingStallThresholdMs` を増やしてください。値はミリ秒単位で、`30000` から `600000` まで許可されます。アカウントごとのオーバーライドがサポートされています。
|
||||
- Telegram Bot API には既読通知のサポートがありません（`sendReadReceipts` は適用されません）。
|
||||
- Telegram は Gateway プロセスが管理します。
|
||||
- ルーティングは決定論的です。Telegram からの受信は Telegram に返信されます（モデルはチャネルを選びません）。
|
||||
- 受信メッセージは、返信メタデータとメディアプレースホルダーを持つ共有チャネルエンベロープに正規化されます。
|
||||
- グループセッションはグループ ID によって分離されます。フォーラムトピックでは、トピックを分離するために `:topic:<threadId>` が追加されます。
|
||||
- DM メッセージには `message_thread_id` を含めることができます。OpenClaw は返信用にスレッド ID を保持しますが、既定では DM をフラットなセッションのままにします。DM トピックのセッション分離を意図的に有効にしたい場合は、`channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct.<chatId>.threadReplies: "inbound"`、`requireTopic: true`、または一致するトピック設定を構成します。
|
||||
- ロングポーリングは、チャットごと/スレッドごとの順序付けを行う grammY runner を使用します。ランナーシンク全体の同時実行数は `agents.defaults.maxConcurrent` を使用します。
|
||||
- ロングポーリングは各 Gateway プロセス内でガードされるため、一度に 1 つのアクティブなポーラーだけがボットトークンを使用できます。それでも `getUpdates` の 409 競合が表示される場合は、別の OpenClaw Gateway、スクリプト、または外部ポーラーが同じトークンを使用している可能性があります。
|
||||
- ロングポーリングのウォッチドッグ再起動は、既定では完了した `getUpdates` のライブネスが 120 秒間ない場合にトリガーされます。デプロイで長時間実行される作業中に誤ったポーリング停止再起動がまだ発生する場合にのみ、`channels.telegram.pollingStallThresholdMs` を増やしてください。値はミリ秒単位で、`30000` から `600000` まで許可されます。アカウントごとの上書きがサポートされています。
|
||||
- Telegram Bot API には既読通知サポートがありません（`sendReadReceipts` は適用されません）。
|
||||
|
||||
## 機能リファレンス
|
||||
|
||||
@ -284,12 +284,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
要件:
|
||||
|
||||
- `channels.telegram.streaming` は `off | partial | block | progress`（デフォルト: `partial`）
|
||||
- `progress` は 1 つの編集可能なステータス下書きを保持し、最終配信までツール進行状況で更新します
|
||||
- `streaming.preview.toolProgress` は、ツール/進行状況の更新で同じ編集済みプレビューメッセージを再利用するかを制御します（デフォルト: プレビューストリーミングが有効な場合は `true`）
|
||||
- レガシーの `channels.telegram.streamMode` と boolean の `streaming` 値は検出されます。`openclaw doctor --fix` を実行して `channels.telegram.streaming.mode` に移行してください
|
||||
- `channels.telegram.streaming` が `off | partial | block | progress` であること（既定: `partial`）
|
||||
- `progress` は編集可能なステータス下書きを 1 つ保持し、最終配信までツール進捗で更新します
|
||||
- `streaming.preview.toolProgress` は、ツール/進捗更新が同じ編集済みプレビューメッセージを再利用するかどうかを制御します（既定: プレビューストリーミングが有効な場合は `true`）
|
||||
- `streaming.preview.commandText` は、それらのツール進捗行内のコマンド/exec 詳細を制御します: `raw`（既定、リリース済みの動作を保持）または `status`（ツールラベルのみ）
|
||||
- 旧式の `channels.telegram.streamMode` と真偽値の `streaming` 値は検出されます。`openclaw doctor --fix` を実行して `channels.telegram.streaming.mode` に移行してください
|
||||
|
||||
ツール進行状況のプレビュー更新は、ツールの実行中に表示される短いステータス行です。たとえば、コマンド実行、ファイル読み取り、計画更新、パッチ要約などです。Telegram では、`v2026.4.22` 以降のリリース済み OpenClaw の動作に合わせるため、これらはデフォルトで有効です。回答テキスト用の編集済みプレビューは維持しつつ、ツール進行状況の行を非表示にするには、次を設定します。
|
||||
ツール進捗プレビュー更新は、ツール実行中に表示される短いステータス行です。たとえば、コマンド実行、ファイル読み取り、計画更新、パッチ要約などです。Telegram では、`v2026.4.22` 以降でリリースされた OpenClaw の動作に合わせるため、これらが既定で有効です。回答テキスト用の編集済みプレビューは維持しつつ、ツール進捗行を非表示にするには、次を設定します。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -306,25 +307,61 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
`streaming.mode: "off"` は、最終結果のみを配信したい場合にだけ使用します。Telegram のプレビュー編集は無効になり、汎用のツール/進行状況の雑談は単独のステータスメッセージとして送信される代わりに抑制されます。承認プロンプト、メディアペイロード、エラーは引き続き通常の最終配信を通じてルーティングされます。回答プレビュー編集だけを維持し、ツール進行状況のステータス行を非表示にしたい場合は、`streaming.preview.toolProgress: false` を使用します。
|
||||
ツール進捗は表示したまま、コマンド/exec テキストを非表示にするには、次を設定します。
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "partial",
|
||||
"preview": {
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
進行状況ドラフトモードでは、同じコマンドテキストポリシーを `streaming.progress` の下に置きます。
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
最終結果のみの配信が必要な場合にだけ `streaming.mode: "off"` を使用します。Telegram のプレビュー編集は無効になり、汎用的なツールや進行状況の雑談は、独立したステータスメッセージとして送信される代わりに抑制されます。承認プロンプト、メディアペイロード、エラーは引き続き通常の最終配信経路を通ります。回答プレビュー編集だけを維持し、ツール進行状況のステータス行を隠したい場合は `streaming.preview.toolProgress: false` を使用します。
|
||||
|
||||
<Note>
|
||||
Telegram の選択引用返信は例外です。`replyToMode` が `"first"`、`"all"`、または `"batched"` で、受信メッセージに選択された引用テキストが含まれる場合、OpenClaw は回答プレビューを編集する代わりに Telegram のネイティブ引用返信経路で最終回答を送信するため、そのターンでは `streaming.preview.toolProgress` で短いステータス行を表示できません。選択引用テキストのない現在メッセージへの返信では、引き続きプレビューストリーミングが維持されます。ツール進行状況の可視性がネイティブ引用返信より重要な場合は `replyToMode: "off"` を設定するか、このトレードオフを受け入れるために `streaming.preview.toolProgress: false` を設定します。
|
||||
Telegram の選択引用返信は例外です。`replyToMode` が `"first"`、`"all"`、または `"batched"` で、受信メッセージに選択された引用テキストが含まれている場合、OpenClaw は回答プレビューを編集する代わりに、Telegram のネイティブな引用返信経路で最終回答を送信します。そのため、そのターンでは `streaming.preview.toolProgress` で短いステータス行を表示できません。選択引用テキストのない現在メッセージへの返信では、引き続きプレビューストリーミングが維持されます。ツール進行状況の可視性がネイティブ引用返信より重要な場合は `replyToMode: "off"` を設定するか、トレードオフを明示的に受け入れるために `streaming.preview.toolProgress: false` を設定します。
|
||||
</Note>
|
||||
|
||||
テキストのみの返信の場合:
|
||||
|
||||
- 短い DM/グループ/トピックのプレビュー: OpenClaw は同じプレビューメッセージを維持し、プレビューが表示された後に可視の非プレビューメッセージが送信されていない限り、最終編集をその場で実行します
|
||||
- 可視の非プレビュー出力が続くプレビュー: OpenClaw は完了した返信を新しい最終メッセージとして送信し、古いプレビューをクリーンアップするため、最終回答は中間出力の後に表示されます
|
||||
- 短いDM/グループ/トピックのプレビュー: プレビューが表示された後に可視の非プレビューメッセージが送信されていない限り、OpenClaw は同じプレビューメッセージを保持し、その場で最終編集を行います
|
||||
- プレビューの後に可視の非プレビュー出力が続く場合: OpenClaw は完了した返信を新しい最終メッセージとして送信し、古いプレビューをクリーンアップするため、最終回答は中間出力の後に表示されます
|
||||
- 約1分より古いプレビュー: OpenClaw は完了した返信を新しい最終メッセージとして送信してからプレビューをクリーンアップするため、Telegram の可視タイムスタンプはプレビュー作成時刻ではなく完了時刻を反映します
|
||||
|
||||
複雑な返信（たとえばメディアペイロード）の場合、OpenClaw は通常の最終配信にフォールバックし、その後プレビューメッセージをクリーンアップします。
|
||||
|
||||
プレビューストリーミングはブロックストリーミングとは別です。Telegram でブロックストリーミングが明示的に有効になっている場合、OpenClaw は二重ストリーミングを避けるためにプレビューストリームをスキップします。
|
||||
プレビューストリーミングはブロックストリーミングとは別です。Telegram でブロックストリーミングが明示的に有効化されている場合、OpenClaw は二重ストリーミングを避けるためにプレビューストリームをスキップします。
|
||||
|
||||
Telegram 専用の推論ストリーム:
|
||||
|
||||
- `/reasoning stream` は生成中に推論をライブプレビューへ送信します
|
||||
- 推論プレビューは最終配信後に削除されます。推論を表示したままにする必要がある場合は `/reasoning on` を使用します
|
||||
- 最終回答は推論テキストなしで送信されます
|
||||
|
||||
</Accordion>
|
||||
@ -332,22 +369,22 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="書式設定とHTMLフォールバック">
|
||||
送信テキストは Telegram `parse_mode: "HTML"` を使用します。
|
||||
|
||||
- Markdown 風のテキストは Telegram で安全な HTML にレンダリングされます。
|
||||
- 生のモデル HTML は、Telegram の解析失敗を減らすためにエスケープされます。
|
||||
- Telegram が解析済み HTML を拒否した場合、OpenClaw はプレーンテキストとして再試行します。
|
||||
- Markdown 風のテキストは Telegram で安全なHTMLにレンダリングされます。
|
||||
- 生のモデルHTMLは、Telegram の解析失敗を減らすためにエスケープされます。
|
||||
- Telegram が解析済みHTMLを拒否した場合、OpenClaw はプレーンテキストで再試行します。
|
||||
|
||||
リンクプレビューはデフォルトで有効で、`channels.telegram.linkPreview: false` で無効にできます。
|
||||
リンクプレビューはデフォルトで有効で、`channels.telegram.linkPreview: false` で無効化できます。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="ネイティブコマンドとカスタムコマンド">
|
||||
Telegram コマンドメニュー登録は、起動時に `setMyCommands` で処理されます。
|
||||
Telegram コマンドメニュー登録は起動時に `setMyCommands` で処理されます。
|
||||
|
||||
ネイティブコマンドのデフォルト:
|
||||
|
||||
- `commands.native: "auto"` は Telegram のネイティブコマンドを有効にします
|
||||
|
||||
カスタムコマンドメニュー項目を追加します:
|
||||
カスタムコマンドメニュー項目を追加します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -371,17 +408,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
注記:
|
||||
|
||||
- カスタムコマンドはメニュー項目のみです。動作を自動実装するものではありません
|
||||
- カスタムコマンドはメニュー項目のみです。動作を自動実装しません
|
||||
- plugin/skill コマンドは、Telegram メニューに表示されていなくても、入力された場合は引き続き動作できます
|
||||
|
||||
ネイティブコマンドが無効な場合、組み込みコマンドは削除されます。カスタム/plugin コマンドは、設定されていれば引き続き登録される場合があります。
|
||||
ネイティブコマンドが無効な場合、組み込みコマンドは削除されます。設定されていれば、カスタム/plugin コマンドは引き続き登録される場合があります。
|
||||
|
||||
よくあるセットアップ失敗:
|
||||
一般的なセットアップ失敗:
|
||||
|
||||
- `BOT_COMMANDS_TOO_MUCH` を伴う `setMyCommands failed` は、トリミング後も Telegram メニューがまだあふれていることを意味します。plugin/skill/カスタムコマンドを減らすか、`channels.telegram.commands.native` を無効にしてください。
|
||||
- 直接の Bot API curl コマンドは動作するのに、`deleteWebhook`、`deleteMyCommands`、または `setMyCommands` が `404: Not Found` で失敗する場合、`channels.telegram.apiRoot` が完全な `/bot<TOKEN>` エンドポイントに設定されている可能性があります。`apiRoot` は Bot API ルートのみである必要があり、`openclaw doctor --fix` は誤って付いた末尾の `/bot<TOKEN>` を削除します。
|
||||
- `getMe returned 401` は、Telegram が設定済みの bot トークンを拒否したことを意味します。`botToken`、`tokenFile`、または `TELEGRAM_BOT_TOKEN` を現在の BotFather トークンで更新してください。OpenClaw はポーリング前に停止するため、これは Webhook クリーンアップ失敗としては報告されません。
|
||||
- ネットワーク/フェッチエラーを伴う `setMyCommands failed` は、通常 `api.telegram.org` への送信 DNS/HTTPS がブロックされていることを意味します。
|
||||
- `setMyCommands failed` と `BOT_COMMANDS_TOO_MUCH` が表示される場合、トリミング後も Telegram メニューがまだ上限を超えていることを意味します。plugin/skill/カスタムコマンドを減らすか、`channels.telegram.commands.native` を無効化してください。
|
||||
- 直接の Bot API curl コマンドは動作するのに、`deleteWebhook`、`deleteMyCommands`、または `setMyCommands` が `404: Not Found` で失敗する場合、`channels.telegram.apiRoot` が完全な `/bot<TOKEN>` エンドポイントに設定されている可能性があります。`apiRoot` は Bot API ルートだけである必要があり、`openclaw doctor --fix` は誤って末尾に付いた `/bot<TOKEN>` を削除します。
|
||||
- `getMe returned 401` は、Telegram が設定済みのボットトークンを拒否したことを意味します。`botToken`、`tokenFile`、または `TELEGRAM_BOT_TOKEN` を現在の BotFather トークンで更新してください。OpenClaw はポーリング前に停止するため、これは Webhook クリーンアップ失敗としては報告されません。
|
||||
- `setMyCommands failed` とネットワーク/fetch エラーが表示される場合、通常は `api.telegram.org` への送信DNS/HTTPSがブロックされていることを意味します。
|
||||
|
||||
### デバイスペアリングコマンド（`device-pair` plugin）
|
||||
|
||||
@ -389,22 +426,22 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
1. `/pair` はセットアップコードを生成します
|
||||
2. iOS アプリにコードを貼り付けます
|
||||
3. `/pair pending` は保留中のリクエストを一覧表示します（ロール/スコープを含む）
|
||||
3. `/pair pending` は保留中のリクエスト（ロール/スコープを含む）を一覧表示します
|
||||
4. リクエストを承認します:
|
||||
- 明示的な承認には `/pair approve <requestId>`
|
||||
- 保留中のリクエストが1つだけの場合は `/pair approve`
|
||||
- 保留中のリクエストが1件だけの場合は `/pair approve`
|
||||
- 最新のものには `/pair approve latest`
|
||||
|
||||
セットアップコードには短命のブートストラップトークンが含まれます。組み込みのブートストラップ引き渡しでは、プライマリノードトークンは `scopes: []` に維持されます。引き渡された operator トークンは、`operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write` に制限されたままです。ブートストラップのスコープチェックはロール接頭辞付きであるため、その operator 許可リストは operator リクエストのみを満たします。operator 以外のロールでは、引き続き各自のロール接頭辞配下のスコープが必要です。
|
||||
セットアップコードには短命のブートストラップトークンが含まれます。組み込みのブートストラップ引き渡しでは、プライマリノードトークンは `scopes: []` に保たれます。引き渡されたオペレータートークンは `operator.approvals`、`operator.read`、`operator.talk.secrets`、`operator.write` に制限されます。ブートストラップスコープチェックはロール接頭辞付きのため、そのオペレーター許可リストはオペレーターリクエストのみを満たします。非オペレーターロールには、引き続きそれぞれのロール接頭辞配下のスコープが必要です。
|
||||
|
||||
デバイスが変更された認証詳細（たとえばロール/スコープ/公開鍵）で再試行した場合、以前の保留中リクエストは置き換えられ、新しいリクエストでは別の `requestId` が使用されます。承認する前に `/pair pending` を再実行してください。
|
||||
デバイスが変更された認証詳細（たとえばロール/スコープ/公開鍵）で再試行した場合、以前の保留中リクエストは置き換えられ、新しいリクエストでは別の `requestId` が使用されます。承認前に `/pair pending` を再実行してください。
|
||||
|
||||
詳細: [ペアリング](/ja-JP/channels/pairing#pair-via-telegram-recommended-for-ios)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="インラインボタン">
|
||||
インラインキーボードのスコープを設定します:
|
||||
インラインキーボードのスコープを設定します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -469,8 +506,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="エージェントと自動化向けのTelegramメッセージアクション">
|
||||
Telegram ツールアクションには次が含まれます:
|
||||
<Accordion title="エージェントと自動化向けの Telegram メッセージアクション">
|
||||
Telegram ツールアクションには次が含まれます。
|
||||
|
||||
- `sendMessage`（`to`、`content`、任意の `mediaUrl`、`replyToMessageId`、`messageThreadId`）
|
||||
- `react`（`chatId`、`messageId`、`emoji`）
|
||||
@ -478,9 +515,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `editMessage`（`chatId`、`messageId`、`content`）
|
||||
- `createForumTopic`（`chatId`、`name`、任意の `iconColor`、`iconCustomEmojiId`）
|
||||
|
||||
チャネルメッセージアクションは、使いやすいエイリアス（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）を公開します。
|
||||
チャンネルメッセージアクションは使いやすいエイリアス（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）を公開します。
|
||||
|
||||
ゲーティング制御:
|
||||
ゲート制御:
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
@ -488,27 +525,27 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.actions.sticker`（デフォルト: 無効）
|
||||
|
||||
注記: `edit` と `topic-create` は現在デフォルトで有効で、個別の `channels.telegram.actions.*` トグルはありません。
|
||||
ランタイム送信はアクティブな config/secrets スナップショット（起動/リロード）を使用するため、アクションパスは送信ごとにアドホックな SecretRef 再解決を行いません。
|
||||
ランタイム送信はアクティブな設定/シークレットのスナップショット（起動/リロード）を使用するため、アクションパスは送信ごとにアドホックな SecretRef 再解決を行いません。
|
||||
|
||||
リアクション削除のセマンティクス: [/tools/reactions](/ja-JP/tools/reactions)
|
||||
リアクション削除セマンティクス: [/tools/reactions](/ja-JP/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="返信スレッドタグ">
|
||||
Telegram は、生成された出力内の明示的な返信スレッドタグをサポートします:
|
||||
<Accordion title="返信スレッド化タグ">
|
||||
Telegram は、生成された出力内の明示的な返信スレッド化タグをサポートします。
|
||||
|
||||
- `[[reply_to_current]]` はトリガー元メッセージに返信します
|
||||
- `[[reply_to:<id>]]` は特定の Telegram メッセージ ID に返信します
|
||||
- `[[reply_to:<id>]]` は特定の Telegram メッセージIDに返信します
|
||||
|
||||
`channels.telegram.replyToMode` は処理を制御します:
|
||||
`channels.telegram.replyToMode` は処理を制御します。
|
||||
|
||||
- `off`（デフォルト）
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
返信スレッドが有効で、元の Telegram テキストまたはキャプションが利用可能な場合、OpenClaw はネイティブ Telegram 引用抜粋を自動的に含めます。Telegram はネイティブ引用テキストを 1024 UTF-16 コードユニットに制限するため、より長いメッセージは先頭から引用され、Telegram が引用を拒否した場合はプレーンな返信にフォールバックします。
|
||||
返信スレッド化が有効で、元の Telegram テキストまたはキャプションが利用可能な場合、OpenClaw はネイティブ Telegram 引用抜粋を自動的に含めます。Telegram はネイティブ引用テキストを1024 UTF-16コードユニットに制限するため、より長いメッセージは先頭から引用され、Telegram が引用を拒否した場合はプレーンな返信にフォールバックします。
|
||||
|
||||
注記: `off` は暗黙的な返信スレッドを無効にします。明示的な `[[reply_to_*]]` タグは引き続き尊重されます。
|
||||
注記: `off` は暗黙的な返信スレッド化を無効化します。明示的な `[[reply_to_*]]` タグは引き続き尊重されます。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -517,18 +554,18 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- トピックセッションキーは `:topic:<threadId>` を追加します
|
||||
- 返信と入力中表示はトピックスレッドを対象にします
|
||||
- トピック config パス:
|
||||
- トピック設定パス:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
一般トピック（`threadId=1`）の特別扱い:
|
||||
一般トピック（`threadId=1`）の特例:
|
||||
|
||||
- メッセージ送信では `message_thread_id` を省略します（Telegram は `sendMessage(...thread_id=1)` を拒否します）
|
||||
- 入力中アクションでは引き続き `message_thread_id` を含めます
|
||||
- 入力中アクションには引き続き `message_thread_id` が含まれます
|
||||
|
||||
トピック継承: トピック項目は、上書きされない限りグループ設定（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）を継承します。
|
||||
`agentId` はトピック専用で、グループのデフォルトからは継承されません。
|
||||
トピックの継承: トピック項目は、上書きされない限りグループ設定（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）を継承します。
|
||||
`agentId` はトピック専用で、グループデフォルトから継承されません。
|
||||
|
||||
**トピックごとのエージェントルーティング**: 各トピックは、トピック config で `agentId` を設定することで別のエージェントにルーティングできます。これにより、各トピックに独自の分離されたワークスペース、メモリ、セッションが与えられます。例:
|
||||
**トピックごとのエージェントルーティング**: 各トピックは、トピック設定で `agentId` を設定することで別のエージェントへルーティングできます。これにより、各トピックは独自の分離されたワークスペース、メモリ、セッションを持てます。例:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -548,24 +585,26 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
各トピックはそれぞれ独自のセッションキーを持ちます: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
その後、各トピックは独自のセッションキーを持ちます: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**永続 ACP トピックバインディング**: フォーラムトピックは、トップレベルの型付き ACP バインディング（`type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`、および `-1001234567890:topic:42` のようなトピック修飾 ID を持つ `bindings[]`）を通じて ACP ハーネスセッションをピン留めできます。現在はグループ/スーパーグループ内のフォーラムトピックにスコープされています。[ACP エージェント](/ja-JP/tools/acp-agents)を参照してください。
|
||||
**永続的な ACP トピックバインディング**: フォーラムトピックは、トップレベルの型付き ACP バインディング（`type: "acp"` と `match.channel: "telegram"`、`peer.kind: "group"`、および `-1001234567890:topic:42` のようなトピック修飾IDを持つ `bindings[]`）を通じて ACP ハーネスセッションを固定できます。現在はグループ/スーパーグループ内のフォーラムトピックにスコープされています。[ACP エージェント](/ja-JP/tools/acp-agents)を参照してください。
|
||||
|
||||
**チャットからのスレッド束縛 ACP spawn**: `/acp spawn <agent> --thread here|auto` は現在のトピックを新しい ACP セッションにバインドし、後続メッセージはそこへ直接ルーティングされます。OpenClaw は spawn 確認をトピック内にピン留めします。`channels.telegram.threadBindings.spawnSessions` が有効なままである必要があります（デフォルト: `true`）。
|
||||
**チャットからのスレッドバインド ACP spawn**: `/acp spawn <agent> --thread here|auto` は現在のトピックを新しい ACP セッションにバインドします。以後のやり取りはそこへ直接ルーティングされます。OpenClaw は spawn 確認をトピック内に固定します。`channels.telegram.threadBindings.spawnSessions` が有効のままである必要があります（デフォルト: `true`）。
|
||||
|
||||
テンプレートコンテキストは `MessageThreadId` と `IsForum` を公開します。`message_thread_id` を持つ DM チャットは、デフォルトではフラットセッション上の DM ルーティングと返信メタデータを維持します。`threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true`、または一致するトピック config が設定されている場合にのみ、スレッド対応セッションキーを使用します。アカウントのデフォルトにはトップレベルの `channels.telegram.dm.threadReplies` を、単一の DM には `direct.<chatId>.threadReplies` を使用します。
|
||||
テンプレートコンテキストは `MessageThreadId` と `IsForum` を公開します。`message_thread_id` を持つ DM チャットは、デフォルトでフラットセッション上の DM ルーティングと返信メタデータを維持します。`threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true`、または一致するトピック設定が構成されている場合にのみ、スレッド対応のセッションキーを使用します。アカウントのデフォルトにはトップレベルの `channels.telegram.dm.threadReplies` を、1 つの DM には `direct.<chatId>.threadReplies` を使用します。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="音声、動画、ステッカー">
|
||||
### 音声メッセージ
|
||||
|
||||
Telegram はボイスメモと音声ファイルを区別します。
|
||||
Telegram は音声メモと音声ファイルを区別します。
|
||||
|
||||
- デフォルト: 音声ファイルの動作
|
||||
- エージェント返信内のタグ `[[audio_as_voice]]` はボイスメモ送信を強制します
|
||||
- 受信ボイスメモの文字起こしは、エージェントコンテキスト内で機械生成の信頼できないテキストとして枠付けされます。メンション検出では引き続き生の文字起こしを使用するため、メンションでゲートされた音声メッセージは動作し続けます。
|
||||
- エージェント返信内のタグ `[[audio_as_voice]]` で音声メモ送信を強制
|
||||
- 受信した音声メモの文字起こしは、エージェントコンテキスト内で機械生成の
|
||||
信頼できないテキストとしてフレーム化されます。メンション検出は引き続き生の
|
||||
文字起こしを使用するため、メンションで制御された音声メッセージは動作し続けます。
|
||||
|
||||
メッセージアクションの例:
|
||||
|
||||
@ -581,7 +620,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
### 動画メッセージ
|
||||
|
||||
Telegram は動画ファイルとビデオノートを区別します。
|
||||
Telegram は動画ファイルと動画メモを区別します。
|
||||
|
||||
メッセージアクションの例:
|
||||
|
||||
@ -595,15 +634,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
ビデオノートはキャプションに対応していません。指定されたメッセージテキストは別途送信されます。
|
||||
動画メモはキャプションをサポートしません。指定されたメッセージテキストは別送されます。
|
||||
|
||||
### ステッカー
|
||||
|
||||
受信ステッカーの処理:
|
||||
|
||||
- 静的 WEBP: ダウンロードして処理されます（プレースホルダー `<media:sticker>`）
|
||||
- アニメーション TGS: スキップされます
|
||||
- 動画 WEBM: スキップされます
|
||||
- 静的 WEBP: ダウンロードして処理（プレースホルダー `<media:sticker>`）
|
||||
- アニメーション TGS: スキップ
|
||||
- 動画 WEBM: スキップ
|
||||
|
||||
ステッカーコンテキストフィールド:
|
||||
|
||||
@ -619,7 +658,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
ステッカーは（可能な場合）一度だけ説明され、繰り返しのビジョン呼び出しを減らすためにキャッシュされます。
|
||||
|
||||
ステッカーアクションを有効にします:
|
||||
ステッカーアクションを有効化:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -644,7 +683,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
キャッシュされたステッカーを検索します:
|
||||
キャッシュ済みステッカーを検索:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -660,7 +699,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="リアクション通知">
|
||||
Telegram のリアクションは `message_reaction` 更新として届きます（メッセージペイロードとは別です）。
|
||||
|
||||
有効な場合、OpenClaw は次のようなシステムイベントをキューに入れます:
|
||||
有効化すると、OpenClaw は次のようなシステムイベントをキューに入れます。
|
||||
|
||||
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
|
||||
|
||||
@ -669,19 +708,19 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all`（デフォルト: `own`）
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive`（デフォルト: `minimal`）
|
||||
|
||||
注:
|
||||
注記:
|
||||
|
||||
- `own` は、ボットが送信したメッセージに対するユーザーのリアクションのみを意味します（送信済みメッセージキャッシュによるベストエフォート）。
|
||||
- リアクションイベントは引き続き Telegram のアクセス制御（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）に従います。許可されていない送信者は破棄されます。
|
||||
- `own` はボットが送信したメッセージへのユーザーリアクションのみを意味します（送信メッセージキャッシュによるベストエフォート）。
|
||||
- リアクションイベントは引き続き Telegram のアクセス制御（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）を尊重します。許可されていない送信者は破棄されます。
|
||||
- Telegram はリアクション更新でスレッド ID を提供しません。
|
||||
- 非フォーラムグループはグループチャットセッションにルーティングされます
|
||||
- フォーラムグループは、正確な発生元トピックではなく、グループの一般トピックセッション（`:topic:1`）にルーティングされます
|
||||
- 非フォーラムグループはグループチャットセッションへルーティング
|
||||
- フォーラムグループは、正確な発生元トピックではなく、グループの一般トピックセッション（`:topic:1`）へルーティング
|
||||
|
||||
ポーリング/Webhook の `allowed_updates` には `message_reaction` が自動的に含まれます。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ack リアクション">
|
||||
<Accordion title="ACK リアクション">
|
||||
`ackReaction` は、OpenClaw が受信メッセージを処理している間に確認用の絵文字を送信します。
|
||||
|
||||
解決順序:
|
||||
@ -691,17 +730,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `messages.ackReaction`
|
||||
- エージェント ID の絵文字フォールバック（`agents.list[].identity.emoji`、なければ "👀"）
|
||||
|
||||
注:
|
||||
注記:
|
||||
|
||||
- Telegram は Unicode 絵文字（例: "👀"）を想定します。
|
||||
- チャンネルまたはアカウントでリアクションを無効にするには `""` を使用します。
|
||||
- Telegram は Unicode 絵文字（例: "👀"）を想定しています。
|
||||
- チャンネルまたはアカウントでリアクションを無効化するには `""` を使用します。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Telegram イベントとコマンドからの設定書き込み">
|
||||
チャンネル設定の書き込みはデフォルトで有効です（`configWrites !== false`）。
|
||||
|
||||
Telegram からトリガーされる書き込みには次が含まれます:
|
||||
Telegram によってトリガーされる書き込みには次が含まれます。
|
||||
|
||||
- `channels.telegram.groups` を更新するためのグループ移行イベント（`migrate_to_chat_id`）
|
||||
- `/config set` と `/config unset`（コマンドの有効化が必要）
|
||||
@ -721,38 +760,38 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="ロングポーリングと Webhook">
|
||||
デフォルトはロングポーリングです。Webhook モードでは `channels.telegram.webhookUrl` と `channels.telegram.webhookSecret` を設定します。任意で `webhookPath`、`webhookHost`、`webhookPort`（デフォルトは `/telegram-webhook`、`127.0.0.1`、`8787`）を設定できます。
|
||||
デフォルトはロングポーリングです。Webhook モードでは `channels.telegram.webhookUrl` と `channels.telegram.webhookSecret` を設定します。任意で `webhookPath`、`webhookHost`、`webhookPort`（デフォルトは `/telegram-webhook`、`127.0.0.1`、`8787`）も設定できます。
|
||||
|
||||
ローカルリスナーは `127.0.0.1:8787` にバインドします。公開イングレスでは、ローカルポートの前にリバースプロキシを置くか、意図的に `webhookHost: "0.0.0.0"` を設定します。
|
||||
ローカルリスナーは `127.0.0.1:8787` にバインドします。公開入口には、ローカルポートの前段にリバースプロキシを置くか、意図的に `webhookHost: "0.0.0.0"` を設定します。
|
||||
|
||||
Webhook モードは、Telegram に `200` を返す前にリクエストガード、Telegram シークレットトークン、JSON 本文を検証します。
|
||||
その後 OpenClaw は、ロングポーリングで使われるものと同じチャット別/トピック別のボットレーンを通じて更新を非同期に処理するため、遅いエージェントターンが Telegram の配信 ACK を保持しません。
|
||||
Webhook モードは、Telegram に `200` を返す前に、リクエストガード、Telegram シークレットトークン、JSON 本文を検証します。
|
||||
その後 OpenClaw は、ロングポーリングで使われるものと同じチャット単位/トピック単位のボットレーンを通じて更新を非同期に処理するため、遅いエージェントターンが Telegram の配信 ACK を保持しません。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="制限、再試行、CLI ターゲット">
|
||||
- `channels.telegram.textChunkLimit` のデフォルトは 4000 です。
|
||||
- `channels.telegram.chunkMode="newline"` は、長さで分割する前に段落境界（空行）を優先します。
|
||||
- `channels.telegram.mediaMaxMb`（デフォルト 100）は、受信および送信の Telegram メディアサイズを制限します。
|
||||
- `channels.telegram.mediaGroupFlushMs`（デフォルト 500）は、OpenClaw が Telegram のアルバム/メディアグループを 1 つの受信メッセージとしてディスパッチする前にバッファする時間を制御します。アルバムの一部が遅れて到着する場合は増やし、アルバム返信のレイテンシを減らすには減らします。
|
||||
- `channels.telegram.timeoutSeconds` は Telegram API クライアントのタイムアウトを上書きします（未設定の場合は grammY のデフォルトが適用されます）。ボットクライアントは、設定値が 60 秒の送信テキスト/タイピングリクエストガード未満の場合、その値をクランプするため、OpenClaw のトランスポートガードとフォールバックが実行される前に grammY が可視返信の配信を中止しません。ロングポーリングは引き続き 45 秒の `getUpdates` リクエストガードを使用するため、アイドル状態のポーリングが無期限に放棄されることはありません。
|
||||
- `channels.telegram.pollingStallThresholdMs` のデフォルトは `120000` です。ポーリング停止の誤検知による再起動の場合のみ、`30000` から `600000` の範囲で調整してください。
|
||||
- `channels.telegram.mediaMaxMb`（デフォルト 100）は、受信および送信 Telegram メディアのサイズ上限を設定します。
|
||||
- `channels.telegram.mediaGroupFlushMs`（デフォルト 500）は、OpenClaw が Telegram のアルバム/メディアグループを 1 つの受信メッセージとしてディスパッチする前に、どれだけバッファするかを制御します。アルバムの一部が遅れて届く場合は増やし、アルバム返信のレイテンシを下げるには減らします。
|
||||
- `channels.telegram.timeoutSeconds` は Telegram API クライアントのタイムアウトを上書きします（未設定の場合は grammY のデフォルトが適用されます）。ボットクライアントは、構成値が 60 秒の送信テキスト/タイピングリクエストガードを下回る場合にクランプするため、OpenClaw のトランスポートガードとフォールバックが実行される前に grammY が表示される返信配信を中止しません。ロングポーリングでは、アイドルポーリングが無期限に放棄されないように、引き続き 45 秒の `getUpdates` リクエストガードを使用します。
|
||||
- `channels.telegram.pollingStallThresholdMs` のデフォルトは `120000` です。ポーリング停止の誤検知による再起動の場合のみ、`30000` から `600000` の間で調整してください。
|
||||
- グループコンテキスト履歴は `channels.telegram.historyLimit` または `messages.groupChat.historyLimit`（デフォルト 50）を使用します。`0` で無効化します。
|
||||
- 返信/引用/転送の補足コンテキストは、現在は受信したまま渡されます。
|
||||
- Telegram の許可リストは主に、完全な補足コンテキスト編集境界ではなく、誰がエージェントをトリガーできるかを制御します。
|
||||
- 返信/引用/転送の補足コンテキストは、現時点では受信したまま渡されます。
|
||||
- Telegram の許可リストは主に、完全な補足コンテキストの秘匿境界ではなく、誰がエージェントをトリガーできるかを制御します。
|
||||
- DM 履歴制御:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- `channels.telegram.retry` 設定は、回復可能な送信 API エラーに対して Telegram 送信ヘルパー（CLI/ツール/アクション）に適用されます。受信の最終返信配信も、Telegram の接続前障害に対して境界付きの安全送信再試行を使用しますが、可視メッセージを重複させる可能性がある送信後の曖昧なネットワークエンベロープは再試行しません。
|
||||
- `channels.telegram.retry` 設定は、回復可能な送信 API エラーに対する Telegram 送信ヘルパー（CLI/ツール/アクション）に適用されます。受信した最終返信の配信も、Telegram の接続前失敗に対して制限付きの安全な送信再試行を使用しますが、表示メッセージを重複させる可能性のある送信後の曖昧なネットワークエンベロープは再試行しません。
|
||||
|
||||
CLI 送信ターゲットには数値のチャット ID またはユーザー名を使用できます:
|
||||
CLI 送信ターゲットには数値チャット ID またはユーザー名を指定できます。
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
openclaw message send --channel telegram --target @name --message "hi"
|
||||
```
|
||||
|
||||
Telegram ポーリングは `openclaw message poll` を使用し、フォーラムトピックに対応しています:
|
||||
Telegram ポーリングは `openclaw message poll` を使用し、フォーラムトピックをサポートします。
|
||||
|
||||
```bash
|
||||
openclaw message poll --channel telegram --target 123456789 \
|
||||
@ -762,57 +801,57 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
--poll-duration-seconds 300 --poll-public
|
||||
```
|
||||
|
||||
Telegram 専用のポーリングフラグ:
|
||||
Telegram 専用ポーリングフラグ:
|
||||
|
||||
- `--poll-duration-seconds`（5-600）
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- フォーラムトピック用の `--thread-id`（または `:topic:` ターゲットを使用）
|
||||
|
||||
Telegram 送信は次にも対応しています:
|
||||
Telegram 送信は次もサポートします。
|
||||
|
||||
- `channels.telegram.capabilities.inlineButtons` が許可している場合、インラインキーボード用の `buttons` ブロックを含む `--presentation`
|
||||
- ボットがそのチャットでピン留めできる場合、ピン留め配信を要求する `--pin` または `--delivery '{"pin":true}'`
|
||||
- 送信画像と GIF を、圧縮された写真またはアニメーションメディアアップロードではなく、ドキュメントとして送信する `--force-document`
|
||||
- `channels.telegram.capabilities.inlineButtons` が許可する場合、インラインキーボード用の `buttons` ブロックを含む `--presentation`
|
||||
- ボットがそのチャットでピン留めできる場合に、ピン留め配信を要求する `--pin` または `--delivery '{"pin":true}'`
|
||||
- 送信画像と GIF を、圧縮写真またはアニメーションメディアアップロードではなくドキュメントとして送信する `--force-document`
|
||||
|
||||
アクション制御:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` は、ポーリングを含む送信 Telegram メッセージを無効にします
|
||||
- `channels.telegram.actions.poll=false` は、通常の送信を有効にしたまま Telegram ポーリング作成を無効にします
|
||||
- `channels.telegram.actions.sendMessage=false` は、ポーリングを含む送信 Telegram メッセージを無効化します
|
||||
- `channels.telegram.actions.poll=false` は、通常の送信を有効のまま、Telegram ポーリング作成を無効化します
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Telegram での exec 承認">
|
||||
Telegram は承認者の DM で exec 承認に対応し、任意で元のチャットまたはトピックにプロンプトを投稿できます。承認者は数値の Telegram ユーザー ID である必要があります。
|
||||
Telegram は承認者 DM で exec 承認をサポートし、任意で発生元のチャットまたはトピックにもプロンプトを投稿できます。承認者は数値の Telegram ユーザー ID である必要があります。
|
||||
|
||||
設定パス:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled`（少なくとも 1 人の承認者が解決可能な場合に自動有効化）
|
||||
- `channels.telegram.execApprovals.enabled`（少なくとも 1 人の承認者を解決できる場合に自動有効化）
|
||||
- `channels.telegram.execApprovals.approvers`（`commands.ownerAllowFrom` の数値オーナー ID にフォールバック）
|
||||
- `channels.telegram.execApprovals.target`: `dm`（デフォルト）| `channel` | `both`
|
||||
- `agentFilter`、`sessionFilter`
|
||||
- `channels.telegram.execApprovals.target`: `dm`（デフォルト） | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
`channels.telegram.allowFrom`、`groupAllowFrom`、`defaultTo` は、誰がボットに話しかけられるか、通常の返信をどこへ送るかを制御します。これらは誰かを exec 承認者にするものではありません。コマンドオーナーがまだ存在しない場合、最初に承認された DM ペアリングが `commands.ownerAllowFrom` をブートストラップするため、1 オーナー構成でも `execApprovals.approvers` に ID を重複して記載せずに動作します。
|
||||
`channels.telegram.allowFrom`、`groupAllowFrom`、`defaultTo` は、誰がボットと会話できるか、および通常の返信をどこへ送るかを制御します。誰かを exec 承認者にするものではありません。コマンドオーナーがまだ存在しない場合、最初に承認された DM ペアリングが `commands.ownerAllowFrom` をブートストラップするため、1 オーナー構成でも `execApprovals.approvers` に ID を重複して設定せずに動作します。
|
||||
|
||||
チャンネル配信ではコマンドテキストがチャットに表示されます。信頼できるグループ/トピックでのみ `channel` または `both` を有効にしてください。プロンプトがフォーラムトピックに届いた場合、OpenClaw は承認プロンプトとフォローアップのトピックを保持します。exec 承認はデフォルトで 30 分後に期限切れになります。
|
||||
チャンネル配信ではチャット内にコマンドテキストが表示されます。`channel` または `both` は信頼できるグループ/トピックでのみ有効化してください。プロンプトがフォーラムトピックに届いた場合、OpenClaw は承認プロンプトとフォローアップのトピックを保持します。exec 承認はデフォルトで 30 分後に期限切れになります。
|
||||
|
||||
インライン承認ボタンでは、`channels.telegram.capabilities.inlineButtons` が対象サーフェス（`dm`、`group`、または `all`）を許可していることも必要です。`plugin:` プレフィックス付きの承認 ID は Plugin 承認を通じて解決され、それ以外はまず exec 承認を通じて解決されます。
|
||||
インライン承認ボタンも、`channels.telegram.capabilities.inlineButtons` が対象サーフェス（`dm`、`group`、または `all`）を許可している必要があります。`plugin:` 接頭辞付きの承認 ID は Plugin 承認を通じて解決され、それ以外はまず exec 承認を通じて解決されます。
|
||||
|
||||
[Exec 承認](/ja-JP/tools/exec-approvals)を参照してください。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## エラー返信の制御
|
||||
## エラー返信制御
|
||||
|
||||
エージェントで配信エラーまたはプロバイダーエラーが発生した場合、Telegram はエラーテキストで返信するか、それを抑制できます。この動作は 2 つの設定キーで制御します:
|
||||
エージェントが配信エラーまたはプロバイダーエラーに遭遇した場合、Telegram はエラーテキストで返信するか、それを抑制できます。この動作は 2 つの設定キーで制御します。
|
||||
|
||||
| キー | 値 | デフォルト | 説明 |
|
||||
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` はチャットにわかりやすいエラーメッセージを送信します。`silent` はエラー返信を完全に抑制します。 |
|
||||
| `channels.telegram.errorCooldownMs` | 数値 (ms) | `60000` | 同じチャットへのエラー返信間の最小時間です。障害中のエラースパムを防ぎます。 |
|
||||
| キー | 値 | デフォルト | 説明 |
|
||||
| ----------------------------------- | ----------------- | ---------- | ---------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` はチャットに親しみやすいエラーメッセージを送信します。`silent` はエラー返信を完全に抑制します。 |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 同じチャットへのエラー返信間の最小時間。障害中のエラースパムを防ぎます。 |
|
||||
|
||||
アカウント別、グループ別、トピック別の上書きに対応しています（他の Telegram 設定キーと同じ継承）。
|
||||
アカウント単位、グループ単位、トピック単位の上書きがサポートされています（他の Telegram 設定キーと同じ継承）。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -833,56 +872,56 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
## トラブルシューティング
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Bot がメンションなしのグループメッセージに応答しない">
|
||||
<Accordion title="メンションなしのグループメッセージにボットが応答しない">
|
||||
|
||||
- `requireMention=false` の場合、Telegram のプライバシーモードで完全な可視性を許可する必要があります。
|
||||
- `requireMention=false` の場合、Telegram プライバシーモードは完全な可視性を許可する必要があります。
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- その後、ボットをグループから削除して再追加します
|
||||
- その後、ボットをグループから削除して再追加
|
||||
- 設定がメンションなしのグループメッセージを想定している場合、`openclaw channels status` が警告します。
|
||||
- `openclaw channels status --probe` は明示的な数値グループ ID を確認できます。ワイルドカード `"*"` はメンバーシップのプローブができません。
|
||||
- `openclaw channels status --probe` は明示的な数値グループ ID を確認できます。ワイルドカード `"*"` はメンバーシッププローブできません。
|
||||
- 簡易セッションテスト: `/activation always`。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Bot がグループメッセージをまったく認識しない">
|
||||
<Accordion title="ボットがグループメッセージをまったく見ていない">
|
||||
|
||||
- `channels.telegram.groups` が存在する場合、グループが一覧に含まれている必要があります（または `"*"` を含めます）
|
||||
- グループ内のボットメンバーシップを確認します
|
||||
- `channels.telegram.groups` が存在する場合、group は列挙されている必要があります（または `"*"` を含めます）
|
||||
- group 内の bot メンバーシップを確認します
|
||||
- スキップ理由についてログを確認します: `openclaw logs --follow`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="コマンドが部分的に動作する、またはまったく動作しない">
|
||||
|
||||
- 送信者 ID を承認します（ペアリングおよび/または数値の `allowFrom`）
|
||||
- グループポリシーが `open` の場合でも、コマンド承認は引き続き適用されます
|
||||
- `BOT_COMMANDS_TOO_MUCH` を伴う `setMyCommands failed` は、ネイティブメニューのエントリが多すぎることを意味します。Plugin/Skill/カスタムコマンドを減らすか、ネイティブメニューを無効にしてください
|
||||
- `deleteMyCommands` / `setMyCommands` の起動時呼び出しと `sendChatAction` のタイピング呼び出しは境界付きで、リクエストタイムアウト時に Telegram のトランスポートフォールバックを通じて 1 回再試行します。永続的なネットワーク/fetch エラーは通常、`api.telegram.org` への DNS/HTTPS 到達性の問題を示します
|
||||
- 送信者 ID を認可します（ペアリングまたは数値の `allowFrom`）
|
||||
- group ポリシーが `open` の場合でも、コマンド認可は適用されます
|
||||
- `BOT_COMMANDS_TOO_MUCH` を伴う `setMyCommands failed` は、ネイティブメニューの項目が多すぎることを意味します。Plugin/スキル/カスタムコマンドを減らすか、ネイティブメニューを無効にしてください
|
||||
- 起動時の `deleteMyCommands` / `setMyCommands` 呼び出しと、入力中を示す `sendChatAction` 呼び出しは、範囲が制限され、リクエストのタイムアウト時には Telegram のトランスポートフォールバック経由で 1 回再試行されます。永続的なネットワーク/フェッチエラーは通常、`api.telegram.org` への DNS/HTTPS 到達性の問題を示します
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="起動時に未承認トークンが報告される">
|
||||
<Accordion title="起動時に未認可のトークンが報告される">
|
||||
|
||||
- `getMe returned 401` は、設定済みボットトークンに対する Telegram 認証失敗です。
|
||||
- BotFather でボットトークンを再コピーまたは再生成してから、デフォルトアカウントの `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken`、または `TELEGRAM_BOT_TOKEN` を更新します。
|
||||
- 起動中の `deleteWebhook 401 Unauthorized` も認証失敗です。これを「Webhook が存在しない」として扱っても、同じ不正なトークンによる失敗が後続の API 呼び出しまで先送りされるだけです。
|
||||
- `getMe returned 401` は、設定済み bot トークンに対する Telegram 認証失敗です。
|
||||
- BotFather で bot トークンを再コピーまたは再生成し、デフォルトアカウントの `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken`、または `TELEGRAM_BOT_TOKEN` を更新します。
|
||||
- 起動中の `deleteWebhook 401 Unauthorized` も認証失敗です。これを「webhook は存在しない」と扱うと、同じ不正なトークンによる失敗を後続の API 呼び出しまで先送りするだけです。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="ポーリングまたはネットワークの不安定性">
|
||||
<Accordion title="ポーリングまたはネットワークの不安定さ">
|
||||
|
||||
- Node 22+ とカスタム fetch/proxy の組み合わせでは、AbortSignal 型が一致しない場合に即時中断動作が発生することがあります。
|
||||
- 一部のホストは `api.telegram.org` を先に IPv6 へ解決します。IPv6 送信が壊れていると、Telegram API が断続的に失敗することがあります。
|
||||
- ログに `TypeError: fetch failed` または `Network request for 'getUpdates' failed!` が含まれる場合、OpenClaw はこれらを復旧可能なネットワークエラーとして再試行するようになりました。
|
||||
- ポーリング起動中、OpenClaw は成功した起動時の `getMe` プローブを grammY に再利用するため、ランナーは最初の `getUpdates` 前に 2 回目の `getMe` を必要としません。
|
||||
- ポーリング起動中に `deleteWebhook` が一時的なネットワークエラーで失敗した場合、OpenClaw は別の事前ポーリング制御プレーン呼び出しを行わず、ロングポーリングに進みます。まだアクティブな Webhook がある場合は `getUpdates` の競合として表面化し、その後 OpenClaw は Telegram トランスポートを再構築して Webhook クリーンアップを再試行します。
|
||||
- Telegram ソケットが短い固定間隔でリサイクルされる場合は、低い `channels.telegram.timeoutSeconds` が設定されていないか確認してください。ボットクライアントは、送信リクエストと `getUpdates` リクエストのガード値を下回る設定値をクランプしますが、古いリリースではこの値がそれらのガード値を下回っていると、すべてのポーリングまたは返信が中断されることがありました。
|
||||
- ログに `Polling stall detected` が含まれる場合、OpenClaw はデフォルトで、完了したロングポールの生存確認が 120 秒間ないと、ポーリングを再起動し Telegram トランスポートを再構築します。
|
||||
- `openclaw channels status --probe` と `openclaw doctor` は、実行中のポーリングアカウントが起動猶予後に `getUpdates` を完了していない場合、実行中の Webhook アカウントが起動猶予後に `setWebhook` を完了していない場合、または最後に成功したポーリングトランスポート活動が古い場合に警告します。
|
||||
- 長時間実行される `getUpdates` 呼び出しが健全であるにもかかわらず、ホストが誤ったポーリング停止再起動を報告する場合にのみ、`channels.telegram.pollingStallThresholdMs` を増やしてください。継続的な停止は通常、ホストと `api.telegram.org` の間の proxy、DNS、IPv6、または TLS 送信の問題を示します。
|
||||
- Telegram は Bot API トランスポートについて、`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` とそれらの小文字バリアントを含むプロセス proxy 環境変数も尊重します。`NO_PROXY` / `no_proxy` は引き続き `api.telegram.org` をバイパスできます。
|
||||
- サービス環境で OpenClaw 管理 proxy が `OPENCLAW_PROXY_URL` を通じて設定されており、標準 proxy 環境変数が存在しない場合、Telegram も Bot API トランスポートにその URL を使用します。
|
||||
- 直接の送信/TLS が不安定な VPS ホストでは、Telegram API 呼び出しを `channels.telegram.proxy` 経由でルーティングします。
|
||||
- Node 22+ とカスタム fetch/proxy の組み合わせでは、AbortSignal 型が一致しない場合に即時 abort 動作が発生することがあります。
|
||||
- 一部のホストは `api.telegram.org` を IPv6 優先で解決します。壊れた IPv6 外向き通信により、Telegram API が断続的に失敗することがあります。
|
||||
- ログに `TypeError: fetch failed` または `Network request for 'getUpdates' failed!` が含まれる場合、OpenClaw はこれらを回復可能なネットワークエラーとして再試行するようになっています。
|
||||
- ポーリング起動中、OpenClaw は成功した起動時の `getMe` プローブを grammY に再利用するため、runner は最初の `getUpdates` の前に 2 回目の `getMe` を必要としません。
|
||||
- ポーリング起動中に `deleteWebhook` が一時的なネットワークエラーで失敗した場合、OpenClaw は別の事前ポーリング control-plane 呼び出しを行わずに long polling へ進みます。webhook がまだ有効な場合は `getUpdates` の競合として表面化し、その後 OpenClaw は Telegram トランスポートを再構築して webhook クリーンアップを再試行します。
|
||||
- Telegram ソケットが短い固定間隔でリサイクルされる場合は、`channels.telegram.timeoutSeconds` が低くないか確認してください。bot クライアントは、外向き通信と `getUpdates` リクエストのガード値を下回る設定値をクランプしますが、古いリリースではこの値がそれらのガード値を下回っていると、すべてのポーリングまたは返信が abort されることがありました。
|
||||
- ログに `Polling stall detected` が含まれる場合、OpenClaw はデフォルトで、完了した long-poll liveness が 120 秒ないとポーリングを再起動し、Telegram トランスポートを再構築します。
|
||||
- `openclaw channels status --probe` と `openclaw doctor` は、実行中のポーリングアカウントが起動猶予後に `getUpdates` を完了していない場合、実行中の webhook アカウントが起動猶予後に `setWebhook` を完了していない場合、または最後に成功したポーリングトランスポート活動が古い場合に警告します。
|
||||
- 長時間実行される `getUpdates` 呼び出しが正常にもかかわらず、ホストがポーリング停止の誤検知による再起動を報告する場合にのみ、`channels.telegram.pollingStallThresholdMs` を増やしてください。永続的な停止は通常、ホストと `api.telegram.org` 間の proxy、DNS、IPv6、または TLS 外向き通信の問題を示します。
|
||||
- Telegram は Bot API トランスポートについて、`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` とそれらの小文字バリアントを含むプロセスの proxy 環境変数も尊重します。`NO_PROXY` / `no_proxy` は引き続き `api.telegram.org` をバイパスできます。
|
||||
- サービス環境で OpenClaw 管理 proxy が `OPENCLAW_PROXY_URL` によって設定され、標準の proxy 環境変数が存在しない場合、Telegram は Bot API トランスポートにもその URL を使用します。
|
||||
- 直接の外向き通信/TLS が不安定な VPS ホストでは、Telegram API 呼び出しを `channels.telegram.proxy` 経由でルーティングします:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -890,8 +929,8 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ はデフォルトで `autoSelectFamily=true` です（WSL2 を除く）。Telegram DNS 結果の順序は、`OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`、次に `channels.telegram.network.dnsResultOrder`、次に `NODE_OPTIONS=--dns-result-order=ipv4first` のようなプロセス既定値に従います。いずれも適用されない場合、Node 22+ は `ipv4first` にフォールバックします。
|
||||
- ホストが WSL2 である場合、または IPv4 のみの動作の方が明示的にうまく機能する場合は、ファミリー選択を強制します。
|
||||
- Node 22+ はデフォルトで `autoSelectFamily=true` です（WSL2 を除く）。Telegram DNS 結果の順序は、`OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`、次に `channels.telegram.network.dnsResultOrder`、次に `NODE_OPTIONS=--dns-result-order=ipv4first` などのプロセスデフォルトに従います。いずれも適用されない場合、Node 22+ は `ipv4first` にフォールバックします。
|
||||
- ホストが WSL2 の場合、または IPv4 のみの動作の方が明示的にうまく機能する場合は、family 選択を強制します:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -900,7 +939,7 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- RFC 2544 ベンチマーク範囲の応答（`198.18.0.0/15`）は、デフォルトで Telegram メディアダウンロードに対してすでに許可されています。信頼済みの fake-IP または透過 proxy が、メディアダウンロード中に `api.telegram.org` を別のプライベート/内部/特殊用途アドレスへ書き換える場合は、Telegram 専用バイパスを有効にできます。
|
||||
- RFC 2544 ベンチマーク範囲の応答（`198.18.0.0/15`）は、デフォルトで Telegram メディアダウンロードについてすでに許可されています。信頼済みの fake-IP または透過 proxy が、メディアダウンロード中に `api.telegram.org` をその他の private/internal/special-use アドレスへ書き換える場合は、Telegram 専用のバイパスを有効にできます:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -909,26 +948,24 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- 同じオプトインは、アカウントごとに
|
||||
- 同じ opt-in はアカウントごとに
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`
|
||||
でも利用できます。
|
||||
- proxy が Telegram メディアホストを `198.18.x.x` に解決する場合は、まず
|
||||
危険なフラグをオフのままにしてください。Telegram メディアはデフォルトで RFC 2544
|
||||
ベンチマーク範囲をすでに許可しています。
|
||||
危険なフラグをオフのままにしてください。Telegram メディアはデフォルトで
|
||||
RFC 2544 ベンチマーク範囲をすでに許可しています。
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` は Telegram
|
||||
メディアの SSRF 保護を弱めます。Clash、Mihomo、Surge fake-IP ルーティングのように、
|
||||
RFC 2544 ベンチマーク範囲外のプライベートまたは特殊用途の応答を合成する、
|
||||
信頼済みの運用者管理 proxy 環境でのみ使用してください。通常のパブリックインターネット経由の
|
||||
Telegram アクセスではオフのままにしてください。
|
||||
メディアの SSRF 保護を弱めます。Clash、Mihomo、Surge の fake-IP ルーティングのように、RFC 2544 ベンチマーク範囲外の private または special-use 応答を合成する、信頼済みのオペレーター管理 proxy
|
||||
環境でのみ使用してください。通常の public internet Telegram アクセスではオフのままにしてください。
|
||||
</Warning>
|
||||
|
||||
- 環境オーバーライド（一時的）:
|
||||
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
|
||||
- DNS 応答を検証します。
|
||||
- DNS 応答を検証します:
|
||||
|
||||
```bash
|
||||
dig +short api.telegram.org A
|
||||
@ -938,24 +975,24 @@ dig +short api.telegram.org AAAA
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
詳細ヘルプ: [チャンネルのトラブルシューティング](/ja-JP/channels/troubleshooting)。
|
||||
詳細ヘルプ: [Channel トラブルシューティング](/ja-JP/channels/troubleshooting)。
|
||||
|
||||
## 設定リファレンス
|
||||
|
||||
主要リファレンス: [設定リファレンス - Telegram](/ja-JP/gateway/config-channels#telegram)。
|
||||
|
||||
<Accordion title="高シグナルの Telegram フィールド">
|
||||
<Accordion title="重要度の高い Telegram フィールド">
|
||||
|
||||
- 起動/認証: `enabled`, `botToken`, `tokenFile`, `accounts.*`（`tokenFile` は通常ファイルを指している必要があります。シンボリックリンクは拒否されます）
|
||||
- アクセス制御: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, トップレベルの `bindings[]`（`type: "acp"`）
|
||||
- 実行承認: `execApprovals`, `accounts.*.execApprovals`
|
||||
- exec 承認: `execApprovals`, `accounts.*.execApprovals`
|
||||
- コマンド/メニュー: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- スレッド/返信: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies`
|
||||
- ストリーミング: `streaming`（プレビュー）, `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- 書式/配信: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- フォーマット/配信: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- メディア/ネットワーク: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- カスタム API ルート: `apiRoot`（Bot API ルートのみ。`/bot<TOKEN>` は含めないでください）
|
||||
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- アクション/機能: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- リアクション: `reactionNotifications`, `reactionLevel`
|
||||
- エラー: `errorPolicy`, `errorCooldownMs`
|
||||
@ -964,7 +1001,7 @@ dig +short api.telegram.org AAAA
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
マルチアカウントの優先順位: 2 つ以上のアカウント ID が設定されている場合は、`channels.telegram.defaultAccount` を設定する（または `channels.telegram.accounts.default` を含める）ことで、デフォルトルーティングを明示してください。そうでない場合、OpenClaw は最初の正規化済みアカウント ID にフォールバックし、`openclaw doctor` が警告します。名前付きアカウントは `channels.telegram.allowFrom` / `groupAllowFrom` を継承しますが、`accounts.default.*` 値は継承しません。
|
||||
マルチアカウントの優先順位: 2 つ以上のアカウント ID が設定されている場合、デフォルトルーティングを明示するために `channels.telegram.defaultAccount` を設定します（または `channels.telegram.accounts.default` を含めます）。それ以外の場合、OpenClaw は最初に正規化されたアカウント ID にフォールバックし、`openclaw doctor` が警告します。名前付きアカウントは `channels.telegram.allowFrom` / `groupAllowFrom` を継承しますが、`accounts.default.*` の値は継承しません。
|
||||
</Note>
|
||||
|
||||
## 関連
|
||||
@ -973,19 +1010,19 @@ dig +short api.telegram.org AAAA
|
||||
<Card title="ペアリング" icon="link" href="/ja-JP/channels/pairing">
|
||||
Telegram ユーザーを Gateway にペアリングします。
|
||||
</Card>
|
||||
<Card title="グループ" icon="users" href="/ja-JP/channels/groups">
|
||||
グループとトピックの許可リスト動作。
|
||||
<Card title="Groups" icon="users" href="/ja-JP/channels/groups">
|
||||
group と topic の allowlist 動作。
|
||||
</Card>
|
||||
<Card title="チャンネルルーティング" icon="route" href="/ja-JP/channels/channel-routing">
|
||||
受信メッセージをエージェントにルーティングします。
|
||||
<Card title="Channel ルーティング" icon="route" href="/ja-JP/channels/channel-routing">
|
||||
受信メッセージを agents にルーティングします。
|
||||
</Card>
|
||||
<Card title="セキュリティ" icon="shield" href="/ja-JP/gateway/security">
|
||||
脅威モデルと堅牢化。
|
||||
脅威モデルと強化。
|
||||
</Card>
|
||||
<Card title="マルチエージェントルーティング" icon="sitemap" href="/ja-JP/concepts/multi-agent">
|
||||
グループとトピックをエージェントにマッピングします。
|
||||
group と topic を agents にマッピングします。
|
||||
</Card>
|
||||
<Card title="トラブルシューティング" icon="wrench" href="/ja-JP/channels/troubleshooting">
|
||||
チャンネル横断の診断。
|
||||
Channel 横断の診断。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
---
|
||||
read_when:
|
||||
- 保存済みセッションを一覧表示し、最近のアクティビティを確認したい場合
|
||||
summary: '`openclaw sessions` のコマンドラインリファレンス（保存済みセッションの一覧表示 + 使用方法）'
|
||||
- 保存済みセッションを一覧表示し、最近のアクティビティを確認したい
|
||||
summary: '`openclaw sessions` の CLI リファレンス（保存済みセッションの一覧表示 + 使用方法）'
|
||||
title: セッション
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T20:44:10Z"
|
||||
generated_at: "2026-05-04T07:02:53Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5c9ec3ca55f7c5b6217b481e9da62f5416df73e69405a0dc15e77d2afeac723f
|
||||
source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e
|
||||
source_path: cli/sessions.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -16,7 +16,9 @@ x-i18n:
|
||||
|
||||
保存済みの会話セッションを一覧表示します。
|
||||
|
||||
セッション一覧は、チャンネル/プロバイダーの稼働状況チェックではありません。セッションストアから永続化済みの会話行を表示します。静かな Discord、Slack、Telegram、またはその他のチャンネルは、メッセージが処理されるまで新しいセッション行を作成せずに正常に再接続できます。ライブのチャンネル接続性が必要な場合は、`openclaw channels status --probe`、`openclaw status --deep`、または `openclaw health --verbose` を使用してください。
|
||||
セッション一覧は、チャンネルやプロバイダーの稼働状況チェックではありません。セッションストアから永続化された会話行を表示します。静かな Discord、Slack、Telegram、またはその他のチャンネルは、新しいセッション行を作成しなくても、メッセージが処理されるまで正常に再接続できます。ライブのチャンネル接続性が必要な場合は、`openclaw channels status --probe`、`openclaw status --deep`、または `openclaw health --verbose` を使用してください。
|
||||
|
||||
Gateway の `sessions.list` レスポンスはデフォルトで制限されているため、大規模で長期間存続するストアが Gateway のイベントループを占有することはありません。別の結果ウィンドウが必要な場合は、RPC クライアントから明示的に正の `limit` を渡してください。呼び出し元がさらに行が存在することを示す必要がある場合、レスポンスには `totalCount`、`limitApplied`、`hasMore` が含まれます。
|
||||
|
||||
```bash
|
||||
openclaw sessions
|
||||
@ -31,9 +33,9 @@ openclaw sessions --json
|
||||
|
||||
- デフォルト: 設定済みのデフォルトエージェントストア
|
||||
- `--verbose`: 詳細ログ
|
||||
- `--agent <id>`: 1 つの設定済みエージェントストア
|
||||
- `--all-agents`: すべての設定済みエージェントストアを集約
|
||||
- `--store <path>`: 明示的なストアパス（`--agent` または `--all-agents` と併用不可）
|
||||
- `--agent <id>`: 設定済みエージェントストア 1 つ
|
||||
- `--all-agents`: 設定済みのすべてのエージェントストアを集約
|
||||
- `--store <path>`: 明示的なストアパス（`--agent` または `--all-agents` と組み合わせることはできません）
|
||||
|
||||
保存済みセッションの軌跡バンドルをエクスポートします:
|
||||
|
||||
@ -42,9 +44,9 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12
|
||||
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
|
||||
```
|
||||
|
||||
これは、所有者が exec リクエストを承認した後に `/export-trajectory` スラッシュコマンドで使用されるコマンドパスです。出力ディレクトリは、選択されたワークスペース配下の `.openclaw/trajectory-exports/` 内に常に解決されます。
|
||||
これは、所有者が実行リクエストを承認した後に `/export-trajectory` スラッシュコマンドで使用されるコマンドパスです。出力ディレクトリは常に、選択されたワークスペース配下の `.openclaw/trajectory-exports/` 内に解決されます。
|
||||
|
||||
`openclaw sessions --all-agents` は設定済みエージェントストアを読み取ります。Gateway と ACP のセッション検出はより広範です。デフォルトの `agents/` ルート、またはテンプレート化された `session.store` ルート配下で見つかったディスク上のみのストアも含まれます。検出されたストアは、エージェントルート内の通常の `sessions.json` ファイルに解決される必要があります。シンボリックリンクとルート外パスはスキップされます。
|
||||
`openclaw sessions --all-agents` は設定済みエージェントストアを読み取ります。Gateway と ACP のセッション検出はより広範です。デフォルトの `agents/` ルートまたはテンプレート化された `session.store` ルート配下で見つかった、ディスク上にのみ存在するストアも含まれます。検出されたストアは、エージェントルート内の通常の `sessions.json` ファイルに解決される必要があります。シンボリックリンクとルート外のパスはスキップされます。
|
||||
|
||||
JSON の例:
|
||||
|
||||
@ -67,9 +69,9 @@ JSON の例:
|
||||
}
|
||||
```
|
||||
|
||||
## クリーンアップメンテナンス
|
||||
## クリーンアップ保守
|
||||
|
||||
次の書き込みサイクルを待たずに、今すぐメンテナンスを実行します:
|
||||
次の書き込みサイクルを待たずに、今すぐ保守を実行します:
|
||||
|
||||
```bash
|
||||
openclaw sessions cleanup --dry-run
|
||||
@ -82,19 +84,19 @@ openclaw sessions cleanup --json
|
||||
|
||||
`openclaw sessions cleanup` は設定の `session.maintenance` 設定を使用します:
|
||||
|
||||
- スコープメモ: `openclaw sessions cleanup` はセッションストア、トランスクリプト、軌跡サイドカーをメンテナンスします。Cron 実行ログ（`cron/runs/<jobId>.jsonl`）は剪定しません。これらは [Cron 設定](/ja-JP/automation/cron-jobs#configuration) の `cron.runLog.maxBytes` と `cron.runLog.keepLines` によって管理され、[Cron メンテナンス](/ja-JP/automation/cron-jobs#maintenance) で説明されています。
|
||||
- スコープの注記: `openclaw sessions cleanup` は、セッションストア、トランスクリプト、軌跡サイドカーを保守します。cron 実行ログ（`cron/runs/<jobId>.jsonl`）は削除しません。これは [Cron 設定](/ja-JP/automation/cron-jobs#configuration) の `cron.runLog.maxBytes` と `cron.runLog.keepLines` によって管理され、[Cron 保守](/ja-JP/automation/cron-jobs#maintenance) で説明されています。
|
||||
|
||||
- `--dry-run`: 書き込みを行わずに、何件のエントリが剪定/上限適用されるかをプレビューします。
|
||||
- テキストモードでは、ドライランはセッションごとのアクション表（`Action`、`Key`、`Age`、`Model`、`Flags`）を出力するため、保持されるものと削除されるものを確認できます。
|
||||
- `--enforce`: `session.maintenance.mode` が `warn` の場合でもメンテナンスを適用します。
|
||||
- `--fix-missing`: トランスクリプトファイルが欠落しているエントリを、通常はまだ経過時間/件数の対象外であっても削除します。
|
||||
- `--active-key <key>`: 特定のアクティブキーをディスク容量制限による退避から保護します。グループセッションやスレッドスコープのチャットセッションなど、永続的な外部会話ポインターも、経過時間/件数/ディスク容量制限メンテナンスで保持されます。
|
||||
- `--agent <id>`: 1 つの設定済みエージェントストアに対してクリーンアップを実行します。
|
||||
- `--all-agents`: すべての設定済みエージェントストアに対してクリーンアップを実行します。
|
||||
- `--dry-run`: 書き込みを行わずに、削除または上限制限されるエントリ数をプレビューします。
|
||||
- テキストモードでは、dry-run はセッションごとのアクションテーブル（`Action`、`Key`、`Age`、`Model`、`Flags`）を出力するため、保持されるものと削除されるものを確認できます。
|
||||
- `--enforce`: `session.maintenance.mode` が `warn` の場合でも保守を適用します。
|
||||
- `--fix-missing`: トランスクリプトファイルが見つからないエントリを、通常ならまだ経過時間や件数の条件から外れない場合でも削除します。
|
||||
- `--active-key <key>`: 特定のアクティブキーをディスク容量予算による退避から保護します。グループセッションやスレッド単位のチャットセッションなど、永続的な外部会話ポインターも、経過時間、件数、ディスク容量予算による保守で保持されます。
|
||||
- `--agent <id>`: 設定済みエージェントストア 1 つに対してクリーンアップを実行します。
|
||||
- `--all-agents`: 設定済みのすべてのエージェントストアに対してクリーンアップを実行します。
|
||||
- `--store <path>`: 特定の `sessions.json` ファイルに対して実行します。
|
||||
- `--json`: JSON サマリーを出力します。`--all-agents` の場合、出力にはストアごとに 1 つのサマリーが含まれます。
|
||||
- `--json`: JSON サマリーを出力します。`--all-agents` を指定した場合、出力にはストアごとのサマリーが含まれます。
|
||||
|
||||
Gateway に到達できる場合、設定済みエージェントストアの非ドライランクリーンアップは Gateway 経由で送信されるため、実行時トラフィックと同じセッションストア書き込み側を共有します。ストアファイルを明示的にオフライン修復する場合は `--store <path>` を使用してください。
|
||||
Gateway に到達できる場合、設定済みエージェントストアに対する dry-run ではないクリーンアップは Gateway 経由で送信されるため、ランタイムトラフィックと同じセッションストアライターを共有します。ストアファイルを明示的にオフライン修復するには `--store <path>` を使用してください。
|
||||
|
||||
`openclaw sessions cleanup --all-agents --dry-run --json`:
|
||||
|
||||
|
||||
@ -2,21 +2,21 @@
|
||||
read_when:
|
||||
- 受信メッセージが返信になる仕組みを説明する
|
||||
- セッション、キューイングモード、またはストリーミング動作の明確化
|
||||
- 推論の可視性と利用上の影響を文書化
|
||||
- 推論の可視性と使用上の影響の文書化
|
||||
summary: メッセージフロー、セッション、キューイング、推論の可視性
|
||||
title: メッセージ
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T16:28:01Z"
|
||||
generated_at: "2026-05-04T07:03:08Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9
|
||||
source_hash: 15242e21fd17a9f2013561003e108d197204d834caf51bbcdc53ffb3f118b14f
|
||||
source_path: concepts/messages.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw は、セッション解決、キューイング、ストリーミング、ツール実行、推論の可視性というパイプラインを通じて受信メッセージを処理します。このページでは、受信メッセージから返信までの経路を示します。
|
||||
OpenClaw は、セッション解決、キューイング、ストリーミング、ツール実行、推論の可視性からなるパイプラインで受信メッセージを処理します。このページでは、受信メッセージから返信までの経路を示します。
|
||||
|
||||
## メッセージフロー (高レベル)
|
||||
## メッセージフロー（高レベル）
|
||||
|
||||
```
|
||||
Inbound message
|
||||
@ -28,21 +28,21 @@ Inbound message
|
||||
|
||||
主要な調整項目は設定内にあります。
|
||||
|
||||
- `messages.*`: プレフィックス、キューイング、グループ動作。
|
||||
- `agents.defaults.*`: ブロックストリーミングとチャンク化のデフォルト。
|
||||
- チャネルの上書き (`channels.whatsapp.*`、`channels.telegram.*` など): 上限とストリーミングの切り替え。
|
||||
- 接頭辞、キューイング、グループ動作には `messages.*`。
|
||||
- ブロックストリーミングとチャンク化のデフォルトには `agents.defaults.*`。
|
||||
- 上限とストリーミングの切り替えには、チャンネルごとの上書き（`channels.whatsapp.*`、`channels.telegram.*` など）。
|
||||
|
||||
完全なスキーマについては [設定](/ja-JP/gateway/configuration) を参照してください。
|
||||
|
||||
## 受信重複排除
|
||||
## 受信の重複排除
|
||||
|
||||
チャネルは再接続後に同じメッセージを再配信することがあります。OpenClaw は、チャネル/アカウント/ピア/セッション/メッセージ ID をキーにした短命のキャッシュを保持し、重複配信によって別のエージェント実行が起動しないようにします。
|
||||
チャンネルは、再接続後に同じメッセージを再配信することがあります。OpenClaw は、チャンネル/アカウント/ピア/セッション/メッセージ ID をキーとする短期間のキャッシュを保持し、重複配信が別のエージェント実行を起動しないようにします。
|
||||
|
||||
## 受信デバウンス
|
||||
## 受信のデバウンス
|
||||
|
||||
**同じ送信者**からの連続した短時間のメッセージは、`messages.inbound` によって単一のエージェントターンにまとめることができます。デバウンスはチャネル + 会話ごとにスコープされ、返信スレッド/ID には最新のメッセージを使用します。
|
||||
**同じ送信者**からの短時間の連続メッセージは、`messages.inbound` によって単一のエージェントターンにまとめられます。デバウンスはチャンネル + 会話単位でスコープされ、返信スレッド/ID には最新のメッセージが使用されます。
|
||||
|
||||
設定 (グローバルデフォルト + チャネルごとの上書き):
|
||||
設定（グローバルデフォルト + チャンネルごとの上書き）:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -62,77 +62,77 @@ Inbound message
|
||||
注:
|
||||
|
||||
- デバウンスは**テキストのみ**のメッセージに適用されます。メディア/添付ファイルは即座にフラッシュされます。
|
||||
- 制御コマンドは単独のままになるようデバウンスをバイパスします。ただし、チャネルが同一送信者の DM 結合を明示的に有効にしている場合は**例外**です (例: [BlueBubbles `coalesceSameSenderDms`](/ja-JP/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition))。この場合、分割送信ペイロードが同じエージェントターンに合流できるよう、DM コマンドはデバウンス期間内で待機します。
|
||||
- 制御コマンドはデバウンスをバイパスするため単独のままです。ただし、チャンネルが同一送信者 DM の結合を明示的に有効にしている場合（例: [BlueBubbles `coalesceSameSenderDms`](/ja-JP/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)）は**例外**で、DM コマンドは分割送信されたペイロードが同じエージェントターンに合流できるように、デバウンス期間内で待機します。
|
||||
|
||||
## セッションとデバイス
|
||||
|
||||
セッションはクライアントではなく Gateway が所有します。
|
||||
|
||||
- ダイレクトチャットはエージェントのメインセッションキーにまとめられます。
|
||||
- グループ/チャネルには固有のセッションキーが割り当てられます。
|
||||
- セッションストアとトランスクリプトは Gateway ホスト上に存在します。
|
||||
- ダイレクトチャットはエージェントのメインセッションキーに集約されます。
|
||||
- グループ/チャンネルは独自のセッションキーを持ちます。
|
||||
- セッションストアとトランスクリプトは Gateway ホスト上にあります。
|
||||
|
||||
複数のデバイス/チャネルを同じセッションに対応付けることはできますが、履歴がすべてのクライアントへ完全に同期されるわけではありません。推奨: 長い会話では文脈の分岐を避けるため、主デバイスを 1 つ使用してください。Control UI と TUI は常に Gateway に裏付けられたセッショントランスクリプトを表示するため、これらが信頼できる情報源です。
|
||||
複数のデバイス/チャンネルを同じセッションにマッピングできますが、履歴はすべてのクライアントに完全には同期されません。推奨事項: 長い会話では、コンテキストの分岐を避けるために 1 つの主要デバイスを使用してください。Control UI と TUI は常に Gateway が保持するセッショントランスクリプトを表示するため、これらが信頼できる情報源です。
|
||||
|
||||
詳細: [セッション管理](/ja-JP/concepts/session)。
|
||||
|
||||
## ツール結果メタデータ
|
||||
|
||||
ツール結果の `content` はモデルに見える結果です。ツール結果の `details` は、UI レンダリング、診断、メディア配信、Plugin 用のランタイムメタデータです。
|
||||
ツール結果の `content` はモデルに見える結果です。ツール結果の `details` は、UI レンダリング、診断、メディア配信、Plugin のためのランタイムメタデータです。
|
||||
|
||||
OpenClaw はその境界を明示的に保ちます。
|
||||
OpenClaw はこの境界を明示的に保ちます。
|
||||
|
||||
- `toolResult.details` はプロバイダー再生と Compaction 入力の前に取り除かれます。
|
||||
- 永続化されたセッショントランスクリプトには、境界内の `details` のみが保持されます。過大なメタデータは、`persistedDetailsTruncated: true` とマークされたコンパクトな要約に置き換えられます。
|
||||
- Plugin とツールは、モデルが読む必要のあるテキストを `details` だけでなく `content` に入れる必要があります。
|
||||
- `toolResult.details` は、プロバイダーの再生と Compaction 入力の前に取り除かれます。
|
||||
- 永続化されたセッショントランスクリプトは、制限された `details` のみを保持します。過大なメタデータは、`persistedDetailsTruncated: true` とマークされたコンパクトな要約に置き換えられます。
|
||||
- Plugin とツールは、モデルが読む必要のあるテキストを `details` のみに入れるのではなく、`content` に入れるべきです。
|
||||
|
||||
## 受信本文と履歴コンテキスト
|
||||
|
||||
OpenClaw は**プロンプト本文**と**コマンド本文**を分離します。
|
||||
|
||||
- `BodyForAgent`: 現在のメッセージについて、主にモデル向けとなるテキスト。チャネル Plugin は、送信者の現在のプロンプトを含むテキストにこれを集中させる必要があります。
|
||||
- `Body`: レガシーのプロンプトフォールバック。これにはチャネルエンベロープや任意の履歴ラッパーが含まれる場合がありますが、現在のチャネルは `BodyForAgent` が利用可能な場合、主要なモデル入力としてこれに依存するべきではありません。
|
||||
- `BodyForAgent`: 現在のメッセージに対する、主なモデル向けテキスト。チャンネル Plugin は、これを送信者の現在のプロンプトを含むテキストに集中させるべきです。
|
||||
- `Body`: レガシーのプロンプトフォールバック。チャンネルのエンベロープや任意の履歴ラッパーを含む場合がありますが、現在のチャンネルは `BodyForAgent` が利用可能な場合、これを主要なモデル入力として扱うべきではありません。
|
||||
- `CommandBody`: ディレクティブ/コマンド解析用の生のユーザーテキスト。
|
||||
- `RawBody`: `CommandBody` のレガシーエイリアス (互換性のために保持)。
|
||||
- `RawBody`: `CommandBody` のレガシーエイリアス（互換性のために保持）。
|
||||
|
||||
チャネルが履歴を提供する場合、共有ラッパーを使用します。
|
||||
チャンネルが履歴を提供する場合、共有ラッパーを使用します。
|
||||
|
||||
- `[Chat messages since your last reply - for context]`
|
||||
- `[Current message - respond to this]`
|
||||
|
||||
**非ダイレクトチャット** (グループ/チャネル/ルーム) では、**現在のメッセージ本文**の先頭に送信者ラベルが付きます (履歴エントリに使われるものと同じスタイル)。これにより、エージェントプロンプト内でリアルタイムメッセージとキュー/履歴メッセージの一貫性が保たれます。
|
||||
**非ダイレクトチャット**（グループ/チャンネル/ルーム）では、**現在のメッセージ本文**の前に送信者ラベルが付加されます（履歴エントリと同じスタイル）。これにより、リアルタイムメッセージとキュー/履歴メッセージがエージェントプロンプト内で一貫します。
|
||||
|
||||
履歴バッファは**保留中のみ**です。実行をトリガーしなかったグループメッセージ (たとえばメンションゲートされたメッセージ) を含み、セッショントランスクリプトにすでにあるメッセージは**除外**します。
|
||||
履歴バッファは**保留中のみ**です。これには、実行をトリガーしなかったグループメッセージ（たとえば、メンションでゲートされたメッセージ）が含まれ、すでにセッショントランスクリプト内にあるメッセージは**除外**されます。
|
||||
|
||||
ディレクティブの除去は**現在のメッセージ**セクションにのみ適用されるため、履歴はそのまま残ります。履歴をラップするチャネルは、`CommandBody` (または `RawBody`) を元のメッセージテキストに設定し、`Body` は結合済みプロンプトとして保持する必要があります。構造化された履歴、返信、転送、チャネルメタデータは、プロンプト組み立て時にユーザーロールの信頼されないコンテキストブロックとしてレンダリングされます。
|
||||
履歴バッファは、`messages.groupChat.historyLimit` (グローバルデフォルト) と、`channels.slack.historyLimit` や `channels.telegram.accounts.<id>.historyLimit` のようなチャネルごとの上書きで設定できます (無効化するには `0` を設定)。
|
||||
ディレクティブの除去は**現在のメッセージ**セクションにのみ適用されるため、履歴はそのまま保持されます。履歴をラップするチャンネルは、`CommandBody`（または `RawBody`）を元のメッセージテキストに設定し、`Body` を結合済みプロンプトとして保持するべきです。構造化された履歴、返信、転送、チャンネルメタデータは、プロンプト組み立て時にユーザー役割の信頼されないコンテキストブロックとしてレンダリングされます。
|
||||
履歴バッファは、`messages.groupChat.historyLimit`（グローバルデフォルト）と、`channels.slack.historyLimit` や `channels.telegram.accounts.<id>.historyLimit` などのチャンネルごとの上書きで設定できます（無効にするには `0` を設定）。
|
||||
|
||||
## キューイングとフォローアップ
|
||||
|
||||
実行がすでにアクティブな場合、受信メッセージはキューに入れる、現在の実行へ誘導する、またはフォローアップターン用に収集することができます。
|
||||
実行がすでにアクティブな場合、受信メッセージはキューに入れる、現在の実行に誘導する、またはフォローアップターン用に収集することができます。
|
||||
|
||||
- `messages.queue` (および `messages.queue.byChannel`) で設定します。
|
||||
- デフォルトモードは `steer` で、誘導がキュー済みフォローアップ配信へフォールバックする場合は 500ms のフォローアップデバウンスがあります。
|
||||
- モード: `steer`、`followup`、`collect`、`steer-backlog`、`interrupt`、およびレガシーの 1 回に 1 つずつ処理する `queue` モード。
|
||||
- `messages.queue`（および `messages.queue.byChannel`）で設定します。
|
||||
- デフォルトモードは `steer` で、誘導がキュー済みフォローアップ配信にフォールバックする場合は 500ms のフォローアップデバウンスがあります。
|
||||
- モード: `steer`、`followup`、`collect`、`steer-backlog`、`interrupt`、およびレガシーの 1 回に 1 件ずつ処理する `queue` モード。
|
||||
|
||||
詳細: [コマンドキュー](/ja-JP/concepts/queue) と [ステアリングキュー](/ja-JP/concepts/queue-steering)。
|
||||
詳細: [コマンドキュー](/ja-JP/concepts/queue) と [Steering キュー](/ja-JP/concepts/queue-steering)。
|
||||
|
||||
## チャネル実行の所有権
|
||||
## チャンネルの実行所有権
|
||||
|
||||
チャネル Plugin は、メッセージがセッションキューに入る前に、順序の保持、入力のデバウンス、トランスポートのバックプレッシャー適用を行うことができます。エージェントターン自体に別個のタイムアウトを課すべきではありません。メッセージがセッションにルーティングされると、長時間実行される作業はセッション、ツール、ランタイムのライフサイクルによって管理され、すべてのチャネルが遅いターンを一貫して報告し復旧できるようになります。
|
||||
チャンネル Plugin は、メッセージがセッションキューに入る前に順序を保持し、入力をデバウンスし、トランスポートのバックプレッシャーを適用できます。エージェントターン自体に別個のタイムアウトを課すべきではありません。メッセージがセッションにルーティングされると、長時間実行される作業はセッション、ツール、ランタイムのライフサイクルによって管理されるため、すべてのチャンネルが遅いターンを一貫して報告し、回復できます。
|
||||
|
||||
## ストリーミング、チャンク化、バッチ化
|
||||
|
||||
ブロックストリーミングは、モデルがテキストブロックを生成するにつれて部分返信を送信します。チャンク化はチャネルのテキスト上限を尊重し、フェンス付きコードの分割を避けます。
|
||||
ブロックストリーミングは、モデルがテキストブロックを生成するにつれて部分返信を送信します。チャンク化はチャンネルのテキスト制限を尊重し、フェンス付きコードの分割を避けます。
|
||||
|
||||
主要な設定:
|
||||
主要設定:
|
||||
|
||||
- `agents.defaults.blockStreamingDefault` (`on|off`、デフォルトは off)
|
||||
- `agents.defaults.blockStreamingBreak` (`text_end|message_end`)
|
||||
- `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`)
|
||||
- `agents.defaults.blockStreamingCoalesce` (アイドルベースのバッチ化)
|
||||
- `agents.defaults.humanDelay` (ブロック返信間の人間らしい一時停止)
|
||||
- チャネルの上書き: `*.blockStreaming` と `*.blockStreamingCoalesce` (Telegram 以外のチャネルでは明示的な `*.blockStreaming: true` が必要)
|
||||
- `agents.defaults.blockStreamingCoalesce`（アイドルベースのバッチ化）
|
||||
- `agents.defaults.humanDelay`（ブロック返信間の人間らしい一時停止）
|
||||
- チャンネルごとの上書き: `*.blockStreaming` と `*.blockStreamingCoalesce`（Telegram 以外のチャンネルでは明示的な `*.blockStreaming: true` が必要）
|
||||
|
||||
詳細: [ストリーミング + チャンク化](/ja-JP/concepts/streaming)。
|
||||
|
||||
@ -141,39 +141,39 @@ OpenClaw は**プロンプト本文**と**コマンド本文**を分離します
|
||||
OpenClaw はモデルの推論を表示または非表示にできます。
|
||||
|
||||
- `/reasoning on|off|stream` は可視性を制御します。
|
||||
- 推論コンテンツは、モデルによって生成された場合、トークン使用量に引き続きカウントされます。
|
||||
- Telegram はドラフトバブルへの推論ストリームをサポートします。
|
||||
- 推論コンテンツは、モデルによって生成された場合、トークン使用量に含まれます。
|
||||
- Telegram は、一時的な下書きバブルへの推論ストリームをサポートしており、これは最終配信後に削除されます。永続的な推論出力には `/reasoning on` を使用してください。
|
||||
|
||||
詳細: [思考 + 推論ディレクティブ](/ja-JP/tools/thinking) と [トークン使用量](/ja-JP/reference/token-use)。
|
||||
|
||||
## プレフィックス、スレッド化、返信
|
||||
## 接頭辞、スレッド化、返信
|
||||
|
||||
送信メッセージの形式は `messages` に集約されています。
|
||||
送信メッセージのフォーマットは `messages` に集約されています。
|
||||
|
||||
- `messages.responsePrefix`、`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix` (送信プレフィックスのカスケード)、および `channels.whatsapp.messagePrefix` (WhatsApp 受信プレフィックス)
|
||||
- `replyToMode` とチャネルごとのデフォルトによる返信スレッド化
|
||||
- `messages.responsePrefix`、`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`（送信接頭辞のカスケード）、および `channels.whatsapp.messagePrefix`（WhatsApp 受信接頭辞）
|
||||
- `replyToMode` とチャンネルごとのデフォルトによる返信スレッド化
|
||||
|
||||
詳細: [設定](/ja-JP/gateway/config-agents#messages) とチャネルドキュメント。
|
||||
詳細: [設定](/ja-JP/gateway/config-agents#messages) とチャンネルドキュメント。
|
||||
|
||||
## サイレント返信
|
||||
|
||||
正確なサイレントトークン `NO_REPLY` / `no_reply` は「ユーザーに見える返信を配信しない」ことを意味します。
|
||||
ターンに生成された TTS 音声などの保留中ツールメディアもある場合、OpenClaw はサイレントテキストを取り除きますが、メディア添付ファイルは引き続き配信します。
|
||||
OpenClaw はその動作を会話タイプごとに解決します。
|
||||
ターンに生成された TTS 音声などの保留中のツールメディアもある場合、OpenClaw はサイレントテキストを取り除きますが、メディア添付ファイルは引き続き配信します。
|
||||
OpenClaw はこの動作を会話タイプ別に解決します。
|
||||
|
||||
- ダイレクト会話ではデフォルトで沈黙を許可せず、裸のサイレント返信を短い可視フォールバックに書き換えます。
|
||||
- グループ/チャネルではデフォルトで沈黙を許可します。
|
||||
- 内部オーケストレーションではデフォルトで沈黙を許可します。
|
||||
- ダイレクト会話では、デフォルトでサイレンスを許可せず、サイレント返信のみの場合は短い可視フォールバックに書き換えます。
|
||||
- グループ/チャンネルでは、デフォルトでサイレンスを許可します。
|
||||
- 内部オーケストレーションでは、デフォルトでサイレンスを許可します。
|
||||
|
||||
OpenClaw は、非ダイレクトチャットでアシスタント返信の前に発生した内部ランナー障害にもサイレント返信を使用するため、グループ/チャネルには Gateway エラーの定型文が表示されません。ダイレクトチャットではデフォルトで簡潔な失敗文が表示されます。生のランナー詳細は `/verbose` が `on` または `full` の場合にのみ表示されます。
|
||||
OpenClaw は、非ダイレクトチャットでアシスタント返信の前に発生した内部ランナー障害にもサイレント返信を使用するため、グループ/チャンネルには Gateway エラーの定型文が表示されません。ダイレクトチャットでは、デフォルトで簡潔な失敗文が表示されます。生のランナー詳細は、`/verbose` が `on` または `full` の場合にのみ表示されます。
|
||||
|
||||
デフォルトは `agents.defaults.silentReply` と `agents.defaults.silentReplyRewrite` の下にあります。`surfaces.<id>.silentReply` と `surfaces.<id>.silentReplyRewrite` はサーフェスごとにこれらを上書きできます。
|
||||
デフォルトは `agents.defaults.silentReply` と `agents.defaults.silentReplyRewrite` の下にあり、`surfaces.<id>.silentReply` と `surfaces.<id>.silentReplyRewrite` でサーフェスごとに上書きできます。
|
||||
|
||||
親セッションに保留中の生成済みサブエージェント実行が 1 つ以上ある場合、裸のサイレント返信は書き換えられる代わりにすべてのサーフェスで破棄されるため、子の完了イベントが実際の返信を配信するまで親は静かなままになります。
|
||||
親セッションに保留中の生成済みサブエージェント実行が 1 つ以上ある場合、サイレント返信のみの返信は書き換えられるのではなくすべてのサーフェスで破棄されるため、子の完了イベントが実際の返信を配信するまで親は静かなままになります。
|
||||
|
||||
## 関連
|
||||
|
||||
- [ストリーミング](/ja-JP/concepts/streaming) — リアルタイムメッセージ配信
|
||||
- [リトライ](/ja-JP/concepts/retry) — メッセージ配信のリトライ動作
|
||||
- [再試行](/ja-JP/concepts/retry) — メッセージ配信の再試行動作
|
||||
- [キュー](/ja-JP/concepts/queue) — メッセージ処理キュー
|
||||
- [チャネル](/ja-JP/channels) — メッセージングプラットフォーム連携
|
||||
- [チャンネル](/ja-JP/channels) — メッセージングプラットフォーム連携
|
||||
|
||||
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- チャネルでのストリーミングまたはチャンク化の仕組みの説明
|
||||
- ブロックストリーミングまたはチャネルのチャンク分割動作の変更
|
||||
- 重複または早期のブロック返信やチャンネルプレビューのストリーミングのデバッグ
|
||||
summary: ストリーミング + チャンク化の動作 (ブロック返信、チャンネルプレビューのストリーミング、モードマッピング)
|
||||
- チャンネルでストリーミングまたはチャンク化がどのように機能するかを説明する
|
||||
- ブロックストリーミングまたはチャネルのチャンク化動作の変更
|
||||
- 重複または早期のブロック返信やチャンネルプレビューのストリーミングをデバッグする
|
||||
summary: ストリーミング + チャンク化の動作 (ブロック返信、チャンネルプレビューストリーミング、モードマッピング)
|
||||
title: ストリーミングとチャンク化
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:31:09Z"
|
||||
generated_at: "2026-05-04T07:03:15Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 1335f4f5532060bd8bf839683a2b1fbab38f38887c5583135652b4753e0f6a50
|
||||
source_hash: ff7b6cd8127255352fe16fb746469e9828e7d5aea183d3799ab10cc768515bd1
|
||||
source_path: concepts/streaming.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw には 2 つの別個のストリーミング層があります。
|
||||
OpenClaw には、2 つの別々のストリーミングレイヤーがあります。
|
||||
|
||||
- **ブロックストリーミング（チャンネル）:** アシスタントが書き込むにつれて、完了した**ブロック**を送信します。これらは通常のチャンネルメッセージです（トークン差分ではありません）。
|
||||
- **ブロックストリーミング（チャンネル）:** アシスタントが書き込み中に、完了した**ブロック**を送信します。これらは通常のチャンネルメッセージです（トークン差分ではありません）。
|
||||
- **プレビューストリーミング（Telegram/Discord/Slack）:** 生成中に一時的な**プレビューメッセージ**を更新します。
|
||||
|
||||
現在、チャンネルメッセージへの**真のトークン差分ストリーミング**はありません。プレビューストリーミングはメッセージベースです（送信 + 編集/追記）。
|
||||
|
||||
## ブロックストリーミング（チャンネルメッセージ）
|
||||
|
||||
ブロックストリーミングは、利用可能になったアシスタント出力を粗いチャンクで送信します。
|
||||
ブロックストリーミングは、利用可能になったアシスタント出力を大きめのチャンクで送信します。
|
||||
|
||||
```
|
||||
Model output
|
||||
@ -37,75 +37,75 @@ Model output
|
||||
|
||||
凡例:
|
||||
|
||||
- `text_delta/events`: モデルストリームイベント（非ストリーミングモデルではまばらな場合があります）。
|
||||
- `chunker`: min/max 境界 + 区切り優先度を適用する `EmbeddedBlockChunker`。
|
||||
- `text_delta/events`: モデルのストリームイベント（非ストリーミングモデルではまばらな場合があります）。
|
||||
- `chunker`: 最小/最大境界 + 区切り優先度を適用する `EmbeddedBlockChunker`。
|
||||
- `channel send`: 実際の送信メッセージ（ブロック返信）。
|
||||
|
||||
**制御:**
|
||||
|
||||
- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"`（デフォルトは off）。
|
||||
- チャンネル上書き: チャンネルごとに `"on"`/`"off"` を強制する `*.blockStreaming`（およびアカウント単位のバリアント）。
|
||||
- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"`（デフォルトはオフ）。
|
||||
- チャンネル上書き: チャンネルごとに `"on"`/`"off"` を強制する `*.blockStreaming`（およびアカウントごとのバリアント）。
|
||||
- `agents.defaults.blockStreamingBreak`: `"text_end"` または `"message_end"`。
|
||||
- `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`。
|
||||
- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }`（送信前にストリーミングされたブロックをマージ）。
|
||||
- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }`（送信前にストリーミングされたブロックを結合）。
|
||||
- チャンネルのハード上限: `*.textChunkLimit`（例: `channels.whatsapp.textChunkLimit`）。
|
||||
- チャンネルのチャンクモード: `*.chunkMode`（デフォルトは `length`、`newline` は長さによるチャンク化の前に空行（段落境界）で分割）。
|
||||
- Discord のソフト上限: `channels.discord.maxLinesPerMessage`（デフォルト 17）は、UI のクリッピングを避けるため長い返信を分割します。
|
||||
- チャンネルのチャンクモード: `*.chunkMode`（デフォルトは `length`、`newline` は長さによるチャンク化の前に空行（段落境界）で分割します）。
|
||||
- Discord のソフト上限: `channels.discord.maxLinesPerMessage`（デフォルトは 17）は、UI の切り詰めを避けるために縦に長い返信を分割します。
|
||||
|
||||
**境界セマンティクス:**
|
||||
**境界の意味:**
|
||||
|
||||
- `text_end`: chunker が送出するとすぐにブロックをストリーミングし、各 `text_end` でフラッシュします。
|
||||
- `message_end`: アシスタントメッセージが完了するまで待ってから、バッファ済みの出力をフラッシュします。
|
||||
- `text_end`: chunker が送信したらすぐにブロックをストリーミングし、各 `text_end` でフラッシュします。
|
||||
- `message_end`: アシスタントメッセージが完了するまで待ち、その後バッファされた出力をフラッシュします。
|
||||
|
||||
`message_end` でも、バッファ済みテキストが `maxChars` を超える場合は chunker を使うため、最後に複数のチャンクを送出できます。
|
||||
バッファされたテキストが `maxChars` を超える場合、`message_end` でも chunker が使われるため、最後に複数のチャンクを送信することがあります。
|
||||
|
||||
### ブロックストリーミングでのメディア配信
|
||||
|
||||
`MEDIA:` ディレクティブは通常の配信メタデータです。ブロックストリーミングがメディアブロックを早めに送信した場合、OpenClaw はそのターンの配信を記憶します。最終アシスタントペイロードが同じメディア URL を繰り返した場合、添付を再送信する代わりに、最終配信では重複メディアが取り除かれます。
|
||||
`MEDIA:` ディレクティブは通常の配信メタデータです。ブロックストリーミングがメディアブロックを早期に送信すると、OpenClaw はそのターンの配信を記憶します。最終的なアシスタントペイロードが同じメディア URL を繰り返す場合、最終配信では添付ファイルを再送信する代わりに重複メディアを取り除きます。
|
||||
|
||||
完全に重複する最終ペイロードは抑制されます。最終ペイロードが、すでにストリーミングされたメディアの周囲に別のテキストを追加する場合、OpenClaw はメディアを 1 回だけ配信したまま新しいテキストを送信します。これにより、エージェントがストリーミング中に `MEDIA:` を送出し、プロバイダーも完了返信にそれを含める場合に、Telegram などのチャンネルで音声メモやファイルが重複するのを防ぎます。
|
||||
完全に重複する最終ペイロードは抑制されます。最終ペイロードが、すでにストリーミングされたメディアの周囲に別個のテキストを追加している場合、OpenClaw はメディアを 1 回だけ配信したまま、新しいテキストを送信します。これにより、エージェントがストリーミング中に `MEDIA:` を送信し、プロバイダーも完了した返信にそれを含める場合に、Telegram などのチャンネルで音声メモやファイルが重複するのを防ぎます。
|
||||
|
||||
## チャンク化アルゴリズム（下限/上限）
|
||||
## チャンク化アルゴリズム（低/高境界）
|
||||
|
||||
ブロックチャンク化は `EmbeddedBlockChunker` によって実装されています。
|
||||
|
||||
- **下限:** バッファ >= `minChars` になるまで送出しません（強制時を除く）。
|
||||
- **上限:** `maxChars` より前での分割を優先します。強制時は `maxChars` で分割します。
|
||||
- **低境界:** バッファ >= `minChars` になるまで送信しません（強制時を除く）。
|
||||
- **高境界:** `maxChars` より前での分割を優先します。強制時は `maxChars` で分割します。
|
||||
- **区切り優先度:** `paragraph` → `newline` → `sentence` → `whitespace` → ハード区切り。
|
||||
- **コードフェンス:** フェンス内では決して分割しません。`maxChars` で強制される場合は、Markdown の妥当性を保つためにフェンスを閉じて再オープンします。
|
||||
- **コードフェンス:** フェンス内部では決して分割しません。`maxChars` で強制される場合は、Markdown の有効性を保つためにフェンスを閉じて再オープンします。
|
||||
|
||||
`maxChars` はチャンネルの `textChunkLimit` にクランプされるため、チャンネルごとの上限を超えることはできません。
|
||||
|
||||
## 結合（ストリーミングされたブロックのマージ）
|
||||
|
||||
ブロックストリーミングが有効な場合、OpenClaw は連続するブロックチャンクを送信前に**マージ**できます。これにより、段階的な出力を維持しながら「1 行だけのスパム」を減らせます。
|
||||
ブロックストリーミングが有効な場合、OpenClaw は送信前に**連続するブロックチャンクを結合**できます。これにより、段階的な出力を提供しながら「1 行だけの大量送信」を減らせます。
|
||||
|
||||
- 結合はフラッシュ前に**アイドル間隔**（`idleMs`）を待ちます。
|
||||
- バッファは `maxChars` で上限設定され、それを超えるとフラッシュされます。
|
||||
- `minChars` は、十分なテキストが蓄積されるまで小さな断片の送信を防ぎます（最終フラッシュでは残りのテキストが必ず送信されます）。
|
||||
- 結合は、フラッシュ前に**アイドル間隔**（`idleMs`）を待ちます。
|
||||
- バッファは `maxChars` で制限され、それを超えるとフラッシュされます。
|
||||
- `minChars` は、十分なテキストが蓄積されるまで小さな断片の送信を防ぎます（最終フラッシュでは常に残りのテキストを送信します）。
|
||||
- 結合文字列は `blockStreamingChunk.breakPreference` から導出されます（`paragraph` → `\n\n`、`newline` → `\n`、`sentence` → スペース）。
|
||||
- チャンネル上書きは `*.blockStreamingCoalesce` で利用できます（アカウント単位の設定を含む）。
|
||||
- チャンネル上書きは `*.blockStreamingCoalesce` で利用できます（アカウントごとの設定を含む）。
|
||||
- デフォルトの結合 `minChars` は、上書きされない限り Signal/Slack/Discord では 1500 に引き上げられます。
|
||||
|
||||
## ブロック間の人間らしいペース調整
|
||||
## ブロック間の人間らしいペーシング
|
||||
|
||||
ブロックストリーミングが有効な場合、ブロック返信の間（最初のブロックの後）に**ランダム化された一時停止**を追加できます。これにより、複数吹き出しの応答がより自然に感じられます。
|
||||
ブロックストリーミングが有効な場合、ブロック返信の間（最初のブロックの後）に**ランダム化された一時停止**を追加できます。これにより、複数の吹き出しからなる応答がより自然に感じられます。
|
||||
|
||||
- 設定: `agents.defaults.humanDelay`（`agents.list[].humanDelay` でエージェントごとに上書き）。
|
||||
- モード: `off`（デフォルト）、`natural`（800–2500ms）、`custom`（`minMs`/`maxMs`）。
|
||||
- 設定: `agents.defaults.humanDelay`（エージェントごとに `agents.list[].humanDelay` で上書き）。
|
||||
- モード: `off`（デフォルト）、`natural`（800〜2500ms）、`custom`（`minMs`/`maxMs`）。
|
||||
- **ブロック返信**にのみ適用され、最終返信やツール要約には適用されません。
|
||||
|
||||
## 「チャンクをストリーミングするか、すべてを送るか」
|
||||
|
||||
これは次に対応します。
|
||||
|
||||
- **チャンクをストリーミング:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（逐次送出）。Telegram 以外のチャンネルでは `*.blockStreaming: true` も必要です。
|
||||
- **最後にすべてをストリーミング:** `blockStreamingBreak: "message_end"`（1 回フラッシュ。非常に長い場合は複数チャンクになる可能性あり）。
|
||||
- **チャンクをストリーミング:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`（進行に合わせて送信）。Telegram 以外のチャンネルでは `*.blockStreaming: true` も必要です。
|
||||
- **最後にすべてをストリーミング:** `blockStreamingBreak: "message_end"`（1 回フラッシュ。非常に長い場合は複数チャンクになる可能性があります）。
|
||||
- **ブロックストリーミングなし:** `blockStreamingDefault: "off"`（最終返信のみ）。
|
||||
|
||||
**チャンネルの注意:** `*.blockStreaming` が明示的に `true` に設定されていない限り、ブロックストリーミングは**オフ**です。チャンネルはブロック返信なしでライブプレビュー（`channels.<channel>.streaming`）をストリーミングできます。
|
||||
**チャンネルの注記:** `*.blockStreaming` が明示的に `true` に設定されていない限り、ブロックストリーミングは**オフ**です。チャンネルは、ブロック返信なしでライブプレビュー（`channels.<channel>.streaming`）をストリーミングできます。
|
||||
|
||||
設定場所のリマインダー: `blockStreaming*` のデフォルトはルート設定ではなく `agents.defaults` 配下にあります。
|
||||
設定場所のリマインダー: `blockStreaming*` のデフォルトはルート設定ではなく、`agents.defaults` の下にあります。
|
||||
|
||||
## プレビューストリーミングモード
|
||||
|
||||
@ -115,20 +115,20 @@ Model output
|
||||
|
||||
- `off`: プレビューストリーミングを無効化します。
|
||||
- `partial`: 最新テキストで置き換えられる単一のプレビュー。
|
||||
- `block`: チャンク化/追記のステップでプレビューを更新します。
|
||||
- `progress`: 生成中の進捗/ステータスプレビュー、完了時に最終回答。
|
||||
- `block`: チャンク化/追記ステップでプレビューを更新します。
|
||||
- `progress`: 生成中の進捗/ステータスプレビュー、完了時の最終回答。
|
||||
|
||||
`streaming.mode: "block"` は、Discord や Telegram など編集可能なチャンネル向けのプレビューストリーミングモードです。そこでのチャンネルブロック配信を有効にするものではありません。通常のブロック返信が必要な場合は、`streaming.block.enabled` またはレガシーの `blockStreaming` チャンネルキーを使用してください。Microsoft Teams は例外です。下書きプレビューのブロックトランスポートがないため、`streaming.mode: "block"` はネイティブの partial/progress ストリーミングではなく Teams のブロック配信にマップされます。
|
||||
`streaming.mode: "block"` は、Discord や Telegram などの編集可能なチャンネル向けのプレビューストリーミングモードです。これは、そのチャンネルでチャンネルブロック配信を有効にするものではありません。通常のブロック返信が必要な場合は、`streaming.block.enabled` またはレガシーの `blockStreaming` チャンネルキーを使います。Microsoft Teams は例外です。下書きプレビューのブロック転送がないため、`streaming.mode: "block"` はネイティブの部分/進捗ストリーミングではなく Teams のブロック配信にマップされます。
|
||||
|
||||
### チャンネルマッピング
|
||||
|
||||
| チャンネル | `off` | `partial` | `block` | `progress` |
|
||||
| ---------- | ----- | --------- | ------- | ----------------------- |
|
||||
| ---------- | ----- | --------- | ------- | ---------- |
|
||||
| Telegram | ✅ | ✅ | ✅ | 編集可能な進捗下書き |
|
||||
| Discord | ✅ | ✅ | ✅ | 編集可能な進捗下書き |
|
||||
| Slack | ✅ | ✅ | ✅ | ✅ |
|
||||
| Mattermost | ✅ | ✅ | ✅ | ✅ |
|
||||
| MS Teams | ✅ | ✅ | ✅ | ネイティブ進捗ストリーム |
|
||||
| Slack | ✅ | ✅ | ✅ | ✅ |
|
||||
| Mattermost | ✅ | ✅ | ✅ | ✅ |
|
||||
| MS Teams | ✅ | ✅ | ✅ | ネイティブ進捗ストリーム |
|
||||
|
||||
Slack のみ:
|
||||
|
||||
@ -137,60 +137,60 @@ Slack のみ:
|
||||
|
||||
レガシーキーの移行:
|
||||
|
||||
- Telegram: レガシーの `streamMode` とスカラー/ブール値の `streaming` は、doctor/config 互換パスによって検出され、`streaming.mode` に移行されます。
|
||||
- Discord: `streamMode` + ブール値の `streaming` は `streaming` enum に自動移行されます。
|
||||
- Slack: `streamMode` は `streaming.mode` に自動移行されます。ブール値の `streaming` は `streaming.mode` と `streaming.nativeTransport` に自動移行されます。レガシーの `nativeStreaming` は `streaming.nativeTransport` に自動移行されます。
|
||||
- Telegram: レガシーの `streamMode` とスカラー/ブール値の `streaming` は、doctor/設定互換パスによって検出され、`streaming.mode` に移行されます。
|
||||
- Discord: `streamMode` + ブール値の `streaming` は `streaming` 列挙型へ自動移行されます。
|
||||
- Slack: `streamMode` は `streaming.mode` へ自動移行されます。ブール値の `streaming` は `streaming.mode` と `streaming.nativeTransport` へ自動移行されます。レガシーの `nativeStreaming` は `streaming.nativeTransport` へ自動移行されます。
|
||||
|
||||
### ランタイム動作
|
||||
|
||||
Telegram:
|
||||
|
||||
- DM とグループ/トピック全体で `sendMessage` + `editMessageText` のプレビュー更新を使用します。
|
||||
- プレビューが約 1 分間表示されていた場合、インプレース編集の代わりに新しい最終メッセージを送信し、その後プレビューをクリーンアップして Telegram のタイムスタンプが返信完了を反映するようにします。
|
||||
- Telegram のブロックストリーミングが明示的に有効な場合、プレビューストリーミングはスキップされます（二重ストリーミングを避けるため）。
|
||||
- `/reasoning stream` は推論をプレビューに書き込めます。
|
||||
- DM とグループ/トピック全体で、`sendMessage` + `editMessageText` のプレビュー更新を使います。
|
||||
- プレビューが約 1 分間表示されていた場合、インプレース編集ではなく新しい最終メッセージを送信し、その後プレビューをクリーンアップして Telegram のタイムスタンプが返信完了を反映するようにします。
|
||||
- Telegram のブロックストリーミングが明示的に有効な場合、二重ストリーミングを避けるためにプレビューストリーミングはスキップされます。
|
||||
- `/reasoning stream` は、一時的なプレビューに推論を書き込み、最終配信後に削除できます。
|
||||
|
||||
Discord:
|
||||
|
||||
- 送信 + 編集のプレビューメッセージを使用します。
|
||||
- `block` モードは下書きチャンク化（`draftChunk`）を使用します。
|
||||
- 送信 + 編集のプレビューメッセージを使います。
|
||||
- `block` モードは下書きチャンク化（`draftChunk`）を使います。
|
||||
- Discord のブロックストリーミングが明示的に有効な場合、プレビューストリーミングはスキップされます。
|
||||
- 最終メディア、エラー、明示的返信ペイロードは、新しい下書きをフラッシュせずに保留中のプレビューをキャンセルし、その後通常の配信を使用します。
|
||||
- 最終メディア、エラー、明示的返信ペイロードは、新しい下書きをフラッシュせずに保留中のプレビューをキャンセルし、その後通常配信を使います。
|
||||
|
||||
Slack:
|
||||
|
||||
- `partial` は、利用可能な場合に Slack ネイティブストリーミング（`chat.startStream`/`append`/`stop`）を使用できます。
|
||||
- `block` は追記形式の下書きプレビューを使用します。
|
||||
- `progress` はステータスプレビューテキストを使用し、その後最終回答を送信します。
|
||||
- 返信スレッドのないトップレベル DM では、Slack ネイティブストリーミングの代わりに下書きプレビュー投稿と編集を使用します。
|
||||
- ネイティブおよび下書きのプレビューストリーミングは、そのターンのブロック返信を抑制するため、Slack の返信は 1 つの配信経路だけでストリーミングされます。
|
||||
- 最終メディア/エラーペイロードと進捗の最終出力は、使い捨ての下書きメッセージを作成しません。プレビューを編集できるテキスト/ブロックの最終出力だけが、保留中の下書きテキストをフラッシュします。
|
||||
- `partial` は、利用可能な場合に Slack ネイティブストリーミング（`chat.startStream`/`append`/`stop`）を使えます。
|
||||
- `block` は追記形式の下書きプレビューを使います。
|
||||
- `progress` はステータスプレビューテキストを使い、その後に最終回答を送信します。
|
||||
- 返信スレッドのないトップレベル DM は、Slack ネイティブストリーミングの代わりに下書きプレビュー投稿と編集を使います。
|
||||
- ネイティブおよび下書きプレビューストリーミングは、そのターンのブロック返信を抑制するため、Slack の返信は 1 つの配信パスだけでストリーミングされます。
|
||||
- 最終メディア/エラーペイロードと進捗の最終送信は、使い捨ての下書きメッセージを作成しません。プレビューを編集できるテキスト/ブロックの最終送信のみが、保留中の下書きテキストをフラッシュします。
|
||||
|
||||
Mattermost:
|
||||
|
||||
- 思考、ツールアクティビティ、部分返信テキストを 1 つの下書きプレビュー投稿にストリーミングし、最終回答を安全に送信できるときにインプレースで最終化します。
|
||||
- 最終化時にプレビュー投稿が削除されている、または利用できない場合は、新しい最終投稿の送信にフォールバックします。
|
||||
- 最終メディア/エラーペイロードは、一時的なプレビュー投稿をフラッシュする代わりに、通常の配信前に保留中のプレビュー更新をキャンセルします。
|
||||
- 思考、ツールアクティビティ、部分返信テキストを単一の下書きプレビュー投稿にストリーミングし、最終回答を安全に送信できるときにインプレースで確定します。
|
||||
- プレビュー投稿が削除された、または確定時に利用できない場合は、新しい最終投稿の送信にフォールバックします。
|
||||
- 最終メディア/エラーペイロードは、一時的なプレビュー投稿をフラッシュする代わりに、通常配信の前に保留中のプレビュー更新をキャンセルします。
|
||||
|
||||
Matrix:
|
||||
|
||||
- 最終テキストがプレビューイベントを再利用できる場合、下書きプレビューはインプレースで最終化されます。
|
||||
- メディアのみ、エラー、返信ターゲット不一致の最終出力は、通常の配信前に保留中のプレビュー更新をキャンセルします。すでに表示されている古いプレビューは取り消されます。
|
||||
- 下書きプレビューは、最終テキストがプレビューイベントを再利用できる場合にインプレースで確定します。
|
||||
- メディアのみ、エラー、返信ターゲット不一致の最終送信は、通常配信の前に保留中のプレビュー更新をキャンセルします。すでに表示されている古いプレビューは削除されます。
|
||||
|
||||
### ツール進捗プレビュー更新
|
||||
|
||||
プレビューストリーミングには、**ツール進捗**更新も含められます。これは「ウェブを検索中」、「ファイルを読み込み中」、「ツールを呼び出し中」のような短いステータス行で、ツール実行中に最終返信より前に同じプレビューメッセージへ表示されます。これにより、複数ステップのツールターンが、最初の思考プレビューと最終回答の間で沈黙せず、視覚的に動き続けます。
|
||||
プレビューストリーミングには、**ツール進捗**更新も含められます。これは「Web を検索中」「ファイルを読み取り中」「ツールを呼び出し中」のような短いステータス行で、ツールの実行中、最終返信の前に同じプレビューメッセージ内に表示されます。これにより、複数ステップのツールターンが、最初の思考プレビューと最終回答の間で沈黙するのではなく、視覚的に進行中であることを示せます。
|
||||
|
||||
対応サーフェス:
|
||||
|
||||
- **Discord**、**Slack**、**Telegram**、**Matrix** は、プレビューストリーミングがアクティブな場合、デフォルトでツール進捗をライブプレビュー編集にストリーミングします。Microsoft Teams は個人チャットでネイティブの進捗ストリームを使用します。
|
||||
- Telegram は `v2026.4.22` 以降、ツール進捗プレビュー更新を有効にした状態で出荷されています。有効なままにすることで、そのリリース済み動作を維持できます。
|
||||
- **Mattermost** はすでにツールアクティビティを単一の下書きプレビュー投稿に組み込んでいます（上記参照）。
|
||||
- ツール進捗の編集はアクティブなプレビューストリーミングモードに従います。プレビューストリーミングが `off` の場合、またはブロックストリーミングがメッセージを引き継いだ場合はスキップされます。Telegram では、`streaming.mode: "off"` は final-only です。汎用の進捗チャットもスタンドアロンのステータスメッセージとして配信される代わりに抑制されますが、承認プロンプト、メディアペイロード、エラーは通常どおりルーティングされます。
|
||||
- プレビューストリーミングは維持しつつツール進捗行を非表示にするには、そのチャンネルの `streaming.preview.toolProgress` を `false` に設定します。プレビュー編集を完全に無効化するには、`streaming.mode` を `off` に設定します。
|
||||
- Telegram の選択引用返信は例外です。`replyToMode` が `"off"` ではなく、選択された引用テキストが存在する場合、OpenClaw はそのターンの回答プレビューストリームをスキップするため、ツール進捗プレビュー行はレンダリングできません。選択引用テキストのない現在メッセージへの返信では、プレビューストリーミングは引き続き維持されます。詳細は [Telegram チャンネルドキュメント](/ja-JP/channels/telegram) を参照してください。
|
||||
- **Discord**、**Slack**、**Telegram**、**Matrix** は、プレビューストリーミングがアクティブな場合、デフォルトでツール進捗をライブプレビュー編集へストリーミングします。Microsoft Teams は個人チャットでネイティブ進捗ストリームを使います。
|
||||
- Telegram は `v2026.4.22` 以降、ツール進捗プレビュー更新を有効にした状態でリリースされています。有効のままにすることで、そのリリース済み動作が維持されます。
|
||||
- **Mattermost** は、すでにツールアクティビティを単一の下書きプレビュー投稿に取り込みます（上記参照）。
|
||||
- ツール進捗編集は、アクティブなプレビューストリーミングモードに従います。プレビューストリーミングが `off` の場合、またはブロックストリーミングがメッセージを引き継いだ場合はスキップされます。Telegram では、`streaming.mode: "off"` は最終送信のみです。承認プロンプト、メディアペイロード、エラーは引き続き通常どおりルーティングされますが、一般的な進捗チャットも単独のステータスメッセージとして配信されずに抑制されます。
|
||||
- プレビューストリーミングは維持しつつツール進捗行を非表示にするには、そのチャンネルの `streaming.preview.toolProgress` を `false` に設定します。コマンド/実行テキストを非表示にしつつツール進捗行を表示し続けるには、`streaming.preview.commandText` を `"status"` に設定するか、`streaming.progress.commandText` を `"status"` に設定します。デフォルトはリリース済み動作を維持するため `"raw"` です。このポリシーは、OpenClaw のコンパクトな進捗レンダラーを使う下書き/進捗チャンネルで共有されます。これには Discord、Matrix、Microsoft Teams、Mattermost、Slack 下書きプレビュー、Telegram が含まれます。プレビュー編集を完全に無効にするには、`streaming.mode` を `off` に設定します。
|
||||
- Telegram の選択引用返信は例外です。`replyToMode` が `"off"` ではなく、選択された引用テキストが存在する場合、OpenClaw はそのターンの回答プレビューストリームをスキップするため、ツール進捗プレビュー行は表示されません。選択引用テキストのない現在メッセージへの返信では、引き続きプレビューストリーミングが維持されます。詳細は [Telegram チャンネルドキュメント](/ja-JP/channels/telegram) を参照してください。
|
||||
|
||||
例:
|
||||
進行状況行は表示したまま、未加工のコマンド/exec テキストは非表示にします。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -199,7 +199,26 @@ Matrix:
|
||||
"streaming": {
|
||||
"mode": "partial",
|
||||
"preview": {
|
||||
"toolProgress": false
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
同じ形を別のコンパクトな進行状況チャンネルキーの下で使用します。たとえば、`channels.discord`、`channels.matrix`、`channels.msteams`、`channels.mattermost`、または Slack ドラフトプレビューです。進行状況ドラフトモードでは、同じポリシーを `streaming.progress` の下に置きます。
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -209,7 +228,7 @@ Matrix:
|
||||
|
||||
## 関連
|
||||
|
||||
- [進捗下書き](/ja-JP/concepts/progress-drafts) — 長いターン中に更新される、表示可能な作業中メッセージ
|
||||
- [進行状況ドラフト](/ja-JP/concepts/progress-drafts) — 長いターン中に更新される、表示可能な作業中メッセージ
|
||||
- [メッセージ](/ja-JP/concepts/messages) — メッセージのライフサイクルと配信
|
||||
- [リトライ](/ja-JP/concepts/retry) — 配信失敗時のリトライ動作
|
||||
- [再試行](/ja-JP/concepts/retry) — 配信失敗時の再試行動作
|
||||
- [チャンネル](/ja-JP/channels) — チャンネルごとのストリーミング対応
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,63 +1,63 @@
|
||||
---
|
||||
read_when:
|
||||
- OpenClawを更新する
|
||||
- OpenClaw の更新
|
||||
- 更新後に問題が発生する
|
||||
summary: OpenClaw を安全に更新する方法（グローバルインストールまたはソースから）とロールバック戦略
|
||||
summary: OpenClaw を安全に更新する（グローバルインストールまたはソースから）方法とロールバック戦略
|
||||
title: 更新
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:35:33Z"
|
||||
generated_at: "2026-05-04T07:03:01Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f9e26ea71748dfd1573cdca01126bf29ebc56be56eac604e2b6a009b463820d1
|
||||
source_hash: 3c9ff1d70d74f45efea3c148718e5cbc74001ce3d924b760edc4d68622d23714
|
||||
source_path: install/updating.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClawを最新の状態に保ちます。
|
||||
OpenClaw を最新の状態に保ちます。
|
||||
|
||||
## 推奨: `openclaw update`
|
||||
|
||||
更新する最速の方法です。インストール種別（npm または git）を検出し、最新バージョンを取得し、`openclaw doctor` を実行して、Gatewayを再起動します。
|
||||
更新する最速の方法です。インストール種別 (npm または git) を検出し、最新バージョンを取得し、`openclaw doctor` を実行して、gateway を再起動します。
|
||||
|
||||
```bash
|
||||
openclaw update
|
||||
```
|
||||
|
||||
チャネルを切り替える、または特定のバージョンを対象にするには:
|
||||
チャンネルを切り替える、または特定のバージョンを対象にするには:
|
||||
|
||||
```bash
|
||||
openclaw update --channel beta
|
||||
openclaw update --channel dev
|
||||
openclaw update --tag main
|
||||
openclaw update --dry-run # preview without applying
|
||||
openclaw update --dry-run # 適用せずにプレビュー
|
||||
```
|
||||
|
||||
`openclaw update` は `--verbose` を受け付けません。更新診断には、予定されている操作をプレビューする `--dry-run`、構造化された結果を得る `--json`、またはチャネルと利用可能状態を確認する `openclaw update status --json` を使用します。インストーラーには独自の `--verbose` フラグがありますが、そのフラグは `openclaw update` の一部ではありません。
|
||||
`openclaw update` は `--verbose` を受け付けません。更新診断には、予定されている操作をプレビューする `--dry-run`、構造化された結果を得る `--json`、またはチャンネルと利用可能状態を確認する `openclaw update status --json` を使用してください。インストーラーには独自の `--verbose` フラグがありますが、そのフラグは `openclaw update` の一部ではありません。
|
||||
|
||||
`--channel beta` は beta を優先しますが、beta タグが存在しない場合、または最新の stable リリースより古い場合、ランタイムは stable/latest にフォールバックします。1回限りのパッケージ更新で npm の未加工の beta dist-tag を使いたい場合は、`--tag beta` を使用します。
|
||||
`--channel beta` は beta を優先しますが、beta タグがない場合、または最新の安定版リリースより古い場合、runtime は stable/latest にフォールバックします。1 回限りのパッケージ更新で生の npm beta dist-tag を使いたい場合は、`--tag beta` を使用してください。
|
||||
|
||||
チャネルの意味については、[開発チャネル](/ja-JP/install/development-channels)を参照してください。
|
||||
チャンネルの意味については、[開発チャンネル](/ja-JP/install/development-channels)を参照してください。
|
||||
|
||||
## npm インストールと git インストールを切り替える
|
||||
|
||||
インストール種別を変更したい場合はチャネルを使用します。アップデーターは `~/.openclaw` 内の状態、設定、認証情報、ワークスペースを保持します。変更されるのは、CLI と Gateway が使用する OpenClaw コードのインストールだけです。
|
||||
インストール種別を変更したい場合はチャンネルを使用します。アップデーターは `~/.openclaw` 内の状態、設定、認証情報、ワークスペースを保持します。変更するのは、CLI と gateway が使用する OpenClaw コードのインストール先だけです。
|
||||
|
||||
```bash
|
||||
# npm package install -> editable git checkout
|
||||
# npm パッケージインストール -> 編集可能な git checkout
|
||||
openclaw update --channel dev
|
||||
|
||||
# git checkout -> npm package install
|
||||
# git checkout -> npm パッケージインストール
|
||||
openclaw update --channel stable
|
||||
```
|
||||
|
||||
まず `--dry-run` で実行して、正確なインストールモード切り替えをプレビューします。
|
||||
正確なインストールモード切り替えをプレビューするには、まず `--dry-run` 付きで実行します:
|
||||
|
||||
```bash
|
||||
openclaw update --channel dev --dry-run
|
||||
openclaw update --channel stable --dry-run
|
||||
```
|
||||
|
||||
`dev` チャネルは git チェックアウトを用意し、それをビルドして、そのチェックアウトからグローバル CLI をインストールします。`stable` と `beta` チャネルはパッケージインストールを使用します。Gateway がすでにインストールされている場合、`--no-restart` を渡さない限り、`openclaw update` はサービスメタデータを更新して再起動します。
|
||||
`dev` チャンネルは git checkout を確保し、それをビルドして、その checkout からグローバル CLI をインストールします。`stable` と `beta` チャンネルはパッケージインストールを使用します。gateway がすでにインストールされている場合、`openclaw update` はサービスメタデータを更新し、`--no-restart` を渡さない限り再起動します。
|
||||
|
||||
## 代替: インストーラーを再実行する
|
||||
|
||||
@ -67,25 +67,27 @@ curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
|
||||
オンボーディングをスキップするには `--no-onboard` を追加します。インストーラー経由で特定のインストール種別を強制するには、`--install-method git --no-onboard` または `--install-method npm --no-onboard` を渡します。
|
||||
|
||||
npm パッケージのインストール段階の後に `openclaw update` が失敗した場合は、インストーラーを再実行します。インストーラーは古いアップデーターを呼び出しません。グローバルパッケージのインストールを直接実行し、部分的に更新された npm インストールを復旧できます。
|
||||
npm パッケージインストール段階の後で `openclaw update` が失敗した場合は、インストーラーを再実行してください。インストーラーは古いアップデーターを呼び出しません。グローバルパッケージインストールを直接実行し、部分的に更新された npm インストールを復旧できます。
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
|
||||
```
|
||||
|
||||
復旧を特定のバージョンまたは dist-tag に固定するには、`--version` を追加します。
|
||||
復旧を特定のバージョンまたは dist-tag に固定するには、`--version` を追加します:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
|
||||
```
|
||||
|
||||
## 代替: 手動の npm、pnpm、または bun
|
||||
## 代替: 手動で npm、pnpm、または bun を使う
|
||||
|
||||
```bash
|
||||
npm i -g openclaw@latest
|
||||
```
|
||||
|
||||
`openclaw update` がグローバル npm インストールを管理する場合、まず一時的な npm prefix に対象をインストールし、パッケージ化された `dist` インベントリを検証してから、クリーンなパッケージツリーを実際のグローバル prefix に入れ替えます。これにより、npm が古いパッケージの古いファイルの上に新しいパッケージを重ねてしまうことを避けられます。インストールコマンドが失敗した場合、OpenClaw は `--omit=optional` を付けて1回再試行します。この再試行は、ネイティブの任意依存関係をコンパイルできないホストで役立ちます。一方で、フォールバックも失敗した場合は元の失敗が見える状態を保ちます。
|
||||
管理下のインストールでは `openclaw update` を推奨します。実行中の Gateway サービスとパッケージ入れ替えを調整できるためです。管理下の Gateway が実行中の状態で手動更新する場合は、パッケージマネージャーの完了直後に Gateway を再起動してください。古いプロセスが置き換え済みのパッケージファイルから提供し続けないようにするためです。
|
||||
|
||||
`openclaw update` がグローバル npm インストールを管理する場合、まず対象を一時的な npm prefix にインストールし、パッケージ化された `dist` インベントリを検証してから、クリーンなパッケージツリーを実際のグローバル prefix に入れ替えます。これにより、npm が古いパッケージ由来の古いファイルの上に新しいパッケージを重ねることを避けられます。インストールコマンドが失敗した場合、OpenClaw は `--omit=optional` 付きで 1 回再試行します。この再試行は、ネイティブのオプション依存関係をコンパイルできないホストで役立ちます。一方で、フォールバックも失敗した場合は元の失敗が見えるままになります。
|
||||
|
||||
```bash
|
||||
pnpm add -g openclaw@latest
|
||||
@ -95,17 +97,17 @@ pnpm add -g openclaw@latest
|
||||
bun add -g openclaw@latest
|
||||
```
|
||||
|
||||
### npm インストールの高度なトピック
|
||||
### 高度な npm インストールのトピック
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="読み取り専用パッケージツリー">
|
||||
OpenClaw は、現在のユーザーがグローバルパッケージディレクトリに書き込める場合でも、パッケージ化されたグローバルインストールを実行時には読み取り専用として扱います。Plugin パッケージのインストール先は、ユーザー設定ディレクトリ配下にある OpenClaw 所有の npm/git ルートです。Gateway の起動時に OpenClaw パッケージツリーは変更されません。
|
||||
OpenClaw は、グローバルパッケージディレクトリが現在のユーザーによって書き込み可能な場合でも、パッケージ化されたグローバルインストールを runtime では読み取り専用として扱います。Plugin パッケージインストールは、ユーザー設定ディレクトリ配下の OpenClaw 所有の npm/git ルートに配置され、Gateway 起動時に OpenClaw パッケージツリーは変更されません。
|
||||
|
||||
一部の Linux npm セットアップでは、`/usr/lib/node_modules/openclaw` など root 所有のディレクトリ配下にグローバルパッケージをインストールします。Plugin のインストール/更新コマンドはそのグローバルパッケージディレクトリの外へ書き込むため、OpenClaw はそのレイアウトをサポートします。
|
||||
一部の Linux npm セットアップでは、`/usr/lib/node_modules/openclaw` のような root 所有ディレクトリ配下にグローバルパッケージをインストールします。Plugin のインストール/更新コマンドはそのグローバルパッケージディレクトリの外側に書き込むため、OpenClaw はそのレイアウトをサポートします。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="強化された systemd ユニット">
|
||||
明示的な Plugin インストール、Plugin 更新、doctor クリーンアップが変更を永続化できるように、OpenClaw の設定/状態ルートへの書き込みアクセスを付与します。
|
||||
明示的な Plugin インストール、Plugin 更新、doctor クリーンアップが変更を永続化できるように、OpenClaw に設定/状態ルートへの書き込みアクセス権を与えます:
|
||||
|
||||
```ini
|
||||
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
|
||||
@ -113,13 +115,13 @@ bun add -g openclaw@latest
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="ディスク容量の事前確認">
|
||||
パッケージ更新と明示的な Plugin インストールの前に、OpenClaw は対象ボリュームのディスク容量をベストエフォートで確認しようとします。容量不足の場合は確認されたパスを含む警告が表示されますが、ファイルシステムのクォータ、スナップショット、ネットワークボリュームは確認後に変化する可能性があるため、更新はブロックされません。実際のパッケージマネージャーによるインストールとインストール後の検証が引き続き信頼できる基準です。
|
||||
パッケージ更新と明示的な Plugin インストールの前に、OpenClaw は対象ボリュームのディスク容量をベストエフォートで確認しようとします。容量不足の場合は確認したパスとともに警告が出ますが、更新はブロックされません。ファイルシステムのクォータ、スナップショット、ネットワークボリュームは確認後に変わる可能性があるためです。実際のパッケージマネージャーによるインストールとインストール後の検証が引き続き信頼できる根拠です。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 自動アップデーター
|
||||
|
||||
自動アップデーターはデフォルトではオフです。`~/.openclaw/openclaw.json` で有効にします。
|
||||
自動アップデーターはデフォルトではオフです。`~/.openclaw/openclaw.json` で有効にします:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -135,16 +137,16 @@ bun add -g openclaw@latest
|
||||
}
|
||||
```
|
||||
|
||||
| チャネル | 動作 |
|
||||
| -------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | `stableDelayHours` 待機し、その後 `stableJitterHours` にわたる決定的ジッター（分散ロールアウト）で適用します。 |
|
||||
| `beta` | `betaCheckIntervalHours` ごと（デフォルト: 1時間ごと）に確認し、すぐに適用します。 |
|
||||
| `dev` | 自動適用はありません。`openclaw update` を手動で使用します。 |
|
||||
| チャンネル | 動作 |
|
||||
| -------- | ------------------------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | `stableDelayHours` 待機した後、`stableJitterHours` 全体にわたる決定的なジッターで適用します (段階的ロールアウト)。 |
|
||||
| `beta` | `betaCheckIntervalHours` ごと (デフォルト: 1 時間ごと) に確認し、即座に適用します。 |
|
||||
| `dev` | 自動適用はありません。`openclaw update` を手動で使用してください。 |
|
||||
|
||||
Gateway は起動時にも更新ヒントをログに出力します（`update.checkOnStart: false` で無効化）。
|
||||
ダウングレードやインシデント復旧では、Gateway 環境で `OPENCLAW_NO_AUTO_UPDATE=1` を設定すると、`update.auto.enabled` が設定されていても自動適用をブロックできます。`update.checkOnStart` も無効化されていない限り、起動時の更新ヒントは引き続き実行される可能性があります。
|
||||
gateway は起動時にも更新ヒントをログ出力します (`update.checkOnStart: false` で無効化)。
|
||||
ダウングレードまたはインシデント復旧では、Gateway 環境で `OPENCLAW_NO_AUTO_UPDATE=1` を設定して、`update.auto.enabled` が設定されている場合でも自動適用をブロックします。`update.checkOnStart` も無効化しない限り、起動時の更新ヒントは引き続き実行できます。
|
||||
|
||||
ライブ Gateway コントロールプレーンハンドラー経由で要求されたパッケージマネージャー更新では、パッケージ入れ替え後に、延期なし、クールダウンなしの更新再起動が強制されます。これにより、すでに置き換え済みのパッケージツリーからチャンクを遅延読み込みするほど古いインメモリプロセスが残ることを避けられます。監督下のインストールでは、更新の前後でサービスを停止および再起動できるため、シェルの `openclaw update` が推奨される経路です。
|
||||
稼働中の Gateway コントロールプレーンハンドラー経由で要求されたパッケージマネージャー更新は、パッケージ入れ替え後に、遅延なし、クールダウンなしの更新再起動を強制します。これにより、すでに置き換えられたパッケージツリーからチャンクを遅延読み込みできるほど長く、古いインメモリプロセスが残ることを避けます。Shell の `openclaw update` は、更新の前後でサービスを停止して再起動できるため、管理下のインストールでは引き続き推奨される経路です。
|
||||
|
||||
## 更新後
|
||||
|
||||
@ -156,9 +158,9 @@ Gateway は起動時にも更新ヒントをログに出力します（`update.c
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
設定を移行し、DM ポリシーを監査し、Gateway の健全性を確認します。詳細: [Doctor](/ja-JP/gateway/doctor)
|
||||
設定を移行し、DM ポリシーを監査し、gateway の健全性を確認します。詳細: [Doctor](/ja-JP/gateway/doctor)
|
||||
|
||||
### Gateway を再起動する
|
||||
### gateway を再起動する
|
||||
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
@ -174,7 +176,7 @@ openclaw health
|
||||
|
||||
## ロールバック
|
||||
|
||||
### バージョンを固定する（npm）
|
||||
### バージョンを固定する (npm)
|
||||
|
||||
```bash
|
||||
npm i -g openclaw@<version>
|
||||
@ -186,7 +188,7 @@ openclaw gateway restart
|
||||
`npm view openclaw version` は現在公開されているバージョンを表示します。
|
||||
</Tip>
|
||||
|
||||
### コミットを固定する（ソース）
|
||||
### コミットを固定する (source)
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
@ -195,17 +197,17 @@ pnpm install && pnpm build
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
最新へ戻すには: `git checkout main && git pull`。
|
||||
最新に戻すには: `git checkout main && git pull`。
|
||||
|
||||
## 行き詰まった場合
|
||||
|
||||
- もう一度 `openclaw doctor` を実行し、出力を注意深く読んでください。
|
||||
- ソースチェックアウト上で `openclaw update --channel dev` を実行する場合、必要に応じてアップデーターが `pnpm` を自動ブートストラップします。pnpm/corepack のブートストラップエラーが表示された場合は、`pnpm` を手動でインストールする（または `corepack` を再有効化する）してから、更新を再実行してください。
|
||||
- `openclaw doctor` をもう一度実行し、出力を注意深く読んでください。
|
||||
- ソース checkout 上で `openclaw update --channel dev` を実行する場合、必要に応じてアップデーターが `pnpm` を自動ブートストラップします。pnpm/corepack のブートストラップエラーが表示された場合は、`pnpm` を手動でインストールする (または `corepack` を再度有効化する) して、更新を再実行してください。
|
||||
- 確認: [トラブルシューティング](/ja-JP/gateway/troubleshooting)
|
||||
- Discord で質問する: [https://discord.gg/clawd](https://discord.gg/clawd)
|
||||
- Discord で質問: [https://discord.gg/clawd](https://discord.gg/clawd)
|
||||
|
||||
## 関連
|
||||
|
||||
- [インストール概要](/ja-JP/install): すべてのインストール方法。
|
||||
- [Doctor](/ja-JP/gateway/doctor): 更新後の健全性チェック。
|
||||
- [Doctor](/ja-JP/gateway/doctor): 更新後の健全性確認。
|
||||
- [移行](/ja-JP/install/migrating): メジャーバージョン移行ガイド。
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,38 +1,38 @@
|
||||
---
|
||||
read_when:
|
||||
- OpenClaw で ElevenLabs の text-to-speech を使いたい場合
|
||||
- 音声添付ファイルに ElevenLabs Scribe speech-to-text を使いたい場合
|
||||
- Voice Call に ElevenLabs の realtime transcription を使いたい場合
|
||||
summary: OpenClaw で ElevenLabs の speech、Scribe STT、Realtime transcription を使う
|
||||
- OpenClawでElevenLabsのテキスト読み上げを使いたい
|
||||
- 音声添付ファイルに ElevenLabs Scribe の音声テキスト変換を使いたい
|
||||
- 音声通話または Google Meet で ElevenLabs のリアルタイム文字起こしを使用したい場合
|
||||
summary: OpenClawでElevenLabs音声、Scribe STT、リアルタイム文字起こしを使う
|
||||
title: ElevenLabs
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T13:57:09Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-04T07:04:03Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 1f858a344228c6355cd5fdc3775cddac39e0075f2e9fcf7683271f11be03a31a
|
||||
source_hash: 4c880bf9dcab01ef70779c74576c70ea5d0203b96b5f739291842fafcb4bdb4b
|
||||
source_path: providers/elevenlabs.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw は、text-to-speech、Scribe
|
||||
v2 によるバッチ speech-to-text、そして Scribe v2 Realtime による Voice Call ストリーミング STT に ElevenLabs を使います。
|
||||
OpenClaw は、テキスト読み上げに ElevenLabs、Scribe
|
||||
v2 によるバッチ音声テキスト化、Scribe v2 Realtime によるストリーミング STT を使用します。
|
||||
|
||||
| Capability | OpenClaw 画面 | デフォルト |
|
||||
| ------------------------ | ----------------------------------------------- | -------------------------- |
|
||||
| Text-to-speech | `messages.tts` / `talk` | `eleven_multilingual_v2` |
|
||||
| Batch speech-to-text | `tools.media.audio` | `scribe_v2` |
|
||||
| Streaming speech-to-text | Voice Call `streaming.provider: "elevenlabs"` | `scribe_v2_realtime` |
|
||||
| 機能 | OpenClaw のサーフェス | デフォルト |
|
||||
| ------------------------ | -------------------------------------------------------------------- | ------------------------ |
|
||||
| テキスト読み上げ | `messages.tts` / `talk` | `eleven_multilingual_v2` |
|
||||
| バッチ音声テキスト化 | `tools.media.audio` | `scribe_v2` |
|
||||
| ストリーミング音声テキスト化 | Voice Call ストリーミングまたは Google Meet `realtime.transcriptionProvider` | `scribe_v2_realtime` |
|
||||
|
||||
## 認証
|
||||
|
||||
環境変数に `ELEVENLABS_API_KEY` を設定してください。既存の ElevenLabs ツールとの
|
||||
互換性のため、`XI_API_KEY` も受け付けられます。
|
||||
環境で `ELEVENLABS_API_KEY` を設定します。既存の ElevenLabs ツールとの互換性のため、
|
||||
`XI_API_KEY` も受け付けられます。
|
||||
|
||||
```bash
|
||||
export ELEVENLABS_API_KEY="..."
|
||||
```
|
||||
|
||||
## Text-to-speech
|
||||
## テキスト読み上げ
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -50,12 +50,12 @@ export ELEVENLABS_API_KEY="..."
|
||||
}
|
||||
```
|
||||
|
||||
ElevenLabs v3 TTS を使うには `modelId` を `eleven_v3` に設定してください。OpenClaw は既存インストール向けのデフォルトとして
|
||||
`eleven_multilingual_v2` を維持しています。
|
||||
ElevenLabs v3 TTS を使用するには、`modelId` を `eleven_v3` に設定します。OpenClaw は既存のインストール向けに、
|
||||
`eleven_multilingual_v2` をデフォルトのままにします。
|
||||
|
||||
## Speech-to-text
|
||||
## 音声テキスト化
|
||||
|
||||
受信音声添付ファイルや短い録音音声セグメントには Scribe v2 を使います。
|
||||
受信音声添付ファイルと短い録音音声セグメントには Scribe v2 を使用します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -70,22 +70,21 @@ ElevenLabs v3 TTS を使うには `modelId` を `eleven_v3` に設定してく
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw は multipart 音声を ElevenLabs の `/v1/speech-to-text` に
|
||||
`model_id: "scribe_v2"` 付きで送信します。言語ヒントがある場合は `language_code` にマッピングされます。
|
||||
OpenClaw は、`model_id: "scribe_v2"` を指定してマルチパート音声を ElevenLabs `/v1/speech-to-text` に送信します。言語ヒントがある場合は `language_code` にマッピングされます。
|
||||
|
||||
## Voice Call ストリーミング STT
|
||||
## ストリーミング STT
|
||||
|
||||
バンドルされた `elevenlabs` Plugin は、Voice Call
|
||||
ストリーミング文字起こし用に Scribe v2 Realtime を登録します。
|
||||
同梱の `elevenlabs` Plugin は、Voice Call と
|
||||
Google Meet エージェントモードのストリーミング文字起こし向けに Scribe v2 Realtime を登録します。
|
||||
|
||||
| Setting | Config path | デフォルト |
|
||||
| --------------- | ------------------------------------------------------------------------- | --------------------------------------------------- |
|
||||
| API key | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | `ELEVENLABS_API_KEY` / `XI_API_KEY` にフォールバック |
|
||||
| Model | `...elevenlabs.modelId` | `scribe_v2_realtime` |
|
||||
| Audio format | `...elevenlabs.audioFormat` | `ulaw_8000` |
|
||||
| Sample rate | `...elevenlabs.sampleRate` | `8000` |
|
||||
| Commit strategy | `...elevenlabs.commitStrategy` | `vad` |
|
||||
| Language | `...elevenlabs.languageCode` | （未設定） |
|
||||
| 設定 | 設定パス | デフォルト |
|
||||
| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| API キー | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | `ELEVENLABS_API_KEY` / `XI_API_KEY` にフォールバック |
|
||||
| モデル | `...elevenlabs.modelId` | `scribe_v2_realtime` |
|
||||
| 音声形式 | `...elevenlabs.audioFormat` | `ulaw_8000` |
|
||||
| サンプルレート | `...elevenlabs.sampleRate` | `8000` |
|
||||
| コミット戦略 | `...elevenlabs.commitStrategy` | `vad` |
|
||||
| 言語 | `...elevenlabs.languageCode` | (未設定) |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -113,12 +112,16 @@ OpenClaw は multipart 音声を ElevenLabs の `/v1/speech-to-text` に
|
||||
```
|
||||
|
||||
<Note>
|
||||
Voice Call は、Twilio メディアを 8 kHz G.711 u-law として受信します。ElevenLabs の realtime
|
||||
provider はデフォルトで `ulaw_8000` を使うため、電話音声フレームは
|
||||
トランスコードなしで転送できます。
|
||||
Voice Call は Twilio メディアを 8 kHz G.711 u-law として受信します。ElevenLabs リアルタイムプロバイダーのデフォルトは `ulaw_8000` のため、電話フレームはトランスコードなしで転送できます。
|
||||
</Note>
|
||||
|
||||
Google Meet エージェントモードでは、
|
||||
`plugins.entries.google-meet.config.realtime.transcriptionProvider` を
|
||||
`"elevenlabs"` に設定し、同じプロバイダーブロックを
|
||||
`plugins.entries.google-meet.config.realtime.providers.elevenlabs` の下に設定します。
|
||||
|
||||
## 関連
|
||||
|
||||
- [Text-to-speech](/ja-JP/tools/tts)
|
||||
- [Model selection](/ja-JP/concepts/model-providers)
|
||||
- [テキスト読み上げ](/ja-JP/tools/tts)
|
||||
- [Google Meet](/ja-JP/plugins/google-meet)
|
||||
- [モデル選択](/ja-JP/concepts/model-providers)
|
||||
|
||||
@ -2,19 +2,19 @@
|
||||
read_when:
|
||||
- 公開リリースチャネルの定義を探しています
|
||||
- リリース検証またはパッケージ受け入れの実行
|
||||
- バージョン命名とリリース頻度を確認しています
|
||||
summary: リリースレーン、オペレーター用チェックリスト、検証ボックス、バージョン命名、リリース周期
|
||||
- バージョン命名とリリース周期を確認する
|
||||
summary: リリースレーン、オペレーターチェックリスト、検証ボックス、バージョン命名、リリース周期
|
||||
title: リリースポリシー
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:37:51Z"
|
||||
generated_at: "2026-05-04T07:04:11Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 566088d826e1e2bac21b11443b82b62cb73ed1fd9c508c3fb865149cf8a428ba
|
||||
source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6
|
||||
source_path: reference/RELEASING.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw には 3 つの公開リリースレーンがあります:
|
||||
OpenClaw には 3 つの公開リリースレーンがあります。
|
||||
|
||||
- stable: デフォルトでは npm `beta` に公開され、明示的に要求された場合は npm `latest` に公開されるタグ付きリリース
|
||||
- beta: npm `beta` に公開されるプレリリースタグ
|
||||
@ -22,128 +22,158 @@ OpenClaw には 3 つの公開リリースレーンがあります:
|
||||
|
||||
## バージョン命名
|
||||
|
||||
- Stable リリースバージョン: `YYYY.M.D`
|
||||
- 安定版リリースバージョン: `YYYY.M.D`
|
||||
- Git タグ: `vYYYY.M.D`
|
||||
- Stable 修正リリースバージョン: `YYYY.M.D-N`
|
||||
- 安定版修正リリースバージョン: `YYYY.M.D-N`
|
||||
- Git タグ: `vYYYY.M.D-N`
|
||||
- Beta プレリリースバージョン: `YYYY.M.D-beta.N`
|
||||
- Git タグ: `vYYYY.M.D-beta.N`
|
||||
- 月または日をゼロ埋めしない
|
||||
- `latest` は現在昇格済みの stable npm リリースを意味する
|
||||
- `latest` は現在昇格済みの安定版 npm リリースを意味する
|
||||
- `beta` は現在の beta インストール対象を意味する
|
||||
- Stable および stable 修正リリースは、デフォルトでは npm `beta` に公開される。リリース担当者は明示的に `latest` を対象にすることも、検証済みの beta ビルドを後から昇格することもできる
|
||||
- すべての stable OpenClaw リリースは npm パッケージと macOS アプリを一緒に出荷する。
|
||||
beta リリースでは通常、npm/パッケージ経路を先に検証して公開し、mac アプリのビルド/署名/公証は明示的に要求されない限り stable 用に確保する
|
||||
- 安定版と安定版修正リリースは、デフォルトでは npm `beta` に公開される。リリース担当者は明示的に `latest` を対象にすることも、検証済みの beta ビルドを後で昇格することもできる
|
||||
- すべての安定版 OpenClaw リリースは npm パッケージと macOS アプリを一緒に出荷する。
|
||||
beta リリースは通常、まず npm/パッケージ経路を検証して公開し、
|
||||
mac アプリのビルド/署名/公証は明示的に要求されない限り安定版用に予約される
|
||||
|
||||
## リリース周期
|
||||
|
||||
- リリースは beta を先行して進む
|
||||
- Stable は最新の beta が検証された後にのみ続く
|
||||
- メンテナーは通常、現在の `main` から作成した `release/YYYY.M.D` ブランチからリリースを作成するため、リリース検証と修正が `main` 上の新規開発をブロックしない
|
||||
- beta タグがプッシュまたは公開済みで修正が必要な場合、メンテナーは古い beta タグを削除または再作成するのではなく、次の `-beta.N` タグを作成する
|
||||
- 詳細なリリース手順、承認、認証情報、復旧メモはメンテナー専用
|
||||
- リリースは beta 優先で進める
|
||||
- 安定版は最新の beta が検証された後にのみ続く
|
||||
- メンテナーは通常、現在の `main` から作成した `release/YYYY.M.D` ブランチからリリースを切る。
|
||||
これにより、リリース検証と修正が `main` 上の新規開発をブロックしない
|
||||
- beta タグが push または公開された後に修正が必要になった場合、メンテナーは古い beta タグを削除または再作成するのではなく、
|
||||
次の `-beta.N` タグを切る
|
||||
- 詳細なリリース手順、承認、認証情報、復旧メモは
|
||||
メンテナー専用
|
||||
|
||||
## リリース担当者チェックリスト
|
||||
|
||||
このチェックリストは、リリースフローの公開されている形を示すものです。非公開の認証情報、
|
||||
署名、公証、dist-tag 復旧、緊急ロールバックの詳細は、
|
||||
このチェックリストはリリースフローの公開上の形です。非公開の認証情報、
|
||||
署名、公証、dist-tag 復旧、緊急ロールバックの詳細は
|
||||
メンテナー専用のリリース runbook に残します。
|
||||
|
||||
1. 現在の `main` から開始する: 最新を pull し、対象コミットがプッシュ済みであることを確認し、
|
||||
現在の `main` CI がブランチ作成に十分な程度に green であることを確認する。
|
||||
2. 実際のコミット履歴から `/changelog` で `CHANGELOG.md` の先頭セクションを書き直し、
|
||||
エントリをユーザー向けに保ち、コミットしてプッシュし、ブランチ作成前にもう一度 rebase/pull する。
|
||||
1. 現在の `main` から開始する: 最新を pull し、対象コミットが push 済みであることを確認し、
|
||||
現在の `main` CI がブランチ作成元として十分に green であることを確認する。
|
||||
2. 実際のコミット履歴から `/changelog` で `CHANGELOG.md` の最上位セクションを書き直し、
|
||||
エントリをユーザー向けに保ち、commit して push し、ブランチ作成前にもう一度 rebase/pull する。
|
||||
3. `src/plugins/compat/registry.ts` と
|
||||
`src/commands/doctor/shared/deprecation-compat.ts` のリリース互換性記録をレビューする。アップグレード経路が引き続きカバーされる場合にのみ期限切れの互換性を削除するか、意図的に保持する理由を記録する。
|
||||
`src/commands/doctor/shared/deprecation-compat.ts` のリリース互換性レコードをレビューする。期限切れの
|
||||
互換性は、アップグレード経路が引き続きカバーされる場合のみ削除する。そうでない場合は、
|
||||
意図的に保持する理由を記録する。
|
||||
4. 現在の `main` から `release/YYYY.M.D` を作成する。通常のリリース作業を
|
||||
`main` で直接行わない。
|
||||
5. 目的のタグに必要なすべてのバージョン箇所を更新し、
|
||||
`pnpm plugins:sync` を実行して公開可能な Plugin パッケージがリリースバージョンと互換性メタデータを共有するようにしてから、ローカルの決定的 preflight を実行する:
|
||||
`main` 上で直接行わない。
|
||||
5. 予定タグに必要なすべてのバージョン箇所を更新し、
|
||||
`pnpm plugins:sync` を実行して公開可能な Plugin パッケージがリリース
|
||||
バージョンと互換性メタデータを共有するようにする。その後、ローカルの決定的な事前確認を実行する:
|
||||
`pnpm check:test-types`, `pnpm check:architecture`,
|
||||
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check`, および
|
||||
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check`, and
|
||||
`pnpm release:check`。
|
||||
6. `OpenClaw NPM Release` を `preflight_only=true` で実行する。タグが存在する前は、
|
||||
検証専用 preflight に完全な 40 文字のリリースブランチ SHA を使用できる。成功した `preflight_run_id` を保存する。
|
||||
7. リリースブランチ、タグ、または完全なコミット SHA に対して `Full Release Validation` ですべてのプレリリーステストを開始する。これは 4 つの大きなリリーステストボックス、Vitest、Docker、QA Lab、Package のための単一の手動エントリポイントである。
|
||||
8. 検証に失敗した場合は、リリースブランチ上で修正し、その修正を証明する最小の失敗ファイル、レーン、workflow job、パッケージプロファイル、プロバイダー、またはモデル allowlist を再実行する。変更された表面により以前の証拠が古くなる場合にのみ、umbrella 全体を再実行する。
|
||||
9. beta の場合、`vYYYY.M.D-beta.N` にタグ付けし、一致する `release/YYYY.M.D` ブランチから `OpenClaw Release Publish` を実行する。これは `pnpm plugins:sync:check` を検証し、すべての公開可能な Plugin パッケージを最初に npm に公開し、次に同じセットを ClawPack npm-pack tarball として ClawHub に公開し、その後一致する dist-tag で準備済みの OpenClaw npm preflight artifact を昇格する。公開後、公開済みの `openclaw@YYYY.M.D-beta.N` または
|
||||
`openclaw@beta` パッケージに対して公開後パッケージ
|
||||
acceptance を実行する。プッシュ済みまたは公開済みのプレリリースに修正が必要な場合は、
|
||||
次の一致するプレリリース番号を作成する。古いプレリリースを削除したり書き換えたりしない。
|
||||
10. stable の場合、検証済みの beta またはリリース候補に必要な検証証拠がある場合にのみ続行する。Stable npm 公開も `OpenClaw Release Publish` を通じて行い、
|
||||
`preflight_run_id` 経由で成功した preflight artifact を再利用する。stable macOS リリース準備には、
|
||||
パッケージ化された `.zip`, `.dmg`, `.dSYM.zip` と、`main` 上で更新された `appcast.xml` も必要である。
|
||||
11. 公開後、npm 公開後 verifier、公開後のチャンネル証明が必要な場合の任意のスタンドアロン公開済み npm Telegram E2E、
|
||||
必要時の dist-tag 昇格、一致する完全な `CHANGELOG.md` セクションからの GitHub release/prerelease notes、そしてリリース告知手順を実行する。
|
||||
6. `preflight_only=true` で `OpenClaw NPM Release` を実行する。タグが存在する前は、
|
||||
検証専用の事前確認として、40 文字の完全なリリースブランチ SHA を使用できる。
|
||||
成功した `preflight_run_id` を保存する。
|
||||
7. リリースブランチ、タグ、または完全なコミット SHA を対象に `Full Release Validation` で
|
||||
すべてのプレリリーステストを開始する。これは 4 つの大きなリリーステストボックス、
|
||||
Vitest、Docker、QA Lab、Package の単一の手動エントリポイントです。
|
||||
8. 検証に失敗した場合は、リリースブランチ上で修正し、修正を証明する最小の失敗
|
||||
ファイル、レーン、ワークフロージョブ、パッケージプロファイル、プロバイダー、またはモデル allowlist を再実行する。
|
||||
変更範囲によって以前の証拠が古くなる場合のみ、全体の umbrella を再実行する。
|
||||
9. beta の場合は `vYYYY.M.D-beta.N` をタグ付けし、その後、一致する
|
||||
`release/YYYY.M.D` ブランチから `OpenClaw Release Publish` を実行する。これは `pnpm plugins:sync:check` を検証し、
|
||||
すべての公開可能な Plugin パッケージをまず npm に公開し、同じ
|
||||
セットを ClawPack npm-pack tarball として次に ClawHub へ公開し、その後、一致する dist-tag で
|
||||
準備済みの OpenClaw npm 事前確認アーティファクトを昇格する。公開後、
|
||||
公開済みの `openclaw@YYYY.M.D-beta.N` または
|
||||
`openclaw@beta` パッケージに対して、公開後パッケージ
|
||||
受け入れを実行する。push または公開済みのプレリリースに修正が必要な場合は、
|
||||
次の一致するプレリリース番号を切る。古い
|
||||
プレリリースを削除または書き換えない。
|
||||
10. 安定版の場合は、検証済みの beta またはリリース候補に必要な
|
||||
検証証拠がある場合のみ続行する。安定版 npm 公開も
|
||||
`OpenClaw Release Publish` を通し、`preflight_run_id` で
|
||||
成功済みの事前確認アーティファクトを再利用する。安定版 macOS リリース準備には、
|
||||
パッケージ化された `.zip`, `.dmg`, `.dSYM.zip` と、`main` 上で更新済みの `appcast.xml` も必要です。
|
||||
11. 公開後、npm 公開後 verifier、公開後チャンネル証拠が必要な場合の任意のスタンドアロン
|
||||
published-npm Telegram E2E、必要に応じた dist-tag 昇格、
|
||||
一致する完全な `CHANGELOG.md` セクションからの GitHub リリース/プレリリースノート、
|
||||
そしてリリース告知
|
||||
手順を実行する。
|
||||
|
||||
## リリース preflight
|
||||
## リリース事前確認
|
||||
|
||||
- リリースのプリフライト前に `pnpm check:test-types` を実行し、テストの TypeScript が高速なローカル `pnpm check` ゲートの外でもカバーされるようにする
|
||||
- リリースのプリフライト前に `pnpm check:architecture` を実行し、より広範な import サイクルとアーキテクチャ境界チェックが高速なローカルゲートの外でもグリーンになるようにする
|
||||
- `pnpm release:check` の前に `pnpm build && pnpm ui:build` を実行し、想定される `dist/*` リリース成果物と Control UI バンドルがパック検証ステップ用に存在するようにする
|
||||
- ルートのバージョンバンプ後、タグ付け前に `pnpm plugins:sync` を実行する。これは公開可能な plugin パッケージバージョン、OpenClaw ピア/API 互換性メタデータ、ビルドメタデータ、plugin changelog スタブをコアのリリースバージョンに合わせて更新する。`pnpm plugins:sync:check` は変更を行わないリリースガードであり、このステップを忘れていた場合、publish ワークフローは registry の変更前に失敗する。
|
||||
- リリース承認前に手動の `Full Release Validation` ワークフローを実行し、すべてのプレリリース test box を単一のエントリポイントから開始する。ブランチ、タグ、または完全なコミット SHA を受け取り、手動の `CI` をディスパッチし、install smoke、package acceptance、Docker リリースパススイート、live/E2E、OpenWebUI、QA Lab parity、Matrix、Telegram レーン向けに `OpenClaw Release Checks` をディスパッチする。`release_profile=full` と `rerun_group=all` を指定すると、リリースチェックの `release-package-under-test` 成果物に対して package Telegram E2E も実行する。公開後、同じ Telegram E2E で公開済み npm パッケージも検証する必要がある場合は `npm_telegram_package_spec` を指定する。公開後、Package Acceptance で SHA からビルドした成果物ではなく出荷済み npm パッケージに対して package/update matrix を実行する必要がある場合は `package_acceptance_package_spec` を指定する。Telegram E2E を強制せずに、検証が公開済み npm パッケージと一致することを private evidence report で証明する場合は `evidence_package_spec` を指定する。例:
|
||||
- リリースの事前確認前に `pnpm check:test-types` を実行して、テストの TypeScript がより高速なローカルの `pnpm check` ゲートの外でも対象になるようにする
|
||||
- リリースの事前確認前に `pnpm check:architecture` を実行して、より広範な import cycle とアーキテクチャ境界チェックが、より高速なローカルゲートの外でもグリーンになるようにする
|
||||
- `pnpm release:check` の前に `pnpm build && pnpm ui:build` を実行して、pack 検証ステップに必要な `dist/*` リリース成果物と Control UI バンドルが存在するようにする
|
||||
- ルートのバージョン bump 後、タグ付け前に `pnpm plugins:sync` を実行する。これは publish 可能な Plugin パッケージのバージョン、OpenClaw peer/API 互換性メタデータ、build メタデータ、Plugin changelog スタブを core リリースバージョンに合わせて更新する。`pnpm plugins:sync:check` は変更を加えないリリースガードであり、このステップを忘れていると publish ワークフローは registry を変更する前に失敗する。
|
||||
- リリース承認前に手動の `Full Release Validation` ワークフローを実行して、すべてのリリース前テストボックスを単一のエントリポイントから起動する。これは branch、tag、または完全な commit SHA を受け取り、手動 `CI` を dispatch し、install smoke、package acceptance、Docker リリースパス suite、live/E2E、OpenWebUI、QA Lab parity、Matrix、Telegram lane 用に `OpenClaw Release Checks` を dispatch する。`release_profile=full` と `rerun_group=all` では、release checks からの `release-package-under-test` artifact に対して package Telegram E2E も実行する。同じ Telegram E2E で publish 済み npm パッケージも証明する必要がある場合は、publish 後に `npm_telegram_package_spec` を指定する。Package Acceptance が SHA から build された artifact ではなく出荷済み npm パッケージに対して package/update matrix を実行する必要がある場合は、publish 後に `package_acceptance_package_spec` を指定する。Telegram E2E を強制せずに、private evidence report で検証が publish 済み npm パッケージに一致することを証明する必要がある場合は、`evidence_package_spec` を指定する。例:
|
||||
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
|
||||
- リリース作業を継続しながらパッケージ候補のサイドチャネル証跡が必要な場合は、手動の `Package Acceptance` ワークフローを実行する。`openclaw@beta`、`openclaw@latest`、または正確なリリースバージョンには `source=npm` を使う。現在の `workflow_ref` ハーネスで信頼済みの `package_ref` ブランチ/タグ/SHA を pack するには `source=ref` を使う。必須の SHA-256 付き HTTPS tarball には `source=url` を使う。または別の GitHub Actions run がアップロードした tarball には `source=artifact` を使う。このワークフローは候補を `package-under-test` に解決し、その tarball に対して Docker E2E リリーススケジューラを再利用し、`telegram_mode=mock-openai` または `telegram_mode=live-frontier` で同じ tarball に対して Telegram QA を実行できる。選択した Docker レーンに `published-upgrade-survivor` が含まれる場合、package 成果物が候補となり、`published_upgrade_survivor_baseline` が公開済み baseline を選択する。
|
||||
- リリース作業を続けながら package candidate の side-channel 証明が必要な場合は、手動の `Package Acceptance` ワークフローを実行する。`openclaw@beta`、`openclaw@latest`、または正確なリリースバージョンには `source=npm` を使う。現在の `workflow_ref` harness で信頼済みの `package_ref` branch/tag/SHA を pack するには `source=ref` を使う。必須 SHA-256 付きの HTTPS tarball には `source=url` を使う。別の GitHub Actions run が upload した tarball には `source=artifact` を使う。このワークフローは candidate を `package-under-test` に解決し、その tarball に対して Docker E2E release scheduler を再利用し、`telegram_mode=mock-openai` または `telegram_mode=live-frontier` で同じ tarball に対する Telegram QA も実行できる。選択された Docker lane に `published-upgrade-survivor` が含まれる場合、package artifact が candidate になり、`published_upgrade_survivor_baseline` が publish 済み baseline を選択する。
|
||||
例: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
|
||||
一般的なプロファイル:
|
||||
- `smoke`: install/channel/agent、Gateway network、config reload レーン
|
||||
- `package`: OpenWebUI または live ClawHub を含まない、成果物ネイティブの package/update/plugin レーン
|
||||
- `product`: package プロファイルに加えて MCP channel、cron/subagent cleanup、OpenAI web search、OpenWebUI
|
||||
- `full`: OpenWebUI を含む Docker リリースパスチャンク
|
||||
- `custom`: 焦点を絞った再実行用の正確な `docker_lanes` 選択
|
||||
- リリース候補に対する通常の完全な CI カバレッジだけが必要な場合は、手動の `CI` ワークフローを直接実行する。手動 CI ディスパッチは changed スコープをバイパスし、Linux Node shards、bundled-plugin shards、channel contracts、Node 22 compatibility、`check`、`check-additional`、build smoke、docs checks、Python skills、Windows、macOS、Android、Control UI i18n レーンを強制する。
|
||||
一般的な profile:
|
||||
- `smoke`: install/channel/agent、gateway network、config reload lane
|
||||
- `package`: OpenWebUI や live ClawHub を含まない artifact-native package/update/plugin lane
|
||||
- `product`: package profile に MCP channel、cron/subagent cleanup、OpenAI web search、OpenWebUI を加えたもの
|
||||
- `full`: OpenWebUI 付きの Docker リリースパス chunk
|
||||
- `custom`: focused rerun 用の正確な `docker_lanes` 選択
|
||||
- リリース candidate に対する通常の full CI coverage だけが必要な場合は、手動の `CI` ワークフローを直接実行する。手動 CI dispatch は changed scoping を bypass し、Linux Node shard、bundled-plugin shard、channel contract、Node 22 互換性、`check`、`check-additional`、build smoke、docs check、Python skills、Windows、macOS、Android、Control UI i18n lane を強制する。
|
||||
例: `gh workflow run ci.yml --ref release/YYYY.M.D`
|
||||
- リリースの telemetry を検証する場合は `pnpm qa:otel:smoke` を実行する。これはローカル OTLP/HTTP receiver を通じて QA-lab を実行し、Opik、Langfuse、その他の外部 collector を必要とせずに、export された trace span 名、制限付き attributes、content/identifier redaction を検証する。
|
||||
- タグ付きリリースのたびに、事前に `pnpm release:check` を実行する
|
||||
- タグが存在した後、変更を伴う publish sequence には `OpenClaw Release Publish` を実行する。`release/YYYY.M.D` からディスパッチする（main から到達可能なタグを公開する場合は `main`）。リリースタグと成功した OpenClaw npm `preflight_run_id` を渡し、意図的に焦点を絞った修復を行う場合を除き、デフォルトの plugin publish scope `all-publishable` を維持する。このワークフローは plugin npm publish、plugin ClawHub publish、OpenClaw npm publish を直列化し、外部化された plugins より前にコアパッケージが公開されないようにする。
|
||||
- リリースチェックは現在、別の手動ワークフローで実行される:
|
||||
- リリース telemetry を検証するときは `pnpm qa:otel:smoke` を実行する。これは local OTLP/HTTP receiver 経由で QA-lab を実行し、Opik、Langfuse、その他の外部 collector を必要とせずに、export された trace span name、bounded attribute、content/identifier redaction を検証する。
|
||||
- タグ付きリリースのたびに `pnpm release:check` を実行する
|
||||
- tag が存在した後、変更を伴う publish sequence には `OpenClaw Release Publish` を実行する。`release/YYYY.M.D` から dispatch し（main から到達可能な tag を publish する場合は `main`）、release tag と成功した OpenClaw npm `preflight_run_id` を渡し、意図的に focused repair を実行している場合を除き、default Plugin publish scope の `all-publishable` を維持する。このワークフローは Plugin npm publish、Plugin ClawHub publish、OpenClaw npm publish を直列化し、外部化された plugins より先に core パッケージが publish されないようにする。
|
||||
- Release checks は現在、別の手動ワークフローで実行される:
|
||||
`OpenClaw Release Checks`
|
||||
- `OpenClaw Release Checks` は、リリース承認前に QA Lab mock parity レーンに加えて、高速な live Matrix プロファイルと Telegram QA レーンも実行する。live レーンは `qa-live-shared` environment を使用する。Telegram は Convex CI credential lease も使用する。Matrix transport、media、E2EE inventory 全体を並列で実行したい場合は、`matrix_profile=all` と `matrix_shards=true` を指定して手動の `QA-Lab - All Lanes` ワークフローを実行する。
|
||||
- クロス OS の install と upgrade runtime 検証は、公開の `OpenClaw Release Checks` と `Full Release Validation` の一部であり、reusable workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` を直接呼び出す
|
||||
- この分割は意図的なもの。実際の npm リリースパスは短く、決定的で、成果物中心に保ち、時間のかかる live check は publish を停滞またはブロックしないように独自のレーンに置く
|
||||
- secrets を持つリリースチェックは、`Full Release Validation` 経由、または `main`/release workflow ref からディスパッチし、workflow logic と secrets が制御された状態を保つ
|
||||
- `OpenClaw Release Checks` は、解決されたコミットが OpenClaw のブランチまたはリリースタグから到達可能である限り、ブランチ、タグ、または完全なコミット SHA を受け付ける
|
||||
- `OpenClaw NPM Release` の検証専用 preflight も、push 済みタグを要求せずに、現在の完全な 40 文字の workflow-branch commit SHA を受け付ける
|
||||
- その SHA パスは検証専用であり、実際の publish に昇格できない
|
||||
- SHA モードでは、ワークフローは package metadata check のためだけに `v<package.json version>` を合成する。実際の publish には引き続き実際のリリースタグが必要
|
||||
- どちらのワークフローも実際の publish と promotion パスを GitHub-hosted runner 上に保ち、変更を伴わない検証パスではより大きな Blacksmith Linux runner を使用できる
|
||||
- そのワークフローは `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` を、`OPENAI_API_KEY` と `ANTHROPIC_API_KEY` の両方の workflow secrets を使って実行する
|
||||
- npm release preflight は、別の release checks レーンを待機しなくなった
|
||||
- 承認前に `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（または対応する beta/correction タグ）を実行する
|
||||
- npm publish 後、公開済み registry install パスを新しい一時 prefix で検証するために `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（または対応する beta/correction バージョン）を実行する
|
||||
- beta publish 後、共有の貸与 Telegram credential pool を使い、公開済み npm パッケージに対して installed-package onboarding、Telegram setup、実際の Telegram E2E を検証するために、`OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` を実行する。ローカル maintainer の単発実行では Convex vars を省略し、3 つの `OPENCLAW_QA_TELEGRAM_*` env credentials を直接渡してもよい。
|
||||
- Maintainers は、手動の `NPM Telegram Beta E2E` ワークフローを通じて、GitHub Actions から同じ post-publish check を実行できる。これは意図的に manual-only であり、すべての merge で実行されるわけではない。
|
||||
- Maintainer release automation は現在、preflight-then-promote を使用する:
|
||||
- 実際の npm publish は、成功した npm `preflight_run_id` を通過している必要がある
|
||||
- 実際の npm publish は、成功した preflight run と同じ `main` または `release/YYYY.M.D` ブランチからディスパッチされている必要がある
|
||||
- 安定版 npm リリースのデフォルトは `beta`
|
||||
- 安定版 npm publish は、workflow input で明示的に `latest` を対象にできる
|
||||
- token ベースの npm dist-tag mutation は現在、セキュリティ上の理由から `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` にある。これは、公開リポジトリが OIDC-only publish を維持する一方で、`npm dist-tag add` には依然として `NPM_TOKEN` が必要なため
|
||||
- 公開 `macOS Release` は validation-only。タグが release branch のみに存在し、workflow が `main` からディスパッチされる場合は、`public_release_branch=release/YYYY.M.D` を設定する
|
||||
- 実際の private mac publish は、成功した private mac `preflight_run_id` と `validate_run_id` を通過している必要がある
|
||||
- 実際の publish パスは、準備済み成果物を再ビルドするのではなく昇格する
|
||||
- `YYYY.M.D-N` のような安定版 correction release では、post-publish verifier は同じ temp-prefix upgrade path で `YYYY.M.D` から `YYYY.M.D-N` への検証も行い、release correction が古い global install を base stable payload のまま静かに残さないようにする
|
||||
- `OpenClaw Release Checks` は、リリース承認前に QA Lab mock parity lane に加えて、高速な live Matrix profile と Telegram QA lane も実行する。live lane は `qa-live-shared` environment を使い、Telegram は Convex CI credential lease も使う。full Matrix transport、media、E2EE inventory を並列で実行したい場合は、手動の `QA-Lab - All Lanes` ワークフローを `matrix_profile=all` と `matrix_shards=true` で実行する。
|
||||
- Cross-OS install と upgrade runtime validation は、再利用可能ワークフロー `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` を直接呼び出す public `OpenClaw Release Checks` と `Full Release Validation` の一部である
|
||||
- この分割は意図的なもの: 実際の npm release path は短く、決定的で、artifact-focused に保ち、遅い live check は専用の lane に置くことで、publish を停滞またはブロックしないようにする
|
||||
- secret を含む release check は、ワークフロー logic と secrets を制御された状態に保つため、`Full Release Validation` 経由または `main`/release workflow ref から dispatch する
|
||||
- `OpenClaw Release Checks` は、resolved commit が OpenClaw branch または release tag から到達可能である限り、branch、tag、または完全な commit SHA を受け取る
|
||||
- `OpenClaw NPM Release` の validation-only preflight は、push 済み tag を要求せず、現在の完全な 40 文字 workflow-branch commit SHA も受け取る
|
||||
- その SHA path は validation-only であり、実際の publish に昇格できない
|
||||
- SHA mode では、workflow は package metadata check のためだけに `v<package.json version>` を合成する。実際の publish には引き続き実際の release tag が必要である
|
||||
- どちらのワークフローも実際の publish と promotion path は GitHub-hosted runner 上に保ち、変更を伴わない validation path ではより大きな Blacksmith Linux runner を使える
|
||||
- そのワークフローは、`OPENAI_API_KEY` と `ANTHROPIC_API_KEY` の両方の workflow secret を使って
|
||||
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
|
||||
を実行する
|
||||
- npm release preflight は、別の release checks lane を待たなくなった
|
||||
- 承認前に `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
|
||||
（または対応する beta/correction tag）を実行する
|
||||
- npm publish 後に
|
||||
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
|
||||
（または対応する beta/correction version）を実行して、fresh temp prefix で publish 済み registry install path を検証する
|
||||
- beta publish 後に `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
|
||||
を実行して、共有の lease 済み Telegram credential pool を使い、publish 済み npm パッケージに対して installed-package onboarding、Telegram setup、実際の Telegram E2E を検証する。ローカル maintainer の単発実行では Convex vars を省略し、3 つの `OPENCLAW_QA_TELEGRAM_*` env credentials を直接渡してもよい。
|
||||
- maintainer machine から full post-publish beta smoke を実行するには、`pnpm release:beta-smoke -- --beta betaN` を使う。この helper は Parallels npm update/fresh-target validation を実行し、`NPM Telegram Beta E2E` を dispatch し、正確な workflow run を poll し、artifact を download して Telegram report を出力する。
|
||||
- Maintainer は、GitHub Actions から手動の `NPM Telegram Beta E2E` ワークフロー経由で同じ post-publish check を実行できる。これは意図的に manual-only であり、すべての merge で実行されるわけではない。
|
||||
- Maintainer release automation は現在 preflight-then-promote を使う:
|
||||
- 実際の npm publish には成功した npm `preflight_run_id` が必要
|
||||
- 実際の npm publish は、成功した preflight run と同じ `main` または `release/YYYY.M.D` branch から dispatch する必要がある
|
||||
- stable npm release の default は `beta`
|
||||
- stable npm publish は workflow input で明示的に `latest` を target にできる
|
||||
- token-based npm dist-tag mutation は現在、security のため `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` にある。`npm dist-tag add` には引き続き `NPM_TOKEN` が必要であり、public repo は OIDC-only publish を維持するためである
|
||||
- public `macOS Release` は validation-only である。tag が release branch 上にのみ存在し、workflow を `main` から dispatch する場合は、`public_release_branch=release/YYYY.M.D` を設定する
|
||||
- 実際の private mac publish には、成功した private mac `preflight_run_id` と `validate_run_id` が必要
|
||||
- 実際の publish path は、準備済み artifact を再 build せずに promote する
|
||||
- `YYYY.M.D-N` のような stable correction release では、post-publish verifier は `YYYY.M.D` から `YYYY.M.D-N` への同じ temp-prefix upgrade path も check し、release correction が古い global install を base stable payload のまま静かに残さないようにする
|
||||
- npm release preflight は、tarball に `dist/control-ui/index.html` と空でない `dist/control-ui/assets/` payload の両方が含まれていない限り fail closed するため、空の browser dashboard を再び出荷しない
|
||||
- Post-publish verification は、公開済み plugin entrypoint と package metadata がインストール済み registry layout に存在することも確認する。plugin runtime payload が欠落したリリースは postpublish verifier に失敗し、`latest` に昇格できない。
|
||||
- `pnpm test:install:smoke` は candidate update tarball に対して npm pack `unpackedSize` budget も強制するため、installer e2e は accidental pack bloat を release publish path の前に検出する
|
||||
- リリース作業で CI planning、extension timing manifest、または extension test matrix に触れた場合は、承認前に `.github/workflows/plugin-prerelease.yml` から planner-owned の `plugin-prerelease-extension-shard` matrix outputs を再生成してレビューし、リリースノートが古い CI layout を説明しないようにする
|
||||
- 安定版 macOS リリース readiness には updater surfaces も含まれる:
|
||||
- GitHub release には packaged `.zip`、`.dmg`、`.dSYM.zip` が最終的に含まれている必要がある
|
||||
- publish 後、`main` の `appcast.xml` は新しい安定版 zip を指している必要がある
|
||||
- packaged app は non-debug bundle id、空でない Sparkle feed URL、そのリリースバージョンの canonical Sparkle build floor 以上の `CFBundleVersion` を維持している必要がある
|
||||
- Post-publish verification は、publish 済み Plugin entrypoint と package metadata が installed registry layout に存在することも check する。Plugin runtime payload が欠落したまま出荷される release は postpublish verifier に失敗し、`latest` に promote できない。
|
||||
- `pnpm test:install:smoke` は candidate update tarball に対して npm pack `unpackedSize` budget も強制するため、installer e2e は release publish path の前に偶発的な pack bloat を検出できる
|
||||
- release 作業で CI planning、extension timing manifest、または extension test matrix に触れた場合は、承認前に `.github/workflows/plugin-prerelease.yml` から planner-owned の `plugin-prerelease-extension-shard` matrix output を regenerate して review し、release note が古い CI layout を説明しないようにする
|
||||
- Stable macOS release readiness には updater surface も含まれる:
|
||||
- GitHub release には最終的に package された `.zip`、`.dmg`、`.dSYM.zip` が含まれる必要がある
|
||||
- publish 後、`main` 上の `appcast.xml` は新しい stable zip を指す必要がある
|
||||
- package された app は、non-debug bundle id、空でない Sparkle feed URL、その release version の canonical Sparkle build floor 以上の `CFBundleVersion` を維持する必要がある
|
||||
|
||||
## リリーステストボックス
|
||||
|
||||
`Full Release Validation` は、operator がすべてのプレリリーステストを単一のエントリポイントから開始する方法である。動きの速いブランチで pinned commit proof を取得するには、helper を使ってすべての子ワークフローを対象 SHA に固定された一時ブランチから実行する:
|
||||
`Full Release Validation` は、operator がすべてのリリース前テストを単一のエントリポイントから起動する方法である。動きの速い branch 上で pinned commit proof が必要な場合は、すべての child workflow が target SHA に固定された temporary branch から実行されるように helper を使う:
|
||||
|
||||
```bash
|
||||
pnpm ci:full-release --sha <full-sha>
|
||||
```
|
||||
|
||||
この helper は `release-ci/<sha>-...` を push し、そのブランチから `ref=<sha>` で `Full Release Validation` をディスパッチし、すべての子ワークフローの `headSha` が対象と一致することを検証してから、一時ブランチを削除する。これにより、誤って新しい `main` の子 run を証明してしまうことを防ぐ。
|
||||
この helper は `release-ci/<sha>-...` を push し、その branch から `ref=<sha>` で `Full Release Validation` を dispatch し、すべての child workflow の `headSha` が target に一致することを検証した後、temporary branch を削除する。これにより、誤って新しい `main` child run を証明することを避けられる。
|
||||
|
||||
リリースブランチまたはタグの検証では、信頼済みの `main` workflow ref から実行し、リリースブランチまたはタグを `ref` として渡す:
|
||||
release branch または tag validation では、信頼済みの `main` workflow ref から実行し、release branch または tag を `ref` として渡す:
|
||||
|
||||
```bash
|
||||
gh workflow run full-release-validation.yml \
|
||||
@ -155,19 +185,25 @@ gh workflow run full-release-validation.yml \
|
||||
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
|
||||
```
|
||||
|
||||
このワークフローはターゲット ref を解決し、`target_ref=<release-ref>` 付きで手動 `CI` をディスパッチし、`OpenClaw Release Checks` をディスパッチし、パッケージ向けチェック用の親 `release-package-under-test` アーティファクトを準備し、`release_profile=full` かつ `rerun_group=all` の場合、または `npm_telegram_package_spec` が設定されている場合に、スタンドアロンのパッケージ Telegram E2E をディスパッチします。その後 `OpenClaw Release Checks` は、インストールスモーク、クロス OS リリースチェック、live/E2E Docker リリースパスのカバレッジ、Telegram パッケージ QA 付きの Package Acceptance、QA Lab パリティ、live Matrix、live Telegram に展開します。フル実行が許容されるのは、`Full Release Validation` のサマリーで `normal_ci` と `release_checks` が成功として表示される場合のみです。full/all モードでは、`npm_telegram` 子も成功している必要があります。full/all 以外では、公開済みの `npm_telegram_package_spec` が指定されていない限りスキップされます。最終の検証サマリーには各子実行の最も遅いジョブの表が含まれるため、リリースマネージャーはログをダウンロードせずに現在のクリティカルパスを確認できます。
|
||||
完全なステージマトリクス、正確なワークフロージョブ名、stable プロファイルと full プロファイルの違い、アーティファクト、重点的な再実行ハンドルについては、[完全リリース検証](/ja-JP/reference/full-release-validation)を参照してください。
|
||||
子ワークフローは、ターゲット `ref` が古いリリースブランチやタグを指している場合でも、`Full Release Validation` を実行する信頼された ref、通常は `--ref main` からディスパッチされます。別個の Full Release Validation workflow-ref 入力はありません。ワークフロー実行 ref を選択することで、信頼されたハーネスを選択します。移動する `main` 上で正確なコミット証拠を得るために `--ref main -f ref=<sha>` を使用しないでください。生のコミット SHA はワークフローディスパッチ ref にできないため、`pnpm ci:full-release --sha <sha>` を使用してピン留めされた一時ブランチを作成します。
|
||||
ワークフローはターゲット ref を解決し、手動 `CI` を
|
||||
`target_ref=<release-ref>` 付きでディスパッチし、`OpenClaw Release Checks` をディスパッチし、パッケージ向けチェック用の親 `release-package-under-test` アーティファクトを準備し、`release_profile=full` かつ `rerun_group=all` の場合、または `npm_telegram_package_spec` が設定されている場合に、スタンドアロンのパッケージ Telegram E2E をディスパッチします。その後、`OpenClaw Release
|
||||
Checks` は、インストールスモーク、クロス OS リリースチェック、ライブ/E2E Docker リリースパスカバレッジ、Telegram パッケージ QA 付き Package Acceptance、QA Lab パリティ、ライブ Matrix、ライブ Telegram に展開します。完全実行が許容されるのは、`Full Release Validation`
|
||||
サマリーで `normal_ci` と `release_checks` が成功と表示されている場合だけです。full/all モードでは、`npm_telegram` 子ワークフローも成功している必要があります。full/all 以外では、公開済みの `npm_telegram_package_spec` が指定されていない限りスキップされます。最終 verifier サマリーには各子実行の最遅ジョブテーブルが含まれるため、リリースマネージャーはログをダウンロードせずに現在のクリティカルパスを確認できます。
|
||||
完全なステージマトリクス、正確なワークフロージョブ名、stable プロファイルと full プロファイルの違い、アーティファクト、集中的な再実行ハンドルについては、[完全リリース検証](/ja-JP/reference/full-release-validation)を参照してください。
|
||||
子ワークフローは、`Full Release
|
||||
Validation` を実行する信頼済み ref、通常は `--ref main` からディスパッチされます。これはターゲット `ref` が古いリリースブランチやタグを指している場合も同じです。Full Release Validation 用の別個の workflow-ref 入力はありません。ワークフロー実行 ref を選ぶことで、信頼済みハーネスを選択します。
|
||||
移動する `main` 上で正確なコミット証跡を得るために `--ref main -f ref=<sha>` を使用しないでください。生のコミット SHA は workflow dispatch ref にできないため、固定された一時ブランチを作成するには `pnpm ci:full-release --sha <sha>` を使用します。
|
||||
|
||||
live/provider の広さを選択するには `release_profile` を使用します。
|
||||
ライブ/プロバイダーの範囲を選択するには `release_profile` を使用します。
|
||||
|
||||
- `minimum`: 最速のリリースクリティカルな OpenAI/core live と Docker パス
|
||||
- `stable`: minimum に加えて、リリース承認用の stable provider/backend カバレッジ
|
||||
- `full`: stable に加えて、広範な advisory provider/media カバレッジ
|
||||
- `minimum`: 最速のリリースクリティカルな OpenAI/コアのライブおよび Docker パス
|
||||
- `stable`: リリース承認向けに minimum に stable プロバイダー/バックエンドカバレッジを追加
|
||||
- `full`: stable に幅広い advisory プロバイダー/メディアカバレッジを追加
|
||||
|
||||
`OpenClaw Release Checks` は、信頼されたワークフロー ref を使用してターゲット ref を `release-package-under-test` として一度だけ解決し、そのアーティファクトをリリースパス Docker チェックと Package Acceptance の両方で再利用します。これにより、すべてのパッケージ向けボックスが同じバイト列を使用し、パッケージビルドの繰り返しを避けられます。クロス OS OpenAI インストールスモークは、repo/org 変数が設定されている場合は `OPENCLAW_CROSS_OS_OPENAI_MODEL` を使用し、それ以外は `openai/gpt-5.4` を使用します。このレーンは、最も遅いデフォルトモデルのベンチマークではなく、パッケージインストール、オンボーディング、Gateway 起動、1 回の live agent ターンを証明するためです。より広範な live provider マトリクスは、引き続きモデル固有のカバレッジの場です。
|
||||
`OpenClaw Release Checks` は、信頼済みワークフロー ref を使用してターゲット ref を一度だけ `release-package-under-test` として解決し、そのアーティファクトをリリースパス Docker チェックと Package Acceptance の両方で再利用します。これにより、すべてのパッケージ向けボックスが同じバイト列を使用し、パッケージビルドの繰り返しを避けられます。
|
||||
クロス OS OpenAI インストールスモークは、repo/org 変数が設定されている場合は `OPENCLAW_CROSS_OS_OPENAI_MODEL` を使用し、そうでない場合は `openai/gpt-5.4` を使用します。このレーンは最も遅いデフォルトモデルをベンチマークするのではなく、パッケージインストール、オンボーディング、Gateway 起動、ライブエージェント 1 ターンを証明するものだからです。より広範なライブプロバイダーマトリクスは、引き続きモデル固有カバレッジの場所です。
|
||||
|
||||
リリース段階に応じて、次のバリアントを使用します。
|
||||
リリース段階に応じて、これらのバリアントを使用します。
|
||||
|
||||
```bash
|
||||
# Validate an unpublished release candidate branch.
|
||||
@ -197,22 +233,23 @@ gh workflow run full-release-validation.yml \
|
||||
-f npm_telegram_provider_mode=mock-openai
|
||||
```
|
||||
|
||||
重点修正後の最初の再実行として、フルの統合ワークフローを使用しないでください。1 つのボックスが失敗した場合は、次の証明に失敗した子ワークフロー、ジョブ、Docker レーン、パッケージプロファイル、モデル provider、または QA レーンを使用します。フルの統合ワークフローを再実行するのは、修正が共有リリースオーケストレーションを変更した場合、または以前の全ボックス証拠が古くなった場合のみにしてください。統合ワークフローの最終検証は、記録された子ワークフロー実行 ID を再チェックするため、子ワークフローが正常に再実行された後は、失敗した親ジョブ `Verify full validation` のみを再実行します。
|
||||
集中的な修正後の最初の再実行として、完全な包括ワークフローを使用しないでください。1 つのボックスが失敗した場合は、次の証跡として、失敗した子ワークフロー、ジョブ、Docker レーン、パッケージプロファイル、モデルプロバイダー、または QA レーンを使用します。完全な包括ワークフローを再度実行するのは、その修正が共有リリースオーケストレーションを変更した場合、または以前の全ボックス証跡を古くした場合だけです。包括ワークフローの最終 verifier は記録された子ワークフロー実行 ID を再チェックするため、子ワークフローの再実行が成功した後は、失敗した親ジョブ `Verify full validation` だけを再実行します。
|
||||
|
||||
範囲を限定した復旧には、統合ワークフローに `rerun_group` を渡します。`all` は実際のリリース候補実行、`ci` は通常 CI 子のみ、`plugin-prerelease` はリリース専用 Plugin 子のみ、`release-checks` はすべてのリリースボックスを実行し、より狭いリリースグループは `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、`npm-telegram` です。重点的な `npm-telegram` 再実行には `npm_telegram_package_spec` が必要です。`release_profile=full` の full/all 実行では、release-checks パッケージアーティファクトを使用します。
|
||||
範囲を限定した復旧には、包括ワークフローに `rerun_group` を渡します。`all` は実際のリリース候補実行、`ci` は通常の CI 子ワークフローのみ、`plugin-prerelease` はリリース専用 Plugin 子ワークフローのみ、`release-checks` はすべてのリリースボックスを実行し、より狭いリリースグループは `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`、`npm-telegram` です。
|
||||
集中的な `npm-telegram` 再実行には `npm_telegram_package_spec` が必要です。`release_profile=full` の full/all 実行では、release-checks パッケージアーティファクトを使用します。
|
||||
|
||||
### Vitest
|
||||
|
||||
Vitest ボックスは手動 `CI` 子ワークフローです。手動 CI は意図的に changed スコープを迂回し、リリース候補に対して通常のテストグラフを強制します。Linux Node shard、バンドル Plugin shard、チャンネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、ドキュメントチェック、Python Skills、Windows、macOS、Android、Control UI i18n が対象です。
|
||||
Vitest ボックスは手動 `CI` 子ワークフローです。手動 CI は意図的に変更スコープをバイパスし、リリース候補に対して通常のテストグラフを強制します。対象は、Linux Node シャード、バンドル Plugin シャード、チャネル契約、Node 22 互換性、`check`、`check-additional`、ビルドスモーク、docs チェック、Python Skills、Windows、macOS、Android、Control UI i18n です。
|
||||
|
||||
このボックスは、「ソースツリーが通常のフルテストスイートに合格したか」に答えるために使用します。これはリリースパスの製品検証と同じではありません。保持すべき証拠:
|
||||
このボックスは「ソースツリーは通常のフルテストスイートを通過したか」に答えるために使用します。リリースパスのプロダクト検証とは同じではありません。保持する証跡:
|
||||
|
||||
- ディスパッチされた `CI` 実行 URL を示す `Full Release Validation` サマリー
|
||||
- 正確なターゲット SHA で green になった `CI` 実行
|
||||
- リグレッション調査時の CI ジョブからの失敗または低速 shard 名
|
||||
- 正確なターゲット SHA で緑の `CI` 実行
|
||||
- リグレッションを調査する際の CI ジョブからの失敗または低速シャード名
|
||||
- 実行にパフォーマンス分析が必要な場合の `.artifacts/vitest-shard-timings.json` などの Vitest タイミングアーティファクト
|
||||
|
||||
リリースで決定論的な通常 CI が必要だが、Docker、QA Lab、live、クロス OS、またはパッケージボックスが不要な場合のみ、手動 CI を直接実行します。
|
||||
リリースで決定的な通常 CI は必要だが、Docker、QA Lab、ライブ、クロス OS、パッケージボックスが不要な場合のみ、手動 CI を直接実行します。
|
||||
|
||||
```bash
|
||||
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
@ -220,51 +257,64 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
|
||||
### Docker
|
||||
|
||||
Docker ボックスは、`openclaw-live-and-e2e-checks-reusable.yml` とリリースモードの `install-smoke` ワークフローを通じて `OpenClaw Release Checks` 内にあります。ソースレベルのテストだけでなく、パッケージ化された Docker 環境を通じてリリース候補を検証します。
|
||||
Docker ボックスは、`openclaw-live-and-e2e-checks-reusable.yml` を通じて `OpenClaw Release Checks` 内にあり、さらにリリースモードの `install-smoke` ワークフローにもあります。これはソースレベルのテストだけではなく、パッケージ化された Docker 環境を通じてリリース候補を検証します。
|
||||
|
||||
リリース Docker カバレッジには次が含まれます。
|
||||
リリース Docker カバレッジには以下が含まれます。
|
||||
|
||||
- 低速な Bun グローバルインストールスモークを有効にした完全なインストールスモーク
|
||||
- ターゲット SHA による root Dockerfile スモークイメージの準備/再利用。QR、root/Gateway、installer/Bun スモークジョブは個別の install-smoke shard として実行
|
||||
- 低速な Bun グローバルインストールスモークを有効にしたフルインストールスモーク
|
||||
- ターゲット SHA ごとのルート Dockerfile スモークイメージ準備/再利用。QR、root/gateway、installer/Bun スモークジョブは個別の install-smoke シャードとして実行
|
||||
- リポジトリ E2E レーン
|
||||
- リリースパス Docker チャンク: `core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g`、`plugins-runtime-install-h`
|
||||
- リリースパス Docker チャンク: `core`、`package-update-openai`、
|
||||
`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、
|
||||
`plugins-runtime-services`、
|
||||
`plugins-runtime-install-a`、`plugins-runtime-install-b`、
|
||||
`plugins-runtime-install-c`、`plugins-runtime-install-d`、
|
||||
`plugins-runtime-install-e`、`plugins-runtime-install-f`、
|
||||
`plugins-runtime-install-g`、`plugins-runtime-install-h`
|
||||
- 要求された場合の `plugins-runtime-services` チャンク内の OpenWebUI カバレッジ
|
||||
- 分割されたバンドル Plugin install/uninstall レーン `bundled-plugin-install-uninstall-0` から `bundled-plugin-install-uninstall-23`
|
||||
- リリースチェックに live スイートが含まれる場合の live/E2E provider スイートと Docker live モデルカバレッジ
|
||||
- 分割されたバンドル Plugin インストール/アンインストールレーン
|
||||
`bundled-plugin-install-uninstall-0` から
|
||||
`bundled-plugin-install-uninstall-23`
|
||||
- リリースチェックにライブスイートが含まれる場合のライブ/E2E プロバイダースイートと Docker ライブモデルカバレッジ
|
||||
|
||||
再実行前に Docker アーティファクトを使用します。リリースパススケジューラーは、レーンログ、`summary.json`、`failures.json`、フェーズタイミング、スケジューラープラン JSON、再実行コマンドを含む `.artifacts/docker-tests/` をアップロードします。重点復旧には、すべてのリリースチャンクを再実行するのではなく、再利用可能な live/E2E ワークフローで `docker_lanes=<lane[,lane]>` を使用します。生成される再実行コマンドには、利用可能な場合、以前の `package_artifact_run_id` と準備済み Docker イメージ入力が含まれるため、失敗したレーンは同じ tarball と GHCR イメージを再利用できます。
|
||||
再実行の前に Docker アーティファクトを使用します。リリースパススケジューラーは、レーンログ、`summary.json`、`failures.json`、フェーズタイミング、スケジューラープラン JSON、再実行コマンドを含む `.artifacts/docker-tests/` をアップロードします。集中的な復旧には、すべてのリリースチャンクを再実行する代わりに、再利用可能な live/E2E ワークフローで `docker_lanes=<lane[,lane]>` を使用します。生成された再実行コマンドには、利用可能な場合、以前の `package_artifact_run_id` と準備済み Docker イメージ入力が含まれるため、失敗したレーンは同じ tarball と GHCR イメージを再利用できます。
|
||||
|
||||
### QA Lab
|
||||
|
||||
QA Lab ボックスも `OpenClaw Release Checks` の一部です。これは agentic behavior とチャンネルレベルのリリースゲートであり、Vitest や Docker パッケージ機構とは別です。
|
||||
QA Lab ボックスも `OpenClaw Release Checks` の一部です。これは agentic な挙動とチャネルレベルのリリースゲートであり、Vitest や Docker パッケージ機構とは別です。
|
||||
|
||||
リリース QA Lab カバレッジには次が含まれます。
|
||||
リリース QA Lab カバレッジには以下が含まれます。
|
||||
|
||||
- agentic parity pack を使用し、OpenAI candidate レーンを Opus 4.6 ベースラインと比較する mock parity レーン
|
||||
- `qa-live-shared` 環境を使用する高速 live Matrix QA プロファイル
|
||||
- Convex CI credential lease を使用する live Telegram QA レーン
|
||||
- リリース telemetry に明示的なローカル証明が必要な場合の `pnpm qa:otel:smoke`
|
||||
- agentic parity pack を使用して OpenAI 候補レーンを Opus 4.6 ベースラインと比較する mock パリティレーン
|
||||
- `qa-live-shared` 環境を使用する高速ライブ Matrix QA プロファイル
|
||||
- Convex CI credential lease を使用するライブ Telegram QA レーン
|
||||
- リリーステレメトリに明示的なローカル証跡が必要な場合の `pnpm qa:otel:smoke`
|
||||
|
||||
このボックスは、「リリースが QA シナリオと live チャンネルフローで正しく動作するか」に答えるために使用します。リリース承認時には、parity、Matrix、Telegram レーンのアーティファクト URL を保持します。完全な Matrix カバレッジは、デフォルトのリリースクリティカルレーンではなく、手動の sharded QA-Lab 実行として引き続き利用できます。
|
||||
このボックスは「リリースは QA シナリオとライブチャネルフローで正しく動作するか」に答えるために使用します。リリースを承認する際は、パリティ、Matrix、Telegram レーンのアーティファクト URL を保持します。完全な Matrix カバレッジは、デフォルトのリリースクリティカルレーンではなく、手動のシャード化された QA-Lab 実行として引き続き利用できます。
|
||||
|
||||
### パッケージ
|
||||
|
||||
パッケージボックスは、インストール可能な製品ゲートです。これは `Package Acceptance` とリゾルバー `scripts/resolve-openclaw-package-candidate.mjs` によって支えられています。リゾルバーは候補を Docker E2E が消費する `package-under-test` tarball に正規化し、パッケージインベントリを検証し、パッケージバージョンと SHA-256 を記録し、ワークフローハーネス ref をパッケージソース ref から分離したままにします。
|
||||
パッケージボックスは、インストール可能プロダクトのゲートです。これは `Package Acceptance` とリゾルバー `scripts/resolve-openclaw-package-candidate.mjs` によって支えられています。リゾルバーは候補を Docker E2E が消費する `package-under-test` tarball に正規化し、パッケージインベントリを検証し、パッケージバージョンと SHA-256 を記録し、ワークフローハーネス ref をパッケージソース ref とは別に保ちます。
|
||||
|
||||
サポートされる候補ソース:
|
||||
|
||||
- `source=npm`: `openclaw@beta`、`openclaw@latest`、または正確な OpenClaw リリースバージョン
|
||||
- `source=ref`: 選択された `workflow_ref` ハーネスで、信頼された `package_ref` ブランチ、タグ、または完全なコミット SHA を pack
|
||||
- `source=ref`: 選択された `workflow_ref` ハーネスで、信頼済みの `package_ref` ブランチ、タグ、または完全なコミット SHA をパック
|
||||
- `source=url`: 必須の `package_sha256` 付きで HTTPS `.tgz` をダウンロード
|
||||
- `source=artifact`: 別の GitHub Actions 実行によってアップロードされた `.tgz` を再利用
|
||||
|
||||
`OpenClaw Release Checks` は、準備済みリリースパッケージアーティファクトを使って Package Acceptance を `source=artifact`、`suite_profile=custom`、`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、`published_upgrade_survivor_baselines=all-since-2026.4.23`、`published_upgrade_survivor_scenarios=reported-issues`、`telegram_mode=mock-openai` で実行します。Package Acceptance は、同じ解決済み tarball に対して、migration、update、古い Plugin 依存関係クリーンアップ、offline Plugin fixtures、Plugin update、Telegram package QA を維持します。upgrade マトリクスは、`2026.4.23` から `latest` までのすべての stable npm 公開済みベースラインを対象にします。すでに出荷済みの候補には `source=npm` の Package Acceptance を使用し、公開前の SHA 裏付けのローカル npm tarball には `source=ref`/`source=artifact` を使用します。これは、以前は Parallels が必要だったパッケージ/update カバレッジの大半を置き換える GitHub ネイティブな手段です。クロス OS リリースチェックは、OS 固有のオンボーディング、installer、プラットフォーム動作のために引き続き重要ですが、パッケージ/update 製品検証では Package Acceptance を優先してください。
|
||||
`OpenClaw Release Checks` は、`source=artifact`、準備済みリリースパッケージアーティファクト、`suite_profile=custom`、
|
||||
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`、
|
||||
`published_upgrade_survivor_baselines=all-since-2026.4.23`、
|
||||
`published_upgrade_survivor_scenarios=reported-issues`、および
|
||||
`telegram_mode=mock-openai` で Package Acceptance を実行します。Package Acceptance は、同じ解決済み tarball に対して、マイグレーション、更新、古い Plugin 依存関係のクリーンアップ、オフライン Plugin フィクスチャ、Plugin 更新、Telegram パッケージ QA を維持します。アップグレードマトリクスは、`2026.4.23` から `latest` までのすべての stable npm 公開済みベースラインをカバーします。すでに出荷済みの候補には `source=npm` で Package Acceptance を使用し、公開前の SHA 裏付けのあるローカル npm tarball には `source=ref`/`source=artifact` を使用します。これは、以前 Parallels を必要としていたパッケージ/更新カバレッジの大半に対する GitHub ネイティブな置き換えです。クロス OS リリースチェックは、OS 固有のオンボーディング、インストーラー、プラットフォーム挙動に引き続き重要ですが、パッケージ/更新のプロダクト検証では Package Acceptance を優先すべきです。
|
||||
|
||||
update と Plugin 検証の正規チェックリストは、[update と Plugin のテスト](/ja-JP/help/testing-updates-plugins)です。Plugin install/update、doctor cleanup、または公開済みパッケージ migration の変更を、どのローカル、Docker、Package Acceptance、または release-check レーンで証明するかを決めるときに使用します。すべての stable `2026.4.23+` パッケージからの網羅的な公開済み update migration は、Full Release CI の一部ではなく、別個の手動 `Update Migration` ワークフローです。
|
||||
更新と Plugin 検証の正規チェックリストは[更新と Plugin のテスト](/ja-JP/help/testing-updates-plugins)です。Plugin のインストール/更新、doctor クリーンアップ、または公開パッケージマイグレーション変更を証明するローカル、Docker、Package Acceptance、またはリリースチェックレーンを決める際に使用します。
|
||||
すべての stable `2026.4.23+` パッケージからの網羅的な公開済み更新マイグレーションは、Full Release CI の一部ではなく、別個の手動 `Update Migration` ワークフローです。
|
||||
|
||||
レガシー package-acceptance の寛容さは、意図的に期間限定です。`2026.4.25` までのパッケージは、すでに npm に公開されたメタデータの欠落に対して互換性パスを使用できます。tarball にない private QA inventory entries、欠落した `gateway install --wrapper`、tarball 由来の git fixture にない patch files、永続化されていない `update.channel`、レガシー Plugin install-record locations、marketplace install-record persistence の欠落、`plugins update` 中の config metadata migration が該当します。公開済みの `2026.4.26` パッケージは、すでに出荷されたローカルビルドメタデータスタンプファイルについて警告する場合があります。それ以降のパッケージは、現代的なパッケージ契約を満たす必要があります。同じ欠落はリリース検証で失敗します。
|
||||
レガシー package-acceptance の緩和は、意図的に期限付きです。`2026.4.25` までのパッケージは、すでに npm に公開されたメタデータギャップについて互換パスを使用できます。対象は、tarball にない private QA インベントリエントリ、欠落した `gateway install --wrapper`、tarball 由来の git フィクスチャ内の欠落したパッチファイル、永続化されていない `update.channel`、レガシー Plugin インストールレコードの場所、マーケットプレイスインストールレコード永続化の欠落、`plugins update` 中の設定メタデータマイグレーションです。公開済みの `2026.4.26` パッケージは、すでに出荷されたローカルビルドメタデータスタンプファイルについて警告する場合があります。それ以降のパッケージは、現代的なパッケージ契約を満たす必要があります。同じギャップはリリース検証で失敗します。
|
||||
|
||||
リリースの論点が実際にインストール可能なパッケージに関する場合は、より広範な Package Acceptance プロファイルを使用します。
|
||||
リリース上の問いが実際のインストール可能パッケージに関するものである場合は、より広範な Package Acceptance プロファイルを使用します。
|
||||
|
||||
```bash
|
||||
gh workflow run package-acceptance.yml \
|
||||
@ -278,20 +328,24 @@ gh workflow run package-acceptance.yml \
|
||||
|
||||
一般的なパッケージプロファイル:
|
||||
|
||||
- `smoke`: クイックなパッケージインストール/チャンネル/エージェント、Gateway ネットワーク、設定リロードのレーン
|
||||
- `package`: live ClawHub なしのインストール/更新/Plugin パッケージ契約。これはリリースチェックのデフォルト
|
||||
- `product`: `package` に加えて MCP チャンネル、cron/サブエージェントのクリーンアップ、OpenAI web検索、OpenWebUI
|
||||
- `smoke`: パッケージのクイックインストール/チャネル/エージェント、Gateway ネットワーク、設定
|
||||
リロードのレーン
|
||||
- `package`: ライブ ClawHub なしでのインストール/更新/Plugin パッケージ契約。これは release-check の
|
||||
デフォルト
|
||||
- `product`: `package` に加えて、MCP チャネル、cron/サブエージェントのクリーンアップ、OpenAI web
|
||||
search、OpenWebUI
|
||||
- `full`: OpenWebUI を含む Docker リリースパスのチャンク
|
||||
- `custom`: 焦点を絞った再実行用の正確な `docker_lanes` リスト
|
||||
- `custom`: 集中的な再実行用の正確な `docker_lanes` リスト
|
||||
|
||||
パッケージ候補の Telegram 証明には、Package Acceptance で `telegram_mode=mock-openai` または
|
||||
パッケージ候補の Telegram 証明では、Package Acceptance で `telegram_mode=mock-openai` または
|
||||
`telegram_mode=live-frontier` を有効にします。このワークフローは、解決済みの
|
||||
`package-under-test` tarball を Telegram レーンに渡します。スタンドアロンの
|
||||
Telegram ワークフローは、公開後チェック用に公開済み npm 仕様を引き続き受け付けます。
|
||||
Telegram ワークフローは、公開後チェック用に公開済み npm spec も引き続き受け付けます。
|
||||
|
||||
## リリース公開の自動化
|
||||
## リリース公開自動化
|
||||
|
||||
`OpenClaw Release Publish` は通常の変更を伴う公開エントリーポイントです。リリースに必要な順序で、信頼済み公開者ワークフローをオーケストレーションします。
|
||||
`OpenClaw Release Publish` は通常の変更を伴う公開エントリポイントです。これは、
|
||||
リリースに必要な順序で trusted-publisher ワークフローをオーケストレーションします。
|
||||
|
||||
1. リリースタグをチェックアウトし、そのコミット SHA を解決します。
|
||||
2. タグが `main` または `release/*` から到達可能であることを検証します。
|
||||
@ -320,7 +374,7 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=beta
|
||||
```
|
||||
|
||||
`latest` へ直接安定版を昇格する場合は明示的に指定します:
|
||||
`latest` へ直接行う安定版昇格は明示的です。
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-release-publish.yml \
|
||||
@ -330,59 +384,70 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=latest
|
||||
```
|
||||
|
||||
低レベルの `Plugin NPM Release` と `Plugin ClawHub Release` ワークフローは、焦点を絞った修復または再公開作業にのみ使用してください。選択した Plugin 修復では、`OpenClaw Release Publish` に `plugin_publish_scope=selected` と `plugins=@openclaw/name` を渡すか、OpenClaw パッケージを公開してはならない場合は子ワークフローを直接ディスパッチします。
|
||||
下位レベルの `Plugin NPM Release` と `Plugin ClawHub Release` ワークフローは、
|
||||
集中的な修復または再公開作業にのみ使用します。選択した Plugin の修復では、
|
||||
`plugin_publish_scope=selected` と `plugins=@openclaw/name` を
|
||||
`OpenClaw Release Publish` に渡すか、OpenClaw パッケージを公開してはいけない場合は
|
||||
子ワークフローを直接ディスパッチします。
|
||||
|
||||
## NPM ワークフロー入力
|
||||
|
||||
`OpenClaw NPM Release` は、次のオペレーター制御入力を受け付けます:
|
||||
`OpenClaw NPM Release` は、オペレーターが制御する次の入力を受け付けます。
|
||||
|
||||
- `tag`: 必須のリリースタグ。例: `v2026.4.2`、`v2026.4.2-1`、`v2026.4.2-beta.1`。`preflight_only=true` の場合は、検証専用プリフライト用に現在の完全な 40 文字のワークフローブランチコミット SHA も使用できます
|
||||
- `tag`: `v2026.4.2`、`v2026.4.2-1`、または
|
||||
`v2026.4.2-beta.1` のような必須のリリースタグ。`preflight_only=true` の場合は、
|
||||
検証専用プリフライト用に現在の完全な 40 文字のワークフローブランチコミット SHA も使用できます
|
||||
- `preflight_only`: 検証/ビルド/パッケージのみの場合は `true`、実際の公開パスの場合は `false`
|
||||
- `preflight_run_id`: 実際の公開パスで必須。ワークフローが成功したプリフライト実行から準備済み tarball を再利用するために使用します
|
||||
- `preflight_run_id`: 実際の公開パスで必須。ワークフローが成功したプリフライト実行から準備済み tarball を再利用するために使います
|
||||
- `npm_dist_tag`: 公開パスの npm ターゲットタグ。デフォルトは `beta`
|
||||
|
||||
`OpenClaw Release Publish` は、次のオペレーター制御入力を受け付けます:
|
||||
`OpenClaw Release Publish` は、オペレーターが制御する次の入力を受け付けます。
|
||||
|
||||
- `tag`: 必須のリリースタグ。すでに存在している必要があります
|
||||
- `preflight_run_id`: 成功した `OpenClaw NPM Release` プリフライト実行 ID。`publish_openclaw_npm=true` の場合は必須
|
||||
- `preflight_run_id`: 成功した `OpenClaw NPM Release` プリフライト実行 id。
|
||||
`publish_openclaw_npm=true` の場合に必須です
|
||||
- `npm_dist_tag`: OpenClaw パッケージの npm ターゲットタグ
|
||||
- `plugin_publish_scope`: デフォルトは `all-publishable`。焦点を絞った修復作業の場合のみ `selected` を使用します
|
||||
- `plugins`: `plugin_publish_scope=selected` の場合のカンマ区切りの `@openclaw/*` パッケージ名
|
||||
- `publish_openclaw_npm`: デフォルトは `true`。ワークフローを Plugin のみの修復オーケストレーターとして使用する場合のみ `false` に設定します
|
||||
- `plugin_publish_scope`: デフォルトは `all-publishable`。集中的な修復作業にのみ `selected` を使用します
|
||||
- `plugins`: `plugin_publish_scope=selected` の場合の、カンマ区切りの `@openclaw/*` パッケージ名
|
||||
- `publish_openclaw_npm`: デフォルトは `true`。ワークフローを Plugin のみの修復オーケストレーターとして使用する場合にのみ `false` を設定します
|
||||
|
||||
`OpenClaw Release Checks` は、次のオペレーター制御入力を受け付けます:
|
||||
`OpenClaw Release Checks` は、オペレーターが制御する次の入力を受け付けます。
|
||||
|
||||
- `ref`: 検証するブランチ、タグ、または完全なコミット SHA。シークレットを伴うチェックでは、解決済みコミットが OpenClaw ブランチまたはリリースタグから到達可能である必要があります。
|
||||
- `ref`: 検証するブランチ、タグ、または完全なコミット SHA。シークレットを伴うチェックでは、
|
||||
解決済みコミットが OpenClaw ブランチまたはリリースタグから到達可能である必要があります。
|
||||
|
||||
ルール:
|
||||
|
||||
- 安定版タグと修正タグは `beta` または `latest` のどちらにも公開できます
|
||||
- ベータのプレリリースタグは `beta` にのみ公開できます
|
||||
- 安定版タグと修正タグは `beta` または `latest` のいずれかへ公開できます
|
||||
- ベータプレリリースタグは `beta` にのみ公開できます
|
||||
- `OpenClaw NPM Release` では、完全なコミット SHA 入力は `preflight_only=true` の場合にのみ許可されます
|
||||
- `OpenClaw Release Checks` と `Full Release Validation` は常に検証専用です
|
||||
- 実際の公開パスでは、プリフライト時に使用したものと同じ `npm_dist_tag` を使用する必要があります。ワークフローは公開を続行する前にそのメタデータを検証します
|
||||
- 実際の公開パスでは、プリフライト中に使用したものと同じ `npm_dist_tag` を使う必要があります。
|
||||
ワークフローは、公開前にそのメタデータが継続していることを検証します
|
||||
|
||||
## 安定版 npm リリース手順
|
||||
|
||||
安定版 npm リリースを切る場合:
|
||||
|
||||
1. `preflight_only=true` で `OpenClaw NPM Release` を実行します
|
||||
- タグが存在する前は、プリフライトワークフローの検証専用ドライランに現在の完全なワークフローブランチコミット SHA を使用できます
|
||||
2. 通常のベータ優先フローでは `npm_dist_tag=beta` を選択し、意図的に直接安定版を公開したい場合のみ `latest` を選択します
|
||||
3. 1 つの手動ワークフローから通常の CI に加えて live プロンプトキャッシュ、Docker、QA Lab、Matrix、Telegram のカバレッジが必要な場合は、リリースブランチ、リリースタグ、または完全なコミット SHA で `Full Release Validation` を実行します
|
||||
4. 意図的に決定的な通常のテストグラフだけが必要な場合は、代わりにリリース ref で手動の `CI` ワークフローを実行します
|
||||
- タグが存在する前は、プリフライトワークフローの検証専用ドライランとして、現在の完全なワークフローブランチコミット SHA を使用できます
|
||||
2. 通常の beta-first フローでは `npm_dist_tag=beta` を選択します。直接の安定版公開を意図している場合にのみ `latest` を選択します
|
||||
3. 1 つの手動ワークフローから通常の CI に加えて、ライブプロンプトキャッシュ、Docker、QA Lab、Matrix、Telegram のカバレッジが必要な場合は、リリースブランチ、リリースタグ、または完全なコミット SHA で `Full Release Validation` を実行します
|
||||
4. 決定的な通常テストグラフだけが必要な場合は、代わりにリリース ref で手動の `CI` ワークフローを実行します
|
||||
5. 成功した `preflight_run_id` を保存します
|
||||
6. 同じ `tag`、同じ `npm_dist_tag`、保存済みの `preflight_run_id` で `OpenClaw Release Publish` を実行します。OpenClaw npm パッケージを昇格する前に、外部化された Plugin を npm と ClawHub に公開します
|
||||
7. リリースが `beta` に着地した場合は、非公開の `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` ワークフローを使用して、その安定版を `beta` から `latest` へ昇格します
|
||||
8. リリースを意図的に `latest` に直接公開し、`beta` も同じ安定版ビルドをすぐに指す必要がある場合は、同じ非公開ワークフローを使用して両方の dist-tag を安定版に向けるか、スケジュールされた自己修復同期で後から `beta` を移動させます
|
||||
6. 同じ `tag`、同じ `npm_dist_tag`、保存済みの `preflight_run_id` で `OpenClaw Release Publish` を実行します。これは OpenClaw npm パッケージを昇格する前に、外部化された Plugin を npm と ClawHub に公開します
|
||||
7. リリースが `beta` に着地した場合は、非公開の
|
||||
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
|
||||
ワークフローを使用して、その安定版を `beta` から `latest` へ昇格します
|
||||
8. リリースを意図的に直接 `latest` へ公開し、`beta` もすぐに同じ安定版ビルドを指すべき場合は、同じ非公開ワークフローを使用して両方の dist-tag を安定版に向けるか、スケジュールされた自己修復同期によって後で `beta` が移動するようにします
|
||||
|
||||
dist-tag の変更は、引き続き `NPM_TOKEN` を必要とするため、セキュリティ上の理由で非公開リポジトリに置かれています。一方、公開リポジトリは OIDC のみの公開を維持します。
|
||||
dist-tag の変更は、引き続き `NPM_TOKEN` を必要とするため、セキュリティ上の理由で非公開リポジトリにあります。一方、公開リポジトリは OIDC のみの公開を維持します。
|
||||
|
||||
これにより、直接公開パスとベータ優先の昇格パスの両方が文書化され、オペレーターから見える状態になります。
|
||||
これにより、直接公開パスと beta-first 昇格パスの両方が文書化され、オペレーターから見える状態になります。
|
||||
|
||||
メンテナーがローカル npm 認証へフォールバックする必要がある場合は、1Password CLI (`op`) コマンドを専用の tmux セッション内でのみ実行してください。メインのエージェントシェルから `op` を直接呼び出さないでください。tmux 内に閉じ込めることで、プロンプト、アラート、OTP 処理を観察可能にし、ホストアラートの繰り返しを防げます。
|
||||
メンテナーがローカル npm 認証にフォールバックする必要がある場合は、1Password CLI（`op`）コマンドを専用の tmux セッション内でのみ実行します。メインエージェントシェルから `op` を直接呼び出さないでください。tmux 内に保つことで、プロンプト、アラート、OTP 処理を観測可能にし、ホストアラートの繰り返しを防げます。
|
||||
|
||||
## 公開リファレンス
|
||||
## 公開参照
|
||||
|
||||
- [`.github/workflows/full-release-validation.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/full-release-validation.yml)
|
||||
- [`.github/workflows/package-acceptance.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/package-acceptance.yml)
|
||||
@ -394,10 +459,10 @@ dist-tag の変更は、引き続き `NPM_TOKEN` を必要とするため、セ
|
||||
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
|
||||
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
|
||||
|
||||
メンテナーは、実際のランブックとして非公開リリースドキュメント
|
||||
メンテナーは、実際のランブックには非公開のリリースドキュメント
|
||||
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
|
||||
を使用します。
|
||||
|
||||
## 関連
|
||||
|
||||
- [リリースチャンネル](/ja-JP/install/development-channels)
|
||||
- [リリースチャネル](/ja-JP/install/development-channels)
|
||||
|
||||
@ -1,48 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- エージェント経由でバックグラウンド作業または並列作業を行いたい場合
|
||||
- sessions_spawn またはサブエージェントツールのポリシーを変更しています
|
||||
- sessions_spawn またはサブエージェントツールポリシーを変更しています
|
||||
- スレッドに紐づくサブエージェントセッションを実装またはトラブルシューティングしている
|
||||
sidebarTitle: Sub-agents
|
||||
summary: 依頼者のチャットへ結果を通知する、隔離されたバックグラウンドエージェント実行を起動する
|
||||
summary: 結果を依頼者のチャットへ通知する、分離されたバックグラウンドエージェント実行を起動します
|
||||
title: サブエージェント
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T05:03:09Z"
|
||||
generated_at: "2026-05-04T07:04:34Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d0df39e06b952def3eb0b296f36c7dc8c0b0a115785d865236a970c5d453fc37
|
||||
source_hash: 65d60bf6813d667b7311aa28109d4bd6be012a16e638c64cfff130831db88cd8
|
||||
source_path: tools/subagents.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
サブエージェントは、既存のエージェント実行から生成されるバックグラウンドのエージェント実行です。
|
||||
各サブエージェントは独自のセッション (`agent:<agentId>:subagent:<uuid>`) で実行され、
|
||||
完了すると、その結果をリクエスト元のチャット
|
||||
チャンネルに**通知**します。各サブエージェント実行は
|
||||
それらは独自のセッション（`agent:<agentId>:subagent:<uuid>`）で実行され、
|
||||
完了すると、その結果をリクエスト元のチャットチャネルへ**通知**します。
|
||||
各サブエージェント実行は
|
||||
[バックグラウンドタスク](/ja-JP/automation/tasks)として追跡されます。
|
||||
|
||||
主な目的:
|
||||
主な目標:
|
||||
|
||||
- メイン実行をブロックせずに「調査 / 長時間タスク / 遅いツール」の作業を並列化する。
|
||||
- サブエージェントをデフォルトで分離しておく（セッション分離 + 任意のサンドボックス化）。
|
||||
- ツール面を誤用しにくく保つ: サブエージェントにはデフォルトでセッションツールを与えない。
|
||||
- メイン実行をブロックせずに、「調査 / 長時間タスク / 遅いツール」の作業を並列化する。
|
||||
- サブエージェントをデフォルトで分離したままにする（セッション分離 + 任意のサンドボックス化）。
|
||||
- ツール面を誤用しにくく保つ: サブエージェントはデフォルトではセッションツールを取得しない。
|
||||
- オーケストレーターパターン向けに、設定可能なネスト深度をサポートする。
|
||||
|
||||
<Note>
|
||||
**コストに関する注記:** 各サブエージェントはデフォルトで独自のコンテキストとトークン使用量を持ちます。
|
||||
重いタスクや反復的なタスクでは、サブエージェントに安価なモデルを設定し、
|
||||
メインエージェントは高品質なモデルのままにしてください。
|
||||
`agents.defaults.subagents.model` またはエージェントごとの上書きで設定します。子が
|
||||
リクエスト元の現在のトランスクリプトを本当に必要とする場合、その生成に限って
|
||||
`context: "fork"` を要求できます。スレッドに紐付いたサブエージェントセッションは、
|
||||
現在の会話をフォローアップスレッドへ分岐するため、デフォルトで
|
||||
`context: "fork"` になります。
|
||||
**コストに関する注意:** 各サブエージェントは、デフォルトで独自のコンテキストとトークン使用量を持ちます。重いタスクや反復的なタスクでは、サブエージェントにより安価なモデルを設定し、メインエージェントは高品質なモデルのままにしてください。`agents.defaults.subagents.model` またはエージェントごとの上書きで設定します。子がリクエスト元の現在のトランスクリプトを本当に必要とする場合、エージェントはその 1 回の生成で `context: "fork"` をリクエストできます。スレッドに紐づくサブエージェントセッションは、現在の会話をフォローアップスレッドへ分岐するため、デフォルトで `context: "fork"` になります。
|
||||
</Note>
|
||||
|
||||
## スラッシュコマンド
|
||||
|
||||
**現在の
|
||||
セッション**のサブエージェント実行を確認または制御するには、`/subagents` を使用します。
|
||||
**現在のセッション**のサブエージェント実行を確認または制御するには、`/subagents` を使用します。
|
||||
|
||||
```text
|
||||
/subagents list
|
||||
@ -54,17 +46,13 @@ x-i18n:
|
||||
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]
|
||||
```
|
||||
|
||||
現在のリクエスト元セッションのアクティブな実行を誘導するには、トップレベルの [`/steer <message>`](/ja-JP/tools/steer) を使用します。対象が子の実行である場合は、`/subagents steer <id|#> <message>` を使用します。
|
||||
現在のリクエスト元セッションのアクティブな実行を誘導するには、トップレベルの [`/steer <message>`](/ja-JP/tools/steer) を使用します。対象が子実行の場合は、`/subagents steer <id|#> <message>` を使用します。
|
||||
|
||||
`/subagents info` は実行メタデータ（ステータス、タイムスタンプ、セッション id、
|
||||
トランスクリプトパス、クリーンアップ）を表示します。境界付きで
|
||||
安全性フィルター済みの呼び出しビューには `sessions_history` を使用し、
|
||||
未加工の完全なトランスクリプトが必要な場合は、ディスク上のトランスクリプトパスを確認します。
|
||||
`/subagents info` は実行メタデータ（ステータス、タイムスタンプ、セッション ID、トランスクリプトパス、クリーンアップ）を表示します。境界付きで安全性フィルター済みの想起ビューには `sessions_history` を使用し、生の完全なトランスクリプトが必要な場合はディスク上のトランスクリプトパスを確認してください。
|
||||
|
||||
### スレッド紐付け制御
|
||||
### スレッド紐づけ制御
|
||||
|
||||
これらのコマンドは、永続的なスレッド紐付けをサポートするチャンネルで機能します。
|
||||
下記の[スレッドをサポートするチャンネル](#thread-supporting-channels)を参照してください。
|
||||
これらのコマンドは、永続的なスレッド紐づけをサポートするチャネルで機能します。下の[スレッド対応チャネル](#thread-supporting-channels)を参照してください。
|
||||
|
||||
```text
|
||||
/focus <subagent-label|session-key|session-id|session-label>
|
||||
@ -74,76 +62,67 @@ x-i18n:
|
||||
/session max-age <duration|off>
|
||||
```
|
||||
|
||||
### 生成動作
|
||||
### 生成時の動作
|
||||
|
||||
`/subagents spawn` は、内部リレーではなくユーザーコマンドとしてバックグラウンドサブエージェントを開始し、
|
||||
実行が完了すると、リクエスト元チャットへ最終的な完了更新を 1 件送信します。
|
||||
`/subagents spawn` は、バックグラウンドのサブエージェントを（内部リレーではなく）ユーザーコマンドとして開始し、実行が完了したときにリクエスト元チャットへ最後の完了更新を 1 回送信します。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="非ブロッキングでプッシュ型の完了">
|
||||
- 生成コマンドは非ブロッキングで、実行 id を即座に返します。
|
||||
- 完了時に、サブエージェントはリクエスト元チャットチャンネルへ要約/結果メッセージを通知します。
|
||||
- 完了はプッシュ型です。生成後は、完了を待つためだけに `/subagents list`、`sessions_list`、`sessions_history` をループでポーリングしないでください。デバッグや介入のために必要な場合のみ、オンデマンドでステータスを確認します。
|
||||
- 完了時に、OpenClaw は通知のクリーンアップフローが続く前に、そのサブエージェントセッションが開いた追跡対象のブラウザータブ/プロセスをベストエフォートで閉じます。
|
||||
<Accordion title="Non-blocking, push-based completion">
|
||||
- spawn コマンドは非ブロッキングで、実行 ID を即座に返します。
|
||||
- 完了時に、サブエージェントは要約/結果メッセージをリクエスト元のチャットチャネルへ通知します。
|
||||
- 完了はプッシュベースです。生成後は、完了を待つためだけに `/subagents list`、`sessions_list`、`sessions_history` をループでポーリングしないでください。ステータス確認は、デバッグや介入が必要な場合にオンデマンドでのみ行ってください。
|
||||
- 完了時に、OpenClaw は通知クリーンアップフローが続行される前に、そのサブエージェントセッションが開いた追跡対象のブラウザータブ/プロセスをベストエフォートで閉じます。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="手動生成の配信耐性">
|
||||
- OpenClaw はまず、安定した冪等性キーで直接 `agent` 配信を試みます。
|
||||
- 直接配信に失敗した場合、キュールーティングへフォールバックします。
|
||||
- キュールーティングもまだ利用できない場合、最終的に諦める前に、短い指数バックオフで通知を再試行します。
|
||||
- 完了配信は、解決済みのリクエスト元ルートを保持します。利用可能な場合は、スレッドに紐付いた完了ルートまたは会話に紐付いた完了ルートが優先されます。完了元がチャンネルのみを提供する場合、OpenClaw はリクエスト元セッションの解決済みルート（`lastChannel` / `lastTo` / `lastAccountId`）から不足している対象/アカウントを補完し、直接配信が引き続き機能するようにします。
|
||||
<Accordion title="Manual-spawn delivery resilience">
|
||||
- OpenClaw はまず、安定した冪等性キーを使って直接 `agent` 配信を試行します。
|
||||
- リクエスト元エージェントの完了ターンが失敗する、可視出力を生成しない、またはキャプチャされた子の結果の明らかに不完全な接頭部分を返す場合、OpenClaw はキャプチャされた子の結果から直接完了配信するフォールバックを行います。
|
||||
- 直接配信を使用できない場合は、キュールーティングへフォールバックします。
|
||||
- キュールーティングもまだ利用できない場合、最終的に諦める前に、通知は短い指数バックオフで再試行されます。
|
||||
- 完了配信は、解決済みのリクエスト元ルートを維持します。スレッド紐づけまたは会話紐づけの完了ルートが利用可能な場合はそれらが優先されます。完了の起点がチャネルしか提供しない場合、OpenClaw はリクエスト元セッションの解決済みルート（`lastChannel` / `lastTo` / `lastAccountId`）から不足している対象/アカウントを補完し、直接配信が引き続き機能するようにします。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="完了引き渡しメタデータ">
|
||||
リクエスト元セッションへの完了引き渡しは、実行時に生成される
|
||||
内部コンテキスト（ユーザーが作成したテキストではありません）で、次を含みます。
|
||||
<Accordion title="Completion handoff metadata">
|
||||
リクエスト元セッションへの完了ハンドオフは、ランタイム生成の内部コンテキスト（ユーザーが作成したテキストではありません）であり、以下を含みます。
|
||||
|
||||
- `Result` — 最新の可視 `assistant` 返信テキスト。それがない場合は、サニタイズ済みの最新ツール/ツール結果テキスト。終端で失敗した実行は、取得済みの返信テキストを再利用しません。
|
||||
- `Result` — 最新の可視 `assistant` 返信テキスト。なければ、サニタイズ済みの最新 tool/toolResult テキスト。終了済みの失敗実行では、キャプチャされた返信テキストは再利用されません。
|
||||
- `Status` — `completed successfully` / `failed` / `timed out` / `unknown`。
|
||||
- コンパクトな実行時/トークン統計。
|
||||
- リクエスト元エージェントに、未加工の内部メタデータを転送せず、通常のアシスタントの声で書き直すよう伝える配信指示。
|
||||
- コンパクトなランタイム/トークン統計。
|
||||
- リクエスト元エージェントに、通常のアシスタントの声で書き直す（生の内部メタデータを転送しない）よう指示する配信指示。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="モードと ACP ランタイム">
|
||||
<Accordion title="Modes and ACP runtime">
|
||||
- `--model` と `--thinking` は、その特定の実行のデフォルトを上書きします。
|
||||
- 完了後に詳細と出力を確認するには、`info`/`log` を使用します。
|
||||
- `/subagents spawn` はワンショットモード（`mode: "run"`）です。永続的なスレッド紐付きセッションには、`thread: true` と `mode: "session"` を指定して `sessions_spawn` を使用します。
|
||||
- ACP ハーネスセッション（Claude Code、Gemini CLI、OpenCode、または明示的な Codex ACP/acpx）では、ツールがそのランタイムを公開している場合に `runtime: "acp"` を指定して `sessions_spawn` を使用します。完了やエージェント間ループをデバッグするときは、[ACP 配信モデル](/ja-JP/tools/acp-agents#delivery-model)を参照してください。`codex` plugin が有効な場合、Codex のチャット/スレッド制御では、ユーザーが ACP/acpx を明示的に求めない限り、ACP より `/codex ...` を優先してください。
|
||||
- OpenClaw は、ACP が有効で、リクエスト元がサンドボックス化されておらず、`acpx` などのバックエンド plugin が読み込まれるまで、`runtime: "acp"` を隠します。`runtime: "acp"` は、外部 ACP ハーネス id、または `runtime.type="acp"` を持つ `agents.list[]` エントリを想定します。`agents_list` の通常の OpenClaw 設定エージェントには、デフォルトのサブエージェントランタイムを使用してください。
|
||||
- 完了後に詳細と出力を調べるには `info`/`log` を使用します。
|
||||
- `/subagents spawn` はワンショットモード（`mode: "run"`）です。永続的なスレッド紐付けセッションには、`thread: true` と `mode: "session"` を指定して `sessions_spawn` を使用します。
|
||||
- ACP ハーネスセッション（Claude Code、Gemini CLI、OpenCode、または明示的な Codex ACP/acpx）では、ツールがそのランタイムを通知している場合に `runtime: "acp"` を指定して `sessions_spawn` を使用します。完了やエージェント間ループをデバッグする場合は、[ACP 配信モデル](/ja-JP/tools/acp-agents#delivery-model) を参照してください。`codex` plugin が有効な場合、ユーザーが明示的に ACP/acpx を求めない限り、Codex のチャット/スレッド制御では ACP より `/codex ...` を優先してください。
|
||||
- OpenClaw は、ACP が有効で、リクエスターがサンドボックス化されておらず、`acpx` などのバックエンド plugin が読み込まれるまで、`runtime: "acp"` を非表示にします。`runtime: "acp"` は外部 ACP ハーネス ID、または `runtime.type="acp"` を持つ `agents.list[]` エントリを想定します。`agents_list` の通常の OpenClaw 設定エージェントには、デフォルトのサブエージェントランタイムを使用します。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## コンテキストモード
|
||||
|
||||
ネイティブサブエージェントは、呼び出し元が現在のトランスクリプトのフォークを明示的に要求しない限り、分離状態で開始します。
|
||||
ネイティブサブエージェントは、呼び出し元が現在のトランスクリプトのフォークを明示的に要求しない限り、分離された状態で開始します。
|
||||
|
||||
| モード | 使用する場面 | 動作 |
|
||||
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| `isolated` | 新規調査、独立した実装、遅いツール作業、またはタスク本文で説明できるあらゆる作業 | クリーンな子トランスクリプトを作成します。これがデフォルトで、トークン使用量を低く保ちます。 |
|
||||
| `fork` | 現在の会話、以前のツール結果、またはリクエスト元トランスクリプトにすでに存在する微妙な指示に依存する作業 | 子の開始前に、リクエスト元トランスクリプトを子セッションへ分岐します。 |
|
||||
| `isolated` | 新規調査、独立した実装、時間のかかるツール作業、またはタスク本文で説明できるもの | クリーンな子トランスクリプトを作成します。これがデフォルトで、トークン使用量を抑えます。 |
|
||||
| `fork` | 現在の会話、以前のツール結果、またはリクエスターのトランスクリプトにすでに存在する細かな指示に依存する作業 | 子が開始する前に、リクエスターのトランスクリプトを子セッションへ分岐します。 |
|
||||
|
||||
`fork` は控えめに使用してください。これはコンテキストに敏感な委任のためのものであり、
|
||||
明確なタスクプロンプトを書くことの代替ではありません。
|
||||
`fork` は控えめに使用してください。これはコンテキスト依存の委任のためのものであり、明確なタスクプロンプトを書くことの代替ではありません。
|
||||
|
||||
## ツール: `sessions_spawn`
|
||||
|
||||
グローバルな `subagent` レーンで `deliver: false` のサブエージェント実行を開始し、
|
||||
その後に通知ステップを実行して、通知返信をリクエスト元チャットチャンネルへ投稿します。
|
||||
グローバル `subagent` レーンで `deliver: false` のサブエージェント実行を開始し、その後アナウンス手順を実行して、アナウンスの返信をリクエスターのチャットチャネルに投稿します。
|
||||
|
||||
利用可否は、呼び出し元の有効なツールポリシーに依存します。`coding` と
|
||||
`full` プロファイルは、デフォルトで `sessions_spawn` を公開します。`messaging` プロファイルは
|
||||
公開しません。作業を委任する必要があるエージェントには、`tools.alsoAllow: ["sessions_spawn", "sessions_yield",
|
||||
"subagents"]` を追加するか、`tools.profile: "coding"` を使用します。
|
||||
チャンネル/グループ、プロバイダー、サンドボックス、エージェントごとの許可/拒否ポリシーは、
|
||||
プロファイル段階の後でもツールを削除できます。同じ
|
||||
セッションから `/tools` を使用して、有効なツール一覧を確認してください。
|
||||
利用可否は、呼び出し元の実効ツールポリシーによって異なります。`coding` と `full` プロファイルは、デフォルトで `sessions_spawn` を公開します。`messaging` プロファイルは公開しません。作業を委任すべきエージェントには、`tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"]` を追加するか、`tools.profile: "coding"` を使用します。チャネル/グループ、プロバイダー、サンドボックス、エージェントごとの許可/拒否ポリシーによって、プロファイル段階の後でもツールが削除されることがあります。同じセッションから `/tools` を使用して、実効ツール一覧を確認してください。
|
||||
|
||||
**デフォルト:**
|
||||
|
||||
- **モデル:** `agents.defaults.subagents.model`（またはエージェントごとの `agents.list[].subagents.model`）を設定しない限り、呼び出し元を継承します。明示的な `sessions_spawn.model` がある場合は、そちらが引き続き優先されます。
|
||||
- **Thinking:** `agents.defaults.subagents.thinking`（またはエージェントごとの `agents.list[].subagents.thinking`）を設定しない限り、呼び出し元を継承します。明示的な `sessions_spawn.thinking` がある場合は、そちらが引き続き優先されます。
|
||||
- **実行タイムアウト:** `sessions_spawn.runTimeoutSeconds` が省略された場合、設定されていれば OpenClaw は `agents.defaults.subagents.runTimeoutSeconds` を使用します。そうでなければ `0`（タイムアウトなし）へフォールバックします。
|
||||
- **モデル:** `agents.defaults.subagents.model`（またはエージェントごとの `agents.list[].subagents.model`）を設定しない限り、呼び出し元を継承します。明示的な `sessions_spawn.model` は引き続き優先されます。
|
||||
- **Thinking:** `agents.defaults.subagents.thinking`（またはエージェントごとの `agents.list[].subagents.thinking`）を設定しない限り、呼び出し元を継承します。明示的な `sessions_spawn.thinking` は引き続き優先されます。
|
||||
- **実行タイムアウト:** `sessions_spawn.runTimeoutSeconds` が省略された場合、OpenClaw は設定されていれば `agents.defaults.subagents.runTimeoutSeconds` を使用します。それ以外の場合は `0`（タイムアウトなし）にフォールバックします。
|
||||
|
||||
### ツールパラメーター
|
||||
|
||||
@ -154,135 +133,128 @@ x-i18n:
|
||||
任意の人間が読めるラベル。
|
||||
</ParamField>
|
||||
<ParamField path="agentId" type="string">
|
||||
`subagents.allowAgents` で許可されている場合、別のエージェント id の下で生成します。
|
||||
`subagents.allowAgents` で許可されている場合、別のエージェント ID の下でスポーンします。
|
||||
</ParamField>
|
||||
<ParamField path="runtime" type='"subagent" | "acp"' default="subagent">
|
||||
`acp` は外部 ACP ハーネス（`claude`、`droid`、`gemini`、`opencode`、または明示的に要求された Codex ACP/acpx）、および `runtime.type` が `acp` の `agents.list[]` エントリ専用です。
|
||||
`acp` は、外部 ACP ハーネス（`claude`、`droid`、`gemini`、`opencode`、または明示的に要求された Codex ACP/acpx）と、`runtime.type` が `acp` の `agents.list[]` エントリ専用です。
|
||||
</ParamField>
|
||||
<ParamField path="resumeSessionId" type="string">
|
||||
ACP のみ。`runtime: "acp"` の場合に既存の ACP ハーネスセッションを再開します。ネイティブサブエージェント生成では無視されます。
|
||||
ACP 専用。`runtime: "acp"` の場合に既存の ACP ハーネスセッションを再開します。ネイティブサブエージェントのスポーンでは無視されます。
|
||||
</ParamField>
|
||||
<ParamField path="streamTo" type='"parent"'>
|
||||
ACP のみ。`runtime: "acp"` の場合に ACP 実行出力を親セッションへストリーミングします。ネイティブサブエージェント生成では省略します。
|
||||
ACP 専用。`runtime: "acp"` の場合に ACP 実行出力を親セッションにストリーミングします。ネイティブサブエージェントのスポーンでは省略します。
|
||||
</ParamField>
|
||||
<ParamField path="model" type="string">
|
||||
サブエージェントモデルを上書きします。無効な値はスキップされ、サブエージェントはデフォルトモデルで実行され、ツール結果に警告が表示されます。
|
||||
サブエージェントのモデルを上書きします。無効な値はスキップされ、サブエージェントはデフォルトモデルで実行され、ツール結果に警告が表示されます。
|
||||
</ParamField>
|
||||
<ParamField path="thinking" type="string">
|
||||
サブエージェント実行の Thinking レベルを上書きします。
|
||||
サブエージェント実行の thinking レベルを上書きします。
|
||||
</ParamField>
|
||||
<ParamField path="runTimeoutSeconds" type="number">
|
||||
設定されている場合は `agents.defaults.subagents.runTimeoutSeconds` がデフォルトになり、そうでなければ `0` になります。設定すると、サブエージェント実行は N 秒後に中止されます。
|
||||
設定されている場合は `agents.defaults.subagents.runTimeoutSeconds` がデフォルトになり、それ以外の場合は `0` です。設定すると、サブエージェント実行は N 秒後に中止されます。
|
||||
</ParamField>
|
||||
<ParamField path="thread" type="boolean" default="false">
|
||||
`true` の場合、このサブエージェントセッションにチャンネルスレッド紐付けを要求します。
|
||||
`true` の場合、このサブエージェントセッションにチャネルスレッド紐付けを要求します。
|
||||
</ParamField>
|
||||
<ParamField path="mode" type='"run" | "session"' default="run">
|
||||
`thread: true` で `mode` が省略された場合、デフォルトは `session` になります。`mode: "session"` には `thread: true` が必要です。
|
||||
`thread: true` で `mode` が省略されている場合、デフォルトは `session` になります。`mode: "session"` には `thread: true` が必要です。
|
||||
</ParamField>
|
||||
<ParamField path="cleanup" type='"delete" | "keep"' default="keep">
|
||||
`"delete"` は通知後すぐにアーカイブします（リネームによりトランスクリプトは保持します）。
|
||||
`"delete"` はアナウンス直後にアーカイブします（リネームによりトランスクリプトは保持されます）。
|
||||
</ParamField>
|
||||
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
|
||||
`require` は、対象の子ランタイムがサンドボックス化されていない限り生成を拒否します。
|
||||
`require` は、対象の子ランタイムがサンドボックス化されていない限りスポーンを拒否します。
|
||||
</ParamField>
|
||||
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
|
||||
`fork` は、リクエスト元の現在のトランスクリプトを子セッションへ分岐します。ネイティブサブエージェントのみ。スレッドに紐付いた生成はデフォルトで `fork`、非スレッド生成はデフォルトで `isolated` です。
|
||||
`fork` は、リクエスターの現在のトランスクリプトを子セッションへ分岐します。ネイティブサブエージェント専用です。スレッド紐付けスポーンはデフォルトで `fork`、非スレッドスポーンはデフォルトで `isolated` になります。
|
||||
</ParamField>
|
||||
|
||||
<Warning>
|
||||
`sessions_spawn` はチャンネル配信パラメーター（`target`、
|
||||
`channel`、`to`、`threadId`、`replyTo`、`transport`）を受け付けません。配信には、
|
||||
生成された実行から `message`/`sessions_send` を使用します。
|
||||
`sessions_spawn` は、チャネル配信パラメーター（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）を受け付けません。配信には、スポーンされた実行から `message`/`sessions_send` を使用します。
|
||||
</Warning>
|
||||
|
||||
## スレッド紐付きセッション
|
||||
## スレッド紐付けセッション
|
||||
|
||||
チャンネルでスレッド紐付けが有効な場合、サブエージェントはスレッドに紐付いたままでいられるため、
|
||||
そのスレッド内のフォローアップユーザーメッセージは同じサブエージェントセッションへルーティングされ続けます。
|
||||
チャネルでスレッド紐付けが有効な場合、サブエージェントはスレッドに紐付いたままでいられるため、そのスレッド内の後続ユーザーメッセージは同じサブエージェントセッションにルーティングされ続けます。
|
||||
|
||||
### スレッドをサポートするチャンネル
|
||||
### スレッド対応チャネル
|
||||
|
||||
**Discord** は現在、唯一サポートされているチャンネルです。これは
|
||||
永続的なスレッド紐付きサブエージェントセッション（`thread: true` を指定した `sessions_spawn`）、
|
||||
手動スレッド制御（`/focus`、`/unfocus`、`/agents`、
|
||||
`/session idle`、`/session max-age`）、およびアダプターキー
|
||||
`channels.discord.threadBindings.enabled`、
|
||||
`channels.discord.threadBindings.idleHours`、
|
||||
`channels.discord.threadBindings.maxAgeHours`、および
|
||||
`channels.discord.threadBindings.spawnSessions` をサポートします。
|
||||
**Discord** は現在唯一の対応チャネルです。永続的なスレッド紐付けサブエージェントセッション（`thread: true` を指定した `sessions_spawn`）、手動スレッド制御（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）、およびアダプターキー `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours`、`channels.discord.threadBindings.spawnSessions` をサポートします。
|
||||
|
||||
### クイックフロー
|
||||
|
||||
<Steps>
|
||||
<Step title="生成">
|
||||
`thread: true`（任意で `mode: "session"`）を指定して `sessions_spawn`。
|
||||
<Step title="Spawn">
|
||||
`sessions_spawn` を `thread: true`（および任意で `mode: "session"`）付きで使用します。
|
||||
</Step>
|
||||
<Step title="紐付け">
|
||||
OpenClaw は、そのセッション対象に対してアクティブなチャンネル内でスレッドを作成または紐付けます。
|
||||
<Step title="Bind">
|
||||
OpenClaw はアクティブなチャネル内で、そのセッションターゲットにスレッドを作成またはバインドします。
|
||||
</Step>
|
||||
<Step title="フォローアップのルーティング">
|
||||
そのスレッド内の返信とフォローアップメッセージは、紐付いたセッションへルーティングされます。
|
||||
<Step title="Route follow-ups">
|
||||
そのスレッド内の返信とフォローアップメッセージは、バインドされたセッションにルーティングされます。
|
||||
</Step>
|
||||
<Step title="タイムアウトの確認">
|
||||
非アクティブ時の自動フォーカス解除を確認/更新するには `/session idle` を使用し、
|
||||
ハード上限を制御するには `/session max-age` を使用します。
|
||||
<Step title="Inspect timeouts">
|
||||
`/session idle` を使用して、非アクティブ時の自動アンフォーカスを確認/更新し、
|
||||
`/session max-age` でハード上限を制御します。
|
||||
</Step>
|
||||
<Step title="切り離し">
|
||||
手動で切り離すには `/unfocus` を使用します。
|
||||
<Step title="Detach">
|
||||
`/unfocus` を使用して手動で切り離します。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 手動制御
|
||||
|
||||
| コマンド | 効果 |
|
||||
| コマンド | 効果 |
|
||||
| ------------------ | --------------------------------------------------------------------- |
|
||||
| `/focus <target>` | 現在のスレッドをサブエージェント/セッションターゲットにバインドする（または作成する） |
|
||||
| `/unfocus` | 現在バインドされているスレッドのバインドを削除する |
|
||||
| `/agents` | アクティブな実行とバインド状態（`thread:<id>` または `unbound`）を一覧表示する |
|
||||
| `/session idle` | アイドル時の自動アンフォーカスを確認/更新する（フォーカス中のバインド済みスレッドのみ） |
|
||||
| `/session max-age` | ハード上限を確認/更新する（フォーカス中のバインド済みスレッドのみ） |
|
||||
| `/focus <target>` | 現在のスレッドをサブエージェント/セッションターゲットにバインドします（または作成します） |
|
||||
| `/unfocus` | 現在バインドされているスレッドのバインドを削除します |
|
||||
| `/agents` | アクティブな実行とバインド状態（`thread:<id>` または `unbound`）を一覧表示します |
|
||||
| `/session idle` | アイドル時の自動アンフォーカスを確認/更新します（フォーカス中のバインド済みスレッドのみ） |
|
||||
| `/session max-age` | ハード上限を確認/更新します（フォーカス中のバインド済みスレッドのみ） |
|
||||
|
||||
### 設定スイッチ
|
||||
|
||||
- **グローバル既定値:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
|
||||
- **チャンネルのオーバーライドとスポーン時の自動バインドキー**はアダプター固有です。上記の[スレッド対応チャンネル](#thread-supporting-channels)を参照してください。
|
||||
- **チャネルのオーバーライドとスポーン時の自動バインドキー** はアダプター固有です。上記の [スレッド対応チャネル](#thread-supporting-channels) を参照してください。
|
||||
|
||||
現在のアダプター詳細については、[設定リファレンス](/ja-JP/gateway/configuration-reference)と
|
||||
[スラッシュコマンド](/ja-JP/tools/slash-commands)を参照してください。
|
||||
現在のアダプター詳細については、[設定リファレンス](/ja-JP/gateway/configuration-reference) と
|
||||
[スラッシュコマンド](/ja-JP/tools/slash-commands) を参照してください。
|
||||
|
||||
### 許可リスト
|
||||
|
||||
<ParamField path="agents.list[].subagents.allowAgents" type="string[]">
|
||||
明示的な `agentId`（`["*"]` は任意を許可）でターゲットにできるエージェント ID の一覧。既定値: リクエスト元エージェントのみ。一覧を設定し、リクエスト元が `agentId` で自身をスポーンできるようにもしたい場合は、リクエスト元 ID を一覧に含めます。
|
||||
明示的な `agentId`（`["*"]` は任意を許可）でターゲットにできるエージェント ID の一覧です。既定値: リクエスターエージェントのみ。一覧を設定し、それでもリクエスターが `agentId` で自分自身をスポーンできるようにしたい場合は、リクエスター ID を一覧に含めます。
|
||||
</ParamField>
|
||||
<ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
|
||||
リクエスト元エージェントが独自の `subagents.allowAgents` を設定していない場合に使われる、既定のターゲットエージェント許可リスト。
|
||||
リクエスターエージェントが独自の `subagents.allowAgents` を設定していない場合に使用される、既定のターゲットエージェント許可リストです。
|
||||
</ParamField>
|
||||
<ParamField path="agents.defaults.subagents.requireAgentId" type="boolean" default="false">
|
||||
`agentId` を省略した `sessions_spawn` 呼び出しをブロックします（明示的なプロファイル選択を強制します）。エージェントごとのオーバーライド: `agents.list[].subagents.requireAgentId`。
|
||||
`agentId` を省略した `sessions_spawn` 呼び出しをブロックします（明示的なプロファイル選択を強制します）。エージェント単位のオーバーライド: `agents.list[].subagents.requireAgentId`.
|
||||
</ParamField>
|
||||
|
||||
リクエスト元セッションがサンドボックス化されている場合、`sessions_spawn` はサンドボックス外で実行されるターゲットを拒否します。
|
||||
リクエスターセッションがサンドボックス化されている場合、`sessions_spawn` は
|
||||
サンドボックスなしで実行されるターゲットを拒否します。
|
||||
|
||||
### 検出
|
||||
|
||||
`sessions_spawn` で現在許可されているエージェント ID を確認するには、`agents_list` を使用します。レスポンスには、一覧に含まれる各エージェントの有効なモデルと埋め込みランタイムメタデータが含まれるため、呼び出し元は PI、Codex app-server、その他の設定済みネイティブランタイムを区別できます。
|
||||
`sessions_spawn` に現在許可されているエージェント ID を確認するには、`agents_list` を使用します。レスポンスには、一覧に含まれる各エージェントの有効な
|
||||
モデルと埋め込みランタイムメタデータが含まれるため、呼び出し元は PI、Codex
|
||||
アプリサーバー、その他の設定済みネイティブランタイムを区別できます。
|
||||
|
||||
### 自動アーカイブ
|
||||
|
||||
- サブエージェントセッションは、`agents.defaults.subagents.archiveAfterMinutes`（既定値 `60`）後に自動的にアーカイブされます。
|
||||
- アーカイブでは `sessions.delete` を使用し、トランスクリプトの名前を `*.deleted.<timestamp>`（同じフォルダー）に変更します。
|
||||
- サブエージェントセッションは、`agents.defaults.subagents.archiveAfterMinutes`（既定値 `60`）の後に自動的にアーカイブされます。
|
||||
- アーカイブは `sessions.delete` を使用し、トランスクリプトを `*.deleted.<timestamp>` にリネームします（同じフォルダー）。
|
||||
- `cleanup: "delete"` は announce の直後にアーカイブします（リネームによってトランスクリプトは保持されます）。
|
||||
- 自動アーカイブはベストエフォートです。Gateway が再起動すると、保留中のタイマーは失われます。
|
||||
- 自動アーカイブはベストエフォートです。Gateway が再起動すると保留中のタイマーは失われます。
|
||||
- `runTimeoutSeconds` は自動アーカイブしません。実行を停止するだけです。セッションは自動アーカイブまで残ります。
|
||||
- 自動アーカイブは深さ 1 と深さ 2 のセッションに同じように適用されます。
|
||||
- ブラウザーのクリーンアップはアーカイブのクリーンアップとは別です。追跡されたブラウザータブ/プロセスは、トランスクリプト/セッションレコードを保持する場合でも、実行終了時にベストエフォートで閉じられます。
|
||||
- 自動アーカイブは depth-1 と depth-2 のセッションに同様に適用されます。
|
||||
- ブラウザーのクリーンアップはアーカイブのクリーンアップとは別です。追跡されているブラウザータブ/プロセスは、トランスクリプト/セッションレコードが保持される場合でも、実行終了時にベストエフォートで閉じられます。
|
||||
|
||||
## ネストされたサブエージェント
|
||||
|
||||
既定では、サブエージェントは自身のサブエージェントをスポーンできません
|
||||
（`maxSpawnDepth: 1`）。1 レベルのネストを有効にするには `maxSpawnDepth: 2` を設定します。これは**オーケストレーターパターン**です: メイン → オーケストレーターサブエージェント →
|
||||
既定では、サブエージェントは自分自身のサブエージェントをスポーンできません
|
||||
（`maxSpawnDepth: 1`）。1 レベルのネストを有効にするには `maxSpawnDepth: 2` を設定します — **オーケストレーターパターン**: メイン → オーケストレーターサブエージェント →
|
||||
ワーカーサブサブエージェント。
|
||||
|
||||
```json5
|
||||
@ -302,131 +274,136 @@ x-i18n:
|
||||
|
||||
### 深さレベル
|
||||
|
||||
| 深さ | セッションキーの形状 | ロール | スポーン可能か |
|
||||
| 深さ | セッションキーの形式 | 役割 | スポーン可能か |
|
||||
| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
|
||||
| 0 | `agent:<id>:main` | メインエージェント | 常に可能 |
|
||||
| 0 | `agent:<id>:main` | メインエージェント | 常に可能 |
|
||||
| 1 | `agent:<id>:subagent:<uuid>` | サブエージェント（深さ 2 が許可されている場合はオーケストレーター） | `maxSpawnDepth >= 2` の場合のみ |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | サブサブエージェント（リーフワーカー） | 不可 |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | サブサブエージェント（リーフワーカー） | 不可 |
|
||||
|
||||
### Announce チェーン
|
||||
### announce チェーン
|
||||
|
||||
結果はチェーンをさかのぼって流れます。
|
||||
結果はチェーンを上方向に戻ります。
|
||||
|
||||
1. 深さ 2 のワーカーが完了 → 親（深さ 1 のオーケストレーター）に announce します。
|
||||
2. 深さ 1 のオーケストレーターが announce を受け取り、結果を合成し、完了 → メインに announce します。
|
||||
3. メインエージェントが announce を受け取り、ユーザーに届けます。
|
||||
1. depth-2 ワーカーが完了 → 親（depth-1 オーケストレーター）に announce します。
|
||||
2. depth-1 オーケストレーターが announce を受け取り、結果を統合して完了 → メインに announce します。
|
||||
3. メインエージェントが announce を受け取り、ユーザーに配信します。
|
||||
|
||||
各レベルは、直接の子からの announce のみを参照します。
|
||||
各レベルは、直接の子からの announce のみを確認します。
|
||||
|
||||
<Note>
|
||||
**運用ガイダンス:** `sessions_list`、
|
||||
`sessions_history`、`/subagents list`、または `exec` の sleep コマンドを中心にポーリングループを構築するのではなく、子の作業を一度開始して完了イベントを待ちます。
|
||||
`sessions_list` と `/subagents list` は子セッション関係をライブ作業に集中させます。ライブの子は関連付けられたままになり、終了済みの子は短い recent ウィンドウの間だけ表示され、古いストアのみの子リンクは鮮度ウィンドウ後に無視されます。これにより、再起動後に古い `spawnedBy` /
|
||||
`parentSessionKey` メタデータがゴーストの子を復活させることを防ぎます。最終回答を送信した後に子の完了イベントが届いた場合、正しいフォローアップは正確なサイレントトークン
|
||||
**運用ガイダンス:** 子の作業は一度だけ開始し、`sessions_list`、
|
||||
`sessions_history`、`/subagents list`、または `exec` の sleep コマンドの周りにポーリングループを構築するのではなく、完了イベントを待ちます。
|
||||
`sessions_list` と `/subagents list` は、子セッションの関係を
|
||||
ライブ作業に集中させます。ライブの子は接続されたまま、終了した子は短い最近のウィンドウ内で表示されたままになり、古いストア専用の子リンクは鮮度ウィンドウ後に無視されます。これにより、再起動後に古い `spawnedBy` /
|
||||
`parentSessionKey` メタデータがゴーストの子を復活させることを防ぎます。最終回答を送信した後に子の完了イベントが到着した場合、正しいフォローアップは正確なサイレントトークン
|
||||
`NO_REPLY` / `no_reply` です。
|
||||
</Note>
|
||||
|
||||
### 深さ別ツールポリシー
|
||||
### 深さごとのツールポリシー
|
||||
|
||||
- ロールと制御スコープはスポーン時にセッションメタデータへ書き込まれます。これにより、フラットなセッションキーや復元されたセッションキーが誤ってオーケストレーター権限を取り戻すことを防ぎます。
|
||||
- 役割と制御スコープはスポーン時にセッションメタデータへ書き込まれます。これにより、フラットまたは復元されたセッションキーが誤ってオーケストレーター権限を取り戻すことを防ぎます。
|
||||
- **深さ 1（`maxSpawnDepth >= 2` の場合のオーケストレーター）:** 子を管理できるように、`sessions_spawn`、`subagents`、`sessions_list`、`sessions_history` を取得します。その他のセッション/システムツールは拒否されたままです。
|
||||
- **深さ 1（`maxSpawnDepth == 1` の場合のリーフ）:** セッションツールなし（現在の既定の動作）。
|
||||
- **深さ 2（リーフワーカー）:** セッションツールなし。`sessions_spawn` は深さ 2 では常に拒否されます。それ以上の子はスポーンできません。
|
||||
- **深さ 1（`maxSpawnDepth == 1` の場合のリーフ）:** セッションツールはありません（現在の既定動作）。
|
||||
- **深さ 2（リーフワーカー）:** セッションツールはありません — `sessions_spawn` は深さ 2 では常に拒否されます。それ以上の子をスポーンすることはできません。
|
||||
|
||||
### エージェントごとのスポーン上限
|
||||
### エージェント単位のスポーン上限
|
||||
|
||||
各エージェントセッション（どの深さでも）は、同時に最大 `maxChildrenPerAgent`
|
||||
（既定値 `5`）個のアクティブな子を持てます。これにより、単一のオーケストレーターからの制御不能なファンアウトを防ぎます。
|
||||
各エージェントセッション（任意の深さ）は、同時に最大 `maxChildrenPerAgent`
|
||||
（既定値 `5`）個のアクティブな子を持つことができます。これにより、単一のオーケストレーターからの制御不能なファンアウトを防ぎます。
|
||||
|
||||
### カスケード停止
|
||||
|
||||
深さ 1 のオーケストレーターを停止すると、そのすべての深さ 2 の子も自動的に停止します。
|
||||
depth-1 オーケストレーターを停止すると、そのすべての depth-2
|
||||
の子が自動的に停止します。
|
||||
|
||||
- メインチャットの `/stop` はすべての深さ 1 エージェントを停止し、その深さ 2 の子にカスケードします。
|
||||
- `/subagents kill <id>` は特定のサブエージェントを停止し、その子にカスケードします。
|
||||
- `/subagents kill all` はリクエスト元のすべてのサブエージェントを停止し、カスケードします。
|
||||
- メインチャットで `/stop` を実行すると、すべての depth-1 エージェントが停止し、その depth-2 の子へカスケードします。
|
||||
- `/subagents kill <id>` は特定のサブエージェントを停止し、その子へカスケードします。
|
||||
- `/subagents kill all` はリクエスターのすべてのサブエージェントを停止し、カスケードします。
|
||||
|
||||
## 認証
|
||||
|
||||
サブエージェントの認証は、セッションタイプではなく**エージェント ID**で解決されます。
|
||||
サブエージェントの認証はセッションタイプではなく **エージェント ID** によって解決されます。
|
||||
|
||||
- サブエージェントセッションキーは `agent:<agentId>:subagent:<uuid>` です。
|
||||
- 認証ストアはそのエージェントの `agentDir` から読み込まれます。
|
||||
- メインエージェントの認証プロファイルは**フォールバック**としてマージされます。競合時はエージェントプロファイルがメインプロファイルをオーバーライドします。
|
||||
- メインエージェントの認証プロファイルは **フォールバック** としてマージされます。競合時にはエージェントプロファイルがメインプロファイルを上書きします。
|
||||
|
||||
マージは加算的なので、メインプロファイルは常にフォールバックとして利用できます。エージェントごとに完全に分離された認証は、まだサポートされていません。
|
||||
マージは加算的であるため、メインプロファイルは常にフォールバックとして利用できます。エージェント単位で完全に分離された認証はまだサポートされていません。
|
||||
|
||||
## Announce
|
||||
|
||||
サブエージェントは announce ステップを通じて報告します。
|
||||
サブエージェントは announce ステップを介して報告します。
|
||||
|
||||
- announce ステップは、リクエスト元セッションではなくサブエージェントセッション内で実行されます。
|
||||
- announce ステップは（リクエスターセッションではなく）サブエージェントセッション内で実行されます。
|
||||
- サブエージェントが正確に `ANNOUNCE_SKIP` と返信した場合、何も投稿されません。
|
||||
- 最新のアシスタントテキストが正確なサイレントトークン `NO_REPLY` / `no_reply` の場合、それ以前に表示される進捗が存在していても announce 出力は抑制されます。
|
||||
- 最新のアシスタントテキストが正確なサイレントトークン `NO_REPLY` / `no_reply` の場合、それ以前に表示される進捗があっても announce 出力は抑制されます。
|
||||
|
||||
配信はリクエスト元の深さによって異なります。
|
||||
配信はリクエスターの深さによって異なります。
|
||||
|
||||
- トップレベルのリクエスト元セッションは、外部配信（`deliver=true`）付きのフォローアップ `agent` 呼び出しを使用します。
|
||||
- ネストされたリクエスト元サブエージェントセッションは内部フォローアップ注入（`deliver=false`）を受け取るため、オーケストレーターは子の結果をセッション内で合成できます。
|
||||
- ネストされたリクエスト元サブエージェントセッションが存在しない場合、OpenClaw は利用可能であればそのセッションのリクエスト元にフォールバックします。
|
||||
- トップレベルのリクエスターセッションは、外部配信（`deliver=true`）付きのフォローアップ `agent` 呼び出しを使用します。
|
||||
- ネストされたリクエスターサブエージェントセッションは、内部フォローアップ注入（`deliver=false`）を受け取り、オーケストレーターが子の結果をセッション内で統合できるようにします。
|
||||
- ネストされたリクエスターサブエージェントセッションが存在しない場合、OpenClaw は利用可能であればそのセッションのリクエスターにフォールバックします。
|
||||
|
||||
トップレベルのリクエスト元セッションでは、完了モードの直接配信はまず、バインドされた会話/スレッドルートとフックオーバーライドを解決し、その後、リクエスト元セッションに保存されたルートから不足しているチャンネルターゲットフィールドを埋めます。これにより、完了の発信元がチャンネルのみを識別している場合でも、完了は正しいチャット/トピックに留まります。
|
||||
トップレベルのリクエスターセッションでは、完了モードの直接配信はまず
|
||||
バインド済みの会話/スレッドルートとフックのオーバーライドを解決し、その後
|
||||
リクエスターセッションに保存されたルートから不足しているチャネルターゲットフィールドを埋めます。
|
||||
これにより、完了元がチャネルのみを識別する場合でも、完了が正しいチャット/トピックに保持されます。
|
||||
|
||||
ネストされた完了結果を構築するとき、子の完了集約は現在のリクエスト元実行にスコープされ、古い以前の実行の子出力が現在の announce に漏れ込むことを防ぎます。announce 返信は、チャンネルアダプターで利用可能な場合、スレッド/トピックルーティングを保持します。
|
||||
ネストされた完了の所見を構築するとき、子の完了集約は現在のリクエスター実行にスコープされるため、以前の実行の古い子出力が現在の announce に漏れ込むことを防ぎます。announce の返信は、チャネルアダプターで利用可能な場合、スレッド/トピックのルーティングを保持します。
|
||||
|
||||
### Announce コンテキスト
|
||||
|
||||
Announce コンテキストは安定した内部イベントブロックに正規化されます。
|
||||
Announce コンテキストは、安定した内部イベントブロックに正規化されます。
|
||||
|
||||
| フィールド | ソース |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| ソース | `subagent` または `cron` |
|
||||
| セッション ID | 子セッションキー/id |
|
||||
| タイプ | Announce タイプ + タスクラベル |
|
||||
| ステータス | ランタイム結果（`success`、`error`、`timeout`、または `unknown`）から派生。モデルテキストからは推測**されません** |
|
||||
| 結果コンテンツ | 最新の表示可能なアシスタントテキスト。それがなければサニタイズ済みの最新 tool/toolResult テキスト |
|
||||
| フォローアップ | 返信する場合と沈黙を保つ場合を説明する指示 |
|
||||
| セッション ID | 子セッションキー/ID |
|
||||
| タイプ | announce タイプ + タスクラベル |
|
||||
| ステータス | ランタイム結果（`success`、`error`、`timeout`、または `unknown`）から派生 — モデルテキストからは推定**しません** |
|
||||
| 結果コンテンツ | 最新の表示可能なアシスタントテキスト。なければ、サニタイズされた最新のツール/toolResult テキスト |
|
||||
| フォローアップ | いつ返信し、いつサイレントのままでいるかを説明する指示 |
|
||||
|
||||
終端で失敗した実行は、キャプチャされた返信テキストを再生せずに失敗ステータスを報告します。タイムアウト時に子がツール呼び出しまでしか進まなかった場合、announce は生のツール出力を再生する代わりに、その履歴を短い部分進捗サマリーへ圧縮できます。
|
||||
端末の失敗した実行は、キャプチャされた返信テキストを再生せずに
|
||||
失敗ステータスを報告します。タイムアウト時に子がツール呼び出しまでしか進んでいない場合、announce は生のツール出力を再生する代わりに、その履歴を短い部分進捗サマリーに折りたたむことができます。
|
||||
|
||||
### 統計行
|
||||
|
||||
Announce ペイロードには末尾に統計行が含まれます（折り返されている場合でも）。
|
||||
Announce ペイロードには、末尾に統計行が含まれます（折り返されている場合でも）。
|
||||
|
||||
- ランタイム（例: `runtime 5m12s`）。
|
||||
- トークン使用量（入力/出力/合計）。
|
||||
- モデル価格が設定されている場合の推定コスト（`models.providers.*.models[].cost`）。
|
||||
- `sessionKey`、`sessionId`、およびトランスクリプトパス。メインエージェントが `sessions_history` で履歴を取得したり、ディスク上のファイルを検査したりできます。
|
||||
- メインエージェントが `sessions_history` で履歴を取得したり、ディスク上のファイルを調べたりできるようにするための、`sessionKey`、`sessionId`、トランスクリプトパス。
|
||||
|
||||
内部メタデータはオーケストレーション専用です。ユーザー向けの返信は通常のアシスタントの声に書き直す必要があります。
|
||||
内部メタデータはオーケストレーション専用です。ユーザー向けの返信は通常のアシスタントの声に書き直すべきです。
|
||||
|
||||
### `sessions_history` を推奨する理由
|
||||
|
||||
`sessions_history` はより安全なオーケストレーション経路です。
|
||||
|
||||
- アシスタントの recall は最初に正規化されます。thinking タグを除去し、`<relevant-memories>` / `<relevant_memories>` の足場を除去し、プレーンテキストのツール呼び出し XML ペイロードブロック（`<tool_call>`、`<function_call>`、`<tool_calls>`、`<function_calls>`）を、正しく閉じていない切り詰められたペイロードも含めて除去し、ダウングレードされたツール呼び出し/結果の足場と履歴コンテキストマーカーを除去し、漏洩したモデル制御トークン（`<|assistant|>`、その他の ASCII `<|...|>`、全角 `<｜...｜>`）を除去し、不正な MiniMax ツール呼び出し XML を除去します。
|
||||
- アシスタントのリコールは最初に正規化されます。thinking タグが削除され、`<relevant-memories>` / `<relevant_memories>` の足場が削除され、プレーンテキストのツール呼び出し XML ペイロードブロック（`<tool_call>`、`<function_call>`、`<tool_calls>`、`<function_calls>`）が、正常に閉じていない切り詰められたペイロードを含めて削除され、ダウングレードされたツール呼び出し/結果の足場と履歴コンテキストマーカーが削除され、漏えいしたモデル制御トークン（`<|assistant|>`、その他の ASCII `<|...|>`、全角 `<｜...｜>`）が削除され、不正な MiniMax ツール呼び出し XML が削除されます。
|
||||
- 認証情報/トークンのようなテキストはリダクトされます。
|
||||
- 長いブロックは切り詰められる場合があります。
|
||||
- 非常に大きな履歴では、古い行が削除されたり、サイズが過大な行が `[sessions_history omitted: message too large]` に置き換えられたりする場合があります。
|
||||
- 完全なバイト単位のトランスクリプトが必要な場合、ディスク上の生トランスクリプト検査がフォールバックです。
|
||||
- 長いブロックは切り詰められることがあります。
|
||||
- 非常に大きな履歴では、古い行を削除したり、過大な行を `[sessions_history omitted: message too large]` に置き換えたりできます。
|
||||
- バイト単位で完全なトランスクリプトが必要な場合は、ディスク上の生トランスクリプト検査がフォールバックです。
|
||||
|
||||
## ツールポリシー
|
||||
|
||||
サブエージェントはまず、親またはターゲットエージェントと同じプロファイルとツールポリシーパイプラインを使用します。その後、OpenClaw がサブエージェント制限レイヤーを適用します。
|
||||
サブエージェントは、まず親または対象エージェントと同じプロファイルおよびツールポリシーパイプラインを使用します。その後、OpenClaw がサブエージェント制限レイヤーを適用します。
|
||||
|
||||
制限的な `tools.profile` がない場合、サブエージェントは**セッションツール**とシステムツールを除くすべてのツールを取得します。
|
||||
制限的な `tools.profile` がない場合、サブエージェントは**セッションツールを除くすべてのツール**とシステムツールを取得します。
|
||||
|
||||
- `sessions_list`
|
||||
- `sessions_history`
|
||||
- `sessions_send`
|
||||
- `sessions_spawn`
|
||||
|
||||
ここでも `sessions_history` は、境界のあるサニタイズ済み recall ビューのままです。生のトランスクリプトダンプではありません。
|
||||
`sessions_history` はここでも境界付きでサニタイズされた想起ビューのままです。生のトランスクリプトダンプではありません。
|
||||
|
||||
`maxSpawnDepth >= 2` の場合、深さ 1 のオーケストレーターサブエージェントは、子を管理できるように `sessions_spawn`、`subagents`、`sessions_list`、および
|
||||
`sessions_history` も受け取ります。
|
||||
`maxSpawnDepth >= 2` の場合、深さ 1 のオーケストレーターサブエージェントは、子を管理できるように `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history` も追加で受け取ります。
|
||||
|
||||
### 設定によるオーバーライド
|
||||
### 設定による上書き
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -450,7 +427,7 @@ Announce ペイロードには末尾に統計行が含まれます（折り返
|
||||
}
|
||||
```
|
||||
|
||||
`tools.subagents.tools.allow` は最終的な許可専用フィルターです。すでに解決済みのツールセットを絞り込むことはできますが、`tools.profile` によって削除されたツールを**追加し直す**ことはできません。たとえば、`tools.profile: "coding"` には `web_search`/`web_fetch` が含まれますが、`browser` ツールは含まれません。coding プロファイルのサブエージェントでブラウザ自動化を使えるようにするには、プロファイル段階で browser を追加します。
|
||||
`tools.subagents.tools.allow` は最終的な許可専用フィルターです。すでに解決済みのツールセットを狭めることはできますが、`tools.profile` によって削除されたツールを**追加し直す**ことはできません。たとえば、`tools.profile: "coding"` には `web_search`/`web_fetch` が含まれますが、`browser` ツールは含まれません。coding プロファイルのサブエージェントにブラウザー自動化を使わせるには、プロファイル段階で browser を追加します。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -461,40 +438,40 @@ Announce ペイロードには末尾に統計行が含まれます（折り返
|
||||
}
|
||||
```
|
||||
|
||||
1 つのエージェントだけにブラウザ自動化を許可する場合は、エージェントごとの `agents.list[].tools.alsoAllow: ["browser"]` を使用します。
|
||||
1 つのエージェントだけにブラウザー自動化を与える場合は、エージェント単位の `agents.list[].tools.alsoAllow: ["browser"]` を使用します。
|
||||
|
||||
## 並行実行
|
||||
## 並行処理
|
||||
|
||||
サブエージェントは専用のインプロセスキューレーンを使用します。
|
||||
|
||||
- **レーン名:** `subagent`
|
||||
- **並行数:** `agents.defaults.subagents.maxConcurrent` (デフォルト `8`)
|
||||
- **並行数:** `agents.defaults.subagents.maxConcurrent`（既定値 `8`）
|
||||
|
||||
## 生存確認と復旧
|
||||
## ライブネスと復旧
|
||||
|
||||
OpenClaw は `endedAt` が存在しないことを、サブエージェントがまだ生きている恒久的な証拠として扱いません。stale-run ウィンドウより古い未終了の実行は、`/subagents list`、ステータス要約、子孫完了ゲート、およびセッションごとの並行実行チェックで active/pending としてカウントされなくなります。
|
||||
OpenClaw は、`endedAt` が存在しないことを、サブエージェントがまだ生存している恒久的な証拠として扱いません。stale-run ウィンドウより古い未終了の実行は、`/subagents list`、ステータス要約、子孫の完了ゲート、セッション単位の並行処理チェックで active/pending として数えられなくなります。
|
||||
|
||||
Gateway 再起動後、古くなった未終了の復元済み実行は、その子セッションが `abortedLastRun: true` としてマークされていない限り剪定されます。これらの再起動により中断された子セッションは、サブエージェントの孤立復旧フローを通じて復旧可能なままです。このフローは、中断マーカーをクリアする前に合成 resume メッセージを送信します。
|
||||
Gateway の再起動後、古い未終了の復元済み実行は、その子セッションが `abortedLastRun: true` とマークされていない限り、削除されます。これらの再起動で中断された子セッションは、サブエージェントの孤立復旧フローを通じて復旧可能なままです。このフローは、中断マーカーをクリアする前に合成 resume メッセージを送信します。
|
||||
|
||||
自動再起動復旧は子セッションごとに制限されます。同じサブエージェントの子が rapid re-wedge ウィンドウ内で繰り返し孤立復旧に受け入れられた場合、OpenClaw はそのセッションに復旧 tombstone を永続化し、以降の再起動で自動再開を停止します。タスクレコードを整合させるには `openclaw tasks maintenance --apply` を実行し、tombstone 化されたセッション上の古い中断済み復旧フラグをクリアするには `openclaw doctor --fix` を実行します。
|
||||
自動再起動復旧は子セッションごとに制限されます。同じサブエージェントの子が rapid re-wedge ウィンドウ内で繰り返し孤立復旧として受け入れられた場合、OpenClaw はそのセッションに復旧 tombstone を永続化し、以後の再起動では自動 resume を停止します。タスクレコードを調整するには `openclaw tasks maintenance --apply` を実行し、tombstone 付きセッションの古い中断復旧フラグをクリアするには `openclaw doctor --fix` を実行します。
|
||||
|
||||
<Note>
|
||||
サブエージェントの spawn が Gateway `PAIRING_REQUIRED` / `scope-upgrade` で失敗する場合は、ペアリング状態を編集する前に RPC 呼び出し元を確認してください。内部の `sessions_spawn` 調整は、直接 loopback の共有トークン/パスワード認証を介して、`client.id: "gateway-client"` と `client.mode: "backend"` で接続する必要があります。この経路は、CLI のペアリング済みデバイスのスコープベースラインには依存しません。リモート呼び出し元、明示的な `deviceIdentity`、明示的なデバイストークン経路、およびブラウザ/node クライアントでは、スコープアップグレードに通常のデバイス承認が引き続き必要です。
|
||||
サブエージェントの spawn が Gateway `PAIRING_REQUIRED` / `scope-upgrade` で失敗する場合は、ペアリング状態を編集する前に RPC 呼び出し元を確認してください。内部の `sessions_spawn` 調整は、直接 local loopback の共有トークン/パスワード認証を介して `client.id: "gateway-client"`、`client.mode: "backend"` として接続する必要があります。このパスは CLI のペアリング済みデバイススコープベースラインに依存しません。リモート呼び出し元、明示的な `deviceIdentity`、明示的なデバイストークンパス、browser/node クライアントでは、スコープアップグレードに通常のデバイス承認が引き続き必要です。
|
||||
</Note>
|
||||
|
||||
## 停止
|
||||
|
||||
- リクエスターのチャットで `/stop` を送信すると、リクエスターセッションが中断され、そこから spawn されたアクティブなサブエージェント実行がすべて停止され、ネストされた子にもカスケードされます。
|
||||
- リクエスターのチャットで `/stop` を送信すると、リクエスターセッションが中断され、そこから spawn されたアクティブなサブエージェント実行がすべて停止し、ネストされた子にもカスケードします。
|
||||
- `/subagents kill <id>` は特定のサブエージェントを停止し、その子にもカスケードします。
|
||||
|
||||
## 制限事項
|
||||
|
||||
- サブエージェントの announce は**ベストエフォート**です。Gateway が再起動すると、保留中の「announce back」作業は失われます。
|
||||
- サブエージェントは同じ Gateway プロセスリソースを引き続き共有します。`maxConcurrent` は安全弁として扱ってください。
|
||||
- `sessions_spawn` は常に非ブロッキングです。即座に `{ status: "accepted", runId, childSessionKey }` を返します。
|
||||
- サブエージェントコンテキストは `AGENTS.md` + `TOOLS.md` のみを注入します (`SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md` は注入しません)。
|
||||
- 最大ネスト深度は 5 です (`maxSpawnDepth` の範囲: 1–5)。ほとんどのユースケースでは深度 2 を推奨します。
|
||||
- `maxChildrenPerAgent` はセッションごとのアクティブな子の数を制限します (デフォルト `5`、範囲 `1–20`)。
|
||||
- サブエージェントの通知は**ベストエフォート**です。Gateway が再起動すると、保留中の「announce back」作業は失われます。
|
||||
- サブエージェントは引き続き同じ Gateway プロセスリソースを共有します。`maxConcurrent` は安全弁として扱ってください。
|
||||
- `sessions_spawn` は常にノンブロッキングです。即座に `{ status: "accepted", runId, childSessionKey }` を返します。
|
||||
- サブエージェントコンテキストは `AGENTS.md` + `TOOLS.md` のみを注入します（`SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md` は含みません）。
|
||||
- 最大ネスト深さは 5 です（`maxSpawnDepth` の範囲: 1–5）。ほとんどのユースケースでは深さ 2 が推奨されます。
|
||||
- `maxChildrenPerAgent` はセッションごとのアクティブな子の上限を設定します（既定値 `5`、範囲 `1–20`）。
|
||||
|
||||
## 関連
|
||||
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- ブラウザから Gateway を操作したい場合
|
||||
- SSH トンネルなしで Tailnet アクセスを使いたい場合
|
||||
- SSH トンネルなしで Tailnet アクセスを利用したい
|
||||
sidebarTitle: Control UI
|
||||
summary: ブラウザベースの Gateway 用コントロール UI（チャット、ノード、設定）
|
||||
title: コントロール UI
|
||||
summary: Gateway のブラウザベースの制御 UI（チャット、ノード、設定）
|
||||
title: 制御 UI
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T05:03:12Z"
|
||||
generated_at: "2026-05-04T07:04:41Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 99a40ab77276fbc3180aefb103c2dd46804829c7b1b6966a8456ed35b85ed644
|
||||
source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
コントロール UI は、Gateway によって配信される小さな **Vite + Lit** シングルページアプリです。
|
||||
Control UI は、Gateway によって配信される小さな **Vite + Lit** のシングルページアプリです。
|
||||
|
||||
- デフォルト: `http://<host>:18789/`
|
||||
- 任意のプレフィックス: `gateway.controlUi.basePath` を設定します (例: `/openclaw`)
|
||||
@ -29,18 +29,18 @@ Gateway が同じコンピューターで実行されている場合は、次を
|
||||
|
||||
ページの読み込みに失敗する場合は、先に Gateway を起動します: `openclaw gateway`。
|
||||
|
||||
認証は、WebSocket ハンドシェイク中に次の方法で提供されます。
|
||||
認証は、WebSocket ハンドシェイク中に次を介して提供されます。
|
||||
|
||||
- `connect.params.auth.token`
|
||||
- `connect.params.auth.password`
|
||||
- `gateway.auth.allowTailscale: true` の場合の Tailscale Serve アイデンティティヘッダー
|
||||
- `gateway.auth.mode: "trusted-proxy"` の場合の信頼済みプロキシアイデンティティヘッダー
|
||||
|
||||
ダッシュボードの設定パネルは、現在のブラウザータブセッションと選択中の Gateway URL 用のトークンを保持します。パスワードは永続化されません。オンボーディングでは通常、初回接続時に共有シークレット認証用の Gateway トークンが生成されますが、`gateway.auth.mode` が `"password"` の場合はパスワード認証も機能します。
|
||||
ダッシュボード設定パネルは、現在のブラウザータブセッションと選択された gateway URL のトークンを保持します。パスワードは永続化されません。オンボーディングは通常、初回接続時に共有シークレット認証用の gateway トークンを生成しますが、`gateway.auth.mode` が `"password"` の場合はパスワード認証も機能します。
|
||||
|
||||
## デバイスペアリング (初回接続)
|
||||
## デバイスのペアリング (初回接続)
|
||||
|
||||
新しいブラウザーまたはデバイスからコントロール UI に接続すると、Gateway は通常、**一回限りのペアリング承認**を要求します。これは不正アクセスを防ぐためのセキュリティ対策です。
|
||||
新しいブラウザーまたはデバイスから Control UI に接続すると、Gateway は通常、**1回限りのペアリング承認**を要求します。これは不正アクセスを防ぐためのセキュリティ対策です。
|
||||
|
||||
**表示される内容:** 「disconnected (1008): pairing required」
|
||||
|
||||
@ -59,13 +59,13 @@ Gateway が同じコンピューターで実行されている場合は、次を
|
||||
|
||||
ブラウザーが変更された認証詳細 (ロール/スコープ/公開鍵) でペアリングを再試行すると、以前の保留中リクエストは置き換えられ、新しい `requestId` が作成されます。承認前に `openclaw devices list` を再実行してください。
|
||||
|
||||
ブラウザーがすでにペアリング済みで、読み取りアクセスから書き込み/管理者アクセスへ変更する場合、これはサイレント再接続ではなく承認のアップグレードとして扱われます。OpenClaw は古い承認を有効なまま保持し、より広い再接続をブロックし、新しいスコープセットを明示的に承認するよう求めます。
|
||||
ブラウザーがすでにペアリング済みで、読み取りアクセスから書き込み/管理者アクセスへ変更する場合、これはサイレントな再接続ではなく承認アップグレードとして扱われます。OpenClaw は古い承認を有効なまま保持し、より広い権限での再接続をブロックし、新しいスコープセットを明示的に承認するよう求めます。
|
||||
|
||||
承認されるとデバイスは記憶され、`openclaw devices revoke --device <id> --role <role>` で取り消さない限り再承認は不要です。トークンローテーションと取り消しについては、[デバイス CLI](/ja-JP/cli/devices) を参照してください。
|
||||
承認されるとデバイスは記憶され、`openclaw devices revoke --device <id> --role <role>` で取り消さない限り再承認は不要です。トークンローテーションと取り消しについては [デバイス CLI](/ja-JP/cli/devices) を参照してください。
|
||||
|
||||
<Note>
|
||||
- 直接の local loopback ブラウザー接続 (`127.0.0.1` / `localhost`) は自動承認されます。
|
||||
- `gateway.auth.allowTailscale: true` で、Tailscale アイデンティティが検証され、ブラウザーがデバイスアイデンティティを提示する場合、Tailscale Serve はコントロール UI オペレーターセッションのペアリング往復を省略できます。
|
||||
- `gateway.auth.allowTailscale: true` で、Tailscale アイデンティティが検証され、ブラウザーが自身のデバイスアイデンティティを提示する場合、Tailscale Serve は Control UI オペレーターセッションのペアリング往復を省略できます。
|
||||
- 直接の Tailnet バインド、LAN ブラウザー接続、デバイスアイデンティティのないブラウザープロファイルでは、引き続き明示的な承認が必要です。
|
||||
- 各ブラウザープロファイルは一意のデバイス ID を生成するため、ブラウザーを切り替えたりブラウザーデータを消去したりすると、再ペアリングが必要になります。
|
||||
|
||||
@ -73,80 +73,80 @@ Gateway が同じコンピューターで実行されている場合は、次を
|
||||
|
||||
## 個人アイデンティティ (ブラウザーローカル)
|
||||
|
||||
コントロール UI は、共有セッションでの帰属表示のために送信メッセージへ付与される、ブラウザーごとの個人アイデンティティ (表示名とアバター) をサポートします。これはブラウザーストレージに存在し、現在のブラウザープロファイルにスコープされ、他のデバイスには同期されません。また、実際に送信したメッセージ上の通常のトランスクリプト作成者メタデータを除き、サーバー側に永続化されません。サイトデータを消去したりブラウザーを切り替えたりすると、空にリセットされます。
|
||||
Control UI は、共有セッションでの帰属表示のため、送信メッセージに付加されるブラウザーごとの個人アイデンティティ (表示名とアバター) をサポートします。これはブラウザーストレージに保存され、現在のブラウザープロファイルにスコープされ、実際に送信したメッセージ上の通常のトランスクリプト著者メタデータを除き、他のデバイスへ同期されたりサーバー側に永続化されたりしません。サイトデータを消去するかブラウザーを切り替えると空にリセットされます。
|
||||
|
||||
同じブラウザーローカルのパターンは、アシスタントアバターの上書きにも適用されます。アップロードされたアシスタントアバターは、ローカルブラウザー上でのみ Gateway が解決したアイデンティティに重ねられ、`config.patch` を通じて往復することはありません。共有 `ui.assistant.avatar` 設定フィールドは、このフィールドへ直接書き込む非 UI クライアント (スクリプト化された Gateway やカスタムダッシュボードなど) 向けに引き続き利用できます。
|
||||
同じブラウザーローカルのパターンは、アシスタントアバターの上書きにも適用されます。アップロードされたアシスタントアバターは、ローカルブラウザー上でのみ gateway が解決したアイデンティティに重ねられ、`config.patch` を介して往復することはありません。共有の `ui.assistant.avatar` 設定フィールドは、スクリプト化された gateway やカスタムダッシュボードなど、このフィールドを直接書き込む非 UI クライアント向けに引き続き利用できます。
|
||||
|
||||
## ランタイム設定エンドポイント
|
||||
|
||||
コントロール UI は、実行時設定を `/__openclaw/control-ui-config.json` から取得します。このエンドポイントは、HTTP サーフェスの残りと同じ Gateway 認証で制御されます。未認証のブラウザーは取得できず、取得に成功するには、すでに有効な Gateway トークン/パスワード、Tailscale Serve アイデンティティ、または信頼済みプロキシアイデンティティのいずれかが必要です。
|
||||
Control UI は、ランタイム設定を `/__openclaw/control-ui-config.json` から取得します。そのエンドポイントは、HTTP サーフェスの残り部分と同じ gateway 認証で保護されています。未認証のブラウザーは取得できず、取得に成功するには、すでに有効な gateway トークン/パスワード、Tailscale Serve アイデンティティ、または信頼済みプロキシアイデンティティのいずれかが必要です。
|
||||
|
||||
## 言語サポート
|
||||
|
||||
コントロール UI は、初回読み込み時にブラウザーのロケールに基づいてローカライズできます。後で上書きするには、**概要 -> Gateway アクセス -> 言語** を開きます。ロケールピッカーは外観ではなく、Gateway アクセスカードにあります。
|
||||
Control UI は、初回読み込み時にブラウザーのロケールに基づいて自身をローカライズできます。後で上書きするには、**概要 -> Gateway アクセス -> 言語**を開きます。ロケールピッカーは外観ではなく、Gateway アクセスカードにあります。
|
||||
|
||||
- サポートされるロケール: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
|
||||
- 英語以外の翻訳はブラウザーで遅延読み込みされます。
|
||||
- 選択したロケールはブラウザーストレージに保存され、以後の訪問で再利用されます。
|
||||
- 不足している翻訳キーは英語にフォールバックします。
|
||||
- サポートされているロケール: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
|
||||
- 英語以外の翻訳はブラウザー内で遅延読み込みされます。
|
||||
- 選択されたロケールはブラウザーストレージに保存され、以後の訪問で再利用されます。
|
||||
- 欠落している翻訳キーは英語にフォールバックします。
|
||||
|
||||
ドキュメント翻訳は同じ英語以外のロケールセット向けに生成されますが、ドキュメントサイトに組み込まれた Mintlify の言語ピッカーは、Mintlify が受け入れるロケールコードに制限されています。タイ語 (`th`) とペルシア語 (`fa`) のドキュメントは公開リポジトリで引き続き生成されますが、Mintlify がこれらのコードをサポートするまで、そのピッカーには表示されない場合があります。
|
||||
Docs 翻訳は同じ英語以外のロケールセット向けに生成されますが、docs サイト組み込みの Mintlify 言語ピッカーは、Mintlify が受け付けるロケールコードに制限されています。タイ語 (`th`) とペルシア語 (`fa`) の docs は公開リポジトリで引き続き生成されますが、Mintlify がこれらのコードをサポートするまで、そのピッカーには表示されない場合があります。
|
||||
|
||||
## 外観テーマ
|
||||
|
||||
外観パネルには、組み込みの Claw、Knot、Dash テーマに加え、ブラウザーローカルの tweakcn インポートスロットが 1 つあります。テーマをインポートするには、[tweakcn editor](https://tweakcn.com/editor/theme) を開き、テーマを選択または作成し、**共有** をクリックして、コピーしたテーマリンクを外観に貼り付けます。インポーターは `https://tweakcn.com/r/themes/<id>` レジストリ URL、`https://tweakcn.com/editor/theme?theme=amethyst-haze` のようなエディター URL、相対 `/themes/<id>` パス、生のテーマ ID、`amethyst-haze` などのデフォルトテーマ名も受け入れます。
|
||||
外観パネルは、組み込みの Claw、Knot、Dash テーマに加え、ブラウザーローカルの tweakcn インポートスロットを1つ保持します。テーマをインポートするには、[tweakcn エディター](https://tweakcn.com/editor/theme) を開き、テーマを選択または作成して **共有** をクリックし、コピーしたテーマリンクを外観に貼り付けます。インポーターは、`https://tweakcn.com/r/themes/<id>` レジストリ URL、`https://tweakcn.com/editor/theme?theme=amethyst-haze` のようなエディター URL、相対 `/themes/<id>` パス、生のテーマ ID、`amethyst-haze` などのデフォルトテーマ名も受け付けます。
|
||||
|
||||
インポートされたテーマは現在のブラウザープロファイルにのみ保存されます。Gateway 設定には書き込まれず、デバイス間で同期されません。インポート済みテーマを置き換えると、1 つのローカルスロットが更新されます。消去すると、インポート済みテーマが選択されていた場合、アクティブテーマは Claw に戻ります。
|
||||
インポートされたテーマは、現在のブラウザープロファイルにのみ保存されます。gateway 設定には書き込まれず、デバイス間で同期されません。インポート済みテーマを置き換えると、その1つのローカルスロットが更新されます。クリアすると、インポート済みテーマが選択されていた場合はアクティブテーマが Claw に戻ります。
|
||||
|
||||
## できること (現在)
|
||||
## できること (現時点)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="チャットと通話">
|
||||
- Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`) 経由でモデルとチャットします。
|
||||
- ブラウザーのリアルタイムセッションで通話します。OpenAI は直接 WebRTC を使用し、Google Live は WebSocket 経由の制約付き一回限りブラウザートークンを使用し、バックエンド専用リアルタイム音声 Plugin は Gateway リレートランスポートを使用します。リレーはプロバイダー資格情報を Gateway 上に保持し、ブラウザーは `talk.realtime.relay*` RPC を通じてマイク PCM をストリーミングし、より大きな設定済み OpenClaw モデル用の `openclaw_agent_consult` ツール呼び出しを `chat.send` 経由で送り返します。
|
||||
- チャットでツール呼び出しとライブツール出力カードをストリーミングします (エージェントイベント)。
|
||||
- ブラウザーのリアルタイムセッションを通じて通話します。OpenAI は直接 WebRTC を使用し、Google Live は WebSocket 上の制限付き1回使用ブラウザートークンを使用し、バックエンド専用リアルタイム音声 plugins は Gateway リレートランスポートを使用します。リレーはプロバイダー認証情報を Gateway に保持し、ブラウザーは `talk.realtime.relay*` RPC を通じてマイク PCM をストリーミングし、より大きな設定済み OpenClaw モデル用に `openclaw_agent_consult` ツール呼び出しを `chat.send` 経由で送り返します。
|
||||
- チャット内でツール呼び出しとライブツール出力カードをストリーミングします (エージェントイベント)。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="チャンネル、インスタンス、セッション、Dream">
|
||||
- チャンネル: 組み込みおよび同梱/外部 Plugin チャンネルのステータス、QR ログイン、チャンネルごとの設定 (`channels.status`, `web.login.*`, `config.patch`)。
|
||||
<Accordion title="チャンネル、インスタンス、セッション、dream">
|
||||
- チャンネル: 組み込みおよびバンドル/外部 plugin チャンネルのステータス、QR ログイン、チャンネルごとの設定 (`channels.status`, `web.login.*`, `config.patch`)。
|
||||
- インスタンス: プレゼンス一覧と更新 (`system-presence`)。
|
||||
- セッション: 一覧とセッションごとのモデル/思考/高速/詳細/トレース/推論の上書き (`sessions.list`, `sessions.patch`)。
|
||||
- Dream: Dreaming ステータス、有効/無効トグル、Dream Diary リーダー (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)。
|
||||
- セッション: 一覧とセッションごとのモデル/思考/高速/詳細/トレース/reasoning 上書き (`sessions.list`, `sessions.patch`)。
|
||||
- Dream: Dreaming ステータス、有効化/無効化トグル、Dream Diary リーダー (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron、Skills、ノード、exec 承認">
|
||||
<Accordion title="Cron、skills、ノード、exec 承認">
|
||||
- Cron ジョブ: 一覧/追加/編集/実行/有効化/無効化と実行履歴 (`cron.*`)。
|
||||
- Skills: ステータス、有効化/無効化、インストール、API キー更新 (`skills.*`)。
|
||||
- ノード: 一覧と機能 (`node.list`)。
|
||||
- exec 承認: Gateway またはノードの許可リストと `exec host=gateway/node` の確認ポリシーを編集します (`exec.approvals.*`)。
|
||||
- Exec 承認: `exec host=gateway/node` の gateway またはノードの許可リストと確認ポリシーを編集 (`exec.approvals.*`)。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="設定">
|
||||
- `~/.openclaw/openclaw.json` を表示/編集します (`config.get`, `config.set`)。
|
||||
- 検証付きで適用して再起動し (`config.apply`)、最後にアクティブだったセッションを起こします。
|
||||
- 書き込みには、同時編集による上書きを防ぐためのベースハッシュガードが含まれます。
|
||||
- 書き込み (`config.set`/`config.apply`/`config.patch`) は、送信された設定ペイロード内の参照について、アクティブな SecretRef 解決を事前確認します。送信された未解決のアクティブ参照は、書き込み前に拒否されます。
|
||||
- スキーマとフォームレンダリング (`config.schema` / `config.schema.lookup`。フィールド `title` / `description`、一致した UI ヒント、直下の子要素サマリー、ネストされたオブジェクト/ワイルドカード/配列/合成ノード上のドキュメントメタデータ、利用可能な場合は Plugin とチャンネルのスキーマを含む)。Raw JSON エディターは、スナップショットが安全に raw 往復できる場合にのみ利用できます。
|
||||
- スナップショットが raw テキストを安全に往復できない場合、コントロール UI はフォームモードを強制し、そのスナップショットの Raw モードを無効にします。
|
||||
- Raw JSON エディターの「保存済みにリセット」は、フラット化されたスナップショットを再レンダリングする代わりに、raw で作成された形状 (書式、コメント、`$include` レイアウト) を保持するため、スナップショットが安全に往復できる場合は外部編集がリセット後も残ります。
|
||||
- 構造化された SecretRef オブジェクト値は、誤ってオブジェクトから文字列へ破損することを防ぐため、フォームのテキスト入力では読み取り専用でレンダリングされます。
|
||||
- 検証付きで適用と再起動を行い (`config.apply`)、最後にアクティブだったセッションを起動します。
|
||||
- 書き込みには、同時編集を上書きしないためのベースハッシュガードが含まれます。
|
||||
- 書き込み (`config.set`/`config.apply`/`config.patch`) は、送信された設定ペイロード内の参照について、アクティブな SecretRef 解決を事前チェックします。未解決のアクティブな送信済み参照は、書き込み前に拒否されます。
|
||||
- スキーマとフォームレンダリング (`config.schema` / `config.schema.lookup`。フィールド `title` / `description`、一致した UI ヒント、直下の子要約、ネストされた object/wildcard/array/composition ノード上の docs メタデータ、利用可能な場合は plugin とチャンネルスキーマを含む)。Raw JSON エディターは、スナップショットが安全な raw 往復を持つ場合にのみ利用できます。
|
||||
- スナップショットが raw テキストを安全に往復できない場合、Control UI はフォームモードを強制し、そのスナップショットの Raw モードを無効にします。
|
||||
- Raw JSON エディターの「保存済みにリセット」は、平坦化されたスナップショットを再レンダリングするのではなく、raw で作成された形状 (フォーマット、コメント、`$include` レイアウト) を保持するため、スナップショットが安全に往復できる場合、外部編集はリセット後も維持されます。
|
||||
- 構造化された SecretRef object 値は、誤って object から文字列へ破損するのを防ぐため、フォームのテキスト入力では読み取り専用で表示されます。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="デバッグ、ログ、更新">
|
||||
- デバッグ: ステータス/ヘルス/モデルのスナップショット、イベントログ、手動 RPC 呼び出し (`status`, `health`, `models.list`)。
|
||||
- ログ: Gateway ファイルログのライブテール、フィルター/エクスポート付き (`logs.tail`)。
|
||||
- 更新: 再起動レポート付きでパッケージ/git 更新と再起動を実行し (`update.run`)、再接続後に `update.status` をポーリングして実行中の Gateway バージョンを検証します。
|
||||
- ログ: gateway ファイルログのライブテールとフィルター/エクスポート (`logs.tail`)。
|
||||
- 更新: パッケージ/git 更新と再起動を実行し (`update.run`)、再起動レポートを取得した後、再接続後に `update.status` をポーリングして実行中の gateway バージョンを検証します。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron ジョブパネルの注記">
|
||||
- 分離ジョブでは、配信のデフォルトはサマリーのアナウンスです。内部専用の実行にしたい場合は、なしに切り替えられます。
|
||||
- アナウンスが選択されている場合、チャンネル/ターゲットフィールドが表示されます。
|
||||
- Webhook モードは、有効な HTTP(S) Webhook URL に設定された `delivery.to` とともに `delivery.mode = "webhook"` を使用します。
|
||||
- メインセッションジョブでは、Webhook と配信なしモードを利用できます。
|
||||
- 詳細編集コントロールには、実行後削除、エージェント上書きのクリア、Cron の厳密/分散オプション、エージェントのモデル/思考の上書き、ベストエフォート配信トグルが含まれます。
|
||||
- フォーム検証はフィールドレベルのエラーとしてインライン表示されます。無効な値がある場合、修正されるまで保存ボタンは無効になります。
|
||||
- 専用の bearer トークンを送信するには `cron.webhookToken` を設定します。省略した場合、Webhook は認証ヘッダーなしで送信されます。
|
||||
- 非推奨のフォールバック: `notify: true` を持つ保存済みの従来ジョブは、移行されるまで引き続き `cron.webhook` を使用できます。
|
||||
- 分離ジョブでは、配信のデフォルトは要約の告知です。内部専用の実行にしたい場合は none に切り替えられます。
|
||||
- announce が選択されている場合、チャンネル/ターゲットフィールドが表示されます。
|
||||
- Webhook モードは、有効な HTTP(S) webhook URL に設定された `delivery.to` とともに `delivery.mode = "webhook"` を使用します。
|
||||
- メインセッションジョブでは、webhook と none の配信モードを利用できます。
|
||||
- 詳細編集コントロールには、実行後削除、エージェント上書きのクリア、cron exact/stagger オプション、エージェントモデル/思考上書き、ベストエフォート配信トグルが含まれます。
|
||||
- フォーム検証はフィールドレベルのエラーとしてインライン表示されます。無効な値があると、修正されるまで保存ボタンが無効になります。
|
||||
- 専用 bearer トークンを送信するには `cron.webhookToken` を設定します。省略した場合、webhook は認証ヘッダーなしで送信されます。
|
||||
- 非推奨のフォールバック: `notify: true` を持つ保存済みのレガシージョブは、移行されるまで `cron.webhook` を引き続き使用できます。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -155,62 +155,62 @@ Gateway が同じコンピューターで実行されている場合は、次を
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="送信と履歴のセマンティクス">
|
||||
- `chat.send` は**非ブロッキング**です。`{ runId, status: "started" }` ですぐに ACK し、応答は `chat` イベント経由でストリーミングされます。
|
||||
- チャットアップロードは画像と動画以外のファイルを受け付けます。画像はネイティブの画像パスを保持し、その他のファイルは管理対象メディアとして保存され、履歴には添付リンクとして表示されます。
|
||||
- 同じ `idempotencyKey` で再送信すると、実行中は `{ status: "in_flight" }`、完了後は `{ status: "ok" }` が返ります。
|
||||
- `chat.history` の応答は UI の安全性のためサイズ制限されています。トランスクリプトエントリが大きすぎる場合、Gateway は長いテキストフィールドを切り詰め、重いメタデータブロックを省略し、サイズ超過メッセージをプレースホルダー（`[chat.history omitted: message too large]`）に置き換えることがあります。
|
||||
- アシスタントまたは生成された画像は管理対象メディア参照として永続化され、認証済み Gateway メディア URL 経由で返されます。そのため、再読み込みは生の base64 画像ペイロードがチャット履歴応答に残っていることに依存しません。
|
||||
- `chat.history` は、表示専用のインラインディレクティブタグ（たとえば `[[reply_to_*]]` と `[[audio_as_voice]]`）、プレーンテキストのツール呼び出し XML ペイロード（`<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>`、切り詰められたツール呼び出しブロックを含む）、漏えいした ASCII/全角のモデル制御トークンも、表示されるアシスタントテキストから除去し、表示テキスト全体が正確なサイレントトークン `NO_REPLY` / `no_reply` だけであるアシスタントエントリを省略します。
|
||||
- アクティブな送信中と最終的な履歴更新中、`chat.history` が一時的に古いスナップショットを返した場合でも、チャットビューはローカルの楽観的なユーザー/アシスタントメッセージを表示し続けます。Gateway 履歴が追いつくと、正規のトランスクリプトがそれらのローカルメッセージを置き換えます。
|
||||
- ライブの `chat` イベントは配信状態であり、`chat.history` は永続セッショントランスクリプトから再構築されます。ツール最終イベントの後、Control UI は履歴を再読み込みし、小さな楽観的末尾だけをマージします。トランスクリプト境界は [WebChat](/ja-JP/web/webchat) に記載されています。
|
||||
- `chat.inject` はアシスタントメモをセッショントランスクリプトに追加し、UI のみの更新として `chat` イベントをブロードキャストします（エージェント実行なし、チャンネル配信なし）。
|
||||
- チャットヘッダーのモデルおよび思考ピッカーは、`sessions.patch` 経由でアクティブセッションに即座にパッチを適用します。これらは永続的なセッションオーバーライドであり、1 ターン限定の送信オプションではありません。
|
||||
- Control UI で `/new` と入力すると、New Chat と同じ新しいダッシュボードセッションが作成され、そのセッションに切り替わります。`/reset` と入力すると、現在のセッションに対する Gateway の明示的なインプレースリセットが維持されます。
|
||||
- チャットモデルピッカーは、Gateway に設定されたモデルビューを要求します。`agents.defaults.models` が存在する場合、その許可リストがピッカーを制御します。それ以外の場合、ピッカーには明示的な `models.providers.*.models` エントリと、使用可能な認証を持つプロバイダーが表示されます。完全なカタログは、デバッグ用の `models.list` RPC で `view: "all"` を指定すると引き続き利用できます。
|
||||
- 新しい Gateway セッション使用状況レポートが高いコンテキスト圧力を示す場合、チャットコンポーザー領域にはコンテキスト通知が表示され、推奨 Compaction レベルでは通常のセッション Compaction パスを実行するコンパクトボタンが表示されます。古いトークンスナップショットは、Gateway が新しい使用状況を再度報告するまで非表示になります。
|
||||
- `chat.send` は **非ブロッキング** です。`{ runId, status: "started" }` ですぐに ack し、応答は `chat` イベント経由でストリーミングされます。
|
||||
- チャットのアップロードは画像と動画以外のファイルを受け付けます。画像はネイティブの画像パスを保持し、それ以外のファイルは管理対象メディアとして保存され、履歴には添付リンクとして表示されます。
|
||||
- 同じ `idempotencyKey` で再送信すると、実行中は `{ status: "in_flight" }` が返り、完了後は `{ status: "ok" }` が返ります。
|
||||
- `chat.history` の応答は UI の安全性のためサイズ制限されます。トランスクリプト項目が大きすぎる場合、Gateway は長いテキストフィールドを切り詰め、重いメタデータブロックを省略し、過大なメッセージをプレースホルダー（`[chat.history omitted: message too large]`）に置き換えることがあります。
|
||||
- アシスタント/生成画像は管理対象メディア参照として永続化され、認証済み Gateway メディア URL 経由で返されるため、再読み込みは生の base64 画像ペイロードがチャット履歴応答に残っていることに依存しません。
|
||||
- `chat.history` は、表示用のインラインディレクティブタグ（例: `[[reply_to_*]]` と `[[audio_as_voice]]`）、プレーンテキストのツール呼び出し XML ペイロード（`<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>`、切り詰められたツール呼び出しブロックを含む）、漏洩した ASCII/全角のモデル制御トークンも、表示されるアシスタントテキストから取り除き、表示テキスト全体が正確なサイレントトークン `NO_REPLY` / `no_reply` だけのアシスタント項目を省略します。
|
||||
- アクティブな送信中と最終的な履歴更新中に、`chat.history` が一時的に古いスナップショットを返した場合でも、チャットビューはローカルの楽観的なユーザー/アシスタントメッセージを表示したままにします。Gateway 履歴が追いつくと、正規のトランスクリプトがそれらのローカルメッセージを置き換えます。
|
||||
- ライブ `chat` イベントは配信状態であり、`chat.history` は永続的なセッショントランスクリプトから再構築されます。ツール最終イベントの後、Control UI は履歴を再読み込みし、小さな楽観的テールだけをマージします。トランスクリプト境界は [WebChat](/ja-JP/web/webchat) に記載されています。
|
||||
- `chat.inject` はアシスタントメモをセッショントランスクリプトに追加し、UI のみの更新のために `chat` イベントをブロードキャストします（エージェント実行なし、チャネル配信なし）。
|
||||
- チャットヘッダーのモデルと思考ピッカーは、`sessions.patch` 経由でアクティブセッションに即座にパッチします。これらは永続的なセッションオーバーライドであり、1 ターン限りの送信オプションではありません。
|
||||
- Control UI で `/new` と入力すると、New Chat と同じ新しいダッシュボードセッションが作成され、そこに切り替わります。`/reset` と入力すると、現在のセッションに対する Gateway の明示的なインプレースリセットが維持されます。
|
||||
- チャットモデルピッカーは Gateway の設定済みモデルビューを要求します。`agents.defaults.models` が存在する場合、その許可リストがピッカーを駆動します。それ以外の場合、ピッカーは明示的な `models.providers.*.models` 項目と、利用可能な認証を持つプロバイダーを表示します。完全なカタログは、デバッグ用の `models.list` RPC で `view: "all"` を指定すると引き続き利用できます。
|
||||
- 新しい Gateway セッション使用状況レポートで高いコンテキスト圧力が示されると、チャットコンポーザー領域にコンテキスト通知が表示され、推奨 Compaction レベルでは通常のセッション Compaction パスを実行するコンパクトボタンが表示されます。古いトークンスナップショットは、Gateway が再び新しい使用状況を報告するまで非表示になります。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="トークモード（ブラウザーリアルタイム）">
|
||||
トークモードは、登録済みのリアルタイム音声プロバイダーを使用します。OpenAI を設定するには `talk.provider: "openai"` と `talk.providers.openai.apiKey` を指定し、Google を設定するには `talk.provider: "google"` と `talk.providers.google.apiKey` を指定します。Voice Call のリアルタイムプロバイダー設定は、フォールバックとして引き続き再利用できます。ブラウザーが標準プロバイダー API キーを受け取ることはありません。OpenAI は WebRTC 用の一時的な Realtime クライアントシークレットを受け取ります。Google Live は、ブラウザー WebSocket セッション用の 1 回限りの制約付き Live API 認証トークンを受け取り、指示とツール宣言は Gateway によってトークン内に固定されます。バックエンドのリアルタイムブリッジのみを公開するプロバイダーは Gateway リレートランスポート経由で実行されるため、認証情報とベンダーソケットはサーバー側に留まり、ブラウザー音声は認証済み Gateway RPC 経由で移動します。Realtime セッションプロンプトは Gateway によって組み立てられます。`talk.realtime.session` は呼び出し元が提供する指示オーバーライドを受け付けません。
|
||||
トークモードは登録済みのリアルタイム音声プロバイダーを使用します。OpenAI は `talk.provider: "openai"` と `talk.providers.openai.apiKey` で設定するか、Google は `talk.provider: "google"` と `talk.providers.google.apiKey` で設定します。Voice Call リアルタイムプロバイダー設定はフォールバックとして引き続き再利用できます。ブラウザーが標準のプロバイダー API キーを受け取ることはありません。OpenAI は WebRTC 用の一時的な Realtime クライアントシークレットを受け取ります。Google Live は、ブラウザー WebSocket セッション用の 1 回限りの制約付き Live API 認証トークンを受け取り、指示とツール宣言は Gateway によってそのトークン内にロックされます。バックエンドのリアルタイムブリッジだけを公開するプロバイダーは Gateway リレートランスポートを経由するため、認証情報とベンダーソケットはサーバー側に留まり、ブラウザー音声は認証済み Gateway RPC 経由で移動します。Realtime セッションプロンプトは Gateway によって組み立てられます。`talk.realtime.session` は呼び出し元が指定する指示オーバーライドを受け付けません。
|
||||
|
||||
Chat コンポーザーでは、Talk コントロールはマイクのディクテーションボタンの横にある波形ボタンです。Talk が開始されると、コンポーザーのステータス行には、音声接続中は `Connecting Talk...`、接続後は `Talk live`、リアルタイムツール呼び出しが `chat.send` 経由で設定済みのより大きなモデルに問い合わせている間は `Asking OpenClaw...` が表示されます。
|
||||
Chat コンポーザーでは、Talk コントロールはマイクディクテーションボタンの隣にある波形ボタンです。Talk が開始すると、コンポーザーのステータス行には `Connecting Talk...` が表示され、その後、音声が接続されている間は `Talk live`、またはリアルタイムツール呼び出しが `chat.send` 経由で設定済みのより大きなモデルに問い合わせている間は `Asking OpenClaw...` が表示されます。
|
||||
|
||||
メンテナー向けライブスモーク: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` は、OpenAI ブラウザー WebRTC SDP 交換、Google Live の制約付きトークンによるブラウザー WebSocket セットアップ、偽のマイクメディアを使った Gateway リレーブラウザーアダプターを検証します。このコマンドはプロバイダーのステータスのみを出力し、シークレットはログに記録しません。
|
||||
メンテナー向けライブスモーク: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` は、OpenAI ブラウザー WebRTC SDP 交換、Google Live の制約付きトークンによるブラウザー WebSocket セットアップ、偽のマイクメディアを使用した Gateway リレーブラウザーアダプターを検証します。このコマンドはプロバイダーステータスのみを出力し、シークレットはログに記録しません。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="停止と中止">
|
||||
- **Stop** をクリックします（`chat.abort` を呼び出します）。
|
||||
- 実行がアクティブな間、通常のフォローアップはキューに入ります。キュー内のメッセージで **Steer** をクリックすると、そのフォローアップを実行中のターンに注入できます。
|
||||
- **停止** をクリックします（`chat.abort` を呼び出します）。
|
||||
- 実行がアクティブな間、通常のフォローアップはキューに入ります。キュー内のメッセージで **誘導** をクリックすると、そのフォローアップが実行中のターンに注入されます。
|
||||
- `/stop`（または `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop` のような単独の中止フレーズ）を入力すると、帯域外で中止します。
|
||||
- `chat.abort` は、そのセッションのすべてのアクティブな実行を中止するために `{ sessionKey }`（`runId` なし）をサポートします。
|
||||
- `chat.abort` は `{ sessionKey }`（`runId` なし）をサポートし、そのセッションのすべてのアクティブな実行を中止できます。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="中止時の部分保持">
|
||||
- 実行が中止された場合でも、部分的なアシスタントテキストが UI に表示されることがあります。
|
||||
- Gateway は、バッファーされた出力が存在する場合、中止された部分的なアシスタントテキストをトランスクリプト履歴に永続化します。
|
||||
- 永続化されたエントリには中止メタデータが含まれるため、トランスクリプト利用側は中止された部分出力と通常の完了出力を区別できます。
|
||||
- 実行が中止された場合でも、部分的なアシスタントテキストを UI に表示できます。
|
||||
- Gateway は、バッファリングされた出力が存在する場合、中止された部分的なアシスタントテキストをトランスクリプト履歴に永続化します。
|
||||
- 永続化された項目には中止メタデータが含まれるため、トランスクリプト利用者は中止された部分出力と通常の完了出力を区別できます。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## PWA のインストールと Web Push
|
||||
## PWA インストールと Web Push
|
||||
|
||||
Control UI には `manifest.webmanifest` とサービスワーカーが同梱されているため、最新のブラウザーではスタンドアロン PWA としてインストールできます。Web Push により、タブやブラウザーウィンドウが開いていない場合でも、Gateway は通知でインストール済み PWA を起動できます。
|
||||
Control UI には `manifest.webmanifest` とサービスワーカーが同梱されているため、最新のブラウザーはスタンドアロン PWA としてインストールできます。Web Push により、タブやブラウザーウィンドウが開いていない場合でも、Gateway は通知でインストール済み PWA を起動できます。
|
||||
|
||||
| サーフェス | 動作 |
|
||||
| サーフェス | 機能 |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `ui/public/manifest.webmanifest` | PWA マニフェスト。到達可能になると、ブラウザーは「アプリをインストール」を提示します。 |
|
||||
| `ui/public/sw.js` | `push` イベントと通知クリックを処理するサービスワーカー。 |
|
||||
| `push/vapid-keys.json`（OpenClaw 状態ディレクトリ配下） | Web Push ペイロードの署名に使用される、自動生成された VAPID キーペア。 |
|
||||
| `push/vapid-keys.json`（OpenClaw 状態ディレクトリ配下） | Web Push ペイロードの署名に使用される、自動生成された VAPID 鍵ペア。 |
|
||||
| `push/web-push-subscriptions.json` | 永続化されたブラウザーサブスクリプションエンドポイント。 |
|
||||
|
||||
キーを固定したい場合（マルチホストデプロイ、シークレットローテーション、テストなど）は、Gateway プロセスの環境変数で VAPID キーペアをオーバーライドします。
|
||||
キーを固定したい場合（マルチホストデプロイ、シークレットローテーション、テストなど）は、Gateway プロセス上の環境変数で VAPID 鍵ペアをオーバーライドします。
|
||||
|
||||
- `OPENCLAW_VAPID_PUBLIC_KEY`
|
||||
- `OPENCLAW_VAPID_PRIVATE_KEY`
|
||||
- `OPENCLAW_VAPID_SUBJECT`（デフォルトは `mailto:openclaw@localhost`）
|
||||
|
||||
Control UI は、ブラウザーサブスクリプションを登録およびテストするために、これらのスコープ制限付き Gateway メソッドを使用します。
|
||||
Control UI は、ブラウザーサブスクリプションの登録とテストに、次のスコープ制限付き Gateway メソッドを使用します。
|
||||
|
||||
- `push.web.vapidPublicKey` — アクティブな VAPID 公開鍵を取得します。
|
||||
- `push.web.subscribe` — `endpoint` と `keys.p256dh`/`keys.auth` を登録します。
|
||||
@ -218,22 +218,22 @@ Control UI は、ブラウザーサブスクリプションを登録およびテ
|
||||
- `push.web.test` — 呼び出し元のサブスクリプションにテスト通知を送信します。
|
||||
|
||||
<Note>
|
||||
Web Push は、iOS APNS リレーパス（リレー backed push については [設定](/ja-JP/gateway/configuration) を参照）および既存の `push.test` メソッドとは独立しています。これらはネイティブモバイルペアリングを対象とします。
|
||||
Web Push は iOS APNS リレーパス（リレー支援 push については [設定](/ja-JP/gateway/configuration) を参照）および既存の `push.test` メソッドとは独立しています。これらはネイティブモバイルペアリングを対象にします。
|
||||
</Note>
|
||||
|
||||
## ホストされた埋め込み
|
||||
## ホスト型埋め込み
|
||||
|
||||
アシスタントメッセージは、`[embed ...]` ショートコードを使ってホストされた Web コンテンツをインラインでレンダリングできます。iframe サンドボックスポリシーは `gateway.controlUi.embedSandbox` によって制御されます。
|
||||
アシスタントメッセージは `[embed ...]` ショートコードでホスト型 Web コンテンツをインライン表示できます。iframe サンドボックスポリシーは `gateway.controlUi.embedSandbox` によって制御されます。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
ホストされた埋め込み内でのスクリプト実行を無効にします。
|
||||
ホスト型埋め込み内でのスクリプト実行を無効にします。
|
||||
</Tab>
|
||||
<Tab title="scripts (default)">
|
||||
オリジン分離を維持しながらインタラクティブな埋め込みを許可します。これがデフォルトであり、通常は自己完結型のブラウザーゲーム/ウィジェットには十分です。
|
||||
<Tab title="scripts（デフォルト）">
|
||||
オリジン分離を維持しながらインタラクティブな埋め込みを許可します。これはデフォルトであり、通常は自己完結型のブラウザーゲーム/ウィジェットには十分です。
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
より強い権限を意図的に必要とする同一サイトドキュメントのために、`allow-scripts` に加えて `allow-same-origin` を追加します。
|
||||
意図的により強い権限を必要とする同一サイトドキュメント向けに、`allow-scripts` に加えて `allow-same-origin` を追加します。
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
@ -253,11 +253,11 @@ Web Push は、iOS APNS リレーパス（リレー backed push については
|
||||
埋め込みドキュメントが本当に同一オリジンの動作を必要とする場合にのみ、`trusted` を使用してください。ほとんどのエージェント生成ゲームやインタラクティブキャンバスでは、`scripts` の方が安全な選択です。
|
||||
</Warning>
|
||||
|
||||
絶対外部 `http(s)` 埋め込み URL は、デフォルトでは引き続きブロックされます。`[embed url="https://..."]` でサードパーティページを読み込ませたいことが意図的にある場合は、`gateway.controlUi.allowExternalEmbedUrls: true` を設定してください。
|
||||
絶対外部 `http(s)` 埋め込み URL はデフォルトでブロックされたままです。意図的に `[embed url="https://..."]` でサードパーティページを読み込みたい場合は、`gateway.controlUi.allowExternalEmbedUrls: true` を設定します。
|
||||
|
||||
## チャットメッセージ幅
|
||||
|
||||
グループ化されたチャットメッセージには、読みやすいデフォルトの最大幅が使用されます。ワイドモニターのデプロイでは、`gateway.controlUi.chatMessageMaxWidth` を設定することで、同梱 CSS にパッチを当てずにこれをオーバーライドできます。
|
||||
グループ化されたチャットメッセージには、読みやすいデフォルトの最大幅が使用されます。ワイドモニター環境では、`gateway.controlUi.chatMessageMaxWidth` を設定することで、同梱 CSS にパッチせずに上書きできます。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -275,7 +275,7 @@ Web Push は、iOS APNS リレーパス（リレー backed push については
|
||||
|
||||
<Tabs>
|
||||
<Tab title="統合 Tailscale Serve（推奨）">
|
||||
Gateway をループバックに保持し、Tailscale Serve に HTTPS でプロキシさせます。
|
||||
Gateway をループバックに維持し、Tailscale Serve で HTTPS プロキシさせます。
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -285,12 +285,12 @@ Web Push は、iOS APNS リレーパス（リレー backed push については
|
||||
|
||||
- `https://<magicdns>/`（または設定済みの `gateway.controlUi.basePath`）
|
||||
|
||||
デフォルトでは、`gateway.auth.allowTailscale` が `true` の場合、Control UI/WebSocket Serve リクエストは Tailscale ID ヘッダー（`tailscale-user-login`）経由で認証できます。OpenClaw は、`x-forwarded-for` アドレスを `tailscale whois` で解決してヘッダーと照合することで ID を検証し、リクエストが Tailscale の `x-forwarded-*` ヘッダー付きで local loopback に到達した場合にのみ受け入れます。ブラウザーデバイス ID を持つ Control UI オペレーターセッションでは、この検証済み Serve パスはデバイスペアリングの往復もスキップします。デバイスなしのブラウザーとノードロール接続は、通常のデバイスチェックに従います。Serve トラフィックであっても明示的な共有シークレット認証情報を要求したい場合は、`gateway.auth.allowTailscale: false` を設定してください。そのうえで `gateway.auth.mode: "token"` または `"password"` を使用します。
|
||||
デフォルトでは、`gateway.auth.allowTailscale` が `true` の場合、Control UI/WebSocket Serve リクエストは Tailscale ID ヘッダー（`tailscale-user-login`）経由で認証できます。OpenClaw は `x-forwarded-for` アドレスを `tailscale whois` で解決してヘッダーと照合することで ID を検証し、リクエストが Tailscale の `x-forwarded-*` ヘッダー付きでループバックに到達した場合にのみ受け付けます。ブラウザーデバイス ID を持つ Control UI オペレーターセッションでは、この検証済み Serve パスはデバイスペアリングの往復もスキップします。デバイスなしのブラウザーとノードロール接続は、通常のデバイスチェックに従います。Serve トラフィックでも明示的な共有シークレット認証情報を要求したい場合は、`gateway.auth.allowTailscale: false` を設定します。その後、`gateway.auth.mode: "token"` または `"password"` を使用します。
|
||||
|
||||
その非同期 Serve ID パスでは、同じクライアント IP と認証スコープに対する認証失敗の試行は、レート制限の書き込み前に直列化されます。そのため、同じブラウザーからの同時の不正リトライでは、2 つの単純な不一致が並行して競合する代わりに、2 番目のリクエストで `retry later` が表示されることがあります。
|
||||
その非同期 Serve ID パスでは、同じクライアント IP と認証スコープの失敗した認証試行は、レート制限の書き込み前に直列化されます。そのため、同じブラウザーからの同時の不正な再試行では、2 つの単純な不一致が並列に競合する代わりに、2 回目のリクエストで `retry later` が表示されることがあります。
|
||||
|
||||
<Warning>
|
||||
トークンなしの Serve 認証は、Gateway ホストが信頼されていることを前提とします。そのホスト上で信頼できないローカルコードが実行される可能性がある場合は、トークン/パスワード認証を要求してください。
|
||||
トークンなしの Serve 認証は、gateway ホストが信頼されていることを前提にします。そのホスト上で信頼できないローカルコードが実行される可能性がある場合は、トークン/パスワード認証を要求してください。
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
@ -299,7 +299,7 @@ Web Push は、iOS APNS リレーパス（リレー backed push については
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
|
||||
次に開きます。
|
||||
次に開く:
|
||||
|
||||
- `http://<tailscale-ip>:18789/`（または設定済みの `gateway.controlUi.basePath`）
|
||||
|
||||
@ -310,13 +310,13 @@ Web Push は、iOS APNS リレーパス（リレー backed push については
|
||||
|
||||
## 安全でない HTTP
|
||||
|
||||
プレーン HTTP（`http://<lan-ip>` または `http://<tailscale-ip>`）でダッシュボードを開くと、ブラウザーは**非セキュアコンテキスト**で実行され、WebCrypto をブロックします。デフォルトでは、OpenClaw はデバイス ID のない Control UI 接続を**ブロック**します。
|
||||
プレーン HTTP（`http://<lan-ip>` または `http://<tailscale-ip>`）でダッシュボードを開くと、ブラウザーは **非セキュアコンテキスト** で実行され、WebCrypto をブロックします。デフォルトでは、OpenClaw はデバイス ID のない Control UI 接続を **ブロック** します。
|
||||
|
||||
文書化された例外:
|
||||
記載されている例外:
|
||||
|
||||
- `gateway.controlUi.allowInsecureAuth=true` による localhost 限定の安全でない HTTP 互換性
|
||||
- `gateway.auth.mode: "trusted-proxy"` 経由でのオペレーター Control UI 認証の成功
|
||||
- 緊急時用の `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
- `gateway.controlUi.allowInsecureAuth=true` による localhost のみの安全でない HTTP 互換性
|
||||
- `gateway.auth.mode: "trusted-proxy"` 経由で成功したオペレーター Control UI 認証
|
||||
- 緊急用の `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
|
||||
**推奨される修正:** HTTPS (Tailscale Serve) を使うか、UI をローカルで開きます。
|
||||
|
||||
@ -335,11 +335,11 @@ Web Push は、iOS APNS リレーパス（リレー backed push については
|
||||
}
|
||||
```
|
||||
|
||||
`allowInsecureAuth` はローカル互換性用のトグルにすぎません。
|
||||
`allowInsecureAuth` はローカル互換性トグルのみです。
|
||||
|
||||
- 非セキュアな HTTP コンテキストで、localhost の Control UI セッションがデバイス ID なしで続行できるようにします。
|
||||
- ペアリングチェックはバイパスしません。
|
||||
- リモート (localhost 以外) のデバイス ID 要件は緩和しません。
|
||||
- リモート (非 localhost) のデバイス ID 要件は緩和しません。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="緊急時のみ">
|
||||
@ -354,43 +354,53 @@ Web Push は、iOS APNS リレーパス（リレー backed push については
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` は Control UI のデバイス ID チェックを無効化し、重大なセキュリティ低下を招きます。緊急使用後は速やかに元に戻してください。
|
||||
`dangerouslyDisableDeviceAuth` は Control UI のデバイス ID チェックを無効化し、深刻なセキュリティ低下を招きます。緊急使用後は速やかに元に戻してください。
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="信頼済みプロキシに関する注記">
|
||||
- 信頼済みプロキシ認証に成功すると、デバイス ID なしで **operator** Control UI セッションを許可できます。
|
||||
- これは node-role Control UI セッションには適用されません。
|
||||
- 同一ホストのループバックリバースプロキシでも、信頼済みプロキシ認証の条件は満たされません。[信頼済みプロキシ認証](/ja-JP/gateway/trusted-proxy-auth) を参照してください。
|
||||
<Accordion title="信頼済みプロキシの注意事項">
|
||||
- 信頼済みプロキシ認証に成功すると、デバイス ID なしで **オペレーター** Control UI セッションを許可できます。
|
||||
- これはノードロールの Control UI セッションには適用されません。
|
||||
- 同一ホストのループバックリバースプロキシでも、信頼済みプロキシ認証は満たしません。[信頼済みプロキシ認証](/ja-JP/gateway/trusted-proxy-auth)を参照してください。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
HTTPS セットアップのガイダンスについては [Tailscale](/ja-JP/gateway/tailscale) を参照してください。
|
||||
HTTPS セットアップのガイダンスについては、[Tailscale](/ja-JP/gateway/tailscale) を参照してください。
|
||||
|
||||
## コンテンツセキュリティポリシー
|
||||
|
||||
Control UI には厳格な `img-src` ポリシーが含まれています。許可されるのは **同一オリジン** のアセット、`data:` URL、ローカルで生成された `blob:` URL のみです。リモートの `http(s)` およびプロトコル相対の画像 URL はブラウザによって拒否され、ネットワークフェッチは発生しません。
|
||||
Control UI には厳格な `img-src` ポリシーが同梱されています。許可されるのは、**同一オリジン** のアセット、`data:` URL、ローカルで生成された `blob:` URL のみです。リモートの `http(s)` およびプロトコル相対の画像 URL はブラウザーによって拒否され、ネットワーク取得は発生しません。
|
||||
|
||||
実際には、これは次を意味します。
|
||||
実際には、これは次のことを意味します。
|
||||
|
||||
- 相対パス配下で提供されるアバターや画像 (例: `/avatars/<id>`) は引き続き表示されます。UI がフェッチしてローカルの `blob:` URL に変換する、認証付きアバタールートも含まれます。
|
||||
- 相対パス (たとえば `/avatars/<id>`) で提供されるアバターや画像は引き続き表示されます。UI が取得してローカルの `blob:` URL に変換する、認証付きアバタールートも含まれます。
|
||||
- インラインの `data:image/...` URL は引き続き表示されます (プロトコル内ペイロードに便利です)。
|
||||
- Control UI によって作成されたローカルの `blob:` URL は引き続き表示されます。
|
||||
- チャネルメタデータから出力されたリモートアバター URL は、Control UI のアバターヘルパーで取り除かれ、組み込みのロゴ/バッジに置き換えられます。そのため、侵害された、または悪意のあるチャネルがオペレーターのブラウザから任意のリモート画像フェッチを強制することはできません。
|
||||
- チャンネルメタデータが出力するリモートアバター URL は、Control UI のアバターヘルパーで取り除かれ、組み込みのロゴ/バッジに置き換えられます。そのため、侵害された、または悪意のあるチャンネルが、オペレーターのブラウザーから任意のリモート画像取得を強制することはできません。
|
||||
|
||||
この動作を得るために変更は不要です。常に有効で、設定変更はできません。
|
||||
この動作を得るために変更は不要です。常に有効で、設定はできません。
|
||||
|
||||
## アバタールート認証
|
||||
|
||||
Gateway 認証が設定されている場合、Control UI のアバターエンドポイントには API の他の部分と同じ Gateway トークンが必要です。
|
||||
|
||||
- `GET /avatar/<agentId>` は認証済みの呼び出し元にのみアバター画像を返します。`GET /avatar/<agentId>?meta=1` は同じルールでアバターメタデータを返します。
|
||||
- どちらのルートへの未認証リクエストも拒否されます (兄弟の assistant-media ルートと同様です)。これにより、他の部分では保護されているホストで、アバタールートからエージェント ID が漏れることを防ぎます。
|
||||
- Control UI 自体はアバターをフェッチするときに Gateway トークンを bearer ヘッダーとして転送し、認証済みの blob URL を使うため、画像はダッシュボード内で引き続き表示されます。
|
||||
- `GET /avatar/<agentId>` は認証済み呼び出し元にのみアバター画像を返します。`GET /avatar/<agentId>?meta=1` は同じルールでアバターメタデータを返します。
|
||||
- どちらのルートへの未認証リクエストも拒否されます (隣接するアシスタントメディアルートと同じです)。これにより、それ以外は保護されているホストで、アバタールートがエージェント ID を漏らすことを防ぎます。
|
||||
- Control UI 自体は、アバター取得時に Gateway トークンを bearer ヘッダーとして転送し、認証済みの blob URL を使うため、画像はダッシュボードで引き続き表示されます。
|
||||
|
||||
Gateway 認証を無効化した場合 (共有ホストでは非推奨)、Gateway の他の部分と同様に、アバタールートも未認証になります。
|
||||
|
||||
## アシスタントメディアルート認証
|
||||
|
||||
Gateway 認証が設定されている場合、アシスタントのローカルメディアプレビューは 2 段階のルートを使用します。
|
||||
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` には通常の Control UI オペレーター認証が必要です。ブラウザーは可用性を確認するとき、Gateway トークンを bearer ヘッダーとして送信します。
|
||||
- 成功したメタデータレスポンスには、その正確なソースパスにスコープされた短命の `mediaTicket` が含まれます。
|
||||
- ブラウザーでレンダリングされる画像、音声、動画、ドキュメントの URL は、有効な Gateway トークンやパスワードの代わりに `mediaTicket=<ticket>` を使用します。チケットはすぐに期限切れになり、別のソースを認可することはできません。
|
||||
|
||||
これにより、再利用可能な Gateway 認証情報を可視のメディア URL に入れずに、通常のメディアレンダリングとブラウザー標準のメディア要素との互換性を保てます。
|
||||
|
||||
## UI のビルド
|
||||
|
||||
Gateway は `dist/control-ui` から静的ファイルを提供します。次でビルドします。
|
||||
@ -399,7 +409,7 @@ Gateway は `dist/control-ui` から静的ファイルを提供します。次
|
||||
pnpm ui:build
|
||||
```
|
||||
|
||||
任意の絶対ベース (固定アセット URL を使いたい場合):
|
||||
任意の絶対ベース (固定アセット URL が必要な場合):
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
@ -411,11 +421,11 @@ OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
pnpm ui:dev
|
||||
```
|
||||
|
||||
その後、UI を Gateway の WS URL (例: `ws://127.0.0.1:18789`) に向けます。
|
||||
その後、UI に Gateway WS URL (例: `ws://127.0.0.1:18789`) を指定します。
|
||||
|
||||
## デバッグ/テスト: 開発サーバー + リモート Gateway
|
||||
|
||||
Control UI は静的ファイルです。WebSocket ターゲットは設定可能で、HTTP オリジンとは異なる場所にできます。これは、Vite 開発サーバーをローカルで使い、Gateway を別の場所で実行したい場合に便利です。
|
||||
Control UI は静的ファイルです。WebSocket ターゲットは設定可能で、HTTP オリジンと異なっていてもかまいません。ローカルでは Vite 開発サーバーを使い、Gateway は別の場所で実行したい場合に便利です。
|
||||
|
||||
<Steps>
|
||||
<Step title="UI 開発サーバーを起動する">
|
||||
@ -428,7 +438,7 @@ Control UI は静的ファイルです。WebSocket ターゲットは設定可
|
||||
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
|
||||
```
|
||||
|
||||
任意の一回限りの認証 (必要な場合):
|
||||
任意の 1 回限りの認証 (必要な場合):
|
||||
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
|
||||
@ -438,18 +448,18 @@ Control UI は静的ファイルです。WebSocket ターゲットは設定可
|
||||
</Steps>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="注記">
|
||||
<Accordion title="注意事項">
|
||||
- `gatewayUrl` は読み込み後に localStorage に保存され、URL から削除されます。
|
||||
- `gatewayUrl` 経由で完全な `ws://` または `wss://` エンドポイントを渡す場合は、ブラウザがクエリ文字列を正しく解析できるように `gatewayUrl` の値を URL エンコードしてください。
|
||||
- 可能な限り、`token` は URL フラグメント (`#token=...`) 経由で渡してください。フラグメントはサーバーに送信されないため、リクエストログや Referer への漏えいを避けられます。従来の `?token=` クエリパラメータも互換性のために一度だけ取り込まれますが、フォールバックとしてのみ使われ、ブートストラップ直後に取り除かれます。
|
||||
- `gatewayUrl` で完全な `ws://` または `wss://` エンドポイントを渡す場合は、ブラウザーがクエリ文字列を正しく解析できるように `gatewayUrl` の値を URL エンコードしてください。
|
||||
- `token` は可能な限り URL フラグメント (`#token=...`) で渡してください。フラグメントはサーバーに送信されないため、リクエストログや Referer からの漏えいを避けられます。従来の `?token=` クエリパラメーターも互換性のために一度だけ取り込まれますが、フォールバックとしてのみ扱われ、ブートストラップ直後に削除されます。
|
||||
- `password` はメモリ内にのみ保持されます。
|
||||
- `gatewayUrl` が設定されている場合、UI は設定や環境の認証情報にフォールバックしません。`token` (または `password`) を明示的に指定してください。明示的な認証情報がない場合はエラーです。
|
||||
- Gateway が TLS (Tailscale Serve、HTTPS プロキシなど) の背後にある場合は `wss://` を使用してください。
|
||||
- `gatewayUrl` はクリックジャッキングを防ぐため、トップレベルウィンドウ (埋め込みではない) でのみ受け付けられます。
|
||||
- Gateway が TLS の背後にある場合 (Tailscale Serve、HTTPS プロキシなど) は `wss://` を使用してください。
|
||||
- `gatewayUrl` は、クリックジャッキングを防ぐため、トップレベルウィンドウ (埋め込みではない) でのみ受け付けられます。
|
||||
- 非ループバックの Control UI デプロイでは、`gateway.controlUi.allowedOrigins` を明示的に設定する必要があります (完全なオリジン)。これにはリモート開発セットアップも含まれます。
|
||||
- Gateway の起動時に、有効な実行時の bind と port から `http://localhost:<port>` や `http://127.0.0.1:<port>` などのローカルオリジンがシードされる場合がありますが、リモートブラウザのオリジンには引き続き明示的なエントリが必要です。
|
||||
- 厳密に管理されたローカルテストを除き、`gateway.controlUi.allowedOrigins: ["*"]` は使用しないでください。これは任意のブラウザオリジンを許可するという意味であり、「現在使用しているホストに一致させる」という意味ではありません。
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` は Host ヘッダーのオリジンフォールバックモードを有効化しますが、危険なセキュリティモードです。
|
||||
- Gateway の起動時に、有効なランタイムのバインドとポートから `http://localhost:<port>` や `http://127.0.0.1:<port>` などのローカルオリジンがシードされる場合がありますが、リモートブラウザーのオリジンには引き続き明示的なエントリが必要です。
|
||||
- 厳密に制御されたローカルテストを除き、`gateway.controlUi.allowedOrigins: ["*"]` は使用しないでください。これは「使用中のホストに一致させる」ではなく、任意のブラウザーオリジンを許可することを意味します。
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` は Host ヘッダーオリジンフォールバックモードを有効にしますが、危険なセキュリティモードです。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -466,11 +476,11 @@ Control UI は静的ファイルです。WebSocket ターゲットは設定可
|
||||
}
|
||||
```
|
||||
|
||||
リモートアクセスセットアップの詳細: [リモートアクセス](/ja-JP/gateway/remote)。
|
||||
リモートアクセスのセットアップ詳細: [リモートアクセス](/ja-JP/gateway/remote)。
|
||||
|
||||
## 関連
|
||||
|
||||
- [ダッシュボード](/ja-JP/web/dashboard) — Gateway ダッシュボード
|
||||
- [ヘルスチェック](/ja-JP/gateway/health) — Gateway ヘルスモニタリング
|
||||
- [ヘルスチェック](/ja-JP/gateway/health) — Gateway ヘルス監視
|
||||
- [TUI](/ja-JP/web/tui) — ターミナルユーザーインターフェイス
|
||||
- [WebChat](/ja-JP/web/webchat) — ブラウザベースのチャットインターフェイス
|
||||
- [WebChat](/ja-JP/web/webchat) — ブラウザーベースのチャットインターフェイス
|
||||
|
||||
Loading…
Reference in New Issue
Block a user