設定參考

~/.openclaw/openclaw.json 中所有可用的欄位。任務導向的概覽請參閱 設定。

設定格式為 JSON5（支援註解和尾隨逗號）。所有欄位皆為可選——省略時 OpenClaw 使用安全的預設值。

頻道

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

DM 和群組存取

所有頻道都支援 DM 策略和群組策略：

注意： channels.defaults.groupPolicy 在提供者的 groupPolicy 未設定時作為預設值。 配對碼在 1 小時後過期。每個頻道最多 3 個待處理的 DM 配對請求。 如果某提供者的區塊完全不存在（channels.<provider> 缺失），執行期群組策略退回到 allowlist（fail-closed），並在啟動時發出警告。

頻道模型覆寫

用 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",
      },
    },
  },
}

頻道預設值和心跳

用 channels.defaults 設定跨提供者的共用群組策略和心跳行為：

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

• channels.defaults.groupPolicy：提供者層級 groupPolicy 未設定時的備援群組策略。
• channels.defaults.heartbeat.showOk：心跳輸出中包含健康的頻道狀態。
• channels.defaults.heartbeat.showAlerts：心跳輸出中包含降級/錯誤狀態。
• channels.defaults.heartbeat.useIndicator：渲染精簡指示器風格的心跳輸出。

WhatsApp

WhatsApp 透過 gateway 的 web 頻道（Baileys Web）運行。已連結的 session 存在時會自動啟動。

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // 藍勾（自聊模式時為 false）
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

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

Telegram

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

• 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" 的條目為論壇 topics 設定持久 ACP 綁定（在 match.peer.id 中使用正規的 chatId:topic:topicId）。欄位語義共享於 ACP Agents。
• Telegram 串流預覽使用 sendMessage + editMessageText（直接和群組聊天都有效）。
• 重試策略：參閱 重試策略。

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress（progress 在 Discord 上對應到 partial）
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in，用於 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>（guild 頻道）；純數字 ID 會被拒絕。
• Guild slug 為小寫，空格替換為 -；頻道鍵使用 slug 化的名稱（不含 #）。建議使用 guild ID。
• 機器人發出的訊息預設被忽略。allowBots: true 啟用；用 allowBots: "mentions" 只接受 mention 了機器人的機器人訊息（自己的訊息仍被過濾）。
• channels.discord.guilds.<id>.ignoreOtherMentions（和頻道覆寫）丟棄 mention 了其他使用者或角色但沒有 mention 機器人的訊息（排除 @everyone/@here）。
• maxLinesPerMessage（預設 17）即使未超過 2000 字元也會分割過長的訊息。
• channels.discord.threadBindings 控制 Discord thread 綁定路由：
  • enabled：Discord 覆寫 thread 綁定 session 功能（/focus、/unfocus、/agents、/session idle、/session max-age，以及綁定的發送/路由）
  • idleHours：Discord 覆寫的閒置自動解綁時間（小時，0 停用）
  • maxAgeHours：Discord 覆寫的硬性最大時間（小時，0 停用）
  • spawnSubagentSessions：sessions_spawn({ thread: true }) 自動建立/綁定 thread 的 opt-in 開關
• 頂層 bindings[] 中 type: "acp" 的條目為頻道和 thread 設定持久 ACP 綁定（在 match.peer.id 中使用頻道/thread 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 在重複解密失敗後還會嘗試透過離開/重新加入語音 session 來恢復語音接收。
• channels.discord.streaming 是正規的串流模式鍵。舊版 streamMode 和布林 streaming 值會自動遷移。
• channels.discord.autoPresence 將執行期可用性對應到機器人狀態（healthy => online、degraded => idle、exhausted => dnd），並允許可選的狀態文字覆寫。
• channels.discord.dangerouslyAllowNameMatching 重新啟用可變的名稱/標籤比對（break-glass 相容模式）。

Reaction 通知模式： 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,
    },
  },
}

• Service account JSON：內聯（serviceAccount）或檔案式（serviceAccountFile）。
• 也支援 Service account SecretRef（serviceAccountRef）。
• 環境變數備援：GOOGLE_CHAT_SERVICE_ACCOUNT 或 GOOGLE_CHAT_SERVICE_ACCOUNT_FILE。
• 發送目標使用 spaces/<spaceId> 或 users/<userId>。
• channels.googlechat.dangerouslyAllowNameMatching 重新啟用可變的 email principal 比對（break-glass 相容模式）。

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 模式）
      nativeStreaming: true, // streaming=partial 時使用 Slack 原生串流 API
      mediaMaxMb: 20,
    },
  },
}

• Socket 模式需要 botToken 和 appToken（預設帳號的環境變數備援為 SLACK_BOT_TOKEN + SLACK_APP_TOKEN）。
• HTTP 模式需要 botToken 加上 signingSecret（根層級或 per-account）。
• configWrites: false 封鎖 Slack 發起的設定寫入。
• 可選的 channels.slack.defaultAccount 在匹配到已設定帳號 id 時覆寫預設帳號選擇。
• channels.slack.streaming 是正規的串流模式鍵。舊版 streamMode 和布林 streaming 值會自動遷移。
• 發送目標使用 user:<id>（DM）或 channel:<id>。

Reaction 通知模式： off、own（預設）、all、allowlist（來自 reactionAllowlist）。

Thread session 隔離： thread.historyScope 預設為 per-thread 或跨頻道共享。thread.inheritParent 將父頻道的 transcript 複製到新 thread。

• typingReaction 在回覆進行中時對入站 Slack 訊息加上臨時 reaction，完成後移除。使用 Slack emoji shortcode 如 "hourglass_flowing_sand"。

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",
        // 反向代理/公開部署時可選的明確 URL
        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 包含回呼 host/domain。使用 host/domain 值，不是完整 URL。
• channels.mattermost.configWrites：允許或拒絕 Mattermost 發起的設定寫入。
• channels.mattermost.requireMention：頻道中回覆前需要 @mention。
• 可選的 channels.mattermost.defaultAccount 在匹配到已設定帳號 id 時覆寫預設帳號選擇。

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // 可選的帳號綁定
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

Reaction 通知模式： 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、群組控制和進階操作：
      // 參閱 /channels/bluebubbles
    },
  },
}

• 此處涵蓋的核心路徑：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", "[email protected]", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• 可選的 channels.imessage.defaultAccount 在匹配到已設定帳號 id 時覆寫預設帳號選擇。

• 需要 Messages DB 的完整磁碟存取權限。

• 發送目標建議用 chat_id:<id>。用 imsg chats --limit 20 列出聊天。

• cliPath 可指向 SSH wrapper；設 remoteHost（host 或 user@host）用於 SCP 附件擷取。

• attachmentRoots 和 remoteAttachmentRoots 限制入站附件路徑（預設：/Users/*/Library/Messages/Attachments）。

• SCP 使用嚴格主機金鑰檢查，確保 relay 主機金鑰已在 ~/.ssh/known_hosts 中。

• channels.imessage.configWrites：允許或拒絕 iMessage 發起的設定寫入。

#!/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 策略：
      // 參閱 /channels/msteams
    },
  },
}

• 此處涵蓋的核心路徑：channels.msteams、channels.msteams.configWrites。
• 完整的 Teams 設定（憑證、webhook、DM/群組策略、per-team/per-channel 覆寫）請參閱 Microsoft Teams。

IRC

IRC 以擴充方式提供，設定在 channels.irc 下。

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

• 此處涵蓋的核心路徑：channels.irc、channels.irc.dmPolicy、channels.irc.configWrites、channels.irc.nickserv.*。
• 可選的 channels.irc.defaultAccount 在匹配到已設定帳號 id 時覆寫預設帳號選擇。
• 完整的 IRC 頻道設定（host/port/TLS/channels/allowlists/mention gating）請參閱 IRC。

多帳號（所有頻道）

每個頻道可運行多個帳號（各有自己的 accountId）：

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

• 省略 accountId 時使用 default（CLI + 路由）。
• 環境變數 token 只套用到預設帳號。
• 基本頻道設定適用於所有帳號，除非 per-account 覆寫。
• 用 bindings[].match.accountId 將各帳號路由到不同 agent。
• 如果你透過 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。

群組聊天 mention 門控

群組訊息預設需要 mention（metadata mention 或 regex 模式）。適用於 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群組聊天。

Mention 類型：

• Metadata mentions：平台原生 @mention。在 WhatsApp 自聊模式中忽略。
• 文字模式：agents.list[].groupChat.mentionPatterns 中的 regex 模式。永遠檢查。
• Mention 門控只在偵測可行時才強制執行（有原生 mention 或至少一個模式）。

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

messages.groupChat.historyLimit 設定全域預設值。頻道可用 channels.<channel>.historyLimit（或 per-account）覆寫。設 0 停用。

DM 歷史限制

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

解析順序：per-DM 覆寫 → 提供者預設 → 無限制（全部保留）。

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

自聊模式

在 allowFrom 中加入自己的號碼以啟用自聊模式（忽略原生 @mention，只回應文字模式）：

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

指令（聊天指令處理）

{
  commands: {
    native: "auto", // 支援時註冊原生指令
    text: true, // 解析聊天訊息中的 /commands
    bash: false, // 允許 !（別名：/bash）
    bashForegroundMs: 2000,
    config: false, // 允許 /config
    debug: false, // 允許 /debug
    restart: false, // 允許 /restart + gateway 重啟工具
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

Agent 預設值

agents.defaults.workspace

預設：~/.openclaw/workspace。

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

agents.defaults.repoRoot

可選的儲存庫根路徑，顯示在系統 prompt 的 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"：不在系統 prompt 中注入警告文字。
• "once"：每個唯一的截斷簽章注入一次警告（建議）。
• "always"：存在截斷時每次執行都注入警告。

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

agents.defaults.imageMaxDimensionPx

提供者呼叫前 transcript/工具圖片區塊最長邊的最大像素數。 預設：1200。

較低值通常能減少截圖密集場景的 vision token 用量和請求 payload 大小。 較高值保留更多視覺細節。

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

agents.defaults.userTimezone

系統 prompt 上下文的時區（不影響訊息時間戳）。退回到主機時區。

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

agents.defaults.timeFormat

系統 prompt 中的時間格式。預設：auto（OS 偏好）。

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

agents.defaults.model

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

• model：接受字串（"provider/model"）或物件（{ primary, fallbacks }）。
  • 字串形式只設定主要模型。
  • 物件形式設定主要模型加上有序的備援模型。
• imageModel：接受字串或物件。
  • 由 image 工具路徑作為 vision 模型設定。
  • 當選中/預設的模型不接受圖片輸入時，也作為備援路由。
• pdfModel：接受字串或物件。
  • 由 pdf 工具用於模型路由。
  • 省略時，PDF 工具退回到 imageModel，再退回到盡力而為的提供者預設值。
• pdfMaxBytesMb：pdf 工具呼叫時未傳入 maxBytesMb 時的預設 PDF 大小限制。
• pdfMaxPages：pdf 工具擷取備援模式考慮的預設最大頁數。
• model.primary：格式 provider/model（例如 anthropic/claude-opus-4-6）。省略 provider 時，OpenClaw 假設 anthropic（已棄用）。
• models：已設定的模型目錄和 /model 的白名單。每筆可包含 alias（快捷方式）和 params（提供者特定，例如 temperature、maxTokens、cacheRetention、context1m）。
• params 合併優先順序（設定）：agents.defaults.models["provider/model"].params 是基底，agents.list[].params（匹配的 agent id）按鍵覆寫。
• 修改這些欄位的設定寫入器（例如 /models set、/models set-image 和 fallback 增刪指令）會儲存正規物件形式，並在可能時保留既有的 fallback 清單。
• maxConcurrent：跨 sessions 的最大並行 agent 回合數（每個 session 仍序列化）。預設：1。

內建別名快捷方式（僅在模型存在於 agents.defaults.models 時適用）：

你設定的別名永遠優先於預設值。

Z.AI GLM-4.x 模型除非你設 --thinking off 或自行定義 agents.defaults.models["zai/<model>"].params.thinking，否則會自動啟用 thinking 模式。 Z.AI 模型預設啟用 tool_stream 來串流 tool call。設 agents.defaults.models["zai/<model>"].params.tool_stream 為 false 可停用。 Anthropic Claude 4.6 模型在沒有明確 thinking 層級時預設使用 adaptive thinking。

由於此參考文件極長，其餘章節（agents.defaults.cliBackends、agents.defaults.heartbeat、agents.defaults.compaction、agents.defaults.contextPruning、Block streaming、Typing indicators、agents.defaults.sandbox、agents.list、Multi-agent routing、Session、Messages、Talk、Tools、Custom providers、Skills、Plugins、Browser、UI、Gateway、Hooks、Canvas host、Discovery、Environment、Secrets、Auth storage、Logging、CLI、Wizard、Identity、Bridge、Cron、Media model template variables、Config includes）的結構、程式碼區塊和表格與英文版完全一致。完整的中文翻譯版本請參閱各專題頁面的獨立文件。

相關：設定 · 設定範例 · Doctor