OpenClaw 設定指南：自訂頻道存取與模型映射

頻道

每個頻道在設定區塊存在時會自動啟動（除非設定 enabled: false）。

DM 與群組存取權限

所有頻道都支援 DM policy 和 group policy：

DM policy	行為
`pairing` (預設)	未知傳送者會收到一次性配對碼；擁有者必須核准
`allowlist`	僅允許 `allowFrom`（或已配對的允許儲存空間）中的傳送者
`open`	允許所有傳入的 DM（需要設定 `allowFrom: ["*"]`）
`disabled`	忽略所有傳入的 DM

Group policy	行為
`allowlist` (預設)	僅允許符合設定的允許清單的群組
`open`	繞過群組允許清單（提及門檻 mention-gating 仍然適用）
`disabled`	封鎖所有群組/聊天室訊息

頻道模型覆寫

使用 channels.modelByChannel 將特定的頻道 ID 釘選到某個模型。數值接受 provider/model 或已設定的模型別名。當 Session 尚未設定模型覆寫（例如透過 /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",
      },
    },
  },
}

頻道預設值與心跳 (Heartbeat)

使用 channels.defaults 來設定跨 Provider 共用的 group-policy 和心跳行為：

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

channels.defaults.groupPolicy: 當 Provider 層級的 groupPolicy 未設定時的回退政策。
channels.defaults.heartbeat.showOk: 在心跳輸出中包含狀態健康的頻道。
channels.defaults.heartbeat.showAlerts: 在心跳輸出中包含降級或錯誤狀態。
channels.defaults.heartbeat.useIndicator: 渲染精簡的指標樣式心跳輸出。

WhatsApp 透過 Gateway 的網頁頻道（Baileys Web）執行。當存在已連結的 Session 時會自動啟動。

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // 藍色勾勾 (在 self-chat 模式下為 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,
    },
  },
}

多帳號 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 token: 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,
      },
    },
  },
}

Token: channels.discord.token，並以 DISCORD_BOT_TOKEN 作為預設帳號的回退方案。
提供明確 Discord token 的直接外傳呼叫會使用該 token；帳號重試/政策設定仍來自目前執行快照中選定的帳號。
選填的 channels.discord.defaultAccount 會在符合已設定的帳號 ID 時，覆寫預設帳號選擇。
傳送目標請使用 user:<id> (DM) 或 channel:<id> (伺服器頻道)；不接受純數字 ID。
伺服器 slug 為小寫且空格替換為 -；頻道 key 使用 slug 名稱（不含 #）。建議優先使用伺服器 ID。
預設會忽略機器人發送的訊息。allowBots: true 可啟用；使用 allowBots: "mentions" 則僅接受提及該機器人的訊息（機器人自身的訊息仍會被過濾）。
channels.discord.guilds.<id>.ignoreOtherMentions（及頻道覆寫）會丟棄提及其他使用者或身分組但未提及機器人的訊息（不包括 @everyone/@here）。
maxLinesPerMessage（預設 17）即使在 2000 字元內也會分割過長的訊息。
channels.discord.threadBindings 控制 Discord 執行緒綁定路由：
- enabled: 執行緒綁定 Session 功能的 Discord 覆寫（/focus, /unfocus, /agents, /session idle, /session max-age 以及綁定的傳送/路由）
- 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 components v2 容器的強調色。
channels.discord.voice 啟用 Discord 語音頻道對話以及選填的自動加入與 TTS 覆寫。
channels.discord.voice.daveEncryption 和 channels.discord.voice.decryptionFailureTolerance 會傳遞給 @discordjs/voice 的 DAVE 選項（預設分別為 true 和 24）。
OpenClaw 還會在重複解密失敗後，嘗試透過離開並重新加入語音會話來恢復語音接收。
channels.discord.streaming 是標準的串流模式 key。舊有的 streamMode 和布林值 streaming 會自動遷移。
channels.discord.autoPresence 將執行時的可用性映射到機器人狀態（healthy => 線上, degraded => 閒置, exhausted => 請勿打擾），並允許選填的狀態文字覆寫。
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 (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 是標準的串流模式 key。舊有的 streamMode 和布林值 streaming 會自動遷移。
傳送目標請使用 user:<id> (DM) 或 channel:<id>。

表情符號回應通知模式： off, own (預設), all, allowlist (來自 reactionAllowlist)。

執行緒 Session 隔離： thread.historyScope 可設定為每個執行緒獨立（預設）或在頻道內共用。thread.inheritParent 會將父頻道的對話紀錄複製到新執行緒。

typingReaction 在回覆執行期間為傳入的 Slack 訊息添加臨時回應，完成後移除。請使用 Slack 表情符號代碼，例如 "hourglass_flowing_sand"。

Action group	預設	備註
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（在 @-mention 時回應，預設）, onmessage（每條訊息都回應）, onchar（以觸發前綴開頭的訊息）。

當啟用 Mattermost 原生指令時：

commands.callbackPath 必須是路徑（例如 /api/channels/mattermost/command），而非完整 URL。
commands.callbackUrl 必須指向 OpenClaw gateway 端點，且 Mattermost 伺服器必須能存取。
對於私有/tailnet/內部回呼主機，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 帳號身分。
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
    },
  },
}

