Configuration Reference

配置参考

~/.openclaw/openclaw.json 中可用的所有字段。面向任务的概览请参见配置。

配置格式为 JSON5（允许注释和尾随逗号）。所有字段都是可选的——省略时 OpenClaw 使用安全的默认值。

频道

每个频道在其配置节存在时自动启动（除非 enabled: false）。

DM 和群组访问

所有频道支持 DM 策略和群组策略：

DM 策略	行为
`pairing`（默认）	未知发送者获得一次性配对代码；所有者必须批准
`allowlist`	仅 `allowFrom`（或已配对的允许存储）中的发送者
`open`	允许所有入站 DM（需要 `allowFrom: ["*"]`）
`disabled`	忽略所有入站 DM

群组策略	行为
`allowlist`（默认）	仅匹配已配置白名单的群组
`open`	绕过群组白名单（提及门控仍然适用）
`disabled`	阻止所有群组/房间消息

`channels.defaults.groupPolicy` 在提供者的 `groupPolicy` 未设置时设置默认值。配对代码在 1 小时后过期。待处理的 DM 配对请求每个频道上限为 **3 个**。如果提供者块完全缺失（`channels.` 不存在），运行时群组策略回退到 `allowlist`（安全关闭），并发出启动警告。

频道模型覆盖

使用 channels.modelByChannel 将特定频道 ID 固定到某个模型。值接受 provider/model 或已配置的模型别名。频道映射在会话没有模型覆盖（例如通过 /model 设置）时适用。

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

频道默认值和心跳

使用 channels.defaults 设置跨提供者共享的群组策略和心跳行为：

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

channels.defaults.groupPolicy：提供者级 groupPolicy 未设置时的回退群组策略。
channels.defaults.heartbeat.showOk：在心跳输出中包含健康的频道状态。
channels.defaults.heartbeat.showAlerts：在心跳输出中包含降级/错误状态。
channels.defaults.heartbeat.useIndicator：渲染紧凑指示器样式的心跳输出。

WhatsApp 通过 Gateway 的 Web 频道（Baileys Web）运行。当存在已链接的会话时自动启动。

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

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

出站命令默认使用账户 default（如果存在）；否则使用第一个已配置的账户 id（排序后）。
可选的 channels.whatsapp.defaultAccount 在匹配已配置的账户 id 时覆盖该回退默认账户选择。
旧版单账户 Baileys auth 目录由 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 代理中共享。
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 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 为小写，空格替换为 -；频道键使用 slug 化名称（无 #）。建议使用服务器 ID。
默认忽略 bot 发送的消息。allowBots: true 启用它们；使用 allowBots: "mentions" 仅接受提及 bot 的 bot 消息（自身消息仍被过滤）。
channels.discord.guilds.<id>.ignoreOtherMentions（和频道覆盖）丢弃提及其他用户或角色但未提及 bot 的消息（不包括 @everyone/@here）。
maxLinesPerMessage（默认 17）即使在 2000 字符以下也会分割高消息。
channels.discord.threadBindings 控制 Discord 线程绑定路由：
- enabled：线程绑定会话功能的 Discord 覆盖（/focus、/unfocus、/agents、/session idle、/session max-age，以及绑定投递/路由）
- idleHours：不活跃自动取消聚焦的 Discord 覆盖，单位为小时（0 禁用）
- maxAgeHours：硬性最大年龄的 Discord 覆盖，单位为小时（0 禁用）
- spawnSubagentSessions：sessions_spawn({ thread: true }) 自动线程创建/绑定的选择性启用开关
顶层 bindings[] 条目中 type: "acp" 为频道和线程配置持久 ACP 绑定（在 match.peer.id 中使用频道/线程 id）。字段语义在 ACP 代理中共享。
channels.discord.ui.components.accentColor 设置 Discord 组件 v2 容器的强调色。
channels.discord.voice 启用 Discord 语音频道对话和可选的自动加入 + TTS 覆盖。
channels.discord.voice.daveEncryption 和 channels.discord.voice.decryptionFailureTolerance 传递给 @discordjs/voice DAVE 选项（默认分别为 true 和 24）。
OpenClaw 还会在重复解密失败后通过离开/重新加入语音会话来尝试语音接收恢复。
channels.discord.streaming 是规范的流模式键。旧版 streamMode 和布尔值 streaming 会自动迁移。
channels.discord.autoPresence 将运行时可用性映射到 bot 状态（healthy => online、degraded => idle、exhausted => dnd），并允许可选的状态文本覆盖。
channels.discord.dangerouslyAllowNameMatching 重新启用可变名称/标签匹配（紧急兼容模式）。

反应通知模式： off（无）、own（bot 的消息，默认）、all（所有消息）、allowlist（来自 guilds.<id>.users 的所有消息）。

Google Chat

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

服务账户 JSON：内联（serviceAccount）或基于文件（serviceAccountFile）。
也支持服务账户 SecretRef（serviceAccountRef）。
环境变量回退：GOOGLE_CHAT_SERVICE_ACCOUNT 或 GOOGLE_CHAT_SERVICE_ACCOUNT_FILE。
使用 spaces/<spaceId> 或 users/<userId> 作为投递目标。
channels.googlechat.dangerouslyAllowNameMatching 重新启用可变的电子邮件主体匹配（紧急兼容模式）。

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: "partial", // off | partial | block | progress (preview mode)
      nativeStreaming: true, // use Slack native streaming API when streaming=partial
      mediaMaxMb: 20,
    },
  },
}

