配置参考

​

配置参考

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

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

---

​

渠道

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

​

私聊和群组访问

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

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

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

当提供商的 groupPolicy 未设置时，channels.defaults.groupPolicy 设置默认值。 配对码在 1 小时后过期。待处理的私聊配对请求上限为 每个渠道 3 个。 如果提供商块完全缺失（缺少 channels.<provider>），运行时群组策略将回退到 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

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

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

多账户 WhatsApp

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

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

​

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (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 token：channels.telegram.botToken 或 channels.telegram.tokenFile（仅限常规文件；拒绝符号链接），其中 TELEGRAM_BOT_TOKEN 作为默认账户的回退。
• 可选的 channels.telegram.defaultAccount 在匹配到配置的账户 id 时，覆盖默认账户选择。
• 在多账户设置（2+ 个账户 id）中，请设置显式默认值（channels.telegram.defaultAccount 或 channels.telegram.accounts.default）以避免回退路由；如果缺少或无效，openclaw doctor 会发出警告。
• configWrites: false 阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、/config set|unset）。
• 带有 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 的直接出站调用使用该令牌进行调用；账户重试/策略设置仍来自活动运行时快照中选定的账户。
• 当匹配配置的账户 ID 时，可选的 channels.discord.defaultAccount 会覆盖默认账户选择。
• 使用 user:<id>（私信）或 channel:<id>（公会频道）作为投递目标；拒绝纯数字 ID。
• 公会别名为小写，空格替换为 -；频道键使用别名（无 #）。建议使用公会 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 }) 自动线程创建/绑定的选择性开关
• 带有 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 将运行时可用性映射到机器人状态（healthy => 在线，degraded => 空闲，exhausted => 请勿打扰）并允许可选的状态文本覆盖。
• channels.discord.dangerouslyAllowNameMatching 重新启用可变名称/标签匹配（应急兼容模式）。

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

​

Google Chat

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

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

​

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: "partial", // off | partial | block | progress (preview mode)
      nativeStreaming: true, // 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 emoji 简码，例如 "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: "[phone]", // optional account binding
      dmPolicy: "pairing",
      allowFrom: ["[phone]", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["[phone]", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

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

• channels.signal.account：将渠道启动指定到特定的 Signal 账号身份。
• channels.signal.configWrites：允许或拒绝由 Signal 发起的配置写入。
• 可选的 channels.signal.defaultAccount 会在匹配到已配置的账号 ID 时覆盖默认的账号选择。

​

BlueBubbles

BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 channels.bluebubbles 下配置）。

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, group controls, and advanced actions:
      // see /channels/bluebubbles
    },
  },
}

• 此处涵盖的核心键路径：channels.bluebubbles、channels.bluebubbles.dmPolicy。
• 可选的 channels.bluebubbles.defaultAccount 会在匹配到已配置的账号 ID 时覆盖默认的账号选择。
• 完整的 BlueBubbles 渠道配置记录在 BlueBubbles 中。

​

iMessage

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

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["[phone]", "[e-mail]", "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 时覆盖默认的账号选择。

• 需要对消息数据库 进行完全磁盘访问。

• 优先使用 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 发起的配置写入。

iMessage SSH 包装器示例

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

​

Microsoft Teams

Microsoft Teams 基于扩展，并在 channels.msteams 下进行配置。

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // see /channels/msteams
    },
  },
}

• 此处涵盖的核心键路径：channels.msteams、channels.msteams.configWrites。
• 完整的 Teams 配置（凭据、webhook、私信/群组策略、按团队/按渠道覆盖）记录在 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: "[e-mail]",
      },
    },
  },
}

• 此处涵盖的核心键路径：channels.irc、channels.irc.dmPolicy、channels.irc.configWrites、channels.irc.nickserv.*。
• 当与配置的账户 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> 并记录在其专门的渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 请查看完整的渠道索引：渠道。

​

群组提及 gating

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

提及类型：

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

