配置 — 消息与对话
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 轮次中;兼容的 Gatewaychat.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