設定リファレンス

~/.openclaw/openclaw.jsonで利用可能なすべてのフィールドです。タスク指向の概要についてはConfigurationを参照してください。

設定形式はJSON5（コメント＋末尾カンマが使用可能）です。すべてのフィールドはオプションであり、省略時はOpenClawが安全なデフォルトを使用します。

チャンネル

各チャンネルは設定セクションが存在すると自動的に起動します（enabled: falseの場合を除く）。

DMとグループアクセス

すべてのチャンネルがDMポリシーとグループポリシーをサポートしています：

注意： channels.defaults.groupPolicyはプロバイダーのgroupPolicyが未設定の場合のデフォルトを設定します。 ペアリングコードは1時間で期限切れになります。保留中のDMペアリングリクエストはチャンネルごとに3件まで。 プロバイダーブロックが完全に欠けている場合（channels.<provider>が不在）、ランタイムのグループポリシーは起動警告付きでallowlistにフォールバック（フェイルクローズ）。

チャンネルモデルオーバーライド

channels.modelByChannelで特定のチャンネルIDをモデルに固定できます。値はprovider/modelまたは設定済みモデルエイリアスを受け付けます。チャンネルマッピングはセッションにモデルオーバーライドがない場合（例：/modelで設定されていない場合）に適用されます。

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

チャンネルデフォルトとハートビート

channels.defaultsでプロバイダー間の共有グループポリシーとハートビート動作を設定：

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy：プロバイダーレベルのgroupPolicyが未設定の場合のフォールバックグループポリシー。
• channels.defaults.heartbeat.showOk：ハートビート出力に正常なチャンネルステータスを含める。
• channels.defaults.heartbeat.showAlerts：ハートビート出力に劣化/エラーステータスを含める。
• channels.defaults.heartbeat.useIndicator：コンパクトなインジケータースタイルのハートビート出力をレンダリング。

WhatsApp

WhatsAppはゲートウェイのWebチャンネル（Baileys Web）経由で動作します。リンク済みセッションが存在すると自動的に起動します。

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // 既読マーク（セルフチャットモードではfalse）
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress（デフォルト：off）
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• ボットトークン：channels.telegram.botTokenまたはchannels.telegram.tokenFile（通常ファイルのみ。シンボリックリンクは拒否）。デフォルトアカウントのフォールバックとしてTELEGRAM_BOT_TOKEN。
• オプションのchannels.telegram.defaultAccountは設定済みアカウントIDと一致する場合にデフォルトアカウント選択をオーバーライド。
• マルチアカウントセットアップ（2つ以上のアカウントID）では、明示的なデフォルトを設定してフォールバックルーティングを回避（channels.telegram.defaultAccountまたはchannels.telegram.accounts.default）。openclaw doctorはこれが欠けているまたは無効な場合に警告。
• configWrites: falseでTelegram発のconfig書き込み（スーパーグループID移行、/config set|unset）をブロック。
• トップレベルのbindings[]エントリでtype: "acp"を設定すると、フォーラムトピック用の永続ACPバインディングを設定（match.peer.idに正規のchatId:topic:topicIdを使用）。フィールドセマンティクスはACP Agentsで共有。
• TelegramストリームプレビューはsendMessage + editMessageTextを使用（ダイレクトチャットとグループチャットで動作）。
• リトライポリシー：Retry policyを参照。

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress（progressはDiscordではpartialにマッピング）
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // sessions_spawn({ thread: true })のオプトイン
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• トークン：channels.discord.token。デフォルトアカウントのフォールバックとしてDISCORD_BOT_TOKEN。
• 明示的なDiscord tokenを提供するダイレクトアウトバウンド呼び出しはその呼び出しにそのトークンを使用。アカウントリトライ/ポリシー設定はアクティブなランタイムスナップショット内の選択済みアカウントから適用。
• オプションのchannels.discord.defaultAccountは設定済みアカウントIDと一致する場合にデフォルトアカウント選択をオーバーライド。
• 配信ターゲットにはuser:<id>（DM）またはchannel:<id>（ギルドチャンネル）を使用。ベアの数値IDは拒否。
• ギルドスラッグは小文字でスペースを-に置換。チャンネルキーはスラッグ化された名前（#なし）。ギルドIDを推奨。
• ボット作成のメッセージはデフォルトで無視。allowBots: trueで有効化。allowBots: "mentions"でボットをメンションしたボットメッセージのみ受け入れ（自身のメッセージは引き続きフィルタ）。
• channels.discord.guilds.<id>.ignoreOtherMentions（およびチャンネルオーバーライド）は、ボットではなく別のユーザーやロールをメンションしたメッセージを破棄（@everyone/@hereを除く）。
• maxLinesPerMessage（デフォルト17）は2000文字以下でも長いメッセージを分割。
• channels.discord.threadBindingsはDiscordスレッドバウンドルーティングを制御：
  • enabled：スレッドバウンドセッション機能のDiscordオーバーライド（/focus、/unfocus、/agents、/session idle、/session max-age、およびバウンド配信/ルーティング）
  • idleHours：非アクティブ時の自動アンフォーカスまでの時間のDiscordオーバーライド（0で無効）
  • maxAgeHours：ハード最大経過時間のDiscordオーバーライド（0で無効）
  • spawnSubagentSessions：sessions_spawn({ thread: true })の自動スレッド作成/バインドのオプトイン