{
  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: ["[phone]"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

​

命令（聊天命令处理）

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

命令详情

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

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

{
  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"],
      },
      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 }）。
  • 由共享图像生成功能以及任何生成图像的未来工具/插件界面使用。
  • 典型值：原生 Nano Banana 风格流程使用 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：当调用时未传递 maxBytesMb 时，pdf 工具的默认 PDF 大小限制。
• pdfMaxPages：pdf 工具中提取回退模式考虑的默认最大页数。
• model.primary：格式 provider/model（例如 anthropic/claude-opus-4-6）。如果省略提供商，OpenClaw 将假定 anthropic（已弃用）。
• models：为 /model 配置的模型目录和允许列表。每个条目可以包含 alias（快捷方式）和 params（特定于提供商，例如 temperature、maxTokens、cacheRetention、context1m）。
• params 合并优先级（配置）：agents.defaults.models["provider/model"].params 是基础，然后 agents.list[].params（匹配代理 ID）按键覆盖。
• 修改这些字段的配置编写器（例如 /models set、/models set-image 和回退添加/删除命令）会保存规范的对象形式，并在可能的情况下保留现有的回退列表。
• maxConcurrent：跨会话的最大并行代理运行数（每个会话仍然串行化）。默认值：1。

内置别名简写（仅当模型在 agents.defaults.models 中时适用）：

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

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

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

​

agents.defaults.cliBackends

用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商出现故障时，可用作备份。

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

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

​

agents.defaults.heartbeat

定期心跳运行。

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

• every：持续时间字符串 (ms/s/m/h)。默认值：30m。
• suppressToolErrorWarnings：为 true 时，在心跳运行期间抑制工具错误警告载荷。
• directPolicy：直接/私信传送策略。allow（默认）允许直接目标传送。block 抑制直接目标传送并发出 reason=dm-blocked。
• lightContext：为 true 时，心跳运行使用轻量级引导上下文，并仅保留工作区引导文件中的 HEARTBEAT.md。
• isolatedSession：为 true 时，每次心跳都在没有先前对话历史的新会话中运行。与 cron sessionTarget: "isolated" 使用相同的隔离模式。将每次心跳的 token 成本从约 100K 降低到约 2-5K tokens。
• 每个代理：设置 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 会在压缩摘要期间前置内置的 opaque identifier 保留指导。
• 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 behavior

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

Soft-trim 保留开头和结尾，并在中间插入 ...。

Hard-clear 用占位符替换整个工具结果。

注意：

• 图像块永远不会被修剪/清除。
• 比率是基于字符的（近似值），而不是确切的令牌计数。
• 如果存在的助手消息少于 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 (use minMs/maxMs)
    },
  },
}

• 非 Telegram 渠道需要显式的 *.blockStreaming: true 才能启用块回复。
• 渠道覆盖：channels.<channel>.blockStreamingCoalesce（以及每个账户的变体）。Signal/Slack/Discord/Google Chat 默认 minChars: 1500。
• humanDelay：块回复之间的随机暂停。natural = 800–2500ms。每个代理的覆盖：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",
          // 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：内联内容或由 OpenClaw 在运行时具体化到临时文件的 SecretRefs
• 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:<id>" 默认被阻止。

入站附件 被暂存到活动工作空间中的 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=<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。
  • 默认值是容器镜像基线；使用带有自定义入口点的自定义浏览器镜像来更改容器默认值。

浏览器 Docker 和 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 的 Cron 任务仍会继承默认回退，除非您设置了 fallbacks: []。
• params：合并到 agents.defaults.models 中所选 WhatsApp 条目的每个代理流参数。使用此功能进行特定于代理的覆盖，如 cacheRetention、temperature 或 maxTokens，而无需复制整个模型目录。
• thinkingDefault：可选的每个代理默认思考级别（off | minimal | low | medium | high | xhigh | adaptive）。当未设置每条消息或 Telegram 覆盖时，覆盖此代理的 agents.defaults.thinkingDefault。
• reasoningDefault：可选的每个代理默认推理可见性（on | off | stream）。在未设置每条消息或 Telegram 推理覆盖时应用。
• fastModeDefault：可选的每个代理快速模式默认值（true | false）。在未设置每条消息或 Telegram 快速模式覆盖时应用。
• runtime：可选的每个代理运行时描述符。当代理应默认为 ACP 挎具 Telegram 时，使用带有 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 将拒绝非沙箱隔离运行的目标。

---

​

多代理路由

在一个 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 }

确定性匹配顺序：

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId（精确，无对等/群组/团队）
5. match.accountId: "*"（渠道范围）
6. 默认代理

在每个层级中，第一个匹配的 bindings 条目胜出。

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

​

每代理访问配置文件

完全访问（无沙箱）

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

只读工具 + 工作区

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

