OpenClaw設定ガイド：チャンネルとDMポリシーを最適化する

チャンネル

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

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

すべてのチャンネルで、DM ポリシーとグループポリシーを設定できます。

DM ポリシー	挙動
`pairing` (デフォルト)	未知の送信者には一度限りのペアリングコードを発行し、オーナーの承認を求めます
`allowlist`	`allowFrom`（またはペアリング済みの保存済みリスト）にある送信者のみ許可します
`open`	すべてのインバウンド DM を許可します（`allowFrom: ["*"]` が必要です）
`disabled`	すべてのインバウンド DM を無視します

グループポリシー	挙動
`allowlist` (デフォルト)	設定された許可リストに一致するグループのみ許可します
`open`	グループの許可リストをバイパスします（メンションによる制限は引き続き適用されます）
`disabled`	すべてのグループ/ルームメッセージをブロックします

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

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,
        showAlert: true,
        useIndicator: true,
      },
    },
  },
}

channels.defaults.groupPolicy: プロバイダーレベルの groupPolicy が未設定の場合のフォールバックポリシーです。
channels.defaults.heartbeat.showOk: 正常なチャンネルステータスをハートビート出力に含めます。
channels.defaults.heartbeat.showAlerts: 低下またはエラー状態のステータスをハートビート出力に含めます。
channels.defaults.heartbeat.useIndicator: コンパクトなインジケーター形式でハートビートを出力します。

WhatsApp は Gateway の Web チャンネル（Baileys Web）を通じて動作します。リンクされたセッションが存在する場合、自動的に起動します。

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      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,
    },
  },
}

マルチアカウント WhatsApp

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

アウトバウンドコマンドは、存在すれば default アカウントをデフォルトとし、そうでなければ最初に設定されたアカウント ID（ソート順）を使用します。
オプションの channels.whatsapp.defaultAccount は、設定済みのアカウント ID と一致する場合、そのフォールバック先を上書きします。
従来のシングルアカウント用 Baileys 認証ディレクトリは、openclaw doctor によって whatsapp/default に移行されます。
アカウントごとのオーバーライド: channels.whatsapp.accounts.<id>.sendReadReceipts, channels.whatsapp.accounts.<id>.dmPolicy, channels.whatsapp.accounts.<id>.allowFrom。

{
  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 (default: 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",
    },
  },
}

Bot トークン: channels.telegram.botToken または channels.telegram.tokenFile（通常のファイルのみ。シンボリックリンクは不可）。デフォルトアカウントのフォールバックとして TELEGRAM_BOT_TOKEN が使用されます。
オプションの channels.telegram.defaultAccount は、設定済みのアカウント ID と一致する場合、デフォルトのアカウント選択を上書きします。
マルチアカウント設定（2つ以上のアカウント ID）では、フォールバックルーティングを避けるために明示的なデフォルト（channels.telegram.defaultAccount または channels.telegram.accounts.default）を設定してください。設定がない場合や無効な場合は openclaw doctor が警告を出します。
configWrites: false: Telegram 経由の設定書き込み（スーパーグループ ID の移行、/config set|unset）をブロックします。
トップレベルの 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 maps to partial on Discord)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in for 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 の使用を推奨します。
Bot が作成したメッセージはデフォルトで無視されます。allowBots: true で許可できます。allowBots: "mentions" を使用すると、その Bot にメンションしているメッセージのみを受け入れます（自身のメッセージは引き続きフィルタリングされます）。
channels.discord.guilds.<id>.ignoreOtherMentions（およびチャンネルのオーバーライド）は、他のユーザーやロールにメンションしているが、その Bot にはメンションしていないメッセージを破棄します（@everyone/@here を除く）。
maxLinesPerMessage (デフォルト 17) は、2000 文字未満であっても行数が多いメッセージを分割します。
channels.discord.threadBindings は Discord スレッドに紐づくルーティングを制御します：
- enabled: スレッドに紐づくセッション機能（/focus, /unfocus, /agents, /session idle, /session max-age および紐づけられた配信/ルーティング）の Discord 用オーバーライド。
- idleHours: 非アクティブによる自動アンフォーカスまでの時間（時間単位、0 で無効）。
- maxAgeHours: ハードな最大生存時間（時間単位、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 や boolean の streaming 値は自動的に移行されます。
channels.discord.autoPresence はランタイムの可用性を Bot のプレゼンスにマッピングし（healthy => online, degraded => idle, exhausted => dnd）、オプションでステータステキストを上書きできます。
channels.discord.dangerouslyAllowNameMatching は、名前/タグによるマッチングを再有効化します（互換性のための緊急回避モード）。

リアクション通知モード: off (なし), own (Bot のメッセージのみ、デフォルト), 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 (preview mode)
      nativeStreaming: true, // streaming=partial の場合に Slack ネイティブストリーミング API を使用
      mediaMaxMb: 20,
    },
  },
}

Socket mode には botToken と appToken の両方が必要です（デフォルトアカウントの環境変数フォールバックは SLACK_BOT_TOKEN + SLACK_APP_TOKEN）。
HTTP mode には botToken に加えて signingSecret（ルートまたはアカウントごと）が必要です。
configWrites: false: Slack 経由の設定書き込みをブロックします。
オプションの channels.slack.defaultAccount は、設定済みのアカウント ID と一致する場合、デフォルトのアカウント選択を上書きします。
channels.slack.streaming は標準的なストリームモードキーです。従来の streamMode や boolean の streaming 値は自動的に移行されます。
配信ターゲットには user:<id> (DM) または channel:<id> を使用してください。

リアクション通知モード: off, own (デフォルト), all, allowlist (reactionAllowlist から)。

スレッドセッションの分離: thread.historyScope はスレッドごと（デフォルト）またはチャンネル全体で共有されます。thread.inheritParent は親チャンネルの履歴を新しいスレッドにコピーします。

typingReaction: 返信の生成中にインバウンドメッセージに一時的なリアクションを追加し、完了後に削除します。"hourglass_flowing_sand" のような Slack 絵文字ショートコードを使用してください。

アクショングループ	デフォルト	備考
reactions	有効	リアクションの追加とリスト取得
messages	有効	読み取り/送信/編集/削除
pins	有効	ピン留め/解除/リスト取得
memberInfo	有効	メンバー情報
emojiList	有効	カスタム絵文字リスト

Mattermost

Mattermost はプラグインとして提供されます: 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, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Optional explicit URL for reverse-proxy/public deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

チャットモード: oncall (@メンションに反応、デフォルト), onmessage (すべてのメッセージ), onchar (トリガープレフィックスで始まるメッセージ)。

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

commands.callbackPath はフル URL ではなくパス（例: /api/channels/mattermost/command）である必要があります。
commands.callbackUrl は OpenClaw Gateway エンドポイントを指し、Mattermost サーバーから到達可能である必要があります。
プライベートネットワークや内部ホストの場合、Mattermost の ServiceSettings.AllowedUntrustedInternalConnections にコールバックホスト/ドメインを含める必要がある場合があります。フル URL ではなくホスト/ドメイン値を指定してください。
channels.mattermost.configWrites: Mattermost 経由の設定書き込みを許可または拒否します。
channels.mattermost.requireMention: チャンネル内で返信する前に @mention を必須にします。
オプションの channels.mattermost.defaultAccount は、設定済みのアカウント ID と一致する場合、デフォルトのアカウント選択を上書きします。

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      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 経由の設定書き込みを許可または拒否します。
オプションの channels.signal.defaultAccount は、設定済みのアカウント ID と一致する場合、デフォルトのアカウント選択を上書きします。

BlueBubbles

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

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, group controls, and advanced actions:
      // see /channels/bluebubbles
    },
  },
}

ここでカバーされる主要なキーパス: 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", "user@example.com", "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 と一致する場合、デフォルトのアカウント選択を上書きします。
メッセージデータベースへの「フルディスクアクセス」権限が必要です。
配信ターゲットには chat_id:<id> を推奨します。imsg chats --limit 20 でチャットを一覧表示できます。
cliPath は SSH ラッパーを指すことができます。アタッチメント取得のために remoteHost (host または user@host) を設定してください。
attachmentRoots と remoteAttachmentRoots はインバウンドアタッチメントのパスを制限します（デフォルト: /Users/*/Library/Messages/Attachments）。
SCP は厳格なホストキーチェックを行うため、リレーホストのキーが ~/.ssh/known_hosts に存在することを確認してください。
channels.imessage.configWrites: iMessage 経由の設定書き込みを許可または拒否します。

iMessage SSH ラッパーの例

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

Microsoft Teams

Microsoft Teams は拡張機能ベースで、channels.msteams で設定します。

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // see /channels/msteams
    },
  },
}

ここでカバーされる主要なキーパス: 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: "bot@example.com",
      },
    },
  },
}

ここでカバーされる主要なキーパス: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*。
オプションの channels.irc.defaultAccount は、設定済みのアカウント ID と一致する場合、デフォルトのアカウント選択を上書きします。
IRC チャンネルの完全な設定（ホスト/ポート/TLS/チャンネル/許可リスト/メンション制限）は IRC に記載されています。

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

1つのチャンネルで複数のアカウントを運用できます（それぞれ独自の accountId を持ちます）。

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

accountId が省略された場合（CLI やルーティング）、default が使用されます。
環境変数のトークンは default アカウントにのみ適用されます。
基本的なチャンネル設定は、アカウントごとに上書きされない限り、すべてのアカウントに適用されます。
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", // register native commands when supported
    text: true, // parse /commands in chat messages
    bash: false, // allow ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // allow /config
    debug: false, // allow /debug
    restart: false, // allow /restart + gateway restart tool
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

コマンドの詳細

テキストコマンドは、先頭に / が付いた 単独の メッセージである必要があります。
native: "auto" は Discord/Telegram でネイティブコマンドを有効にし、Slack はオフのままにします。
チャンネルごとに上書き可能: channels.discord.commands.native (bool または "auto")。false は以前に登録されたコマンドをクリアします。
channels.telegram.customCommands は Telegram Bot メニューにエントリを追加します。
bash: true はホストシェル用の ! <cmd> を有効にします。tools.elevated.enabled と、送信者が tools.elevated.allowFrom.<channel> に含まれている必要があります。
config: true は /config (openclaw.json の読み書き) を有効にします。Gateway の chat.send クライアントの場合、永続的な /config set|unset には operator.admin 権限が必要です。読み取り専用の /config show は通常の書き込み権限を持つオペレータークライアントでも利用可能です。
channels.<provider>.configWrites はチャンネルごとの設定変更を制限します（デフォルト: true）。
マルチアカウントチャンネルの場合、channels.<provider>.accounts.<id>.configWrites はそのアカウントをターゲットとする書き込みも制限します（例: /allowlist --config --account <id> や /config set channels.<provider>.accounts.<id>...）。
allowFrom はプロバイダーごとです。設定されている場合、それが 唯一の 認可ソースとなります（チャンネルの許可リスト/ペアリングや useAccessGroups は無視されます）。
useAccessGroups: false は、allowFrom が設定されていない場合にコマンドがアクセスグループポリシーをバイパスすることを許可します。

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

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

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

エイリアス	モデル
`opus`	`anthropic/claude-opus-4-6`
`sonnet`	`anthropic/claude-sonnet-4-6`
`gpt`	`openai/gpt-5.4`
`gpt-mini`	`openai/gpt-5-mini`
`gemini`	`google/gemini-3.1-pro-preview`
`gemini-flash`	`google/gemini-3-flash-preview`
`gemini-flash-lite`	`google/gemini-3.1-flash-lite-preview`

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

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 disables
        model: "openai/gpt-5.2-mini",
        includeReasoning: false,
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: 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.", // used when identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
        model: "openrouter/anthropic/claude-sonnet-4-5", // optional compaction-only model override
        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 はコンパクション要約中に組み込みの不透明な識別子保持ガイダンスを付加します。
identifierInstructions: identifierPolicy=custom の場合に使用される、オプションのカスタム識別子保持テキストです。
postCompactionSections: コンパクション後に再注入するオプションの AGENTS.md H2/H3 セクション名です。デフォルトは ["Session Startup", "Red Lines"] です。[] に設定すると再注入を無効にします。未設定またはデフォルトのペアが設定されている場合、従来の Every Session/Safety 見出しもフォールバックとして受け入れられます。
model: コンパクション要約のみに使用するオプションの provider/model-id オーバーライドです。メインセッションはあるモデルを使い続け、コンパクション要約は別のモデルで実行したい場合に使用します。未設定の場合、コンパクションはセッションのプライマリモデルを使用します。
memoryFlush: 自動コンパクションの前に、永続的なメモリを保存するためのサイレントなエージェントターンを実行します。ワークスペースが読み取り専用の場合はスキップされます。

`agents.defaults.contextPruning`

LLM に送信する前に、メモリ内のコンテキストから 古いツールの実行結果 を削除します。ディスク上のセッション履歴は変更 しません。

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        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"] },
      },
    },
  },
}

cache-ttl モードの挙動

mode: "cache-ttl" はプルーニングパスを有効にします。
ttl は、プルーニングを再度実行できる頻度（最後のキャッシュタッチ後）を制御します。
プルーニングは、まずサイズ超過のツール結果をソフトトリムし、必要に応じて古いツール結果をハードクリアします。

ソフトトリムは、最初と最後を保持し、中間に ... を挿入します。

ハードクリアは、ツール結果全体をプレースホルダーに置き換えます。

備考:

画像ブロックはトリムやクリアの対象になりません。
比率はトークン数ではなく文字数に基づいています（概算）。
keepLastAssistants で指定された数よりアシスタントメッセージが少ない場合、プルーニングはスキップされます。

挙動の詳細については 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"],
      },
    },
  },
}

サンドボックスの詳細

ワークスペースアクセス:

none: ~/.openclaw/sandboxes 配下のスコープごとのサンドボックスワークスペース
ro: /workspace にサンドボックスワークスペース、/agent にエージェントワークスペースを読み取り専用でマウント
rw: /workspace にエージェントワークスペースを読み書き可能でマウント

スコープ:

session: セッションごとのコンテナ + ワークスペース
agent: エージェントごとに1つのコンテナ + ワークスペース (デフォルト)
shared: 共有コンテナとワークスペース (セッション間の分離なし)

setupCommand はコンテナ作成後に一度だけ実行されます (sh -lc 経由)。ネットワーク接続、書き込み可能なルート、ルートユーザー権限が必要です。

コンテナはデフォルトで network: "none" です。エージェントが外部アクセスを必要とする場合は、"bridge" (またはカスタムブリッジネットワーク) に設定してください。 "host" はブロックされます。"container:<id>" は、sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true を明示的に設定しない限り、デフォルトでブロックされます。

インバウンドアタッチメントは、アクティブなワークスペースの media/inbound/* にステージングされます。

docker.binds は追加のホストディレクトリをマウントします。グローバル設定とエージェントごとの設定はマージされます。

サンドボックス化されたブラウザ (sandbox.browser.enabled): コンテナ内の Chromium + CDP です。noVNC の URL がシステムプロンプトに注入されます。openclaw.json で browser.enabled を設定する必要はありません。 noVNC オブザーバーアクセスはデフォルトで VNC 認証を使用し、OpenClaw は共有 URL にパスワードを露出させる代わりに、短命なトークン URL を発行します。

allowHostControl: false (デフォルト) は、サンドボックス化されたセッションがホストのブラウザをターゲットにすることをブロックします。
network はデフォルトで openclaw-sandbox-browser (専用ブリッジネットワーク) です。グローバルなブリッジ接続を明示的に希望する場合のみ bridge に設定してください。
cdpSourceRange は、コンテナエッジでの CDP イングレスを CIDR 範囲 (例: 172.21.0.1/32) に制限できます。
sandbox.browser.binds は、サンドボックスブラウザコンテナにのみ追加のホストディレクトリをマウントします。設定されている場合（[] を含む）、ブラウザコンテナについては docker.binds を置き換えます。
起動時のデフォルト設定は scripts/sandbox-browser-entrypoint.sh で定義されており、コンテナホスト向けに調整されています：
- --remote-debugging-address=127.0.0.1
- --remote-debugging-port=<OPENCLAW_BROWSER_CDP_PORT から派生>
- --user-data-dir=${HOME}/.chrome
- --no-first-run
- --no-default-browser-check
- --disable-3d-apis
- --disable-gpu
- --disable-software-rasterizer
- --disable-dev-shm-usage
- --disable-background-networking
- --disable-features=TranslateUI
- --disable-breakpad
- --disable-crash-reporter
- --renderer-process-limit=2
- --no-zygote
- --metrics-recording-only
- --disable-extensions (デフォルトで有効)
- --disable-3d-apis, --disable-software-rasterizer, --disable-gpu はデフォルトで有効ですが、WebGL/3D の使用が必要な場合は OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 で無効にできます。
- ワークフローで拡張機能が必要な場合は、OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 で再有効化できます。
- --renderer-process-limit=2 は OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> で変更可能です。Chromium のデフォルト制限を使用するには 0 を設定してください。
- noSandbox が有効な場合は --no-sandbox と --disable-setuid-sandbox が追加されます。
- デフォルト設定はコンテナイメージのベースラインです。コンテナのデフォルトを変更するには、カスタムエントリポイントを持つカスタムブラウザイメージを使用してください。

イメージのビルド：

scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image

`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" }, // defaults.models の params をキーごとに上書き
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          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: 複数が設定されている場合、最初の

メッセージ

{
  messages: {
    responsePrefix: "🦞", // または "auto"
    ackReaction: "👀",
    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,
      },
    },
  },
}

レスポンスの接頭辞（Response prefix）

チャンネルやアカウントごとに上書き設定が可能です： channels.<channel>.responsePrefix、 channels.<channel>.accounts.<id>.responsePrefix。

解決順序（最も具体的な設定が優先されます）： account → channel → global。 "" を設定すると無効になり、上位設定への継承も止まります。 "auto" を指定すると [{identity.name}] が自動的に使用されます。

テンプレート変数:

変数	説明	例
`{model}`	短いモデル名	`claude-opus-4-6`
`{modelFull}`	完全なモデル識別子	`anthropic/claude-opus-4-6`
`{provider}`	プロバイダー名	`anthropic`
`{thinkingLevel}`	現在の思考レベル	`high`, `low`, `off`
`{identity.name}`	エージェントの識別名	(`"auto"` と同じ)

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

確認リアクション（Ack reaction）

デフォルトではアクティブなエージェントの identity.emoji が使用され、設定がない場合は "👀" になります。無効にするには "" を設定してください。
チャンネルごとの上書き： channels.<channel>.ackReaction、 channels.<channel>.accounts.<id>.ackReaction。
解決順序： account → channel → messages.ackReaction → identity のデフォルト。
スコープ（Scope）： group-mentions（デフォルト）、 group-all、 direct、 all。
removeAckAfterReply: 返信後に確認リアクションを削除します（Slack/Discord/Telegram/Google Chat のみ対応）。

インバウンド・デバウンス（Inbound debounce）

同じ送信者からの連続したテキストメッセージを、一つのエージェントターンとしてまとめます。メディアや添付ファイルがある場合は即座に処理が開始されます。また、制御コマンドはデバウンス処理をバイパスします。

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",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
      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 コマンドでセッションごとに上書きできます。
summaryModel は、自動要約に使用される agents.defaults.model.primary を上書きします。
modelOverrides はデフォルトで有効です。 modelOverrides.allowProvider はデフォルトで false（オプトイン方式）です。
API キーは ELEVENLABS_API_KEY/XI_API_KEY および OPENAI_API_KEY の環境変数にフォールバックします。
openai.baseUrl は OpenAI TTS エンドポイントを上書きします。解決順序は、設定ファイル、 OPENAI_TTS_BASE_URL 環境変数、そして https://api.openai.com/v1 の順です。
openai.baseUrl が OpenAI 以外のエンドポイントを指している場合、OpenClaw はそれを OpenAI 互換の TTS サーバーとして扱い、モデルや音声のバリデーションを緩和します。

トーク（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（Voice ID）は ELEVENLABS_VOICE_ID または SAG_VOICE_ID にフォールバックします。
apiKey および providers.*.apiKey は、プレーンテキストの文字列または SecretRef オブジェクトを受け入れます。
ELEVENLABS_API_KEY へのフォールバックは、Talk 用の API キーが設定されていない場合にのみ適用されます。
voiceAliases を使用すると、Talk ディレクティブで親しみやすい名前を使用できます。
silenceTimeoutMs は、ユーザーが黙ってから文字起こしを送信するまでの待ち時間を制御します。未設定の場合は、プラットフォームのデフォルトの休止ウィンドウ（macOS と Android では 700 ms、iOS では 900 ms）が使用されます。

ツール（Tools）

ツールプロファイル

tools.profile は、 tools.allow/tools.deny が適用される前のベースとなる許可リストを設定します。

ローカルでのオンボーディング時、設定が未指定の場合はデフォルトで tools.profile: "coding" が設定されます（既存の明示的なプロファイルは保持されます）。

プロファイル	含まれる内容
`minimal`	`session_status` のみ
`coding`	`group:fs`, `group:runtime`, `group:sessions`, `group:memory`, `image`
`messaging`	`group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status`
`full`	制限なし（未設定と同じ）

ツールグループ

グループ	ツール
`group:runtime`	`exec`, `process` (`bash` は `exec` のエイリアスとして使用可能)
`group:fs`	`read`, `write`, `edit`, `apply_patch`
`group:sessions`	`sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status`
`group:memory`	`memory_search`, `memory_get`
`group:web`	`web_search`, `web_fetch`
`group:ui`	`browser`, `canvas`
`group:automation`	`cron`, `gateway`
`group:messaging`	`message`
`group:nodes`	`nodes`
`group:openclaw`	すべての組み込みツール（プロバイダープラグインを除く）

`tools.allow` / `tools.deny`

グローバルなツールの許可/拒否ポリシーです（拒否が優先されます）。大文字と小文字を区別せず、 * ワイルドカードをサポートしています。Docker サンドボックスがオフの場合でも適用されます。

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

`tools.byProvider`

特定のプロバイダーやモデルに対して、さらにツールを制限します。適用順序は、ベースプロファイル → プロバイダープロファイル → 個別の allow/deny です。

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

`tools.elevated`

昇格した（ホスト上の）実行アクセスを制御します：

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

エージェントごとの上書き（agents.list[].tools.elevated）では、制限を強めることのみ可能です。
/elevated on|off|ask|full コマンドはセッションごとに状態を保存します。インラインディレクティブは単一のメッセージに適用されます。
昇格した exec はホスト上で実行され、サンドボックスをバイパスします。

`tools.exec`

{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      notifyOnExit: true,
      notifyOnExitEmptySuccess: false,
      applyPatch: {
        enabled: false,
        allowModels: ["gpt-5.2"],
      },
    },
  },
}

`tools.loopDetection`

ツールループの安全性チェックは、デフォルトで無効になっています。有効にするには enabled: true を設定してください。設定は tools.loopDetection でグローバルに定義でき、 agents.list[].tools.loopDetection でエージェントごとに上書きできます。

{
  tools: {
    loopDetection: {
      enabled: true,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}

historySize: ループ分析のために保持されるツール呼び出し履歴の最大数。
warningThreshold: 進捗のないパターンが繰り返された場合に警告を出すしきい値。
criticalThreshold: 致命的なループをブロックするための、より高い繰り返ししきい値。
globalCircuitBreakerThreshold: 進捗のない実行を強制停止するハードなしきい値。
detectors.genericRepeat: 同じツールや引数での呼び出しが繰り返された場合に警告します。
detectors.knownPollNoProgress: 既知のポーリングツール（process.poll, command_status など）で警告またはブロックします。
detectors.pingPong: 交互に繰り返される進捗のないペアパターンで警告またはブロックします。
warningThreshold >= criticalThreshold または criticalThreshold >= globalCircuitBreakerThreshold の場合、バリデーションは失敗します。

`tools.web`

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // または BRAVE_API_KEY 環境変数
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        userAgent: "custom-ua",
      },
    },
  },
}

`tools.media`

インバウンドメディア（画像/音声/動画）の理解を設定します：

{
  tools: {
    media: {
      concurrency: 2,
      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" }],
      },
    },
  },
}

メディアモデルのエントリフィールド

プロバイダーエントリ (type: "provider" または省略時):

provider: API プロバイダー ID (openai, anthropic, google/gemini, groq など)
model: モデル ID の上書き
profile / preferredProfile: auth-profiles.json のプロファイル選択

CLI エントリ (type: "cli"):

command: 実行するコマンド
args: テンプレート化された引数（{{MediaPath}}, {{Prompt}}, {{MaxChars}} などをサポート）

共通フィールド:

capabilities: オプションのリスト (image, audio, video)。デフォルト： openai/anthropic/minimax → image、 google → image+audio+video、 groq → audio。
prompt, maxChars, maxBytes, timeoutSeconds, language: エントリごとの上書き。
失敗した場合は、次のエントリにフォールバックします。

プロバイダー認証は標準の順序に従います： auth-profiles.json → 環境変数 → models.providers.*.apiKey。

`tools.agentToAgent`

{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },
}

`tools.sessions`

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

デフォルト： tree（現在のセッション + サブエージェントなどのそこから派生したセッション）。

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

注意点：

self: 現在のセッションキーのみ。
tree: 現在のセッション + 現在のセッションから生成されたセッション（サブエージェント）。
agent: 現在のエージェント ID に属するすべてのセッション（同じエージェント ID で送信者ごとにセッションを実行している場合、他のユーザーのものも含まれる可能性があります）。
all: すべてのセッション。エージェントをまたぐターゲット指定には、引き続き tools.agentToAgent が必要です。
サンドボックスの制限：現在のセッションがサンドボックス化されており、 agents.defaults.sandbox.sessionToolsVisibility="spawned" の場合、 tools.sessions.visibility="all" と設定されていても、可視性は強制的に tree になります。

`tools.sessions_spawn`

sessions_spawn におけるインライン添付ファイルのサポートを制御します。

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // opt-in: set true to allow inline file attachments
        maxTotalBytes: 5242880, // 5 MB total across all files
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB per file
        retainOnSessionKeep: false, // keep attachments when cleanup="keep"
      },
    },
  },
}

注意点：

添付ファイルは runtime: "subagent" でのみサポートされます。ACP ランタイムでは拒否されます。
ファイルは子ワークスペースの .openclaw/attachments/<uuid>/ に .manifest.json と共に実体化されます。
添付ファイルの内容は、文字起こしの永続化時に自動的に秘匿化（redact）されます。
Base64 入力は、厳密なアルファベット/パディングチェックとデコード前のサイズガードによって検証されます。
ファイル権限は、ディレクトリが 0700、ファイルが 0600 です。
クリーンアップは cleanup ポリシーに従います： delete は常に添付ファイルを削除し、 keep は retainOnSessionKeep: true の場合にのみ保持します。

`tools.subagents`

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

model: 生成されたサブエージェントのデフォルトモデル。省略された場合、サブエージェントは呼び出し元のモデルを継承します。
runTimeoutSeconds: ツール呼び出しで runTimeoutSeconds が省略された場合の sessions_spawn のデフォルトタイムアウト（秒）。 0 はタイムアウトなしを意味します。
サブエージェントごとのツールポリシー： tools.subagents.tools.allow / tools.subagents.tools.deny。

カスタムプロバイダーとベース URL（Custom providers and base URLs）

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) で上書きできます。
プロバイダー ID が一致する場合のマージ優先順位：
- エージェントの models.json にある空でない baseUrl が優先されます。
- エージェントの空でない apiKey は、そのプロバイダーが現在の設定/認証プロファイルで SecretRef 管理されていない場合にのみ優先されます。
- SecretRef 管理されているプロバイダーの apiKey は、解決されたシークレットを永続化するのではなく、ソースマーカー（環境変数の場合は ENV_VAR_NAME、ファイル/実行リファレンスの場合は secretref-managed）からリフレッシュされます。
- SecretRef 管理されているプロバイダーのヘッダー値は、ソースマーカー（環境変数の場合は secretref-env:ENV_VAR_NAME、ファイル/実行リファレンスの場合は secretref-managed）からリフレッシュされます。
- エージェントの apiKey/baseUrl が空または欠落している場合は、設定内の models.providers にフォールバックします。
- 一致するモデルの contextWindow/maxTokens は、明示的な設定と暗黙的なカタログ値のうち、高い方の値が使用されます。
- 設定で models.json を完全に書き換えたい場合は、 models.mode: "replace" を使用してください。
- マーカーの永続化はソース優先です。マーカーは、解決された実行時のシークレット値からではなく、アクティブなソース設定スナップショット（解決前）から書き込まれます。

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

models.mode: プロバイダーカタログの動作 (merge または replace)。
models.providers: プロバイダー ID をキーとしたカスタムプロバイダーマップ。
models.providers.*.api: リクエストアダプター (openai-completions, openai-responses, anthropic-messages, google-generative-ai など)。
models.providers.*.apiKey: プロバイダーの認証情報（SecretRef/環境変数置換を推奨）。
models.providers.*.auth: 認証戦略 (api-key, token, oauth, aws-sdk)。
models.providers.*.injectNumCtxForOpenAICompat: Ollama + openai-completions の場合、リクエストに options.num_ctx を注入します（デフォルト： true）。
models.providers.*.authHeader: 必要に応じて Authorization ヘッダーでの認証情報転送を強制します。
models.providers.*.baseUrl: アップストリーム API のベース URL。
models.providers.*.headers: プロキシやテナントルーティング用の追加の静的ヘッダー。
models.providers.*.models: 明示的なプロバイダーモデルカタログエントリ。
models.providers.*.models.*.compat.supportsDeveloperRole: オプションの互換性ヒント。 api: "openai-completions" かつ baseUrl が空でなくネイティブでない（ホストが api.openai.com ではない）場合、OpenClaw は実行時にこれを強制的に false にします。 baseUrl が空または省略されている場合は、デフォルトの OpenAI の動作を維持します。
models.bedrockDiscovery: Bedrock 自動検出設定のルート。
models.bedrockDiscovery.enabled: 検出ポーリングのオン/オフを切り替えます。
models.bedrockDiscovery.region: 検出用の AWS リージョン。
models.bedrockDiscovery.providerFilter: 特定の検出をターゲットにするためのオプションのプロバイダー ID フィルタ。
models.bedrockDiscovery.refreshInterval: 検出リフレッシュのポーリング間隔。
models.bedrockDiscovery.defaultContextWindow: 検出されたモデルのフォールバックコンテキストウィンドウ。
models.bedrockDiscovery.defaultMaxTokens: 検出されたモデルのフォールバック最大出力トークン。

プロバイダーの例

Cerebras (GLM 4.6 / 4.7)

{
  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 を使用します。

OpenCode

{
  agents: {
    defaults: {
      model: { primary: "opencode/claude-opus-4-6" },
      models: { "opencode/claude-opus-4-6": { alias: "Opus" } },
    },
  },
}

OPENCODE_API_KEY (または OPENCODE_ZEN_API_KEY) を設定してください。Zen カタログには opencode/... リファレンスを、Go カタログには opencode-go/... リファレンスを使用します。ショートカット： openclaw onboard --auth-choice opencode-zen または openclaw onboard --auth-choice opencode-go。

Z.AI (GLM-4.7)

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

ZAI_API_KEY を設定してください。 z.ai/* および z-ai/* もエイリアスとして受け入れられます。ショートカット： openclaw onboard --auth-choice zai-api-key。

一般エンドポイント： https://api.z.ai/api/paas/v4
コーディングエンドポイント（デフォルト）： https://api.z.ai/api/coding/paas/v4
一般エンドポイントを使用する場合は、ベース URL を上書きしたカスタムプロバイダーを定義してください。

Moonshot AI (Kimi)

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

中国エンドポイントの場合： baseUrl: "https://api.moonshot.cn/v1" または openclaw onboard --auth-choice moonshot-api-key-cn。

Kimi Coding

{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "kimi-coding/k2p5" },
      models: { "kimi-coding/k2p5": { alias: "Kimi K2.5" } },
    },
  },
}

Anthropic 互換の組み込みプロバイダーです。ショートカット： openclaw onboard --auth-choice kimi-code-api-key。

Synthetic (Anthropic 互換)

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

ベース URL から /v1 を除いてください（Anthropic クライアントが自動的に付与します）。ショートカット： openclaw onboard --auth-choice synthetic-api-key。

MiniMax M2.5 (直接)

{
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.5" },
      models: {
        "minimax/MiniMax-M2.5": { alias: "Minimax" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.5",
            name: "MiniMax M2.5",
            reasoning: false,
            input: ["text"],
            cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

MINIMAX_API_KEY を設定してください。ショートカット： openclaw onboard --auth-choice minimax-api。

ローカルモデル (LM Studio)

ローカルモデルを参照してください。要約：高性能なハードウェア上で LM Studio Responses API を介して MiniMax M2.5 を実行し、フォールバック用にホスト型モデルをマージしておきます。

スキル（Skills）

{
  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" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

allowBundled: バンドルされたスキル専用のオプションの許可リストです。管理済みスキルやワークスペースのスキルには影響しません。
entries 設定: enabled: false を指定すると、スキルがバンドルまたはインストールされていても無効化できます。また、apiKey フィールドを使うと、主要な環境変数をプレーンテキストや SecretRef オブジェクトで簡単に設定できて便利です。

プラグイン（Plugins）

{
  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.entries.<id>.apiKey: プラグインがサポートしている場合に、プラグインレベルの API key を設定できる便利なフィールドです。
plugins.entries.<id>.env: プラグインのスコープ内で使用される環境変数のマップです。
plugins.entries.<id>.hooks.allowPromptInjection: false に設定すると、コア機能が before_prompt_build をブロックします。これにより、レガシーな before_agent_start からのプロンプト変更フィールドが無視されますが、modelOverride や providerOverride はそのまま保持されます。
plugins.entries.<id>.config: プラグインごとに定義される設定オブジェクトです。プラグインのスキーマに従って検証されます。
plugins.slots.memory: 使用するメモリプラグインの ID を選択します。メモリ機能をオフにする場合は "none" を指定してください。
plugins.slots.contextEngine: 使用するコンテキストエンジンプラグインの ID を選択します。別のエンジンをインストールして選択しない限り、デフォルトは "legacy" になります。
plugins.installs: openclaw plugins update コマンドで管理されるインストールのメタデータです。
これには source, spec, sourcePath, installPath, version, resolvedName, resolvedVersion, resolvedSpec, integrity, shasum, resolvedAt, installedAt といった情報が含まれます。
plugins.installs.* の内容は管理された状態として扱うため、手動で編集するよりも CLI コマンドを使って操作することをおすすめします。

詳細は Plugins を参照してください。

ブラウザ（Browser）

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "chrome",
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // default trusted-network mode
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
    // headless: false,
    // noSandbox: false,
    // extraArgs: [],
    // relayBindHost: "0.0.0.0", // only when the extension relay must be reachable across namespaces (for example WSL2)
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false,
  },
}

evaluateEnabled: false に設定すると、act:evaluate や wait --fn が使えなくなります。
ssrfPolicy.dangerouslyAllowPrivateNetwork は、設定されていない場合デフォルトで true（信頼されたネットワークモード）になります。
パブリックネットワークのみにアクセスを制限したい場合は、ssrfPolicy.dangerouslyAllowPrivateNetwork: false に設定してください。
ssrfPolicy.allowPrivateNetwork は、レガシーなエイリアスとして引き続きサポートされています。
制限モードを使用しているときは、ssrfPolicy.hostnameAllowlist や ssrfPolicy.allowedHostnames を使って明示的に例外を許可できます。
リモートプロファイルはアタッチ専用の設定です。開始、停止、リセットの操作はできません。
ブラウザの自動検出は、Chromium ベースのデフォルトブラウザ → Chrome → Brave → Edge → Chromium → Chrome Canary の順で行われます。
コントロールサービスはループバックのみで動作します。ポートは gateway.port から計算され、デフォルトは 18791 です。
extraArgs を使うと、ローカルの Chromium 起動時に --disable-gpu やウィンドウサイズ、デバッグ用のフラグなどを追加できます。
relayBindHost は Chrome 拡張機能のリレーがリッスンするアドレスを変更します。通常は未設定（ループバックのみ）で問題ありません。WSL2 などで名前空間を越えてリレーにアクセスする必要があり、かつネットワークが信頼できる場合にのみ、0.0.0.0 などを設定してください。

UI（ユーザーインターフェース）

{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // emoji, short text, image URL, or data URI
    },
  },
}

seamColor: Talk Mode のバブルの色など、アプリの UI で使われるアクセントカラーを指定します。
assistant: UI 上の表示名を上書きします。設定しない場合は、現在アクティブなエージェントの名前が表示されます。

ゲートウェイ

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      // root: "dist/control-ui",
      // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
      // allowInsecureAuth: false,
      // dangerouslyDisableDeviceAuth: false,
    },
    remote: {
      url: "ws://gateway.tailnet:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
      // password: "your-password",
    },
    trustedProxies: ["10.0.0.1"],
    // Optional. Default false.
    allowRealIpFallback: false,
    tools: {
      // Additional /tools/invoke HTTP denies
      deny: ["browser"],
      // Remove tools from the default HTTP deny list
      allow: ["gateway"],
    },
  },
}

Gateway field details

mode: local（Gatewayを実行）または remote（リモートのGatewayに接続）を指定します。local に設定しない限り、Gatewayは起動しません。
port: WS と HTTP で共有される単一のポートです。優先順位は、--port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789 となります。
bind: auto、loopback（デフォルト）、lan（0.0.0.0）、tailnet（Tailscale IPのみ）、または custom から選択します。
レガシーな bind エイリアス: gateway.bind には、ホスト名のエイリアス（0.0.0.0 や localhost など）ではなく、上記の bind モードの値を指定してください。
Docker に関する注意: デフォルトの loopback 設定は、コンテナ内の 127.0.0.1 でリスンします。Docker のブリッジネットワーク（-p 18789:18789）を使用する場合、トラフィックは eth0 に届くため、Gateway にアクセスできなくなります。--network host を使用するか、bind: "lan"（または bind: "custom" と customBindHost: "0.0.0.0" の組み合わせ）を設定して、すべてのインターフェースでリスンするようにしてください。
Auth: デフォルトで必須です。loopback 以外の bind を使用する場合は、共有トークンまたはパスワードが必要です。オンボーディングウィザードでは、デフォルトでトークンが生成されます。
gateway.auth.token と gateway.auth.password の両方が設定されている場合（SecretRef を含む）、gateway.auth.mode を token または password に明示的に設定してください。両方が設定され、かつモードが未指定の場合、起動やサービスのインストール・修復フローが失敗します。
gateway.auth.mode: "none": 認証なしモードです。信頼できるローカルの loopback 環境でのみ使用してください。この設定は、オンボーディングのプロンプトでは意図的に選択できないようになっています。
gateway.auth.mode: "trusted-proxy": 認証を ID 認識型のリバースプロキシに委譲します。gateway.trustedProxies からの ID ヘッダーを信頼します（詳細は Trusted Proxy Auth を参照）。
gateway.auth.allowTailscale: true の場合、Tailscale Serve の ID ヘッダーを使用して Control UI や WebSocket の認証をパスできます（tailscale whois で検証されます）。ただし、HTTP API エンドポイントには引き続きトークンまたはパスワードによる認証が必要です。このトークンレスのフローは、Gateway ホストが信頼されていることを前提としています。tailscale.mode = "serve" の場合、デフォルトは true です。
gateway.auth.rateLimit: 認証失敗時のリミッター設定（任意）です。クライアント IP ごと、および認証スコープ（共有シークレットとデバイス・トークンは個別に追跡）ごとに適用されます。ブロックされたリクエストには 429 エラーと Retry-After ヘッダーが返されます。
- gateway.auth.rateLimit.exemptLoopback はデフォルトで true です。テスト環境や厳格なプロキシ運用などで、localhost からのトラフィックも制限したい場合は false に設定してください。
ブラウザオリジンの WS 認証の試行は、loopback の除外設定が無効な状態で常にスロットリングされます（ブラウザベースの localhost へのブルートフォース攻撃に対する多層防御のため）。
tailscale.mode: serve（tailnet のみ、loopback bind）または funnel（公開設定、認証必須）を指定します。
controlUi.allowedOrigins: Gateway の WebSocket 接続を許可するブラウザオリジンのホワイトリストです。loopback 以外のオリジンからブラウザクライアントを使用する場合に必要です。
controlUi.dangerouslyAllowHostHeaderOriginFallback: Host ヘッダーによるオリジンフォールバックを有効にする危険なモードです。Host ヘッダーのオリジンポリシーに意図的に依存するデプロイメントで使用します。
remote.transport: ssh（デフォルト）または direct（ws/wss）を指定します。direct の場合、remote.url は ws:// または wss:// である必要があります。
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1: 信頼されたプライベートネットワーク IP へのプレーンテキスト ws:// 接続を許可するクライアント側のオーバーライド設定です。デフォルトでは loopback のみがプレーンテキストを許可します。
gateway.remote.token / .password: リモートクライアント用の認証フィールドです。これら自体が Gateway の認証を構成するわけではありません。
ローカルの Gateway 呼び出しパスでは、gateway.auth.* が未設定の場合にのみ、gateway.remote.* がフォールバックとして使用されます。
gateway.auth.token または gateway.auth.password が SecretRef を通じて明示的に設定され、かつ解決できない場合、フォールバックは行われず処理は失敗します。
trustedProxies: TLS を終端するリバースプロキシの IP アドレスです。自身が管理しているプロキシのみをリストに追加してください。
allowRealIpFallback: true の場合、X-Forwarded-For が存在しないときに X-Real-IP を受け入れます。デフォルトは false で、より安全な動作（fail-closed）となります。
gateway.tools.deny: HTTP POST /tools/invoke でブロックするツール名を追加します（デフォルトの拒否リストを拡張します）。
gateway.tools.allow: デフォルトの HTTP 拒否リストからツール名を除外します。

OpenAI互換エンドポイント

Chat Completions: デフォルトでは無効です。gateway.http.endpoints.chatCompletions.enabled: true で有効化できます。
Responses API: gateway.http.endpoints.responses.enabled で設定します。
Responses URL 入力のセキュリティ強化:
- gateway.http.endpoints.responses.maxUrlParts
- gateway.http.endpoints.responses.files.urlAllowlist
- gateway.http.endpoints.responses.images.urlAllowlist
任意のセキュリティヘッダー設定:
- gateway.http.securityHeaders.strictTransportSecurity（自身が管理する HTTPS オリジンに対してのみ設定してください。詳細は Trusted Proxy Auth を参照）

マルチインスタンスの分離

1つのホスト上で、ポートと状態ディレクトリ（state dir）を分けて複数の Gateway を実行できます。

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? }
- リクエストペイロードからの sessionKey は、hooks.allowRequestSessionKey=true（デフォルトは false）の場合のみ受け入れられます。
POST /hooks/<name> → hooks.mappings に基づいて解決されます。

Mapping details

match.path: /hooks 以降のサブパスにマッチします（例: /hooks/gmail → gmail）。
match.source: 汎用パスにおいて、ペイロード内の特定のフィールドにマッチさせます。
{{messages[0].subject}} のようなテンプレートを使用して、ペイロードから値を読み取れます。
transform: フックのアクションを返す JS/TS モジュールを指定できます。
- transform.module は相対パスである必要があり、hooks.transformsDir 内に制限されます（絶対パスやディレクトリトラバーサルは拒否されます）。
agentId: 特定のエージェントにルーティングします。不明な ID の場合はデフォルトにフォールバックします。
allowedAgentIds: 明示的なルーティングを制限します（* または省略で全許可、[] で全拒否）。
defaultSessionKey: sessionKey が指定されていないフック実行時に使用される、任意の固定セッションキーです。
allowRequestSessionKey: /hooks/agent の呼び出し元が sessionKey を設定することを許可します（デフォルトは false）。
allowedSessionKeyPrefixes: 明示的な sessionKey（リクエストまたはマッピング内）に対するプレフィックスのホワイトリストです（例: ["hook:"]）。
deliver: true: 最終的な返信をチャンネルに送信します。channel のデフォルトは last です。
model: このフック実行で使用する LLM を上書きします（モデルカタログが設定されている場合は、許可されている必要があります）。

Gmail連携

{
  hooks: {
    gmail: {
      account: "openclaw@gmail.com",
      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,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

設定されている場合、Gateway は起動時に gog gmail watch serve を自動的に開始します。無効にするには OPENCLAW_SKIP_GMAIL_WATCHER=1 を設定してください。
Gateway とは別に gog gmail watch serve を実行しないでください。

キャンバスホスト

{
  canvasHost: {
    root: "~/.openclaw/workspace/canvas",
    liveReload: true,
    // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1
  },
}

エージェントが編集可能な HTML/CSS/JS および A2UI を、Gateway ポート経由の HTTP で提供します。
- http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
- http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
ローカル専用の場合: gateway.bind: "loopback"（デフォルト）のままにしてください。
loopback 以外の bind の場合: キャンバスのルートへのアクセスには、他の Gateway HTTP サービスと同様に認証（トークン/パスワード/trusted-proxy）が必要です。
Node WebViews は通常、認証ヘッダーを送信しません。ノードがペアリングされ接続された後、Gateway はキャンバス/A2UI アクセス用のノードスコープの Capability URL を通知します。
Capability URL はアクティブなノードの WS セッションに紐付けられており、短時間で期限切れになります。IP ベースのフォールバックは使用されません。
提供される HTML にライブリロードクライアントを自動的に挿入します。
ディレクトリが空の場合、スターター用の index.html を自動作成します。
/__openclaw__/a2ui/ で A2UI も提供します。
設定の変更を反映するには Gateway の再起動が必要です。
大規模なディレクトリで EMFILE エラーが発生する場合は、ライブリロードを無効にしてください。

ディスカバリー

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 の Split DNS を組み合わせてください。

セットアップ方法: openclaw dns setup --apply

AI Setup Assistant

Environment（環境設定）

`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_]*）のみがマッチします。
変数が存在しない、または空の場合は、設定の読み込み時にエラーが発生します。
${VAR} という文字列をそのまま記述したい場合は、$${VAR} とエスケープしてください。
$include 内でも利用可能です。

Secrets（シークレット）

シークレットの参照は追加的な機能です。プレーンテキストでの値も引き続き利用できます。

`SecretRef`

以下のオブジェクト形式を使用します。

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

バリデーション：

provider のパターン：^[a-z][a-z0-9_-]{0,63}$
source: "env" の id パターン：^[A-Z][A-Z0-9_]{0,127}$
source: "file" の id：絶対パス形式の JSON ポインター（例："/providers/openai/apiKey"）
source: "exec" の id パターン：^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
source: "exec" の id には、スラッシュで区切られた . や .. を含めることはできません（例：a/../b は拒否されます）。

サポートされている認証情報の範囲

対応マトリックス：SecretRef Credential Surface
secrets apply は、openclaw.json 内のサポートされている認証情報パスを対象とします。
auth-profiles.json の参照は、実行時の解決および監査の対象に含まれます。

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

{
  secrets: {
    providers: {
      default: { source: "env" }, // optional explicit env provider
      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",
    },
  },
}

注意点：

file プロバイダーは mode: "json" と mode: "singleValue" をサポートしています（singleValue モードでは id を "value" にする必要があります）。
exec プロバイダーは実行コマンドの絶対パスが必要で、stdin/stdout を介したプロトコルを使用します。
デフォルトでは、シンボリックリンクのコマンドパスは拒否されます。解決後のターゲットパスを検証しつつシンボリックリンクを許可するには、allowSymlinkCommand: true を設定してください。
trustedDirs が設定されている場合、信頼されたディレクトリのチェックは解決後のターゲットパスに適用されます。
exec の子プロセス環境はデフォルトで最小限です。必要な変数は passEnv で明示的に渡してください。
シークレットの参照は、アクティベーション時にメモリ内のスナップショットに解決されます。その後、リクエストパスはそのスナップショットのみを読み取ります。
アクティベーション中にアクティブな範囲のフィルタリングが適用されます。有効な範囲で未解決の参照がある場合は起動やリロードに失敗しますが、非アクティブな範囲は診断情報とともにスキップされます。

Auth ストレージ

{
  auth: {
    profiles: {
      "anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
    },
    order: {
      anthropic: ["anthropic:me@example.com", "anthropic:work"],
    },
  },
}

エージェントごとのプロファイルは、<agentDir>/auth-profiles.json に保存されます。
auth-profiles.json は、値レベルの参照（api_key のための keyRef や token のための tokenRef）をサポートしています。
静的なランタイム認証情報は、メモリ内で解決されたスナップショットから取得されます。古い形式の静的な auth.json エントリが見つかった場合は、自動的にクリーンアップされます。
以前の OAuth 設定は ~/.openclaw/credentials/oauth.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 を設定してください。
--verbose フラグを使用すると、consoleLevel は debug に引き上げられます。

CLI

CLIの表示を自分好みにカスタマイズする方法を紹介します。

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

cli.banner.taglineMode を設定することで、バナーに表示されるキャッチコピー（tagline）のスタイルをコントロールできます。

"random"（デフォルト）: 遊び心のあるフレーズや季節ごとのキャッチコピーが入れ替わりで表示されます。
"default": 標準的なキャッチコピー（All your chats, one OpenClaw.）に固定されます。
"off": キャッチコピーを非表示にします。この場合も、バナーのタイトルやバージョンは引き続き表示されます。

もしキャッチコピーだけでなく、バナー全体を完全に非表示にしたいのであれば、環境変数に OPENCLAW_HIDE_BANNER=1 を設定するのがベストな方法です。

ウィザード

onboard、configure、doctor といった CLI のウィザードを実行すると、以下のようなメタデータが自動的に書き込まれます。

{
  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: "🦥",
          avatar: "avatars/samantha.png",
        },
      },
    ],
  },
}

macOS のオンボーディングアシスタントによって書き込まれる項目です。ここでの設定に基づいて、以下のデフォルト値が自動的に適用されます。

messages.ackReaction（identity.emoji を参照、未設定時は 👀）と mentionPatterns は、この設定から自動的に生成されます。
avatar には、ワークスペース内の相対パス、http(s) URL、または data: URI を指定できます。

Bridge（レガシー、削除済み）

最新のビルドには TCP bridge は含まれていません。Node は Gateway WebSocket を介して接続する仕様に変更されました。bridge.* キーは設定スキーマに含まれなくなったため、これらが残っているとバリデーションエラーが発生します。手動で削除するか、openclaw doctor --fix を実行して不明なキーを自動でクリーンアップしてください。

レガシーな Bridge 設定（履歴用リファレンス）

{
  "bridge": {
    "enabled": true,
    "port": 18790,
    "bind": "tailnet",
    "tls": {
      "enabled": true,
      "autoGenerate": true
    }
  }
}

Cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
    sessionRetention: "24h", // duration string or false
    runLog: {
      maxBytes: "2mb", // default 2_000_000 bytes
      keepLines: 2000, // default 2000
    },
  },
}

sessionRetention: 完了した個別の Cron 実行セッションを sessions.json から削除するまでの保持期間を指定します。削除済みの Cron トランスクリプトのクリーンアップもこの設定で制御します。デフォルトは 24h です。無効にする場合は false を設定してください。
runLog.maxBytes: 実行ログファイル（cron/runs/<jobId>.jsonl）が削減される前の最大サイズです。デフォルトは 2_000_000 バイトです。
runLog.keepLines: 実行ログの削減が実行された際に保持される、最新の行数です。デフォルトは 2000 です。
webhookToken: Cron の Webhook POST 送信（delivery.mode = "webhook"）に使用される Bearer トークンです。省略した場合、認証ヘッダーは送信されません。
webhook: 非推奨（deprecated）のレガシーなフォールバック用 Webhook URL (http/https) です。notify: true が設定されたまま保存されているジョブにのみ使用されます。

詳細は Cron Jobs を参照してください。

Media model テンプレート変数

tools.media.models[].args 内で使用できるテンプレート変数（プレースホルダー）は以下の通りです。

変数	説明
`{{Body}}`	受信メッセージの本文全文
`{{RawBody}}`	生の本文（履歴や送信者のラッパーなし）
`{{BodyStripped}}`	グループメンションを除去した本文
`{{From}}`	送信者の識別子
`{{To}}`	送信先の識別子
`{{MessageSid}}`	チャネルのメッセージ ID
`{{SessionId}}`	現在のセッション UUID
`{{IsNewSession}}`	新しいセッションが作成された場合に `"true"` となる
`{{MediaUrl}}`	受信メディアの疑似 URL
`{{MediaPath}}`	ローカルのメディアパス
`{{MediaType}}`	メディアタイプ (image/audio/document/…)
`{{Transcript}}`	音声の文字起こし
`{{Prompt}}`	CLI エントリ用に解決されたメディアプロンプト
`{{MaxChars}}`	CLI エントリ用に解決された最大出力文字数
`{{ChatType}}`	`"direct"` または `"group"`
`{{GroupSubject}}`	グループの件名（ベストエフォート）
`{{GroupMembers}}`	グループメンバーのプレビュー（ベストエフォート）
`{{SenderName}}`	送信者の表示名（ベストエフォート）
`{{SenderE164}}`	送信者の電話番号（ベストエフォート）
`{{Provider}}`	プロバイダーのヒント (whatsapp, telegram, discord など)

設定のインクルード ($include)

設定ファイルを複数のファイルに分割して管理できます。

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

マージの挙動:

単一ファイルの場合: 記述されたオブジェクトをそのファイルの内容で置き換えます。
ファイルの配列の場合: 指定された順序でディープマージされます（後から読み込まれたファイルが前の内容を上書きします）。
同階層のキー: インクルードされた内容の後にマージされます（インクルードされた値を上書きします）。
ネストされたインクルード: 最大 10 レベルの深さまでサポートしています。
パス: インクルード元のファイルからの相対パスで解決されます。ただし、トップレベルの設定ディレクトリ（openclaw.json があるディレクトリ）の内部に収まっている必要があります。絶対パスや ../ 形式は、その境界内に収まる場合にのみ許可されます。
エラー: ファイルが見つからない場合、パースエラー、循環インクルードが発生した場合は、明確なエラーメッセージが表示されます。

関連: Configuration · Configuration Examples · Doctor

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

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

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

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

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。

OpenClaw設定ガイド：チャンネルとDMポリシーを最適化する

チャンネル

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

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

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

WhatsApp

Telegram

Discord

Google Chat

Slack

Mattermost

Signal

BlueBubbles

iMessage

Microsoft Teams

IRC

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

その他の拡張チャンネル

グループチャットのメンション制限

DM 履歴制限

セルフチャットモード

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

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

agents.defaults.workspace

agents.defaults.repoRoot

agents.defaults.skipBootstrap

agents.defaults.bootstrapMaxChars

agents.defaults.bootstrapTotalMaxChars

agents.defaults.bootstrapPromptTruncationWarning

agents.defaults.imageMaxDimensionPx

agents.defaults.userTimezone

agents.defaults.timeFormat

agents.defaults.model

agents.defaults.cliBackends

agents.defaults.heartbeat

agents.defaults.compaction

agents.defaults.contextPruning

ブロックストリーミング

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

agents.defaults.sandbox

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

メッセージ

レスポンスの接頭辞（Response prefix）

確認リアクション（Ack reaction）

インバウンド・デバウンス（Inbound debounce）

TTS (テキスト読み上げ)

トーク（Talk）

ツール（Tools）

ツールプロファイル

ツールグループ

tools.allow / tools.deny

tools.byProvider

tools.elevated

tools.exec

tools.loopDetection

tools.web

tools.media

tools.agentToAgent

tools.sessions

tools.sessions_spawn

tools.subagents

カスタムプロバイダーとベース URL（Custom providers and base URLs）

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

プロバイダーの例

スキル（Skills）

プラグイン（Plugins）

ブラウザ（Browser）

UI（ユーザーインターフェース）

ゲートウェイ

OpenAI互換エンドポイント

マルチインスタンスの分離

フック

Gmail連携

キャンバスホスト

ディスカバリー

mDNS (Bonjour)

広域 (DNS-SD)

Environment（環境設定）

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

環境変数の置換

`agents.defaults.workspace`

`agents.defaults.repoRoot`

`agents.defaults.skipBootstrap`

`agents.defaults.bootstrapMaxChars`

`agents.defaults.bootstrapTotalMaxChars`

`agents.defaults.bootstrapPromptTruncationWarning`

`agents.defaults.imageMaxDimensionPx`

`agents.defaults.userTimezone`

`agents.defaults.timeFormat`

`agents.defaults.model`

`agents.defaults.cliBackends`

`agents.defaults.heartbeat`

`agents.defaults.compaction`

`agents.defaults.contextPruning`

`agents.defaults.sandbox`

`agents.list` (エージェントごとのオーバーライド)

`tools.allow` / `tools.deny`

`tools.byProvider`

`tools.elevated`

`tools.exec`

`tools.loopDetection`

`tools.web`

`tools.media`

`tools.agentToAgent`

`tools.sessions`

`tools.sessions_spawn`

`tools.subagents`

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

`SecretRef`