跳转至

配置 — 消息与对话

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

模板变量:

变量 描述 示例
{model} 简短模型名称 claude-opus-4-6
{modelFull} 完整模型标识符 anthropic/claude-opus-4-6
{provider} 提供商名称 anthropic
{thinkingLevel} 当前思考级别 high、low、off
{identity.name} 代理身份名称 (与 "auto" 相同)

变量不区分大小写。{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:将新的 prompt 注入当前活动运行。
  • followup:在活动运行结束后运行新 prompt。
  • collect:将兼容消息批量处理,稍后一起运行。具有独立持久入口准入的消息(包括 Discord 和 Telegram)仍保留在单独的 followup 轮次中;兼容的 Gateway chat.send 输入仍可以合并。参见 队列模式。
  • interrupt:在启动最新 prompt 之前中止当前活动运行。
  • 队列对 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

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 路由。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw