設定 — エージェント

agents.*、multiAgent.*、session.*、 messages.*、talk.* 配下のエージェントスコープ設定キー。 チャンネル、ツール、Gateway ランタイム、およびその他のトップレベルキーについては、設定リファレンスを参照してください。

エージェントのデフォルト

agents.defaults.workspace

デフォルト: OPENCLAW_WORKSPACE_DIR が設定されている場合はその値、それ以外は ~/.openclaw/workspace（OPENCLAW_PROFILE がデフォルト以外のプロファイルに設定されている場合は ~/.openclaw/workspace-<profile>）。

{  agents: { defaults: { workspace: "~/.openclaw/workspace" } },}

明示的な agents.defaults.workspace の値は OPENCLAW_WORKSPACE_DIR より優先されます。設定にパスを書き込みたくない場合は、環境変数を使用してデフォルトのエージェントがマウント済みワークスペースを参照するようにします。

agents.defaults.repoRoot

システムプロンプトの Runtime 行に表示される、オプションのリポジトリルート。未設定の場合、OpenClaw はワークスペースから上位へたどって自動検出します。

{  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },}

agents.defaults.skills

agents.list[].skills を設定していないエージェント向けの、オプションのデフォルト Skills 許可リスト。

{  agents: {    defaults: { skills: ["github", "weather"] },    list: [      { id: "writer" }, // github、weatherを継承      { id: "docs", skills: ["docs-search"] }, // デフォルトを置換      { id: "locked-down", skills: [] }, // Skillsなし    ],  },}

• デフォルトで Skills を無制限にするには、agents.defaults.skills を省略します。
• デフォルトを継承するには、agents.list[].skills を省略します。
• Skills を無効にするには、agents.list[].skills: [] を設定します。
• 空でない agents.list[].skills リストが、そのエージェントの最終的なセットになります。デフォルトとは マージされません。

agents.defaults.skipBootstrap

ワークスペースのブートストラップファイル（AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md）の自動作成を無効にします。

{  agents: { defaults: { skipBootstrap: true } },}

agents.defaults.skipOptionalBootstrapFiles

必須のブートストラップファイル（AGENTS.md、TOOLS.md、BOOTSTRAP.md）は引き続き書き込みながら、選択したオプションのワークスペースファイルの作成をスキップします。有効な値: SOUL.md、USER.md、HEARTBEAT.md、IDENTITY.md。

{  agents: {    defaults: {      skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],    },  },}

agents.defaults.contextInjection

ワークスペースのブートストラップファイルをシステムプロンプトに注入するタイミングを制御します。デフォルト: "always"。

• "continuation-skip": 安全に継続できるターン（アシスタントの応答完了後）ではワークスペースブートストラップの再注入をスキップし、プロンプトサイズを削減します。Heartbeat の実行と Compaction 後の再試行では、引き続きコンテキストを再構築します。
• "never": すべてのターンでワークスペースブートストラップとコンテキストファイルの注入を無効にします。プロンプトのライフサイクルを完全に管理するエージェント（カスタムコンテキストエンジン、独自にコンテキストを構築するネイティブランタイム、またはブートストラップ不要の特殊なワークフロー）にのみ使用してください。Heartbeat と Compaction 復旧ターンでも注入をスキップします。

{  agents: { defaults: { contextInjection: "continuation-skip" } },}

エージェントごとのオーバーライド: agents.list[].contextInjection。省略した値は agents.defaults.contextInjection を継承します。

agents.defaults.bootstrapMaxChars

切り詰め前のワークスペースブートストラップファイルごとの最大文字数。デフォルト: 20000。

{  agents: { defaults: { bootstrapMaxChars: 20000 } },}

エージェントごとのオーバーライド: agents.list[].bootstrapMaxChars。省略した値は agents.defaults.bootstrapMaxChars を継承します。

agents.defaults.bootstrapTotalMaxChars

すべてのワークスペースブートストラップファイルから注入される合計最大文字数。デフォルト: 60000。

{  agents: { defaults: { bootstrapTotalMaxChars: 60000 } },}

エージェントごとのオーバーライド: agents.list[].bootstrapTotalMaxChars。省略した値は agents.defaults.bootstrapTotalMaxChars を継承します。

エージェントごとのブートストラッププロファイルのオーバーライド

あるエージェントで共有デフォルトとは異なるプロンプト注入動作が必要な場合は、エージェントごとのブートストラッププロファイルのオーバーライドを使用します。省略したフィールドは agents.defaults から継承されます。

{  agents: {    defaults: {      contextInjection: "continuation-skip",      bootstrapMaxChars: 20000,      bootstrapTotalMaxChars: 60000,    },    list: [      {        id: "strict-worker",        contextInjection: "always",        bootstrapMaxChars: 50000,        bootstrapTotalMaxChars: 300000,      },    ],  },}

agents.defaults.bootstrapPromptTruncationWarning

ブートストラップコンテキストが切り詰められた場合に、エージェントに表示されるシステムプロンプト通知を制御します。 デフォルト: "always"。

• "off": 切り詰め通知テキストをシステムプロンプトに一切注入しません。
• "once": 一意の切り詰めシグネチャごとに、簡潔な通知を1回注入します。
• "always": 切り詰めが存在する場合、実行のたびに簡潔な通知を注入します（推奨）。

生データと注入後の詳細な件数、および設定調整用フィールドは、コンテキスト/ステータスレポートやログなどの診断情報にのみ保持されます。通常の WebChat のユーザー/ランタイムコンテキストには、簡潔な復旧通知のみが含まれます。

{  agents: { defaults: { bootstrapPromptTruncationWarning: "always" } }, // off | once | always}

コンテキスト予算の所有範囲

OpenClaw には大容量のプロンプト/コンテキスト予算が複数あり、すべてを1つの汎用設定に集約するのではなく、意図的にサブシステム別に分割されています。

対応するエージェントごとのオーバーライド:

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextInjection
• agents.list[].bootstrapMaxChars
• agents.list[].bootstrapTotalMaxChars
• agents.list[].contextLimits.*

agents.defaults.startupContext

リセット/起動時のモデル実行で、最初のターンに注入される起動前置きを制御します。 単独のチャット /new および /reset コマンドは、モデルを呼び出さずにリセットへの確認応答を行うため、 この前置きを読み込みません。

{  agents: {    defaults: {      startupContext: {        enabled: true,        applyOn: ["new", "reset"],        dailyMemoryDays: 2,        maxFileBytes: 16384,        maxFileChars: 1200,        maxTotalChars: 2800,      },    },  },}

agents.defaults.contextLimits

上限付きランタイムコンテキストサーフェスの共有デフォルト。

{  agents: {    defaults: {      contextLimits: {        memoryGetMaxChars: 12000,        memoryGetDefaultLines: 120,        postCompactionMaxChars: 1800,      },    },  },}

• memoryGetMaxChars: 切り詰めメタデータと継続通知が追加される前の、デフォルトの memory_get 抜粋上限。
• memoryGetDefaultLines: lines が省略された場合の、デフォルトの memory_get 行範囲。
• toolResultMaxChars: 永続化される結果とオーバーフロー復旧に使用する、高度なライブツール結果の上限。モデルコンテキストによる自動上限を使用する場合は未設定のままにします。 100Kトークン未満では 16000 文字、100K以上では 32000 文字、200K以上では 64000 文字です。長いコンテキストに対応するモデルでは 1000000 までの明示的な値を指定できますが、 実効上限は引き続きモデルのコンテキストウィンドウの約30%に制限されます。openclaw doctor --deep は実効上限を表示し、 doctor は明示的なオーバーライドが古いか、効果がない場合にのみ警告します。
• postCompactionMaxChars: Compaction 後の更新注入時に使用される AGENTS.md 抜粋上限。

agents.list[].contextLimits

共有 contextLimits 設定に対するエージェントごとのオーバーライド。省略したフィールドは agents.defaults.contextLimits から継承されます。

{  agents: {    defaults: {      contextLimits: { memoryGetMaxChars: 12000 },    },    list: [      {        id: "tiny-local",        contextLimits: {          memoryGetMaxChars: 6000,          toolResultMaxChars: 8000, // このエージェントの高度な上限        },      },    ],  },}

skills.limits.maxSkillsPromptChars

システムプロンプトに注入されるコンパクトな Skills リストのグローバル上限。これは、必要に応じた SKILL.md ファイルの読み取りには影響しません。

{  skills: { limits: { maxSkillsPromptChars: 18000 } },}

agents.list[].skillsLimits.maxSkillsPromptChars

Skills プロンプト予算のエージェントごとのオーバーライド。

{  agents: {    list: [{ id: "tiny-local", skillsLimits: { maxSkillsPromptChars: 6000 } }],  },}

agents.defaults.imageMaxDimensionPx

プロバイダー呼び出し前の、トランスクリプト/ツールの画像ブロックにおける画像の長辺の最大ピクセル数。 デフォルト: 1200。

値を小さくすると、通常、スクリーンショットを多用する実行でビジョントークンの使用量とリクエストペイロードサイズが減少します。 値を大きくすると、より多くの視覚的詳細が維持されます。

{  agents: { defaults: { imageMaxDimensionPx: 1200 } },}

agents.defaults.imageQuality

ファイルパス、URL、メディア参照から読み込まれる画像に対する、画像ツールの圧縮/詳細度設定。 デフォルト: auto。

OpenClaw は、選択した画像モデルに合わせてリサイズ段階を調整します。たとえば、Claude Opus 4.8、OpenAI GPT-5.6 Sol、Qwen VL、およびホスト型 Llama 4 ビジョンモデルでは、従来の/デフォルトの高詳細ビジョンパスより大きな画像を使用できます。一方、複数画像のターンでは、トークンとレイテンシーのコストを制御するため、auto モードでより積極的に圧縮されます。

値:

• auto: モデルの制限と画像数に適応します。
• efficient: トークンとバイトの使用量を減らすため、小さい画像を優先します。
• balanced: 標準的な中間設定の段階を使用します。
• high: スクリーンショット、図、文書画像の詳細をより多く維持します。

{  agents: { defaults: { imageQuality: "auto" } },}

agents.defaults.userTimezone

システムプロンプトのコンテキストに使用するタイムゾーン（メッセージのタイムスタンプには使用しません）。ホストのタイムゾーンにフォールバックします。

{  agents: { defaults: { userTimezone: "America/Chicago" } },}

agents.defaults.timeFormat

システムプロンプトの時刻形式。デフォルト: auto（OS の設定）。

{  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24}

agents.defaults.model

{  agents: {    defaults: {      models: {        "anthropic/claude-opus-4-6": { alias: "opus" },        "minimax/MiniMax-M2.7": { alias: "minimax" },      },      model: {        primary: "anthropic/claude-opus-4-6",        fallbacks: ["minimax/MiniMax-M2.7"],      },      utilityModel: "openai/gpt-5.4-mini",      imageModel: {        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],      },      imageGenerationModel: {        primary: "openai/gpt-image-2",        fallbacks: ["google/gemini-3.1-flash-image-preview"],      },      videoGenerationModel: {        primary: "qwen/wan2.6-t2v",        fallbacks: ["qwen/wan2.6-i2v"],      },      pdfModel: {        primary: "anthropic/claude-opus-4-6",        fallbacks: ["openai/gpt-5.4-mini"],      },      params: { cacheRetention: "long" }, // プロバイダーのグローバルデフォルトパラメーター      pdfMaxBytesMb: 10,      pdfMaxPages: 20,      thinkingDefault: "low",      verboseDefault: "off",      toolProgressDetail: "explain",      reasoningDefault: "off",      elevatedDefault: "on",      timeoutSeconds: 600,      mediaMaxMb: 5,      contextTokens: 200000,      maxConcurrent: 4,    },  },}

• model: 文字列（"provider/model"）またはオブジェクト（{ primary, fallbacks }）を受け付けます。
  • 文字列形式では、プライマリモデルのみを設定します。
  • オブジェクト形式では、プライマリモデルと順序付きフェイルオーバーモデルを設定します。
• utilityModel: 短い内部タスク用の、省略可能な provider/model 参照またはエイリアスです。現在は、生成される Control UI のセッションタイトル、Telegram DM のトピックタイトル、Discord の自動スレッドタイトル、および進行状況ドラフトのナレーションに使用されます。未設定の場合、OpenClaw はプライマリプロバイダーに宣言済みの小規模モデルのデフォルトがあれば、それを使用します（OpenAI → gpt-5.6-luna、Anthropic → claude-haiku-4-5）。それ以外の場合、タイトルタスクはエージェントのプライマリモデルにフォールバックし、ナレーションは無効のままです。ユーティリティルーティングを完全に無効にするには、utilityModel: "" を設定します。agents.list[].utilityModel はデフォルトを上書きし（エージェントごとの値を空にすると、そのエージェントでは無効になります）、操作固有のモデル上書きはその両方より優先されます。ユーティリティタスクは個別にモデルを呼び出し、タスク固有の内容を選択したモデルプロバイダーへ送信します。ダッシュボードのタイトル生成では、コマンドではない最初のメッセージの先頭 1,000 文字までを送信します。ナレーションでは、受信リクエストと簡潔に編集されたツール概要を送信します。コストとデータ処理の要件に合うプロバイダーを選択してください。
• imageModel: 文字列（"provider/model"）またはオブジェクト（{ primary, fallbacks }）を受け付けます。
  • アクティブなモデルが画像を受け付けられない場合に、image ツールパスでビジョンモデル設定として使用されます。ネイティブに画像を扱えるモデルには、読み込まれた画像バイトが代わりに直接渡されます。
  • 選択されたモデルまたはデフォルトモデルが画像入力を受け付けられない場合のフォールバックルーティングにも使用されます。
  • 明示的な provider/model 参照を推奨します。互換性のため、プロバイダーなしの ID も受け付けます。プロバイダーなしの ID が models.providers.*.models に設定された画像対応エントリの 1 つと一意に一致する場合、OpenClaw はそのプロバイダーで修飾します。設定済みの一致候補が複数ある場合は、明示的なプロバイダープレフィックスが必要です。
• imageGenerationModel: 文字列（"provider/model"）またはオブジェクト（{ primary, fallbacks }）を受け付けます。
  • 共有の画像生成機能、および今後追加される画像生成用のツール／Plugin サーフェスで使用されます。
  • 一般的な値: Gemini のネイティブ画像生成には google/gemini-3.1-flash-image-preview、fal には fal/fal-ai/flux/dev、OpenAI Images には openai/gpt-image-2、透明背景の OpenAI PNG/WebP 出力には openai/gpt-image-1.5 を使用します。
  • プロバイダー／モデルを直接選択する場合は、対応するプロバイダー認証も設定してください（たとえば、google/* には GEMINI_API_KEY または GOOGLE_API_KEY、openai/gpt-image-2 / openai/gpt-image-1.5 には OPENAI_API_KEY または OpenAI Codex OAuth、fal/* には FAL_KEY）。
  • 省略した場合でも、image_generate は認証に基づいてプロバイダーのデフォルトを推定できます。まず現在のデフォルトプロバイダーを試し、次に登録済みの残りの画像生成プロバイダーをプロバイダー ID 順に試します。
• musicGenerationModel: 文字列（"provider/model"）またはオブジェクト（{ primary, fallbacks }）を受け付けます。
  • 共有の音楽生成機能と、組み込みの music_generate ツールで使用されます。
  • 一般的な値: google/lyria-3-clip-preview、google/lyria-3-pro-preview、または minimax/music-2.6。
  • 省略した場合でも、music_generate は認証に基づいてプロバイダーのデフォルトを推定できます。まず現在のデフォルトプロバイダーを試し、次に登録済みの残りの音楽生成プロバイダーをプロバイダー ID 順に試します。
  • プロバイダー／モデルを直接選択する場合は、対応するプロバイダー認証／API キーも設定してください。
• videoGenerationModel: 文字列（"provider/model"）またはオブジェクト（{ primary, fallbacks }）を受け付けます。
  • 共有の動画生成機能と、組み込みの video_generate ツールで使用されます。
  • 一般的な値: qwen/wan2.6-t2v、qwen/wan2.6-i2v、qwen/wan2.6-r2v、qwen/wan2.6-r2v-flash、または qwen/wan2.7-r2v。
  • 省略した場合でも、video_generate は認証に基づいてプロバイダーのデフォルトを推定できます。まず現在のデフォルトプロバイダーを試し、次に登録済みの残りの動画生成プロバイダーをプロバイダー ID 順に試します。
  • プロバイダー／モデルを直接選択する場合は、対応するプロバイダー認証／API キーも設定してください。
  • 公式の Qwen 動画生成 Plugin は、最大 1 本の出力動画、1 枚の入力画像、4 本の入力動画、10 秒の長さ、およびプロバイダーレベルの size、aspectRatio、resolution、audio、watermark オプションをサポートします。
• pdfModel: 文字列（"provider/model"）またはオブジェクト（{ primary, fallbacks }）を受け付けます。
  • モデルルーティング用に pdf ツールで使用されます。
  • 省略した場合、PDF ツールは imageModel にフォールバックし、次に解決済みのセッション／デフォルトモデルへフォールバックします。
• pdfMaxBytesMb: 呼び出し時に maxBytesMb が渡されなかった場合に、pdf ツールで使用されるデフォルトの PDF サイズ上限です。
• pdfMaxPages: pdf ツールの抽出フォールバックモードで対象とするデフォルトの最大ページ数です。
• verboseDefault: エージェントのデフォルトの詳細出力レベルです。値: "off"、"on"、"full"。デフォルト: "off"。
• toolProgressDetail: /verbose ツール概要および進行状況ドラフトのツール行の詳細モードです。値: "explain"（デフォルト、簡潔で人が読みやすいラベル）または "raw"（利用可能な場合は生のコマンド／詳細を追加）。エージェントごとの agents.list[].toolProgressDetail がこのデフォルトを上書きします。
• reasoningDefault: エージェントのデフォルトの推論表示設定です。値: "off"、"on"、"stream"。エージェントごとの agents.list[].reasoningDefault がこのデフォルトを上書きします。設定された推論のデフォルトは、メッセージ単位またはセッション単位の推論上書きが設定されていない場合に限り、所有者、認可済み送信者、またはオペレーター管理者の Gateway コンテキストにのみ適用されます。
• elevatedDefault: エージェントのデフォルトの昇格出力レベルです。値: "off"、"on"、"ask"、"full"。デフォルト: "on"。
• model.primary: 形式は provider/model（例: Codex OAuth アクセスの場合は openai/gpt-5.6-sol）。プロバイダーを省略すると、OpenClaw は最初にエイリアスを試し、次にその正確なモデル ID に対する設定済みプロバイダーの一意の一致を試し、その後にのみ設定済みのデフォルトプロバイダーへフォールバックします（非推奨の互換動作であるため、明示的な provider/model を推奨します）。そのプロバイダーが設定済みのデフォルトモデルを提供しなくなった場合、OpenClaw は削除済みプロバイダーの古いデフォルトをエラーとして提示する代わりに、最初の設定済みプロバイダー／モデルへフォールバックします。
• models: /model 用に設定されたモデルカタログおよび許可リストです。各エントリには、alias（ショートカット）と params（プロバイダー固有。例: temperature、maxTokens、cacheRetention、context1m、responsesServerCompaction、responsesCompactThreshold、OpenRouter の provider ルーティング、chat_template_kwargs、extra_body/extraBody）を含められます。
  • すべてのモデル ID を手動で列挙せずに、選択したプロバイダーで検出されたすべてのモデルを表示するには、"openai/*": {} や "vllm/*": {} などの provider/* エントリを使用します。
  • そのプロバイダーで動的に検出されるすべてのモデルに同じランタイムを使用する場合は、provider/* エントリに agentRuntime を追加します。完全一致する provider/model のランタイムポリシーが、引き続きワイルドカードより優先されます。
  • 安全な編集: エントリを追加するには openclaw config set agents.defaults.models '<json>' --strict-json --merge を使用します。--replace を渡さない限り、config set は既存の許可リストエントリを削除する置換を拒否します。
  • プロバイダー単位の設定／オンボーディングフローは、選択したプロバイダーのモデルをこのマップにマージし、すでに設定されている無関係なプロバイダーを保持します。
  • OpenAI Responses の直接モデルでは、サーバー側 Compaction が自動的に有効になります。context_management の注入を停止するには params.responsesServerCompaction: false を使用し、しきい値を上書きするには params.responsesCompactThreshold を使用します。OpenAI のサーバー側 Compactionを参照してください。
• params: すべてのモデルに適用される、プロバイダーのグローバルデフォルトパラメーターです。agents.defaults.params に設定します（例: { cacheRetention: "long" }）。
• params のマージ優先順位（設定）: agents.defaults.params（グローバルベース）は agents.defaults.models["provider/model"].params（モデルごと）で上書きされ、次に agents.list[].params（一致するエージェント ID）がキー単位で上書きします。詳細はプロンプトキャッシュを参照してください。
• models.providers.openrouter.params.provider: OpenRouter 全体のデフォルトのプロバイダールーティングポリシーです。OpenClaw はこれを OpenRouter のリクエスト provider オブジェクトへ転送します。モデルごとの agents.defaults.models["openrouter/<model>"].params.provider とエージェントパラメーターがキー単位で上書きします。OpenRouter のプロバイダールーティングを参照してください。
• params.extra_body/params.extraBody: OpenAI 互換プロキシ向けの api: "openai-completions" リクエスト本文にマージされる高度なパススルー JSON です。生成されたリクエストキーと競合する場合、追加の本文が優先されます。非ネイティブの completions ルートでは、その後も OpenAI 専用の store が削除されます。
• params.chat_template_kwargs: トップレベルの api: "openai-completions" リクエスト本文にマージされる、vLLM／OpenAI 互換のチャットテンプレート引数です。思考が無効な vllm/nemotron-3-* の場合、同梱の vLLM Plugin は enable_thinking: false と force_nonempty_content: true を自動的に送信します。明示的な chat_template_kwargs は生成されたデフォルトを上書きし、extra_body.chat_template_kwargs が引き続き最終的な優先権を持ちます。設定済みの vLLM Qwen および Nemotron 思考モデルでは、多段階の労力レベルの代わりに、二者択一の /think 選択肢（off、on）が公開されます。
• compat.thinkingFormat: OpenAI 互換の思考ペイロード形式です。Together 形式の reasoning.enabled には "together"、Qwen 形式のトップレベル enable_thinking には "qwen"、vLLM などリクエストレベルのチャットテンプレート kwargs をサポートする Qwen 系バックエンド上の chat_template_kwargs.enable_thinking には "qwen-chat-template" を使用します。OpenClaw は無効な思考を false、有効な思考を true にマッピングします。また、設定済みの vLLM Qwen モデルでは、これらの形式に対して二者択一の /think 選択肢が公開されます。
• compat.supportedReasoningEfforts: モデルごとの OpenAI 互換推論労力リストです。それを実際に受け付けるカスタムエンドポイントでは "xhigh" を含めます。これにより OpenClaw は、設定されたプロバイダー／モデルについて、コマンドメニュー、Gateway セッション行、セッションパッチ検証、エージェント CLI 検証、llm-task 検証で /think xhigh を公開します。バックエンドが標準レベルに対してプロバイダー固有の値を必要とする場合は、compat.reasoningEffortMap を使用します。
• params.preserveThinking: 思考を保持するための Z.AI 専用のオプトイン設定です。有効で、かつ思考がオンの場合、OpenClaw は thinking.clear_thinking: false を送信し、以前の reasoning_content を再生します。Z.AI の思考と保持された思考を参照してください。
• localService: ローカル／セルフホスト型モデルサーバー向けの、省略可能なプロバイダーレベルのプロセスマネージャーです。選択したモデルがそのプロバイダーに属する場合、OpenClaw は healthUrl（または baseUrl + "/models"）をプローブし、エンドポイントが停止していれば args を指定して command を起動し、最大 readyTimeoutMs 待機してからモデルリクエストを送信します。command は絶対パスでなければなりません。idleStopMs: 0 は、OpenClaw が終了するまでプロセスを維持します。正の値を指定すると、OpenClaw が起動したプロセスを、そのミリ秒数だけアイドル状態が続いた後に停止します。ローカルモデルサービスを参照してください。
• ランタイムポリシーは agents.defaults ではなく、プロバイダーまたはモデルに設定します。プロバイダー全体のルールには models.providers.<provider>.agentRuntime を、モデル固有のルールには agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime を使用します。プロバイダー/モデルのプレフィックスだけでハーネスが選択されることはありません。ランタイムが未設定または auto の場合、作成者によるリクエストのオーバーライドがなく、公式 HTTPS Platform Responses または ChatGPT Responses のルートと完全に一致するときに限り、OpenAI が暗黙的に Codex を選択することがあります。OpenAI の暗黙的なエージェントランタイムを参照してください。
• これらのフィールドを変更する設定書き込み処理（例: /models set、/models set-image、フォールバックの追加/削除コマンド）は、正規のオブジェクト形式で保存し、可能な場合は既存のフォールバックリストを保持します。
• maxConcurrent: セッションをまたいで並列実行できるエージェント実行の最大数（各セッション内では引き続き直列化されます）。デフォルト: 4。

ランタイムポリシー

{  models: {    providers: {      openai: {        agentRuntime: { id: "codex" },      },    },  },  agents: {    defaults: {      model: "openai/gpt-5.6-sol",      models: {        "anthropic/claude-opus-4-8": {          agentRuntime: { id: "claude-cli" },        },        "vllm/*": {          agentRuntime: { id: "openclaw" },        },      },    },  },}

• id: "auto"、"openclaw"、登録済みPluginハーネス ID、またはサポートされている CLI バックエンドエイリアス。バンドルされている Codex Plugin は codex を登録し、バンドルされている Anthropic Plugin は claude-cli CLI バックエンドを提供します。
• id: "auto" は、登録済みPluginハーネスが、サポート契約を宣言するか、その他の方法で満たす有効なルートを引き受けられるようにし、一致するハーネスがない場合は OpenClaw を使用します。id: "codex" のような明示的なPluginランタイムには、そのハーネスと互換性のある有効なルートが必要です。いずれかが利用できない場合、または実行に失敗した場合は、フェイルクローズします。
• id: "pi" は、v2026.5.22 以前のリリース済み設定を維持するために、openclaw の非推奨エイリアスとしてのみ受け入れられます。新しい設定では openclaw を使用してください。
• ランタイムの優先順位は、最初に完全一致モデルポリシー（agents.list[].models["provider/model"]、agents.defaults.models["provider/model"]、または models.providers.<provider>.models[]）、次に agents.list[] / agents.defaults.models["provider/*"]、最後に models.providers.<provider>.agentRuntime のプロバイダー全体のポリシーです。
• エージェント全体のランタイムキーはレガシーです。agents.defaults.agentRuntime、agents.list[].agentRuntime、セッションランタイムの固定、および OPENCLAW_AGENT_RUNTIME は、ランタイム選択では無視されます。古い値を削除するには openclaw doctor --fix を実行してください。
• 作成者によるリクエストのオーバーライドがない、対象となる公式 HTTPS OpenAI Responses/ChatGPT 完全一致ルートでは、Codex ハーネスが暗黙的に使用される場合があります。プロバイダー/モデルの agentRuntime.id: "codex" は Codex をフェイルクローズ要件にしますが、互換性のないルートを互換性のあるものにはしません。
• Claude CLI のデプロイでは、model: "anthropic/claude-opus-4-8" とモデルスコープの agentRuntime.id: "claude-cli" の併用を推奨します。レガシーの claude-cli/<model> 参照も互換性のため引き続き機能しますが、新しい設定ではプロバイダー/モデルの選択を正規形に保ち、実行バックエンドをプロバイダー/モデルのランタイムポリシーに配置してください。
• これはテキストエージェントターンの実行のみを制御します。メディア生成、ビジョン、PDF、音楽、動画、TTS では、引き続きそれぞれのプロバイダー/モデル設定が使用されます。

組み込みエイリアスの短縮形（モデルが agents.defaults.models に含まれる場合にのみ適用）:

設定したエイリアスは常にデフォルトより優先されます。

Z.AI GLM-4.x モデルでは、--thinking off を設定するか、agents.defaults.models["zai/<model>"].params.thinking を独自に定義しない限り、思考モードが自動的に有効になります。 Z.AI モデルでは、ツール呼び出しのストリーミング用に tool_stream がデフォルトで有効になります。無効にするには、agents.defaults.models["zai/<model>"].params.tool_stream を false に設定してください。 Anthropic Claude Opus 4.8 では、OpenClaw において思考はデフォルトで無効です。適応的思考を明示的に有効にした場合、Anthropic のプロバイダーが所有するエフォートのデフォルト値は high です。Claude 4.6 モデルでは、明示的な思考レベルが設定されていない場合、デフォルトで adaptive が使用されます。

agents.defaults.cliBackends

テキストのみのフォールバック実行用のオプションの CLI バックエンド（ツール呼び出しなし）。API プロバイダーで障害が発生した場合のバックアップとして役立ちます。

{  agents: {    defaults: {      cliBackends: {        "claude-cli": {          command: "/opt/homebrew/bin/claude",        },        "my-cli": {          command: "my-cli",          args: ["--json"],          output: "json",          modelArg: "--model",          sessionArg: "--session",          sessionMode: "existing",          systemPromptArg: "--system",          // または、CLI がプロンプトファイルのフラグを受け付ける場合は systemPromptFileArg を使用します。          systemPromptWhen: "first",          imageArg: "--image",          imageMode: "repeat",        },      },    },  },}

• CLI バックエンドはテキスト優先であり、ツールは常に無効です。
• sessionArg が設定されている場合、セッションがサポートされます。
• imageArg がファイルパスを受け付ける場合、画像のパススルーがサポートされます。
• reseedFromRawTranscriptWhenUncompacted: true により、最初のCompaction要約が存在する前に、境界が設定された未加工の OpenClaw トランスクリプト末尾から、安全に無効化されたセッションをバックエンドが復旧できます。認証プロファイルまたは認証情報エポックが変更された場合は、引き続き未加工データによる再シードは行われません。

agents.defaults.promptOverlays

OpenClaw が組み立てたプロンプトサーフェスにモデルファミリー単位で適用される、プロバイダー非依存のプロンプトオーバーレイ。GPT-5 ファミリーのモデル ID は、OpenClaw/プロバイダールート全体で共有動作契約を受け取ります。personality は、親しみやすい対話スタイルのレイヤーのみを制御します。ネイティブ Codex app-server ルートでは、この OpenClaw GPT-5 オーバーレイの代わりに Codex 所有の基本命令/モデル命令が維持され、OpenClaw はネイティブスレッドで Codex の組み込みパーソナリティを無効にします。

{  agents: {    defaults: {      promptOverlays: {        gpt5: {          personality: "friendly", // friendly | on | off        },      },    },  },}

• "friendly"（デフォルト）と "on" は、親しみやすい対話スタイルのレイヤーを有効にします。
• "off" は親しみやすいレイヤーのみを無効にします。タグ付けされた GPT-5 動作契約は引き続き有効です。
• この共有設定が未設定の場合、レガシーの plugins.entries.openai.config.personality が引き続き読み込まれます。

agents.defaults.heartbeat

定期的なHeartbeat実行。

{  agents: {    defaults: {      heartbeat: {        every: "30m", // 0m で無効化        model: "openai/gpt-5.4-mini",        includeReasoning: false,        includeSystemPromptSection: true, // デフォルト: true。false の場合、システムプロンプトから Heartbeat セクションを省略        lightContext: false, // デフォルト: false。true の場合、ワークスペースのブートストラップファイルから HEARTBEAT.md のみを保持        isolatedSession: false, // デフォルト: false。true の場合、各 Heartbeat を新しいセッションで実行（会話履歴なし）        skipWhenBusy: false, // デフォルト: false。true の場合、このエージェントのサブエージェント/ネストされたレーンも待機        session: "main",        to: "+15555550123",        directPolicy: "allow", // allow（デフォルト）| block        target: "none", // デフォルト: none | 選択肢: last | whatsapp | telegram | discord | ...        prompt: "HEARTBEAT.md が存在する場合は読み取ってください...",        ackMaxChars: 300,        suppressToolErrorWarnings: false,        timeoutSeconds: 45,      },    },  },}

• every: 期間文字列（ms/s/m/h）。デフォルト: 30m（API キー認証）または 1h（OAuth 認証）。無効にするには 0m に設定します。
• includeSystemPromptSection: false の場合、システムプロンプトから Heartbeat セクションを省略し、ブートストラップコンテキストへの HEARTBEAT.md の挿入をスキップします。デフォルト: true。
• suppressToolErrorWarnings: true の場合、Heartbeat実行中のツールエラー警告ペイロードを抑制します。
• timeoutSeconds: Heartbeatエージェントターンが中止されるまでに許容される最大時間（秒）。未設定の場合、agents.defaults.timeoutSeconds が設定されていればそれを使用し、そうでなければ最大 600 秒に制限されたHeartbeat間隔を使用します。
• directPolicy: ダイレクト/DM 配信ポリシー。allow（デフォルト）はダイレクトターゲットへの配信を許可します。block はダイレクトターゲットへの配信を抑制し、reason=dm-blocked を出力します。
• lightContext: true の場合、Heartbeat実行では軽量ブートストラップコンテキストを使用し、ワークスペースのブートストラップファイルから HEARTBEAT.md のみを保持します。
• isolatedSession: true の場合、各Heartbeatは過去の会話履歴がない新しいセッションで実行されます。Cron の sessionTarget: "isolated" と同じ分離パターンです。Heartbeatごとのトークンコストを約 100K から約 2-5K トークンに削減します。
• skipWhenBusy: true の場合、そのエージェントの追加のビジーレーン、つまり自身のセッションキー付きサブエージェントまたはネストされたコマンド処理中は、Heartbeat実行を延期します。このフラグがなくても、Cron レーンは常にHeartbeatを延期します。
• エージェントごと: agents.list[].heartbeat を設定します。いずれかのエージェントが heartbeat を定義すると、それらのエージェントのみがHeartbeatを実行します。
• Heartbeatは完全なエージェントターンを実行するため、間隔を短くすると消費するトークンが増えます。

agents.defaults.compaction

{  agents: {    defaults: {      compaction: {        mode: "safeguard", // default | safeguard        provider: "my-provider", // 登録済み Compaction プロバイダーPluginの ID（任意）        timeoutSeconds: 180,        reserveTokensFloor: 24000,        keepRecentTokens: 50000,        recentTurnsPreserve: 3,        maxHistoryShare: 0.7,        identifierPolicy: "strict", // strict | off | custom        identifierInstructions: "デプロイ ID、チケット ID、host:port の組を正確に保持してください。", // identifierPolicy=custom の場合に使用        qualityGuard: { enabled: true, maxRetries: 1 },        midTurnPrecheck: { enabled: false }, // 任意のツールループ負荷チェック        postIndexSync: "async", // off | async | await        postCompactionSections: ["Session Startup", "Red Lines"], // AGENTS.md セクションの再挿入をオプトイン        model: "openrouter/anthropic/claude-sonnet-4-6", // 任意の Compaction 専用モデルオーバーライド        truncateAfterCompaction: true, // Compaction 後に、より小さい後継 JSONL へローテーション        maxActiveTranscriptBytes: "20mb", // 任意のプリフライトローカル Compaction トリガー        notifyUser: true, // Compaction の開始時/完了時、およびメモリフラッシュの機能低下時に通知（デフォルト: false）        memoryFlush: {          enabled: true,          model: "ollama/qwen3:8b", // 任意のメモリフラッシュ専用モデルオーバーライド          softThresholdTokens: 6000,          forceFlushTranscriptBytes: "2mb",          systemPrompt: "セッションが Compaction に近づいています。永続的なメモリを今すぐ保存してください。",          prompt: "永続的に残すメモを memory/YYYY-MM-DD.md に書き込んでください。保存するものがない場合は、正確なサイレントトークン NO_REPLY で応答してください。",        },      },    },  },}

• mode: default または safeguard（長い履歴向けのチャンク単位の要約）。Compactionを参照してください。
• provider: 登録済みの Compaction プロバイダー Plugin の ID。設定すると、組み込みの LLM 要約の代わりにプロバイダーの summarize() が呼び出されます。失敗した場合は組み込み機能にフォールバックします。プロバイダーを設定すると、mode: "safeguard" が強制されます。Compactionを参照してください。
• timeoutSeconds: OpenClaw が中止するまでに、1 回の Compaction 操作に許可される最大秒数。デフォルト: 180。
• reserveTokens: Compaction 後のモデル出力と将来のツール結果用に確保されるトークンの余裕。モデルのコンテキストウィンドウが既知の場合、OpenClaw は実効予約量がプロンプト予算を消費しないよう上限を設定します。
• reserveTokensFloor: 組み込みランタイムによって適用される最小予約量。下限を無効にするには 0 を設定します。この下限には、引き続き有効なコンテキストウィンドウの上限が適用されます。
• keepRecentTokens: 最新のトランスクリプト末尾を原文のまま保持するためのエージェント切断点予算。明示的に設定されている場合、手動の /compact はこの値に従います。それ以外の場合、手動 Compaction は厳密なチェックポイントになります。
• recentTurnsPreserve: セーフガード要約の外側で原文のまま保持される、直近のユーザー／アシスタントターン数。デフォルト: 3。
• maxHistoryShare: Compaction 後に保持される履歴に許可される、コンテキスト予算全体に対する最大比率（範囲 0.1～0.9）。
• identifierPolicy: strict（デフォルト）、off、または custom。strict は、Compaction 要約時に組み込みの不透明な識別子を保持するためのガイダンスを先頭に追加します。
• identifierInstructions: identifierPolicy=custom の場合に使用される、識別子保持用の任意のカスタムテキスト。
• qualityGuard: セーフガード要約の不正な形式の出力に対する再試行チェック。セーフガードモードではデフォルトで有効です。監査を省略するには enabled: false を設定します。
• midTurnPrecheck: 任意のツールループ負荷チェック。enabled: true の場合、OpenClaw はツール結果が追加された後、次のモデル呼び出しの前にコンテキスト負荷を確認します。コンテキストが収まらなくなった場合、プロンプトを送信する前に現在の試行を中止し、既存の事前チェック復旧パスを再利用してツール結果を切り詰めるか、Compaction を実行して再試行します。default と safeguard の両方の Compaction モードで動作します。デフォルト: 無効。
• postIndexSync: Compaction 後のセッションメモリ再インデックスモード。デフォルト: "async"。鮮度を最優先する場合は "await"、Compaction のレイテンシーを低減する場合は "async"、セッションメモリの同期がほかの場所で処理される場合に限り "off" を使用します。
• postCompactionSections: Compaction 後に再挿入する、任意の AGENTS.md H2/H3 セクション名。未設定または [] に設定されている場合、再挿入は無効です。["Session Startup", "Red Lines"] を明示的に設定すると、その組み合わせが有効になり、従来の Every Session/Safety フォールバックが保持されます。追加コンテキストの価値が、Compaction 要約にすでに取り込まれているプロジェクトガイダンスを重複させるリスクに見合う場合にのみ有効にしてください。
• model: Compaction 要約のみに使用する、任意の provider/model-id または agents.defaults.models の単純なエイリアス。単純なエイリアスはディスパッチ前に解決されます。競合時は、設定されたリテラルモデル ID が優先されます。メインセッションではあるモデルを維持しつつ、Compaction 要約を別のモデルで実行する場合に使用します。未設定の場合、Compaction はセッションのプライマリモデルを使用します。
• truncateAfterCompaction: Compaction 後にアクティブなセッショントランスクリプトをローテーションし、以後のターンでは要約と未要約の末尾のみを読み込む一方、以前の完全なトランスクリプトはアーカイブに残します。長時間実行されるセッションで、アクティブなトランスクリプトが際限なく増大するのを防ぎます。デフォルト: false。
• maxActiveTranscriptBytes: トランスクリプト履歴がしきい値を超えた場合、実行前に通常のローカル Compaction を開始する任意のバイトしきい値（number または "20mb" のような文字列）。Compaction の成功後に、より小さい後続トランスクリプトへローテーションできるようにするため、truncateAfterCompaction が必要です。未設定または 0 の場合は無効です。
• notifyUser: true の場合、簡潔なコンテキスト保守通知をユーザーへ送信します。通知は、Compaction の開始時と完了時（例: 「コンテキストを Compaction 中...」「Compaction が完了しました」）、および Compaction 前のメモリフラッシュを使い果たし、機能が低下した状態で応答を続行する場合（例: 「メモリ保守に一時的に失敗しました。応答を続行します。」）に送信されます。これらの通知を表示しないよう、デフォルトでは無効です。
• memoryFlush: 永続的なメモリを保存するため、自動 Compaction の前に実行されるサイレントなエージェントターン。この保守ターンをローカルモデル上に維持する必要がある場合、model を ollama/qwen3:8b のような正確なプロバイダー／モデルに設定します。このオーバーライドは、アクティブなセッションのフォールバックチェーンを継承しません。forceFlushTranscriptBytes は、トークンカウンターが古い場合でも、トランスクリプトサイズがしきい値に達するとフラッシュを強制します。ワークスペースが読み取り専用の場合はスキップされます。

agents.defaults.runRetries

障害復旧中の無限実行ループを防ぐための、組み込みエージェントランタイムにおける外側の実行ループの再試行回数境界。この設定は組み込みエージェントランタイムにのみ適用され、ACP または CLI ランタイムには適用されません。

{  agents: {    defaults: {      runRetries: {        base: 24,        perProfile: 8,        min: 32,        max: 160,      },    },    list: [      {        id: "main",        runRetries: { max: 50 }, // エージェントごとの任意のオーバーライド      },    ],  },}

• base: 外側の実行ループにおける基本の実行再試行回数。デフォルト: 24。
• perProfile: フォールバックプロファイル候補ごとに追加される実行再試行回数。デフォルト: 8。
• min: 実行再試行回数の絶対的な最小上限。デフォルト: 32。
• max: 暴走を防ぐための、実行再試行回数の絶対的な最大上限。デフォルト: 160。

agents.defaults.contextPruning

LLM に送信する前に、メモリ内のコンテキストから古いツール結果を削減します。ディスク上のセッション履歴は変更しません。デフォルトでは無効です。有効にするには mode: "cache-ttl" を設定します。

{  agents: {    defaults: {      contextPruning: {        mode: "cache-ttl", // off（デフォルト）| cache-ttl        ttl: "1h", // 期間（ms/s/m/h）、デフォルト単位: 分、デフォルト: 5m        keepLastAssistants: 3,        softTrimRatio: 0.3,        hardClearRatio: 0.5,        minPrunableToolChars: 50000,        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },        hardClear: { enabled: true, placeholder: "[古いツール結果の内容を消去しました]" },        tools: { deny: ["browser", "canvas"] },      },    },  },}

動作の詳細については、セッションの削減を参照してください。

ブロックストリーミング

{  agents: {    defaults: {      blockStreamingDefault: "off", // on | off      blockStreamingBreak: "text_end", // text_end | message_end      blockStreamingChunk: { minChars: 800, maxChars: 1200, breakPreference: "paragraph" },      blockStreamingCoalesce: { idleMs: 1000 },      humanDelay: { mode: "natural" }, // off（デフォルト）| natural | custom（minMs/maxMs を使用）    },  },}

• Telegram 以外のチャンネルでは、ブロック返信を有効にするために *.streaming.block.enabled: true を明示的に設定する必要があります。QQ Bot は例外です。streaming.block キーがなく、channels.qqbot.streaming.mode が "off" でない限りブロック返信をストリーミングします。
• チャンネルごとのオーバーライド: channels.<channel>.streaming.block.coalesce（およびアカウントごとのバリエーション）。Discord、Google Chat、Mattermost、MS Teams、Signal、Slack のデフォルトは minChars: 1500 / idleMs: 1000 です。
• blockStreamingChunk.breakPreference: 優先されるチャンク境界（"paragraph" | "newline" | "sentence"）。
• humanDelay: ブロック返信間のランダムな一時停止。デフォルト: off。natural = 800-2500ms。custom は minMs/maxMs を使用します（未設定の境界値には自然な範囲がフォールバックとして使用されます）。エージェントごとのオーバーライド: agents.list[].humanDelay。

動作とチャンク分割の詳細については、ストリーミングを参照してください。

入力中インジケーター

{  agents: {    defaults: {      typingMode: "instant", // never | instant | thinking | message      typingIntervalSeconds: 6,    },  },}

• デフォルト: ダイレクトチャット／メンションでは instant、メンションのないグループチャットでは message。
• typingIntervalSeconds のデフォルト: 6。
• セッションごとのオーバーライド: session.typingMode、session.typingIntervalSeconds。

入力中インジケーターを参照してください。

agents.defaults.sandbox

組み込みエージェント向けの任意のサンドボックス化。完全なガイドについては、サンドボックス化を参照してください。

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // off（デフォルト）| non-main | all        backend: "docker", // docker（デフォルト）| ssh | openshell        scope: "agent", // session | agent（デフォルト）| shared        workspaceAccess: "none", // none（デフォルト）| ro | rw        workspaceRoot: "~/.openclaw/sandboxes",        docker: {          image: "openclaw-sandbox:bookworm-slim",          containerPrefix: "openclaw-sbx-",          workdir: "/workspace",          readOnlyRoot: true,          tmpfs: ["/tmp", "/var/tmp", "/run"],          network: "none",          user: "1000:1000",          capDrop: ["ALL"],          env: { LANG: "C.UTF-8" },          setupCommand: "apt-get update && apt-get install -y git curl jq",          pidsLimit: 256,          memory: "1g",          memorySwap: "2g",          cpus: 1,          gpus: "all",          ulimits: {            nofile: { soft: 1024, hard: 2048 },            nproc: 256,          },          seccompProfile: "/path/to/seccomp.json",          apparmorProfile: "openclaw-sandbox",          dns: ["1.1.1.1", "8.8.8.8"],          extraHosts: ["internal.service:10.0.0.5"],          binds: ["/home/user/source:/source:rw"],        },        ssh: {          target: "user@gateway-host:22",          command: "ssh",          workspaceRoot: "/tmp/openclaw-sandboxes",          strictHostKeyChecking: true,          updateHostKeys: true,          identityFile: "~/.ssh/id_ed25519",          certificateFile: "~/.ssh/id_ed25519-cert.pub",          knownHostsFile: "~/.ssh/known_hosts",          // SecretRefs／インラインコンテンツにも対応:          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },        browser: {          enabled: false,          image: "openclaw-sandbox-browser:bookworm-slim",          network: "openclaw-sandbox-browser",          cdpPort: 9222,          cdpSourceRange: "172.21.0.1/32",          vncPort: 5900,          noVncPort: 6080,          headless: false,          enableNoVnc: true,          allowHostControl: false,          autoStart: true,          autoStartTimeoutMs: 12000,        },        prune: {          idleHours: 24,          maxAgeDays: 7,        },      },    },  },  tools: {    sandbox: {      tools: {        allow: [          "exec",          "process",          "read",          "write",          "edit",          "apply_patch",          "sessions_list",          "sessions_history",          "sessions_send",          "sessions_spawn",          "session_status",        ],        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],      },    },  },}

上記に示したデフォルト（off/docker/agent/none/bookworm-slim イメージ／none ネットワークなど）は、単なる例示値ではなく、実際の OpenClaw のデフォルトです。

{plugins: {  entries: {    openshell: {      enabled: true,      config: {        mode: "mirror", // mirror（デフォルト）| remote        command: "openshell",        from: "openclaw",        remoteWorkspaceDir: "/sandbox",        remoteAgentWorkspaceDir: "/agent",        gateway: "lab", // 任意        gatewayEndpoint: "https://lab.example", // 任意        policy: "strict", // 任意の OpenShell ポリシー ID        providers: ["openai"], // 任意        autoProviders: true,        timeoutSeconds: 120,      },    },  },},}

ブラウザのサンドボックス化と sandbox.docker.binds は Docker でのみ利用できます。

イメージをビルドする（ソースチェックアウトから）:

scripts/sandbox-setup.sh           # メインのサンドボックスイメージscripts/sandbox-browser-setup.sh   # 任意のブラウザイメージ

ソースチェックアウトを使用しない npm インストールについては、インラインの docker build コマンドを サンドボックス化 § イメージとセットアップで確認してください。

agents.list（エージェントごとのオーバーライド）

agents.list[].tts を使用すると、エージェントごとに独自の TTS プロバイダー、音声、モデル、 スタイル、または自動 TTS モードを指定できます。エージェントブロックはグローバルな messages.tts にディープマージされるため、共有認証情報を 1 か所に保持したまま、個々の エージェントは必要な音声またはプロバイダーフィールドのみをオーバーライドできます。アクティブなエージェントの オーバーライドは、自動音声応答、/tts audio、/tts status、および tts エージェントツールに適用されます。プロバイダーの例と優先順位については、 テキスト読み上げを参照してください。

{  agents: {    list: [      {        id: "main",        default: true,        name: "メインエージェント",        workspace: "~/.openclaw/workspace",        agentDir: "~/.openclaw/agents/main/agent",        model: "anthropic/claude-opus-4-6", // または { primary, fallbacks }        utilityModel: "openai/gpt-5.4-mini",        thinkingDefault: "high", // エージェントごとの思考レベルの上書き        reasoningDefault: "on", // エージェントごとの推論表示の上書き        fastModeDefault: false, // エージェントごとの高速モードの上書き        params: { cacheRetention: "none" }, // 一致する defaults.models のパラメーターをキー単位で上書き        tts: {          providers: {            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },        skills: ["docs-search"], // 設定した場合は agents.defaults.skills を置き換える        identity: {          name: "Samantha",          theme: "親切なナマケモノ",          emoji: "🦥",          avatar: "avatars/samantha.png",        },        groupChat: { mentionPatterns: ["@openclaw"] },        sandbox: { mode: "off" },        runtime: {          type: "acp",          acp: {            agent: "codex",            backend: "acpx",            mode: "persistent", // persistent | oneshot            cwd: "/workspace/openclaw",          },        },        subagents: { allowAgents: ["*"] },        tools: {          profile: "coding",          allow: ["browser"],          deny: ["canvas"],          elevated: { enabled: true },        },      },    ],  },}

• id: 安定したエージェント ID（必須）。
• default: 複数設定されている場合は、最初のものが優先されます（警告がログに記録されます）。どれも設定されていない場合は、リストの最初のエントリがデフォルトになります。
• model: 文字列形式では、モデルのフォールバックを使用しない厳密なエージェントごとのプライマリが設定されます。オブジェクト形式の { primary } も、fallbacks を追加しない限り厳密です。{ primary, fallbacks: [...] } を使用すると、そのエージェントでフォールバックを有効にできます。また、{ primary, fallbacks: [] } を使用すると厳密な動作を明示できます。primary のみを上書きする Cron ジョブは、fallbacks: [] を設定しない限り、引き続きデフォルトのフォールバックを継承します。
• utilityModel: 生成されるセッション名やスレッド名など、短い内部タスク向けの任意のエージェントごとの上書きです。agents.defaults.utilityModel、プライマリプロバイダーが宣言した小型モデルのデフォルト、このエージェントのプライマリモデルの順にフォールバックします。空文字列を指定すると、このエージェントのユーティリティルーティングが無効になります。
• params: agents.defaults.models で選択されたモデルエントリにマージされる、エージェントごとのストリームパラメーターです。モデルカタログ全体を複製せずに、cacheRetention、temperature、maxTokens などのエージェント固有の上書きを設定する場合に使用します。
• tts: 任意のエージェントごとのテキスト読み上げ設定の上書きです。このブロックは messages.tts にディープマージされるため、共有プロバイダーの認証情報とフォールバックポリシーは messages.tts に保持し、プロバイダー、音声、モデル、スタイル、自動モードなど、ペルソナ固有の値のみをここに設定してください。
• skills: 任意のエージェントごとの Skills 許可リストです。省略した場合、設定されていればエージェントは agents.defaults.skills を継承します。明示的なリストはデフォルトとマージせずに置き換え、[] は Skills なしを意味します。
• thinkingDefault: 任意のエージェントごとのデフォルト思考レベル（off | minimal | low | medium | high | xhigh | adaptive | max）です。メッセージ単位またはセッション単位の上書きが設定されていない場合、このエージェントでは agents.defaults.thinkingDefault を上書きします。選択したプロバイダー／モデルプロファイルによって、有効な値が決まります。Google Gemini では、adaptive によってプロバイダー管理の動的思考が維持されます（Gemini 3/3.1 では thinkingLevel を省略し、Gemini 2.5 では thinkingBudget: -1）。
• reasoningDefault: 任意のエージェントごとのデフォルト推論表示（on | off | stream）です。メッセージ単位またはセッション単位の推論の上書きが設定されていない場合、このエージェントでは agents.defaults.reasoningDefault を上書きします。
• fastModeDefault: 任意のエージェントごとの高速モードのデフォルト（"auto" | true | false）です。メッセージ単位またはセッション単位の高速モードの上書きが設定されていない場合に適用されます。
• models: 完全な provider/model ID をキーとする、任意のエージェントごとのモデルカタログ／ランタイムの上書きです。エージェントごとのランタイム例外には models["provider/model"].agentRuntime を使用します。
• runtime: 任意のエージェントごとのランタイム記述子です。エージェントで ACP ハーネスセッションをデフォルトにする場合は、runtime.acp のデフォルト（agent、backend、mode、cwd）とともに type: "acp" を使用します。
• identity.avatar: ワークスペース相対パス、http(s) URL、または data: URI。
• ローカルのワークスペース相対 identity.avatar 画像ファイルは 2 MB に制限されます。http(s) URL と data: URI は、ローカルファイルサイズの制限に対して検査されません。
• identity はデフォルトを導出します。ackReaction は emoji から、mentionPatterns は name/emoji から導出されます。
• subagents.allowAgents: 明示的な sessions_spawn.agentId ターゲットとして設定済みエージェント ID を指定する許可リストです（["*"] = 設定済みの任意のターゲット。デフォルト: 同じエージェントのみ）。自身をターゲットとする agentId 呼び出しを許可する場合は、要求元の ID を含めます。エージェント設定が削除された古いエントリは sessions_spawn によって拒否され、agents_list から除外されます。これらをクリーンアップするには openclaw doctor --fix を実行します。または、デフォルトを継承しながらそのターゲットを引き続き生成可能にする場合は、最小限の agents.list[] エントリを追加します。
• サンドボックス継承ガード: 要求元セッションがサンドボックス化されている場合、sessions_spawn はサンドボックス外で実行されるターゲットを拒否します。
• subagents.requireAgentId: true の場合、agentId を省略した sessions_spawn 呼び出しをブロックします（明示的なプロファイル選択を強制します。デフォルト: false）。
• subagents.maxConcurrent: サブエージェント実行全体における子エージェントの最大同時実行数です。デフォルト: 8。
• subagents.maxChildrenPerAgent: 1 つのエージェントセッションが生成できるアクティブな子の最大数です。デフォルト: 5。
• subagents.maxSpawnDepth: サブエージェント生成の最大ネスト深度（1～5）です。デフォルト: 1（ネストなし）。
• subagents.archiveAfterMinutes: 完了したサブエージェントの状態がアーカイブされるまでの期間です。デフォルト: 60。

マルチエージェントルーティング

1 つの Gateway 内で複数の分離されたエージェントを実行します。マルチエージェントを参照してください。

{  agents: {    list: [      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },      { id: "work", workspace: "~/.openclaw/workspace-work" },    ],  },  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },  ],}

バインディングの一致フィールド

• type（任意）: 通常のルーティングには route（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" エントリの場合、OpenClaw は正確な会話 ID（match.channel + アカウント + match.peer.id）によって解決し、前述のルートバインディングの階層順序は使用しません。

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

{agents: {  list: [    {      id: "personal",      workspace: "~/.openclaw/workspace-personal",      sandbox: { mode: "off" },    },  ],},}

{agents: {  list: [    {      id: "family",      workspace: "~/.openclaw/workspace-family",      sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },      tools: {        allow: [          "read",          "sessions_list",          "sessions_history",          "sessions_send",          "sessions_spawn",          "session_status",        ],        deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],      },    },  ],},}

{agents: {  list: [    {      id: "public",      workspace: "~/.openclaw/workspace-public",      sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },      tools: {        allow: [          "sessions_list",          "sessions_history",          "sessions_send",          "sessions_spawn",          "session_status",          "whatsapp",          "telegram",          "slack",          "discord",          "gateway",        ],        deny: [          "read",          "write",          "edit",          "apply_patch",          "exec",          "process",          "browser",          "canvas",          "nodes",          "cron",          "gateway",          "image",        ],      },    },  ],},}

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

セッション

{  session: {    scope: "per-sender",    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer    identityLinks: {      alice: ["telegram:123456789", "discord:987654321012345678"],    },    reset: {      mode: "daily", // daily | idle      atHour: 4,      idleMinutes: 60,    },    resetByType: {      thread: { mode: "daily", atHour: 4 },      direct: { mode: "idle", idleMinutes: 240 },      group: { mode: "idle", idleMinutes: 120 },    },    resetByChannel: {      discord: { mode: "idle", idleMinutes: 30 },    },    resetTriggers: ["/new", "/reset"],    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",    maintenance: {      mode: "enforce", // enforce（デフォルト）| warn      pruneAfter: "30d",      maxEntries: 500,      resetArchiveRetention: "30d", // 期間または false      maxDiskBytes: "500mb", // 任意のハード上限      highWaterBytes: "400mb", // 任意のクリーンアップ目標    },    writeLock: {      acquireTimeoutMs: 60000,      staleMs: 1800000,      maxHoldMs: 300000,    },    threadBindings: {      enabled: true,      idleHours: 24, // 非アクティブ時に自動的にフォーカスを解除するまでのデフォルト時間（時間単位。`0` で無効）      maxAgeHours: 0, // デフォルトの絶対最大存続時間（時間単位。`0` で無効）    },    mainKey: "main", // レガシー（ランタイムは常に "main" を使用）    agentToAgent: { maxPingPongTurns: 5 },    sendPolicy: {      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],      default: "allow",    },  },}

メッセージ

{  messages: {    responsePrefix: "🦞", // または "auto"    ackReaction: "👀",    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all | off | none    removeAckAfterReply: false,    queue: {      mode: "steer", // steer（デフォルト）| followup | collect | interrupt      debounceMs: 500,      cap: 20,      drop: "summarize", // old | new | summarize（デフォルト）      byChannel: {        whatsapp: "followup",        telegram: "followup",      },    },    inbound: {      debounceMs: 2000, // 0 で無効化      byChannel: {        whatsapp: 5000,        slack: 1500,      },    },  },}

応答の接頭辞

チャンネル／アカウントごとのオーバーライド: channels.<channel>.responsePrefix、channels.<channel>.accounts.<id>.responsePrefix。

解決順序（最も具体的な設定が優先）: アカウント → チャンネル → グローバル。"" は無効化し、カスケードを停止します。"auto" は [{identity.name}] を導出します。

テンプレート変数:

変数では大文字と小文字を区別しません。{think} は {thinkingLevel} のエイリアスです。

確認リアクション

• デフォルトではアクティブなエージェントの identity.emoji を使用し、それがなければ "👀" を使用します。無効にするには "" を設定します。
• チャンネルごとのオーバーライド: channels.<channel>.ackReaction、channels.<channel>.accounts.<id>.ackReaction。
• 解決順序: アカウント → チャンネル → messages.ackReaction → アイデンティティのフォールバック。
• スコープ: group-mentions（デフォルト）、group-all、direct、all、または off/none（確認リアクションを完全に無効化）。
• removeAckAfterReply: Slack、Discord、Signal、Telegram、WhatsApp、iMessage など、リアクションに対応するチャンネルで返信後に確認リアクションを削除します。
• messages.statusReactions.enabled: Slack、Discord、Signal、Telegram、WhatsApp でライフサイクルステータスのリアクションを有効にします。 Discord では、未設定の場合、確認リアクションがアクティブであればステータスリアクションも有効のままになります。 Slack、Signal、Telegram、WhatsApp では、ライフサイクルステータスのリアクションを有効にするため、明示的に true を設定してください。 Slack はデフォルトで、進行状況にネイティブのアシスタントスレッドステータスと切り替わる読み込みメッセージを使用し、設定された確認リアクションは固定のまま維持します。
• messages.statusReactions.emojis: ライフサイクル絵文字キーをオーバーライドします: queued、thinking、compacting、tool、coding、web、deploy、build、 concierge、done、error、stallSoft、および stallHard。 Telegram では使用できるリアクションが固定されているため、設定された未対応の絵文字は、 そのチャットでサポートされる最も近いステータスの種類にフォールバックします。

キュー

• mode: セッション実行中に到着した受信メッセージのキュー戦略。デフォルト: "steer"。
  • steer: 新しいプロンプトをアクティブな実行に挿入します。
  • followup: アクティブな実行が完了した後に、新しいプロンプトを実行します。
  • collect: 互換性のあるメッセージをまとめ、後で一括して実行します。
  • interrupt: 最新のプロンプトを開始する前に、アクティブな実行を中止します。
• debounceMs: キューに入れられた、または誘導されたメッセージをディスパッチするまでの遅延。デフォルト: 500。
• cap: ドロップポリシーを適用するまでにキューへ格納できるメッセージの最大数。デフォルト: 20。
• drop: 上限を超えた場合の戦略。"summarize"（デフォルト）は最も古いエントリを削除しますが、簡潔な要約は保持します。"old" は要約を残さずに最も古いエントリを削除し、"new" は最新の項目を拒否します。
• byChannel: プロバイダー ID をキーとする、チャンネルごとの mode オーバーライド。
• debounceMsByChannel: プロバイダー ID をキーとする、チャンネルごとの debounceMs オーバーライド。

受信デバウンス

同じ送信者から短時間に連続して届くテキストのみのメッセージを、エージェントの単一ターンにまとめます。メディア／添付ファイルは直ちにフラッシュされます。制御コマンドはデバウンスを迂回します。デフォルトの debounceMs: 2000。

その他のメッセージキー

• messages.messagePrefix: 受信したユーザーメッセージがエージェントランタイムに到達する前に付加される接頭辞テキスト。チャンネルコンテキストのマーカーとして必要最小限に使用してください。
• messages.visibleReplies: ダイレクト、グループ、チャンネルの各会話に表示される送信元への返信を制御します（"message_tool" で表示出力を行うには message(action=send) が必要です。"automatic" は従来どおり通常の返信を投稿します）。
• messages.usageTemplate / messages.responseUsage: カスタム /usage フッターテンプレートと、返信ごとのデフォルト使用モード（off | tokens | full、および tokens の従来のエイリアス on）。
• messages.groupChat.mentionPatterns / historyLimit: グループメッセージのメンショントリガーと履歴ウィンドウのサイズ指定。
• messages.suppressToolErrors: true の場合、ユーザーに表示される ⚠️ ツールエラー警告を抑制します（エージェントは引き続きコンテキスト内でエラーを認識し、再試行できます）。デフォルト: false。

TTS（テキスト読み上げ）

{  messages: {    tts: {      auto: "off", // off (default) | always | inbound | tagged      mode: "final", // final | all      provider: "elevenlabs",      summaryModel: "openai/gpt-5.4-mini",      modelOverrides: { enabled: true },      maxTextLength: 4000,      timeoutMs: 30000,      prefsPath: "~/.openclaw/settings/tts.json",      providers: {        elevenlabs: {          apiKey: "elevenlabs_api_key",          baseUrl: "https://api.elevenlabs.io",          speakerVoiceId: "voice_id",          modelId: "eleven_multilingual_v2",          seed: 42,          applyTextNormalization: "auto",          languageCode: "en",          voiceSettings: {            stability: 0.5,            similarityBoost: 0.75,            style: 0.0,            useSpeakerBoost: true,            speed: 1.0,          },        },        microsoft: {          speakerVoice: "en-US-MichelleNeural",          lang: "en-US",          outputFormat: "audio-24khz-48kbitrate-mono-mp3",        },        openai: {          apiKey: "openai_api_key",          baseUrl: "https://api.openai.com/v1",          model: "gpt-4o-mini-tts",          speakerVoice: "coral",        },      },    },  },}

• autoは、デフォルトの自動TTSモード（off、always、inbound、またはtagged）を制御します。/tts on|offでローカル設定を上書きでき、/tts statusで有効な状態を確認できます。
• summaryModelは、自動要約で使用するagents.defaults.model.primaryを上書きします。
• modelOverridesはデフォルトで有効です（enabled !== false）。modelOverrides.allowProviderは明示的な有効化が必要です。
• APIキーは、ELEVENLABS_API_KEY/XI_API_KEYおよびOPENAI_API_KEYにフォールバックします。
• 同梱の音声プロバイダーはPluginが所有します。plugins.allowが設定されている場合は、使用する各TTSプロバイダーPluginを含めてください。たとえば、Edge TTSにはmicrosoftを指定します。従来のプロバイダーID edgeは、microsoftのエイリアスとして受け入れられます。
• providers.openai.baseUrlは、OpenAI TTSエンドポイントを上書きします。解決順序は、設定、OPENAI_TTS_BASE_URL、https://api.openai.com/v1です。
• providers.openai.baseUrlがOpenAI以外のエンドポイントを指す場合、OpenClawはそれをOpenAI互換TTSサーバーとして扱い、モデルと音声の検証を緩和します。

Talk

Talkモード（macOS/iOS/AndroidおよびブラウザーのControl UI）のデフォルト設定です。

{  talk: {    provider: "elevenlabs",    providers: {      elevenlabs: {        speakerVoiceId: "elevenlabs_voice_id",        voiceAliases: {          Clawd: "EXAVITQu4vr4xnSDxMaL",          Roger: "CwhRBWXzGAHq8TQ4Fs17",        },        modelId: "eleven_multilingual_v2",        outputFormat: "mp3_44100_128",        apiKey: "elevenlabs_api_key",      },      mlx: {        modelId: "mlx-community/Soprano-80M-bf16",      },      system: {},    },    consultThinkingLevel: "low",    consultFastMode: true,    speechLocale: "ru-RU",    silenceTimeoutMs: 1500,    interruptOnSpeech: true,    realtime: {      provider: "openai",      providers: {        openai: {          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },      instructions: "Speak warmly and keep answers brief.",      mode: "realtime", // realtime | stt-tts | transcription      transport: "webrtc", // webrtc | provider-websocket | gateway-relay | managed-room      vadThreshold: 0.5,      silenceDurationMs: 500,      prefixPaddingMs: 300,      reasoningEffort: "medium",      brain: "agent-consult", // agent-consult | direct-tools | none    },  },}

• 複数のTalkプロバイダーを設定する場合、talk.providerはtalk.providers内のキーと一致する必要があります。
• 従来のフラットなTalkキー（talk.voiceId、talk.voiceAliases、talk.modelId、talk.outputFormat、talk.apiKey）は互換性維持専用です。openclaw doctor --fixを実行して、保存済み設定をtalk.providers.<provider>に書き換えてください。
• 音声IDは、ELEVENLABS_VOICE_IDまたはSAG_VOICE_IDにフォールバックします（macOS Talkクライアントの動作）。
• providers.*.apiKeyは、プレーンテキスト文字列またはSecretRefオブジェクトを受け入れます。
• ELEVENLABS_API_KEYへのフォールバックは、Talk APIキーが設定されていない場合にのみ適用されます。
• providers.*.voiceAliasesを使用すると、Talkディレクティブでわかりやすい名前を使用できます。
• providers.mlx.modelIdは、macOSのローカルMLXヘルパーが使用するHugging Faceリポジトリを選択します。省略した場合、macOSはmlx-community/Soprano-80M-bf16を使用します。
• macOSでのMLX再生は、同梱のopenclaw-mlx-ttsヘルパーが存在する場合はそれを経由し、存在しない場合はPATH上の実行可能ファイルを経由します。OPENCLAW_MLX_TTS_BINは、開発時のヘルパーパスを上書きします。
• consultThinkingLevelは、Control UI Talkのリアルタイムopenclaw_agent_consult呼び出しの背後で実行される完全なOpenClawエージェント実行の思考レベルを制御します。通常のセッションおよびモデルの動作を維持するには、未設定のままにしてください。
• consultFastModeは、セッションの通常の高速モード設定を変更せずに、Control UI Talkのリアルタイムコンサルトに対して1回限りの高速モード上書きを設定します。
• speechLocaleは、iOS/macOSのTalk音声認識で使用するBCP 47ロケールIDを設定します。デバイスのデフォルトを使用するには、未設定のままにしてください。
• silenceTimeoutMsは、ユーザーが話し終えてからTalkモードが文字起こしを送信するまでの待機時間を制御します。未設定の場合、プラットフォームのデフォルトの一時停止時間（700 ms on macOS and Android, 900 ms on iOS）が維持されます。
• realtime.instructionsは、OpenClawに組み込まれたリアルタイムプロンプトにプロバイダー向けのシステム指示を追加します。これにより、デフォルトのopenclaw_agent_consultガイダンスを失うことなく音声スタイルを設定できます。
• realtime.vadThresholdは、プロバイダーの音声アクティビティしきい値を0（最も高感度）から1（最も低感度）の範囲で設定します。未設定の場合、プロバイダーのデフォルトが維持されます。
• realtime.silenceDurationMsは、プロバイダーがリアルタイムのユーザーターンを確定するまでの無音時間を正の整数で設定します。未設定の場合、プロバイダーのデフォルトが維持されます。
• realtime.prefixPaddingMsは、音声の検出開始前に保持する音声量を負でない整数で設定します。未設定の場合、プロバイダーのデフォルトが維持されます。
• realtime.reasoningEffortは、リアルタイムセッションに対するプロバイダー固有の推論レベルを設定します。未設定の場合、プロバイダーのデフォルトが維持されます。
• realtime.consultRouting："provider-direct"（デフォルト）は、リアルタイムプロバイダーがopenclaw_agent_consultなしで最終的なユーザー文字起こしを生成した場合に、プロバイダーからの直接応答を維持します。代わりに、"force-agent-consult"は確定したリクエストをOpenClaw経由で処理します。

関連項目

• 設定リファレンス — その他すべての設定キー
• 設定 — 一般的なタスクとクイックセットアップ
• 設定例