配置参考

~/.openclaw/openclaw.json 中可用的每个字段。如需面向任务的概述，请参阅配置。

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

渠道

当存在配置部分时，每个渠道会自动启动（除非 enabled: false）。

私聊和群组访问

所有渠道都支持私聊策略和群组策略：

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

群组策略	行为
`allowlist` (默认)	仅限匹配配置的允许列表的群组
`open`	绕过群组允许列表（提及限制仍然适用）
`disabled`	阻止所有群组/房间消息

渠道模型覆盖

使用 channels.modelByChannel 将特定渠道 ID 固定到模型。值接受 provider/model 或配置的模型别名。当会话尚未具有模型覆盖时（例如，通过 /model 设置），应用渠道映射。

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

渠道默认值和心跳

使用 channels.defaults 在提供商之间实现共享的组策略和心跳行为：

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

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

WhatsApp 通过网关的 Web 渠道（Baileys Web）运行。当存在关联的会话时，它会自动启动。

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

多账号 WhatsApp

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

出站命令默认使用账号 default（如果存在）；否则使用第一个配置的账号 id（已排序）。
可选的 channels.whatsapp.defaultAccount 会覆盖该回退默认账号选择，当其与已配置的账号 id 匹配时。
旧版单账号 Baileys 认证目录会由 openclaw doctor 迁移至 whatsapp/default。
每账号覆盖项：`channels.whatsapp.accounts.

.sendReadReceipts、channels.whatsapp.accounts.

.dmPolicy、channels.whatsapp.accounts.

.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; opt in explicitly to avoid preview-edit rate limits)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

Bot 令牌：channels.telegram.botToken 或 channels.telegram.tokenFile（仅限常规文件；拒绝符号链接），其中 TELEGRAM_BOT_TOKEN 作为默认账号的回退项。
可选的 channels.telegram.defaultAccount 会覆盖默认账号选择，当其与已配置的账号 id 匹配时。
在多账号设置中（2 个或更多账号 id），设置一个显式的默认值（channels.telegram.defaultAccount 或 channels.telegram.accounts.default）以避免回退路由；openclaw doctor 会在其缺失或无效时发出警告。
configWrites: false 阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、/config set|unset）。
具有 type: "acp" 的顶层 bindings[] 条目为论坛主题配置持久的 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 maps to partial on Discord)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true })
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

令牌：channels.discord.token，其中 DISCORD_BOT_TOKEN 作为默认账号的回退项。
提供显式 Discord token 的直接出站调用将使用该令牌进行调用；账号重试/策略设置仍来自活动运行时快照中选定的账号。
可选的 channels.discord.defaultAccount 在匹配已配置的账户 ID 时覆盖默认账户选择。
使用 user:<id> (私信) 或 channel:<id> (服务器频道) 作为交付目标；不接受纯数字 ID。
服务器 slug 为小写，空格替换为 -；频道键使用 slugged 名称（无 #）。建议使用服务器 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 }) 自动线程创建/绑定的选择性加入开关
带有 type: "acp" 的顶级 bindings[] 条目为频道和线程配置持久的 ACP 绑定（在 match.peer.id 中使用频道/线程 ID）。字段语义在 ACP Agents 中共享。
channels.discord.ui.components.accentColor 设置 Discord 组件 v2 容器的强调色。
channels.discord.voice 启用 Discord 语音频道对话和可选的自动加入 + TTS 覆盖。
channels.discord.voice.daveEncryption 和 channels.discord.voice.decryptionFailureTolerance 传递给 @discordjs/voice DAVE 选项（默认为 true 和 24）。
OpenClaw 还会在重复解密失败后，通过离开/重新加入语音会话来尝试语音接收恢复。
channels.discord.streaming 是规范的流模式键。传统的 streamMode 和布尔 streaming 值会自动迁移。
channels.discord.autoPresence 将运行时可用性映射到机器人在线状态（健康 => 在线，降级 => 空闲，耗尽 => 忙碌），并允许可选的状态文本覆盖。
channels.discord.dangerouslyAllowNameMatching 重新启用可变名称/标签匹配（应急兼容模式）。

反应通知模式： off（无），own（机器人的消息，默认），all（所有消息），allowlist（从 guilds.<id>.users 开始的所有消息）。

Google Chat

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

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

Slack

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

表情回复通知模式： off、own（默认）、all、allowlist（来自 reactionAllowlist）。

会话线程隔离： thread.historyScope 按线程隔离（默认）或在渠道间共享。thread.inheritParent 会将父渠道的记录复制到新线程中。

typingReaction 会在回复运行时向传入的 Slack 消息添加一个临时表情，然后在完成后将其移除。请使用 Slack 表情符号代码，例如 "hourglass_flowing_sand"。

操作组	默认值	备注
reactions	enabled	反应 + 列出反应
messages	enabled	读取/发送/编辑/删除
pins	enabled	固定/取消固定/列出
memberInfo	enabled	成员信息
emojiList	enabled	自定义 emoji 列表

Mattermost

Mattermost 作为插件提供：openclaw plugins install @openclaw/mattermost。

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      commands: {
        native: true, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Optional explicit URL for reverse-proxy/public deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

聊天模式：oncall（在 @提及时回复，默认）、onmessage（每条消息）、onchar（以触发前缀开头的消息）。

当启用 Mattermost 原生命令时：

commands.callbackPath 必须是路径（例如 /api/channels/mattermost/command），而不是完整的 URL。
commands.callbackUrl 必须解析到 OpenClaw 网关端点，并且可从 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 时覆盖默认账户选择。
具有 type: "acp" 的顶级 bindings[] 条目可以将 BlueBubbles 对话绑定到持久的 ACP 会话。在 match.peer.id 中使用 BlueBubbles 句柄或目标字符串（chat_id:*、chat_guid:*、chat_identifier:*）。共享字段语义：ACP Agents。
完整的 BlueBubbles 渠道配置记录在 BlueBubbles 中。

iMessage

OpenClaw 会生成 imsg rpc（通过 stdio 进行 JSON-RPC 通信）。不需要守护进程或端口。

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

可选的 channels.imessage.defaultAccount 会在匹配已配置的账户 ID 时覆盖默认账户选择。
需要对 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 发起的配置写入。
带有 type: "acp" 的顶级 bindings[] 条目可以将 iMessage 会话绑定到持久化的 ACP 会话。在 match.peer.id 中使用规范化句柄或显式聊天目标（chat_id:*、chat_guid:*、chat_identifier:*）。共享字段语义：ACP Agents。

iMessage SSH 包装器示例

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

Matrix

Matrix 由扩展支持，并在 channels.matrix 下进行配置。

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

令牌认证使用 accessToken；密码认证使用 userId + password。
channels.matrix.proxy 通过显式的 HTTP(S) 代理路由 Matrix HTTP 流量。命名账户可以使用 channels.matrix.accounts.<id>.proxy 覆盖它。
channels.matrix.allowPrivateNetwork 允许使用私有/内部主服务器。proxy 和 allowPrivateNetwork 是独立的控制项。
channels.matrix.defaultAccount 在多账户设置中选择首选账户。
Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。
完整的 Matrix 配置、定位规则和设置示例记录在 Matrix 中。

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、私信/组策略、按团队/按渠道覆盖）记录在 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 匹配时，可选的 channels.irc.defaultAccount 会覆盖默认的账户选择。
完整的 IRC 渠道配置（主机/端口/TLS/渠道/允许列表/提及控制）记录在 IRC 中。

多账号（所有渠道）

每个渠道运行多个账号（每个都有自己的 accountId）：

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

当省略 accountId 时使用 default（CLI + 路由）。
环境令牌仅适用于默认账号。
基础渠道设置适用于所有账号，除非按账号覆盖。
使用 bindings[].match.accountId 将每个账号路由到不同的代理。
如果您在仍处于单账号顶级渠道配置时通过 openclaw channels add（或渠道新手引导）添加非默认账号，OpenClaw 会先将账号范围的顶级单账号值移动到 channels.<channel>.accounts.default 中，以便原始账号继续工作。
现有的仅渠道绑定（无 accountId）继续匹配默认账号；账号范围的绑定仍然是可选的。
当存在命名账号但缺少 default 时，openclaw doctor --fix 还会通过将账号范围的顶级单账号值移动到 accounts.default 来修复混合形状。

其他扩展渠道

许多扩展渠道配置为 channels.<id> 并记录在其专门的渠道页面中（例如飞书、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。查看完整的渠道索引：渠道。

群聊提及控制

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

提及类型：

元数据提及：原生的平台 @提及。在 WhatsApp 自聊模式中忽略。
文本模式：agents.list[].groupChat.mentionPatterns 中的安全正则表达式模式。无效的模式和不安全的嵌套重复将被忽略。
仅在检测可行（原生提及或至少一种模式）时才强制执行提及控制。

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

messages.groupChat.historyLimit 设置全局默认值。频道可以使用 channels.<channel>.historyLimit（或每个账户）覆盖。设置 0 以禁用。

私信历史记录限制

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

解析顺序：每条私信的覆盖 -> 提供商默认 -> 无限制（全部保留）。

支持：telegram、whatsapp、discord、slack、signal、imessage、msteams。

自聊模式

在 allowFrom 中包含您自己的号码以启用自聊模式（忽略原生 @提及，仅响应文本模式）：

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

指令（聊天指令处理）

{
  commands: {
    native: "auto", // register native commands when supported
    text: true, // parse /commands in chat messages
    bash: false, // allow ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // allow /config
    debug: false, // allow /debug
    restart: false, // allow /restart + gateway restart tool
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

Command details

文本命令必须是带有前缀 / 的独立消息。
native: "auto" 会为 Discord/Telegram 开启原生命令，并保持 Slack 关闭。
按渠道覆盖：channels.discord.commands.native（布尔值或 "auto"）。false 会清除之前注册的命令。
channels.telegram.customCommands 添加额外的 Telegram 机器人菜单条目。
bash: true 为主机 Shell 启用 `!

