Discord

Discord 支持智能体输出中的回复标签：

• [[reply_to_current]]
• [[reply_to:<id>]]

由 channels.discord.replyToMode 控制：

• off（默认）
• first
• all
• batched

注意：off 会禁用隐式回复串联。显式 [[reply_to_*]] 标签仍会被遵循。 first 始终将隐式原生回复引用附加到该轮的第一条出站 Discord 消息。 batched 仅在入站轮次是多条消息经防抖后组成的批次时，才会附加 Discord 的隐式原生回复引用。若你主要希望在含义不明确的突发聊天中使用原生回复，而不是每个单消息轮次都使用，这会很有用。

消息 ID 会出现在上下文/历史中，便于智能体定位特定消息。

OpenClaw 可以通过发送临时消息并在文本到达时编辑它来流式传输草稿回复。channels.discord.streaming 接受 off | partial | block | progress（默认）。progress 会保留一条可编辑的 Status 草稿，并用工具进度更新它，直到最终投递；streamMode 是旧版运行时别名。运行 openclaw doctor --fix 可将持久化配置改写为规范键。

将 channels.discord.streaming.mode 设置为 off 可禁用 Discord 预览编辑。如果显式启用了 Discord 分块流式传输，OpenClaw 会跳过预览流，以避免重复流式传输。

{
channels: {
discord: {
  streaming: {
    mode: "progress",
    progress: {
      label: "auto",
      maxLines: 8,
      toolProgress: true,
    },
  },
},
},
}

• partial 会在 token 到达时编辑单条预览消息。
• block 会发出草稿大小的分块（使用 draftChunk 调整大小和断点，并受 textChunkLimit 限制）。
• 媒体、错误和显式回复的最终消息会取消待处理的预览编辑。
• streaming.preview.toolProgress（默认 true）控制工具/进度更新是否复用预览消息。
• streaming.preview.commandText / streaming.progress.commandText 控制紧凑进度行中的命令/执行详情：raw（默认）或 status（仅工具标签）。

隐藏原始命令/执行文本，同时保留紧凑进度行：

