メインコンテンツへスキップ
~/.openclaw/openclaw.json で使用可能なすべてのフィールドについて説明します。タスク指向の概要については、構成 を参照してください。 構成形式は JSON5 です(コメントや末尾のカンマが許可されます)。すべてのフィールドはオプションです。省略された場合、OpenClaw は安全なデフォルト値を使用します。

チャネル

各チャネルは、その構成セクションが存在すると自動的に開始されます(enabled: false を指定した場合を除く)。

DM とグループへのアクセス

すべてのチャネルは DM ポリシーとグループポリシーをサポートしています。
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 はゲートウェイの Web チャネル(Baileys Web)経由で実行されます。リンクされたセッションが存在する場合、自動的に開始されます。
  • アウトバウンドコマンドは、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 オプションに渡されます(デフォルトはそれぞれ true24)。
  • 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): botTokenappToken の両方が必要です(デフォルトアカウントのフォールバックとして SLACK_BOT_TOKEN + SLACK_APP_TOKEN)。
  • HTTP モード: botTokensigningSecret(ルートまたはアカウントごと)が必要です。
  • configWrites: false は、Slack 主導の構成書き込みをブロックします。
  • オプションの channels.slack.defaultAccount は、構成済みの ID と一致する場合にデフォルトのアカウント選択をオーバーライドします。
  • channels.slack.streaming は標準のストリームモードキーです。従来の streamMode やブール値の streaming は自動的に移行されます。
  • 配信ターゲットには user:<id> (DM) または channel:<id> を使用してください。