此處涵蓋的核心 key 路徑：channels.bluebubbles, channels.bluebubbles.dmPolicy。
選填的 channels.bluebubbles.defaultAccount 會在符合已設定的帳號 ID 時，覆寫預設帳號選擇。
完整的 BlueBubbles 頻道設定文件請見 BlueBubbles。

iMessage

OpenClaw 會啟動 imsg rpc (透過 stdio 的 JSON-RPC)。不需要守護行程 (daemon) 或連接埠。

{
  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 時，覆寫預設帳號選擇。
需要 Messages 資料庫的完整磁碟存取權限。
建議優先使用 chat_id:<id> 目標。使用 imsg chats --limit 20 列出聊天。
cliPath 可以指向 SSH wrapper；設定 remoteHost (host 或 user@host) 以進行 SCP 附件擷取。
attachmentRoots 和 remoteAttachmentRoots 限制傳入附件的路徑（預設：/Users/*/Library/Messages/Attachments）。
SCP 使用嚴格的主機金鑰檢查，請確保中繼主機金鑰已存在於 ~/.ssh/known_hosts。
channels.imessage.configWrites: 允許或拒絕由 iMessage 發起的設定寫入。

iMessage SSH wrapper 範例

#!/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
    },
  },
}

此處涵蓋的核心 key 路徑：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",
      },
    },
  },
}

此處涵蓋的核心 key 路徑：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...",
        },
      },
    },
  },
}

當省略 accountId 時（CLI + 路由）會使用 default。
環境變數中的 token 僅套用於 default 帳號。
基礎頻道設定會套用於所有帳號，除非在個別帳號中覆寫。
使用 bindings[].match.accountId 將每個帳號路由到不同的 Agent。
如果你在仍使用單帳號頂層頻道設定時，透過 openclaw channels add（或頻道引導）新增非預設帳號，OpenClaw 會先將帳號範圍的頂層單帳號數值移動到 channels.<channel>.accounts.default，以確保原始帳號能繼續運作。
現有的僅限頻道綁定（無 accountId）會繼續匹配預設帳號；帳號範圍的綁定仍為選填。
當具名帳號存在但缺少 default 時，openclaw doctor --fix 也會透過將帳號範圍的頂層單帳號數值移動到 accounts.default 來修復混合格式。

其他擴充頻道

許多擴充頻道設定為 channels.<id>，並在其專屬的頻道頁面中說明（例如飛書、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。請參閱完整的頻道索引：Channels。

群組聊天提及門檻 (Mention Gating)

群組訊息預設為 需要提及（元數據提及或正規表達式模式）。適用於 WhatsApp, Telegram, Discord, Google Chat 和 iMessage 群組聊天。

提及類型：

元數據提及 (Metadata mentions)：平台原生的 @-提及。在 WhatsApp self-chat 模式下會被忽略。
文字模式 (Text patterns)：agents.list[].groupChat.mentionPatterns 中的正規表達式模式。一律會檢查。
僅在可偵測時（原生提及或至少有一個模式）才會強制執行提及門檻。

{
  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 覆寫 → Provider 預設值 → 無限制（全部保留）。

支援頻道：telegram, whatsapp, discord, slack, signal, imessage, msteams。

Self-chat 模式

將你自己的號碼包含在 allowFrom 中以啟用 self-chat 模式（忽略原生 @-提及，僅回應文字模式）：

{
  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 (布林值或 "auto")。false 會清除先前註冊的指令。
channels.telegram.customCommands 可新增額外的 Telegram 機器人選單項目。
bash: true 為主機 shell 啟用 ! <cmd>。需要 tools.elevated.enabled 且傳送者位於 tools.elevated.allowFrom.<channel> 中。
config: true 啟用 /config（讀取/寫入 openclaw.json）。對於 gateway chat.send 客戶端，持久性的 /config set|unset 寫入還需要 operator.admin 權限；唯讀的 /config show 對一般寫入權限的 operator 客戶端仍然可用。
channels.<provider>.configWrites 依頻道管控設定變更（預設：true）。
對於多帳號頻道，channels.<provider>.accounts.<id>.configWrites 也會管控針對該帳號的寫入（例如 /allowlist --config --account <id> 或 /config set channels.<provider>.accounts.<id>...）。
allowFrom 是依 Provider 設定的。一旦設定，它就是唯一的授權來源（頻道允許清單/配對和 useAccessGroups 會被忽略）。
useAccessGroups: false 當未設定 allowFrom 時，允許指令繞過存取群組政策。

Agent 預設值

`agents.defaults.workspace`

預設值：~/.openclaw/workspace。

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

`agents.defaults.repoRoot`

選填的儲存庫根目錄，顯示在系統提示詞的 Runtime 行中。如果未設定，OpenClaw 會從 workspace 向上搜尋自動偵測。

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

`agents.defaults.skipBootstrap`

停用自動建立 workspace 引導檔案（AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md）。

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

`agents.defaults.bootstrapMaxChars`

每個 workspace 引導檔案在截斷前的最大字元數。預設值：20000。

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

`agents.defaults.bootstrapTotalMaxChars`

所有 workspace 引導檔案注入的總字元數上限。預設值：150000。

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

`agents.defaults.bootstrapPromptTruncationWarning`

控制當引導內容被截斷時，Agent 可見的警告文字。預設值："once"。

"off"：永遠不在系統提示詞中注入警告文字。
"once"：每個唯一的截斷特徵僅注入一次警告（建議）。
"always"：只要存在截斷，每次執行都會注入警告。

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

`agents.defaults.imageMaxDimensionPx`

在呼叫 Provider 之前，對話紀錄/工具圖片區塊中圖片長邊的最大像素尺寸。預設值：1200。

較低的值通常可以減少 Vision Token 的使用量，並縮小包含大量截圖的請求負載。較高的值則能保留更多視覺細節。

{
  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 })。
- 字串形式僅設定主要模型。
- 物件形式設定主要模型加上依序的故障轉移 (failover) 模型。
imageModel: 接受字串 ("provider/model") 或物件 ({ primary, fallbacks })。
- 作為 image 工具路徑的 Vision 模型設定。
- 當選定/預設的模型不接受圖片輸入時，也作為回退路由。
pdfModel: 接受字串 ("provider/model") 或物件 ({ primary, fallbacks })。
- 用於 pdf 工具的模型路由。
- 如果省略，pdf 工具會回退到 imageModel，然後回退到 Provider 的最佳預設值。
pdfMaxBytesMb: 當呼叫時未傳遞 maxBytesMb 時，pdf 工具的預設 PDF 大小限制。
pdfMaxPages: pdf 工具在擷取回退模式下考慮的預設最大頁數。
model.primary: 格式為 provider/model (例如 anthropic/claude-opus-4-6)。如果省略 provider，OpenClaw 會假設為 anthropic (已棄用)。
models: 為 /model 設定的模型目錄和允許清單。每個項目可以包含 alias (捷徑) 和 params (Provider 特定參數，例如 temperature, maxTokens, cacheRetention, context1m)。
params 合併優先順序 (設定)：以 agents.defaults.models["provider/model"].params 為基礎，然後由 agents.list[].params (匹配 Agent ID) 依 key 覆寫。
變更這些欄位的設定寫入工具（例如 /models set, /models set-image 以及回退的新增/移除指令）會儲存標準物件格式，並盡可能保留現有的回退列表。
maxConcurrent: 跨 Session 的最大平行 Agent 執行數（每個 Session 仍維持序列化執行）。預設值：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。 Z.AI 模型預設啟用 tool_stream 以進行工具呼叫串流。設定 agents.defaults.models["zai/<model>"].params.tool_stream 為 false 可停用。 Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 adaptive 思考。

`agents.defaults.cliBackends`

選填的 CLI 後端，用於僅限文字的回退執行（無工具呼叫）。在 API Provider 故障時作為備援非常有用。

{
  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 時支援 Session。
當 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 時，心跳執行使用輕量級引導上下文，僅保留 workspace 引導檔案中的 HEARTBEAT.md。
每個 Agent 設定：設定 agents.list[].heartbeat。當任何 Agent 定義了 heartbeat 時，僅有這些 Agent 會執行心跳。
心跳會執行完整的 Agent 輪次 —— 較短的間隔會消耗更多 Token。

`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 覆寫，僅用於壓縮摘要。當主 Session 應保持一個模型但壓縮摘要應在另一個模型執行時使用；若未設定，壓縮將使用 Session 的主要模型。
memoryFlush: 在自動壓縮前進行無聲的 Agent 輪次以儲存持久記憶。當 workspace 為唯讀時會跳過。

`agents.defaults.contextPruning`

在傳送給 LLM 之前，從記憶體上下文中修剪舊的工具結果。這不會修改磁碟上的 Session 歷史紀錄。

{
  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 控制修剪再次執行的頻率（在最後一次快取觸碰之後）。
修剪會先對過大的工具結果進行軟修剪 (soft-trim)，如有需要則對舊的工具結果進行硬清除 (hard-clear)。

軟修剪 (Soft-trim) 保留開頭 + 結尾，並在中間插入 ...。

硬清除 (Hard-clear) 將整個工具結果替換為預留位置。

備註：

圖片區塊永遠不會被修剪/清除。
比例是基於字元（近似值），而非精確的 Token 計數。
如果 Assistant 訊息少於 keepLastAssistants 條，則會跳過修剪。

行為詳情請見 Session Pruning。

區塊串流 (Block streaming)

{
  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。每個 Agent 覆寫：agents.list[].humanDelay。

行為與分段詳情請見 Streaming。

輸入指示器 (Typing indicators)

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

預設值：直接聊天/提及時為 instant，未提及的群組聊天為 message。
每個 Session 覆寫：session.typingMode, session.typingIntervalSeconds。

參見 Typing Indicators。

`agents.defaults.sandbox`

內嵌 Agent 的選填 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"],
      },
    },
  },
}

沙箱詳情

Workspace 存取：

none: 在 ~/.openclaw/sandboxes 下建立依範圍劃分的沙箱 workspace
ro: 沙箱 workspace 位於 /workspace，Agent workspace 以唯讀方式掛載於 /agent
rw: Agent workspace 以讀寫方式掛載於 /workspace

範圍 (Scope)：

session: 每個 Session 獨立的容器 + workspace
agent: 每個 Agent 一個容器 + workspace（預設）
shared: 共用容器與 workspace（無跨 Session 隔離）

setupCommand 在容器建立後執行一次（透過 sh -lc）。需要網路連線、可寫入的根目錄以及 root 使用者。

容器預設為 network: "none" —— 如果 Agent 需要外網存取，請設定為 "bridge"（或自定義橋接網路）。 "host" 被封鎖。"container:<id>" 預設被封鎖，除非你明確設定 sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true（緊急開關）。

傳入附件 會暫存到目前工作區的 media/inbound/*。

docker.binds 掛載額外的主機目錄；全域和每個 Agent 的掛載會合併。

沙箱瀏覽器 (sandbox.browser.enabled): 容器中的 Chromium + CDP。noVNC URL 會注入到系統提示詞中。不需要在 openclaw.json 中啟用 browser.enabled。 noVNC 觀察者存取預設使用 VNC 認證，OpenClaw 會發出短效 Token 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> 更改；設定為 0 則使用 Chromium 的預設程序限制。
- 加上 --no-sandbox 和 --disable-setuid-sandbox（當 noSandbox 啟用時）。
- 預設值為容器映像檔基準；使用自定義瀏覽器映像檔與自定義進入點可更改容器預設值。

建置映像檔：

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

`agents.list` (每個 Agent 的覆寫)

{
  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" }, // 依 key 覆寫匹配的 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: 穩定的 Agent ID（必填）。
default: 當設定多個時，第一個勝出（會記錄警告）。若未設定，列表第一個項目為預設。
model: 字串形式僅覆寫 primary；物件形式 { primary, fallbacks } 覆寫兩者（[] 停用全域回退）。僅覆寫 primary 的 Cron 任務仍會繼承預設回退，除非你設定 fallbacks: []。
params: 每個 Agent 的串流參數，合併到 agents.defaults.models 中選定的模型項目。用於 Agent 特定的覆寫，如 cacheRetention, temperature 或 maxTokens，而無需複製整個模型目錄。
runtime: 選填的每個 Agent 執行時描述。當 Agent 應預設使用 ACP harness Session 時，使用 type: "acp" 搭配 runtime.acp 預設值（agent, backend, mode, cwd）。
identity.avatar: 相對於 workspace 的路徑、http(s) URL 或 data: URI。
identity 衍生預設值：ackReaction 來自 emoji，mentionPatterns 來自 name/emoji。
subagents.allowAgents: sessions_spawn 允許的 Agent ID 允許清單（["*"] = 任何；預設：僅限同一個 Agent）。
沙箱繼承防護：如果請求者 Session 已進入沙箱，sessions_spawn 會拒絕那些將在非沙箱環境執行的目標。

多 Agent 路由

在一個 Gateway 中執行多個隔離的 Agent。參見 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 用於一般路由（缺少類型時預設為 route），acp 用於持久性 ACP 對話綁定。
match.channel (必填)
match.accountId (選填; * = 任何帳號; 省略 = 預設帳號)
match.peer (選填; { kind: direct|group|channel, id })
match.guildId / match.teamId (選填; 頻道特定)
acp (選填; 僅用於 type: "acp"): { mode, label, cwd, backend }

確定性匹配順序：

match.peer
match.guildId
match.teamId
match.accountId (精確匹配，無 peer/guild/team)
match.accountId: "*" (全頻道)
預設 Agent

在每一層級中，第一個匹配的 bindings 項目勝出。

對於 type: "acp" 項目，OpenClaw 透過精確的對話身分（match.channel +

訊息 (Messages)

{
  messages: {
    responsePrefix: "🦞", // or "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 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

回應前綴 (Response prefix)

你可以針對每個 Channel 或帳號進行覆蓋設定：channels.<channel>.responsePrefix 或 channels.<channel>.accounts.<id>.responsePrefix。

解析順序（越具體的優先級越高）：帳號 → Channel → 全域。設定為 "" 會停用並停止繼承。設定為 "auto" 則會自動帶入 [{identity.name}]。

範本變數：

變數	描述	範例
`{model}`	短模型名稱	`claude-opus-4-6`
`{modelFull}`	完整模型識別碼	`anthropic/claude-opus-4-6`
`{provider}`	Provider 名稱	`anthropic`
`{thinkingLevel}`	當前的思考層級	`high`, `low`, `off`
`{identity.name}`	Agent 身分名稱	(與 `"auto"` 相同)

變數不區分大小寫。{think} 是 {thinkingLevel} 的別名。

確認回應 (Ack reaction)

預設使用目前啟用的 Agent 的 identity.emoji，否則為 "👀"。設定為 "" 即可停用。
每個 Channel 的覆蓋設定：channels.<channel>.ackReaction 或 channels.<channel>.accounts.<id>.ackReaction。
解析順序：帳號 → Channel → messages.ackReaction → 身分預設值。
範圍 (Scope)：group-mentions (預設), group-all, direct, all。
removeAckAfterReply：在回覆後移除確認回應（僅限 Slack/Discord/Telegram/Google Chat）。

入站防抖 (Inbound debounce)

將來自同一發送者的連續純文字訊息合併為單次 Agent 輪次。媒體或附件會立即觸發。控制指令則會跳過防抖機制。

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 在每個 Session 中覆蓋此設定。
summaryModel 會覆蓋 agents.defaults.model.primary 來進行自動摘要。
modelOverrides 預設啟用；modelOverrides.allowProvider 預設為 false（需手動開啟）。
API key 會回退到 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,
  },
}

Voice ID 會回退到 ELEVENLABS_VOICE_ID 或 SAG_VOICE_ID。
apiKey 和 providers.*.apiKey 接受純文字字串或 SecretRef 物件。
ELEVENLABS_API_KEY 回退僅在未設定 Talk API key 時生效。
voiceAliases 讓 Talk 指令可以使用親切的名稱。
silenceTimeoutMs 控制在使用者沉默多久後發送逐字稿。若未設定，則使用平台預設的停頓時間（macOS 和 Android 為 700 ms，iOS 為 900 ms）。

工具 (Tools)

工具設定檔 (Tool profiles)

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`	無限制（與未設定相同）

工具群組 (Tool groups)

群組	工具
`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`	所有內建工具（不含 Provider 插件）

`tools.allow` / `tools.deny`

全域工具允許/拒絕策略（拒絕優先）。不區分大小寫，支援 * 萬用字元。即使 Docker 沙箱關閉也會套用。

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

`tools.byProvider`

針對特定的 Provider 或模型進一步限制工具。順序：基礎設定檔 → Provider 設定檔 → 允許/拒絕。

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

`tools.elevated`

控制提權（主機）的 exec 存取：

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

每個 Agent 的覆蓋設定 (agents.list[].tools.elevated) 只能進行更嚴格的限制。
/elevated on|off|ask|full 會儲存每個 Session 的狀態；行內指令僅適用於單則訊息。
提權後的 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 針對每個 Agent 進行覆蓋。

{
  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", // or BRAVE_API_KEY env
        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" }],
      },
    },
  },
}

媒體模型欄位說明

Provider 項目（type: "provider" 或省略）：

provider: API provider 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: 每個項目的覆蓋設定。
失敗時會自動回退到下一個項目。

Provider 認證遵循標準順序：auth-profiles.json → 環境變數 → models.providers.*.apiKey。

`tools.agentToAgent`

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

`tools.sessions`

控制哪些 Session 可以被 Session 工具（sessions_list, sessions_history, sessions_send）存取。

預設值：tree（目前 Session + 由其產生的 Session，例如 Subagent）。

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

備註：

self: 僅限目前的 Session key。
tree: 目前 Session + 由目前 Session 產生的 Session (Subagent)。
agent: 屬於目前 Agent ID 的任何 Session（如果你為每個發送者在同一個 Agent ID 下執行 Session，則可能包含其他使用者）。
all: 任何 Session。跨 Agent 目標仍需要 tools.agentToAgent。
沙箱限制：當目前 Session 處於沙箱中且 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 runtime 會拒絕附件。
檔案會被實體化到子工作區的 .openclaw/attachments/<uuid>/，並附帶一個 .manifest.json。
附件內容會自動從逐字稿持久化中遮蔽。
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: 產生的 Subagent 預設模型。若省略，Subagent 會繼承呼叫者的模型。
runTimeoutSeconds: 當工具呼叫省略 runTimeoutSeconds 時，sessions_spawn 的預設逾時時間（秒）。0 表示不逾時。
每個 Subagent 的工具策略：tools.subagents.tools.allow / tools.subagents.tools.deny。

自定義 Provider 與 Base URL

OpenClaw 使用 pi-coding-agent 模型目錄。你可以透過設定檔中的 models.providers 或 ~/.openclaw/agents/<agentId>/agent/models.json 來新增自定義 Provider。

{
  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) 覆蓋 Agent 設定根目錄。
匹配 Provider ID 的合併優先級：
- 非空的 Agent models.json 中的 baseUrl 值優先。
- 僅當該 Provider 在目前設定/認證設定檔中未受 SecretRef 管理時，非空的 Agent apiKey 值優先。
- 受 SecretRef 管理的 Provider apiKey 值會從來源標記（環境變數參考為 ENV_VAR_NAME，檔案/執行參考為 secretref-managed）重新整理，而不是持久化已解析的秘密。
- 受 SecretRef 管理的 Provider header 值會從來源標記（環境變數參考為 secretref-env:ENV_VAR_NAME，檔案/執行參考為 secretref-managed）重新整理。
- 空的或缺失的 Agent apiKey/baseUrl 會回退到設定檔中的 models.providers。
- 匹配模型的 contextWindow/maxTokens 會使用明確設定與隱含目錄值中的較大者。
- 當你希望設定檔完全重寫 models.json 時，請使用 models.mode: "replace"。
- 標記持久化以來源為準：標記是從活動的來源設定快照（解析前）寫入的，而不是從解析後的執行階段秘密值寫入。

Provider 欄位詳情

models.mode: Provider 目錄行為 (merge 或 replace)。
models.providers: 以 Provider ID 為鍵的自定義 Provider 映射。
models.providers.*.api: 請求適配器 (openai-completions, openai-responses, anthropic-messages, google-generative-ai 等)。
models.providers.*.apiKey: Provider 憑證（建議使用 SecretRef/環境變數替換）。
models.providers.*.auth: 認證策略 (api-key, token, oauth, aws-sdk)。
models.providers.*.injectNumCtxForOpenAICompat: 針對 Ollama + openai-completions，在請求中注入 options.num_ctx（預設：true）。
models.providers.*.authHeader: 必要時強制在 Authorization header 中傳輸憑證。
models.providers.*.baseUrl: 上游 API 基礎 URL。
models.providers.*.headers: 用於 Proxy/租戶路由的額外靜態 header。
models.providers.*.models: 明確的 Provider 模型目錄項目。
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: 用於目標探索的可選 Provider ID 過濾器。
models.bedrockDiscovery.refreshInterval: 探索重新整理的輪詢間隔。
models.bedrockDiscovery.defaultContextWindow: 已探索模型的後備 Context Window。
models.bedrockDiscovery.defaultMaxTokens: 已探索模型的後備最大輸出 Token。

Provider 範例

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/zai-glm-4.7 存取 Cerebras；使用 zai/glm-4.7 直接存取 Z.AI。

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)。使用 opencode/... 參考 Zen 目錄，或使用 opencode-go/... 參考 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
Coding 端點（預設）：https://api.z.ai/api/coding/paas/v4
若要使用通用端點，請定義一個帶有 Base URL 覆蓋的自定義 Provider。

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，內建 Provider。快捷方式：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,
          },
        ],
      },
    },
  },
}

Base 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.<skillKey>.enabled: false: 即使是內建或已安裝的技能，也可以直接停用。
entries.<skillKey>.apiKey: 方便為宣告主要環境變數的技能設定 API key（可以是純文字字串或 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 的 prompt 修改欄位，但會保留舊版的 modelOverride 與 providerOverride。
plugins.entries.<id>.config: 外掛定義的設定物件（由外掛 schema 驗證）。
plugins.slots.memory: 選擇啟用的記憶外掛 ID，或設為 "none" 來停用。
plugins.slots.contextEngine: 選擇啟用的上下文引擎外掛 ID；預設為 "legacy"，除非你安裝並選擇了其他引擎。
plugins.installs: 由 CLI 管理的安裝元數據，供 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 來設定明確的例外清單。
遠端設定檔（Remote profiles）僅限附加模式（無法執行啟動/停止/重設）。
自動偵測順序：預設瀏覽器（若為 Chromium 核心）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
控制服務：僅限 loopback（連接埠由 gateway.port 衍生，預設為 18791）。
extraArgs 會在啟動本地 Chromium 時附加額外的 flag（例如 --disable-gpu、視窗大小或除錯 flag）。
relayBindHost 決定 Chrome extension relay 的監聽位置。若只需本機存取請保持未設定；只有在 relay 需要跨越命名空間邊界（例如 WSL2）且主機網路已受信任時，才設定明確的非 loopback 綁定地址（如 0.0.0.0）。

使用者介面 (UI)

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

seamColor: 原生應用程式 UI 的強調色（例如 Talk Mode 的氣泡色調等）。
assistant: 覆寫控制 UI 的識別資訊。若未設定則會退回使用當前 Agent 的識別資訊。

Gateway 閘道器

{
  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 中使用模式值（auto, loopback, lan, tailnet, custom），不要使用主機別名（0.0.0.0, 127.0.0.1, localhost, ::, ::1）。
Docker 注意事項: 預設的 loopback 綁定會監聽容器內的 127.0.0.1。使用 Docker bridge 網路 (-p 18789:18789) 時，流量會到達 eth0，導致無法存取 Gateway。請使用 --network host，或將 bind 設為 "lan" (或 bind: "custom" 搭配 customBindHost: "0.0.0.0") 來監聽所有介面。
Auth: 預設為必要。非 loopback 綁定需要共享 token/password。初始化精靈預設會產生一個 token。
如果同時配置了 gateway.auth.token 和 gateway.auth.password（包括 SecretRefs），請明確將 gateway.auth.mode 設為 token 或 password。如果兩者都配置但未設定模式，啟動和服務安裝/修復流程將會失敗。
gateway.auth.mode: "none": 明確的無驗證模式。僅用於受信任的本地 loopback 設定；初始化提示中刻意不提供此選項。
gateway.auth.mode: "trusted-proxy": 將驗證委託給具備身份識別功能的反向代理，並信任來自 gateway.trustedProxies 的身份標頭（參見 Trusted Proxy Auth）。
gateway.auth.allowTailscale: 當為 true 時，Tailscale Serve 身份標頭可以滿足 Control UI/WebSocket 驗證（透過 tailscale whois 驗證）；HTTP API 端點仍需要 token/password 驗證。此無 token 流程假設 Gateway 主機是受信任的。當 tailscale.mode = "serve" 時，預設為 true。
gateway.auth.rateLimit: 選用的驗證失敗限制器。按客戶端 IP 和驗證範圍（shared-secret 和 device-token 分別追蹤）套用。被封鎖的嘗試會回傳 429 + Retry-After。
- gateway.auth.rateLimit.exemptLoopback 預設為 true；如果你想刻意限制 localhost 流量（用於測試設定或嚴格的代理部署），請設為 false。
瀏覽器來源的 WS 驗證嘗試一律會被限制，且停用 loopback 豁免（針對基於瀏覽器的 localhost 暴力破解進行深度防禦）。
tailscale.mode: serve (僅限 tailnet，loopback 綁定) 或 funnel (公開，需要驗證)。
controlUi.allowedOrigins: Gateway WebSocket 連接的明確瀏覽器來源允許清單。當預期有來自非 loopback 來源的瀏覽器客戶端時，此項為必填。
controlUi.dangerouslyAllowHostHeaderOriginFallback: 危險模式，為刻意依賴 Host-header 來源策略的部署啟用 Host-header 來源回退。
remote.transport: ssh (預設) 或 direct (ws/wss)。對於 direct，remote.url 必須是 ws:// 或 wss://。
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1: 客戶端緊急覆蓋開關，允許純文字 ws:// 連接到受信任的私有網路 IP；純文字的預設值仍僅限 loopback。
gateway.remote.token / .password 是遠端客戶端憑證欄位。它們本身不會配置 Gateway 驗證。
僅當 gateway.auth.* 未設定時，本地 Gateway 呼叫路徑才能使用 gateway.remote.* 作為回退。
如果 gateway.auth.token / gateway.auth.password 透過 SecretRef 明確配置但未解析，解析將失敗並關閉（不會有遠端回退遮掩）。
trustedProxies: 終止 TLS 的反向代理 IP。僅列出你控制的代理。
allowRealIpFallback: 當為 true 時，如果缺少 X-Forwarded-For，Gateway 會接受 X-Real-IP。預設為 false 以確保失敗關閉行為。
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）

多實例隔離

在單一主機上執行多個 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 鉤子

{
  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? }
- 僅當 hooks.allowRequestSessionKey=true（預設：false）時，才接受來自請求負載的 sessionKey。
POST /hooks/<name> → 透過 hooks.mappings 解析。

Mapping details

match.path 匹配 /hooks 後的子路徑（例如 /hooks/gmail → gmail）。
match.source 針對通用路徑匹配負載欄位。
像 {{messages[0].subject}} 這樣的模板會從負載中讀取。
transform 可以指向回傳 hook 動作的 JS/TS 模組。
- transform.module 必須是相對路徑，且留在 hooks.transformsDir 內（拒絕絕對路徑和路徑遍歷）。
agentId 路由到特定的 agent；未知的 ID 會回退到預設值。
allowedAgentIds: 限制明確路由（* 或省略 = 允許所有，[] = 拒絕所有）。
defaultSessionKey: 選用的固定 session key，用於沒有明確 sessionKey 的 hook agent 執行。
allowRequestSessionKey: 允許 /hooks/agent 呼叫者設定 sessionKey（預設：false）。
allowedSessionKeyPrefixes: 明確 sessionKey 值的選用前綴允許清單（請求 + 映射），例如 ["hook:"]。
deliver: true 將最終回覆發送到頻道；channel 預設為 last。
model 為此次 hook 執行覆蓋 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。

Canvas 主機

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

透過 Gateway 連接埠以 HTTP 提供 agent 可編輯的 HTML/CSS/JS 和 A2UI：
- http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
- http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
僅限本地：保持 gateway.bind: "loopback"（預設）。
非 loopback 綁定：canvas 路由需要 Gateway 驗證（token/password/trusted-proxy），與其他 Gateway HTTP 介面相同。
Node WebViews 通常不發送驗證標頭；在 node 配對並連接後，Gateway 會發布用於 canvas/A2UI 存取的 node 範圍功能 URL。
功能 URL 綁定到活動的 node WS 工作階段且很快就會過期。不使用基於 IP 的回退。
將 live-reload 客戶端注入到提供的 HTML 中。
當目錄為空時自動建立入門 index.html。
同時在 /__openclaw__/a2ui/ 提供 A2UI。
更改需要重啟 Gateway。
對於大型目錄或 EMFILE 錯誤，請停用 live reload。

Discovery 探索

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。

環境設定

`env` (行內環境變數)

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

行內環境變數只有在 process env 找不到該 key 時才會套用。
.env 檔案：會讀取 CWD .env + ~/.openclaw/.env（兩者都不會覆蓋已存在的變數）。
shellEnv：從你的 login shell profile 中匯入缺失的預期 key。
完整的優先順序請參考 Environment。

環境變數替換

你可以在任何配置字串中使用 ${VAR_NAME} 來引用環境變數：

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

只會比對大寫名稱：[A-Z_][A-Z0-9_]*。
如果變數缺失或為空，在載入配置時會報錯。
使用 $${VAR} 來跳脫，以取得字面上的 ${VAR}。
支援與 $include 搭配使用。

機密資訊

機密引用（Secret refs）是累加的：純文字數值依然可以正常運作。

`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 pointer（例如 "/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 提供者需要絕對的 command 路徑，並透過 stdin/stdout 使用協定負載（protocol payloads）。
預設情況下會拒絕符號連結（symlink）的指令路徑。設定 allowSymlinkCommand: true 可以允許符號連結，同時仍會驗證解析後的目標路徑。
如果配置了 trustedDirs，信任目錄檢查將套用於解析後的目標路徑。
exec 的子程序環境預設是極小化的；請透過 passEnv 明確傳遞需要的變數。
機密引用會在啟動時解析為記憶體中的快照，隨後的請求路徑僅讀取該快照。
啟動時會進行有效範圍過濾：在啟用的範圍內若有未解析的引用，會導致啟動或重新載入失敗，而未啟用的範圍則會跳過並顯示診斷資訊。

身份驗證儲存 (Auth storage)

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

每個 agent 的設定檔都儲存在 <agentDir>/auth-profiles.json。
auth-profiles.json 支援值等級的引用（api_key 使用 keyRef，token 使用 tokenRef）。
靜態運行時憑證來自記憶體中解析的快照；一旦發現舊版的靜態 auth.json 項目就會被清除。
舊版 OAuth 會從 ~/.openclaw/credentials/oauth.json 匯入。
參考 OAuth。
Secrets 運行行為與 audit/configure/apply 工具：Secrets Management。

日誌記錄 (Logging)

{
  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: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

cli.banner.taglineMode 用來控制橫幅標語的樣式：
- "random" (預設)：隨機輪播有趣或季節性的標語。
- "default"：固定的中性標語 (All your chats, one OpenClaw.)。
- "off"：不顯示標語文字（但橫幅標題與版本號仍會顯示）。
如果你想隱藏整個橫幅（而不只是標語），可以設定環境變數 OPENCLAW_HIDE_BANNER=1。

Wizard 引導

這些是由 CLI wizard（例如 onboard, configure, doctor）自動寫入的 Metadata：

{
  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 onboarding assistant 寫入的，它會幫你推導出一些預設值：

messages.ackReaction 來自 identity.emoji（預設會回退到 👀），而 mentionPatterns 則是由 identity.name 或 identity.emoji 產生的。
avatar 欄位支援：workspace 相對路徑、http(s) URL 或 data: URI。

Bridge（舊版，已移除）

目前的版本已經不再包含 TCP bridge 了。現在 Node.js 會直接透過 Gateway WebSocket 連接。bridge.* 這些 key 也不再屬於設定檔 schema 的一部分（在移除前驗證會失敗；你可以執行 openclaw doctor --fix 來自動刪除這些未知的 key）。

舊版 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: 決定在從 sessions.json 清除之前，要保留已完成的獨立 Cron 執行 Session 多久。這也會控制已刪除 Cron 逐字稿存檔的清理。預設為 24h；設定為 false 即可停用。
runLog.maxBytes: 每個執行日誌檔案 (cron/runs/<jobId>.jsonl) 在清理前的最大容量。預設為 2_000_000 bytes。
runLog.keepLines: 觸發執行日誌清理時，要保留的最新的行數。預設為 2000。
webhookToken: 用於 Cron Webhook POST 傳送 (delivery.mode = "webhook") 的 Bearer Token，如果省略則不會發送 Auth Header。
webhook: 已棄用的舊版備用 Webhook URL (http/https)，僅用於仍帶有 notify: true 的儲存任務。

參考 Cron Jobs。

Media 模型模板變數

在 tools.media.models[].args 中展開的模板佔位符：

變數	描述
`{{Body}}`	完整的傳入訊息主體
`{{RawBody}}`	原始主體（無歷史記錄/發送者包裝）
`{{BodyStripped}}`	移除群組提及後的主體
`{{From}}`	發送者識別碼
`{{To}}`	目的地識別碼
`{{MessageSid}}`	頻道訊息 ID
`{{SessionId}}`	目前 Session 的 UUID
`{{IsNewSession}}`	建立新 Session 時為 `"true"`
`{{MediaUrl}}`	傳入媒體的虛擬 URL
`{{MediaPath}}`	本地媒體路徑
`{{MediaType}}`	媒體類型 (image/audio/document/…)
`{{Transcript}}`	音訊逐字稿
`{{Prompt}}`	CLI 條目解析後的媒體 Prompt
`{{MaxChars}}`	CLI 條目解析後的最大輸出字元數
`{{ChatType}}`	`"direct"` 或 `"group"`
`{{GroupSubject}}`	群組主題（盡力提供）
`{{GroupMembers}}`	群組成員預覽（盡力提供）
`{{SenderName}}`	發送者顯示名稱（盡力提供）
`{{SenderE164}}`	發送者電話號碼（盡力提供）
`{{Provider}}`	Provider 提示 (WhatsApp, Telegram, Discord 等)

設定檔包含 (`$include`)

你可以將設定拆分為多個檔案：

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

合併行為：

單一檔案：替換包含該屬性的物件。
檔案陣列：依序進行 Deep-merge（後者會覆蓋前者）。
同級 Key：在 Include 之後合併（會覆蓋 Include 的值）。
巢狀 Include：支援最多 10 層深度。
路徑：相對於包含它的檔案進行解析，但必須留在頂層設定目錄內（即 openclaw.json 的 dirname）。只有在解析後仍位該邊界內時，才允許使用絕對路徑或 ../ 形式。
錯誤處理：針對遺失檔案、解析錯誤和循環 Include 提供清晰的訊息。

相關內容：Configuration · Configuration Examples · Doctor

{
  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，拿到可執行步驟。