Concepts

OpenClaw 分两个阶段处理故障： 在当前提供商内进行认证配置文件轮换。 模型回退到 agents.defaults.model.fallbacks 中的下一个模型。 本文档解释运行时规则及其背后的数据。 认证存储（密钥 + OAuth） OpenClaw 对 API 密钥和 OAuth 令牌都使用认证配置文件。 密钥存储在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（旧版：~/.openclaw/agent/auth-profiles.json）。 配置 auth.profiles / auth.order 仅用于元数据和路由（不含密钥）。 旧版仅导入 OAuth 文件：~/.openclaw/credentials/oauth.json（首次使用时导入到 auth-profiles.json）。 更多详情：/concepts/oauth 凭证类型： type: "api_key" → { provider, key } type: "oauth" → { provider, access, refresh, expires, email? }（某些提供商还有 projectId/enterpriseUrl） 配置文件 ID OAuth 登录创建不同的配置文件，以便多个账户可以共存。 默认：当没有电子邮件可用时为 provider:default。 带电子邮件的 OAuth：provider:<email>（例如 google-antigravity:[email protected]）。 配置文件存储在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 的 profiles 下。 轮换顺序 当一个提供商有多个配置文件时，OpenClaw 按以下顺序选择： 显式配置：auth.order[provider]（如果设置）。 已配置的配置文件：按提供商过滤的 auth.profiles。 已存储的配置文件：auth-profiles.json 中该提供商的条目。 如果没有配置显式顺序，OpenClaw 使用轮询顺序： ...

OpenClaw 有两个独立的"流式传输"层： 分块流式传输（渠道）： 在助手写入时发出已完成的块。这些是普通的渠道消息（不是令牌增量）。 类令牌流式传输（仅限 Telegram）： 在生成时用部分文本更新草稿气泡；最终消息在结束时发送。 目前没有真正的令牌流式传输到外部渠道消息。Telegram 草稿流式传输是唯一的部分流式传输界面。 分块流式传输（渠道消息） 分块流式传输在助手输出可用时以粗粒度块发送。 模型输出 └─ text_delta/events ├─ (blockStreamingBreak=text_end) │ └─ 分块器在缓冲区增长时发出块 └─ (blockStreamingBreak=message_end) └─ 分块器在 message_end 时刷新 └─ 渠道发送（块回复） 图例： text_delta/events：模型流事件（对于非流式模型可能稀疏）。 chunker：应用最小/最大边界 + 断点偏好的 EmbeddedBlockChunker。 channel send：实际的出站消息（块回复）。 控制项： agents.defaults.blockStreamingDefault："on"/"off"（默认关闭）。 渠道覆盖：*.blockStreaming（以及每账户变体）可为每个渠道强制设置 "on"/"off"。 agents.defaults.blockStreamingBreak："text_end" 或 "message_end"。 agents.defaults.blockStreamingChunk：{ minChars, maxChars, breakPreference? }。 agents.defaults.blockStreamingCoalesce：{ minChars?, maxChars?, idleMs? }（发送前合并流式块）。 渠道硬上限：*.textChunkLimit（例如 channels.whatsapp.textChunkLimit）。 渠道分块模式：*.chunkMode（默认 length，newline 在长度分块之前按空行（段落边界）分割）。 Discord 软上限：channels.discord.maxLinesPerMessage（默认 17）分割高度较大的回复以避免 UI 裁剪。 边界语义： text_end：分块器发出时立即流式传输块；在每个 text_end 时刷新。 message_end：等到助手消息完成，然后刷新缓冲的输出。 如果缓冲文本超过 maxChars，message_end 仍然使用分块器，因此可能在最后发出多个块。 分块算法（低/高边界） 块分块由 EmbeddedBlockChunker 实现： ...

