01. 三类痛点：语音跟不进频道、无头 xAI 登录失败、Policy doctor 新增项

1）Discord 文字能回、语音却「像没装频道」：v2026.5.20 把实时语音与文字频道拆开演进：voice.followUsers 让 bot 跟随指定用户进语音频道，并带 allowed-channel 校验、多用户 handoff 与 DAVE 恢复。若你只验收过文字配对与 Allowlist，会误以为「Discord 已通」——语音合格信号是用户进语音 → bot 跟随进同一 allowed 频道 → STT/路由有日志，而不是 channels status 里 discord 显示 configured。

2）VPS/SSH 上 xAI OAuth 卡在 localhost 回调：5.20 新增 xai-device-code：Gateway 打印 xAI 验证 URL 与短码，操作者在任意浏览器完成授权，远端进程轮询换 token。仍用 loopback OAuth 却未做端口转发时，会表现为「登录命令挂起」——这与 API Key 缺失、模型列表空是不同分诊轴，应优先对照官方 openclaw models auth login --provider xai --device-code 路径。

3）Policy 插件让 doctor 多出「合规 / 修复」类条目：捆绑 Policy 插件对频道配置做策略级 conformance check、doctor lint，并支持可选 workspace repair。误操作是一见到 lint 就全局自动修复生产目录；Runbook 应在按天租用隔离机上先 dry-run，再决定是否 opt-in repair。

02. v2026.5.20 决策矩阵：Discord 语音 / xAI / Policy

能力面（5.20）	通过信号	短租 macOS 证据
Discord `voice.followUsers`	配置用户 ID 后进语音，bot 进入同一 allowed 频道；handoff 有界	保存 Gateway 语音段日志（脱敏）+ `channels status --channel discord`
`voice.realtime.bootstrapContextFiles`	默认注入 IDENTITY/USER/SOUL；设 `[]` 可关闭；人格与路由 agent 一致	对比开关前后首轮语音回复是否「丢人设」
xAI device-code OAuth	`models auth login --device-code` 完成后有 `xai/oauth` profile；推理 smoke 通过	SSH 会话完整保存 URL/轮询退出码（勿提交 token）
Policy 插件 doctor	lint 项有文档引用；repair 仅在隔离环境 opt-in	`openclaw doctor` 前后 diff（脱敏）
OpenRouter `params.provider`	provider 级路由策略生效；agent/model 参数可覆盖	保存一次路由请求 ID 与模型别名（无密钥）

与 v2026.5.12 模块化插件相邻：5.20 不替代「按需装频道插件」，而是在已装 Discord 插件前提下叠加语音与 realtime 配置。与命令报错大全相邻：Exec approvals 在 5.20 移除旧 SKILL.md cat 兼容路径，技能须走 read 工具——若语音 agent 仍依赖旧 allowlist，会表现为「工具拒绝」而非 STT 失败。

Discord 语音关键配置示例

# openclaw.json 片段（字段名以你安装的 5.20 文档为准）
{
  "channels": { "discord": { "enabled": true } },
  "voice": {
    "followUsers": ["<discord-user-snowflake>"],
    "realtime": {
      "bootstrapContextFiles": ["IDENTITY.md", "USER.md", "SOUL.md"],
      "toolPolicy": "owner",
      "agentConsult": "always"
    }
  }
}

agent-proxy 模式下 Discord 语音拥有播放权，consult 全工具策略默认对 owner 说话者开放；多路 consult 答案排队而非中途截断——验收时要测连续两句指令是否丢后半句。

03. 七步落地：升级 → followUsers → bootstrapContext → device-code → Policy → 验收 → 擦除

