Configuration 🔧

OpenClaw は ~/.openclaw/openclaw.json からオプションの JSON5 設定を読み込みます（コメントと末尾カンマが許可されています）。

ファイルが存在しない場合、OpenClaw は安全なデフォルト設定を使用します（埋め込み Pi エージェント + 送信者ごとのセッション + ワークスペース ~/.openclaw/workspace）。通常、設定ファイルが必要になるのは以下の場合のみです：

  • ボットをトリガーできるユーザーを制限する（channels.whatsapp.allowFrom、channels.telegram.allowFrom など）
  • グループの許可リストとメンション動作を制御する（channels.whatsapp.groups、channels.telegram.groups、channels.discord.guilds、agents.list[].groupChat）
  • メッセージプレフィックスをカスタマイズする（messages）
  • エージェントのワークスペースを設定する（agents.defaults.workspace または agents.list[].workspace）
  • 埋め込みエージェントのデフォルトとセッション動作を調整する（agents.defaults、session）
  • エージェントごとのアイデンティティを設定する（agents.list[].identity）

設定が初めてですか？ 詳細な説明付きの完全な例については、Configuration Examples ガイドをご確認ください！

厳密な設定検証

OpenClaw はスキーマに完全に一致する設定のみを受け入れます。 未知のキー、不正な型、または無効な値があると、安全のため Gateway は起動を拒否します。

検証が失敗した場合：

  • Gateway は起動しません。
  • 診断コマンドのみが許可されます（例：openclaw doctor、openclaw logs、openclaw health、openclaw status、openclaw service、openclaw help）。
  • openclaw doctor を実行して正確な問題を確認してください。
  • openclaw doctor --fix（または --yes）を実行してマイグレーション/修復を適用してください。

Doctor は明示的に --fix/--yes を選択しない限り、変更を書き込みません。

Schema + UI ヒント

Gateway は UI エディタ用に config.schema 経由で設定の JSON Schema 表現を公開します。 Control UI はこのスキーマからフォームをレンダリングし、Raw JSON エディタを緊急用のエスケープハッチとして提供します。

Channel プラグインと拡張機能は、設定のためにスキーマ + UI ヒントを登録できるため、channel 設定は ハードコードされたフォームなしでアプリ全体でスキーマ駆動のままになります。

ヒント（ラベル、グループ化、機密フィールド）はスキーマと一緒に提供されるため、クライアントは 設定の知識をハードコードすることなく、より良いフォームをレンダリングできます。

Apply + restart (RPC)

config.apply を使用して、完全な設定を検証 + 書き込みし、Gateway を一度に再起動します。 再起動センチネルを書き込み、Gateway が復帰した後、最後のアクティブセッションに ping を送信します。

警告：config.apply は設定全体を置き換えます。いくつかのキーのみを変更したい場合は、 config.patch または openclaw config set を使用してください。~/.openclaw/openclaw.json のバックアップを保持してください。

パラメータ：

  • raw（string）— 設定全体の JSON5 ペイロード
  • baseHash（オプション）— config.get から取得した設定ハッシュ（設定が既に存在する場合は必須）
  • sessionKey（オプション）— ウェイクアップ ping のための最後のアクティブセッションキー
  • note（オプション）— 再起動センチネルに含めるメモ
  • restartDelayMs（オプション）— 再起動前の遅延（デフォルト 2000）

例（gateway call 経由）：

openclaw gateway call config.get --params '{}' # payload.hash を取得
openclaw gateway call config.apply --params '{
  "raw": "{\\n  agents: { defaults: { workspace: \\"~/.openclaw/workspace\\" } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

部分更新（RPC）

config.patch を使用して、関連のないキーを上書きせずに、部分的な更新を既存の設定にマージします。 JSON merge patch のセマンティクスを適用します：

  • オブジェクトは再帰的にマージされます
  • null はキーを削除します
  • 配列は置き換えられます

config.apply と同様に、検証、設定の書き込み、再起動センチネルの保存を行い、 Gateway の再起動をスケジュールします（sessionKey が提供された場合はオプションのウェイクアップ付き）。

パラメータ：

  • raw（string）— 変更するキーのみを含む JSON5 ペイロード
  • baseHash（必須）— config.get から取得した設定ハッシュ
  • sessionKey（オプション）— ウェイクアップ ping のための最後のアクティブセッションキー
  • note（オプション）— 再起動センチネルに含めるメモ
  • restartDelayMs（オプション）— 再起動前の遅延（デフォルト 2000）

例：

openclaw gateway call config.get --params '{}' # payload.hash を取得
openclaw gateway call config.patch --params '{
  "raw": "{\\n  channels: { telegram: { groups: { \\"*\\": { requireMention: false } } } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

最小限の設定（推奨される出発点）

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}

次のコマンドでデフォルトイメージを一度ビルドします：

scripts/sandbox-setup.sh

セルフチャットモード（グループ制御に推奨）

グループ内の WhatsApp @メンションに応答しないようにする（特定のテキストトリガーのみに応答）：

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["@openclaw", "reisponde"] }
      }
    ]
  },
  channels: {
    whatsapp: {
      // 許可リストは DM のみ；自分の番号を含めることでセルフチャットモードが有効になります。
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  }
}

Config Includes（$include）

$include ディレクティブを使用して、設定を複数のファイルに分割できます。これは以下の場合に便利です：

  • 大規模な設定を整理する（例：クライアントごとのエージェント定義）
  • 環境間で共通設定を共有する
  • 機密設定を分離する

基本的な使用方法

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  
  // 単一ファイルをインクルード（キーの値を置き換えます）
  agents: { "$include": "./agents.json5" },
  
  // 複数ファイルをインクルード（順番にディープマージされます）
  broadcast: { 
    "$include": [
      "./clients/mueller.json5",
      "./clients/schmidt.json5"
    ]
  }
}

// ~/.openclaw/agents.json5
{
  defaults: { sandbox: { mode: "all", scope: "session" } },
  list: [
    { id: "main", workspace: "~/.openclaw/workspace" }
  ]
}

マージの動作

  • 単一ファイル：$include を含むオブジェクトを置き換えます
  • ファイルの配列：ファイルを順番にディープマージします（後のファイルが前のファイルを上書きします）
  • 兄弟キーとの併用：兄弟キーはインクルード後にマージされます（インクルードされた値を上書きします）
  • 兄弟キー + 配列/プリミティブ：サポートされていません（インクルードされるコンテンツはオブジェクトである必要があります）
// 兄弟キーはインクルードされた値を上書きします
{
  "$include": "./base.json5",   // { a: 1, b: 2 }
  b: 99                          // 結果：{ a: 1, b: 99 }
}

ネストされたインクルード

インクルードされたファイル自体も $include ディレクティブを含むことができます（最大10レベルの深さ）：

// clients/mueller.json5
{
  agents: { "$include": "./mueller/agents.json5" },
  broadcast: { "$include": "./mueller/broadcast.json5" }
}

パス解決

  • 相対パス：インクルードするファイルからの相対パスで解決されます
  • 絶対パス：そのまま使用されます
  • 親ディレクトリ：../ 参照は期待通りに機能します
{ "$include": "./sub/config.json5" }      // 相対
{ "$include": "/etc/openclaw/base.json5" } // 絶対
{ "$include": "../shared/common.json5" }   // 親ディレクトリ

