配置 — 消息与对话

messages.* 投递行为、文本转语音，以及 Talk 模式的 talk.* 默认值。

消息¶

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all | off | none
    queue: {
      mode: "steer", // steer (default) | followup | collect | interrupt
      cap: 20,
      drop: "summarize", // old | new | summarize (default)
      byChannel: {
        whatsapp: "followup",
        telegram: "followup",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disables ordinary burst batching
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

响应前缀¶

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

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

模板变量：

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

确认表情回应¶

• 默认使用当前活动代理的 identity.emoji，否则为 "👀"。设置 "" 可禁用。
• Discord、Matrix、Slack 和 Telegram 支持按渠道覆盖：channels.<channel>.ackReaction、channels.<channel>.accounts.<id>.ackReaction。对于其他支持确认表情回应的渠道，请改用 messages.ackReaction。
• 解析顺序：账号 → 渠道 → messages.ackReaction → 身份回退。
• WhatsApp 是上述两条规则的例外。它仅从 messages.ackReaction 和 messages.ackReactionScope 获取表情和范围；当 messages.ackReaction 未设置时，它完全不会发送确认回应，因此身份回退在那里永远不会生效。将 channels.whatsapp.reactionLevel（或按账号形式）设置为 "off" 仍会抑制所有自动表情回应，包括确认回应。参见 WhatsApp 确认表情回应。
• 范围：group-mentions（默认）、group-all、direct、all，或 off/none（完全禁用确认表情回应）。
• group-mentions 会对提及代理的群消息进行确认，包括在 requireMention: false 的群组中。使用 group-all 可确认每条群消息。
• messages.statusReactions.enabled：在 Slack、Discord、Signal、Telegram 和 WhatsApp 上启用生命周期状态表情回应。 在 Discord 上，未设置时，如果确认表情回应处于活动状态，则保持状态表情回应启用。 在 Slack、Signal、Telegram 和 WhatsApp 上，需显式设置为 true 才能启用生命周期状态表情回应。 Slack 默认使用其原生助手线程状态和轮换加载消息来显示进度，同时保持已配置的确认表情回应为静态。

队列¶

• mode：当会话运行处于活动状态时，入站消息到达的队列策略。默认值："steer"。
• steer：将新提示注入当前活动运行。
• followup：在当前活动运行结束后运行新提示。
• collect：将兼容消息批量处理，稍后一起运行。
• interrupt：在开始最新提示前中止当前活动运行。
• 队列对 steer、followup 和 collect 批处理使用内置的 500ms 防抖。
• cap：在应用丢弃策略前，队列中允许的最大消息数。默认值：20。
• drop：超过上限时的策略。"summarize"（默认）丢弃最旧的条目，但保留简洁摘要；"old" 丢弃最旧条目且不保留摘要；"new" 拒绝最新条目。
• byChannel：按提供商 id 作为键的按渠道 mode 覆盖。
• debounceMsByChannel：按提供商 id 作为键的按渠道防抖覆盖，单位为毫秒。

使用 messages.inbound.debounceMs 作为全局入队前防抖窗口。

入站防抖¶

在静默窗口后，将同一发送者快速发送的纯文本消息合并为单个代理回合。媒体/附件会立即发送。控制命令绕过防抖。

• messages.inbound.byChannel.<channel> 覆盖 messages.inbound.debounceMs。
• 如果两者都未设置，Telegram 使用 300 毫秒；其他渠道没有通用防抖延迟。
• 0 禁用普通突发批处理。Telegram 仍会自动组装接近上限的长粘贴片段，允许续传最多 1500 毫秒。

批处理是一种有界时序启发式方法，并不保证长消息的每个部分都会合并为一个回合。参见 入站防抖 和 Telegram 入站文本批处理。

其他消息键¶

• channels.whatsapp.responsePrefix：出站 WhatsApp 回复前缀。Doctor 仅当此规范值未设置时，才会将已弃用的入站 messagePrefix 值迁移到这里。
• messages.visibleReplies：控制直接、群组和渠道会话中的可见源回复（"message_tool" 需要 message(action=send) 才能产生可见输出；"automatic" 按原样发布普通回复）。
• messages.usageTemplate / messages.responseUsage：自定义 /usage 页脚模板以及每条回复的默认用量模式（off | tokens | full，另有 tokens 的旧版 on 别名）。
• messages.groupChat.mentionPatterns / historyLimit：群消息提及触发器和历史窗口大小。

TTS（文本转语音）¶

{
  tts: {
    auto: "off", // off (default) | always | inbound | tagged
    mode: "final", // final | all
    provider: "elevenlabs",
    summaryModel: "openai/gpt-5.4-mini",
    modelOverrides: { enabled: true },
    maxTextLength: 4000,
    timeoutMs: 30000,
    providers: {
      elevenlabs: {
        apiKey: "example-elevenlabs-api-key",
        baseUrl: "https://api.elevenlabs.io",
        speakerVoiceId: "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,
        },
      },
      microsoft: {
        speakerVoice: "en-US-MichelleNeural",
        lang: "en-US",
        outputFormat: "audio-24khz-48kbitrate-mono-mp3",
      },
      openai: {
        apiKey: "example-openai-api-key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        speakerVoice: "coral",
      },
    },
  },
}

全局偏好路径属于机器状态（默认 ~/.openclaw/settings/tts.json；使用 OPENCLAW_TTS_PREFS 覆盖）。高级 多智能体配置可以设置 agents.entries.<id>.tts.prefsPath，以使用独立的 按智能体划分的偏好存储。

• auto 控制默认自动 TTS 模式：off、always、inbound 或 tagged。/tts on|off 可以覆盖本地偏好，/tts status 显示生效状态。
• summaryModel 为自动摘要覆盖 agents.defaults.model.primary。
• modelOverrides 默认启用（enabled !== false）；modelOverrides.allowProvider 为可选启用。
• API 密钥回退到 ELEVENLABS_API_KEY/XI_API_KEY 和 OPENAI_API_KEY。
• 内置语音提供商由插件拥有。如果设置了 plugins.allow，请包含你要使用的每个 TTS 提供商插件，例如 Edge TTS 使用 microsoft。旧版 edge 提供商 ID 作为 microsoft 的别名被接受。
• providers.openai.baseUrl 覆盖 OpenAI TTS 端点。解析顺序为配置，然后 OPENAI_TTS_BASE_URL，然后 https://api.openai.com/v1。
• 当 providers.openai.baseUrl 指向非 OpenAI 端点时，OpenClaw 将其视为 OpenAI 兼容 TTS 服务器，并放宽模型/语音验证。

对话¶

Talk 模式的默认值（macOS/iOS/Android 以及浏览器 Control UI）。

{
  talk: {
    agentId: "ops",
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        speakerVoiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_multilingual_v2",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    consultThinkingLevel: "low",
    consultFastMode: true,
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime-2.1",
          speakerVoice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      mode: "realtime", // realtime | stt-tts | transcription
      transport: "webrtc", // webrtc | provider-websocket | gateway-relay | managed-room
      vadThreshold: 0.5,
      silenceDurationMs: 500,
      prefixPaddingMs: 300,
      reasoningEffort: "medium",
      brain: "agent-consult", // agent-consult | direct-tools | none
    },
  },
}

