vultr/openclaw

Fork 0

mirror of https://github.com/openclaw/openclaw.git synced 2026-03-20 22:40:58 +00:00

Files

Peter Steinberger 00ef214d59 docs: regenerate zh-CN onboarding references

2026-03-16 07:03:19 +00:00

111 KiB

Raw Blame History

description, read_when, summary, title, x-i18n

description

read_when

summary

title

x-i18n

Complete field-by-field reference for ~/.openclaw/openclaw.json

你需要精确到字段级别的配置语义或默认值

你正在验证渠道、模型、Gateway 网关或工具配置块

每个 OpenClaw 配置键、默认值和渠道设置的完整参考

配置参考

generated_at	model	provider	source_hash	source_path	workflow
2026-03-16T06:27:43Z	gpt-5.4	openai	c2926153fa94bbb3141ac7cd9ebfa381394c9c9ad7a1cf1d21fb91c879905d51	gateway/configuration-reference.md	15

配置参考

~/.openclaw/openclaw.json 中所有可用字段。若需面向任务的概览，请参见 Configuration。

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

渠道

只要某个渠道的配置节存在，它就会自动启动（除非设置了 enabled: false）。

私信和群组访问

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

DM policy	Behavior
`pairing`（默认）	未知发送者会收到一次性配对码；所有者必须批准
`allowlist`	仅 `allowFrom` 中的发送者（或已配对的允许列表存储）
`open`	允许所有入站私信（要求 `allowFrom: ["*"]`）
`disabled`	忽略所有入站私信

Group policy	Behavior
`allowlist`（默认）	仅允许匹配已配置 allowlist 的群组
`open`	绕过群组 allowlist（仍会应用提及门控）
`disabled`	阻止所有群组/房间消息

`channels.defaults.groupPolicy` 会在某个提供商的 `groupPolicy` 未设置时作为默认值。配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多 **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, // 蓝色双勾（自聊模式下为 false）
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

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

出站命令默认使用账户 default（若存在）；否则使用第一个已配置的账户 ID（排序后）。
可选的 channels.whatsapp.defaultAccount 会在其与某个已配置账户 ID 匹配时，覆盖该回退默认账户选择。
旧版单账户 Baileys 认证目录会由 openclaw doctor 迁移到 whatsapp/default。
按账户覆盖：channels.whatsapp.accounts.<id>.sendReadReceipts、channels.whatsapp.accounts.<id>.dmPolicy、channels.whatsapp.accounts.<id>.allowFrom。

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress（默认：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",
    },
  },
}

机器人令牌：channels.telegram.botToken 或 channels.telegram.tokenFile（仅常规文件；拒绝符号链接），默认账户还可回退到 TELEGRAM_BOT_TOKEN。
可选的 channels.telegram.defaultAccount 会在其与某个已配置账户 ID 匹配时覆盖默认账户选择。
在多账户设置（2 个及以上账户 ID）中，请设置显式默认值（channels.telegram.defaultAccount 或 channels.telegram.accounts.default），以避免回退路由；如果缺失或无效，openclaw doctor 会发出警告。
configWrites: false 会阻止 Telegram 发起的配置写入（超级群组 ID 迁移、/config set|unset）。
顶层 bindings[] 中 type: "acp" 的条目会为论坛话题配置持久化 ACP 绑定（在 match.peer.id 中使用规范形式 chatId:topic:topicId）。字段语义与 ACP Agents 共享。
Telegram 流式预览使用 sendMessage + editMessageText（适用于私聊和群聊）。
重试策略：参见 Retry policy。

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress（在 Discord 上 progress 映射为 partial）
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // 为 `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 为小写且空格替换为 -；频道键使用 slug 化名称（不含 #）。优先使用 guild ID。
默认会忽略机器人自己发出的消息。allowBots: true 可启用；使用 allowBots: "mentions" 可仅接受提及该机器人的机器人消息（仍会过滤自己的消息）。
channels.discord.guilds.<id>.ignoreOtherMentions（及频道级覆盖）会丢弃那些提及了其他用户或角色但未提及机器人的消息（不含 @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 Agents 共享。
channels.discord.ui.components.accentColor 设置 Discord components v2 容器的强调色。
channels.discord.voice 启用 Discord 语音频道对话，以及可选的自动加入 + TTS 覆盖。
channels.discord.voice.daveEncryption 和 channels.discord.voice.decryptionFailureTolerance 会透传给 @discordjs/voice 的 DAVE 选项（默认分别为 true 和 24）。
在重复解密失败后，OpenClaw 还会尝试通过离开/重新加入语音会话来恢复语音接收。
channels.discord.streaming 是规范的流式模式键。旧版 streamMode 和布尔型 streaming 值会自动迁移。
channels.discord.autoPresence 将运行时可用性映射为机器人状态（健康 => online，降级 => idle，耗尽 => dnd），并允许可选的状态文本覆盖。
channels.discord.dangerouslyAllowNameMatching 会重新启用可变名称/tag 匹配（紧急兼容模式）。

反应通知模式：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（预览模式）
      nativeStreaming: true, // 当 streaming=partial 时使用 Slack 原生流式 API
      mediaMaxMb: 20,
    },
  },
}

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

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

线程会话隔离：thread.historyScope 可设为按线程（默认）或在频道内共享。thread.inheritParent 会将父频道记录复制到新线程。

typingReaction 会在回复运行期间，为入站 Slack 消息添加一个临时反应，并在完成后移除。请使用 Slack emoji 短代码，例如 "hourglass_flowing_sand"。

Action group	Default	Notes
reactions	已启用	添加反应 + 列出反应
messages	已启用	读取/发送/编辑/删除
pins	已启用	置顶/取消置顶/列出
memberInfo	已启用	成员信息
emojiList	已启用	自定义 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, // 选择性启用
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // 为反向代理/公共部署提供可选的显式 URL
        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 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", // 可选账户绑定
      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、群组控制和高级操作：
      // 见 /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 DB 具有 Full Disk Access。
优先使用 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、团队/频道策略：
      // 见 /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: "bot@example.com",
      },
    },
  },
}

此处涵盖的核心键路径：channels.irc、channels.irc.dmPolicy、channels.irc.configWrites、channels.irc.nickserv.*。
可选的 channels.irc.defaultAccount 会在其与某个已配置账户 ID 匹配时覆盖默认账户选择。
完整的 IRC 渠道配置（主机/端口/TLS/频道/allowlist/提及门控）见 IRC。

多账户（所有渠道）

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

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

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

其他扩展渠道

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

群聊提及门控

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

提及类型：

元数据提及：平台原生 @ 提及。在 WhatsApp 自聊模式中会被忽略。
文本模式：位于 agents.list[].groupChat.mentionPatterns 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。
只有在可以检测提及的情况下（原生提及或至少一个模式），才会强制执行提及门控。

{
  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", // 在支持时注册原生命令
    text: true, // 解析聊天消息中的 /commands
    bash: false, // 允许 !（别名：/bash）
    bashForegroundMs: 2000,
    config: false, // 允许 /config
    debug: false, // 允许 /debug
    restart: false, // 允许 /restart + gateway restart 工具
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

文本命令必须是以 / 开头的独立消息。
native: "auto" 会为 Discord/Telegram 打开原生命令，而让 Slack 保持关闭。
可按渠道覆盖：channels.discord.commands.native（布尔值或 "auto"）。false 会清除先前已注册的命令。
channels.telegram.customCommands 可添加额外的 Telegram 机器人菜单项。
bash: true 会为主机 shell 启用 ! <cmd>。要求 tools.elevated.enabled 已启用，且发送者在 tools.elevated.allowFrom.<channel> 中。
config: true 启用 /config（读取/写入 openclaw.json）。对于 gateway chat.send 客户端，持久化的 /config set|unset 写入还要求 operator.admin；只读的 /config show 对普通写作用域 operator 客户端仍然可用。
channels.<provider>.configWrites 按渠道控制配置变更（默认：true）。
对多账户渠道，channels.<provider>.accounts.<id>.configWrites 也会控制针对该账户的写入（例如 /allowlist --config --account <id> 或 /config set channels.<provider>.accounts.<id>...）。
allowFrom 是按提供商配置的。设置后，它将成为唯一的授权来源（渠道 allowlist/配对和 useAccessGroups 都会被忽略）。
当 allowFrom 未设置时，useAccessGroups: false 允许命令绕过访问组策略。

智能体默认值

`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）。如果省略 provider，OpenClaw 会假定为 anthropic（已弃用）。
models：为 /model 配置的模型目录和 allowlist。每项可包含 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 中时适用）：

Alias	Model
`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 模式，除非你设置 --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 模型在未显式设置 thinking 级别时，默认使用 adaptive thinking。

`agents.defaults.cliBackends`

文本专用回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，可作为备份。

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

CLI 后端以文本为主；工具始终禁用。
设置了 sessionArg 时支持会话。
当 imageArg 接受文件路径时，支持图像透传。

`agents.defaults.heartbeat`

周期性心跳运行。

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m 表示禁用
        model: "openai/gpt-5.2-mini",
        includeReasoning: false,
        lightContext: false, // 默认：false；true 仅保留工作区引导文件中的 HEARTBEAT.md
        isolatedSession: false, // 默认：false；true 表示每次心跳都在全新会话中运行（无对话历史）
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow（默认）| block
        target: "none", // 默认：none | 可选：last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
      },
    },
  },
}