エラー処理

  • ファイルが見つからない：解決されたパスを含む明確なエラー
  • パースエラー：失敗したインクルードファイルを表示
  • 循環インクルード：インクルードチェーンとともに検出され、報告されます

例：マルチクライアント法律事務所のセットアップ

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789, auth: { token: "secret" } },
  
  // 共通のエージェントデフォルト
  agents: {
    defaults: {
      sandbox: { mode: "all", scope: "session" }
    },
    // すべてのクライアントからエージェントリストをマージ
    list: { "$include": [
      "./clients/mueller/agents.json5",
      "./clients/schmidt/agents.json5"
    ]}
  },
  
  // ブロードキャスト設定をマージ
  broadcast: { "$include": [
    "./clients/mueller/broadcast.json5",
    "./clients/schmidt/broadcast.json5"
  ]},
  
  channels: { whatsapp: { groupPolicy: "allowlist" } }
}

// ~/.openclaw/clients/mueller/agents.json5
[
  { id: "mueller-transcribe", workspace: "~/clients/mueller/transcribe" },
  { id: "mueller-docs", workspace: "~/clients/mueller/docs" }
]

// ~/.openclaw/clients/mueller/broadcast.json5
{
  "[email protected]": ["mueller-transcribe", "mueller-docs"]
}

共通オプション

環境変数 + .env

OpenClaw は親プロセス（shell、launchd/systemd、CI など）から環境変数を読み込みます。

さらに、以下をロードします：

  • 現在の作業ディレクトリの .env（存在する場合）
  • ~/.openclaw/.env（別名 $OPENCLAW_STATE_DIR/.env）からのグローバルフォールバック .env

どちらの .env ファイルも既存の環境変数を上書きしません。

設定にインライン環境変数を提供することもできます。これらは プロセス環境にキーが存在しない場合にのみ適用されます（同じ非上書きルール）：

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-..."
    }
  }
}

完全な優先順位とソースについては /environment を参照してください。

env.shellEnv（オプション）

オプトイン便利機能：有効にすると、予想されるキーがまだ設定されていない場合、OpenClaw はログインシェルを実行し、不足している予想されるキーのみをインポートします（上書きはしません）。 これは効果的にシェルプロファイルをソースします。

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000
    }
  }
}

環境変数による設定：

  • OPENCLAW_LOAD_SHELL_ENV=1
  • OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

設定内での環境変数の置換

${VAR_NAME} 構文を使用して、任意の設定文字列値で環境変数を直接参照できます。 変数は検証前の設定ロード時に置換されます。

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}"
      }
    }
  },
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

ルール：

  • 大文字の環境変数名のみがマッチします：[A-Z_][A-Z0-9_]*
  • 存在しないまたは空の環境変数は設定ロード時にエラーをスローします
  • $${VAR} でエスケープしてリテラル ${VAR} を出力します
  • $include と連携します（インクルードされたファイルも置換が行われます）

インライン置換：

{
  models: {
    providers: {
      custom: {
        baseUrl: "${CUSTOM_API_BASE}/v1"  // → "https://api.example.com/v1"
      }
    }
  }
}

Auth ストレージ（OAuth + API キー）

OpenClaw はエージェントごとの認証プロファイル（OAuth + API キー）を以下に保存します：

  • <agentDir>/auth-profiles.json（デフォルト：~/.openclaw/agents/<agentId>/agent/auth-profiles.json）

参照：/concepts/oauth

レガシー OAuth インポート：

  • ~/.openclaw/credentials/oauth.json（または $OPENCLAW_STATE_DIR/credentials/oauth.json）

埋め込み Pi エージェントは以下の場所にランタイムキャッシュを保持します：

  • <agentDir>/auth.json（自動管理；手動編集しないでください）