• トップレベルのbindings[]エントリでtype: "acp"を設定するとチャンネルとスレッド用の永続ACPバインディングを設定（match.peer.idにチャンネル/スレッドIDを使用）。フィールドセマンティクスはACP Agentsで共有。
• channels.discord.ui.components.accentColorはDiscordコンポーネントv2コンテナのアクセントカラーを設定。
• channels.discord.voiceはDiscordボイスチャンネル会話とオプションの自動参加＋TTSオーバーライドを有効化。
• channels.discord.voice.daveEncryptionとchannels.discord.voice.decryptionFailureToleranceは@discordjs/voiceのDAVEオプション（デフォルトはtrueと24）にパススルー。
• OpenClawは復号失敗の繰り返し後にボイスセッションの離脱/再参加による受信リカバリーも試行。
• channels.discord.streamingが正規のストリームモードキー。レガシーのstreamModeとブールstreaming値は自動マイグレーション。
• channels.discord.autoPresenceはランタイムの可用性をボットプレゼンスにマッピング（healthy => online、degraded => idle、exhausted => dnd）。オプションのステータステキストオーバーライドも可能。
• channels.discord.dangerouslyAllowNameMatchingで可変名/タグマッチングを再有効化（ブレークグラス互換モード）。

リアクション通知モード： off（なし）、own（ボットのメッセージ、デフォルト）、all（すべてのメッセージ）、allowlist（guilds.<id>.usersからすべてのメッセージ）。

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• サービスアカウントJSON：インライン（serviceAccount）またはファイルベース（serviceAccountFile）。
• サービスアカウントSecretRefもサポート（serviceAccountRef）。
• 環境変数フォールバック：GOOGLE_CHAT_SERVICE_ACCOUNTまたはGOOGLE_CHAT_SERVICE_ACCOUNT_FILE。
• 配信ターゲットにはspaces/<spaceId>またはusers/<userId>を使用。
• channels.googlechat.dangerouslyAllowNameMatchingで可変メールプリンシパルマッチングを再有効化（ブレークグラス互換モード）。

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: "partial", // off | partial | block | progress（プレビューモード）
      nativeStreaming: true, // streaming=partialの場合にSlackネイティブストリーミングAPIを使用
      mediaMaxMb: 20,
    },
  },
}

• SocketモードにはbotTokenとappTokenの両方が必要（デフォルトアカウントの環境変数フォールバックとしてSLACK_BOT_TOKEN + SLACK_APP_TOKEN）。
• HTTPモードにはbotTokenとsigningSecretが必要（ルートまたはアカウントごと）。
• configWrites: falseでSlack発のconfig書き込みをブロック。
• オプションのchannels.slack.defaultAccountは設定済みアカウントIDと一致する場合にデフォルトアカウント選択をオーバーライド。
• channels.slack.streamingが正規のストリームモードキー。レガシーのstreamModeとブールstreaming値は自動マイグレーション。
• 配信ターゲットにはuser:<id>（DM）またはchannel:<id>を使用。

リアクション通知モード： off、own（デフォルト）、all、allowlist（reactionAllowlistから）。

スレッドセッション分離： thread.historyScopeはスレッドごと（デフォルト）またはチャンネル全体で共有。thread.inheritParentは新スレッドに親チャンネルのトランスクリプトをコピー。

• typingReactionは返信実行中に受信Slackメッセージに一時的なリアクションを追加し、完了時に削除。"hourglass_flowing_sand"のようなSlack絵文字ショートコードを使用。

Mattermost