every：时长字符串（ms/s/m/h）。默认：30m。
suppressToolErrorWarnings：为 true 时，在心跳运行期间抑制工具错误警告负载。
directPolicy：直接/私信投递策略。allow（默认）允许直接目标投递。block 会抑制直接目标投递，并发出 reason=dm-blocked。
lightContext：为 true 时，心跳运行使用轻量引导上下文，并且只保留工作区引导文件中的 HEARTBEAT.md。
isolatedSession：为 true 时，每次心跳都会在无先前对话历史的全新会话中运行。与 cron sessionTarget: "isolated" 使用相同的隔离模式。可将每次心跳的 token 成本从约 100K 降到约 2-5K。
按智能体设置：使用 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.", // 当 identifierPolicy=custom 时使用
        postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入
        model: "openrouter/anthropic/claude-sonnet-4-5", // 可选，仅用于压缩的模型覆盖
        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", // 时长（ms/s/m/h），默认单位：分钟
        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 数。
如果 assistant 消息少于 keepLastAssistants，则跳过裁剪。

行为细节见 Session Pruning。

分块流式传输

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off | natural | custom（使用 minMs/maxMs）
    },
  },
}

非 Telegram 渠道需要显式设置 *.blockStreaming: true 才会启用分块回复。
渠道覆盖：channels.<channel>.blockStreamingCoalesce（以及按账户变体）。Signal/Slack/Discord/Google Chat 默认 minChars: 1500。
humanDelay：分块回复之间的随机暂停。natural = 800–2500 ms。按智能体覆盖：agents.list[].humanDelay。

行为和分块细节见 Streaming。

输入指示器

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

默认值：私聊/被提及时为 instant，未提及的群聊中为 message。
按会话覆盖：session.typingMode、session.typingIntervalSeconds。

见 Typing Indicators。

`agents.defaults.sandbox`

嵌入式智能体的可选沙箱隔离。完整指南见沙箱隔离。