{
  "channels": {
    "discord": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

预览流式传输仅支持文本；媒体回复会回退到正常投递。当显式启用 block 流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。

公会历史上下文：

• channels.discord.historyLimit 默认 20
• 回退项：messages.groupChat.historyLimit
• 0 禁用

私信历史控制项：

• channels.discord.dmHistoryLimit
• channels.discord.dms["<user_id>"].historyLimit

线程行为：

• Discord 线程会作为渠道会话路由，并继承父渠道配置，除非被覆盖。
• 线程会话会继承父渠道的会话级 /model 选择，作为仅模型的回退；线程本地的 /model 选择仍优先，并且父转录历史不会被复制，除非启用了转录继承。
• channels.discord.thread.inheritParent（默认 false）会让新的自动线程从父转录开始播种。按账号覆盖位于 channels.discord.accounts.<id>.thread.inheritParent 下。
• 消息工具反应可以解析 user:<id> 私信目标。
• guilds.<guild>.channels.<channel>.requireMention: false 会在回复阶段激活回退期间保留。

渠道主题会作为不受信任的上下文注入。Allowlists 控制谁可以触发智能体，并不是完整的补充上下文脱敏边界。

Discord 可以将线程绑定到会话目标，使该线程中的后续消息继续路由到同一会话（包括子智能体会话）。

命令：

• /focus <target> 将当前/新线程绑定到子智能体/会话目标
• /unfocus 移除当前线程绑定
• /agents 显示活动运行和绑定状态
• /session idle <duration|off> 检查/更新聚焦绑定的不活动自动取消聚焦时间
• /session max-age <duration|off> 检查/更新聚焦绑定的硬性最大时长

配置：

{
session: {
threadBindings: {
  enabled: true,
  idleHours: 24,
  maxAgeHours: 0,
},
},
channels: {
discord: {
  threadBindings: {
    enabled: true,
    idleHours: 24,
    maxAgeHours: 0,
    spawnSessions: true,
    defaultSpawnContext: "fork",
  },
},
},
}

注意：

• session.threadBindings.* 设置全局默认值。
• channels.discord.threadBindings.* 覆盖 Discord 行为。
• spawnSessions 控制为 sessions_spawn({ thread: true }) 和 ACP 线程生成自动创建/绑定线程。默认：true。
• defaultSpawnContext 控制线程绑定生成的原生子智能体上下文。默认："fork"。
• 已弃用的 spawnSubagentSessions/spawnAcpSessions 键会由 openclaw doctor --fix 迁移。
• 如果某个账号禁用了线程绑定，则 /focus 和相关线程绑定操作不可用。

请参阅子智能体、ACP 智能体和配置参考。

对于稳定的“始终在线”ACP 工作区，请配置面向 Discord 对话的顶层类型化 ACP 绑定。

配置路径：

• 带有 type: "acp" 和 match.channel: "discord" 的 bindings[]

示例：

{
agents: {
list: [
  {
    id: "codex",
    runtime: {
      type: "acp",
      acp: {
        agent: "codex",
        backend: "acpx",
        mode: "persistent",
        cwd: "/workspace/openclaw",
      },
    },
  },
],
},
bindings: [
{
  type: "acp",
  agentId: "codex",
  match: {
    channel: "discord",
    accountId: "default",
    peer: { kind: "channel", id: "222222222222222222" },
  },
  acp: { label: "codex-main" },
},
],
channels: {
discord: {
  guilds: {
    "111111111111111111": {
      channels: {
        "222222222222222222": {
          requireMention: false,
        },
      },
    },
  },
},
},
}

注意：

• /acp spawn codex --bind here 会就地绑定当前渠道或线程，并让未来消息保持在同一 ACP 会话中。线程消息会继承父渠道绑定。
• 在已绑定的渠道或线程中，/new 和 /reset 会就地重置同一 ACP 会话。临时线程绑定在活动时可以覆盖目标解析。
• spawnSessions 会门控通过 --thread auto|here 进行的子线程创建/绑定。

请参阅 ACP 智能体了解绑定行为详情。

按公会设置的反应通知模式：

• off
• own（默认）
• all
• allowlist（使用 guilds.<id>.users）

反应事件会被转换为系统事件，并附加到路由后的 Discord 会话。

ackReaction 会在 OpenClaw 处理入站消息时发送确认 emoji。

解析顺序：

• channels.discord.accounts.<accountId>.ackReaction
• channels.discord.ackReaction
• messages.ackReaction
• 智能体身份 emoji 回退（agents.list[].identity.emoji，否则为 "👀"）

注意：

• Discord 接受 unicode emoji 或自定义 emoji 名称。
• 使用 "" 可为渠道或账号禁用该反应。

渠道发起的配置写入默认启用。

这会影响 /config set|unset 流程（当命令功能启用时）。

禁用：

{
channels: {
discord: {
  configWrites: false,
},
},
}

通过带有 channels.discord.proxy 的 HTTP(S) 代理路由 Discord gateway WebSocket 流量和启动时 REST 查询（应用 ID + allowlist 解析）。

{
channels: {
discord: {
  proxy: "http://proxy.example:8080",
},
},
}

按账号覆盖：

{
channels: {
discord: {
  accounts: {
    primary: {
      proxy: "http://proxy.example:8080",
    },
  },
},
},
}

启用 PluralKit 解析，将代理消息映射到系统成员身份：

{
channels: {
discord: {
  pluralkit: {
    enabled: true,
    token: "pk_live_...", // optional; needed for private systems
  },
},
},
}

注意：

• allowlists 可以使用 pk:<memberId>
• 仅当 channels.discord.dangerouslyAllowNameMatching: true 时，成员显示名称才会按名称/slug 匹配
• 查询使用原始消息 ID，并受时间窗口约束
• 如果查询失败，代理消息会被视为机器人消息并丢弃，除非 allowBots=true

当智能体需要对已知 Discord 用户进行确定性的出站提及时，请使用 mentionAliases。键是不带前导 @ 的 handle；值是 Discord 用户 ID。未知 handle、@everyone、@here 以及 Markdown 代码跨度中的提及会保持不变。

{
channels: {
discord: {
  mentionAliases: {
    Vladislava: "123456789012345678",
  },
  accounts: {
    ops: {
      mentionAliases: {
        OpsLead: "234567890123456789",
      },
    },
  },
},
},
}

当你设置状态或活动字段，或启用自动在线状态时，会应用在线状态更新。

仅状态示例：

{
channels: {
discord: {
  status: "idle",
},
},
}

活动示例（自定义状态是默认活动类型）：

{
channels: {
discord: {
  activity: "Focus time",
  activityType: 4,
},
},
}

流式传输示例：

{
channels: {
discord: {
  activity: "Live coding",
  activityType: 1,
  activityUrl: "https://twitch.tv/openclaw",
},
},
}

活动类型映射：

• 0：Playing
• 1：Streaming（需要 activityUrl）
• 2：Listening
• 3：Watching
• 4：Custom（使用活动文本作为状态 state；emoji 可选）
• 5：Competing

自动在线状态示例（运行时健康信号）：

{
channels: {
discord: {
  autoPresence: {
    enabled: true,
    intervalMs: 30000,
    minUpdateIntervalMs: 15000,
    exhaustedText: "token exhausted",
  },
},
},
}

自动在线状态会将运行时可用性映射到 Discord 状态：healthy => online，degraded 或 unknown => idle，exhausted 或 unavailable => dnd。可选文本覆盖项：

• autoPresence.healthyText
• autoPresence.degradedText
• autoPresence.exhaustedText（支持 {reason} 占位符）

Discord 支持在私信中基于按钮处理审批，也可以选择在发起审批的渠道中发布审批提示。

配置路径：

• channels.discord.execApprovals.enabled
• channels.discord.execApprovals.approvers（可选；在可行时回退到 commands.ownerAllowFrom）
• channels.discord.execApprovals.target（dm | channel | both，默认值：dm）
• agentFilter、sessionFilter、cleanupAfterResolve

当 enabled 未设置或为 "auto"，且至少可以解析出一个审批人时，Discord 会自动启用原生 exec 审批；审批人可来自 execApprovals.approvers 或 commands.ownerAllowFrom。Discord 不会从渠道 allowFrom、旧版 dm.allowFrom 或私信 defaultTo 推断 exec 审批人。设置 enabled: false 可明确禁止 Discord 作为原生审批客户端。

对于 /diagnostics 和 /export-trajectory 等敏感的仅所有者可用群组命令，OpenClaw 会私下发送审批提示和最终结果。当调用命令的所有者有 Discord 所有者路由时，它会先尝试 Discord 私信；如果不可用，则回退到 commands.ownerAllowFrom 中第一个可用的所有者路由，例如 Telegram。

当 target 为 channel 或 both 时，审批提示会在渠道中可见。只有已解析的审批人可以使用按钮；其他用户会收到一条临时拒绝消息。审批提示包含命令文本，因此仅应在受信任的渠道中启用渠道投递。如果无法从会话键派生渠道 ID，OpenClaw 会回退到私信投递。

Discord 还会渲染其他聊天渠道使用的共享审批按钮。当这些按钮存在时，它们是主要的审批 UX；OpenClaw 仅应在工具结果表明聊天审批不可用，或手动审批是唯一路径时，才包含手动 /approve 命令。如果 Discord 原生审批运行时未激活，OpenClaw 会保持本地确定性的 /approve <id> <decision> 提示可见。如果运行时已激活，但原生卡片无法投递到任何目标，OpenClaw 会在同一聊天中发送回退通知，其中包含待处理审批中的确切 /approve 命令。

Gateway 网关认证和审批解析遵循共享 Gateway 网关客户端契约（plugin: ID 通过 plugin.approval.resolve 解析；其他 ID 通过 exec.approval.resolve 解析）。审批默认在 30 分钟后过期。

请参阅 Exec 审批。

• 启用 Message Content Intent
• 依赖用户/成员解析时，启用 Server Members Intent
• 更改 intent 后重启 Gateway 网关

• 检查 groupPolicy
• 检查 channels.discord.guilds 下的服务器允许列表
• 如果存在服务器 channels 映射，则仅允许列出的渠道
• 检查 requireMention 行为和提及模式

有用的检查：

openclaw doctor
openclaw channels status --probe
openclaw logs --follow

常见原因：

• groupPolicy="allowlist" 但没有匹配的服务器/渠道允许列表
• requireMention 配置在了错误位置（必须位于 channels.discord.guilds 或渠道条目下）
• 发送者被服务器/渠道 users 允许列表阻止

典型日志：

• Slow listener detected ...
• stuck session: sessionKey=agent:...:discord:... state=processing ...

Discord Gateway 网关队列参数：

• 单账号：channels.discord.eventQueue.listenerTimeout
• 多账号：channels.discord.accounts.<accountId>.eventQueue.listenerTimeout
• 这只控制 Discord Gateway 网关监听器工作，不控制智能体轮次生命周期

Discord 不会对排队的智能体轮次应用渠道拥有的超时。消息监听器会立即移交，排队的 Discord 运行会保留每个会话的顺序，直到会话/工具/运行时生命周期完成或中止该工作。

{
channels: {
discord: {
  accounts: {
    default: {
      eventQueue: {
        listenerTimeout: 120000,
      },
    },
  },
},
},
}

OpenClaw 会在连接前获取 Discord /gateway/bot 元数据。瞬时故障会回退到 Discord 的默认 Gateway 网关 URL，并在日志中限速记录。

元数据超时参数：

• 单账号：channels.discord.gatewayInfoTimeoutMs
• 多账号：channels.discord.accounts.<accountId>.gatewayInfoTimeoutMs
• 配置未设置时的环境变量回退：OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS
• 默认值：30000（30 秒），最大值：120000

OpenClaw 会在启动期间以及运行时重连后等待 Discord 的 Gateway 网关 READY 事件。带启动错峰的多账号设置可能需要比默认值更长的启动 READY 窗口。

READY 超时参数：

• 启动单账号：channels.discord.gatewayReadyTimeoutMs
• 启动多账号：channels.discord.accounts.<accountId>.gatewayReadyTimeoutMs
• 配置未设置时的启动环境变量回退：OPENCLAW_DISCORD_READY_TIMEOUT_MS
• 启动默认值：15000（15 秒），最大值：120000
• 运行时单账号：channels.discord.gatewayRuntimeReadyTimeoutMs
• 运行时多账号：channels.discord.accounts.<accountId>.gatewayRuntimeReadyTimeoutMs
• 配置未设置时的运行时环境变量回退：OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS
• 运行时默认值：30000（30 秒），最大值：120000

channels status --probe 权限检查只适用于数字渠道 ID。

如果你使用 slug 键，运行时匹配仍然可以工作，但 probe 无法完整验证权限。

• 私信已禁用：channels.discord.dm.enabled=false
• 私信策略已禁用：channels.discord.dmPolicy="disabled"（旧版：channels.discord.dm.policy）
• 在 pairing 模式下等待配对批准

默认情况下，会忽略机器人发送的消息。

如果你设置 channels.discord.allowBots=true，请使用严格的提及和允许列表规则，以避免循环行为。 优先使用 channels.discord.allowBots="mentions"，仅接受提及该机器人的机器人消息。

{
channels: {
discord: {
  accounts: {
    mantis: {
      // Mantis listens to other bots only when they mention her.
      allowBots: "mentions",
    },
    molty: {
      // Molty listens to all bot-authored Discord messages.
      allowBots: true,
      mentionAliases: {
        // Lets Molty write "@Mantis" and send a real Discord mention.
        Mantis: "MANTIS_DISCORD_USER_ID",
      },
    },
  },
},
},
}

• 保持 OpenClaw 为最新版本（openclaw update），以确保包含 Discord 语音接收恢复逻辑
• 确认 channels.discord.voice.daveEncryption=true（默认）
• 从 channels.discord.voice.decryptionFailureTolerance=24（上游默认值）开始，仅在需要时调优
• 查看日志中的：
  • discord voice: DAVE decrypt failures detected
  • discord voice: repeated decrypt failures; attempting rejoin
• 如果自动重新加入后故障仍然持续，请收集日志，并与 discord.js #11419 和 discord.js #11449 中的上游 DAVE 接收历史进行比较