• 当配置了多个 Talk 提供商时，talk.provider 必须匹配 talk.providers 中的某个键。
• talk.agentId 拥有在未显式指定智能体作用域会话键时创建的 Talk 会话。会话作用域的 Talk 调用继续使用编码在该键中的智能体。Doctor 可能为现有多智能体配置创建一个仅包含此所有者的最小 talk 块。
• 旧版扁平 Talk 键（talk.voiceId、talk.voiceAliases、talk.modelId、talk.outputFormat、talk.apiKey）仅用于兼容。运行 openclaw doctor --fix 以将持久化配置重写为 talk.providers.<provider>。
• 语音 ID 回退到 ELEVENLABS_VOICE_ID 或 SAG_VOICE_ID（macOS Talk 客户端行为）。
• providers.*.apiKey 接受明文字符串或 SecretRef 对象。
• ELEVENLABS_API_KEY 回退仅在未配置 Talk API 密钥时适用。
• providers.*.voiceAliases 允许 Talk 指令使用友好名称。
• providers.mlx.modelId 选择 macOS 本地 MLX 助手使用的 Hugging Face 仓库。如果省略，macOS 使用 mlx-community/Soprano-80M-bf16。
• macOS MLX 播放通过捆绑的 openclaw-mlx-tts 助手运行（如果存在），或通过 PATH 上的可执行文件运行；OPENCLAW_MLX_TTS_BIN 用于开发时覆盖助手路径。
• consultThinkingLevel 控制 Control UI Talk 实时 openclaw_agent_consult 调用背后的完整 OpenClaw 智能体运行的思考级别。保持未设置以保留正常会话/模型行为。
• consultFastMode 为 Control UI Talk 实时咨询设置一次性快速模式覆盖，而不更改会话的正常快速模式设置。
• speechLocale 设置 Android、iOS 和 macOS Talk 语音识别以及 iOS 系统语音回退使用的 BCP 47 区域 ID。Android 还使用其语言组件来指导实时输入转录。保持未设置以使用设备默认值。
• silenceTimeoutMs 控制 Talk 模式在用户静默后等待多久再发送转录文本。未设置时保留平台默认暂停窗口（macOS 和 Android 为 700 ms，iOS 为 900 ms）。
• realtime.instructions 将面向提供商的系统指令追加到 OpenClaw 内置的实时提示中，因此可以配置语音风格，而不会丢失默认 openclaw_agent_consult 指导。
• realtime.vadThreshold 设置提供商语音活动阈值，从 0（最敏感）到 1（最不敏感）。未设置时保留提供商默认值。
• realtime.silenceDurationMs 设置提供商确认实时用户轮次之前的正整数静默窗口。未设置时保留提供商默认值。
• realtime.prefixPaddingMs 设置在检测到语音开始之前保留的非负整数音频量。未设置时保留提供商默认值。
• realtime.reasoningEffort 为实时会话设置提供商特定的推理级别。未设置时保留提供商默认值。
• realtime.consultRouting："provider-direct"（默认）在实时提供商生成最终用户转录文本而未使用 openclaw_agent_consult 时，保留提供商直接回复。"force-agent-consult" 改为将已最终确定的请求通过 OpenClaw 路由。