MattermostはプラグインとしてB供：openclaw plugins install @openclaw/mattermost。

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      commands: {
        native: true, // オプトイン
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

チャットモード：oncall（@メンションで応答、デフォルト）、onmessage（全メッセージ）、onchar（トリガープレフィックスで始まるメッセージ）。

Mattermostネイティブコマンドが有効な場合：

• commands.callbackPathはパスでなければならない（完全なURLではない）。
• commands.callbackUrlはOpenClawゲートウェイエンドポイントに解決され、Mattermostサーバーから到達可能でなければならない。
• プライベート/tailnet/内部コールバックホストでは、MattermostのServiceSettings.AllowedUntrustedInternalConnectionsにコールバックホスト/ドメインを含める必要がある場合がある。
• channels.mattermost.configWrites：Mattermost発のconfig書き込みを許可/拒否。
• channels.mattermost.requireMention：チャンネルで返信前に@mentionを要求。
• オプションのchannels.mattermost.defaultAccountは設定済みアカウントIDと一致する場合にデフォルトアカウント選択をオーバーライド。

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // オプションのアカウントバインディング
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

リアクション通知モード： off、own（デフォルト）、all、allowlist（reactionAllowlistから）。

• channels.signal.account：特定のSignalアカウントIDにチャンネル起動をバインド。
• channels.signal.configWrites：Signal発のconfig書き込みを許可/拒否。
• オプションのchannels.signal.defaultAccountは設定済みアカウントIDと一致する場合にデフォルトアカウント選択をオーバーライド。

BlueBubbles

BlueBubblesは推奨iMessageパス（プラグインベース、channels.bluebubblesで設定）。

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}

• コアキーパス：channels.bluebubbles、channels.bluebubbles.dmPolicy。
• オプションのchannels.bluebubbles.defaultAccountは設定済みアカウントIDと一致する場合にデフォルトアカウント選択をオーバーライド。
• 完全なBlueBubblesチャンネル設定はBlueBubblesに記載。

iMessage