。需要 tools.elevated.enabled且发送者在tools.elevated.allowFrom.

` 中。

config: true 启用 /config（读/写 openclaw.json）。对于网关 chat.send 客户端，持久性 /config set|unset 写入还需要 operator.admin；只读 /config show 仍可供普通写入作用域的操作员客户端使用。
`channels.

.configWrites` 控制每个渠道的配置变更（默认：true）。

对于多账户渠道，`channels.

.accounts.

.configWrites也会控制针对该账户的写入操作（例如/allowlist —config —account

或/config set channels.

.accounts.

…`）。

allowFrom 是按提供商设置的。设置后，它是唯一的授权来源（渠道允许列表/配对和 useAccessGroups 会被忽略）。
当未设置 allowFrom 时，useAccessGroups: false 允许命令绕过访问组策略。

Agent defaults

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

较低的值通常会减少视觉令牌（vision-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.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-1",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5-mini"],
      },
      params: { cacheRetention: "long" }, // global default provider params
      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 工具路径的视觉模型配置。
- 当选定的/默认模型无法接受图像输入时，也用作故障转移路由。
imageGenerationModel：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
- 由共享图像生成功能以及任何生成图像的未来工具/插件接口使用。
- 典型值：原生 Gemini 图像生成使用 google/gemini-3-pro-image-preview，fal 使用 fal/fal-ai/flux/dev，OpenAI Images 使用 openai/gpt-image-1。
- 如果直接选择提供商/模型，请同时配置匹配的提供商 auth/API 密钥（例如 google/* 使用 GEMINI_API_KEY 或 GOOGLE_API_KEY，openai/* 使用 OPENAI_API_KEY，fal/* 使用 FAL_KEY）。
- 如果省略，image_generate 仍然可以从兼容的支持身份验证的图像生成提供商中推断尽力的提供商默认值。
pdfModel：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
- 由 pdf 工具用于模型路由。
- 如果省略，PDF 工具将回退到 imageModel，然后再回退到尽力而为的提供商默认值。
pdfMaxBytesMb：pdf 工具在调用时未传递 maxBytesMb 时的默认 PDF 大小限制。
pdfMaxPages：pdf 工具中提取回退模式考虑的默认最大页数。
verboseDefault：代理的默认详细级别。值："off"、"on"、"full"。默认值："off"。
elevatedDefault：代理的默认提升输出级别。值："off"、"on"、"ask"、"full"。默认值："on"。
model.primary: 格式 provider/model (例如 anthropic/claude-opus-4-6)。如果省略提供商，OpenClaw 将假定 anthropic（已弃用）。
models: 为 /model 配置的模型目录和允许列表。每个条目可以包含 alias（快捷方式）和 params（特定于提供商，例如 temperature、maxTokens、cacheRetention、context1m）。
params: 应用于所有模型的全局默认提供商参数。在 agents.defaults.params 设置（例如 { cacheRetention: "long" }）。
params 合并优先级（配置）：agents.defaults.params（全局基础）被 agents.defaults.models["provider/model"].params（每个模型）覆盖，然后 agents.list[].params（匹配的 agent id）按键覆盖。详细信息请参阅 Prompt Caching。
变更这些字段的配置写入程序（例如 /models set、/models set-image 以及回退添加/删除命令）将保存规范的对象形式，并尽可能保留现有的回退列表。
maxConcurrent: 跨会话的最大并行 agent 运行数（每个会话仍然串行化）。默认值：4。

内置别名简写（仅在模型位于 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`

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

