思渡AI Logo
OpenClaw 官方手册网关与运维Gateway配置参考

配置参考

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

配置参考

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

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

渠道

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

私信和群组访问

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

DM policyBehavior
pairing（默认）未知发送者会收到一次性配对码；所有者必须批准
allowlist仅 allowFrom 中的发送者（或已配对的允许列表存储）
open允许所有入站私信（要求 allowFrom: ["*"]）
disabled忽略所有入站私信
Group policyBehavior
allowlist（默认）仅允许匹配已配置 allowlist 的群组
open绕过群组 allowlist（仍会应用提及门控）
disabled阻止所有群组/房间消息

channels.defaults.groupPolicy 会在某个提供商的 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 通过 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,
    },
  },
}

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress（默认：off）
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}
  • 机器人令牌：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 groupDefaultNotes
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 发起的配置写入。

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

智能体默认值

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 中时适用）：

AliasModel
opusanthropic/claude-opus-4-6
sonnetanthropic/claude-sonnet-4-6
gptopenai/gpt-5.4
gpt-miniopenai/gpt-5-mini
geminigoogle/gemini-3.1-pro-preview
gemini-flashgoogle/gemini-3-flash-preview
gemini-flash-litegoogle/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"] },
      },
    },
  },
}

行为细节见 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"],
      },
    },
  },
}

浏览器沙箱隔离和 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 }

确定性匹配顺序：

  1. match.peer
  2. match.guildId
  3. match.teamId
  4. match.accountId（精确匹配，无 peer/guild/team）
  5. match.accountId: "*"（全渠道）
  6. 默认智能体

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

对于 type: "acp" 条目，OpenClaw 会按精确对话身份（match.channel + account + match.peer.id）解析，不使用上述 route 绑定层级顺序。

按智能体的访问配置

优先级细节见 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",
    },
  },
}

消息

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

模板变量：

VariableDescriptionExample
{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"（现有显式配置文件会保留）。

ProfileIncludes
minimal仅 session_status
codinggroup:fs、group:runtime、group:sessions、group:memory、image
messaginggroup:messaging、sessions_list、sessions_history、sessions_send、session_status
full不限制（等同于未设置）

工具组

GroupTools
group:runtime ext、process（bash 可作为 ext 的别名）
group:fsread、write、edit、apply_patch
group:sessionssessions_list、sessions_history、sessions_send、sessions_spawn、session_status
group:memorymemory_search、memory_get
group:webweb_search、web_fetch
group:uibrowser、canvas
group:automationcron、gateway
group:messagingmessage
group:nodesnodes
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

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

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["1234567890123", "987654321098765432"],
      },
    },
  },
}
  • 按智能体覆盖（agents.list[].tools.elevated）只能进一步收紧限制。
  • /elevated on|off|ask|full 会按会话保存状态；内联指令仅作用于单条消息。
  • 提升权限的 ext 会在主机上运行，并绕过沙箱隔离。

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

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

提供商示例

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

兼容 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 解析

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 + extPort。
  • full：包含 cliPath + extPort。
  • 主机名默认为 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"）。
  • ext 提供商要求绝对 command 路径，并通过 stdin/stdout 使用协议负载。
  • 默认会拒绝符号链接命令路径。设置 allowSymlinkCommand: true 可允许符号链接路径，同时校验解析后的目标路径。
  • 如果配置了 trustedDirs，则受信任目录检查会应用到解析后的目标路径。
  • ext 子进程环境默认最小化；请通过 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 可清除未知键）。

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 中展开的模板占位符：

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

Previous

配置示例

Next

配置

On this page

配置参考渠道私信和群组访问渠道模型覆盖渠道默认值和心跳WhatsAppTelegramDiscordGoogle ChatSlackMattermostSignalBlueBubblesiMessageMicrosoft TeamsIRC多账户（所有渠道）其他扩展渠道群聊提及门控私信历史限制自聊模式命令（聊天命令处理）智能体默认值agents.defaults.workspaceagents.defaults.repoRootagents.defaults.skipBootstrapagents.defaults.bootstrapMaxCharsagents.defaults.bootstrapTotalMaxCharsagents.defaults.bootstrapPromptTruncationWarningagents.defaults.imageMaxDimensionPxagents.defaults.userTimezoneagents.defaults.timeFormatagents.defaults.modelagents.defaults.cliBackendsagents.defaults.heartbeatagents.defaults.compactionagents.defaults.contextPruning分块流式传输输入指示器agents.defaults.sandboxagents.list（按智能体覆盖）多智能体路由绑定匹配字段按智能体的访问配置会话消息回复前缀确认反应入站防抖TTS（文本转语音）Talk工具工具配置文件工具组tools.allow / tools.denytools.byProvidertools.elevatedtools.exectools.loopDetectiontools.webtools.mediatools.agentToAgenttools.sessionstools.sessions_spawntools.subagents自定义提供商和 base URL提供商字段详情提供商示例Skills插件浏览器UIGateway 网关兼容 OpenAI 的端点多实例隔离HooksGmail 集成Canvas host设备发现mDNS（Bonjour）广域（DNS-SD）环境env（内联环境变量）环境变量替换密钥SecretRef支持的凭证表面Secret providers 配置认证存储日志CLI向导身份Bridge（旧版，已移除）Cron媒体模型模板变量配置 includes（$include）