无文件系统访问权限（仅限消息传递）

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
        tools: {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
            "gateway",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

有关优先级详情，请参阅 多代理沙箱与工具。

---

​

会话

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

Session 字段详情

• 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"。
• 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.<timestamp> 记录存档的保留期。默认为 pruneAfter；设置 false 以禁用。
  • maxDiskBytes: 可选的会话目录磁盘预算。在 warn 模式下记录警告；在 enforce 模式下首先删除最旧的工件/会话。
  • highWaterBytes: 预算清理后的可选目标。默认为 80% 的 maxDiskBytes。
• 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。

解析顺序（最具体优先）：account → 渠道 → global。"" 禁用并停止级联。"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。
• 解析顺序：account → 渠道 → messages.ackReaction → identity fallback。
• 范围：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: {
    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 对象。
• 仅当未配置对话 API 密钥时，才应用 ELEVENLABS_API_KEY 回退。
• voiceAliases 允许对话指令使用易记名称。
• silenceTimeoutMs 控制对话模式在用户停止说话后等待多久再发送转录内容。如果未设置，则保持平台默认的暂停窗口 (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: ["[phone]"],
        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 运行时会拒绝它们。
• 文件会以 .manifest.json 的形式在 .openclaw/attachments/<uuid>/ 处具体化到子工作区中。
• 附件内容会从转录持久化中自动编辑。
• Base64 输入将通过严格的字母表/填充检查和解码前大小保护进行验证。
• 目录的文件权限为 0700，文件的权限为 0600。
• 清理遵循 cleanup 策略：delete 始终删除附件；keep 仅在 retainOnSessionKeep: true 时保留它们。

​

tools.subagents

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

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

---

​

自定义提供商和基础 URL

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

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

• 使用 authHeader: true + headers 满足自定义身份验证需求。
• 使用 OPENCLAW_AGENT_DIR（或 PI_CODING_AGENT_DIR）覆盖代理配置根目录。
• 匹配提供商 ID 的合并优先级：
  • 非空的代理 models.json baseUrl 值优先。
  • 非空的代理 apiKey 值仅当该提供商在当前配置/身份验证配置文件上下文中不由 SecretRef 管理时才优先。
  • 由 SecretRef 管理的提供商 apiKey 值从源标记（环境变量引用为 ENV_VAR_NAME，文件/exec 引用为 secretref-managed）刷新，而不是持久化已解析的密钥。
  • 由 SecretRef 管理的提供商标头值从源标记（环境变量引用为 secretref-env:ENV_VAR_NAME，文件/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 基础 URL。
• models.providers.*.headers：用于代理/租户路由的额外静态请求头。
• models.providers.*.models：显式的提供商 WhatsApp 目录条目。
• 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：已发现 WhatsApp 的回退上下文窗口。
• models.bedrockDiscovery.defaultMaxTokens：已发现 WhatsApp 的回退最大输出令牌数。

​

提供商示例

Cerebras (GLM 4.6 / 4.7)

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

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

OpenCode

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

设置 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）。对 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。 如果您更喜欢旧版文本模型，MiniMax-M2.5 和 MiniMax-M2.5-highspeed 仍然可用。

Local models (LM Studio)

请参阅 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: {
      "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，即使该 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 目标的可选允许列表。仅当您有意想要允许任何模型时才使用 "*"。
• 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 命令而非手动编辑。

参见 插件。

---

​

浏览器

{
  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: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // emoji, short text, image URL, or data URI
    },
  },
}

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

​

OpenAI 兼容端点

• Chat Completions：默认禁用。使用 gateway.http.endpoints.chatCompletions.enabled: true 启用。
• Responses API：gateway.http.endpoints.responses.enabled。
• Responses URL 输入加固：
  • 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>）。

请参阅多网关。

---

​

钩子

{
  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 值（请求 + 映射），例如 ["hook:"]。
• deliver: true 将最终回复发送到渠道；channel 默认为 last。
• model 覆盖此 hook 运行的 LLM（如果设置了模型目录，则必须被允许）。

​

Gmail 集成

{
  hooks: {
    gmail: {
      account: "[e-mail]",
      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"（默认）。
• 非环回绑定：Canvas 路由需要 Gateway(网关) 身份验证（令牌/密码/受信任代理），与其他 Gateway(网关) HTTP 表面相同。
• Node WebViews 通常不发送身份验证头；在节点配对并连接后，Gateway(网关) 会广播用于 Canvas/A2UI 访问的节点范围功能 URL。
• 功能 URL 绑定到活动节点 WS 会话并很快过期。不使用基于 IP 的回退。
• 将实时重新加载客户端注入到提供的 HTML 中。
• 如果为空，则自动创建初始 index.html。
• 同时也在 /__openclaw__/a2ui/ 提供 A2UI 服务。
• 更改需要重启 Gateway。
• 对于大型目录或 EMFILE 错误，请禁用实时重新加载。

---

​

设备发现

​

mDNS (Bonjour)

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

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

​

广域 (DNS-SD)

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

在 ~/.openclaw/dns/ 下写入单播 DNS-SD 区域。为了跨网络发现，请将其与 DNS 服务器（推荐 CoreDNS）+ Tailscale 分割 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 providers 配置

{
  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: {
    profiles: {
      "anthropic:[e-mail]": { provider: "anthropic", mode: "oauth", email: "[e-mail]" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
    },
    order: {
      anthropic: ["anthropic:[e-mail]", "anthropic:work"],
    },
  },
}

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

---

​

日志记录

{
  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 新手引导助手写入。派生默认值：

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

---

​

网桥（旧版，已移除）

当前版本不再包含 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 令牌，如果省略则不发送认证头。
• webhook：已弃用的旧版后备 webhook URL (http/https)，仅用于仍然具有 notify: true 的存储作业。

请参阅 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）

将配置拆分为多个文件：

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

合并行为：

• 单个文件：替换包含的对象。
• 文件数组：按顺序深度合并（后面的覆盖前面的）。
• 同级键：在包含之后合并（覆盖包含的值）。
• 嵌套包含：最多 10 层深度。
• 路径：相对于包含文件解析，但必须保持在顶级配置目录内（dirname 的 openclaw.json）。仅当绝对路径/../ 形式仍在该边界内解析时才允许使用。
• 错误：针对丢失文件、解析错误和循环包含的明确消息。

---

相关：Configuration · Configuration Examples · Doctor

---

本页面源自 openclaw/openclaw，由 BeaversLab 翻译，遵循 MIT 协议 发布。