除非您设置了 --thinking off 或自行定义了 agents.defaults.models["zai/<model>"].params.thinking，否则 Z.AI GLM-4.x 模型会自动启用思考模式。默认情况下，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
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        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 (API 密钥认证) 或 1h (OAuth 认证)。设置为 0m 可将其禁用。
suppressToolErrorWarnings：如果为 true，则在心跳运行期间禁止工具错误警告载荷。
directPolicy：直接/私信传递策略。allow (默认) 允许直接目标传递。block 禁止直接目标传递并发出 reason=dm-blocked。
lightContext：如果为 true，心跳运行使用轻量级引导上下文，并且仅保留工作区引导文件中的 HEARTBEAT.md。
isolatedSession：如果为 true，每次心跳都在没有先前对话历史记录的新会话中运行。与 cron sessionTarget: "isolated" 具有相同的隔离模式。将每次心跳的 token 成本从约 100K 降低到约 2-5K token。
每个代理：设置 agents.list[].heartbeat。当任何代理定义了 heartbeat 时，仅这些代理运行心跳。
心跳运行完整的代理轮次 —— 间隔越短，消耗的 token 越多。

`agents.defaults.compaction`

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        timeoutSeconds: 900,
        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-6", // optional compaction-only model override
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

mode: default 或 safeguard (针对长历史的分块摘要)。请参阅 Compaction。
timeoutSeconds: OpenClaw 中止单次压缩操作前允许的最长秒数。默认值: 900。
identifierPolicy: strict (默认), off, 或 custom。strict 会在压缩摘要期间预置内置的保留标识符的指导说明。
identifierInstructions: 使用 identifierPolicy=custom 时可选的自定义保留标识符文本。
postCompactionSections: 压缩后重新注入的可选 AGENTS.md H2/H3 部分名称。默认为 ["Session Startup", "Red Lines"]；设置为 [] 以禁用重新注入。当未设置或显式设置为该默认对时，较旧的 Every Session/Safety 标题也将作为旧版回退选项被接受。
model: 仅用于压缩摘要的可选 provider/model-id 覆盖。当主会话应保留一个模型但压缩摘要应在另一个模型上运行时使用此选项；未设置时，压缩使用会话的主要模型。
memoryFlush: 自动压缩之前的静默智能体回合，用于存储持久记忆。当工作区为只读时跳过。

`agents.defaults.contextPruning`

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

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

cache-ttl 模式行为

mode: "cache-ttl" 启用修剪过程。
ttl 控制修剪可以再次运行的频率（在上一次缓存接触之后）。
修剪首先会对超大的工具结果进行软修剪，然后在需要时硬清除较旧的工具结果。

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

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

注意：

图像块永远不会被修剪/清除。
比率是基于字符的（近似值），而不是精确的令牌计数。
如果存在的助手消息少于 keepLastAssistants 条，则跳过修剪。

有关行为详细信息，请参阅会话修剪。

分块流式传输

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

嵌入式代理的可选沙箱隔离。有关完整指南，请参阅沙箱隔离。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        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"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRefs / inline contents also supported:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        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"],
      },
    },
  },
}

沙箱详情

后端：

docker：本地 Docker 运行时（默认）
ssh：通用的 SSH 支持的远程运行时
openshell：OpenShell 运行时

当选择 backend: "openshell" 时，特定于运行时的设置会移至 plugins.entries.openshell.config。

SSH 后端配置：

target：user@host[:port] 格式的 SSH 目标
command：SSH 客户端命令（默认：ssh）
workspaceRoot：用于每个范围工作区的绝对远程根目录
identityFile / certificateFile / knownHostsFile：传递给 OpenSSH 的现有本地文件
identityData / certificateData / knownHostsData：内联内容或 SecretRefs，OpenClaw 在运行时将其具象化为临时文件
strictHostKeyChecking / updateHostKeys：OpenSSH 主机密钥策略控制项

SSH 认证优先级：

identityData 优先于 identityFile
certificateData 优先于 certificateFile
knownHostsData 优先于 knownHostsFile
基于 SecretRef 的 *Data 值在沙箱会话开始之前从活动的机密运行时快照中解析

SSH 后端行为：

在创建或重新创建后初始化一次远程工作区
然后保持远程 SSH 工作区为权威版本
通过 SSH 路由 exec、文件工具和媒体路径
不会自动将远程更改同步回主机
不支持沙箱浏览器容器

工作区访问：

none：位于 ~/.openclaw/sandboxes 下的每个范围的沙箱工作区
ro：位于 /workspace 的沙箱工作区，代理工作区以只读方式挂载于 /agent
rw：代理工作区以读/写方式挂载于 /workspace

范围：

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

OpenShell 插件配置：

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          mode: "mirror", // mirror | remote
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // optional
          gatewayEndpoint: "https://lab.example", // optional
          policy: "strict", // optional OpenShell policy id
          providers: ["openai"], // optional
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

OpenShell 模式：

mirror：在执行前从本地初始化远程，在执行后同步回本地；本地工作区保持权威版本
remote：在创建沙箱时初始化远程一次，然后保持远程工作区为权威版本

在 remote 模式下，在 OpenClaw 之外进行的主机本地编辑在初始化步骤之后不会自动同步到沙箱中。传输是通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期和可选的镜像同步。

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

容器默认为 network: "none" — 如果代理需要出站访问，请设置为 "bridge"（或自定义桥接网络）。 "host" 被阻止。除非您显式设置 sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true（应急手段），否则 `“container:

”` 默认被阻止。

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

docker.binds 挂载其他主机目录；全局和每个代理的绑定会被合并。

沙箱隔离浏览器（sandbox.browser.enabled）：容器中的 Chromium + CDP。noVNC URL 被注入到系统提示词中。不需要 openclaw.json 中的 browser.enabled。 noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短期令牌 URL（而不是在共享 URL 中暴露密码）。

allowHostControl: false（默认）阻止沙箱隔离会话定位主机浏览器。
network 默认为 openclaw-sandbox-browser（专用桥接网络）。仅当您明确需要全局桥接连接时才设置为 bridge。
cdpSourceRange 可选择将容器边缘的 CDP 入站限制为 CIDR 范围（例如 172.21.0.1/32）。
sandbox.browser.binds 仅将其他主机目录挂载到沙箱浏览器容器中。设置时（包括 []），它会替换浏览器容器的 docker.binds。
启动默认值在 scripts/sandbox-browser-entrypoint.sh 中定义，并针对容器主机进行了调整：
- --remote-debugging-address=127.0.0.1
- `—remote-debugging-port=

--user-data-dir=${HOME}/.chrome
--no-first-run
--no-default-browser-check
--disable-3d-apis
--disable-gpu
--disable-software-rasterizer
--disable-dev-shm-usage
--disable-background-networking
--disable-features=TranslateUI
--disable-breakpad
--disable-crash-reporter
--renderer-process-limit=2
--no-zygote
--metrics-recording-only
--disable-extensions（默认启用）
--disable-3d-apis、--disable-software-rasterizer 和 --disable-gpu 默认启用，如果 WebGL/3D 使用需要，可以使用 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 禁用。
OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 在您的工作流依赖扩展时重新启用它们。
--renderer-process-limit=2 可以通过 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=

更改；设置0` 以使用 Chromium 的默认进程限制。