反応通知モード: off, own(デフォルト), all, allowlistreactionAllowlist に基づく)。 スレッドセッションの分離: thread.historyScope は、スレッドごと(デフォルト)かチャネル全体で共有するかを選択します。thread.inheritParent を true にすると、親チャネルのログが新しいスレッドにコピーされます。
  • typingReaction: 返信の実行中に、受信した Slack メッセージに一時的なリアクションを追加し、完了時に削除します。"hourglass_flowing_sand" などの Slack 絵文字ショートコードを使用します。

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) を設定してください。
  • attachmentRootsremoteAttachmentRoots は、受信した添付ファイルのパスを制限します(デフォルト: /Users/*/Library/Messages/Attachments)。
  • SCP は厳密なホストキーチェックを行うため、リレーホストのキーが ~/.ssh/known_hosts に存在することを確認してください。
  • channels.imessage.configWrites: iMessage 主導の構成書き込みを許可または拒否します。

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 履歴の制限

解決順序: 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/configopenclaw.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(ショートカット)や paramstemperature, maxTokens, cacheRetention などのプロバイダー固有パラメータ)を含めることができます。
  • params のマージ優先順位: agents.defaults.models["provider/model"].params がベースとなり、agents.list[].params (エージェント ID が一致する場合) でキーごとに上書きされます。
  • これらのフィールドを変更するコマンド(/models set, /models set-image など)は、可能な限り正規のオブジェクト形式を維持し、既存のフォールバックリストを保持します。
  • maxConcurrent: セッションをまたいで並列実行できるエージェントの最大数(各セッション内は依然として直列実行されます)。デフォルト: 1。
組み込みのエイリアス(短縮名) (agents.defaults.models に含まれる場合に適用): ユーザーが構成したエイリアスは常にデフォルトより優先されます。 Z.AI GLM-4.x モデルは、--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, または customstrict は要約中に識別子を保持するためのガイドラインを付加します。
  • identifierInstructions: identifierPolicy=custom の場合に使用されるカスタムテキスト。
  • postCompactionSections: 圧縮後に再注入する AGENTS.md 内の H2/H3 セクション名のリスト。デフォルトは ["Session Startup", "Red Lines"] です。空の配列 [] を指定すると再注入が無効になります。未設定またはデフォルト値の場合、古い Every Session/Safety 見出しも互換性のために受け入れられます。
  • model: 圧縮要約のみに使用するオプションのモデル。メインセッションとは別のモデルで要約を行いたい場合に使用します。未設定の場合はセッションのメインモデルが使用されます。
  • memoryFlush: 自動コンパクションの前に、エージェントが記憶を保存するためのサイレントなターンを実行します。ワークスペースが読み取り専用の場合はスキップされます。

agents.defaults.contextPruning

LLM へ送信する前に、メモリ内のコンテキストから 古いツールの実行結果 を削除します。ディスク上のセッション履歴は 変更されません
  • mode: "cache-ttl" はプルーニング(削減)パスを有効にします。
  • ttl は、プルーニングを再実行するまでの頻度(最後にキャッシュに触れてからの経過時間)を制御します。
  • プルーニングは、まずサイズ超過したツールの結果を「ソフトトリム」し、必要に応じて古いツールの結果を「ハードクリア」します。
ソフトトリム (Soft-trim) は、最初と最後を保持し、中間を ... で置き換えます。ハードクリア (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 サンドボックス 設定。詳細は サンドボックス を参照してください。
ワークスペースへのアクセス (workspaceAccess):
  • none: ~/.openclaw/sandboxes 配下のスコープごとのサンドボックス用ワークスペースを使用。
  • ro: サンドボックス用ワークスペースを /workspace に、エージェントのワークスペースを /agent に読み取り専用でマウント。
  • rw: エージェントのワークスペースを /workspace に読み書き可能でマウント。
スコープ (scope):
  • session: セッションごとに個別のコンテナとワークスペースを作成。
  • agent: エージェントごとに 1 つのコンテナとワークスペースを作成(デフォルト)。
  • shared: すべてで共有のコンテナとワークスペースを使用(セッション間の分離なし)。
setupCommand は、コンテナ作成後に 1 回だけ実行されます(sh -lc 経由)。ネットワークへの外部アクセス権限、書き込み可能なルート、およびルートユーザー権限が必要です。コンテナのネットワークはデフォルトで network: "none" です。エージェントが外部アクセスを必要とする場合は、"bridge"(またはカスタムブリッジネットワーク)に設定してください。"host" はブロックされます。"container:<id>" は、sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true を明示的に設定しない限り、デフォルトでブロックされます。受信した添付ファイル は、アクティブなワークスペースの media/inbound/* に配置されます。docker.binds を使用して、ホスト上の追加ディレクトリをマウントできます。グローバル設定とエージェントごとの設定はマージされます。サンドボックス内ブラウザ (sandbox.browser.enabled): コンテナ内で Chromium と CDP を実行します。noVNC の URL がシステムプロンプトに注入されます。openclaw.json で別途 browser.enabled を設定する必要はありません。 noVNC による閲覧にはデフォルトで VNC 認証が使用されます。OpenClaw は共有 URL にパスワードを直接含める代わりに、短寿命のトークン付き URL を発行します。
  • allowHostControl: false (デフォルト): サンドボックス化されたセッションがホスト側のブラウザを操作することを防ぎます。
  • network: デフォルトは openclaw-sandbox-browser (専用ブリッジネットワーク) です。明示的にグローバルなブリッジ接続が必要な場合にのみ bridge に設定してください。
  • cdpSourceRange: オプションで、コンテナ境界での CDP への流入を CIDR 範囲 (例: 172.21.0.1/32) に制限できます。
  • sandbox.browser.binds: 追加のホストディレクトリをサンドボックスブラウザコンテナにのみマウントします。設定されている場合(空の配列 [] を含む)、ブラウザコンテナについては docker.binds の内容を置き換えます。
  • 起動時のデフォルト設定は scripts/sandbox-browser-entrypoint.sh で定義されており、コンテナホスト向けに最適化されています。
    • --remote-debugging-address=127.0.0.1
    • --remote-debugging-port=<OPENCLAW_BROWSER_CDP_PORT から派生>
    • --user-data-dir=${HOME}/.chrome
    • --no-first-run, --no-default-browser-check
    • --disable-3d-apis, --disable-gpu, --disable-software-rasterizer
    • --disable-dev-shm-usage, --disable-background-networking
    • --disable-features=TranslateUI, --disable-breakpad, --disable-crash-reporter
    • --renderer-process-limit=2
    • --no-zygote, --metrics-recording-only
    • --disable-extensions (デフォルトで有効)
    • 3D/GPU 関連のフラグはデフォルトで有効ですが、WebGL/3D が必要な場合は OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 で無効化できます。
    • 拡張機能が必要な場合は OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 で再有効化できます。
    • プロセス制限は OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> で変更可能です。0 を指定すると Chromium のデフォルト値になります。
    • noSandbox が有効な場合は、--no-sandbox--disable-setuid-sandbox が追加されます。
    • これらの設定はコンテナイメージのベースラインに基づいています。変更したい場合は、カスタムエントリポイントを持つカスタムブラウザイメージを使用してください。
イメージのビルドコマンド:

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 から ackReactionname/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 }
決定的な一致順序:
  1. match.peer
  2. match.guildId
  3. match.teamId
  4. match.accountId (正確な一致。ピア/ギルド/チーム指定なし)
  5. match.accountId: "*" (チャネル全体)
  6. デフォルトエージェント
各階層内では、bindings リストで最初に一致したエントリが優先されます。 type: "acp" のエントリについては、会話の ID(チャネル + アカウント + ピア ID)による正確な一致で解決され、上記のルーティング階層の順序は使用されません。

エージェントごとのアクセスプロファイル

優先順位の詳細については、マルチエージェント サンドボックスとツール を参照してください。

セッション

  • dmScope: DM をどのようにグループ化するか。
    • main: すべての DM がメインセッションを共有。
    • per-peer: チャネルをまたいで送信者 ID ごとに分離。
    • per-channel-peer: チャネルと送信者の組み合わせごとに分離(マルチユーザーの受信トレイに推奨)。
    • per-account-channel-peer: アカウント、チャネル、送信者の組み合わせごとに分離(マルチアカウント運用に推奨)。
  • identityLinks: 正規の ID をプロバイダーのプレフィックス付きピアにマップし、チャネルを越えてセッションを共有。
  • reset: 主要なリセットポリシー。daily は現地時間の atHour に、idleidleMinutes 経過後にリセット。両方設定されている場合は先に到達した方が優先されます。
  • resetByType: タイプごとのオーバーライド(direct, group, thread)。レガシーな dmdirect のエイリアスとして扱われます。
  • 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}] を使用します。 テンプレート変数: 変数は大文字小文字を区別しません。{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" に設定されます(既存のプロファイルは保持されます)。

ツールグループ

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 内のプロファイル選択。
CLI エントリ (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 は常に削除し、keepretainOnSessionKeep: 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: trueheaders を組み合わせて使用します。
  • エージェント設定のルートディレクトリは 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"baseUrlapi.openai.com 以外の場合、OpenClaw はこれを強制的に false に設定して互換性を確保します。
  • models.bedrockDiscovery: Bedrock 自動検出の設定。
    • enabled: 検出の有効/無効。
    • region: AWS リージョン。
    • providerFilter: 特定のプロバイダー ID で絞り込むオプション。
    • refreshInterval: 検出の更新間隔。
    • defaultContextWindow / defaultMaxTokens: 検出されたモデルのフォールバック値。

プロバイダーの例

Cerebras を経由する場合は cerebras/zai-glm-4.7 を、Z.AI 直販を使用する場合は zai/glm-4.7 を使用します。
OPENCODE_API_KEY (または OPENCODE_ZEN_API_KEY) を設定してください。ショートカット: openclaw onboard --auth-choice opencode-zen
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 を上書きしてカスタムプロバイダーを定義してください。
中国向けエンドポイントを使用する場合: baseUrl: "https://api.moonshot.cn/v1" または openclaw onboard --auth-choice moonshot-api-key-cn
Anthropic 互換の組み込みプロバイダーです。ショートカット: openclaw onboard --auth-choice kimi-code-api-key
ベース URL から /v1 を除外する必要があります(Anthropic クライアントが自動付加します)。ショートカット: openclaw onboard --auth-choice synthetic-api-key
MINIMAX_API_KEY を設定してください。ショートカット: openclaw onboard --auth-choice minimax-api
ローカルモデル を参照してください。要約: ハイスペックなハードウェア上の 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 からのプロンプト変更フィールドを無視します(modelOverrideproviderOverride は維持されます)。
  • 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:evaluatewait --fn を無効化します。
  • ssrfPolicy.dangerouslyAllowPrivateNetwork: 未設定時はデフォルトで true(信頼されたネットワークモデル)。パブリックな Web 閲覧のみに制限したい場合は false に設定してください。
  • ssrfPolicy.allowPrivateNetwork もレガシーエイリアスとしてサポートされます。
  • 制限モードでは、hostnameAllowlistallowedHostnames で例外を定義できます。
  • リモートプロファイルは接続専用です(開始/停止/リセットは不可)。
  • 自動検出順序: 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.tokengateway.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.urlws:// または 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: HTTP POST /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.maxUrlParts
    • gateway.http.endpoints.responses.files.urlAllowlist
    • gateway.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/gmailgmail)。
  • 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 レコードから cliPathsshPort を除外します。
  • full: cliPathsshPort を含めます。
  • ホスト名はデフォルトで 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 用の keyReftoken 用の tokenRef)をサポートしています。
  • 実行時の静的な認証情報はメモリ上の解決済みスナップショットから取得されます。従来の静的な auth.json エントリは検出時に削除されます。
  • 従来の OAuth インポートは ~/.openclaw/credentials/oauth.json から行われます。
  • 詳細は OAuth を参照してください。
  • シークレットの実行時の動作および audit/configure/apply ツールについては、シークレット管理 を参照してください。

ロギング (Logging)

  • デフォルトのログファイル: /tmp/openclaw/openclaw-YYYY-MM-DD.log
  • 固定のパスを使用したい場合は logging.file を設定してください。
  • --verbose 指定時は consoleLeveldebug に引き上げられます。

CLI

  • cli.banner.taglineMode はバナーのタグライン(標語)スタイルを制御します。
    • "random" (デフォルト): 面白いものや季節ごとのタグラインを入れ替えて表示します。
    • "default": 固定の中立的なタグライン(All your chats, one OpenClaw.)を表示します。
    • "off": タグラインを表示しません(バナーのタイトルとバージョンは引き続き表示されます)。
  • タグラインだけでなくバナー全体を非表示にするには、環境変数 OPENCLAW_HIDE_BANNER=1 を設定してください。

ウィザード (Wizard)

CLI ウィザード(onboard, configure, doctor)によって書き込まれるメタデータです。

アイデンティティ (Identity)

macOS のオンボーディングアシスタントによって書き込まれます。以下のデフォルト値が導出されます。
  • identity.emoji から messages.ackReaction (未設定なら 👀)
  • identity.name / identity.emoji から mentionPatterns
  • avatar にはワークスペース相対パス、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)。
詳細は Cron ジョブ を参照してください。

メディアモデルのテンプレート変数

tools.media.models[].args 内で展開されるテンプレートプレースホルダーです。

構成のインクルード ($include)

構成を複数のファイルに分割できます。
マージ動作:
  • 単一ファイル: 含まれているオブジェクトで置き換えます。
  • ファイルの配列: 順番にディープマージされます(後のファイルが前のファイルを上書きします)。
  • 兄弟キー: インクルード後にマージされます(インクルードされた値を上書きします)。
  • ネストされたインクルード: 最大 10 レベルまで。
  • パス: インクルード元のファイルを基準に解決されますが、最上位の構成ディレクトリ(openclaw.json のディレクトリ)内にある必要があります。絶対パスや ../ は、その境界内で解決される場合にのみ許可されます。
  • エラー: ファイルの欠落、解析エラー、循環参照に関する明確なメッセージを表示します。

関連: 構成 · 構成例 · ドクター