Socket 模式需要 botToken 和 appToken（默认账户环境变量回退为 SLACK_BOT_TOKEN + SLACK_APP_TOKEN）。
HTTP 模式需要 botToken 加 signingSecret（在根级或逐账户级）。
configWrites: false 阻止 Slack 发起的配置写入。
可选的 channels.slack.defaultAccount 在匹配已配置的账户 id 时覆盖默认账户选择。
channels.slack.streaming 是规范的流模式键。旧版 streamMode 和布尔值 streaming 会自动迁移。
使用 user:<id>（DM）或 channel:<id> 作为投递目标。

反应通知模式： off、own（默认）、all、allowlist（来自 reactionAllowlist）。

线程会话隔离： thread.historyScope 为逐线程（默认）或跨频道共享。thread.inheritParent 将父频道转录复制到新线程。

typingReaction 在回复运行时向入站 Slack 消息添加临时反应，完成后移除。使用 Slack 表情短代码如 "hourglass_flowing_sand"。

操作组	默认	说明
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
    },
  },
}

此处涵盖的核心键路径：channels.bluebubbles、channels.bluebubbles.dmPolicy。
可选的 channels.bluebubbles.defaultAccount 在匹配已配置的账户 id 时覆盖默认账户选择。
完整的 BlueBubbles 频道配置文档在 BlueBubbles 中。

iMessage

OpenClaw 生成 imsg rpc（通过 stdio 的 JSON-RPC）。无需守护进程或端口。

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