本页汇总了 OpenClaw 如何处理入站消息、会话、队列、流式传输和推理可见性。 消息流程（高层概述） 入站消息 -> 路由/绑定 -> 会话密钥 -> 队列（如果有运行中的任务） -> 智能体运行（流式传输 + 工具） -> 出站回复（渠道限制 + 分块） 关键配置项在配置中： messages.* 用于前缀、队列和群组行为。 agents.defaults.* 用于分块流式传输和分块默认值。 渠道覆盖（channels.whatsapp.*、channels.telegram.* 等）用于上限和流式传输开关。 完整 schema 参见配置。 入站去重 渠道可能在重新连接后重复投递同一消息。OpenClaw 保持一个短期缓存，以渠道/账户/对端/会话/消息 ID 为键，因此重复投递不会触发另一次智能体运行。 入站防抖 来自同一发送者的快速连续消息可以通过 messages.inbound 批量合并为单个智能体轮次。防抖按渠道 + 会话为范围，并使用最近的消息进行回复线程/ID 处理。 配置（全局默认 + 单渠道覆盖）： { messages: { inbound: { debounceMs: 2000, byChannel: { whatsapp: 5000, slack: 1500, discord: 1500, }, }, }, } 注意事项： 防抖仅适用于纯文本消息；媒体/附件会立即刷新。 控制命令会绕过防抖，保持独立。 会话和设备 会话由 Gateway 网关拥有，而非客户端。 直接聊天合并到智能体主会话密钥。 群组/渠道获得各自的会话密钥。 会话存储和记录保存在 Gateway 网关主机上。 多个设备/渠道可以映射到同一会话，但历史记录不会完全同步回每个客户端。建议：对长对话使用一个主设备，以避免上下文分歧。控制 UI 和 TUI 始终显示 Gateway 网关支持的会话记录，因此它们是事实来源。 ...

OpenClaw 为每次智能体运行构建自定义系统提示词。该提示词由 OpenClaw 拥有，不使用 pi-coding-agent 默认提示词。 该提示词由 OpenClaw 组装并注入到每次智能体运行中。 结构 该提示词设计紧凑，使用固定部分： Tooling：当前工具列表 + 简短描述。 Safety：简短的防护提醒，避免追求权力的行为或绕过监督。 Skills（如果可用）：告诉模型如何按需加载 Skill 指令。 OpenClaw Self-Update：如何运行 config.apply 和 update.run。 Workspace：工作目录（agents.defaults.workspace）。 Documentation：OpenClaw 文档的本地路径（仓库或 npm 包）以及何时阅读它们。 Workspace Files (injected)：表示下方包含引导文件。 Sandbox（启用时）：表示沙箱隔离运行时、沙箱路径，以及是否可用提权执行。 Current Date & Time：用户本地时间、时区和时间格式。 Reply Tags：支持的提供商的可选回复标签语法。 Heartbeats：心跳提示词和确认行为。 Runtime：主机、操作系统、node、模型、仓库根目录（检测到时）、思考级别（一行）。 Reasoning：当前可见性级别 + /reasoning 切换提示。 系统提示词中的安全防护是建议性的。它们指导模型行为但不强制执行策略。使用工具策略、执行审批、沙箱隔离和渠道允许列表进行硬性执行；运维人员可以按设计禁用这些。 提示词模式 OpenClaw 可以为子智能体渲染更小的系统提示词。运行时为每次运行设置一个 promptMode（不是面向用户的配置）： full（默认）：包含上述所有部分。 minimal：用于子智能体；省略 Skills、Memory Recall、OpenClaw Self-Update、Model Aliases、User Identity、Reply Tags、Messaging、Silent Replies 和 Heartbeats。Tooling、Safety、Workspace、Sandbox、Current Date & Time（已知时）、Runtime 和注入的上下文仍然可用。 none：仅返回基本身份行。 当 promptMode=minimal 时，额外注入的提示词标记为 Subagent Context 而不是 Group Chat Context。 ...

