~/.openclaw/openclaw.json で使用可能なすべてのフィールドについて説明します。タスク指向の概要については、構成 を参照してください。
構成形式は JSON5 です(コメントや末尾のカンマが許可されます)。すべてのフィールドはオプションです。省略された場合、OpenClaw は安全なデフォルト値を使用します。
チャネル
各チャネルは、その構成セクションが存在すると自動的に開始されます(enabled: false を指定した場合を除く)。
DM とグループへのアクセス
すべてのチャネルは DM ポリシーとグループポリシーをサポートしています。| DM ポリシー | 動作 |
|---|---|
pairing (デフォルト) | 未知の送信者にはワンタイムペアリングコードが送信されます。所有者が承認する必要があります。 |
allowlist | allowFrom(またはペアリング済みの許可ストア)に含まれる送信者のみを許可します。 |
open | すべての受信 DM を許可します(allowFrom: ["*"] が必要)。 |
disabled | すべての受信 DM を無視します。 |
| グループポリシー | 動作 |
|---|---|
allowlist (デフォルト) | 構成された許可リストに一致するグループのみを許可します。 |
open | グループの許可リストをバイパスします(メンションによる制限は引き続き適用されます)。 |
disabled | すべてのグループ/ルームメッセージをブロックします。 |
channels.defaults.groupPolicy は、プロバイダーの groupPolicy が設定されていない場合のデフォルト値を設定します。
ペアリングコードは 1 時間で期限切れになります。保留中の DM ペアリングリクエストは、1 チャネルあたり 3 つ までに制限されます。
プロバイダーのブロックが完全に欠落している(channels.<provider> が存在しない)場合、実行時のグループポリシーは起動時の警告とともに allowlist(フェールクローズ)にフォールバックします。チャネルごとのモデルオーバーライド
channels.modelByChannel を使用して、特定のチャネル ID を特定のモデルに固定します。値には provider/model または構成済みのモデルエイリアスを指定できます。このチャネルマッピングは、セッションにモデルオーバーライド(例:/model で設定されたもの)がまだ存在しない場合に適用されます。
チャネルのデフォルトとハートビート
channels.defaults を使用して、プロバイダー間で共通のグループポリシーやハートビートの動作を設定します。
channels.defaults.groupPolicy: プロバイダーレベルのgroupPolicyが未設定の場合のフォールバックポリシー。channels.defaults.heartbeat.showOk: ハートビート出力に正常なチャネルのステータスを含めます。channels.defaults.heartbeat.showAlerts: ハートビート出力に劣化/エラーステータスを含めます。channels.defaults.heartbeat.useIndicator: コンパクトなインジケーター形式でハートビート出力を表示します。
マルチアカウント WhatsApp
マルチアカウント WhatsApp
- アウトバウンドコマンドは、
defaultアカウントが存在すればそれをデフォルトとして使用し、存在しなければ最初に構成されたアカウント ID(ソート順)を使用します。 - オプションの
channels.whatsapp.defaultAccountを使用すると、構成済みの ID と一致する場合に、上記のフォールバック動作をオーバーライドできます。 - 従来のシングルアカウント形式の Baileys 認証ディレクトリは、
openclaw doctorによってwhatsapp/defaultに移行されます。 - アカウントごとのオーバーライド:
channels.whatsapp.accounts.<id>.sendReadReceipts,channels.whatsapp.accounts.<id>.dmPolicy,channels.whatsapp.accounts.<id>.allowFrom。
Telegram
- ボットトークン:
channels.telegram.botTokenまたはchannels.telegram.tokenFile。デフォルトアカウントのフォールバックとしてTELEGRAM_BOT_TOKEN環境変数が使用されます。 - オプションの
channels.telegram.defaultAccountは、構成済みの ID と一致する場合にデフォルトのアカウント選択をオーバーライドします。 - マルチアカウント設定(2 つ以上のアカウント ID)では、フォールバックルーティングを避けるために、明示的なデフォルト(
channels.telegram.defaultAccountまたはchannels.telegram.accounts.default)を設定してください。設定が欠落していたり無効な場合、openclaw doctorが警告を表示します。 configWrites: falseは、Telegram 主導の構成書き込み(スーパーグループ ID の移行や/config set|unset)をブロックします。type: "acp"を持つトップレベルのbindings[]エントリは、フォーラムトピック用の永続的な ACP バインディングを構成します(match.peer.idに正規のchatId:topic:topicIdを使用)。フィールドのセマンティクスは ACP エージェント と共通です。- Telegram のストリームプレビューは
sendMessage+editMessageTextを使用します(ダイレクトチャットおよびグループチャットで機能します)。 - 再試行ポリシーについては、再試行ポリシー を参照してください。
Discord
- トークン:
channels.discord.token。デフォルトアカウントのフォールバックとしてDISCORD_BOT_TOKEN環境変数が使用されます。 - オプションの
channels.discord.defaultAccountは、構成済みの ID と一致する場合にデフォルトのアカウント選択をオーバーライドします。 - 配信ターゲットには
user:<id>(DM) またはchannel:<id>(サーバーチャネル) を使用してください。数値のみの ID は拒否されます。 - ギルドスラッグ(Slug)は小文字で、スペースは
-に置き換えられます。チャネルキーはスラッグ名を使用します(#は不要)。ギルド ID の使用を推奨します。 - ボットが作成したメッセージはデフォルトで無視されます。
allowBots: trueで有効化できます。allowBots: "mentions"を使用すると、ボットに言及しているボットメッセージのみを受け入れます(自分自身のメッセージは引き続き除外されます)。 channels.discord.guilds.<id>.ignoreOtherMentions(およびチャネルごとのオーバーライド)は、ボット以外(@everyone/@here を除く)のユーザーやロールに言及しているメッセージを無視します。maxLinesPerMessage(デフォルト 17)は、2000 文字未満であっても、行数の多いメッセージを分割します。channels.discord.threadBindingsは Discord のスレッドバインドルーティングを制御します。enabled: スレッドバインドセッション機能(/focus,/unfocus,/agents,/session idle,/session max-age, バインドされた配信/ルーティング)の Discord 用オーバーライド。idleHours: 非アクティブによる自動フォーカス解除までの時間(時間単位)の Discord 用オーバーライド(0で無効)。maxAgeHours: セッションの最大存続時間(時間単位)の Discord 用オーバーライド(0で無効)。spawnSubagentSessions:sessions_spawn({ thread: true })による自動スレッド作成/バインドを有効にするスイッチ。
type: "acp"を持つトップレベルのbindings[]エントリは、チャネルとスレッド用の永続的な ACP バインディングを構成します(match.peer.idにチャネル/スレッド ID を使用)。フィールドのセマンティクスは ACP エージェント と共通です。channels.discord.ui.components.accentColorは、Discord コンポーネント v2 コンテナのアクセントカラーを設定します。channels.discord.voiceは、Discord ボイスチャネルでの会話、オプションの自動参加、および TTS オーバーライドを有効にします。channels.discord.voice.daveEncryptionおよびchannels.discord.voice.decryptionFailureToleranceは、@discordjs/voiceの DAVE オプションに渡されます(デフォルトはそれぞれtrueと24)。- OpenClaw は、復号エラーが繰り返された場合にボイスセッションを一度退出して再参加することで、音声受信の回復を試みます。
channels.discord.streamingは標準のストリームモードキーです。従来のstreamModeやブール値のstreamingは自動的に移行されます。channels.discord.autoPresenceは、実行時の可用性をボットのプレゼンス状態にマップします(正常 => オンライン、劣化 => アイドル、枯渇 => 取り込み中)。オプションでステータステキストのオーバーライドも可能です。channels.dangerouslyAllowNameMatchingは、名前やタグによる一致を再度有効にします(互換性のための非推奨モード)。
off(なし)、own(ボット自身のメッセージ、デフォルト)、all(すべてのメッセージ)、allowlist(すべてのメッセージのうち guilds.<id>.users に含まれるユーザーによるもの)。
Google Chat
- サービスアカウント JSON: インライン(
serviceAccount)またはファイルベース(serviceAccountFile)。 - サービスアカウントの SecretRef もサポートされています(
serviceAccountRef)。 - 環境変数のフォールバック:
GOOGLE_CHAT_SERVICE_ACCOUNTまたはGOOGLE_CHAT_SERVICE_ACCOUNT_FILE。 - 配信ターゲットには
spaces/<spaceId>またはusers/<userId>を使用してください。 channels.googlechat.dangerouslyAllowNameMatchingは、変更可能なメールアドレスによる一致を再度有効にします(互換性のための非推奨モード)。
Slack
- ソケットモード(Socket mode):
botTokenとappTokenの両方が必要です(デフォルトアカウントのフォールバックとしてSLACK_BOT_TOKEN+SLACK_APP_TOKEN)。 - HTTP モード:
botTokenとsigningSecret(ルートまたはアカウントごと)が必要です。 configWrites: falseは、Slack 主導の構成書き込みをブロックします。- オプションの
channels.slack.defaultAccountは、構成済みの ID と一致する場合にデフォルトのアカウント選択をオーバーライドします。 channels.slack.streamingは標準のストリームモードキーです。従来のstreamModeやブール値のstreamingは自動的に移行されます。- 配信ターゲットには
user:<id>(DM) またはchannel:<id>を使用してください。
off, own(デフォルト), all, allowlist(reactionAllowlist に基づく)。
スレッドセッションの分離: thread.historyScope は、スレッドごと(デフォルト)かチャネル全体で共有するかを選択します。thread.inheritParent を true にすると、親チャネルのログが新しいスレッドにコピーされます。
typingReaction: 返信の実行中に、受信した Slack メッセージに一時的なリアクションを追加し、完了時に削除します。"hourglass_flowing_sand"などの Slack 絵文字ショートコードを使用します。
| アクショングループ | デフォルト | 備考 |
|---|---|---|
reactions | 有効 | リアクションの追加と一覧取得 |
messages | 有効 | 読み取り/送信/編集/削除 |
pins | 有効 | ピン留め/解除/一覧取得 |
memberInfo | 有効 | メンバー情報 |
emojiList | 有効 | カスタム絵文字リスト |
Mattermost
Mattermost はプラグインとして提供されます:openclaw plugins install @openclaw/mattermost。
oncall(@メンションで応答、デフォルト)、onmessage(すべてのメッセージに応答)、onchar(特定のプレフィックスで始まるメッセージに応答)。
Mattermost ネイティブコマンドが有効な場合:
commands.callbackPathは、完全な URL ではなく/api/channels/mattermost/commandのようなパスである必要があります。commands.callbackUrlは OpenClaw ゲートウェイのエンドポイントに解決され、Mattermost サーバーからアクセス可能である必要があります。- プライベートネットワークや Tailscale 内のコールバックホストの場合、Mattermost の
ServiceSettings.AllowedUntrustedInternalConnectionsにコールバックホスト/ドメインを含める必要がある場合があります。完全な URL ではなく、ホスト/ドメインの値のみを使用してください。 channels.mattermost.configWrites: Mattermost 主導の構成書き込みを許可または拒否します。channels.mattermost.requireMention: チャネルで返信する前に@mentionを必須にします。- オプションの
channels.mattermost.defaultAccountは、構成済みの ID と一致する場合にデフォルトのアカウント選択をオーバーライドします。
Signal
off, own (デフォルト), all, allowlist (reactionAllowlist に基づく)。
channels.signal.account: チャネルの開始を特定の Signal アカウント ID に固定します。channels.signal.configWrites: Signal 主導の構成書き込みを許可または拒否します。- オプションの
channels.signal.defaultAccountは、構成済みの ID と一致する場合にデフォルトのアカウント選択をオーバーライドします。
BlueBubbles
BlueBubbles は、推奨される iMessage の利用方法です(プラグインを利用し、channels.bluebubbles で構成されます)。
- ここで扱う主要なキー:
channels.bluebubbles,channels.bluebubbles.dmPolicy。 - オプションの
channels.bluebubbles.defaultAccountは、構成済みの ID と一致する場合にデフォルトのアカウント選択をオーバーライドします。 - BlueBubbles チャネルの完全な構成については、BlueBubbles を参照してください。
iMessage
OpenClaw はimsg rpc (stdio 経由の JSON-RPC) を起動します。デーモンやポートは不要です。
- オプションの
channels.imessage.defaultAccountは、構成済みの ID と一致する場合にデフォルトのアカウント選択をオーバーライドします。 - メッセージ DB への「フルディスクアクセス」権限が必要です。
- ターゲットには
chat_id:<id>を推奨します。チャット一覧を取得するにはimsg chats --limit 20を実行してください。 cliPathには SSH ラッパーを指定できます。添付ファイルを SCP で取得するにはremoteHost(hostまたはuser@host) を設定してください。attachmentRootsとremoteAttachmentRootsは、受信した添付ファイルのパスを制限します(デフォルト:/Users/*/Library/Messages/Attachments)。- SCP は厳密なホストキーチェックを行うため、リレーホストのキーが
~/.ssh/known_hostsに存在することを確認してください。 channels.imessage.configWrites: iMessage 主導の構成書き込みを許可または拒否します。
iMessage SSH ラッパーの例
iMessage SSH ラッパーの例
Microsoft Teams
Microsoft Teams はプラグイン経由で動作し、channels.msteams で構成されます。
- ここで扱う主要なキー:
channels.msteams,channels.msteams.configWrites。 - 完全な Teams 構成(認証情報、Webhook、DM/グループポリシー、チーム/チャネルごとのオーバーライド)については、Microsoft Teams を参照してください。
IRC
IRC はプラグイン経由で動作し、channels.irc で構成されます。
- ここで扱う主要なキー:
channels.irc,channels.irc.dmPolicy,channels.irc.configWrites,channels.irc.nickserv.*。 - オプションの
channels.irc.defaultAccountは、構成済みの ID と一致する場合にデフォルトのアカウント選択をオーバーライドします。 - IRC チャネルの完全な構成(ホスト/ポート/TLS/チャネル/許可リスト/メンション制限)については、IRC を参照してください。
マルチアカウント (すべてのチャネル共通)
各チャネルで、独自の一意なaccountId を持つ複数のアカウントを実行できます。
accountIdが省略された場合、defaultアカウントが使用されます(CLI およびルーティング)。- 環境変数によるトークン指定は、デフォルトアカウントにのみ適用されます。
- 基本的なチャネル設定は、アカウントごとにオーバーライドされない限り、すべてのアカウントに適用されます。
bindings[].match.accountIdを使用して、各アカウントを異なるエージェントにルーティングできます。- シングルアカウント形式の構成から、
openclaw channels add等で別のアカウントを追加した場合、OpenClaw は既存のアカウントが動作し続けるよう、トップレベルの設定値を自動的にchannels.<channel>.accounts.defaultに移動します。 - 既存のチャネルのみを指定したバインディング(
accountIdなし)は、引き続きデフォルトアカウントと一致します。 openclaw doctor --fixは、名前付きアカウントが存在するのにdefaultが欠落している場合などの混在した構成を修復します。
その他の拡張チャネル
多くの拡張チャネルはchannels.<id> として構成され、各専用ページ(Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, Twitch など)にドキュメントがあります。
詳細はチャネルインデックス チャネル を参照してください。
グループチャットのメンション制限
グループメッセージはデフォルトで メンションを必須 とします(メタデータのメンションまたは正規表現パターン)。これは WhatsApp, Telegram, Discord, Google Chat, iMessage のグループチャットに適用されます。 メンションの種類:- メタデータのメンション: プラットフォーム固有の @メンション。WhatsApp のセルフチャットモードでは無視されます。
- テキストパターン:
agents.list[].groupChat.mentionPatternsで定義された正規表現パターン。常にチェックされます。 - メンション制限は、検出が可能な場合(ネイティブメンションまたは少なくとも 1 つのテキストパターンが存在する場合)にのみ適用されます。
messages.groupChat.historyLimit はグローバルなデフォルトを設定します。チャネルごとに channels.<channel>.historyLimit(またはアカウントごと)でオーバーライド可能です。0 に設定すると履歴は保持されません。
DM 履歴の制限
telegram, whatsapp, discord, slack, signal, imessage, msteams。
セルフチャットモード
allowFrom に自身の番号を含めることで、セルフチャットモードを有効にできます(ネイティブの @メンションを無視し、テキストパターンにのみ応答します)。
コマンド (チャット内のコマンド処理)
コマンドの詳細
コマンドの詳細
- テキストコマンドは、先頭に
/が付いた 単独の メッセージである必要があります。 native: "auto"は Discord/Telegram では有効、Slack では無効のままにします。- チャネルごとのオーバーライド:
channels.discord.commands.native(ブール値または"auto")。falseは登録済みのコマンドをクリアします。 channels.telegram.customCommandsは Telegram のボットメニュー項目を追加します。bash: trueは、ホストシェルの! <cmd>を有効にします。tools.elevated.enabledと、チャネルごとのtools.elevated.allowFrom.<channel>による許可が必要です。config: trueは/config(openclaw.jsonの読み書き)を有効にします。ゲートウェイのchat.sendクライアントにおいて、永続的な/config set|unsetを行うにはoperator.admin権限も必要です。読み取り専用の/config showは、通常の書き込み権限を持つオペレータークライアントでも利用可能です。channels.<provider>.configWritesは、チャネル経由での構成変更をゲート(制限)します(デフォルト: true)。allowFromはプロバイダーごとに設定可能です。これが設定されている場合、それが 唯一の 認証ソースとなります(チャネルの許可リスト/ペアリングやuseAccessGroupsは無視されます)。
エージェントのデフォルト設定
agents.defaults.workspace
デフォルト: ~/.openclaw/workspace。
agents.defaults.repoRoot
システムプロンプトの Runtime 行に表示されるオプションのリポジトリルート。未設定の場合、OpenClaw はワークスペースから上位ディレクトリに向かって自動検出します。
agents.defaults.skipBootstrap
ワークスペースのブートストラップファイル(AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md)の自動作成を無効にします。
agents.defaults.bootstrapMaxChars
ワークスペースの各ブートストラップファイルが切り詰められる前の最大文字数。デフォルト: 20000。
agents.defaults.bootstrapTotalMaxChars
すべてのワークスペースブートストラップファイルから注入される合計最大文字数。デフォルト: 150000。
agents.defaults.bootstrapPromptTruncationWarning
ブートストラップコンテキストが切り詰められた際に、エージェントに表示される警告テキストを制御します。
デフォルト: "once"。
"off": システムプロンプトに警告テキストを注入しません。"once": 切り捨てのパターン(署名)ごとに 1 回だけ警告を注入します(推奨)。"always": 切り捨てが存在する場合、実行ごとに警告を注入します。
agents.defaults.imageMaxDimensionPx
プロバイダー呼び出し前の、ログやツール画像ブロック内の画像の長辺の最大ピクセルサイズ。
デフォルト: 1200。
低い値を設定するとビジョントークンの消費を抑えられ、スクリーンショットを多用する実行時のペイロードサイズを削減できます。
高い値を設定すると、より多くの視覚的詳細が保持されます。
agents.defaults.userTimezone
システムプロンプトのコンテキストに使用されるタイムゾーン(メッセージのタイムスタンプではありません)。未設定の場合はホストのタイムゾーンが使用されます。
agents.defaults.timeFormat
システムプロンプト内の時刻形式。デフォルト: auto (OS の設定に従う)。
agents.defaults.model
model: 文字列 ("provider/model") またはオブジェクト ({ primary, fallbacks }) を指定します。- 文字列形式はメインモデルのみを設定します。
- オブジェクト形式は、メインモデルと順序付けられたフェイルオーバー用モデルを設定します。
imageModel: 文字列 ("provider/model") またはオブジェクト ({ primary, fallbacks }) を指定します。imageツールのビジョンモデル構成として使用されます。- また、選択されたモデルが画像入力を受け付けない場合のフォールバックルーティングとしても使用されます。
pdfModel: 文字列 ("provider/model") またはオブジェクト ({ primary, fallbacks }) を指定します。pdfツールのモデルルーティングに使用されます。- 省略された場合、PDF ツールは
imageModelにフォールバックし、さらにプロバイダーのデフォルトへとフォールバックします。
pdfMaxBytesMb: 呼び出し時にmaxBytesMbが渡されない場合の、pdfツールのデフォルト PDF サイズ制限。pdfMaxPages:pdfツールのテキスト抽出フォールバックモードで処理されるデフォルトの最大ページ数。model.primary:provider/model形式(例:anthropic/claude-opus-4-6)。プロバイダーを省略した場合、OpenClaw はanthropic(非推奨) とみなします。models:/modelコマンドで利用可能なモデルカタログと許可リスト。各エントリにはalias(ショートカット)やparams(temperature,maxTokens,cacheRetentionなどのプロバイダー固有パラメータ)を含めることができます。paramsのマージ優先順位:agents.defaults.models["provider/model"].paramsがベースとなり、agents.list[].params(エージェント ID が一致する場合) でキーごとに上書きされます。- これらのフィールドを変更するコマンド(
/models set,/models set-imageなど)は、可能な限り正規のオブジェクト形式を維持し、既存のフォールバックリストを保持します。 maxConcurrent: セッションをまたいで並列実行できるエージェントの最大数(各セッション内は依然として直列実行されます)。デフォルト: 1。
agents.defaults.models に含まれる場合に適用):
| エイリアス | モデル名 |
|---|---|
opus | anthropic/claude-opus-4-6 |
sonnet | anthropic/claude-sonnet-4-6 |
gpt | openai/gpt-5.4 |
gpt-mini | openai/gpt-5-mini |
gemini | google/gemini-3.1-pro-preview |
gemini-flash | google/gemini-3-flash-preview |
gemini-flash-lite | google/gemini-3.1-flash-lite-preview |
--thinking off を設定するか、agents.defaults.models["zai/<model>"].params.thinking を明示的に定義しない限り、思考モードが自動的に有効になります。
Z.AI モデルはデフォルトでツール呼び出しのストリーミング (tool_stream) が有効です。無効にするには false を設定してください。
Anthropic Claude 4.6 モデルは、明示的な思考レベルが設定されていない場合、デフォルトで adaptive 思考になります。
agents.defaults.cliBackends
テキストのみのフォールバック実行(ツール呼び出しなし)用のオプションの CLI バックエンド。API プロバイダーがダウンした場合のバックアップとして有用です。
- CLI バックエンドはテキスト専用であり、ツールは常に無効になります。
sessionArgが設定されている場合、セッションがサポートされます。imageArgがファイルパスを受け付ける場合、画像のパススルーがサポートされます。
agents.defaults.heartbeat
定期的な心跳(ハートビート)の実行設定。
every: 間隔を表す文字列 (ms/s/m/h)。デフォルト:30m。suppressToolErrorWarnings: true の場合、ハートビート実行中のツールエラー警告を抑制します。directPolicy: 直接送信/DM のポリシー。allow(デフォルト) は直接ターゲットへの配信を許可します。blockは配信を抑制し、reason=dm-blockedを発行します。lightContext: true の場合、軽量なブートストラップコンテキストを使用し、ワークスペースファイルからHEARTBEAT.mdのみを保持します。- エージェントごとの設定:
agents.list[].heartbeatを設定します。いずれかのエージェントでheartbeatが定義されている場合、そのエージェントのみがハートビートを実行します。 - ハートビートはエージェントのフルターンを実行するため、間隔が短いほどトークンを多く消費します。
agents.defaults.compaction
mode:defaultまたはsafeguard(長い履歴向けのチャンク化された要約)。詳細は コンパクション(圧縮) を参照してください。identifierPolicy:strict(デフォルト),off, またはcustom。strictは要約中に識別子を保持するためのガイドラインを付加します。identifierInstructions:identifierPolicy=customの場合に使用されるカスタムテキスト。postCompactionSections: 圧縮後に再注入するAGENTS.md内の H2/H3 セクション名のリスト。デフォルトは["Session Startup", "Red Lines"]です。空の配列[]を指定すると再注入が無効になります。未設定またはデフォルト値の場合、古いEvery Session/Safety見出しも互換性のために受け入れられます。model: 圧縮要約のみに使用するオプションのモデル。メインセッションとは別のモデルで要約を行いたい場合に使用します。未設定の場合はセッションのメインモデルが使用されます。memoryFlush: 自動コンパクションの前に、エージェントが記憶を保存するためのサイレントなターンを実行します。ワークスペースが読み取り専用の場合はスキップされます。
agents.defaults.contextPruning
LLM へ送信する前に、メモリ内のコンテキストから 古いツールの実行結果 を削除します。ディスク上のセッション履歴は 変更されません。
cache-ttl モードの動作
cache-ttl モードの動作
mode: "cache-ttl"はプルーニング(削減)パスを有効にします。ttlは、プルーニングを再実行するまでの頻度(最後にキャッシュに触れてからの経過時間)を制御します。- プルーニングは、まずサイズ超過したツールの結果を「ソフトトリム」し、必要に応じて古いツールの結果を「ハードクリア」します。
... で置き換えます。ハードクリア (Hard-clear) は、ツールの結果全体をプレースホルダーテキストに置き換えます。注意点:- 画像ブロックはトリミングや消去の対象になりません。
- 比率はトークン数ではなく、文字数に基づいた概算値です。
- アシスタントのメッセージ数が
keepLastAssistants未満の場合、プルーニングはスキップされます。
ブロックストリーミング (Block streaming)
- Telegram 以外のチャネルでブロック返信を有効にするには、明示的に
*.blockStreaming: trueを設定する必要があります。 - チャネルごとのオーバーライド:
channels.<channel>.blockStreamingCoalesce(およびアカウントごとのバリアント)。Signal/Slack/Discord/Google Chat のデフォルトはminChars: 1500です。 humanDelay: ブロック返信の間のランダムな一時停止。natural= 800〜2500ms。エージェントごとのオーバーライドはagents.list[].humanDelayです。
タイピングインジケーター
- デフォルト値: ダイレクトチャットやメンション時は
instant、メンションされていないグループチャット時はmessage。 - セッションごとのオーバーライド:
session.typingMode,session.typingIntervalSeconds。
agents.defaults.sandbox
埋め込みエージェント用のオプションの Docker サンドボックス 設定。詳細は サンドボックス を参照してください。
サンドボックスの詳細
サンドボックスの詳細
agents.list (エージェントごとのオーバーライド)
id: 固定のエージェント ID (必須)。default: 複数が設定されている場合、最初のものが優先されます(ログに警告が出ます)。未設定の場合、リストの最初のエントリがデフォルトになります。model: 文字列形式はprimaryのみを上書きします。オブジェクト形式{ primary, fallbacks }は両方を上書きします([]を指定するとグローバルフォールバックが無効になります)。メインモデルのみを上書きする Cron ジョブなどは、fallbacks: []を指定しない限りデフォルトのフォールバック設定を継承します。params:agents.defaults.modelsで選択されたモデルエントリにマージされる、エージェントごとのストリームパラメータ。モデルカタログ全体を複製することなく、cacheRetention,temperature,maxTokensなどのエージェント固有の上書きを行いたい場合に使用します。runtime: オプションのエージェントごとのランタイム記述子。エージェントがデフォルトで ACP ハーネスセッションを使用する場合は、type: "acp"をruntime.acpのデフォルト値(agent,backend,mode,cwd)と共に指定します。identity.avatar: ワークスペースの相対パス、http(s)URL、またはdata:URI。identityはデフォルト値を導出します:emojiからackReaction、name/emojiからmentionPatterns。subagents.allowAgents:sessions_spawnで許可するエージェント ID のリスト(["*"]はすべて許可。デフォルトは自身のエージェントのみ)。- サンドボックス継承ガード: 要求元セッションがサンドボックス化されている場合、
sessions_spawnはサンドボックスなしで実行されるターゲットを拒否します。
マルチエージェントルーティング
1つのゲートウェイ内で、複数の分離されたエージェントを実行します。詳細は マルチエージェント を参照してください。バインディングの一致フィールド
type(オプション): 通常のルーティングはroute(省略時のデフォルト)、永続的な ACP 会話バインディングはacp。match.channel(必須)match.accountId(オプション:*はすべてのアカウントに一致。省略時はデフォルトアカウント)match.peer(オプション:{ kind: direct|group|channel, id })match.guildId/match.teamId(オプション: チャネル固有)acp(オプション:type: "acp"の場合のみ):{ mode, label, cwd, backend }
match.peermatch.guildIdmatch.teamIdmatch.accountId(正確な一致。ピア/ギルド/チーム指定なし)match.accountId: "*"(チャネル全体)- デフォルトエージェント
bindings リストで最初に一致したエントリが優先されます。
type: "acp" のエントリについては、会話の ID(チャネル + アカウント + ピア ID)による正確な一致で解決され、上記のルーティング階層の順序は使用されません。
エージェントごとのアクセスプロファイル
フルアクセス (サンドボックスなし)
フルアクセス (サンドボックスなし)
読み取り専用ツール + ワークスペース
読み取り専用ツール + ワークスペース
ファイルシステムへのアクセスなし (メッセージングのみ)
ファイルシステムへのアクセスなし (メッセージングのみ)
セッション
セッションフィールドの詳細
セッションフィールドの詳細
dmScope: DM をどのようにグループ化するか。main: すべての DM がメインセッションを共有。per-peer: チャネルをまたいで送信者 ID ごとに分離。per-channel-peer: チャネルと送信者の組み合わせごとに分離(マルチユーザーの受信トレイに推奨)。per-account-channel-peer: アカウント、チャネル、送信者の組み合わせごとに分離(マルチアカウント運用に推奨)。
identityLinks: 正規の ID をプロバイダーのプレフィックス付きピアにマップし、チャネルを越えてセッションを共有。reset: 主要なリセットポリシー。dailyは現地時間のatHourに、idleはidleMinutes経過後にリセット。両方設定されている場合は先に到達した方が優先されます。resetByType: タイプごとのオーバーライド(direct,group,thread)。レガシーなdmはdirectのエイリアスとして扱われます。parentForkMaxTokens: スレッドセッションをフォークする際に許可される親セッションの最大totalTokens(デフォルト100000)。- 親のトークン数がこの値を超えている場合、履歴を継承せずに新しいスレッドセッションを開始します。
0を設定するとこの制限が無効になり、常にフォークを試みます。
mainKey: レガシーフィールド。ランタイムは現在、メインのダイレクトチャットバケットに常に"main"を使用します。sendPolicy:channel,chatType(direct|group|channel),keyPrefix,rawKeyPrefixによる一致判定。最初にマッチしたdenyルールが適用されます。maintenance: セッションストアのクリーンアップと保持制御。mode:warnは警告のみ、enforceは実際にクリーンアップを適用。pruneAfter: 古いエントリの削除期限(デフォルト30d)。maxEntries:sessions.jsonの最大エントリ数(デフォルト500)。rotateBytes: このサイズを超えたらsessions.jsonをローテーション(デフォルト10mb)。resetArchiveRetention:*.reset.<timestamp>トランスクリプトアーカイブの保持期間。デフォルトはpruneAfterと同じ。falseで無効化。maxDiskBytes: セッションディレクトリのディスク予算。warnモードでは警告をログ出力し、enforceモードでは古いセッションから順に削除。highWaterBytes: 予算制限後のクリーンアップ目標。デフォルトはmaxDiskBytesの 80%。
threadBindings: スレッドバインドセッション機能のグローバルデフォルト。enabled: 全体スイッチ(プロバイダーごとに上書き可能。Discord はchannels.discord.threadBindings.enabledを使用)。idleHours: 非アクティブ時の自動フォーカス解除時間(デフォルト。0で無効。プロバイダーごとに上書き可能)。maxAgeHours: 最大存続時間(デフォルト。0で無効。プロバイダーごとに上書き可能)。
メッセージ
応答プレフィックス (Response prefix)
チャネル/アカウントごとのオーバーライド:channels.<channel>.responsePrefix, channels.<channel>.accounts.<id>.responsePrefix。
解決順序(最も具体的なものが優先): アカウント → チャネル → グローバル。"" を設定すると継承が停止します。"auto" は [{identity.name}] を使用します。
テンプレート変数:
| 変数名 | 説明 | 例 |
|---|---|---|
{model} | 短いモデル名 | claude-opus-4-6 |
{modelFull} | 完全なモデル識別子 | anthropic/claude-opus-4-6 |
{provider} | プロバイダー名 | anthropic |
{thinkingLevel} | 現在の思考レベル | high, low, off |
{identity.name} | エージェントの名前 | ("auto" と同じ) |
{think} は {thinkingLevel} の短縮形です。
確認リアクション (Ack reaction)
- デフォルトはアクティブなエージェントの
identity.emoji、未設定なら"👀"。""で無効化。 - チャネル/アカウントごとのオーバーライド:
channels.<channel>.ackReaction,channels.<channel>.accounts.<id>.ackReaction。 - 解決順序: アカウント → チャネル →
messages.ackReaction→ アイデンティティのフォールバック。 - スコープ:
group-mentions(デフォルト),group-all,direct,all。 removeAckAfterReply: 返信後にリアクションを削除(Slack/Discord/Telegram/Google Chat のみ)。
インバウンドデバウンス (Inbound debounce)
同じ送信者からの連続したテキストメッセージを 1 つのエージェントターンにまとめます。メディアや添付ファイルは即座に処理されます。制御コマンドはデバウンスをバイパスします。TTS (テキスト読み上げ)
auto: 自動 TTS を制御。/tts off|always|inbound|taggedでセッションごとに変更可能。summaryModel: 自動要約用のモデル。agents.defaults.model.primaryを上書きします。modelOverrides: デフォルトで有効。modelOverrides.allowProviderのデフォルトはfalse(オプトイン)です。- API キーは
ELEVENLABS_API_KEY/XI_API_KEYまたはOPENAI_API_KEY環境変数にフォールバックします。 openai.baseUrl: OpenAI TTS エンドポイントを上書き。解決順序は 構成 >OPENAI_TTS_BASE_URL>https://api.openai.com/v1。openai.baseUrlが非 OpenAI エンドポイントを指している場合、OpenClaw はそれを互換サーバーとして扱い、バリデーションを緩和します。
話す (トークモード)
macOS/iOS/Android のトークモードのデフォルト設定。- 音声 ID は
ELEVENLABS_VOICE_IDまたはSAG_VOICE_ID環境変数にフォールバックします。 apiKeyおよびproviders.*.apiKeyはプレーンテキストまたは SecretRef オブジェクトを受け入れます。ELEVENLABS_API_KEYへのフォールバックは、Talk 構成にキーが設定されていない場合にのみ適用されます。voiceAliases: トークディレクティブでフレンドリーな名称を使用できるようにします。silenceTimeoutMs: ユーザーが話をやめてから送信を開始するまでの待機時間。未設定の場合はプラットフォームのデフォルト(macOS/Android: 700ms, iOS: 900ms)が使用されます。
ツール (Tools)
ツールプロファイル
tools.profile は、tools.allow/tools.deny が適用される前の基本的なホワイトリストを設定します。
オンボーディング時に未設定の場合、新規のローカル構成ではデフォルトで tools.profile: "coding" に設定されます(既存のプロファイルは保持されます)。
| プロファイル | 含まれるツール |
|---|---|
minimal | session_status のみ |
coding | group:fs, group:runtime, group:sessions, group:memory, image |
messaging | group:messaging, sessions_list, sessions_history, sessions_send, session_status |
full | 制限なし(未設定と同じ) |
ツールグループ
| グループ名 | ツール |
|---|---|
group:runtime | exec, process (bash は exec のエイリアスとして許可) |
group:fs | read, write, edit, apply_patch |
group:sessions | sessions_list, sessions_history, sessions_send, sessions_spawn, session_status |
group:memory | memory_search, memory_get |
group:web | web_search, web_fetch |
group:ui | browser, canvas |
group:automation | cron, gateway |
group:messaging | message |
group:nodes | nodes |
group:openclaw | すべての組み込みツール(プロバイダープラグインを除く) |
tools.allow / tools.deny
ツール許可/拒否のグローバルポリシー(拒否が優先)。大文字小文字を区別せず、* ワイルドカードをサポートします。Docker サンドボックスが無効でも適用されます。
tools.byProvider
特定のプロバイダーやモデルに対して、さらにツールを制限します。適用順序: 基本プロファイル → プロバイダープロファイル → 許可/拒否設定。
tools.elevated
昇格された権限(ホスト上での実行)を制御します。
- エージェントごとのオーバーライド(
agents.list[].tools.elevated)は、グローバル設定をより厳しくすることのみ可能です。 /elevated on|off|ask|fullはセッションごとに状態を保存します。インラインディレクティブは単一のメッセージに適用されます。- 昇格された
execはホスト上で直接実行され、サンドボックスをバイパスします。
tools.exec
tools.loopDetection (ループ検出)
ツールループの安全性チェックは デフォルトで無効 です。有効にするには enabled: true を設定してください。
設定は tools.loopDetection でグローバルに定義でき、agents.list[].tools.loopDetection でエージェントごとに上書き可能です。
historySize: ループ分析のために保持されるツール呼び出し履歴の最大数。warningThreshold: 進行のないパターンの繰り返しに対する警告しきい値。criticalThreshold: クリティカルなループをブロックするための、より高い繰り返ししきい値。globalCircuitBreakerThreshold: 進行のない実行を強制停止するためのハードしきい値。detectors.genericRepeat: 同じツールや引数での繰り返し呼び出しを警告。detectors.knownPollNoProgress: 既知のポーリングツール(process.poll,command_statusなど)を警告/ブロック。detectors.pingPong: 交互に繰り返される進行のないペアパターンを警告/ブロック。warningThreshold >= criticalThresholdまたはcriticalThreshold >= globalCircuitBreakerThresholdの場合はバリデーションエラーになります。
tools.web
tools.media
受信メディア(画像、音声、動画)の解析設定です。
メディアモデルのエントリフィールド
メディアモデルのエントリフィールド
プロバイダーエントリ (
type: "provider" または省略時):provider: API プロバイダー ID (openai,anthropic,google/gemini,groqなど)。model: モデル ID のオーバーライド。profile/preferredProfile:auth-profiles.json内のプロファイル選択。
type: "cli"):command: 実行するコマンド名。args: テンプレート引数({{MediaPath}},{{Prompt}},{{MaxChars}}などをサポート)。
capabilities: 対応機能のリスト (image,audio,video)。デフォルト設定:openai/anthropic/minimaxは画像、googleは画像・音声・動画、groqは音声。prompt,maxChars,maxBytes,timeoutSeconds,language: エントリごとのオーバーライド。- 失敗した場合はリスト内の次のエントリへフォールバックします。
auth-profiles.json → 環境変数 → models.providers.*.apiKey の順で解決されます。tools.agentToAgent
tools.sessions
セッション操作ツール(sessions_list, sessions_history, sessions_send)が対象にできる範囲を制御します。
デフォルト: tree(現在のセッションと、そこから生成されたサブエージェントなどのセッション)。
self: 現在のセッションのみ。tree: 現在のセッションと、そのセッションから派生したすべてのセッション。agent: 現在のエージェント ID に属するすべてのセッション。all: すべてのセッション。エージェントをまたぐ場合はtools.agentToAgentの許可も必要です。- サンドボックスの制限: セッションがサンドボックス化されており、
agents.defaults.sandbox.sessionToolsVisibility="spawned"が設定されている場合、この設定がallであっても強制的にtreeに制限されます。
tools.sessions_spawn
sessions_spawn におけるインライン添付ファイルのサポートを制御します。
- 添付ファイルは
runtime: "subagent"でのみサポートされます。ACP ランタイムでは拒否されます。 - ファイルは子ワークスペースの
.openclaw/attachments/<uuid>/に配置されます。 - 添付ファイルの内容は、ログの永続化時に自動的に伏せ字(redact)処理されます。
- Base64 入力は厳密にチェックされ、デコード前のサイズ制限が適用されます。
- ファイル権限はディレクトリが
0700、ファイルが0600に設定されます。 - クリーンアップは
cleanupポリシーに従います。deleteは常に削除し、keepはretainOnSessionKeep: trueの場合のみ保持します。
tools.subagents
model: 生成されるサブエージェントのデフォルトモデル。省略時は呼び出し元のモデルを継承します。runTimeoutSeconds: ツール呼び出しで指定されなかった場合のデフォルトタイムアウト。0は無制限を意味します。- サブエージェントごとのツールポリシー:
tools.subagents.tools.allow/tools.subagents.tools.denyで設定します。
カスタムプロバイダーとベース URL
OpenClaw は pi-coding-agent のモデルカタログを使用します。構成ファイルのmodels.providers または ~/.openclaw/agents/<agentId>/agent/models.json を通じてカスタムプロバイダーを追加できます。
- 特殊な認証が必要な場合は
authHeader: trueとheadersを組み合わせて使用します。 - エージェント設定のルートディレクトリは
OPENCLAW_AGENT_DIR環境変数で変更可能です。 - プロバイダー ID が一致する場合のマージ優先順位:
- エージェント個別の
models.json内のbaseUrlが最優先されます。 apiKeyは、そのプロバイダーが SecretRef で管理されていない場合にのみ優先されます。- 空または欠落している項目は、メイン構成の
models.providersにフォールバックします。 contextWindow/maxTokensは、明示的な設定値とカタログ値のうち高い方が採用されます。models.mode: "replace"を使用すると、カタログをマージせずに構成ファイルの内容で完全に置き換えます。
- エージェント個別の
プロバイダーフィールドの詳細
models.mode: カタログの動作 (mergeまたはreplace)。models.providers: プロバイダー ID をキーとするカスタムプロバイダーのマップ。models.providers.*.api: リダプターの種類 (openai-completions,openai-responses,anthropic-messages,google-generative-aiなど)。models.providers.*.apiKey: 認証情報(SecretRef や環境変数参照を推奨)。models.providers.*.auth: 認証戦略 (api-key,token,oauth,aws-sdk)。models.providers.*.injectNumCtxForOpenAICompat: Ollama 等でoptions.num_ctxを注入するかどうか (デフォルト:true)。models.providers.*.baseUrl: アップストリームの API ベース URL。models.providers.*.headers: プロキシやルーティング用の追加ヘッダー。models.providers.*.models: プロバイダーごとの明示的なモデルカタログ。models.providers.*.models.*.compat.supportsDeveloperRole:api: "openai-completions"でbaseUrlがapi.openai.com以外の場合、OpenClaw はこれを強制的にfalseに設定して互換性を確保します。models.bedrockDiscovery: Bedrock 自動検出の設定。enabled: 検出の有効/無効。region: AWS リージョン。providerFilter: 特定のプロバイダー ID で絞り込むオプション。refreshInterval: 検出の更新間隔。defaultContextWindow/defaultMaxTokens: 検出されたモデルのフォールバック値。
プロバイダーの例
Cerebras (GLM 4.6 / 4.7)
Cerebras (GLM 4.6 / 4.7)
cerebras/zai-glm-4.7 を、Z.AI 直販を使用する場合は zai/glm-4.7 を使用します。OpenCode Zen
OpenCode Zen
OPENCODE_API_KEY (または OPENCODE_ZEN_API_KEY) を設定してください。ショートカット: openclaw onboard --auth-choice opencode-zen。Z.AI (GLM-4.7)
Z.AI (GLM-4.7)
ZAI_API_KEY を設定してください。z.ai/* や z-ai/* もエイリアスとして受け入れられます。ショートカット: openclaw onboard --auth-choice zai-api-key。- 一般的なエンドポイント:
https://api.z.ai/api/paas/v4 - コーディング用エンドポイント (デフォルト):
https://api.z.ai/api/coding/paas/v4 - 一般的なエンドポイントを使用する場合は、ベース URL を上書きしてカスタムプロバイダーを定義してください。
Moonshot AI (Kimi)
Moonshot AI (Kimi)
baseUrl: "https://api.moonshot.cn/v1" または openclaw onboard --auth-choice moonshot-api-key-cn。Kimi Coding
Kimi Coding
openclaw onboard --auth-choice kimi-code-api-key。Synthetic (Anthropic 互換)
Synthetic (Anthropic 互換)
/v1 を除外する必要があります(Anthropic クライアントが自動付加します)。ショートカット: openclaw onboard --auth-choice synthetic-api-key。MiniMax M2.5 (直接利用)
MiniMax M2.5 (直接利用)
MINIMAX_API_KEY を設定してください。ショートカット: openclaw onboard --auth-choice minimax-api。ローカルモデル (LM Studio)
ローカルモデル (LM Studio)
ローカルモデル を参照してください。要約: ハイスペックなハードウェア上の LM Studio Responses API 経由で MiniMax M2.5 を実行し、フォールバック用にクラウド版をマージしておきます。
スキル (Skills)
allowBundled: 同梱されているスキルのみを許可するオプションのホワイトリスト(管理済み/ワークスペーススキルには影響しません)。entries.<skillKey>.enabled: false: 同梱またはインストールされているスキルを無効化します。entries.<skillKey>.apiKey: 主要な環境変数を宣言するための便利なフィールド(プレーンテキストまたは SecretRef)。
プラグイン (Plugins)
~/.openclaw/extensions,<workspace>/.openclaw/extensions, およびplugins.load.pathsからロードされます。- 構成を変更した場合はゲートウェイの再起動が必要です。
allow: 許可リスト(リストにないプラグインはロードされません)。denyが優先されます。plugins.entries.<id>.apiKey: プラグイン固有の API キー用フィールド(プラグインが対応している場合)。plugins.entries.<id>.env: プラグインスコープの環境変数マップ。plugins.entries.<id>.hooks.allowPromptInjection:falseの場合、before_prompt_buildによるプロンプト変更をブロックし、レガシーなbefore_agent_startからのプロンプト変更フィールドを無視します(modelOverrideやproviderOverrideは維持されます)。plugins.entries.<id>.config: プラグインが定義する設定オブジェクト(プラグインのスキーマで検証されます)。plugins.slots.memory: 使用するメモリプラグインの ID を指定。無効にする場合は"none"を指定します。plugins.slots.contextEngine: 使用するコンテキストエンジンプラグインの ID。デフォルトは"legacy"です。plugins.installs:openclaw plugins update等で使用される CLI 管理のインストール用メタデータ。source,spec,version,integrity等が含まれます。これらは CLI によって自動管理されるため、手動編集は避けてください。
ブラウザ (Browser)
evaluateEnabled: false:act:evaluateやwait --fnを無効化します。ssrfPolicy.dangerouslyAllowPrivateNetwork: 未設定時はデフォルトでtrue(信頼されたネットワークモデル)。パブリックな Web 閲覧のみに制限したい場合はfalseに設定してください。ssrfPolicy.allowPrivateNetworkもレガシーエイリアスとしてサポートされます。- 制限モードでは、
hostnameAllowlistやallowedHostnamesで例外を定義できます。 - リモートプロファイルは接続専用です(開始/停止/リセットは不可)。
- 自動検出順序: Chromium ベースのデフォルトブラウザ → Chrome → Brave → Edge → Chromium → Chrome Canary。
- 制御サービス: ループバックのみ(ポートは
gateway.portから派生。デフォルトは18791)。 extraArgs: 起動時の追加フラグ(GPU 無効化、ウィンドウサイズ指定、デバッグフラグ等)。relayBindHost: Chrome 拡張機能のリレーがリッスンするアドレス。ループバックのみの場合は未設定のままにしてください。名前空間の境界(WSL2 等)を越える必要があり、かつホストネットワークが信頼できる場合のみ0.0.0.0等を設定してください。
UI
seamColor: ネイティブアプリの UI アクセントカラー(トークモードのバブルの色など)。assistant: コントロール UI におけるアイデンティティのオーバーライド。未設定時はアクティブなエージェントのアイデンティティが使用されます。
ゲートウェイ (Gateway)
ゲートウェイフィールドの詳細
ゲートウェイフィールドの詳細
mode:local(ゲートウェイを実行) またはremote(リモートゲートウェイに接続)。localでない限りゲートウェイは起動しません。port: WebSocket と HTTP で共用される単一のポート。優先順位:--port引数 >OPENCLAW_GATEWAY_PORT>gateway.port>18789。bind:auto,loopback(デフォルト),lan(0.0.0.0),tailnet(Tailscale IP のみ), またはcustom。- レガシーなバインドエイリアス:
gateway.bindにはホストのエイリアス(0.0.0.0,127.0.0.1等)ではなく、上記のバインドモード値を指定してください。 - Docker に関する注意: デフォルトの
loopbackはコンテナ内の127.0.0.1でリッスンします。Docker のブリッジネットワーク(-p 18789:18789)を使用する場合、トラフィックはeth0に到達するため、ゲートウェイにアクセスできなくなります。--network hostを使用するか、bind: "lan"(またはbind: "custom"かつcustomBindHost: "0.0.0.0")を設定してすべてのインターフェースでリッスンするようにしてください。 - 認証 (Auth): デフォルトで必須です。ループバック以外のバインドには共通のトークン/パスワードが必要です。オンボーディングウィザードはデフォルトでトークンを生成します。
gateway.auth.tokenとgateway.auth.passwordの両方が構成されている場合(SecretRef を含む)、gateway.auth.modeを明示的にtokenまたはpasswordに設定してください。モードが未設定で両方が存在する場合、起動やサービスのインストール/修復に失敗します。gateway.auth.mode: "none": 明示的な無認証モード。信頼されたローカルループバック環境でのみ使用してください。オンボーディングのプロンプトでは意図的に提供されません。gateway.auth.mode: "trusted-proxy": 認証を ID 認識リバースプロキシに委任し、gateway.trustedProxiesからの ID ヘッダーを信頼します(信頼されたプロキシ認証 を参照)。gateway.auth.allowTailscale:trueの場合、Tailscale Serve の ID ヘッダーをコントロール UI/WebSocket の認証に使用できます(tailscale whoisで検証)。HTTP API エンドポイントには引き続きトークン/パスワード認証が必要です。このトークンレスフローは、ゲートウェイホストが信頼されていることを前提としています。tailscale.mode = "serve"の場合はデフォルトでtrueになります。gateway.auth.rateLimit: オプションの認証失敗リミッター。クライアント IP ごと、および認証スコープ(共通シークレットとデバイス用トークンは個別に追跡)ごとに適用されます。ブロックされた試行は429(Retry-After 付き) を返します。gateway.auth.rateLimit.exemptLoopback: デフォルトはtrueです。テスト環境や厳格なプロキシ運用のためにローカルホストからのトラフィックも制限したい場合はfalseに設定してください。
- ブラウザをオリジンとする WebSocket 認証の試行は、常にデバウンスが有効な状態でスロットル制限されます(ブラウザベースのローカルホストへのブルートフォース攻撃に対する多層防御のため)。
tailscale.mode:serve(Tailnet 内のみ、ループバックバインド) またはfunnel(公開、認証必須)。controlUi.allowedOrigins: ゲートウェイ WebSocket 接続を許可する明示的なブラウザオリジンのリスト。ループバック以外のオリジンからブラウザクライアントが接続する場合に必要です。controlUi.dangerouslyAllowHostHeaderOriginFallback: Host ヘッダーによるオリジンポリシーに依存するデプロイ環境向けの、Host ヘッダーによる Origin フォールバックを有効にする危険なモードです。remote.transport:ssh(デフォルト) またはdirect(ws/wss)。directの場合、remote.urlはws://またはwss://である必要があります。OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1: クライアント側の非常用オーバーライド設定で、信頼されたプライベートネットワーク IP へのプレーンテキストws://接続を許可します。デフォルトではプレーンテキストはループバックのみに制限されています。gateway.remote.token/.passwordはリモートクライアント用の認証情報フィールドです。これら自体がゲートウェイの認証を構成するものではありません。- ローカルからのゲートウェイ呼び出しにおいて、
gateway.auth.*が未設定の場合、gateway.remote.*がフォールバックとして使用されることがあります。 trustedProxies: TLS を終端するリバースプロキシの IP アドレス。自身が管理するプロキシのみをリストしてください。allowRealIpFallback:trueの場合、X-Forwarded-Forが存在しない場合にX-Real-IPを受け入れます。デフォルトはfalseです(安全側に倒す動作)。gateway.tools.deny: HTTPPOST /tools/invokeでブロックする追加のツール名(デフォルトの拒否リストを拡張)。gateway.tools.allow: デフォルトの HTTP 拒否リストからツール名を除外します。
OpenAI 互換エンドポイント
- チャット完了 (Chat Completions): デフォルトでは無効です。
gateway.http.endpoints.chatCompletions.enabled: trueで有効にします。 - 応答 API (Responses API):
gateway.http.endpoints.responses.enabled。 - 応答 URL 入力の強化:
gateway.http.endpoints.responses.maxUrlPartsgateway.http.endpoints.responses.files.urlAllowlistgateway.http.endpoints.responses.images.urlAllowlist
- オプションの応答強化ヘッダー:
gateway.http.securityHeaders.strictTransportSecurity(自身が管理する HTTPS オリジンに対してのみ設定してください。信頼されたプロキシ認証 を参照)
マルチインスタンスの分離
1つのホスト上で、一意のポートと状態ディレクトリを使用して複数のゲートウェイを実行できます。--dev (~/.openclaw-dev + ポート 19001 を使用)、--profile <name> (~/.openclaw-<name> を使用)。
詳細は マルチゲートウェイ を参照してください。
フック (Hooks)
Authorization: Bearer <token> または x-openclaw-token: <token> ヘッダーを使用します。
エンドポイント:
POST /hooks/wake→{ text, mode?: "now"|"next-heartbeat" }POST /hooks/agent→{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }- リクエストペイロードからの
sessionKeyは、hooks.allowRequestSessionKey=true(デフォルト:false) の場合にのみ受け入れられます。
- リクエストペイロードからの
POST /hooks/<name>→hooks.mappingsを介して解決されます。
マッピングの詳細
マッピングの詳細
match.path:/hooks以降のサブパスに一致します(例:/hooks/gmail→gmail)。match.source: 汎用的なパスに対してペイロード内のフィールドで一致を判定します。{{messages[0].subject}}のようなテンプレートはペイロードから値を読み取ります。transform: フックアクションを返す JS/TS モジュールを指定できます。transform.moduleは相対パスである必要があり、hooks.transformsDir内にある必要があります(絶対パスやディレクトリトラバーサルは拒否されます)。
agentId: 特定のエージェントにルーティングします。未知の ID はデフォルトにフォールバックします。allowedAgentIds: 明示的なルーティングを制限します(*または省略で全許可、[]で全拒否)。defaultSessionKey: 明示的なsessionKeyがないフックエージェント実行用の、オプションの固定セッションキー。allowRequestSessionKey:/hooks/agentの呼び出し元がsessionKeyを設定することを許可します (デフォルト:false)。allowedSessionKeyPrefixes: 明示的なsessionKey値に対するオプションのプレフィックス許可リスト(例:["hook:"])。deliver: true: 最終的な返信をチャネルに送信します。channelはデフォルトでlastになります。model: このフック実行の LLM を上書きします(モデルカタログで許可されている必要があります)。
Gmail 連携
- ゲートウェイは、構成されている場合、起動時に
gog gmail watch serveを自動的に開始します。無効にするにはOPENCLAW_SKIP_GMAIL_WATCHER=1を設定してください。 - ゲートウェイと並行して個別の
gog gmail watch serveを実行しないでください。
キャンバスホスト (Canvas host)
- エージェントが編集可能な HTML/CSS/JS および A2UI を、ゲートウェイのポート経由で HTTP 配信します。
http://<gateway-host>:<gateway.port>/__openclaw__/canvas/http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
- ローカルのみの利用:
gateway.bind: "loopback"(デフォルト) のままにしてください。 - ループバック以外のバインド: キャンバスのルートへのアクセスには、ゲートウェイの他の HTTP 面と同様に認証(トークン/パスワード/信頼されたプロキシ)が必要です。
- ノード上の WebView は通常、認証ヘッダーを送信しません。ノードがペアリングされ接続されると、ゲートウェイはそのノード専用のキャンバス/A2UI アクセス用「機能 URL(Capability URL)」を通知します。
- 機能 URL はアクティブなノードの WS セッションに紐付けられており、短時間で期限切れになります。IP ベースのフォールバックは使用されません。
- 配信される HTML にライブリロード用クライアントを注入します。
- ディレクトリが空の場合、スターター用の
index.htmlを自動生成します。 /__openclaw__/a2ui/で A2UI も配信します。- 設定の変更にはゲートウェイの再起動が必要です。
- 大規模なディレクトリや
EMFILEエラーが発生する場合は、ライブリロードを無効にしてください。
検出 (Discovery)
mDNS (Bonjour)
minimal(デフォルト): TXT レコードからcliPathとsshPortを除外します。full:cliPathとsshPortを含めます。- ホスト名はデフォルトで
openclawになります。OPENCLAW_MDNS_HOSTNAMEで上書き可能です。
広域検出 (DNS-SD)
~/.openclaw/dns/ 配下にユニキャスト DNS-SD ゾーンファイルを書き出します。ネットワークを越えた検出を行うには、DNS サーバー(CoreDNS 推奨)と Tailscale の Split DNS を組み合わせてください。
セットアップ: openclaw dns setup --apply。
環境設定 (Environment)
env (インライン環境変数)
- インライン環境変数は、プロセスの環境変数にそのキーが存在しない場合にのみ適用されます。
.envファイル: カレントディレクトリの.envと~/.openclaw/.envが読み込まれます(既存の変数は上書きしません)。shellEnv: ログインシェルのプロファイルから、不足している期待されるキーをインポートします。- 詳細は 環境設定 を参照してください。
環境変数の置換
構成ファイル内の任意の文字列で${VAR_NAME} の形式で環境変数を参照できます。
- 大文字の名前のみが一致します:
[A-Z_][A-Z0-9_]*。 - 変数が欠落しているか空の場合、構成のロード時にエラーが発生します。
- リテラルとして
${VAR}と記述したい場合は$${VAR}のようにエスケープしてください。 $include内でも動作します。
シークレット (Secrets)
シークレット参照(SecretRef)は加算的です。プレーンテキストの値も引き続き動作します。SecretRef
以下のオブジェクト形式を使用します。
providerパターン:^[a-z][a-z0-9_-]{0,63}$source: "env"の ID パターン:^[A-Z][A-Z0-9_]{0,127}$source: "file"の ID: 絶対パス形式の JSON ポインター(例:"/providers/openai/apiKey")source: "exec"の ID パターン:^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
サポートされている認証情報箇所
- 対応表: SecretRef 対応箇所一覧
secrets applyコマンドは、openclaw.json内のサポートされている認証情報パスを対象にします。auth-profiles.json内の参照も、実行時の解決および監査の対象に含まれます。
シークレットプロバイダーの構成
fileプロバイダーはmode: "json"およびmode: "singleValue"をサポートします(singleValue モードではidを"value"にする必要があります)。execプロバイダーは絶対パスによるcommand指定が必要で、標準入出力を介したプロトコルを使用します。- デフォルトではシンボリックリンクのコマンドパスは拒否されます。
allowSymlinkCommand: trueを設定すると、解決後のターゲットパスを検証した上で許可されます。 trustedDirsが構成されている場合、解決後のターゲットパスに対してチェックが行われます。execで起動される子プロセスの環境変数はデフォルトで最小限です。必要な変数はpassEnvで明示的に渡してください。- シークレットの参照はアクティベーション時にメモリ上のスナップショットへと解決され、以降のリクエストパスではそのスナップショットのみを読み取ります。
- 有効な箇所(Surface)での解決失敗は起動/リロードのエラーとなりますが、無効な箇所にある参照は診断情報と共にスキップされます。
認証情報の保存 (Auth storage)
- エージェントごとのプロファイルは
<agentDir>/auth-profiles.jsonに保存されます。 auth-profiles.jsonは値レベルでの参照(api_key用のkeyRef、token用のtokenRef)をサポートしています。- 実行時の静的な認証情報はメモリ上の解決済みスナップショットから取得されます。従来の静的な
auth.jsonエントリは検出時に削除されます。 - 従来の OAuth インポートは
~/.openclaw/credentials/oauth.jsonから行われます。 - 詳細は OAuth を参照してください。
- シークレットの実行時の動作および
audit/configure/applyツールについては、シークレット管理 を参照してください。
ロギング (Logging)
- デフォルトのログファイル:
/tmp/openclaw/openclaw-YYYY-MM-DD.log。 - 固定のパスを使用したい場合は
logging.fileを設定してください。 --verbose指定時はconsoleLevelがdebugに引き上げられます。
CLI
cli.banner.taglineModeはバナーのタグライン(標語)スタイルを制御します。"random"(デフォルト): 面白いものや季節ごとのタグラインを入れ替えて表示します。"default": 固定の中立的なタグライン(All your chats, one OpenClaw.)を表示します。"off": タグラインを表示しません(バナーのタイトルとバージョンは引き続き表示されます)。
- タグラインだけでなくバナー全体を非表示にするには、環境変数
OPENCLAW_HIDE_BANNER=1を設定してください。
ウィザード (Wizard)
CLI ウィザード(onboard, configure, doctor)によって書き込まれるメタデータです。
アイデンティティ (Identity)
identity.emojiからmessages.ackReaction(未設定なら 👀)identity.name/identity.emojiからmentionPatternsavatarにはワークスペース相対パス、http(s)URL、またはdata:URI を指定可能
ブリッジ (Bridge - レガシー、削除済み)
現在のビルドには TCP ブリッジは含まれていません。ノードはゲートウェイの WebSocket 経由で接続します。bridge.* キーは構成スキーマから削除されています(削除しないと検証エラーになります。openclaw doctor --fix で不明なキーを削除できます)。
旧ブリッジ構成 (歴史的リファレンス)
旧ブリッジ構成 (歴史的リファレンス)
Cron
sessionRetention: 完了した分離 Cron 実行セッションをsessions.jsonから削除するまでの期間。アーカイブされた削除済み Cron ログのクリーンアップも制御します。デフォルトは24hです。無効にするにはfalseを設定します。runLog.maxBytes: 各実行ログファイル (cron/runs/<jobId>.jsonl) がクリーンアップされる前の最大サイズ。runLog.keepLines: 実行ログのクリーンアップ時に保持される最新の行数。webhookToken: Cron Webhook の送信 (delivery.mode = "webhook") に使用される Bearer トークン。省略された場合、認証ヘッダーは送信されません。webhook:notify: trueが設定されたままの古いジョブのために残されている、非推奨のフォールバック用 Webhook URL (http/https)。
メディアモデルのテンプレート変数
tools.media.models[].args 内で展開されるテンプレートプレースホルダーです。
| 変数 | 説明 |
|---|---|
{{Body}} | 受信メッセージの全文 |
{{RawBody}} | 生の本文(履歴や送信者情報を含まない) |
{{BodyStripped}} | 本文からグループメンションを除去したもの |
{{From}} | 送信者識別子 |
{{To}} | 宛先識別子 |
{{MessageSid}} | チャネルにおけるメッセージ ID |
{{SessionId}} | 現在のセッション UUID |
{{IsNewSession}} | 新しいセッションが作成された場合に "true" |
{{MediaUrl}} | 受信メディアの疑似 URL |
{{MediaPath}} | ローカルのメディアパス |
{{MediaType}} | メディアの種類 (image/audio/document/…) |
{{Transcript}} | 音声の書き起こし内容 |
{{Prompt}} | CLI エントリ用に解決されたメディアプロンプト |
{{MaxChars}} | CLI エントリ用に解決された最大出力文字数 |
{{ChatType}} | "direct" または "group" |
{{GroupSubject}} | グループの件名 (ベストエフォート) |
{{GroupMembers}} | グループメンバーのプレビュー (ベストエフォート) |
{{SenderName}} | 送信者の表示名 (ベストエフォート) |
{{SenderE164}} | 送信者の電話番号 (ベストエフォート) |
{{Provider}} | プロバイダーのヒント (whatsapp, telegram, discord など) |
構成のインクルード ($include)
構成を複数のファイルに分割できます。
- 単一ファイル: 含まれているオブジェクトで置き換えます。
- ファイルの配列: 順番にディープマージされます(後のファイルが前のファイルを上書きします)。
- 兄弟キー: インクルード後にマージされます(インクルードされた値を上書きします)。
- ネストされたインクルード: 最大 10 レベルまで。
- パス: インクルード元のファイルを基準に解決されますが、最上位の構成ディレクトリ(
openclaw.jsonのディレクトリ)内にある必要があります。絶対パスや../は、その境界内で解決される場合にのみ許可されます。 - エラー: ファイルの欠落、解析エラー、循環参照に関する明確なメッセージを表示します。
関連: 構成 · 構成例 · ドクター