{
  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",
          // 也支持 SecretRef / 内联内容：
          // 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：内联内容或 SecretRef，OpenClaw 会在运行时将其物化为临时文件
strictHostKeyChecking / updateHostKeys：OpenSSH 主机密钥策略开关

SSH 认证优先级：

identityData 优先于 identityFile
certificateData 优先于 certificateFile
knownHostsData 优先于 knownHostsFile
由 SecretRef 支持的 *Data 值会在沙箱会话启动前，从活动 secrets 运行时快照中解析

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", // 可选
          gatewayEndpoint: "https://lab.example", // 可选
          policy: "strict", // 可选的 OpenShell policy id
          providers: ["openai"], // 可选
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

OpenShell 模式：

mirror：执行前从本地为远程植入种子，执行后同步回本地；本地工作区保持为规范副本
remote：在创建沙箱时只为远程植入一次种子，之后保持远程工作区为规范副本

在 remote 模式下，在 OpenClaw 外部对主机本地所做的编辑，不会在种子步骤后自动同步进沙箱。传输层是通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期以及可选的镜像同步。

setupCommand 会在容器创建后运行一次（通过 sh -lc）。需要网络出口、可写根文件系统以及 root 用户。

容器默认使用 network: "none" ——如果智能体需要出站访问，请设为 "bridge"（或自定义 bridge 网络）。默认会阻止 "host"。除非你显式设置 sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true（紧急模式），否则默认也会阻止 "container:<id>"。

入站附件 会暂存到活动工作区中的 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 网络）。仅当你明确需要全局 bridge 连接时，才设为 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 默认启用，如果 WebGL/3D 使用场景需要，可通过 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 禁用这些标志。
- OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 会重新启用扩展，如果你的工作流依赖它们。
- --renderer-process-limit=2 可通过 OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> 更改；设为 0 将使用 Chromium 的默认进程上限。
- 若启用了 noSandbox，还会额外加上 --no-sandbox 和 --disable-setuid-sandbox。
- 默认值是容器镜像的基线；若要更改容器默认值，请使用自定义浏览器镜像及自定义 entrypoint。

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

构建镜像：

scripts/sandbox-setup.sh           # 主沙箱镜像
scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像

`agents.list`（按智能体覆盖）

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

id：稳定的智能体 ID（必填）。
default：若设置了多个，则第一个生效（会记录警告）。若一个都未设，则列表第一项为默认。
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 会派生默认值：从 emoji 派生 ackReaction，从 name/emoji 派生 mentionPatterns。
subagents.allowAgents：sessions_spawn 的智能体 ID allowlist（["*"] = 任意；默认：仅同一智能体）。
沙箱继承保护：若请求方会话处于沙箱中，sessions_spawn 会拒绝那些将以非沙箱方式运行的目标。

多智能体路由

在一个 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）解析，不使用上述 route 绑定层级顺序。

按智能体的访问配置

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

优先级细节见 Multi-Agent Sandbox & Tools。

会话

{
  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, // 超过此 token 数则跳过父线程 fork（0 表示禁用）
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // 时长或 false
      maxDiskBytes: "500mb", // 可选硬预算
      highWaterBytes: "400mb", // 可选清理目标
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // 默认不活动自动取消聚焦时长（小时，`0` 表示禁用）
      maxAgeHours: 0, // 默认硬性最大年龄（小时，`0` 表示禁用）
    },
    mainKey: "main", // 旧字段（运行时始终使用 "main"）
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

dmScope：私信如何分组。
- main：所有私信共享主会话。
- per-peer：按发送者 ID 跨渠道隔离。
- per-channel-peer：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
- per-account-channel-peer：按账户 + 渠道 + 发送者隔离（推荐用于多账户）。
identityLinks：将规范 ID 映射到带提供商前缀的 peer，用于跨渠道共享会话。
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: "🦞", // 或 "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 表示禁用
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

回复前缀

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

解析顺序（最具体者优先）：账户 → 渠道 → 全局。"" 会禁用并停止级联。"auto" 会派生为 [{identity.name}]。

模板变量：

Variable	Description	Example
`{model}`	短模型名	`claude-opus-4-6`
`{modelFull}`	完整模型标识符	`anthropic/claude-opus-4-6`
`{provider}`	提供商名称	`anthropic`
`{thinkingLevel}`	当前 thinking 级别	`high`、`low`、`off`
`{identity.name}`	智能体身份名称	（与 `"auto"` 相同）

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

确认反应

默认取活动智能体的 identity.emoji，否则为 "👀"。设为 "" 可禁用。
按渠道覆盖：channels.<channel>.ackReaction、channels.<channel>.accounts.<id>.ackReaction。
解析顺序：账户 → 渠道 → messages.ackReaction → identity 回退。
作用域：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 密钥回退到 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 对象。
仅在未配置 Talk API key 时，才会回退到 ELEVENLABS_API_KEY。
voiceAliases 让 Talk 指令可以使用友好的名称。
silenceTimeoutMs 控制 Talk 模式在用户停止说话后等待多久才发送转录。未设置时使用平台默认暂停窗口（macOS 和 Android 上为 700 ms，iOS 上为 900 ms）。

工具

工具配置文件

tools.profile 会在 tools.allow/tools.deny 之前设置基础 allowlist：

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

Profile	Includes
`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	Tools
`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`

全局工具 allow/deny 策略（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", // 或 BRAVE_API_KEY 环境变量
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        userAgent: "custom-ua",
      },
    },
  },
}

`tools.media`

配置入站媒体理解（图像/音频/视频）：

{
  tools: {
    media: {
      concurrency: 2,
      audio: {
        enabled: true,
        maxBytes: 20971520,
        scope: {
          default: "deny",
          rules: [{ action: "allow", match: { chatType: "direct" } }],
        },
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
        ],
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

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

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

CLI 条目（type: "cli"）：

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

通用字段：

capabilities：可选列表（image、audio、video）。默认值：openai/anthropic/minimax → 图像，google → 图像+音频+视频，groq → 音频。
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, // 选择性启用：设为 true 以允许内联文件附件
        maxTotalBytes: 5242880, // 所有文件合计 5 MB
        maxFiles: 50,
        maxFileBytes: 1048576, // 每个文件 1 MB
        retainOnSessionKeep: false, // 当 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（默认）| 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）覆盖智能体配置根目录。
对匹配的 provider ID，合并优先级如下：
- 非空的智能体 models.json baseUrl 优先。
- 非空的智能体 apiKey 仅在该提供商未由当前配置/auth-profile 上下文中的 SecretRef 管理时优先。
- 由 SecretRef 管理的提供商 apiKey 会从源标记（环境变量引用为 ENV_VAR_NAME，file/exec 引用为 secretref-managed）刷新，而不是持久化已解析的密钥。
- 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用为 secretref-env: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：用于代理/租户路由的额外静态 header。
models.providers.*.models：显式的提供商模型目录条目。
models.providers.*.models.*.compat.supportsDeveloperRole：可选的兼容性提示。对 api: "openai-completions" 且非空、非原生 baseUrl（主机不是 api.openai.com）的情况，OpenClaw 会在运行时将其强制设为 false。空或省略的 baseUrl 会保留默认 OpenAI 行为。
models.bedrockDiscovery：Bedrock 自动发现设置根。
models.bedrockDiscovery.enabled：开启/关闭发现轮询。
models.bedrockDiscovery.region：发现使用的 AWS 区域。
models.bedrockDiscovery.providerFilter：用于定向发现的可选 provider-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 目录使用 opencode/... 引用，Go 目录使用 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: true,
            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: true,
            input: ["text"],
            cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

设置 MINIMAX_API_KEY。快捷方式：openclaw onboard --auth-choice minimax-api。

参见 Local Models。简而言之：在强劲硬件上通过 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" }, // 或明文字符串
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

allowBundled：仅针对捆绑 Skills 的可选 allowlist（托管/工作区 Skills 不受影响）。
entries.<skillKey>.enabled: false：即使某个技能已捆绑/已安装，也会禁用它。
entries.<skillKey>.apiKey：针对声明主环境变量的技能提供的便捷字段（明文字符串或 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 bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。
配置更改需要重启 Gateway 网关。
allow：可选 allowlist（仅加载列出的插件）。deny 优先。
plugins.entries.<id>.apiKey：插件级 API key 便捷字段（插件支持时）。
plugins.entries.<id>.env：插件作用域环境变量映射。
plugins.entries.<id>.hooks.allowPromptInjection：为 false 时，核心会阻止 before_prompt_build，并忽略旧版 before_agent_start 中会修改 prompt 的字段，同时保留旧版 modelOverride 和 providerOverride。适用于原生插件 hook 以及受支持 bundle 提供的 hook 目录。
plugins.entries.<id>.config：插件定义的配置对象（如有可用原生 OpenClaw 插件 schema，则会校验）。
已启用的 Claude bundle 插件也可以从 settings.json 提供嵌入式 Pi 默认值；OpenClaw 会将其作为净化后的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。
plugins.slots.memory：选择活动记忆插件 ID，或设为 "none" 以禁用记忆插件。
plugins.slots.contextEngine：选择活动上下文引擎插件 ID；默认是 "legacy"，除非你安装并选择了其他引擎。
plugins.installs：由 CLI 管理的安装元数据，供 openclaw plugins update 使用。
- 包括 source、spec、sourcePath、installPath、version、resolvedName、resolvedVersion、resolvedSpec、integrity、shasum、resolvedAt、installedAt。
- 请将 plugins.installs.* 视为托管状态；优先使用 CLI 命令，而不是手动编辑。

见 Plugins。

浏览器

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "user",
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // 默认可信网络模式
      // allowPrivateNetwork: true, // 旧别名
      // 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", // 仅在扩展 relay 需要跨命名空间可达时（例如 WSL2）
    // 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 显式放行例外。
远程配置文件为仅附加模式（禁止启动/停止/重置）。
自动检测顺序：默认浏览器如果是基于 Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary。
控制服务：仅 loopback（端口由 gateway.port 派生，默认 18791）。
extraArgs 会向本地 Chromium 启动追加额外标志（例如 --disable-gpu、窗口大小设置或调试标志）。
relayBindHost 更改 Chrome 扩展 relay 的监听地址。若只需 loopback 访问请保持未设置；仅当 relay 必须跨命名空间边界可达（例如 WSL2）且主机网络已受信任时，才显式设置为非 loopback 地址，例如 0.0.0.0。

UI

{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // emoji、短文本、图片 URL 或 data URI
    },
  },
}

seamColor：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。
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", // 或 OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；见 /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"], // 非 loopback Control UI 必需
      // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host-header origin 回退模式
      // 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"],
    // 可选。默认 false。
    allowRealIpFallback: false,
    tools: {
      // 额外的 /tools/invoke HTTP deny
      deny: ["browser"],
      // 从默认 HTTP deny 列表中移除工具
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

mode：local（运行网关）或 remote（连接远程网关）。除非为 local，否则 Gateway 网关拒绝启动。
port：用于 WS + HTTP 的单一复用端口。优先级：--port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789。
bind：auto、loopback（默认）、lan（0.0.0.0）、tailnet（仅 Tailscale IP）或 custom。
旧版 bind 别名：请在 gateway.bind 中使用 bind 模式值（auto、loopback、lan、tailnet、custom），不要使用主机别名（0.0.0.0、127.0.0.1、localhost、::、::1）。
Docker 说明：默认的 loopback bind 在容器内监听 127.0.0.1。在 Docker bridge 网络（-p 18789:18789）下，流量从 eth0 进入，因此网关不可达。请使用 --network host，或设置 bind: "lan"（或 bind: "custom" 并配合 customBindHost: "0.0.0.0"）以监听所有接口。
认证：默认要求认证。非 loopback bind 需要共享 token/password。新手引导默认会生成一个 token。
如果同时配置了 gateway.auth.token 和 gateway.auth.password（包括 SecretRef），请显式设置 gateway.auth.mode 为 token 或 password。如果两者都已配置但 mode 未设置，启动和服务安装/修复流程都会失败。
gateway.auth.mode: "none"：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中故意不提供此选项。
gateway.auth.mode: "trusted-proxy"：将认证委托给具备身份感知能力的反向代理，并信任来自 gateway.trustedProxies 的身份头（见 Trusted Proxy Auth）。
gateway.auth.allowTailscale：为 true 时，Tailscale Serve 身份头可满足 Control UI/WebSocket 认证（通过 tailscale whois 验证）；HTTP API 端点仍要求 token/password 认证。这种无 token 流程假定网关主机是受信任的。当 tailscale.mode = "serve" 时默认值为 true。
gateway.auth.rateLimit：可选的认证失败限流器。按客户端 IP 和认证范围生效（共享密钥和设备 token 分别跟踪）。被阻止的尝试返回 429 + Retry-After。
- gateway.auth.rateLimit.exemptLoopback 默认值为 true；当你有意希望 localhost 流量也受限流时（用于测试设置或严格代理部署），请设为 false。
来自浏览器 origin 的 WS 认证尝试始终会在禁用 loopback 豁免的情况下限流（作为对基于浏览器的 localhost 暴力破解的纵深防御）。
tailscale.mode：serve（仅 tailnet，loopback bind）或 funnel（公开，需要认证）。
controlUi.allowedOrigins：用于 Gateway 网关 WebSocket 连接的显式浏览器 origin allowlist。当浏览器客户端预期来自非 loopback origin 时必须设置。
controlUi.dangerouslyAllowHostHeaderOriginFallback：危险模式，为那些刻意依赖 Host-header origin 策略的部署启用 Host-header origin 回退。
remote.transport：ssh（默认）或 direct（ws/wss）。对于 direct，remote.url 必须是 ws:// 或 wss://。
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1：客户端侧的紧急覆盖，允许对受信任的私有网络 IP 使用明文 ws://；默认仍只允许 loopback 使用明文。
gateway.remote.token / .password 是远程客户端凭证字段。它们本身不会配置网关认证。
gateway.push.apns.relay.baseUrl：官方/TestFlight iOS 版本在将基于 relay 的注册发布到网关后，供网关使用的外部 APNs relay 基础 HTTPS URL。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。
gateway.push.apns.relay.timeoutMs：网关到 relay 的发送超时（毫秒）。默认值为 10000。
基于 relay 的注册会被委派给一个特定网关身份。配对的 iOS 应用会获取 gateway.identity.get，将该身份包含到 relay 注册中，并将带注册作用域的发送授权转发给网关。其他网关不能复用该已存储注册。
OPENCLAW_APNS_RELAY_BASE_URL / OPENCLAW_APNS_RELAY_TIMEOUT_MS：用于覆盖上述 relay 配置的临时环境变量。
OPENCLAW_APNS_RELAY_ALLOW_HTTP=true：仅开发用的逃生口，用于 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。
gateway.channelHealthCheckMinutes：渠道健康检查监视间隔（分钟）。设为 0 可全局禁用健康检查重启。默认：5。
gateway.channelStaleEventThresholdMinutes：陈旧 socket 阈值（分钟）。请保持其大于或等于 gateway.channelHealthCheckMinutes。默认：30。
gateway.channelMaxRestartsPerHour：滚动一小时内，每个渠道/账户允许的最大健康检查重启次数。默认：10。
channels.<provider>.healthMonitor.enabled：按渠道选择退出健康检查重启，同时保留全局监视器开启。
channels.<provider>.accounts.<accountId>.healthMonitor.enabled：多账户渠道的按账户覆盖。设置后，它优先于渠道级覆盖。
仅当 gateway.auth.* 未设置时，本地 Gateway 网关调用路径才可回退到 gateway.remote.*。
如果 gateway.auth.token / gateway.auth.password 通过 SecretRef 显式配置但无法解析，解析会以默认拒绝方式失败（不会用 remote 回退掩盖）。
trustedProxies：终止 TLS 的反向代理 IP。仅列出你控制的代理。
allowRealIpFallback：为 true 时，当缺失 X-Forwarded-For 时，Gateway 网关接受 X-Real-IP。默认为 false，以实现默认拒绝行为。
gateway.tools.deny：对 HTTP POST /tools/invoke 额外阻止的工具名（扩展默认 deny 列表）。
gateway.tools.allow：从默认 HTTP deny 列表中移除工具名。

兼容 OpenAI 的端点

Chat Completions：默认禁用。通过 gateway.http.endpoints.chatCompletions.enabled: true 启用。
Responses API：gateway.http.endpoints.responses.enabled。
Responses URL 输入加固：
- gateway.http.endpoints.responses.maxUrlParts
- gateway.http.endpoints.responses.files.urlAllowlist
- gateway.http.endpoints.responses.images.urlAllowlist
可选的响应加固 header：
- gateway.http.securityHeaders.strictTransportSecurity（仅对你控制的 HTTPS origin 设置；见 Trusted Proxy Auth）

多实例隔离

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

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

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

见 Multiple Gateways。

Hooks

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

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

端点：

POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
- 仅当 hooks.allowRequestSessionKey=true（默认：false）时，才接受请求负载中的 sessionKey。
POST /hooks/<name> → 通过 hooks.mappings 解析

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 值（请求 + 映射）的可选前缀 allowlist，例如 ["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 host

{
  canvasHost: {
    root: "~/.openclaw/workspace/canvas",
    liveReload: true,
    // enabled: false, // 或 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 bind：canvas 路由需要 Gateway 网关认证（token/password/trusted-proxy），与其他 Gateway 网关 HTTP 界面一致。
Node WebView 通常不会发送认证头；在某个节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问通告带节点作用域的 capability URL。
Capability URL 绑定到活动节点 WS 会话，并且很快过期。不使用基于 IP 的回退。
会向所服务的 HTML 中注入 live-reload 客户端。
空目录时会自动创建起始 index.html。
也会在 /__openclaw__/a2ui/ 提供 A2UI。
更改需要重启 Gateway 网关。
对于大型目录或 EMFILE 错误，请禁用 live reload。

设备发现

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 文件：当前工作目录 .env + ~/.openclaw/.env（两者都不会覆盖现有变量）。
shellEnv：从你的登录 shell 配置文件导入缺失的预期键名。
完整优先级见 Environment。

环境变量替换

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

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

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

密钥

Secret refs 是增量能力：明文值仍然可用。

`SecretRef`

使用以下对象形式之一：

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

校验：

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

支持的凭证表面

规范矩阵：SecretRef Credential Surface
secrets apply 会定位受支持的 openclaw.json 凭证路径。
auth-profiles.json 中的 ref 也包含在运行时解析和审计覆盖范围内。

Secret providers 配置

{
  secrets: {
    providers: {
      default: { source: "env" }, // 可选的显式环境变量提供商
      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 refs 会在激活时解析为内存快照，之后请求路径只读取该快照。
激活期间会应用活动表面过滤：已启用表面上的未解析 ref 会导致启动/重载失败，而非活动表面会被跳过并记录诊断信息。

认证存储

{
  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 支持值级 ref（api_key 使用 keyRef，token 使用 tokenRef）。
静态运行时凭证来自内存中的已解析快照；发现旧版静态 auth.json 条目时会进行清理。
旧版 OAuth 会从 ~/.openclaw/credentials/oauth.json 导入。
见 OAuth。
Secrets 运行时行为以及 audit/configure/apply 工具：见 Secrets Management。

日志

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | compact | json
    redactSensitive: "tools", // off | tools
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}

默认日志文件：/tmp/openclaw/openclaw-YYYY-MM-DD.log。
设置 logging.file 以获得稳定路径。
使用 --verbose 时，consoleLevel 会提升为 debug。

CLI

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

身份

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

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

从 identity.emoji 派生 messages.ackReaction（回退为 👀）
从 identity.name/identity.emoji 派生 mentionPatterns
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", // 旧版回退，仅用于已存储的 notify:true 作业
    webhookToken: "replace-with-dedicated-token", // 可选，用于出站 webhook 认证的 bearer token
    sessionRetention: "24h", // 时长字符串或 false
    runLog: {
      maxBytes: "2mb", // 默认 2_000_000 字节
      keepLines: 2000, // 默认 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 的已存储作业。

见 Cron Jobs。

媒体模型模板变量

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

Variable	Description
`{{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 等）

配置 includes（`$include`）

将配置拆分为多个文件：

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

合并行为：

单个文件：替换包含它的对象。
文件数组：按顺序深度合并（后者覆盖前者）。
同级键：在 include 之后再合并（覆盖被包含的值）。
嵌套 include：最多 10 层。
路径：相对于包含它的文件解析，但必须保持在顶层配置目录（openclaw.json 的 dirname）内。只有在最终解析结果仍位于该边界内时，才允许使用绝对路径/../ 形式。
错误：缺失文件、解析错误和循环 include 都会给出清晰错误信息。

相关内容：Configuration · Configuration Examples · Doctor

111 KiB Raw Blame History Unescape Escape

配置参考

渠道

私信和群组访问

渠道模型覆盖

渠道默认值和心跳

WhatsApp

Telegram

Discord

Google Chat

Slack

Mattermost

Signal

BlueBubbles

iMessage

Microsoft Teams

IRC

多账户（所有渠道）

其他扩展渠道

群聊提及门控

私信历史限制

自聊模式

命令（聊天命令处理）

智能体默认值

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

tools.subagents

自定义提供商和 base URL

提供商字段详情

提供商示例

Skills

插件

浏览器

UI

Gateway 网关

兼容 OpenAI 的端点

多实例隔离

Hooks

Gmail 集成

Canvas host

设备发现

111 KiB

Raw Blame History

`agents.defaults.workspace`

`agents.defaults.repoRoot`

`agents.defaults.skipBootstrap`

`agents.defaults.bootstrapMaxChars`

`agents.defaults.bootstrapTotalMaxChars`

`agents.defaults.bootstrapPromptTruncationWarning`

`agents.defaults.imageMaxDimensionPx`

`agents.defaults.userTimezone`

`agents.defaults.timeFormat`

`agents.defaults.model`

`agents.defaults.cliBackends`

`agents.defaults.heartbeat`

`agents.defaults.compaction`

`agents.defaults.contextPruning`

`agents.defaults.sandbox`

`agents.list`（按智能体覆盖）

`tools.allow` / `tools.deny`

`tools.byProvider`

`tools.elevated`

`tools.exec`

`tools.loopDetection`

`tools.web`

`tools.media`

`tools.agentToAgent`

`tools.sessions`

`tools.sessions_spawn`

`tools.subagents`

`env`（内联环境变量）

`SecretRef`

配置 includes（`$include`）