当启用 noSandbox 时，加上 --no-sandbox 和 --disable-setuid-sandbox。
默认值是容器镜像基线；使用带有自定义入口点的自定义浏览器镜像来更改容器默认值。

浏览器沙箱隔离和 sandbox.docker.binds 目前仅支持 Docker。

构建镜像：

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 }
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        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 的定时任务仍会继承默认回退，除非你设置了 fallbacks: []。
params：合并到 agents.defaults.models 中所选模型条目的每个代理流参数。使用此选项进行代理特定的覆盖，如 cacheRetention、temperature 或 maxTokens，而无需复制整个模型目录。
thinkingDefault：可选的每个代理默认思考级别（off | minimal | low | medium | high | xhigh | adaptive）。当未设置每条消息或会话覆盖时，覆盖此代理的 agents.defaults.thinkingDefault。
reasoningDefault：可选的每个代理默认推理可见性（on | off | stream）。当未设置每条消息或会话推理覆盖时应用。
fastModeDefault：可选的每个代理快速模式默认值（true | false）。当未设置每条消息或会话快速模式覆盖时应用。
runtime：可选的每个代理运行时描述符。当代理应默认为 ACP 挂载会话时，使用带有 runtime.acp 默认值（agent、backend、mode、cwd）的 type: "acp"。
identity.avatar：工作区相对路径、http(s) URL 或 data: URI。
identity 派生默认值：从 emoji 派生 ackReaction，从 name/emoji 派生 mentionPatterns。
subagents.allowAgents：用于 sessions_spawn 的代理 ID 白名单（["*"] = 任意；默认值：仅限相同代理）。
沙箱隔离继承保护：如果请求者会话是沙箱隔离的，sessions_spawn 将拒绝会以非沙箱隔离方式运行的目标。
subagents.requireAgentId：如果为 true，则阻止省略了 agentId 的 sessions_spawn 调用（强制显式选择配置文件；默认值：false）。

多代理路由

在一个 Gateway(网关) 内运行多个隔离的代理。请参阅 Multi-Agent。

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

绑定匹配字段

type（可选）：route 用于普通路由（缺少类型时默认为 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 + account + 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",
    },
  },
}

会话字段详情

scope：群聊上下文的基础会话分组策略。
- per-sender（默认）：每个发送者在渠道上下文中获得一个独立的会话。
- global：渠道上下文中的所有参与者共享单个会话（仅在意图共享上下文时使用）。
dmScope：如何对私信进行分组。
- main：所有私信共享主会话。
- 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"。
agentToAgent.maxPingPongTurns：代理之间在代理到代理交换期间的最大回复轮次（整数，范围：0–5）。0 禁用乒乓链接。
sendPolicy：按 channel、chatType（direct|group|channel，带有传统 dm 别名）、keyPrefix 或 rawKeyPrefix 匹配。优先拒绝。
maintenance：会话存储清理 + 保留控制。
- mode：warn 仅发出警告；enforce 应用清理。
- pruneAfter：陈旧条目的过期时间（默认 30d）。
- maxEntries：sessions.json 中的最大条目数（默认 500）。
- rotateBytes：当 sessions.json 超过此大小时进行轮换（默认 10mb）。
- resetArchiveRetention：`*.reset.

对话记录存档的保留期。默认为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}`	Agent 身份名称	（与 `"auto"` 相同）

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

确认反应

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

入站防抖

将来自同一发送者的快速纯文本消息批处理为单个 Agent 轮次。媒体/附件会立即刷新。控制命令会绕过防抖。

TTS（文本转语音）

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

auto 控制自动 TTS。/tts off|always|inbound|tagged 按会话覆盖。
summaryModel 覆盖 agents.defaults.model.primary 以进行自动总结。
modelOverrides 默认启用；modelOverrides.allowProvider 默认为 false（需选择加入）。
API 密钥回退到 ELEVENLABS_API_KEY/XI_API_KEY 和 OPENAI_API_KEY。
openai.baseUrl 会覆盖 OpenAI TTS 端点。解析顺序为：配置项，然后是 OPENAI_TTS_BASE_URL，接着是 https://api.openai.com/v1。
当 openai.baseUrl 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音验证。

Talk

Talk 模式的默认设置 (macOS/iOS/Android)。

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

语音 ID 回退到 ELEVENLABS_VOICE_ID 或 SAG_VOICE_ID。
apiKey 和 providers.*.apiKey 接受纯文本字符串或 SecretRef 对象。
ELEVENLABS_API_KEY 回退仅适用于未配置 Talk API 密钥的情况。
voiceAliases 允许 Talk 指令使用友好名称。
silenceTimeoutMs 控制 Talk 模式在用户静音后发送转录文本之前的等待时长。未设置时保留平台默认的暂停窗口 (700 ms on macOS and Android, 900 ms on iOS)。

工具

工具配置

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`

进一步限制特定提供商或模型的工具。顺序：基础配置文件 → 提供商配置文件 → 允许/拒绝。

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

`tools.elevated`

控制提升（主机）执行访问权限：

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

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

`tools.exec`

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

`tools.loopDetection`

工具循环安全检查默认处于禁用状态。设置 enabled: true 以激活检测。设置可以在 tools.loopDetection 中全局定义，并在 agents.list[].tools.loopDetection 中针对每个代理进行覆盖。

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

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

`tools.web`

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // 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" 时，即使 tools.sessions.visibility="all"，可见性也会被强制设为 tree。

`tools.sessions_spawn`

控制 sessions_spawn 的内联附件支持。

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

备注：

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

`agents.defaults.subagents`

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

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

自定义提供商和基础 URL

OpenClaw 使用内置的模型目录。可以通过配置中的 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 的合并优先级：
- 非空的 agent models.json baseUrl 值优先。
- 仅当该提供商在当前 config/auth-profile 上下文中未由 SecretRef 管理时，非空的 agent apiKey 值才优先。
- 由 SecretRef 管理的提供商 apiKey 值会从源标记（env 引用为 ENV_VAR_NAME，file/exec 引用为 secretref-managed）刷新，而不是持久化已解析的密钥。
- 由 SecretRef 管理的提供商 header 值会从源标记（env 引用为 secretref-env:ENV_VAR_NAME，file/exec 引用为 secretref-managed）刷新。
- 空或缺失的 agent apiKey/baseUrl 会回退到 config 中的 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/env 替换）。
models.providers.*.auth：身份验证策略（api-key、token、oauth、aws-sdk）。
models.providers.*.injectNumCtxForOpenAICompat：对于 Ollama + openai-completions，将 options.num_ctx 注入请求中（默认值：true）。
models.providers.*.authHeader：在需要时强制在 Authorization 标头中传输凭据。
models.providers.*.baseUrl：上游 API 基础 URL。
models.providers.*.headers：用于代理/租户路由的额外静态标头。
models.providers.*.models：显式的提供商模型目录条目。
models.providers.*.models.*.compat.supportsDeveloperRole：可选的兼容性提示。对于具有非空非原生 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：已发现模型的回退最大输出令牌数。

提供商示例

Cerebras (GLM 4.6 / 4.7)

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

对 Cerebras 使用 cerebras/zai-glm-4.7；对 Z.AI direct 使用 zai/glm-4.7。

OpenCode

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

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

Z.AI (GLM-4.7)

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

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

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

Moonshot AI (Kimi)

{
  env: { MOONSHOT_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "moonshot/kimi-k2.5" },
      models: { "moonshot/kimi-k2.5": { alias: "Kimi K2.5" } },
    },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "kimi-k2.5",
            name: "Kimi K2.5",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 256000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

对于中国端点：baseUrl: "https://api.moonshot.cn/v1" 或 openclaw onboard --auth-choice moonshot-api-key-cn。

Kimi Coding

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

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

Synthetic (Anthropic-compatible)

{
  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: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 192000,
            maxTokens: 65536,
          },
        ],
      },
    },
  },
}

基础 URL 应省略 /v1（Anthropic 客户端会附加它）。快捷方式：openclaw onboard --auth-choice synthetic-api-key。

MiniMax M2.7 (direct)

{
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.7" },
      models: {
        "minimax/MiniMax-M2.7": { alias: "Minimax" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.7",
            name: "MiniMax M2.7",
            reasoning: true,
            input: ["text"],
            cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.12 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

设置 MINIMAX_API_KEY。快捷方式：openclaw onboard --auth-choice minimax-api。模型目录现在默认仅限 M2.7。

Local models (LM Studio)

参见 Local Models。TL;DR：在强大的硬件上通过 LM Studio Responses API 运行大型本地模型；保持托管模型合并以备回退。

Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn
    },
    entries: {
      "image-lab": {
        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 加载。
设备发现接受原生 OpenClaw 插件以及兼容的 Codex 捆绑包和 Claude 捆绑包，包括无清单的 Claude 默认布局捆绑包。
配置更改需要重启网关。
allow：可选允许列表（仅加载列出的插件）。deny 优先。
plugins.entries.<id>.apiKey：插件级 API 密钥便捷字段（当插件支持时）。
plugins.entries.<id>.env：插件作用域环境变量映射。
plugins.entries.<id>.hooks.allowPromptInjection：当 false 时，核心会拦截 before_prompt_build 并忽略来自旧版 before_agent_start 的提示突变字段，同时保留旧版 modelOverride 和 providerOverride。适用于原生插件钩子和支持的捆绑包提供的钩子目录。
plugins.entries.<id>.subagent.allowModelOverride：显式信任此插件以请求后台子代理运行的每次运行 provider 和 model 覆盖。
plugins.entries.<id>.subagent.allowedModels：受信任子代理覆盖的规范 provider/model 目标的可选允许列表。仅当您有意允许任何 WhatsApp 时才使用 "*"。
plugins.entries.<id>.config：插件定义的配置对象（如果有，由原生 OpenClaw 插件架构验证）。
启用的 Claude 捆绑包插件还可以从 settings.json 提供嵌入式 Pi 默认值；OpenClaw 将这些作为经过清理的代理设置应用，而不是作为原始 OpenClaw 配置补丁。
plugins.slots.memory：选择活动内存插件 ID，或选择 "none" 以禁用内存插件。
plugins.slots.contextEngine：选择活动上下文引擎插件 ID；除非您安装并选择另一个引擎，否则默认为 "legacy"。
plugins.installs：由 openclaw plugins update 使用的 CLI 管理安装元数据。
- 包括 source、spec、sourcePath、installPath、version、resolvedName、resolvedVersion、resolvedSpec、integrity、shasum、resolvedAt、installedAt。
- 将 plugins.installs.* 视为托管状态；优先使用 CLI 命令而非手动编辑。

参见 Plugins。

浏览器

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "user",
    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" },
      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
    // headless: false,
    // noSandbox: false,
    // extraArgs: [],
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false,
  },
}

evaluateEnabled: false 会禁用 act:evaluate 和 wait --fn。
如果未设置，ssrfPolicy.dangerouslyAllowPrivateNetwork 默认为 true（受信任网络模型）。
设置 ssrfPolicy.dangerouslyAllowPrivateNetwork: false 以实现严格的仅公开浏览器导航。
在严格模式下，远程 CDP 配置文件端点（profiles.*.cdpUrl）在可达性/发现检查期间同样受到私有网络拦截。
ssrfPolicy.allowPrivateNetwork 作为旧别名继续受支持。
在严格模式下，使用 ssrfPolicy.hostnameAllowlist 和 ssrfPolicy.allowedHostnames 来设置明确的例外。
远程配置文件仅支持附加（禁用启动/停止/重置）。
existing-session 配置文件仅限主机，并使用 Chrome MCP 而非 CDP。
existing-session 配置文件可以设置 userDataDir 来定位特定的基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。
自动检测顺序：如果是基于 Chromium 的默认浏览器 → Chrome → Brave → Edge → Chromium → Chrome Canary。
控制服务：仅限环回（端口从 gateway.port 派生，默认 18791）。
extraArgs 向本地 Chromium 启动附加额外的启动标志（例如 --disable-gpu、窗口大小调整或调试标志）。

UI

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

seamColor：本机应用 UI 铬层的强调色（Talk Mode 气泡色调等）。
assistant：控制 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"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

Gateway(网关) 字段详情

mode：local（运行 Gateway(网关)）或 remote（连接到远程 Gateway(网关)）。除非为 local，否则 Gateway(网关) 拒绝启动。
port：用于 WS + HTTP 的单个多路复用端口。优先级：--port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789。
bind：auto、loopback（默认）、lan（0.0.0.0）、tailnet（仅 Tailscale IP）或 custom。
旧版绑定别名：在 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"（或在 customBindHost: "0.0.0.0" 下设置 bind: "custom"）以在所有接口上监听。
身份验证：默认情况下是必需的。非 local loopback 绑定需要共享的令牌/密码。新手引导向导默认生成令牌。
如果同时配置了 gateway.auth.token 和 gateway.auth.password（包括 SecretRefs），请将 gateway.auth.mode 显式设置为 token 或 password。当两者都已配置但未设置模式时，启动和服务安装/修复流程将失败。
gateway.auth.mode: "none"：显式无身份验证模式。仅用于受信任的 local loopback 设置；新手引导提示有意不提供此选项。
gateway.auth.mode: "trusted-proxy"：将身份验证委托给支持身份感知的反向代理，并信任来自 gateway.trustedProxies 的身份标头（请参阅受信任的代理身份验证）。
gateway.auth.allowTailscale：当为 true 时，Tailscale Serve 身份标头可以满足控制 UI/WebSocket 身份验证（通过 tailscale whois 验证）；HTTP API 端点仍需要令牌/密码身份验证。此无令牌流程假定 Gateway(网关) 主机是受信任的。当 tailscale.mode = "serve" 时，默认为 true。
gateway.auth.rateLimit：可选的身份验证失败限制器。适用于每个客户端 IP 和每个身份验证范围（共享密钥和设备令牌独立跟踪）。被阻止的尝试返回 429 + Retry-After。
- gateway.auth.rateLimit.exemptLoopback 默认为 true；当您有意希望也对 localhost 流量进行速率限制时（对于测试设置或严格的代理部署），请设置 false。
浏览器源 WS 身份验证尝试始终受到限制，并且禁用了 local loopback 豁免（针对基于浏览器的 localhost 暴力破解的纵深防御）。
tailscale.mode：serve（仅限 tailnet，local loopback 绑定）或 funnel（公开，需要身份验证）。
controlUi.allowedOrigins：Gateway(网关) WebSocket 连接的显式浏览器源允许列表。当预期浏览器客户端来自非 local loopback 源时是必需的。
controlUi.dangerouslyAllowHostHeaderOriginFallback：危险模式，为故意依赖 Host 标头源策略的部署启用 Host 标头源回退。
remote.transport：ssh（默认）或 direct（ws/wss）。对于 direct，remote.url 必须是 ws:// 或 wss://。
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1：客户端应急覆盖，允许将纯文本 ws:// 用于受信任的专用网络 IP；对于纯文本，默认值仍仅为 local loopback。
gateway.remote.token / .password 是远程客户端凭据字段。它们本身不配置 Gateway(网关) 身份验证。
gateway.push.apns.relay.baseUrl：官方/TestFlight iOS 构建版在将支持中继的注册发布到 Gateway(网关) 后，使用的外部 APNs 中继的基本 HTTPS URL。此 URL 必须与编译到 iOS 构建版中的中继 URL 匹配。
gateway.push.apns.relay.timeoutMs：Gateway(网关) 到中继的发送超时（毫秒）。默认为 10000。
支持中继的注册被委托给特定的 Gateway(网关) 身份。配对的 iOS 应用获取 gateway.identity.get，将该身份包含在中继注册中，并将特定于注册的发送授权转发给 Gateway(网关)。另一个 Gateway(网关) 无法重用该存储的注册。
OPENCLAW_APNS_RELAY_BASE_URL / OPENCLAW_APNS_RELAY_TIMEOUT_MS：上述中继配置的临时环境覆盖。
OPENCLAW_APNS_RELAY_ALLOW_HTTP=true：仅用于开发的 local loopback HTTP 中继 URL 的应急逃生舱。生产中继 URL 应保持使用 HTTPS。
gateway.channelHealthCheckMinutes：渠道健康监控间隔（分钟）。设置 0 可全局禁用健康监控重启。默认值：5。
gateway.channelStaleEventThresholdMinutes：陈旧套接字阈值（分钟）。保持此值大于或等于 gateway.channelHealthCheckMinutes。默认值：30。
gateway.channelMaxRestartsPerHour：每个渠道/帐户在一个滚动小时内的最大健康监控重启次数。默认值：10。
`channels.