OpenClaw 记忆是智能体工作空间中的纯 Markdown 文件。这些文件是唯一的事实来源；模型只"记住"写入磁盘的内容。 记忆搜索工具由活动的记忆插件提供（默认：memory-core）。使用 plugins.slots.memory = "none" 禁用记忆插件。 记忆文件（Markdown） 默认工作空间布局使用两个记忆层： memory/YYYY-MM-DD.md 每日日志（仅追加）。 在会话开始时读取今天和昨天的内容。 MEMORY.md（可选） 精心整理的长期记忆。 仅在主要的私人会话中加载（绝不在群组上下文中加载）。 这些文件位于工作空间下（agents.defaults.workspace，默认 ~/.openclaw/workspace）。完整布局参见智能体工作空间。 何时写入记忆 决策、偏好和持久性事实写入 MEMORY.md。 日常笔记和运行上下文写入 memory/YYYY-MM-DD.md。 如果有人说"记住这个"，就写下来（不要只保存在内存中）。 这个领域仍在发展中。提醒模型存储记忆会有帮助；它会知道该怎么做。 如果你想让某些内容持久保存，请要求机器人将其写入记忆。 自动记忆刷新（压缩前触发） 当会话接近自动压缩时，OpenClaw 会触发一个静默的智能体回合，提醒模型在上下文被压缩之前写入持久记忆。默认提示明确说明模型可以回复，但通常 NO_REPLY 是正确的响应，因此用户永远不会看到这个回合。 这由 agents.defaults.compaction.memoryFlush 控制： { agents: { defaults: { compaction: { reserveTokensFloor: 20000, memoryFlush: { enabled: true, softThresholdTokens: 4000, 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.", }, }, }, }, } 详情： ...

在运行活跃期间，输入指示器会发送到聊天渠道。使用 agents.defaults.typingMode 控制输入指示器何时开始显示，使用 typingIntervalSeconds 控制刷新频率。 默认行为 当 agents.defaults.typingMode 未设置时，OpenClaw 保持旧版行为： 私聊：模型循环开始后立即显示输入指示器。 群聊中被提及：立即显示输入指示器。 群聊中未被提及：仅在消息文本开始流式传输时显示输入指示器。 心跳运行：输入指示器禁用。 模式 将 agents.defaults.typingMode 设置为以下值之一： never — 永远不显示输入指示器。 instant — 模型循环开始后立即显示输入指示器，即使运行最终只返回静默回复令牌。 thinking — 在第一个推理增量时开始显示输入指示器（需要运行时设置 reasoningLevel: "stream"）。 message — 在第一个非静默文本增量时开始显示输入指示器（忽略 NO_REPLY 静默令牌）。 触发时机从晚到早的顺序： never → message → thinking → instant 配置 { agent: { typingMode: "thinking", typingIntervalSeconds: 6, }, } 可以按会话覆盖模式或刷新频率： { session: { typingMode: "message", typingIntervalSeconds: 4, }, } 注意事项 message 模式不会为纯静默回复显示输入指示器（例如用于抑制输出的 NO_REPLY 令牌）。 thinking 仅在运行流式传输推理时触发（reasoningLevel: "stream"）。 如果模型未产生推理增量，则不会显示输入指示器。 无论使用何种模式，心跳运行都不会显示输入指示器。 typingIntervalSeconds 控制的是刷新频率，而非开始时间。 默认值为 6 秒。

目标 按 HTTP 请求重试，而非按多步骤流程重试。 通过仅重试当前步骤来保持顺序。 避免重复执行非幂等操作。 默认值 尝试次数：3 最大延迟上限：30000 毫秒 抖动：0.1（10%） 提供商默认值： Telegram 最小延迟：400 毫秒 Discord 最小延迟：500 毫秒 行为 Discord 仅在速率限制错误（HTTP 429）时重试。 可用时使用 Discord retry_after，否则使用指数退避。 Telegram 在瞬态错误时重试（429、超时、连接/重置/关闭、暂时不可用）。 可用时使用 retry_after，否则使用指数退避。 Markdown 解析错误不会重试；会回退为纯文本。 配置 在 ~/.openclaw/openclaw.json 中按提供商设置重试策略： { channels: { telegram: { retry: { attempts: 3, minDelayMs: 400, maxDelayMs: 30000, jitter: 0.1, }, }, discord: { retry: { attempts: 3, minDelayMs: 500, maxDelayMs: 30000, jitter: 0.1, }, }, }, } 注意事项 重试按请求应用（消息发送、媒体上传、表情回应、投票、贴纸）。 组合流程不会重试已完成的步骤。