OpenClawはimsg rpc（stdio経由のJSON-RPC）を起動。デーモンやポートは不要。

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "[email protected]", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• オプションのchannels.imessage.defaultAccountは設定済みアカウントIDと一致する場合にデフォルトアカウント選択をオーバーライド。
• メッセージDBへのフルディスクアクセスが必要。
• 配信ターゲットにはchat_id:<id>を推奨。imsg chats --limit 20でチャット一覧を表示。
• cliPathはSSHラッパーを指定可能。SCP添付ファイル取得にはremoteHost（hostまたはuser@host）を設定。
• attachmentRootsとremoteAttachmentRootsは受信添付ファイルパスを制限（デフォルト：/Users/*/Library/Messages/Attachments）。
• SCPは厳格なホストキーチェックを使用するため、リレーホストキーが~/.ssh/known_hostsに存在することを確認。
• channels.imessage.configWrites：iMessage発のconfig書き込みを許可/拒否。

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

Microsoft Teams

Microsoft Teamsはエクステンションベースでchannels.msteamsで設定。

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
    },
  },
}

• コアキーパス：channels.msteams、channels.msteams.configWrites。
• 完全なTeams設定（認証情報、Webhook、DM/グループポリシー、チーム/チャンネルごとのオーバーライド）はMicrosoft Teamsに記載。

IRC

IRCはエクステンションベースでchannels.ircで設定。

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "[email protected]",
      },
    },
  },
}

• コアキーパス：channels.irc、channels.irc.dmPolicy、channels.irc.configWrites、channels.irc.nickserv.*。
• オプションのchannels.irc.defaultAccountは設定済みアカウントIDと一致する場合にデフォルトアカウント選択をオーバーライド。
• 完全なIRCチャンネル設定（ホスト/ポート/TLS/チャンネル/許可リスト/メンションゲーティング）はIRCに記載。

マルチアカウント（全チャンネル）

チャンネルごとに複数のアカウントを実行（それぞれ固有のaccountId）：

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

• defaultはaccountId省略時に使用（CLI＋ルーティング）。
• 環境変数トークンはデフォルトアカウントにのみ適用。
• ベースチャンネル設定はアカウントごとにオーバーライドされない限り全アカウントに適用。
• bindings[].match.accountIdで各アカウントを異なるエージェントにルーティング。
• 単一アカウントのトップレベルチャンネル設定のままopenclaw channels add（またはチャンネルオンボーディング）で非デフォルトアカウントを追加すると、OpenClawはまずアカウントスコープのトップレベル単一アカウント値をchannels.<channel>.accounts.defaultに移動して元のアカウントが引き続き動作するようにする。
• 既存のチャンネルのみバインディング（accountIdなし）はデフォルトアカウントに引き続きマッチ。アカウントスコープのバインディングはオプション。
• openclaw doctor --fixも名前付きアカウントが存在するがdefaultが欠けている場合にアカウントスコープのトップレベル単一アカウント値をaccounts.defaultに移動して修復。

その他のエクステンションチャンネル

多くのエクステンションチャンネルはchannels.<id>として設定され、専用チャンネルページに記載（例：Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat、Twitch）。 チャンネル全インデックス：Channels。

グループチャットメンションゲーティング

グループメッセージはデフォルトでメンション必須（メタデータメンションまたは正規表現パターン）。WhatsApp、Telegram、Discord、Google Chat、iMessageのグループチャットに適用。

メンションの種類：

• メタデータメンション：ネイティブプラットフォームの@メンション。WhatsAppセルフチャットモードでは無視。
• テキストパターン：agents.list[].groupChat.mentionPatternsの正規表現パターン。常にチェック。
• メンションゲーティングは検出が可能な場合のみ適用（ネイティブメンションまたは少なくとも1つのパターン）。

{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

messages.groupChat.historyLimitがグローバルデフォルトを設定。チャンネルはchannels.<channel>.historyLimit（またはアカウントごと）でオーバーライド可能。0で無効。

DM履歴制限

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

解決順：DMごとのオーバーライド → プロバイダーデフォルト → 制限なし（すべて保持）。

対応：telegram、whatsapp、discord、slack、signal、imessage、msteams。

セルフチャットモード

allowFromに自分の番号を含めるとセルフチャットモードを有効化（ネイティブ@メンションを無視、テキストパターンにのみ応答）：

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

コマンド（チャットコマンド処理）

{
  commands: {
    native: "auto", // 対応時にネイティブコマンドを登録
    text: true, // チャットメッセージ内の/commandsをパース
    bash: false, // !（エイリアス：/bash）を許可
    bashForegroundMs: 2000,
    config: false, // /configを許可
    debug: false, // /debugを許可
    restart: false, // /restart＋ゲートウェイ再起動ツールを許可
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

エージェントデフォルト

agents.defaults.workspace

デフォルト：~/.openclaw/workspace。

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

agents.defaults.repoRoot

システムプロンプトのRuntimeラインに表示されるオプションのリポジトリルート。未設定時はOpenClawがワークスペースから上方探索で自動検出。

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

agents.defaults.skipBootstrap

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

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

agents.defaults.bootstrapMaxChars

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

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

agents.defaults.bootstrapTotalMaxChars

全ワークスペースブートストラップファイルの注入最大合計文字数。デフォルト：150000。

{
  agents: { defaults: { bootstrapTotalMaxChars: 150000 } },
}

agents.defaults.bootstrapPromptTruncationWarning

ブートストラップコンテキストが切り詰められた場合のエージェント向け警告テキストを制御。 デフォルト："once"。

• "off"：システムプロンプトに警告テキストを注入しない。
• "once"：一意の切り詰めシグネチャごとに1回警告を注入（推奨）。
• "always"：切り詰めが存在する毎回の実行で警告を注入。

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

agents.defaults.imageMaxDimensionPx

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

低い値はスクリーンショット多用の実行でビジョントークン使用量とリクエストペイロードサイズを削減。高い値はより多くの視覚的詳細を保持。

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

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.5": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.5"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5-mini"],
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model：文字列（"provider/model"）またはオブジェクト（{ primary, fallbacks }）を受け付ける。
  • 文字列形式はプライマリモデルのみを設定。
  • オブジェクト形式はプライマリ＋順序付きフェイルオーバーモデルを設定。
• imageModel：文字列またはオブジェクト。imageツールパスのビジョンモデル設定として使用。選択/デフォルトモデルが画像入力を受け付けられない場合のフォールバックルーティングにも使用。
• pdfModel：文字列またはオブジェクト。pdfツールのモデルルーティングに使用。省略時はimageModelにフォールバック、次にプロバイダーデフォルト。
• pdfMaxBytesMb：呼び出し時にmaxBytesMbが渡されない場合のpdfツールのデフォルトPDFサイズ制限。
• pdfMaxPages：pdfツールの抽出フォールバックモードで考慮される最大ページ数。
• model.primary：フォーマットprovider/model（例：anthropic/claude-opus-4-6）。プロバイダーを省略するとOpenClawはanthropicを想定（非推奨）。
• models：設定済みモデルカタログと/modelの許可リスト。各エントリにalias（ショートカット）とparams（プロバイダー固有、例：temperature、maxTokens、cacheRetention、context1m）を含めることが可能。
• paramsのマージ優先順位（設定）：agents.defaults.models["provider/model"].paramsがベース、次にagents.list[].params（一致するエージェントID）がキーごとにオーバーライド。
• これらのフィールドを変更する設定ライター（例：/models set、/models set-image、フォールバック追加/削除コマンド）は正規オブジェクト形式で保存し、可能な場合既存のフォールバックリストを保持。
• maxConcurrent：セッション間の最大並列エージェント実行数（各セッションはシリアル化）。デフォルト：1。

ビルトインエイリアスショートハンド（モデルがagents.defaults.modelsに含まれている場合のみ適用）：

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

Z.AI GLM-4.xモデルは--thinking offを設定するかagents.defaults.models["zai/<model>"].params.thinkingを自身で定義しない限り自動的にthinkingモードを有効化。 Z.AIモデルはツール呼び出しストリーミング用にデフォルトでtool_streamを有効化。無効にするにはagents.defaults.models["zai/<model>"].params.tool_streamをfalseに設定。 Anthropic Claude 4.6モデルは明示的なthinkingレベルが設定されていない場合adaptive thinkingをデフォルトに。

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

• CLIバックエンドはテキスト優先。ツールは常に無効。
• sessionArg設定時にセッション対応。
• imageArgがファイルパスを受け付ける場合に画像パススルー対応。

agents.defaults.heartbeat

定期的なハートビート実行。

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0mで無効
        model: "openai/gpt-5.2-mini",
        includeReasoning: false,
        lightContext: false,
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow（デフォルト）| block
        target: "none", // デフォルト：none | オプション：last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
      },
    },
  },
}

• every：期間文字列（ms/s/m/h）。デフォルト：30m。
• suppressToolErrorWarnings：trueの場合、ハートビート実行中のツールエラー警告ペイロードを抑制。
• directPolicy：ダイレクト/DM配信ポリシー。allow（デフォルト）はダイレクトターゲット配信を許可。blockはダイレクトターゲット配信を抑制しreason=dm-blockedを出力。
• lightContext：trueの場合、ハートビート実行は軽量ブートストラップコンテキストを使用し、ワークスペースブートストラップファイルからHEARTBEAT.mdのみを保持。
• エージェントごと：agents.list[].heartbeatで設定。いずれかのエージェントがheartbeatを定義するとそれらのエージェントのみがハートビートを実行。
• ハートビートは完全なエージェントターンを実行 — 短い間隔はより多くのトークンを消費。

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.",
        postCompactionSections: ["Session Startup", "Red Lines"],
        model: "openrouter/anthropic/claude-sonnet-4-5",
        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.",
        },
      },
    },
  },
}

• mode：defaultまたはsafeguard（長い履歴用のチャンク化要約）。Compactionを参照。
• identifierPolicy：strict（デフォルト）、off、custom。strictはcompaction要約時にビルトインの不透明ID保持ガイダンスを先頭追加。
• identifierInstructions：identifierPolicy=custom時に使用されるオプションのカスタムID保持テキスト。
• postCompactionSections：compaction後に再注入するオプションのAGENTS.md H2/H3セクション名。デフォルトは["Session Startup", "Red Lines"]。[]で再注入を無効化。
• model：compaction要約専用のオプションprovider/model-idオーバーライド。未設定時はセッションのプライマリモデルを使用。
• memoryFlush：自動compaction前の永続メモリ保存のためのサイレントエージェントターン。ワークスペースが読み取り専用の場合はスキップ。

agents.defaults.contextPruning

LLMに送信する前にインメモリコンテキストから古いツール結果を刈り込み。ディスク上のセッション履歴は変更しない。

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h",
        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]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

Session Pruningで動作の詳細を参照。

ブロックストリーミング

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

• 非Telegramチャンネルではブロックリプライを有効にするために明示的に*.blockStreaming: trueが必要。
• チャンネルオーバーライド：channels.<channel>.blockStreamingCoalesce（およびアカウントごとのバリアント）。Signal/Slack/Discord/Google ChatのデフォルトはminChars: 1500。
• humanDelay：ブロックリプライ間のランダム化された一時停止。natural = 800-2500ms。エージェントごとのオーバーライド：agents.list[].humanDelay。

Streamingで動作＋チャンキングの詳細を参照。

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

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

• デフォルト：ダイレクトチャット/メンションにはinstant、メンションされていないグループチャットにはmessage。
• セッションごとのオーバーライド：session.typingMode、session.typingIntervalSeconds。

Typing Indicatorsを参照。

agents.defaults.sandbox

オプションのDockerサンドボックス。完全ガイドはSandboxingを参照。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        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,
          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"],
        },
        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"],
      },
    },
  },
}

イメージのビルド：

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

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

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // またはオブジェクト{ primary, fallbacks }
        params: { cacheRetention: "none" },
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "\ud83e\udda5",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id：安定したエージェントID（必須）。
• default：複数設定時は最初のものが優先（警告がログ出力）。未設定時は最初のリストエントリがデフォルト。
• model：文字列形式はprimaryのみをオーバーライド。オブジェクト形式{ primary, fallbacks }は両方をオーバーライド（[]でグローバルフォールバックを無効化）。
• params：agents.defaults.modelsの選択されたモデルエントリにマージされるエージェントごとのストリームパラメータ。モデルカタログ全体を複製せずにcacheRetention、temperature、maxTokensなどのオーバーライドに使用。
• runtime：オプションのエージェントごとのランタイムディスクリプタ。
• identity.avatar：ワークスペース相対パス、http(s) URL、またはdata: URI。
• identityからデフォルトを導出：ackReactionをemojiから、mentionPatternsをname/emojiから。
• subagents.allowAgents：sessions_spawnのエージェントID許可リスト（["*"] = 任意。デフォルト：同一エージェントのみ）。

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

1つのGateway内で複数の分離されたエージェントを実行。Multi-Agentを参照。

{
  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が欠落した場合のデフォルト）、永続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（正確、peer/guild/teamなし）
5. match.accountId: "*"（チャンネルワイド）
6. デフォルトエージェント

各ティア内で最初にマッチするbindingsエントリが優先。

エージェントごとのアクセスプロファイル例についてはMulti-Agent Sandbox & Toolsを参照。

セッション

{
  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 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    parentForkMaxTokens: 100000,
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d",
      maxDiskBytes: "500mb",
      highWaterBytes: "400mb",
    },
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    mainKey: "main",
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

メッセージ

{
  messages: {
    responsePrefix: "\ud83e\udde0", // または"auto"
    ackReaction: "\ud83d\udc40",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
      },
    },
    inbound: {
      debounceMs: 2000, // 0で無効
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

レスポンスプレフィックス

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

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

ackリアクション

• デフォルトはアクティブエージェントのidentity.emoji、なければ"\ud83d\udc40"。""で無効化。
• チャンネルごとのオーバーライド：channels.<channel>.ackReaction。
• スコープ：group-mentions（デフォルト）、group-all、direct、all。
• removeAckAfterReply：リプライ後にackを削除（Slack/Discord/Telegram/Google Chatのみ）。

受信デバウンス

同一送信者からの高速テキストメッセージを単一のエージェントターンにバッチ処理。メディア/添付ファイルは即座にフラッシュ。制御コマンドはデバウンスをバイパス。

TTS（テキスト読み上げ）

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

• autoで自動TTSを制御。/tts off|always|inbound|taggedでセッションごとにオーバーライド。
• APIキーはELEVENLABS_API_KEY/XI_API_KEYとOPENAI_API_KEYにフォールバック。

Talk

Talkモード（macOS/iOS/Android）のデフォルト。

{
  talk: {
    voiceId: "elevenlabs_voice_id",
    voiceAliases: {
      Clawd: "EXAVITQu4vr4xnSDxMaL",
      Roger: "CwhRBWXzGAHq8TQ4Fs17",
    },
    modelId: "eleven_v3",
    outputFormat: "mp3_44100_128",
    apiKey: "elevenlabs_api_key",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
}

• ボイスIDはELEVENLABS_VOICE_IDまたはSAG_VOICE_IDにフォールバック。
• voiceAliasesでTalkディレクティブにフレンドリー名を使用可能。
• silenceTimeoutMsはユーザーの沈黙後にトランスクリプトを送信するまでの待機時間を制御。

ツール

ツールプロファイル

tools.profileでtools.allow/tools.deny前のベース許可リストを設定：

ツールグループ

tools.allow / tools.deny

グローバルツール許可/拒否ポリシー（denyが優先）。大文字小文字を区別せず、*ワイルドカード対応。Dockerサンドボックスがオフでも適用。

tools.elevated

特権（ホスト）exec アクセスの制御：

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

tools.web

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key",
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        maxChars: 50000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
}

tools.sessions

セッションツール（sessions_list、sessions_history、sessions_send）がターゲットにできるセッションを制御。

デフォルト：tree（現在のセッション＋それが生成したセッション）。

{
  tools: {
    sessions: {
      visibility: "tree", // "self" | "tree" | "agent" | "all"
    },
  },
}

tools.subagents

{
  agents: {
    defaults: {
      subagents: {
        model: "minimax/MiniMax-M2.5",
        maxConcurrent: 1,
        runTimeoutSeconds: 900,
        archiveAfterMinutes: 60,
      },
    },
  },
}

カスタムプロバイダーとベースURL

OpenClawはpi-coding-agentモデルカタログを使用。設定のmodels.providersまたは~/.openclaw/agents/<agentId>/agent/models.jsonでカスタムプロバイダーを追加可能。

{
  models: {
    mode: "merge", // merge（デフォルト）| replace
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai
        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,
          },
        ],
      },
    },
  },
}

• authHeader: true＋headersでカスタム認証に対応。
• OPENCLAW_AGENT_DIR（またはPI_CODING_AGENT_DIR）でエージェント設定ルートをオーバーライド。
• マージ優先順位：非空のエージェントmodels.json baseUrl値が優先。非空のエージェントapiKey値はそのプロバイダーが現在の設定/認証プロファイルコンテキストでSecretRef管理されていない場合のみ優先。
• models.mode: "replace"で設定がmodels.jsonを完全に書き換え。

プロバイダーフィールドの詳細

• models.providers.*.api：リクエストアダプタ（openai-completions、openai-responses、anthropic-messages、google-generative-aiなど）。
• models.providers.*.apiKey：プロバイダー認証情報（SecretRef/環境変数置換を推奨）。
• models.providers.*.auth：認証戦略（api-key、token、oauth、aws-sdk）。
• models.providers.*.baseUrl：上流APIベースURL。
• models.providers.*.headers：プロキシ/テナントルーティング用の追加静的ヘッダー。
• models.bedrockDiscovery：Bedrock自動検出設定ルート。

プロバイダー例（Cerebras、OpenCode、Z.AI、Moonshot AI、Kimi Coding、Synthetic、MiniMax M2.5、LM Studioなど）の詳細コードブロックは、すべてのJSON5設定が英語版と同一です。Configuration Referenceの英語版Provider examplesセクションを参照してください。

スキル

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn
    },
    entries: {
      "nano-banana-pro": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• allowBundled：バンドルスキルのみのオプション許可リスト（マネージド/ワークスペーススキルは影響なし）。
• entries.<skillKey>.enabled: falseでバンドル/インストール済みでもスキルを無効化。
• entries.<skillKey>.apiKey：プライマリ環境変数を宣言するスキル用の便利フィールド（平文文字列またはSecretRefオブジェクト）。

プラグイン

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: [],
    load: {
      paths: ["~/Projects/oss/voice-call-extension"],
    },
    entries: {
      "voice-call": {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
        config: { provider: "twilio" },
      },
    },
  },
}

• ~/.openclaw/extensions、<workspace>/.openclaw/extensions、およびplugins.load.pathsからロード。
• 設定変更にはGatewayの再起動が必要。
• allow：オプション許可リスト（リストされたプラグインのみロード）。denyが優先。
• plugins.slots.memory：アクティブなメモリープラグインIDを選択、または"none"でメモリープラグインを無効化。
• plugins.slots.contextEngine：アクティブなコンテキストエンジンプラグインIDを選択。デフォルトは"legacy"。

Pluginsを参照。

ブラウザ

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "chrome",
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true,
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
  },
}

• evaluateEnabled: falseでact:evaluateとwait --fnを無効化。
• ssrfPolicy.dangerouslyAllowPrivateNetworkは未設定時にデフォルトtrue（信頼ネットワークモデル）。
• リモートプロファイルはアタッチのみ（開始/停止/リセット無効）。
• 自動検出順：デフォルトブラウザ（Chromiumベースの場合）→ Chrome → Brave → Edge → Chromium → Chrome Canary。

UI

{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB",
    },
  },
}

• seamColor：ネイティブアプリUIクロームのアクセントカラー。
• assistant：UIアイデンティティオーバーライド。アクティブエージェントアイデンティティにフォールバック。

Gateway

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
    },
    remote: {
      url: "ws://gateway.tailnet:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
    },
    trustedProxies: ["10.0.0.1"],
    allowRealIpFallback: false,
    tools: {
      deny: ["browser"],
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

OpenAI互換エンドポイント

• Chat Completions：デフォルト無効。gateway.http.endpoints.chatCompletions.enabled: trueで有効化。
• Responses API：gateway.http.endpoints.responses.enabled。

マルチインスタンス分離

1つのホストでユニークなポートと状態ディレクトリで複数のゲートウェイを実行：

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

便利フラグ：--dev（~/.openclaw-dev＋ポート19001を使用）、--profile <name>（~/.openclaw-<name>を使用）。

Multiple Gatewaysを参照。

フック

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    maxBodyBytes: 262144,
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    allowedAgentIds: ["hooks", "main"],
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "hooks",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.2-mini",
      },
    ],
  },
}

認証：Authorization: Bearer <token>またはx-openclaw-token: <token>。

エンドポイント：

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
• POST /hooks/<name> → hooks.mappings経由で解決

Gmail統合

{
  hooks: {
    gmail: {
      account: "[email protected]",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

• Gatewayは設定時にブート時にgog gmail watch serveを自動起動。OPENCLAW_SKIP_GMAIL_WATCHER=1で無効化。

キャンバスホスト

{
  canvasHost: {
    root: "~/.openclaw/workspace/canvas",
    liveReload: true,
  },
}

• Gatewayポート配下のHTTPでエージェント編集可能なHTML/CSS/JSとA2UIを提供。
• ローカル専用：gateway.bind: "loopback"（デフォルト）を維持。
• 変更にはGatewayの再起動が必要。

ディスカバリー

mDNS（Bonjour）

{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}

• minimal（デフォルト）：TXTレコードからcliPath＋sshPortを省略。
• full：cliPath＋sshPortを含める。
• ホスト名はデフォルトでopenclaw。OPENCLAW_MDNS_HOSTNAMEでオーバーライド。

ワイドエリア（DNS-SD）

{
  discovery: {
    wideArea: { enabled: true },
  },
}

~/.openclaw/dns/配下にユニキャストDNS-SDゾーンを書き込み。クロスネットワーク検出には、DNSサーバー（CoreDNS推奨）＋Tailscaleスプリットと組み合わせ。

セットアップ：openclaw dns setup --apply。

環境変数

env（インライン環境変数）

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

• インライン環境変数はプロセス環境にキーが欠けている場合のみ適用。
• .envファイル：CWDの.env＋~/.openclaw/.env（いずれも既存の変数をオーバーライドしない）。
• shellEnv：ログインシェルプロファイルから欠落している期待キーをインポート。
• 完全な優先順位はEnvironmentを参照。

環境変数置換

設定文字列内で${VAR_NAME}で環境変数を参照：

{
  gateway: {
    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
  },
}

• 大文字名のみマッチ：[A-Z_][A-Z0-9_]*。
• 欠落/空の変数はconfig読み込み時にエラー。
• $${VAR}でリテラル${VAR}をエスケープ。
• $includeで動作。

シークレット

シークレットrefは追加的：平文値も引き続き動作。

SecretRef

1つのオブジェクト形式を使用：

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

シークレットプロバイダー設定

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
        timeoutMs: 5000,
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
  },
}

認証ストレージ

{
  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"],
    },
  },
}

• エージェントごとのプロファイルは<agentDir>/auth-profiles.jsonに保存。
• OAuthを参照。
• シークレットランタイム動作とaudit/configure/applyツール：Secrets Management。

ログ

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | compact | json
    redactSensitive: "tools", // off | tools
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}

• デフォルトログファイル：/tmp/openclaw/openclaw-YYYY-MM-DD.log。
• logging.fileで安定したパスを設定。
• consoleLevelは--verbose時にdebugに引き上げ。

CLI

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

• cli.banner.taglineMode：バナーのタグラインスタイルを制御。
  • "random"（デフォルト）：ローテーションする面白い/季節のタグライン。
  • "default"：固定のニュートラルなタグライン。
  • "off"：タグラインテキストなし（バナータイトル/バージョンは表示）。

ウィザード

CLIウィザード（onboard、configure、doctor）が書き込むメタデータ：

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

アイデンティティ

{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "\ud83e\udda5",
          avatar: "avatars/samantha.png",
        },
      },
    ],
  },
}

macOSオンボーディングアシスタントが書き込み。デフォルトを導出：

• messages.ackReactionをidentity.emojiから（フォールバック：\ud83d\udc40）
• mentionPatternsをidentity.name/identity.emojiから
• avatar：ワークスペース相対パス、http(s) URL、またはdata: URI

ブリッジ（レガシー、削除済み）

現在のビルドにはTCPブリッジは含まれていません。ノードはGateway WebSocket経由で接続。bridge.*キーは設定スキーマから削除（削除されるまでバリデーションが失敗。openclaw doctor --fixで不明キーの削除が可能）。

Cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    webhook: "https://example.invalid/legacy",
    webhookToken: "replace-with-dedicated-token",
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

• sessionRetention：完了した分離cronランセッションをsessions.jsonから刈り込むまでの保持期間。デフォルト：24h。falseで無効。
• runLog.maxBytes：ランログファイルごとの最大サイズ。デフォルト：2_000_000バイト。
• webhookToken：cron webhook POST配信用のベアラートークン。

Cron Jobsを参照。

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

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

設定include（$include）

設定を複数ファイルに分割：

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

マージ動作：

• 単一ファイル：含むオブジェクトを置換。
• ファイルの配列：順序通りにディープマージ（後のものが前のものをオーバーライド）。
• 兄弟キー：include後にマージ（インクルードされた値をオーバーライド）。
• ネストされたinclude：10レベルまで。
• パス：インクルードするファイルからの相対解決。ただしトップレベルの設定ディレクトリ（openclaw.jsonのdirname）内に留まる必要あり。絶対/../形式はその境界内に解決される場合のみ許可。
• エラー：欠落ファイル、パースエラー、循環includeに対する明確なメッセージ。

関連：Configuration · Configuration Examples · Doctor