.healthMonitor.enabled`：针对健康监控重启的每个渠道退出选项，同时保持全局监控启用。

`channels.

.accounts.

.healthMonitor.enabled`：多帐户渠道的每个帐户覆盖。设置后，它优先于渠道级别的覆盖。

本地 Gateway(网关) 调用路径仅当 gateway.auth.* 未设置时，才能将 gateway.remote.* 用作回退。
如果 gateway.auth.token / gateway.auth.password 通过 SecretRef 显式配置但未解析，解析将以失败关闭（没有远程回退掩码）。
trustedProxies：终止 TLS 的反向代理 IP。仅列出您控制的代理。
allowRealIpFallback：当为 true 时，如果 X-Forwarded-For 缺失，Gateway(网关) 将接受 X-Real-IP。默认 false 以实现失败关闭行为。
gateway.tools.deny：为 HTTP POST /tools/invoke 阻止的额外工具名称（扩展默认拒绝列表）。
gateway.tools.allow：从默认 HTTP 拒绝列表中删除工具名称。

OpenAI 兼容端点

聊天补全：默认禁用。使用 gateway.http.endpoints.chatCompletions.enabled: true 启用。
响应 API：gateway.http.endpoints.responses.enabled。
响应 URL 输入加固：
- gateway.http.endpoints.responses.maxUrlParts
- gateway.http.endpoints.responses.files.urlAllowlist
- gateway.http.endpoints.responses.images.urlAllowlist 空白允许列表被视为未设置；请使用 gateway.http.endpoints.responses.files.allowUrl=false 和/或 gateway.http.endpoints.responses.images.allowUrl=false 来禁用 URL 获取。
可选的响应加固标头：
- gateway.http.securityHeaders.strictTransportSecurity （仅为您控制的 HTTPS 源设置；请参阅受信任的代理身份验证）

多实例隔离

在一个主机上运行多个网关，使用不同的端口和状态目录：

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

便捷标志：--dev （使用 ~/.openclaw-dev + 端口 19001），--profile <name> （使用 ~/.openclaw-<name>）。

请参阅多个网关。

`gateway.tls`

{
  gateway: {
    tls: {
      enabled: false,
      autoGenerate: false,
      certPath: "/etc/openclaw/tls/server.crt",
      keyPath: "/etc/openclaw/tls/server.key",
      caPath: "/etc/openclaw/tls/ca-bundle.crt",
    },
  },
}

enabled：在网关监听器上启用 TLS 终止 (HTTPS/WSS)（默认值：false）。
autoGenerate：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅供本地/开发使用。
certPath：TLS 证书文件的文件系统路径。
keyPath：TLS 私钥文件的文件系统路径；请保持权限受限。
caPath：用于客户端验证或自定义信任链的可选 CA 包路径。

`gateway.reload`

{
  gateway: {
    reload: {
      mode: "hybrid", // off | restart | hot | hybrid
      debounceMs: 500,
      deferralTimeoutMs: 300000,
    },
  },
}

mode：控制在运行时如何应用配置编辑。
- "off"：忽略实时编辑；更改需要显式重启。
- "restart"：配置更改时始终重启网关进程。
- "hot"：在进程中应用更改而无需重启。
- "hybrid" （默认值）：首先尝试热重载；如果需要则回退到重启。
debounceMs：应用配置更改前的去抖动窗口（以毫秒为单位）（非负整数）。
deferralTimeoutMs：在强制重启前等待进行中操作的最长时间（单位：毫秒）（默认：300000 = 5 分钟）。

钩子（Hooks）

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

认证：Authorization: Bearer <token> 或 x-openclaw-token: <token>。

端点：

POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
- 仅当 hooks.allowRequestSessionKey=true 时，才接受请求负载中的 sessionKey（默认：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: "[email protected]",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      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"（默认值）。
非环回绑定：画布路由需要 Gateway(网关) 认证（令牌/密码/受信任代理），与其他 Gateway(网关) HTTP 表面相同。
Node WebViews 通常不发送认证头；在节点配对并连接后，Gateway(网关) 会通告用于画布/A2UI 访问的节点范围功能 URL。
功能 URL 绑定到活动的节点 WS 会话并很快过期。不使用基于 IP 的回退。
将实时重载客户端注入到提供的 HTML 中。
为空时自动创建初始 index.html。
同时也在 /__openclaw__/a2ui/ 提供 A2UI 服务。
更改需要重启网关。
对于大型目录或 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 分离 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 Credential Surface
secrets apply 目标支持 openclaw.json 凭证路径。
auth-profiles.json 引用包含在运行时解析和审计覆盖中。

Secret 提供商配置

{
  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 显式传递所需的变量。
Secret 引用在激活时解析为内存快照，然后请求路径仅读取该快照。
激活期间应用活动界面过滤：已启用界面上未解析的引用会导致启动/重新加载失败，而非活动界面则会被跳过并输出诊断信息。

Auth 存储

{
  auth: {
    profiles: {
      "anthropic:[email protected]": { provider: "anthropic", mode: "oauth", email: "[email protected]" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
    },
    order: {
      anthropic: ["anthropic:[email protected]", "anthropic:work"],
    },
  },
}

每个代理的配置文件存储在 <agentDir>/auth-profiles.json。
auth-profiles.json 支持值级引用（keyRef 对应 api_key，tokenRef 对应 token）用于静态凭证模式。
OAuth 模式配置文件（auth.profiles.<id>.mode = "oauth"）不支持由 SecretRef 支持的 auth-profile 凭证。
静态运行时凭证来自内存解析的快照；旧的静态 auth.json 条目在发现时会被清除。
从 ~/.openclaw/credentials/oauth.json 导入的旧版 OAuth。
请参阅 OAuth。
Secrets 运行时行为和 audit/configure/apply 工具：Secrets 管理。

`auth.cooldowns`

{
  auth: {
    cooldowns: {
      billingBackoffHours: 5,
      billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },
      billingMaxHours: 24,
      failureWindowHours: 24,
      overloadedProfileRotations: 1,
      overloadedBackoffMs: 0,
      rateLimitedProfileRotations: 1,
    },
  },
}

billingBackoffHours：当配置文件因计费/余额不足而失败时，以小时为单位的基准退避时间（默认：5）。
billingBackoffHoursByProvider：可选的针对每个提供商的计费退避小时数覆盖。
billingMaxHours：计费退避指数增长的上限（小时）（默认：24）。
failureWindowHours：用于退避计数器的滚动窗口（小时）（默认：24）。
overloadedProfileRotations：在切换到模型回退之前，针对过载错误的最大同一提供商 auth-profile 轮换次数（默认：1）。
overloadedBackoffMs：在重试过载的提供商/配置文件轮换之前的固定延迟（默认：0）。
rateLimitedProfileRotations：在切换到模型回退之前，针对速率限制错误的最大同一提供商 auth-profile 轮换次数（默认：1）。

日志记录

{
  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。
maxFileBytes: 停止写入前的最大日志文件大小（以字节为单位；正整数；默认值：524288000 = 500 MB）。生产环境部署请使用外部日志轮转。

诊断

{
  diagnostics: {
    enabled: true,
    flags: ["telegram.*"],
    stuckSessionWarnMs: 30000,

    otel: {
      enabled: false,
      endpoint: "https://otel-collector.example.com:4318",
      protocol: "http/protobuf", // http/protobuf | grpc
      headers: { "x-tenant-id": "my-org" },
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: false,
      sampleRate: 1.0,
      flushIntervalMs: 5000,
    },

    cacheTrace: {
      enabled: false,
      includeMessages: true,
      includePrompt: true,
      includeSystem: true,
    },
  },
}

enabled: 检测输出的主控开关（默认值：true）。
flags: 用于启用定向日志输出的标志字符串数组（支持如 "telegram.*" 或 "*" 的通配符）。
stuckSessionWarnMs: 当会话保持处理状态时，发出卡滞会话警告的时间阈值（毫秒）。
otel.enabled: 启用 OpenTelemetry 导出管道（默认值：false）。
otel.endpoint: OTel 导出的收集器 URL。
otel.protocol: "http/protobuf"（默认值）或 "grpc"。
otel.headers: 随 OTel 导出请求发送的额外 HTTP/gRPC 元数据标头。
otel.serviceName: 资源属性的服务名称。
otel.traces / otel.metrics / otel.logs: 启用链路追踪、指标或日志导出。
otel.sampleRate: 链路追踪采样率 0–1。
otel.flushIntervalMs: 定期遥测刷新间隔（毫秒）。
cacheTrace.enabled: 记录嵌入式运行的缓存追踪快照（默认值：false）。
cacheTrace.includeMessages / includePrompt / includeSystem: 控制缓存追踪输出中包含的内容（均默认为：true）。

更新

{
  update: {
    channel: "stable", // stable | beta | dev
    checkOnStart: true,

    auto: {
      enabled: false,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}

channel: npm/git 安装的发布渠道 — "stable"、"beta" 或 "dev"。
checkOnStart: 网关启动时检查 npm 更新（默认值：true）。
auto.enabled：为软件包安装启用后台自动更新（默认：false）。
auto.stableDelayHours：stable 渠道自动应用前的最小延迟小时数（默认：6；最大值：168）。
auto.stableJitterHours：额外的 stable 渠道分发布展窗口小时数（默认：12；最大值：168）。
auto.betaCheckIntervalHours：beta 渠道检查运行频率小时数（默认：1；最大值：24）。

ACP

{
  acp: {
    enabled: false,
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "main",
    allowedAgents: ["main", "ops"],
    maxConcurrentSessions: 10,

    stream: {
      coalesceIdleMs: 50,
      maxChunkChars: 1000,
      repeatSuppression: true,
      deliveryMode: "live", // live | final_only
      hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph
      maxOutputChars: 50000,
      maxSessionUpdateChars: 500,
    },

    runtime: {
      ttlMinutes: 30,
    },
  },
}

enabled：全局 ACP 功能开关（默认：false）。
dispatch.enabled：ACP 会话轮次调度的独立开关（默认：true）。设置为 false 可在阻止执行的同时保持 ACP 命令可用。
backend：默认 ACP 运行时后端 ID（必须与已注册的 ACP 运行时插件匹配）。
defaultAgent：当生成（spawn）未指定明确目标时的 ACP 目标代理 ID 回退值。
allowedAgents：允许用于 ACP 运行时会话的代理 ID 白名单；留空表示无额外限制。
maxConcurrentSessions：最大并发活动 ACP 会话数。
stream.coalesceIdleMs：流式文本的空闲刷新窗口（毫秒）。
stream.maxChunkChars：分割流式块投影前的最大块大小。
stream.repeatSuppression：抑制每轮中重复的状态/工具行（默认：true）。
stream.deliveryMode："live" 增量流式传输；"final_only" 缓冲直到轮次终止事件。
stream.hiddenBoundarySeparator：隐藏工具事件后可见文本之前的分隔符（默认："paragraph"）。
stream.maxOutputChars：每个 ACP 轮次投影的最大助手输出字符数。
stream.maxSessionUpdateChars：投影 ACP 状态/更新行的最大字符数。
runtime.ttlMinutes：ACP 会话工作进程在符合清理条件前的空闲 TTL（分钟）。

CLI

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

cli.banner.taglineMode 控制横幅标语样式：
- "random"（默认）：轮换的有趣/季节性标语。
- "default"：固定的中性标语（All your chats, one OpenClaw.）。
- "off"：无标语文本（仍显示横幅标题/版本）。
要隐藏整个横幅（不仅仅是标语），请设置环境变量 OPENCLAW_HIDE_BANNER=1。

向导

由 CLI 引导式设置流程写入的元数据（onboard、configure、doctor）：

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

身份

请参阅 Agent 默认值下的 agents.list 身份字段。

Bridge（已弃用，已移除）

当前版本不再包含 TCP 网桥。节点通过 Gateway(网关) WebSocket 连接。bridge.* 键不再属于配置架构的一部分（验证失败直到被移除；openclaw doctor --fix 可以去除未知键）。

Legacy bridge config (historical reference)

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

Cron

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

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

`cron.retry`

{
  cron: {
    retry: {
      maxAttempts: 3,
      backoffMs: [30000, 60000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],
    },
  },
}

maxAttempts：一次性作业在瞬时错误时的最大重试次数（默认：3；范围：0–10）。
backoffMs：每次重试尝试的退避延迟（毫秒）数组（默认：[30000, 60000, 300000]；1–10 个条目）。
retryOn：触发重试的错误类型 — "rate_limit"、"overloaded"、"network"、"timeout"、"server_error"。省略以重试所有瞬时类型。

仅适用于一次性 cron 作业。周期性作业使用单独的失败处理机制。

`cron.failureAlert`

{
  cron: {
    failureAlert: {
      enabled: false,
      after: 3,
      cooldownMs: 3600000,
      mode: "announce",
      accountId: "main",
    },
  },
}

enabled：为 cron 作业启用失败告警（默认：false）。
after：触发告警前的连续失败次数（正整数，最小值：1）。
cooldownMs：针对同一作业的重复告警之间的最小毫秒数（非负整数）。
mode：传递模式 — "announce" 通过渠道消息发送；"webhook" 发送到配置的 webhook。
accountId：用于限定告警传递范围的可选账号或渠道 ID。

请参阅 Cron 作业。隔离的 cron 执行被作为后台任务进行跟踪。

媒体模型模板变量

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

变量	描述
`{{Body}}`	完整的入站消息正文
`{{RawBody}}`	原始正文（无历史记录/发送者包装器）
`{{BodyStripped}}`	已去除群组提及的正文
`{{From}}`	发送者标识符
`{{To}}`	目标标识符
`{{MessageSid}}`	频道消息 ID
`{{SessionId}}`	当前会话 UUID
`{{IsNewSession}}`	创建新会话时的 `"true"`
`{{MediaUrl}}`	入站媒体伪 URL
`{{MediaPath}}`	本地媒体路径
`{{MediaType}}`	媒体类型（图片/音频/文档/……）
`{{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 层深。
路径：相对于包含的文件解析，但必须保持在顶层配置目录内（dirname 的 openclaw.json）。仅当绝对路径或 ../ 形式仍解析在该边界内时才允许使用。
错误：针对文件缺失、解析错误和循环包含提供明确的错误信息。

相关：配置 · 配置示例 · 诊断工具

配置参考

配置参考

渠道

私聊和群组访问

渠道模型覆盖

渠道默认值和心跳

WhatsApp

Telegram

Discord

Google Chat

Slack

Mattermost

Signal

BlueBubbles

iMessage

Matrix

Microsoft Teams

IRC

多账号（所有渠道）

其他扩展渠道

群聊提及控制

私信历史记录限制

自聊模式

指令（聊天指令处理）

Agent defaults

agents.defaults.workspace

agents.defaults.repoRoot

agents.defaults.skipBootstrap

agents.defaults.bootstrapMaxChars

agents.defaults.bootstrapTotalMaxChars

agents.defaults.bootstrapPromptTruncationWarning

agents.defaults.imageMaxDimensionPx

agents.defaults.userTimezone

agents.defaults.timeFormat

agents.defaults.model

agents.defaults.cliBackends

agents.defaults.heartbeat

agents.defaults.compaction

agents.defaults.contextPruning

分块流式传输

正在输入指示器

agents.defaults.sandbox

agents.list（每个代理的覆盖设置）

多代理路由

绑定匹配字段

每个代理的访问配置文件

会话

消息

响应前缀

确认反应

入站防抖

TTS（文本转语音）

Talk

工具

工具配置

工具组

tools.allow / tools.deny

tools.byProvider

tools.elevated

tools.exec

tools.loopDetection

tools.web

tools.media

tools.agentToAgent

tools.sessions

tools.sessions_spawn

agents.defaults.subagents

自定义提供商和基础 URL

提供商字段详情

提供商示例

Skills

插件

浏览器

UI

Gateway(网关)

OpenAI 兼容端点

多实例隔离

gateway.tls

gateway.reload

钩子（Hooks）

`agents.defaults.workspace`

`agents.defaults.repoRoot`

`agents.defaults.skipBootstrap`

`agents.defaults.bootstrapMaxChars`

`agents.defaults.bootstrapTotalMaxChars`

`agents.defaults.bootstrapPromptTruncationWarning`

`agents.defaults.imageMaxDimensionPx`

`agents.defaults.userTimezone`

`agents.defaults.timeFormat`

`agents.defaults.model`

`agents.defaults.cliBackends`

`agents.defaults.heartbeat`

`agents.defaults.compaction`

`agents.defaults.contextPruning`

`agents.defaults.sandbox`

`agents.list`（每个代理的覆盖设置）

`tools.allow` / `tools.deny`

`tools.byProvider`

`tools.elevated`

`tools.exec`

`tools.loopDetection`

`tools.web`

`tools.media`

`tools.agentToAgent`

`tools.sessions`

`tools.sessions_spawn`

`agents.defaults.subagents`

`gateway.tls`

`gateway.reload`

`env`（内联环境变量）

`SecretRef`

`auth.cooldowns`

`cron.retry`

`cron.failureAlert`

配置包含 (`$include`)