冻结基线：openclaw --version、openclaw channels status --json、现有 xAI/OpenRouter 鉴权 profile；确认 Gateway 监听与 Discord bot 权限（Connect/Speak 等）。
备份与升级到 5.20：按安装指南执行 openclaw update；保存 stdout。GitHub Release 标注发布于 2026-05-21，可作为变更审计锚点。
配置 voice.followUsers：仅列入需要跟进的 Discord 用户；核对 allowed-channel 列表，避免 bot 跟入未授权语音房。
调 bootstrapContextFiles：默认三文件注入 realtime 指令；若语音回复过长或泄露 workspace 细节，可改为子集或 []，但需接受「快回合丢人设」权衡。
无头 xAI 授权：在 SSH/VPS 执行 openclaw models auth login --provider xai --device-code [--set-default]；在本地浏览器完成 x.ai 设备码页面；禁止把 token 写入聊天日志。
Policy doctor：openclaw doctor 审阅 Policy 插件 conformance；仅在隔离机尝试 opt-in workspace repair；生产只应用已评审 diff。
交叉验收与擦除：openclaw channels status --probe；语音实测 + 一条 xAI 推理 smoke；租机删除 OAuth state、Discord bot 演示 token 与临时 openclaw.json 副本。

openclaw --version
openclaw channels status --json 2>&1 | tee /tmp/oc520-ch-before.json
openclaw backup create   # 若环境已启用

openclaw update
openclaw gateway restart

openclaw models auth login --provider xai --device-code --set-default
openclaw infer model run --local --model xai/grok-4.3 --prompt 'Reply: oc520-ok'

openclaw doctor 2>&1 | tee /tmp/oc520-doctor.txt
openclaw channels status --probe

04. 分诊表：症状 → 优先动作 → 误操作

症状	优先动作	常见误操作
用户进语音，bot 不进房	查 `followUsers` snowflake、bot Connect 权限、allowed-channel	重配文字 Allowlist 一整晚
语音「有人设」但工具不执行	区分 realtime 快回合 vs `openclaw_agent_consult`；查 Exec approvals 与 read 工具路径	关闭 bootstrap 误当成工具坏
xAI login 一直 polling	确认已在浏览器提交设备码；查时钟漂移与出站 HTTPS	在 VPS 上硬开 localhost 回调而不转发
doctor Policy 报 repair 可用	先读 lint 说明；隔离机试 repair；生产走变更单	直接对生产 workspace 一键修复
OpenRouter 路由不符合预期	核对 `params.provider` 层级覆盖顺序	只改 agent 默认模型名

05. 三条数据、误区与 1～3 日按天租用 macOS 日程

数据 1：GitHub v2026.5.20 于 2026-05-21 发布， Highlights 含 Discord voice follow、bootstrapContext、Policy 插件、xAI device-code、OpenRouter provider 路由等，可作为版本对齐凭证。
数据 2：官方 xAI 文档明确：SSH/Docker/VPS 应优先 --device-code；loopback OAuth 默认 127.0.0.1:56121，无转发时 headless 成功率接近零——这不是「网络坏了」而是鉴权路径选错。
数据 3：团队在 M4 按天租用机上把「5.20 升级 + 语音实测 + device-code + doctor」压进单会话 3～5 小时（相对跨三机复制日志的 1～2 日），前提是 Discord 插件与 Node 22.19+ 已就绪。

误区 A：把语音问题当文字频道 pairing 问题。误区 B：在 production 上首次试 Policy repair。误区 C：bootstrap 文件过大导致 realtime token 爆顶，却去降模型 IQ。

第 1 日：升级 5.20、跑 doctor、完成 device-code（若用 Grok）；傍晚配置 followUsers 并做一次进房跟随。

第 2 日：调 bootstrapContextFiles A/B；OpenRouter 路由抽测；保存脱敏证据链。

第 3 日：回滚演练、擦除租机密钥、写生产切换窗口。带宽与 SSH 见 FAQ。

06. VPS 无头节点 vs 按天租 Mac：语音调试与 Control UI

纯 Linux VPS 适合长期跑 Gateway 与 device-code 轮询，但Discord 语音权限、浏览器里对照文档、以及 Control UI 里看 Sessions分散时，排错成本常高于短租。原生 macOS 让你把语音实测、doctor、OAuth 状态与 UI 放在同一证据链，再决定是否切生产。

虽然你可以用SSH + 端口转发 + 远程桌面完成大部分验收，但该组合更适合短期验证：当你要在 1～3 天内把「5.20 语音 + 无头 Grok + Policy lint」写成可交接 Runbook，并与团队主力机解耦，按天租用 Mac通常更顺畅——M4 节点对 realtime 与本地调试更稳定，维护成本低于自拼多台跳板机。套餐见价格页。