可选的 channels.imessage.defaultAccount 在匹配已配置的账户 id 时覆盖默认账户选择。
需要对 Messages 数据库的完全磁盘访问权限。
建议使用 chat_id:<id> 目标。使用 imsg chats --limit 20 列出聊天。
cliPath 可以指向 SSH 包装器；设置 remoteHost（host 或 user@host）用于 SCP 附件获取。
attachmentRoots 和 remoteAttachmentRoots 限制入站附件路径（默认：/Users/*/Library/Messages/Attachments）。
SCP 使用严格的主机密钥检查，请确保中继主机密钥已存在于 ~/.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 policies:
      // see /channels/msteams
    },
  },
}

此处涵盖的核心键路径：channels.msteams、channels.msteams.configWrites。
完整的 Teams 配置（凭据、webhook、DM/群组策略、每团队/每频道覆盖）文档在 Microsoft Teams 中。

IRC

IRC 基于扩展，配置在 channels.irc 下。

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}

此处涵盖的核心键路径：channels.irc、channels.irc.dmPolicy、channels.irc.configWrites、channels.irc.nickserv.*。
可选的 channels.irc.defaultAccount 在匹配已配置的账户 id 时覆盖默认账户选择。
完整的 IRC 频道配置（主机/端口/TLS/频道/白名单/提及门控）文档在 IRC 中。

多账户（所有频道）

每个频道运行多个账户（每个有自己的 accountId）：

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

当省略 accountId 时使用 default（CLI + 路由）。
环境变量 token 仅适用于默认账户。
基础频道设置适用于所有账户，除非逐账户覆盖。
使用 bindings[].match.accountId 将每个账户路由到不同的代理。
如果你通过 openclaw channels add（或频道引导）添加非默认账户，而仍在单账户顶层频道配置上，OpenClaw 会首先将账户范围的顶层单账户值移入 channels.<channel>.accounts.default，以确保原始账户继续工作。
现有的仅频道绑定（无 accountId）继续匹配默认账户；账户范围的绑定仍然是可选的。
openclaw doctor --fix 也通过在命名账户存在但 default 缺失时将账户范围的顶层单账户值移入 accounts.default 来修复混合结构。

其他扩展频道

许多扩展频道配置为 channels.<id>，文档在其专用频道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。参见完整频道索引：频道。

群聊提及门控

群消息默认需要提及（元数据提及或正则模式）。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。

提及类型：

元数据提及：原生平台 @-mention。在 WhatsApp 自聊模式下被忽略。
文本模式：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 覆盖 → 提供者默认 → 无限制（全部保留）。

支持：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", // 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 bot 菜单条目。
bash: true 启用 ! <cmd> 用于主机 shell。需要 tools.elevated.enabled 且发送者在 tools.elevated.allowFrom.<channel> 中。
config: true 启用 /config（读写 openclaw.json）。对于 Gateway chat.send 客户端，持久 /config set|unset 写入还需要 operator.admin；只读 /config show 对普通写入范围的操作者客户端保持可用。
channels.<provider>.configWrites 按频道门控配置变更（默认：true）。
对于多账户频道，channels.<provider>.accounts.<id>.configWrites 也门控针对该账户的写入（例如 /allowlist --config --account <id> 或 /config set channels.<provider>.accounts.<id>...）。
allowFrom 是按提供者的。设置后，它是唯一的授权来源（频道白名单/配对和 useAccessGroups 被忽略）。
useAccessGroups: false 允许命令在 allowFrom 未设置时绕过访问组策略。

代理默认值

`agents.defaults.workspace`

默认：~/.openclaw/workspace。

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

`agents.defaults.repoRoot`

可选的仓库根目录，显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 从工作区向上遍历自动检测。

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

`agents.defaults.skipBootstrap`

禁用自动创建工作区引导文件（AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md）。

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

`agents.defaults.bootstrapMaxChars`

截断前每个工作区引导文件的最大字符数。默认：20000。

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

`agents.defaults.bootstrapTotalMaxChars`

所有工作区引导文件注入的最大总字符数。默认：150000。

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

`agents.defaults.bootstrapPromptTruncationWarning`

控制引导上下文被截断时代理可见的警告文本。默认："once"。

"off"：不向系统提示注入警告文本。
"once"：每个唯一截断签名注入一次警告（推荐）。
"always"：存在截断时每次运行都注入警告。

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

`agents.defaults.imageMaxDimensionPx`

在提供者调用之前，转录/工具图片块中最长边的最大像素大小。默认：1200。

较低的值通常减少截图密集运行中的视觉 token 使用和请求载荷大小。较高的值保留更多视觉细节。

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

`agents.defaults.userTimezone`

用于系统提示上下文的时区（非消息时间戳）。回退到主机时区。

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

`agents.defaults.timeFormat`

系统提示中的时间格式。默认：auto（操作系统偏好）。

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

`agents.defaults.model`

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

model：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
- 字符串形式仅设置主模型。
- 对象形式设置主模型加有序的故障转移模型。
imageModel：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
- 由 image 工具路径用作其视觉模型配置。
- 当选定/默认模型无法接受图片输入时，也用作回退路由。
pdfModel：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
- 由 pdf 工具用于模型路由。
- 如果省略，PDF 工具回退到 imageModel，然后是尽力而为的提供者默认值。
pdfMaxBytesMb：pdf 工具在调用时未传递 maxBytesMb 时的默认 PDF 大小限制。
pdfMaxPages：pdf 工具中提取回退模式考虑的默认最大页数。
model.primary：格式 provider/model（例如 anthropic/claude-opus-4-6）。如果省略提供者，OpenClaw 假设 anthropic（已弃用）。
models：已配置的模型目录和 /model 的白名单。每个条目可包含 alias（快捷方式）和 params（提供者特定，例如 temperature、maxTokens、cacheRetention、context1m）。
params 合并优先级（配置）：agents.defaults.models["provider/model"].params 是基础，然后 agents.list[].params（匹配代理 id）按键覆盖。
变更这些字段的配置写入器（例如 /models set、/models set-image 和回退添加/删除命令）保存规范对象形式，并在可能时保留现有回退列表。
maxConcurrent：跨会话的最大并行代理运行数（每个会话仍然串行化）。默认：1。

内置别名快捷方式（仅在模型在 agents.defaults.models 中时适用）：

别名	模型
`opus`	`anthropic/claude-opus-4-6`
`sonnet`	`anthropic/claude-sonnet-4-6`
`gpt`	`openai/gpt-5.4`
`gpt-mini`	`openai/gpt-5-mini`
`gemini`	`google/gemini-3.1-pro-preview`
`gemini-flash`	`google/gemini-3-flash-preview`
`gemini-flash-lite`	`google/gemini-3.1-flash-lite-preview`

你配置的别名始终优先于默认值。

Z.AI GLM-4.x 模型自动启用思考模式，除非你设置 --thinking off 或自己定义 agents.defaults.models["zai/<model>"].params.thinking。 Z.AI 模型默认启用 tool_stream 用于工具调用流式传输。设置 agents.defaults.models["zai/<model>"].params.tool_stream 为 false 以禁用。 Anthropic Claude 4.6 模型在未设置显式思考级别时默认为 adaptive 思考。

`agents.defaults.cliBackends`

可选的 CLI 后端，用于纯文本回退运行（无工具调用）。作为 API 提供者失败时的备份很有用。

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

CLI 后端以文本为先；工具始终禁用。
设置 sessionArg 时支持会话。
设置 imageArg 接受文件路径时支持图片传递。

`agents.defaults.heartbeat`

周期性心跳运行。

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.2-mini",
        includeReasoning: false,
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
      },
    },
  },
}

every：持续时间字符串（ms/s/m/h）。默认：30m。
suppressToolErrorWarnings：为 true 时，抑制心跳运行期间的工具错误警告载荷。
directPolicy：直接/DM 投递策略。allow（默认）允许直接目标投递。block 抑制直接目标投递并发出 reason=dm-blocked。
lightContext：为 true 时，心跳运行使用轻量引导上下文，仅从工作区引导文件中保留 HEARTBEAT.md。
逐代理：设置 agents.list[].heartbeat。当任何代理定义了 heartbeat，仅那些代理运行心跳。
心跳运行完整代理回合——更短的间隔消耗更多 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（长历史的分块摘要）。参见压缩。
identifierPolicy：strict（默认）、off 或 custom。strict 在压缩摘要期间预置内置的不透明标识符保留指导。
identifierInstructions：可选的自定义标识符保留文本，在 identifierPolicy=custom 时使用。
postCompactionSections：压缩后重新注入的可选 AGENTS.md H2/H3 节名。默认为 ["Session Startup", "Red Lines"]；设置 [] 禁用重新注入。未设置或显式设置为该默认对时，旧版 Every Session/Safety 标题也作为遗留回退被接受。
model：可选的仅用于压缩摘要的 provider/model-id 覆盖。当主会话应保持一个模型但压缩摘要应在另一个上运行时使用；未设置时，压缩使用会话的主模型。
memoryFlush：自动压缩前的静默代理回合，用于存储持久记忆。工作区为只读时跳过。

`agents.defaults.contextPruning`

在发送到 LLM 之前从内存上下文中修剪旧工具结果。不修改磁盘上的会话历史。

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

mode: "cache-ttl" 启用修剪通道。
ttl 控制修剪在上次缓存触碰后多久可以再次运行。
修剪首先软修剪过大的工具结果，然后在需要时硬清除较旧的工具结果。

软修剪保留开头 + 结尾，在中间插入 ...。

硬清除将整个工具结果替换为占位符。

说明：

图片块永远不会被修剪/清除。
比率基于字符（近似），而非精确的 token 计数。
如果助手消息少于 keepLastAssistants，修剪被跳过。

参见会话修剪了解行为详情。

块流式传输

{
  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 (use minMs/maxMs)
    },
  },
}

非 Telegram 频道需要显式 *.blockStreaming: true 来启用块回复。
频道覆盖：channels.<channel>.blockStreamingCoalesce（和逐账户变体）。Signal/Slack/Discord/Google Chat 默认 minChars: 1500。
humanDelay：块回复之间的随机暂停。natural = 800–2500ms。逐代理覆盖：agents.list[].humanDelay。

参见流式传输了解行为和分块详情。

输入指示器

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

默认：直接聊天/提及为 instant，未提及的群聊为 message。
逐会话覆盖：session.typingMode、session.typingIntervalSeconds。

参见输入指示器。

`agents.defaults.sandbox`

嵌入式代理的可选 Docker 沙箱化。完整指南参见沙箱化。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

工作区访问：

none：按作用域的沙箱工作区位于 ~/.openclaw/sandboxes 下
ro：沙箱工作区在 /workspace，代理工作区以只读方式挂载在 /agent
rw：代理工作区以读写方式挂载在 /workspace

作用域：

session：每会话的容器 + 工作区
agent：每代理一个容器 + 工作区（默认）
shared：共享容器和工作区（无跨会话隔离）

setupCommand 在容器创建后运行一次（通过 sh -lc）。需要网络出口、可写根目录、root 用户。

容器默认为 network: "none"——如果代理需要出站访问，设置为 "bridge"（或自定义桥接网络）。 "host" 被阻止。"container:<id>" 默认被阻止，除非你显式设置 sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true（紧急开关）。

入站附件被暂存到活跃工作区的 media/inbound/* 中。

docker.binds 挂载额外的主机目录；全局和逐代理的 binds 会被合并。

沙箱化浏览器（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=<derived from 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 默认启用，可通过 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 在需要 WebGL/3D 使用时禁用。
- 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`（逐代理覆盖）

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

id：稳定的代理 id（必需）。
default：当多个设置时，第一个生效（记录警告）。如果没有设置，第一个列表条目为默认。
model：字符串形式仅覆盖 primary；对象形式 { primary, fallbacks } 同时覆盖两者（[] 禁用全局回退）。仅覆盖 primary 的 Cron 作业仍继承默认回退，除非你设置 fallbacks: []。
params：逐代理流参数，合并到 agents.defaults.models 中选定的模型条目上。用于代理特定覆盖（如 cacheRetention、temperature 或 maxTokens），而无需复制整个模型目录。
runtime：可选的逐代理运行时描述符。当代理应默认使用 ACP harness 会话时，使用 type: "acp" 配合 runtime.acp 默认值（agent、backend、mode、cwd）。
identity.avatar：工作区相对路径、http(s) URL 或 data: URI。
identity 派生默认值：ackReaction 来自 emoji，mentionPatterns 来自 name/emoji。
subagents.allowAgents：sessions_spawn 的代理 id 白名单（["*"] = 任意；默认：仅同一代理）。
沙箱继承保护：如果请求者会话是沙箱化的，sessions_spawn 拒绝会在非沙箱化环境中运行的目标。

多代理路由

在一个 Gateway 中运行多个隔离代理。参见多代理。

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

绑定匹配字段

type（可选）：route 用于正常路由（缺少 type 默认为 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: "*"（频道范围）
默认代理

在每个层级内，第一个匹配的 bindings 条目生效。

对于 type: "acp" 条目，OpenClaw 通过精确对话身份（match.channel + 账户 + match.peer.id）解析，不使用上述路由绑定层级顺序。

逐代理访问配置

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

dmScope：DM 如何分组。
- main：所有 DM 共享主会话。
- per-peer：按跨频道的发送者 id 隔离。
- per-channel-peer：按频道 + 发送者隔离（推荐用于多用户收件箱）。
- per-account-channel-peer：按账户 + 频道 + 发送者隔离（推荐用于多账户）。
identityLinks：将规范 id 映射到提供者前缀的对等体，用于跨频道会话共享。
reset：主重置策略。daily 在本地时间 atHour 重置；idle 在 idleMinutes 后重置。两者都配置时，先过期的生效。
resetByType：按类型覆盖（direct、group、thread）。旧版 dm 作为 direct 的别名被接受。
parentForkMaxTokens：创建分叉线程会话时允许的最大父会话 totalTokens（默认 100000）。
- 如果父 totalTokens 超过此值，OpenClaw 启动一个全新的线程会话而非继承父转录历史。
- 设置 0 禁用此保护并始终允许父分叉。
mainKey：旧版字段。运行时现在始终为主直聊桶使用 "main"。
sendPolicy：按 channel、chatType（direct|group|channel，有旧版 dm 别名）、keyPrefix 或 rawKeyPrefix 匹配。第一个 deny 生效。
maintenance：会话存储清理 + 保留控制。
- mode：warn 仅发出警告；enforce 应用清理。
- pruneAfter：过期条目的年龄截止（默认 30d）。
- maxEntries：sessions.json 中的最大条目数（默认 500）。
- rotateBytes：sessions.json 超过此大小时轮换（默认 10mb）。
- resetArchiveRetention：*.reset.<timestamp> 转录归档的保留时间。默认为 pruneAfter；设置 false 禁用。
- maxDiskBytes：可选的会话目录磁盘预算。在 warn 模式下记录警告；在 enforce 模式下首先删除最旧的归档/会话。
- highWaterBytes：预算清理后的可选目标。默认为 maxDiskBytes 的 80%。
threadBindings：线程绑定会话功能的全局默认值。
- enabled：主默认开关（提供者可覆盖；Discord 使用 channels.discord.threadBindings.enabled）
- idleHours：不活跃自动取消聚焦的默认小时数（0 禁用；提供者可覆盖）
- maxAgeHours：硬性最大年龄的默认小时数（0 禁用；提供者可覆盖）

消息

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

响应前缀

逐频道/账户覆盖：channels.<channel>.responsePrefix、channels.<channel>.accounts.<id>.responsePrefix。

解析（最具体的生效）：账户 → 频道 → 全局。"" 禁用并停止级联。"auto" 派生 [{identity.name}]。

模板变量：

变量	描述	示例
`{model}`	简短模型名称	`claude-opus-4-6`
`{modelFull}`	完整模型标识符	`anthropic/claude-opus-4-6`
`{provider}`	提供者名称	`anthropic`
`{thinkingLevel}`	当前思考级别	`high`、`low`、`off`
`{identity.name}`	代理身份名称	（与 `"auto"` 相同）

变量不区分大小写。{think} 是 {thinkingLevel} 的别名。

确认反应

默认为活跃代理的 identity.emoji，否则为 "👀"。设置 "" 禁用。
逐频道覆盖：channels.<channel>.ackReaction、channels.<channel>.accounts.<id>.ackReaction。
解析顺序：账户 → 频道 → messages.ackReaction → 身份回退。
范围：group-mentions（默认）、group-all、direct、all。
removeAckAfterReply：回复后移除确认（仅 Slack/Discord/Telegram/Google Chat）。

入站去抖

将同一发送者的快速纯文本消息批量合并为单个代理回合。媒体/附件立即刷新。控制命令绕过去抖。

TTS（文本转语音）

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

auto 控制自动 TTS。/tts off|always|inbound|tagged 按会话覆盖。
summaryModel 覆盖自动摘要的 agents.defaults.model.primary。
modelOverrides 默认启用；modelOverrides.allowProvider 默认为 false（选择性启用）。
API 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 控制 Talk 模式在用户沉默后等待多长时间才发送转录。未设置时保持平台默认暂停窗口（macOS 和 Android 为 700 ms，iOS 为 900 ms）。

工具

工具配置文件

tools.profile 在 tools.allow/tools.deny 之前设置基础白名单：

本地引导在新本地配置中未设置时默认为 tools.profile: "coding"（现有的显式配置文件被保留）。

配置文件	包含
`minimal`	仅 `session_status`
`coding`	`group:fs`、`group:runtime`、`group:sessions`、`group:memory`、`image`
`messaging`	`group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status`
`full`	无限制（与未设置相同）

工具组

组	工具
`group:runtime`	`exec`、`process`（`bash` 作为 `exec` 的别名被接受）
`group:fs`	`read`、`write`、`edit`、`apply_patch`
`group:sessions`	`sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`session_status`
`group:memory`	`memory_search`、`memory_get`
`group:web`	`web_search`、`web_fetch`
`group:ui`	`browser`、`canvas`
`group:automation`	`cron`、`gateway`
`group:messaging`	`message`
`group:nodes`	`nodes`
`group:openclaw`	所有内置工具（不包括提供者插件）

`tools.allow` / `tools.deny`

全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 * 通配符。即使 Docker 沙箱关闭也会应用。

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

`tools.byProvider`

为特定提供者或模型进一步限制工具。顺序：基础配置文件 → 提供者配置文件 → allow/deny。

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

`tools.elevated`

控制提升的（主机）exec 访问：

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

逐代理覆盖（agents.list[].tools.elevated）只能进一步限制。
/elevated on|off|ask|full 按会话存储状态；内联指令适用于单条消息。
提升的 exec 在主机上运行，绕过沙箱化。

`tools.exec`

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

`tools.loopDetection`

工具循环安全检查默认禁用。设置 enabled: true 激活检测。设置可以在 tools.loopDetection 中全局定义，并在 agents.list[].tools.loopDetection 中逐代理覆盖。

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

historySize：为循环分析保留的最大工具调用历史。
warningThreshold：重复无进展模式的警告阈值。
criticalThreshold：阻止关键循环的更高重复阈值。
globalCircuitBreakerThreshold：任何无进展运行的硬停止阈值。
detectors.genericRepeat：重复的同工具/同参数调用时发出警告。
detectors.knownPollNoProgress：已知轮询工具（process.poll、command_status 等）的警告/阻止。
detectors.pingPong：交替无进展配对模式的警告/阻止。
如果 warningThreshold >= criticalThreshold 或 criticalThreshold >= globalCircuitBreakerThreshold，验证失败。

`tools.web`

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // 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" }],
      },
    },
  },
}

提供者条目（type: "provider" 或省略）：

provider：API 提供者 id（openai、anthropic、google/gemini、groq 等）
model：模型 id 覆盖
profile / preferredProfile：auth-profiles.json 配置文件选择

CLI 条目（type: "cli"）：

command：要运行的可执行文件
args：模板化参数（支持 {{MediaPath}}、{{Prompt}}、{{MaxChars}} 等）

通用字段：

capabilities：可选列表（image、audio、video）。默认：openai/anthropic/minimax → image，google → image+audio+video，groq → audio。
prompt、maxChars、maxBytes、timeoutSeconds、language：逐条目覆盖。
失败时回退到下一个条目。

提供者认证遵循标准顺序：auth-profiles.json → 环境变量 → models.providers.*.apiKey。

`tools.agentToAgent`

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

`tools.sessions`

控制会话工具（sessions_list、sessions_history、sessions_send）可以目标的会话。

默认：tree（当前会话 + 由它生成的会话，如子代理）。

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

说明：

self：仅当前会话键。
tree：当前会话 + 由当前会话生成的会话（子代理）。
agent：属于当前代理 id 的任何会话（如果你在同一代理 id 下运行按发送者会话，可能包括其他用户）。
all：任何会话。跨代理目标仍需要 tools.agentToAgent。
沙箱限制：当当前会话是沙箱化的且 agents.defaults.sandbox.sessionToolsVisibility="spawned" 时，可见性被强制为 tree，即使 tools.sessions.visibility="all"。

`tools.sessions_spawn`

控制 sessions_spawn 的内联附件支持。

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

说明：

附件仅支持 runtime: "subagent"。ACP 运行时拒绝它们。
文件在子工作区的 .openclaw/attachments/<uuid>/ 中具化，带 .manifest.json。
附件内容自动从转录持久化中脱敏。
Base64 输入通过严格的字母表/填充检查和预解码大小保护进行验证。
文件权限为目录 0700，文件 0600。
清理遵循 cleanup 策略：delete 始终移除附件；keep 仅在 retainOnSessionKeep: true 时保留它们。

`tools.subagents`

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

model：生成子代理的默认模型。如果省略，子代理继承调用者的模型。
runTimeoutSeconds：工具调用省略 runTimeoutSeconds 时 sessions_spawn 的默认超时（秒）。0 表示无超时。
逐子代理工具策略：tools.subagents.tools.allow / tools.subagents.tools.deny。

自定义提供者和 Base URL

OpenClaw 使用 pi-coding-agent 模型目录。通过配置中的 models.providers 或 ~/.openclaw/agents/<agentId>/agent/models.json 添加自定义提供者。

{
  models: {
    mode: "merge", // merge (default) | replace
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

使用 authHeader: true + headers 满足自定义认证需求。
使用 OPENCLAW_AGENT_DIR（或 PI_CODING_AGENT_DIR）覆盖代理配置根目录。
匹配提供者 ID 的合并优先级：
- 非空的代理 models.json baseUrl 值优先。
- 非空的代理 apiKey 值仅在该提供者未在当前配置/auth-profile 上下文中被 SecretRef 管理时优先。
- SecretRef 管理的提供者 apiKey 值从源标记（环境变量引用的 ENV_VAR_NAME、file/exec 引用的 secretref-managed）刷新，而非持久化已解析的密钥。
- 空或缺失的代理 apiKey/baseUrl 回退到配置中的 models.providers。
- 匹配模型的 contextWindow/maxTokens 使用显式配置和隐式目录值之间的较大值。
- 当你想让配置完全重写 models.json 时使用 models.mode: "replace"。

提供者字段详情

models.mode：提供者目录行为（merge 或 replace）。
models.providers：按提供者 id 为键的自定义提供者映射。
models.providers.*.api：请求适配器（openai-completions、openai-responses、anthropic-messages、google-generative-ai 等）。
models.providers.*.apiKey：提供者凭据（建议使用 SecretRef/环境变量替换）。
models.providers.*.auth：认证策略（api-key、token、oauth、aws-sdk）。
models.providers.*.injectNumCtxForOpenAICompat：对于 Ollama + openai-completions，在请求中注入 options.num_ctx（默认：true）。
models.providers.*.authHeader：在需要时强制在 Authorization 头中传输凭据。
models.providers.*.baseUrl：上游 API base URL。
models.providers.*.headers：用于代理/租户路由的额外静态头。
models.providers.*.models：显式的提供者模型目录条目。
models.providers.*.models.*.compat.supportsDeveloperRole：可选兼容性提示。对于具有非空非原生 baseUrl（主机不是 api.openai.com）的 api: "openai-completions"，OpenClaw 在运行时将其强制为 false。空/省略的 baseUrl 保持默认 OpenAI 行为。
models.bedrockDiscovery：Bedrock 自动发现设置根。
models.bedrockDiscovery.enabled：开启/关闭发现轮询。
models.bedrockDiscovery.region：发现的 AWS 区域。
models.bedrockDiscovery.providerFilter：可选的提供者 id 过滤器，用于定向发现。
models.bedrockDiscovery.refreshInterval：发现刷新的轮询间隔。
models.bedrockDiscovery.defaultContextWindow：已发现模型的回退上下文窗口。
models.bedrockDiscovery.defaultMaxTokens：已发现模型的回退最大输出 token。

提供者示例

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

Cerebras 使用 cerebras/zai-glm-4.7；Z.AI 直连使用 zai/glm-4.7。

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

设置 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）。Zen catalog 使用 opencode/... 引用，Go catalog 使用 opencode-go/... 引用。快捷方式：openclaw onboard --auth-choice opencode-zen 或 openclaw onboard --auth-choice opencode-go。

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

设置 ZAI_API_KEY。z.ai/* 和 z-ai/* 作为别名被接受。快捷方式：openclaw onboard --auth-choice zai-api-key。

通用端点：https://api.z.ai/api/paas/v4
编码端点（默认）：https://api.z.ai/api/coding/paas/v4
对于通用端点，使用 base URL 覆盖定义自定义提供者。

{
  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。

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

Anthropic 兼容，内置提供者。快捷方式：openclaw onboard --auth-choice kimi-code-api-key。

{
  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。

{
  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 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：可选的仅限捆绑 Skills 的白名单（托管/工作区 Skills 不受影响）。
entries.<skillKey>.enabled: false 即使已捆绑/安装也禁用 Skill。
entries.<skillKey>.apiKey：声明主要环境变量的 Skills 的便捷字段（明文字符串或 SecretRef 对象）。

插件

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

从 ~/.openclaw/extensions、<workspace>/.openclaw/extensions 加载，加上 plugins.load.paths。
配置更改需要 Gateway 重启。
allow：可选白名单（仅列出的插件加载）。deny 优先。
plugins.entries.<id>.apiKey：插件级 API key 便捷字段（当插件支持时）。
plugins.entries.<id>.env：插件范围的环境变量映射。
plugins.entries.<id>.hooks.allowPromptInjection：为 false 时，核心阻止 before_prompt_build 并忽略旧版 before_agent_start 的提示变更字段，同时保留旧版 modelOverride 和 providerOverride。
plugins.entries.<id>.config：插件定义的配置对象（由插件 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 命令而非手动编辑。

参见插件。

浏览器

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

evaluateEnabled: false 禁用 act:evaluate 和 wait --fn。
ssrfPolicy.dangerouslyAllowPrivateNetwork 未设置时默认为 true（受信任网络模型）。
设置 ssrfPolicy.dangerouslyAllowPrivateNetwork: false 实现严格的仅公共浏览器导航。
ssrfPolicy.allowPrivateNetwork 作为旧版别名仍然受支持。
在严格模式下，使用 ssrfPolicy.hostnameAllowlist 和 ssrfPolicy.allowedHostnames 进行显式例外。
远程配置文件为仅附加模式（禁用启动/停止/重置）。
自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
控制服务：仅 loopback（端口从 gateway.port 派生，默认 18791）。
extraArgs 向本地 Chromium 启动追加额外启动标志（例如 --disable-gpu、窗口大小或调试标志）。
relayBindHost 更改 Chrome 扩展中继监听位置。未设置时保持仅 loopback 访问；仅在中继必须跨命名空间边界（例如 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：Control UI 身份覆盖。回退到活跃代理身份。

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

mode：local（运行 Gateway）或 remote（连接到远程 Gateway）。Gateway 除非为 local 否则拒绝启动。
port：WS + HTTP 的单复用端口。优先级：--port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789。
bind：auto、loopback（默认）、lan（0.0.0.0）、tailnet（仅 Tailscale IP）或 custom。
旧版绑定别名：在 gateway.bind 中使用绑定模式值（auto、loopback、lan、tailnet、custom），而非主机别名（0.0.0.0、127.0.0.1、localhost、::、::1）。
Docker 注意：默认 loopback 绑定在容器内监听 127.0.0.1。使用 Docker 桥接网络（-p 18789:18789）时，流量到达 eth0，因此 Gateway 不可达。使用 --network host，或设置 bind: "lan"（或 bind: "custom" 配合 customBindHost: "0.0.0.0"）以监听所有接口。
认证：默认需要。非 loopback 绑定需要共享令牌/密码。引导向导默认生成令牌。
如果同时配置了 gateway.auth.token 和 gateway.auth.password（包括 SecretRef），请将 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 端点仍需要令牌/密码认证。此无令牌流程假定 Gateway 主机是受信任的。当 tailscale.mode = "serve" 时默认为 true。
gateway.auth.rateLimit：可选的认证失败限制器。按客户端 IP 和认证范围（共享密钥和设备令牌独立跟踪）适用。被阻止的尝试返回 429 + Retry-After。
- gateway.auth.rateLimit.exemptLoopback 默认为 true；设置 false 当你有意想对 localhost 流量也进行速率限制时（用于测试设置或严格代理部署）。
浏览器来源的 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 调用路径仅在 gateway.auth.* 未设置时可使用 gateway.remote.* 作为回退。
如果 gateway.auth.token / gateway.auth.password 通过 SecretRef 显式配置且未解析，解析会安全关闭（无远程回退掩盖）。
trustedProxies：终止 TLS 的反向代理 IP。仅列出你控制的代理。
allowRealIpFallback：为 true 时，Gateway 在 X-Forwarded-For 缺失时接受 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-input 加固：
- 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>）。

参见多 Gateway。

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? }
- 请求载荷中的 sessionKey 仅在 hooks.allowRequestSessionKey=true（默认：false）时被接受。
POST /hooks/<name> → 通过 hooks.mappings 解析

match.path 匹配 /hooks 后的子路径（例如 /hooks/gmail → gmail）。
match.source 匹配通用路径的载荷字段。
模板如 {{messages[0].subject}} 从载荷中读取。
transform 可以指向返回 hook 动作的 JS/TS 模块。
- transform.module 必须是相对路径且保持在 hooks.transformsDir 内（绝对路径和遍历被拒绝）。
agentId 路由到特定代理；未知 ID 回退到默认值。
allowedAgentIds：限制显式路由（* 或省略 = 允许所有，[] = 拒绝所有）。
defaultSessionKey：没有显式 sessionKey 的 hook 代理运行的可选固定会话键。
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 提供代理可编辑的 HTML/CSS/JS 和 A2UI：
- http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
- http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
仅本地：保持 gateway.bind: "loopback"（默认）。
非 loopback 绑定：canvas 路由需要 Gateway 认证（令牌/密码/trusted-proxy），与其他 Gateway HTTP 表面相同。
Node WebView 通常不发送认证头；节点配对并连接后，Gateway 为 canvas/A2UI 访问通告节点范围的能力 URL。
能力 URL 绑定到活跃的节点 WS 会话并很快过期。不使用基于 IP 的回退。
向提供的 HTML 注入实时重载客户端。
为空时自动创建入门 index.html。
也在 /__openclaw__/a2ui/ 提供 A2UI。
更改需要 Gateway 重启。
对于大目录或 EMFILE 错误，禁用实时重载。

发现

mDNS（Bonjour）

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

minimal（默认）：从 TXT 记录中省略 cliPath + sshPort。
full：包含 cliPath + sshPort。
主机名默认为 openclaw。使用 OPENCLAW_MDNS_HOSTNAME 覆盖。

广域（DNS-SD）

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

在 ~/.openclaw/dns/ 下写入单播 DNS-SD 区域。对于跨网络发现，配合 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。

设置：openclaw dns setup --apply。

环境

`env`（内联环境变量）

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

内联环境变量仅在进程环境缺少该键时应用。
.env 文件：CWD .env + ~/.openclaw/.env（两者都不覆盖现有变量）。
shellEnv：从你的登录 shell 配置文件导入缺失的预期键。
参见环境了解完整优先级。

环境变量替换

在任何配置字符串中使用 ${VAR_NAME} 引用环境变量：

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

仅匹配大写名称：[A-Z_][A-Z0-9_]*。
缺失/空变量在配置加载时抛出错误。
使用 $${VAR} 转义为字面 ${VAR}。
与 $include 配合使用。

密钥

密钥引用是增量式的：明文值仍然有效。

`SecretRef`

使用一个对象结构：

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

验证：

provider 模式：^[a-z][a-z0-9_-]{0,63}$
source: "env" id 模式：^[A-Z][A-Z0-9_]{0,127}$
source: "file" id：绝对 JSON 指针（例如 "/providers/openai/apiKey"）
source: "exec" id 模式：^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
source: "exec" id 不能包含 . 或 .. 斜杠分隔的路径段（例如 a/../b 被拒绝）

支持的凭据表面

规范矩阵：SecretRef 凭据表面
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 上使用协议载荷。
默认情况下，符号链接命令路径被拒绝。设置 allowSymlinkCommand: true 以允许符号链接路径，同时验证解析后的目标路径。
如果配置了 trustedDirs，受信任目录检查适用于解析后的目标路径。
exec 子进程环境默认最小化；使用 passEnv 显式传递所需变量。
密钥引用在激活时解析为内存快照，然后请求路径仅读取快照。
激活期间适用活跃表面过滤：已启用表面上未解析的引用导致启动/重新加载失败，而非活跃表面带诊断信息被跳过。

认证存储

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

逐代理配置文件存储在 <agentDir>/auth-profiles.json。
auth-profiles.json 支持值级引用（api_key 的 keyRef、token 的 tokenRef）。
静态运行时凭据来自内存中已解析的快照；遗留静态 auth.json 条目在被发现时被清除。
从 ~/.openclaw/credentials/oauth.json 导入旧版 OAuth。
参见 OAuth。
密钥运行时行为和 audit/configure/apply 工具：密钥管理。

日志

{
  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 向导（onboard、configure、doctor）写入的元数据：

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

身份

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

由 macOS 引导助手写入。派生默认值：

messages.ackReaction 来自 identity.emoji（回退到 👀）
mentionPatterns 来自 identity.name/identity.emoji
avatar 接受：工作区相对路径、http(s) URL 或 data: URI

Bridge（旧版，已移除）

当前构建不再包含 TCP bridge。节点通过 Gateway WebSocket 连接。bridge.* 键不再属于配置 schema（验证失败直到移除；openclaw doctor --fix 可以剥离未知键）。

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

Cron

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

sessionRetention：完成的隔离 cron 运行会话在从 sessions.json 修剪之前保留多长时间。也控制已归档的已删除 cron 转录的清理。默认：24h；设置 false 禁用。
runLog.maxBytes：每个运行日志文件（cron/runs/<jobId>.jsonl）在修剪前的最大大小。默认：2_000_000 字节。
runLog.keepLines：运行日志修剪触发时保留的最新行数。默认：2000。
webhookToken：用于 cron webhook POST 投递（delivery.mode = "webhook"）的 bearer token，省略时不发送认证头。
webhook：已弃用的旧版回退 webhook URL（http/https），仅用于仍有 notify: true 的已存储作业。

参见定时任务。

媒体模型模板变量

tools.media.models[].args 中展开的模板占位符：

变量	描述
`{{Body}}`	完整入站消息正文
`{{RawBody}}`	原始正文（无历史/发送者包装）
`{{BodyStripped}}`	剥离群组提及的正文
`{{From}}`	发送者标识符
`{{To}}`	目标标识符
`{{MessageSid}}`	频道消息 id
`{{SessionId}}`	当前会话 UUID
`{{IsNewSession}}`	创建新会话时为 `"true"`
`{{MediaUrl}}`	入站媒体伪 URL
`{{MediaPath}}`	本地媒体路径
`{{MediaType}}`	媒体类型（image/audio/document/…）
`{{Transcript}}`	音频转录
`{{Prompt}}`	CLI 条目的已解析媒体提示
`{{MaxChars}}`	CLI 条目的已解析最大输出字符数
`{{ChatType}}`	`"direct"` 或 `"group"`
`{{GroupSubject}}`	群组主题（尽力而为）
`{{GroupMembers}}`	群组成员预览（尽力而为）
`{{SenderName}}`	发送者显示名称（尽力而为）
`{{SenderE164}}`	发送者电话号码（尽力而为）
`{{Provider}}`	提供者提示（whatsapp、telegram、discord 等）

配置包含（`$include`）

将配置拆分为多个文件：

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

合并行为：

单文件：替换包含对象。
文件数组：按顺序深度合并（后者覆盖前者）。
同级键：在包含之后合并（覆盖包含的值）。
嵌套包含：最多 10 层深。
路径：相对于包含文件解析，但必须保持在顶层配置目录（openclaw.json 的 dirname）内。绝对/../ 形式仅在它们仍然解析到该边界内时允许。
错误：对缺失文件、解析错误和循环包含提供清晰消息。

相关：配置 · 配置示例 · Doctor