レガシーエージェントディレクトリ（マルチエージェント以前）：

  • ~/.openclaw/agent/*（openclaw doctor によって ~/.openclaw/agents/<defaultAgentId>/agent/* に移行されます）

上書き：

  • OAuth ディレクトリ（レガシーインポートのみ）：OPENCLAW_OAUTH_DIR
  • エージェントディレクトリ（デフォルトエージェントルートの上書き）：OPENCLAW_AGENT_DIR（推奨）、PI_CODING_AGENT_DIR（レガシー）

初回使用時、OpenClaw は oauth.json エントリを auth-profiles.json にインポートします。

auth

認証プロファイルのオプションメタデータ。これはシークレットを保存しません； プロファイル ID をプロバイダー + モード（およびオプションのメール）にマッピングし、フェイルオーバーに使用されるプロバイダーのローテーション順序を定義します。

{
  auth: {
    profiles: {
      "anthropic:[email protected]": { provider: "anthropic", mode: "oauth", email: "[email protected]" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" }
    },
    order: {
      anthropic: ["anthropic:[email protected]", "anthropic:work"]
    }
  }
}

agents.list[].identity

デフォルトと UX に使用されるオプションのエージェントごとのアイデンティティ。これは macOS オンボーディングアシスタントによって書き込まれます。

設定されている場合、OpenClaw はデフォルト値を派生します（明示的に設定していない場合のみ）：

  • アクティブエージェントの identity.emoji から messages.ackReaction（👀 にフォールバック）
  • エージェントの identity.name/identity.emoji から agents.list[].groupChat.mentionPatterns（Telegram/Slack/Discord/Google Chat/iMessage/WhatsApp のグループで "@Samantha" が機能します）
  • identity.avatar はワークスペース相対の画像パスまたはリモート URL/data URL を受け入れます。ローカルファイルはエージェントワークスペース内に存在する必要があります。

identity.avatar が受け入れるもの：

  • ワークスペース相対パス（エージェントワークスペース内に留まる必要があります）
  • http(s) URL
  • data: URI
{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png"
        }
      }
    ]
  }
}

wizard

CLI ウィザード（onboard、configure、doctor）によって書き込まれるメタデータ。

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local"
  }
}

logging

  • デフォルトログファイル：/tmp/openclaw/openclaw-YYYY-MM-DD.log
  • 安定したパスが必要な場合は、logging.file を /tmp/openclaw/openclaw.log に設定します。
  • コンソール出力は個別に調整できます：
    • logging.consoleLevel（デフォルトは info、--verbose で debug に上がります）
    • logging.consoleStyle（pretty | compact | json）
  • ツールサマリーはシークレット漏洩を防ぐために編集できます：
    • logging.redactSensitive（off | tools、デフォルト：tools）
    • logging.redactPatterns（正規表現文字列の配列；デフォルトを上書きします）
{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
    redactPatterns: [
      // 例：独自のルールでデフォルトを上書きします。
      "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1",
      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi"
    ]
  }
}

channels.whatsapp.dmPolicy

WhatsApp のダイレクトチャット（DM）の処理方法を制御します：

  • "pairing"（デフォルト）：未知の送信者にはペアリングコードが送信されます；オーナーは承認する必要があります
  • "allowlist"：channels.whatsapp.allowFrom（またはペアリング済み許可ストア）内の送信者のみを許可します
  • "open"：すべての受信 DM を許可します（channels.whatsapp.allowFrom に "*" を含める必要があります）
  • "disabled"：すべての受信 DM を無視します

ペアリングコードは1時間後に期限切れになります；ボットは新しいリクエストが作成されたときのみペアリングコードを送信します。保留中の DM ペアリングリクエストは、デフォルトでチャンネルごとに3つに制限されています。

ペアリング承認：

  • openclaw pairing list whatsapp
  • openclaw pairing approve whatsapp <code>

channels.whatsapp.allowFrom

WhatsApp の自動返信をトリガーできる E.164 電話番号の許可リスト（DM のみ）。 空で channels.whatsapp.dmPolicy="pairing" の場合、未知の送信者はペアリングコードを受け取ります。 グループの場合は、channels.whatsapp.groupPolicy + channels.whatsapp.groupAllowFrom を使用します。

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000, // オプションの送信チャンクサイズ（文字数）
      chunkMode: "length", // オプションのチャンクモード（length | newline）
      mediaMaxMb: 50 // オプションの受信メディア上限（MB）
    }
  }
}

channels.whatsapp.sendReadReceipts

受信 WhatsApp メッセージを既読（青いチェック）としてマークするかどうかを制御します。デフォルト：true。

セルフチャットモードは、有効になっている場合でも常に既読通知をスキップします。

アカウントごとの上書き：channels.whatsapp.accounts.<id>.sendReadReceipts。

{
  channels: {
    whatsapp: { sendReadReceipts: false }
  }
}

channels.whatsapp.accounts（マルチアカウント）

1つの Gateway で複数の WhatsApp アカウントを実行：

{
  channels: {
    whatsapp: {
      accounts: {
        default: {}, // オプション；デフォルトの id を安定させます
        personal: {},
        biz: {
          // オプションの上書き。デフォルト：~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        }
      }
    }
  }
}

注意：

  • 送信コマンドは、default が存在する場合はそれをデフォルトとします；それ以外の場合は最初に設定されたアカウント id（ソート済み）。
  • レガシーシングルアカウント Baileys 認証ディレクトリは、openclaw doctor によって whatsapp/default に移行されます。

channels.telegram.accounts / channels.discord.accounts / channels.googlechat.accounts / channels.slack.accounts / channels.mattermost.accounts / channels.signal.accounts / channels.imessage.accounts

チャンネルごとに複数のアカウントを実行（各アカウントには独自の accountId とオプションの name があります）：

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC..."
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ..."
        }
      }
    }
  }
}

注意：

  • accountId が省略された場合は default が使用されます（CLI + ルーティング）。
  • 環境変数トークンはデフォルトアカウントにのみ適用されます。
  • ベースチャンネル設定（グループポリシー、メンションゲーティングなど）は、アカウントごとに上書きされない限り、すべてのアカウントに適用されます。
  • bindings[].match.accountId を使用して、各アカウントを異なる agents.defaults にルーティングします。

グループチャットのメンションゲーティング（agents.list[].groupChat + messages.groupChat）

グループメッセージはデフォルトでメンションを要求します（メタデータメンションまたは正規表現パターンのいずれか）。WhatsApp、Telegram、Discord、Google Chat、iMessage グループチャットに適用されます。

メンションタイプ：

  • メタデータメンション：ネイティブプラットフォームの @メンション（例：WhatsApp のタップしてメンション）。WhatsApp セルフチャットモードでは無視されます（channels.whatsapp.allowFrom を参照）。
  • テキストパターン：agents.list[].groupChat.mentionPatterns で定義された正規表現パターン。セルフチャットモードに関係なく常にチェックされます。
  • メンションゲーティングは、メンション検出が可能な場合（ネイティブメンションまたは少なくとも1つの mentionPattern）にのみ適用されます。
{
  messages: {
    groupChat: { historyLimit: 50 }
  },
  agents: {
    list: [
      { id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }
    ]
  }
}

messages.groupChat.historyLimit はグループ履歴コンテキストのグローバルデフォルトを設定します。チャンネルは channels.<channel>.historyLimit（またはマルチアカウントの場合は channels.<channel>.accounts.*.historyLimit）で上書きできます。履歴ラッピングを無効にするには 0 に設定します。

DM 履歴制限

DM 会話は、エージェントによって管理されるセッションベースの履歴を使用します。DM セッションごとに保持されるユーザーターン数を制限できます：

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,  // DM セッションを30ユーザーターンに制限
      dms: {
        "123456789": { historyLimit: 50 }  // ユーザーごとの上書き（ユーザー ID）
      }
    }
  }
}

解決順序：

  1. DM ごとの上書き：channels.<provider>.dms[userId].historyLimit
  2. プロバイダーデフォルト：channels.<provider>.dmHistoryLimit
  3. 制限なし（すべての履歴を保持）

サポートされているプロバイダー：telegram、whatsapp、discord、slack、signal、imessage、msteams。

エージェントごとの上書き（設定された場合は優先されます、[] でも）：

{
  agents: {
    list: [
      { id: "work", groupChat: { mentionPatterns: ["@workbot", "\\+15555550123"] } },
      { id: "personal", groupChat: { mentionPatterns: ["@homebot", "\\+15555550999"] } }
    ]
  }
}

メンションゲーティングのデフォルトはチャンネルごとに存在します（channels.whatsapp.groups、channels.telegram.groups、channels.imessage.groups、channels.discord.guilds）。*.groups が設定されている場合、グループ許可リストとしても機能します；すべてのグループを許可するには "*" を含めます。

特定のテキストトリガーのみに応答する（ネイティブ @メンションを無視する）：

{
  channels: {
    whatsapp: {
      // セルフチャットモードを有効にするには自分の番号を含めます（ネイティブ @メンションを無視）。
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          // これらのテキストパターンのみが応答をトリガーします
          mentionPatterns: ["reisponde", "@openclaw"]
        }
      }
    ]
  }
}

グループポリシー（チャンネルごと）

channels.*.groupPolicy を使用して、グループ/ルームメッセージが受け入れられるかどうかを制御します：

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"]
    },
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["tg:123456789", "@alice"]
    },
    signal: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"]
    },
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["chat_id:123"]
    },
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["[email protected]"]
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        "GUILD_ID": {
          channels: { help: { allow: true } }
        }
      }
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } }
    }
  }
}

注意：

  • "open"：グループは許可リストをバイパスします；メンションゲーティングは引き続き適用されます。
  • "disabled"：すべてのグループ/ルームメッセージをブロックします。
  • "allowlist"：設定された許可リストに一致するグループ/ルームのみを許可します。
  • channels.defaults.groupPolicy は、プロバイダーの groupPolicy が未設定の場合のデフォルトを設定します。
  • WhatsApp/Telegram/Signal/iMessage/Microsoft Teams は groupAllowFrom を使用します（フォールバック：明示的な allowFrom）。
  • Discord/Slack はチャンネル許可リストを使用します（channels.discord.guilds.*.channels、channels.slack.channels）。
  • グループ DM（Discord/Slack）は引き続き dm.groupEnabled + dm.groupChannels によって制御されます。
  • デフォルトは groupPolicy: "allowlist" です（channels.defaults.groupPolicy によって上書きされない限り）；許可リストが設定されていない場合、グループメッセージはブロックされます。

マルチエージェントルーティング（agents.list + bindings）

1つの Gateway 内で複数の分離されたエージェント（別々のワークスペース、agentDir、セッション）を実行します。 受信メッセージはバインディングを介してエージェントにルーティングされます。

  • agents.list[]：エージェントごとの上書き。
    • id：安定したエージェント ID（必須）。
    • default：オプション；複数設定されている場合、最初のものが優先され、警告がログに記録されます。 何も設定されていない場合、リストの最初のエントリがデフォルトエージェントになります。
    • name：エージェントの表示名。
    • workspace：デフォルト ~/.openclaw/workspace-<agentId>（main の場合、agents.defaults.workspace にフォールバック）。
    • agentDir：デフォルト ~/.openclaw/agents/<agentId>/agent。
    • model：エージェントごとのデフォルトモデル、そのエージェントの agents.defaults.model を上書きします。
      • 文字列形式："provider/model"、agents.defaults.model.primary のみを上書きします
      • オブジェクト形式：{ primary, fallbacks }（fallbacks は agents.defaults.model.fallbacks を上書きします；[] はそのエージェントのグローバルフォールバックを無効にします）
    • identity：エージェントごとの名前/テーマ/絵文字（メンションパターン + 確認リアクションに使用されます）。
    • groupChat：エージェントごとのメンションゲーティング（mentionPatterns）。
    • sandbox：エージェントごとの sandbox 設定（agents.defaults.sandbox を上書き）。
      • mode："off" | "non-main" | "all"
      • workspaceAccess："none" | "ro" | "rw"
      • scope："session" | "agent" | "shared"
      • workspaceRoot：カスタム sandbox ワークスペースルート
      • docker：エージェントごとの docker 上書き（例：image、network、env、setupCommand、制限；scope: "shared" の場合は無視されます）
      • browser：エージェントごとの sandbox ブラウザ上書き（scope: "shared" の場合は無視されます）
      • prune：エージェントごとの sandbox プルーニング上書き（scope: "shared" の場合は無視されます）
    • subagents：エージェントごとのサブエージェントデフォルト。
      • allowAgents：このエージェントからの sessions_spawn のためのエージェント ID 許可リスト（["*"] = 任意を許可；デフォルト：同じエージェントのみ）
    • tools：エージェントごとのツール制限（sandbox ツールポリシーの前に適用されます）。
      • profile：ベースツールプロファイル（allow/deny の前に適用されます）
      • allow：許可されたツール名の配列
      • deny：拒否されたツール名の配列（deny が優先されます）
  • agents.defaults：共有エージェントデフォルト（モデル、ワークスペース、sandbox など）。
  • bindings[]：受信メッセージを agentId にルーティングします。
    • match.channel（必須）
    • match.accountId（オプション；* = 任意のアカウント；省略 = デフォルトアカウント）
    • match.peer（オプション；{ kind: dm|group|channel, id }）
    • match.guildId / match.teamId（オプション；チャンネル固有）

決定論的なマッチ順序：

  1. match.peer
  2. match.guildId
  3. match.teamId
  4. match.accountId（正確、peer/guild/team なし）
  5. match.accountId: "*"（チャンネル全体、peer/guild/team なし）
  6. デフォルトエージェント（agents.list[].default、それ以外は最初のリストエントリ、それ以外は "main"）

各マッチ層内では、bindings の最初に一致するエントリが優先されます。

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

各エージェントは独自の sandbox + ツールポリシーを持つことができます。これを使用して、1つの Gateway でアクセスレベルを混在させます：

  • フルアクセス（個人エージェント）
  • 読み取り専用ツール + ワークスペース
  • ファイルシステムアクセスなし（メッセージング/セッションツールのみ）

優先順位と追加の例については、Multi-Agent Sandbox & Tools を参照してください。

フルアクセス（sandbox なし）：

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

読み取り専用ツール + 読み取り専用ワークスペース：

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",
          scope: "agent",
例：Opus 4.5 をプライマリとして MiniMax M2.1 をフォールバックとして使用（ホスト型 MiniMax）：

```json5
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-5": { alias: "opus" },
        "minimax/MiniMax-M2.1": { alias: "minimax" }
      },
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: ["minimax/MiniMax-M2.1"]
      }
    }
  }
}

MiniMax 認証：MINIMAX_API_KEY（環境変数）を設定するか、models.providers.minimax を設定してください。

agents.defaults.cliBackends（CLI フォールバック）

テキスト専用フォールバック実行（ツール呼び出しなし）用のオプションの CLI バックエンド。これらは API プロバイダーが失敗したときのバックアップパスとして役立ちます。ファイルパスを受け入れる imageArg を設定すると、画像のパススルーがサポートされます。

注意事項：

  • CLI バックエンドは テキスト優先 です。ツールは常に無効化されます。
  • sessionArg が設定されている場合、セッションがサポートされます。セッション ID はバックエンドごとに永続化されます。
  • claude-cli の場合、デフォルトが組み込まれています。PATH が最小限の場合（launchd/systemd）、コマンドパスを上書きしてください。

例：

{
  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",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat"
        }
      }
    }
  }
}

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-5": { alias: "Opus" },
        "anthropic/claude-sonnet-4-1": { alias: "Sonnet" },
        "openrouter/deepseek/deepseek-r1:free": {},
        "zai/glm-4.7": {
          alias: "GLM",
          params: {
            thinking: {
              type: "enabled",
              clear_thinking: false
            }
          }
        }
      },
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: [
          "openrouter/deepseek/deepseek-r1:free",
          "openrouter/meta-llama/llama-3.3-70b-instruct:free"
        ]
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: [
          "openrouter/google/gemini-2.0-flash-vision:free"
        ]
      },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      heartbeat: {
        every: "30m",
        target: "last"
      },
      maxConcurrent: 3,
      subagents: {
        model: "minimax/MiniMax-M2.1",
        maxConcurrent: 1,
        archiveAfterMinutes: 60
      },
      exec: {
        backgroundMs: 10000,
        timeoutSec: 1800,
        cleanupMs: 1800000
      },
      contextTokens: 200000
    }
  }
}

agents.defaults.contextPruning（ツール結果のプルーニング）

agents.defaults.contextPruning は、リクエストが LLM に送信される直前に、メモリ内コンテキストから 古いツール結果 をプルーニングします。ディスク上のセッション履歴（*.jsonl は完全に保持）は変更しません。

これは、時間の経過とともに大量のツール出力を蓄積するおしゃべりなエージェントのトークン使用量を削減することを目的としています。

概要：

  • ユーザー/アシスタントメッセージには一切触れません。
  • 最後の keepLastAssistants 個のアシスタントメッセージを保護します（その後のツール結果はプルーニングされません）。
  • ブートストラッププレフィックスを保護します（最初のユーザーメッセージより前のものはプルーニングされません）。
  • モード：
    • adaptive：推定コンテキスト比が softTrimRatio を超えると、サイズが大きすぎるツール結果をソフトトリム（先頭/末尾を保持）します。その後、推定コンテキスト比が hardClearRatio を超え、かつ プルーニング可能なツール結果の総量（minPrunableToolChars）が十分にある場合、最も古い対象ツール結果をハードクリアします。
    • aggressive：常にカットオフより前の対象ツール結果を hardClear.placeholder に置き換えます（比率チェックなし）。

ソフトプルーニング vs ハードプルーニング（LLM に送信されるコンテキストで何が変わるか）：

  • ソフトトリム：サイズが大きすぎる ツール結果のみ対象。先頭と末尾を保持し、中央に ... を挿入します。
    • 変更前：toolResult("…非常に長い出力…")
    • 変更後：toolResult("HEAD…\n...\n…TAIL\n\n[Tool result trimmed: …]")
  • ハードクリア：ツール結果全体をプレースホルダーに置き換えます。
    • 変更前：toolResult("…非常に長い出力…")
    • 変更後：toolResult("[Old tool result content cleared]")

注意事項 / 現在の制限事項：

  • 画像ブロックを含むツール結果はスキップされます（現時点ではトリム/クリアされません）。
  • 推定「コンテキスト比」は 文字数 に基づいており（概算）、正確なトークン数ではありません。
  • セッションにまだ keepLastAssistants 個のアシスタントメッセージが含まれていない場合、プルーニングはスキップされます。
  • aggressive モードでは、hardClear.enabled は無視されます（対象のツール結果は常に hardClear.placeholder に置き換えられます）。

デフォルト（adaptive）：

{
  agents: { defaults: { contextPruning: { mode: "adaptive" } } }
}

無効化する場合：

{
  agents: { defaults: { contextPruning: { mode: "off" } } }
}

デフォルト値（mode が "adaptive" または "aggressive" の場合）：

  • keepLastAssistants: 3
  • softTrimRatio: 0.3（adaptive のみ）
  • hardClearRatio: 0.5（adaptive のみ）
  • minPrunableToolChars: 50000（adaptive のみ）
  • softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }（adaptive のみ）
  • hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }

例（aggressive、最小構成）：

{
  agents: { defaults: { contextPruning: { mode: "aggressive" } } }
}

例（adaptive 調整済み）：

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "adaptive",
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        // オプション：特定のツールにプルーニングを制限（deny が優先、"*" ワイルドカードサポート）
        tools: { deny: ["browser", "canvas"] },
      }
    }
  }
}

動作の詳細については、/concepts/session-pruning を参照してください。

agents.defaults.compaction（ヘッドルーム予約 + メモリフラッシュ）

agents.defaults.compaction.mode はコンパクション要約戦略を選択します。デフォルトは default です。非常に長い履歴に対してチャンク化された要約を有効にするには、safeguard を設定してください。/concepts/compaction を参照してください。

agents.defaults.compaction.reserveTokensFloor は、Pi コンパクションの最小 reserveTokens 値を強制します（デフォルト：20000）。フロアを無効にするには 0 に設定してください。

agents.defaults.compaction.memoryFlush は、自動コンパクション前に サイレントな エージェントターンを実行し、モデルに永続的なメモリをディスクに保存するよう指示します（例：memory/YYYY-MM-DD.md）。セッショントークン推定値がコンパクション制限以下のソフト閾値を超えるとトリガーされます。

レガシーデフォルト：

  • memoryFlush.enabled: true
  • memoryFlush.softThresholdTokens: 4000
  • memoryFlush.prompt / memoryFlush.systemPrompt: NO_REPLY を含む組み込みデフォルト
  • 注意：セッションワークスペースが読み取り専用の場合（agents.defaults.sandbox.workspaceAccess: "ro" または "none"）、メモリフラッシュはスキップされます。

例（調整済み）：

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard",
        reserveTokensFloor: 24000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

ブロックストリーミング：

  • agents.defaults.blockStreamingDefault: "on"/"off"（デフォルトは off）。
  • チャネルオーバーライド：*.blockStreaming（およびアカウントごとのバリアント）で、ブロックストリーミングを強制的にオン/オフできます。非 Telegram チャネルでブロック返信を有効にするには、明示的に *.blockStreaming: true が必要です。
  • agents.defaults.blockStreamingBreak: "text_end" または "message_end"（デフォルト：text_end）。
  • agents.defaults.blockStreamingChunk：ストリーミングされたブロックのソフトチャンキング。デフォルトは 800～1200 文字で、段落区切り（\n\n）、改行、文を優先します。 例： 
    {
  agents: { defaults: { blockStreamingChunk: { minChars: 800, maxChars: 1200 } } }
}
  • agents.defaults.blockStreamingCoalesce：送信前にストリーミングされたブロックをマージします。デフォルトは { idleMs: 1000 } で、blockStreamingChunk から minChars を継承し、maxChars はチャネルのテキスト制限に制限されます。Signal/Slack/Discord/Google Chat はオーバーライドされない限り、デフォルトで minChars: 1500 になります。 チャネルオーバーライド：channels.whatsapp.blockStreamingCoalesce、channels.telegram.blockStreamingCoalesce、channels.discord.blockStreamingCoalesce、channels.slack.blockStreamingCoalesce、channels.mattermost.blockStreamingCoalesce、channels.signal.blockStreamingCoalesce、channels.imessage.blockStreamingCoalesce、channels.msteams.blockStreamingCoalesce、channels.googlechat.blockStreamingCoalesce（およびアカウントごとのバリアント）。
  • agents.defaults.humanDelay：最初の返信後の ブロック返信 間のランダム化された一時停止。モード：off（デフォルト）、natural（800～2500ms）、custom（minMs/maxMs を使用）。エージェントごとのオーバーライド：agents.list[].humanDelay。 例： 
    {
  agents: { defaults: { humanDelay: { mode: "natural" } } }
}

動作とチャンキングの詳細については、/concepts/streaming を参照してください。

タイピングインジケーター：

  • agents.defaults.typingMode: "never" | "instant" | "thinking" | "message"。ダイレクトチャット/メンションのデフォルトは instant、メンションされていないグループチャットのデフォルトは message です。
  • session.typingMode：モードのセッションごとのオーバーライド。
  • agents.defaults.typingIntervalSeconds：タイピングシグナルの更新頻度（デフォルト：6秒）。
  • session.typingIntervalSeconds：更新間隔のセッションごとのオーバーライド。 動作の詳細については、/concepts/typing-indicators を参照してください。

agents.defaults.model.primary は provider/model として設定する必要があります（例：anthropic/claude-opus-4-5）。エイリアスは agents.defaults.models.*.alias から取得されます（例：Opus）。プロバイダーを省略すると、OpenClaw は現在、一時的な非推奨フォールバックとして anthropic を想定します。

Z.AI モデルは zai/<model>（例：zai/glm-4.7）として利用可能で、環境に ZAI_API_KEY（またはレガシー Z_AI_API_KEY）が必要です。

agents.defaults.heartbeat は定期的なハートビート実行を設定します：

  • every：期間文字列（ms、s、m、h）。デフォルト単位は分。デフォルト：30m。無効にするには 0m を設定します。
  • model：ハートビート実行用のオプションのオーバーライドモデル（provider/model）。
  • includeReasoning：true の場合、利用可能な場合、ハートビートは別の Reasoning: メッセージも配信します（/reasoning on と同じ形式）。デフォルト：false。
  • session：ハートビートが実行されるセッションを制御するオプションのセッションキー。デフォルト：main。
  • to：オプションの受信者オーバーライド（チャネル固有の ID、例：WhatsApp の E.164、Telegram のチャット ID）。
  • target：オプションの配信チャネル（last、whatsapp、telegram、discord、slack、msteams、signal、imessage、none）。デフォルト：last。
  • prompt：ハートビート本文のオプションのオーバーライド（デフォルト：Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.）。オーバーライドはそのまま送信されます。ファイルを読み込みたい場合は、Read HEARTBEAT.md 行を含めてください。
  • ackMaxChars：配信前に HEARTBEAT_OK の後に許可される最大文字数（デフォルト：300）。

エージェントごとのハートビート：

  • agents.list[].heartbeat を設定して、特定のエージェントのハートビート設定を有効にするか、オーバーライドします。
  • いずれかのエージェントエントリが heartbeat を定義している場合、それらのエージェントのみ がハートビートを実行します。デフォルトは、それらのエージェントの共有ベースラインになります。

ハートビートは完全なエージェントターンを実行します。間隔を短くするとトークンが多く消費されます。every に注意し、HEARTBEAT.md を小さく保ち、かつ/または安価な model を選択してください。

tools.exec はバックグラウンド exec のデフォルトを設定します：

  • backgroundMs：自動バックグラウンド化までの時間（ms、デフォルト 10000）
  • timeoutSec：この実行時間後に自動キル（秒、デフォルト 1800）
  • cleanupMs：完了したセッションをメモリに保持する時間（ms、デフォルト 1800000）
  • notifyOnExit：バックグラウンド化された exec が終了したときにシステムイベントをエンキューし、ハートビートをリクエストします（デフォルト true）
  • applyPatch.enabled：実験的な apply_patch を有効にします（OpenAI/OpenAI Codex のみ、デフォルト false）
  • applyPatch.allowModels：モデル ID のオプションの許可リスト（例：gpt-5.2 または openai/gpt-5.2） 注意：applyPatch は tools.exec 内のみです。

tools.web はウェブ検索 + フェッチツールを設定します：

  • tools.web.search.enabled（デフォルト：キーが存在する場合は true）
  • tools.web.search.apiKey（推奨：openclaw configure --section web で設定するか、BRAVE_API_KEY 環境変数を使用）
  • tools.web.search.maxResults（1～10、デフォルト 5）
  • tools.web.search.timeoutSeconds（デフォルト 30）
  • tools.web.search.cacheTtlMinutes（デフォルト 15）
  • tools.web.fetch.enabled（デフォルト true）
  • tools.web.fetch.maxChars（デフォルト 50000）
  • tools.web.fetch.timeoutSeconds（デフォルト 30）
  • tools.web.fetch.cacheTtlMinutes（デフォルト 15）
  • tools.web.fetch.userAgent（オプションのオーバーライド）
  • tools.web.fetch.readability（デフォルト true。基本的な HTML クリーンアップのみを使用するには無効にします）
  • tools.web.fetch.firecrawl.enabled（API キーが設定されている場合、デフォルト true）
  • tools.web.fetch.firecrawl.apiKey（オプション。デフォルトは FIRECRAWL_API_KEY）
  • tools.web.fetch.firecrawl.baseUrl（デフォルト https://api.firecrawl.dev）
  • tools.web.fetch.firecrawl.onlyMainContent（デフォルト true）
  • tools.web.fetch.firecrawl.maxAgeMs（オプション）
  • tools.web.fetch.firecrawl.timeoutSeconds（オプション）

tools.media はインバウンドメディア理解（画像/音声/ビデオ）を設定します：

  • tools.media.models：共有モデルリスト（機能タグ付き。機能ごとのリストの後に使用されます）。
  • tools.media.concurrency：最大同時機能実行数（デフォルト 2）。
  • tools.media.image / tools.media.audio / tools.media.video：
    • enabled：オプトアウトスイッチ（モデルが設定されている場合、デフォルト true）。
    • prompt：オプションのプロンプトオーバーライド（image/video は maxChars ヒントを自動的に追加します）。
    • maxChars：最大出力文字数（デフォルト：image/video は 500、audio は未設定）。
    • maxBytes：送信する最大メディアサイズ（デフォルト：image 10MB、audio 20MB、video 50MB）。
    • timeoutSeconds：リクエストタイムアウト（デフォルト：image 60秒、audio 60秒、video 120秒）。
    • language：オプションの音声ヒント。
    • attachments：添付ファイルポリシー（mode、maxAttachments、prefer）。
    • scope：オプションのゲーティング（最初の一致が優先）。match.channel、match.chatType、または match.keyPrefix を使用します。
    • models：モデルエントリの順序付きリスト。失敗または大きすぎるメディアは次のエントリにフォールバックします。
  • 各 models[] エントリ：
    • プロバイダーエントリ（type: "provider" または省略）：
      • provider：API プロバイダー ID（openai、anthropic、google/gemini、groq など）。
      • model：モデル ID オーバーライド（image には必須。audio プロバイダーのデフォルトは gpt-4o-mini-transcribe/whisper-large-v3-turbo、video のデフォルトは gemini-3-flash-preview）。
      • profile / preferredProfile：認証プロファイル選択。
    • CLI エントリ（type: "cli"）：
      • command：実行する実行ファイル。
      • args：テンプレート化された引数（{{MediaPath}}、{{Prompt}}、{{MaxChars}} などをサポート）。
    • capabilities：オプションのリスト（image、audio、video）。共有エントリをゲートします。省略時のデフォルト：openai/anthropic/minimax → image、google → image+audio+video、groq → audio。
    • prompt、maxChars、maxBytes、timeoutSeconds、language はエントリごとにオーバーライドできます。

モデルが設定されていない場合（または enabled: false の場合）、理解はスキップされます。モデルは元の添付ファイルを受け取ります。

プロバイダー認証は、標準のモデル認証順序（認証プロファイル、OPENAI_API_KEY/GROQ_API_KEY/GEMINI_API_KEY などの環境変数、または models.providers.*.apiKey）に従います。

例：

{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        scope: {
          default: "deny",
          rules: [{ action: "allow", match: { chatType: "direct" } }]
        },
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
        ]
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }]
      }
    }
  }
}

agents.defaults.subagents はサブエージェントのデフォルトを設定します：

  • model：生成されたサブエージェントのデフォルトモデル（文字列または { primary, fallbacks }）。省略した場合、サブエージェントは、エージェントごとまたは呼び出しごとにオーバーライドされない限り、呼び出し元のモデルを継承します。
  • maxConcurrent：最大同時サブエージェント実行数（デフォルト 1）
  • archiveAfterMinutes：N 分後にサブエージェントセッションを自動アーカイブ（デフォルト 60。無効にするには 0 を設定）
  • サブエージェントごとのツールポリシー：tools.subagents.tools.allow / tools.subagents.tools.deny（deny が優先）

tools.profile は、tools.allow/tools.deny の前に ベースツール許可リスト を設定します：

  • 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：制限なし（未設定と同じ）

エージェントごとのオーバーライド：agents.list[].tools.profile。

例（デフォルトでメッセージングのみ、Slack + Discord ツールも許可）：

{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"]
  }
}

例（コーディングプロファイル、ただしどこでも exec/process を拒否）：

{
  tools: {
    profile: "coding",
    deny: ["group:runtime"]
  }
}

tools.byProvider を使用すると、特定のプロバイダー（または単一の provider/model）のツールを さらに制限 できます。エージェントごとのオーバーライド：agents.list[].tools.byProvider。

順序：ベースプロファイル → プロバイダープロファイル → allow/deny ポリシー。 プロバイダーキーは、provider（例：google-antigravity）または provider/model（例：openai/gpt-5.2）を受け入れます。

例（グローバルコーディングプロファイルを維持しつつ、Google Antigravity では最小限のツール）：

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" }
    }
  }
}

例（provider/model 固有の許可リスト）：

{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] }
    }
  }
}

tools.allow / tools.deny はグローバルツールの allow/deny ポリシーを設定します（deny が優先）。マッチングは大文字小文字を区別せず、* ワイルドカードをサポートします（"*" はすべてのツールを意味します）。これは Docker サンドボックスが オフ の場合でも適用されます。

例（どこでも browser/canvas を無効化）：

{
  tools: { deny: ["browser", "canvas"] }
}

ツールグループ（短縮形）は グローバル および エージェントごと のツールポリシーで機能します：

  • group:runtime：exec、bash、process
  • 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：すべての組み込み OpenClaw ツール（プロバイダープラグインを除く）

tools.elevated は昇格した（ホスト）exec アクセスを制御します：

  • enabled：昇格モードを許可（デフォルト true）
  • allowFrom：チャネルごとの許可リスト（空 = 無効）
    • whatsapp：E.164 番号
    • telegram：チャット ID またはユーザー名
    • discord：ユーザー ID またはユーザー名（省略時は channels.discord.dm.allowFrom にフォールバック）
    • signal：E.164 番号
    • imessage：ハンドル/チャット ID
    • webchat：セッション ID またはユーザー名

例：

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["steipete", "1234567890123"]
      }
    }
  }
}

エージェントごとのオーバーライド（さらに制限）：

{
  agents: {
    list: [
      {
        id: "family",
        tools: {
          elevated: { enabled: false }
        }
      }
    ]
  }
}

注意事項：

  • tools.elevated はグローバルベースラインです。agents.list[].tools.elevated はさらに制限することのみ可能です（両方が許可する必要があります）。
  • /elevated on|off|ask|full はセッションキーごとに状態を保存します。インラインディレクティブは単一のメッセージに適用されます。
  • 昇格した exec はホスト上で実行され、サンドボックス化をバイパスします。
  • ツールポリシーは引き続き適用されます。exec が拒否されている場合、昇格は使用できません。

agents.defaults.maxConcurrent は、セッション全体で並行して実行できる組み込みエージェント実行の最大数を設定します。各セッションは引き続きシリアライズされます（セッションキーごとに一度に 1 つの実行）。デフォルト：1。

agents.defaults.sandbox

組み込みエージェント用のオプションの Docker サンドボックス化。メインセッション以外でホストシステムにアクセスできないようにすることを目的としています。

詳細：Sandboxing

デフォルト（有効な場合）：

  • scope："agent"（エージェントごとに 1 つのコンテナ + ワークスペース）
  • Debian bookworm-slim ベースのイメージ
  • エージェントワークスペースアクセス：workspaceAccess: "none"（デフォルト）
    • "none"：~/.openclaw/sandboxes 下のスコープごとのサンドボックスワークスペースを使用
    • "ro"：サンドボックスワークスペースを /workspace に保持し、エージェントワークスペースを読み取り専用で /agent にマウント（write/edit/apply_patch を無効化）
    • "rw"：エージェントワークスペースを読み取り/書き込み可能で /workspace にマウント
  • 自動プルーニング：アイドル > 24時間 OR 経過時間 > 7日
  • ツールポリシー：exec、process、read、write、edit、apply_patch、sessions_list、sessions_history、sessions_send、sessions_spawn、session_status のみ許可（deny が優先）
    • tools.sandbox.tools で設定、エージェントごとに agents.list[].tools.sandbox.tools でオーバーライド
    • サンドボックスポリシーでツールグループの短縮形をサポート：group:runtime、group:fs、group:sessions、group:memory（Sandbox vs Tool Policy vs Elevated を参照）
  • オプションのサンドボックス化されたブラウザ（Chromium + CDP、noVNC オブザーバー）
  • 強化ノブ：network、user、pidsLimit、memory、cpus、ulimits、seccompProfile、apparmorProfile

警告：scope: "shared" は、共有コンテナと共有ワークスペースを意味します。セッション間の分離はありません。セッションごとの分離には scope: "session" を使用してください。

レガシー：perSession は引き続きサポートされています（true → scope: "session"、false → scope: "shared"）。

setupCommand は、コンテナの作成後に 一度 実行されます（コンテナ内で sh -lc 経由）。パッケージのインストールには、ネットワーク出力、書き込み可能なルート FS、および root ユーザーが必要です。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared（デフォルトは agent）
        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",
          // エージェントごとのオーバーライド（マルチエージェント）：agents.list[].sandbox.docker.*
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          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: ["/var/run/docker.sock:/var/run/docker.sock", "/home/user/source:/source:rw"]
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          containerPrefix: "openclaw-sbx-browser-",
          cdpPort: 9222,
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          allowedControlUrls: ["http://10.0.0.42:18791"],
          allowedControlHosts: ["browser.lab.local", "10.0.0.42"],
          allowedControlPorts: [18791],
          autoStart: true,
          autoStartTimeoutMs: 12000
        },
        prune: {
          idleHours: 24,  // 0 でアイドルプルーニングを無効化
          maxAgeDays: 7   // 0 で最大経過時間プルーニングを無効化
        }
      }
    }
  },
  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"]
      }
    }
  }
}

デフォルトのサンドボックスイメージを一度ビルドします：

scripts/sandbox-setup.sh

注意：サンドボックスコンテナのデフォルトは network: "none" です。エージェントがアウトバウンドアクセスを必要とする場合は、agents.defaults.sandbox.docker.network を "bridge"（またはカスタムネットワーク）に設定してください。

注意：インバウンド添付ファイルは、アクティブなワークスペースの media/inbound/* にステージングされます。workspaceAccess: "rw" の場合、ファイルはエージェントワークスペースに書き込まれます。

注意：docker.binds は追加のホストディレクトリをマウントします。グローバルおよびエージェントごとのバインドはマージされます。

オプションのブラウザイメージをビルドします：

scripts/sandbox-browser-setup.sh

agents.defaults.sandbox.browser.enabled=true の場合、ブラウザツールはサンドボックス化された Chromium インスタンス（CDP）を使用します。noVNC が有効な場合（headless=false の場合のデフォルト）、noVNC URL がシステムプロンプトに挿入されるため、エージェントはそれを参照できます。メイン設定で browser.enabled は必要ありません。サンドボックス制御 URL はセッションごとに挿入されます。

agents.defaults.sandbox.browser.allowHostControl（デフォルト：false）を使用すると、サンドボックス化されたセッションがブラウザツール（target: "host"）を介して ホスト ブラウザ制御サーバーを明示的にターゲットできます。厳格なサンドボックス分離が必要な場合は、これをオフのままにしてください。

リモート制御の許可リスト：

  • allowedControlUrls：target: "custom" で許可される正確な制御 URL。
  • allowedControlHosts：許可されるホスト名（ホスト名のみ、ポートなし）。
  • allowedControlPorts：許可されるポート（デフォルト：http=80、https=443）。 デフォルト：すべての許可リストは未設定（制限なし）。allowHostControl のデフォルトは false です。

models（カスタムプロバイダー + ベース URL）

OpenClaw は pi-coding-agent モデルカタログを使用します。カスタムプロバイダー（LiteLLM、ローカル OpenAI 互換サーバー、Anthropic プロキシなど）を追加するには、~/.openclaw/agents/<agentId>/agent/models.json を記述するか、OpenClaw 設定内の models.providers の下に同じスキーマを定義します。

プロバイダーごとの概要と例：/concepts/model-providers。

models.providers が存在する場合、OpenClaw は起動時に ~/.openclaw/agents/<agentId>/agent/ に models.json を書き込み/マージします：

  • デフォルトの動作：merge（既存のプロバイダーを保持し、名前でオーバーライド）
  • ファイルの内容を上書きするには、models.mode: "replace" を設定します

agents.defaults.model.primary（provider/model）でモデルを選択します。

{
  agents: {
    defaults: {
      model: { primary: "custom-proxy/llama-3.1-8b" },
      models: {
        "custom-proxy/llama-3.1-8b": {}
      }
    }
  },
  models: {
    mode: "merge",
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions",
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000
          }
        ]
      }
    }
  }
}

OpenCode Zen（マルチモデルプロキシ）

OpenCode Zen は、モデルごとのエンドポイントを持つマルチモデルゲートウェイです。OpenClaw は pi-ai の組み込み opencode プロバイダーを使用します。https://opencode.ai/auth から OPENCODE_API_KEY（または OPENCODE_ZEN_API_KEY）を設定してください。

注意事項：

  • モデル参照は opencode/<modelId> を使用します（例：opencode/claude-opus-4-5）。
  • agents.defaults.models で許可リストを有効にする場合は、使用する予定の各モデルを追加してください。
  • ショートカット：openclaw onboard --auth-choice opencode-zen。
{
  agents: {
    defaults: {
      model: { primary: "opencode/claude-opus-4-5" },
      models: { "opencode/claude-opus-4-5": { alias: "Opus" } }
    }
  }
}

Z.AI（GLM-4.7）— プロバイダーエイリアスサポート

Z.AI モデルは組み込みの zai プロバイダーを介して利用できます。環境に ZAI_API_KEY を設定し、provider/model でモデルを参照してください。

ショートカット：openclaw onboard --auth-choice zai-api-key。

{
  agents: {
    defaults: {
      model: { primary: "zai/glm-4.7" },
      models: { "zai/glm-4.7": {} }
    }
  }
}

注意事項：

  • z.ai/* および z-ai/* は受け入れられるエイリアスで、zai/* に正規化されます。
  • ZAI_API_KEY が欠落している場合、zai/* へのリクエストは実行時に認証エラーで失敗します。
  • エラー例：No API key found for provider "zai".
  • Z.AI の一般的な API エンドポイントは https://api.z.ai/api/paas/v4 です。GLM コーディングリクエストは専用の Coding エンドポイント https://api.z.ai/api/coding/paas/v4 を使用します。組み込みの zai プロバイダーは Coding エンドポイントを使用します。一般的なエンドポイントが必要な場合は、ベース URL オーバーライドで models.providers にカスタムプロバイダーを定義してください（上記のカスタムプロバイダーセクションを参照）。
  • ドキュメント/設定では偽のプレースホルダーを使用してください。実際の API キーをコミットしないでください。

Moonshot AI（Kimi）

Moonshot の OpenAI 互換エンドポイントを使用します：

{
  env: { MOONSHOT_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "moonshot/kimi-k2.5" },
      models: { "moonshot/kimi-k2.5": { alias: "Kimi K2.5" } }
    }
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "kimi-k2.5",
            name: "Kimi K2.5",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 256000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

注意事項：

  • 環境で MOONSHOT_API_KEY を設定するか、openclaw onboard --auth-choice moonshot-api-key を使用してください。
  • モデル参照：moonshot/kimi-k2.5。
  • 中国エンドポイントが必要な場合は、https://api.moonshot.cn/v1 を使用してください。

Kimi Code

Kimi Code の専用 OpenAI 互換エンドポイント（Moonshot とは別）を使用します：

{
  env: { KIMICODE_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "kimi-code/kimi-for-coding" },
      models: { "kimi-code/kimi-for-coding": { alias: "Kimi Code" } }
    }
  },
  models: {
    mode: "merge",
    providers: {
      "kimi-code": {
        baseUrl: "https://api.kimi.com/coding/v1",
        apiKey: "${KIMICODE_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "kimi-for-coding",
            name: "Kimi For Coding",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 262144,
            maxTokens: 32768,
            headers: { "User-Agent": "KimiCLI/0.77" },
            compat: { supportsDeveloperRole: false }
          }
        ]
      }
    }
  }
}

注意事項：

  • 環境で KIMICODE_API_KEY を設定するか、openclaw onboard --auth-choice kimi-code-api-key を使用してください。
  • モデル参照：kimi-code/kimi-for-coding。

Synthetic（Anthropic 互換）

Synthetic の Anthropic 互換エンドポイントを使用します：

{
  env: { SYNTHETIC_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.1" },
      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.1": { alias: "MiniMax M2.1" } }
    }
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "hf:MiniMaxAI/MiniMax-M2.1",
            name: "MiniMax M2.1",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 192000,
            maxTokens: 65536
          }
        ]
      }
    }
  }
}

注意事項：

  • SYNTHETIC_API_KEY を設定するか、openclaw onboard --auth-choice synthetic-api-key を使用してください。
  • モデル参照：synthetic/hf:MiniMaxAI/MiniMax-M2.1。
  • Anthropic クライアントが /v1 を追加するため、ベース URL は /v1 を省略する必要があります。

ローカルモデル（LM Studio）— 推奨セットアップ

現在のローカルガイダンスについては、/gateway/local-models を参照してください。要約：真剣なハードウェア上で LM Studio Responses API 経由で MiniMax M2.1 を実行し、フォールバック用にホスト型モデルをマージしておきます。

MiniMax M2.1

LM Studio を使用せずに MiniMax M2.1 を直接使用します：

{
  agent: {
    model: { primary: "minimax/MiniMax-M2.1" },
    models: {
      "anthropic/claude-opus-4-5": { alias: "Opus" },
      "minimax/MiniMax-M2.1": { alias: "Minimax" }
    }
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.1",
            name: "MiniMax M2.1",
            reasoning: false,
            input: ["text"],
            // 価格設定：正確なコスト追跡が必要な場合は models.json で更新してください。
            cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
            contextWindow: 200000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

注意事項：

  • MINIMAX_API_KEY 環境変数を設定するか、openclaw onboard --auth-choice minimax-api を使用してください。
  • 利用可能なモデル：MiniMax-M2.1（デフォルト）。
  • 正確なコスト追跡が必要な場合は、models.json で価格設定を更新してください。

Cerebras（GLM 4.6 / 4.7）

Cerebras の OpenAI 互換エンドポイントを介して Cerebras を使用します：

{
  env: { CEREBRAS_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: {
        primary: "cerebras/zai-glm-4.7",
        fallbacks: ["cerebras/zai-glm-4.6"]
      },
      models: {
        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
        "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" }
      }
    }
  },
  models: {
    mode: "merge",
    providers: {
      cerebras: {
        baseUrl: "https://api.cerebras.ai/v1",
        apiKey: "${CEREBRAS_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
          { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" }
        ]
      }
    }
  }
}

注意事項：

  • Cerebras には cerebras/zai-glm-4.7 を使用します。Z.AI 直接には zai/glm-4.7 を使用します。
  • 環境または設定で CEREBRAS_API_KEY を設定してください。

注意事項：

  • サポートされている API：openai-completions、openai-responses、anthropic-messages、google-generative-ai
  • カスタム認証のニーズには authHeader: true + headers を使用します。
  • models.json を別の場所に保存したい場合は、OPENCLAW_AGENT_DIR（または PI_CODING_AGENT_DIR）でエージェント設定ルートをオーバーライドします（デフォルト：~/.openclaw/agents/main/agent）。
← ドキュメントに戻る