Appearance
问题排查总索引
养龙虾遇到问题了？按症状找到对应排查页面。
编号格式
#NNNNN对应 GitHub issue 原帖，文档已按编号去重。
安装相关
| 症状 | 页面 | 编号 |
|---|---|---|
| Windows CLI 冷启动极慢（10-14 秒） | Windows 安装 | #30072 |
| 升级 3.12 后图片识别失效（sharp win32 模块） | Windows 安装 | #45343 |
| Docker 容器重启后无限登录循环 | Docker 部署 | #29955 |
| QNAP NAS / 非标准 Docker 部署 Gateway 卡死 | Docker 部署 | #30080 |
| 微信插件 2026.3.22+ 报 Cannot find module openclaw/plugin-sdk | 插件加载 | #52885 |
| WhatsApp 渠道在 2026.3.22 ~ 2026.3.23-1 完全无法启动 | 插件加载 | #53285 |
| extraDirs 自定义 Skill 不被加载（v2026.2.3+） | extraDirs Skill 不加载 | #10386 |
| npm 更新到 2026.4.5 后 CLI 报缺少依赖 @buape/carbon | npm 更新缺少依赖 | #61686 |
| Docker 容器内安装 Skill 报 brew not installed | Docker Skill brew 缺失 | #14593 |
| ARM64 上 doctor 报 @discordjs/opus 缺失且 --fix 无法恢复 | ARM64 opus 修复失败 | #64070 |
Gateway 启动 / 运行
| 症状 | 页面 | 编号 |
|---|---|---|
| [社区] Gateway 作为系统服务启动失败：环境变量未传递给服务进程 | Gateway 服务环境变量 | — |
| [社区] Cron 任务在列表中显示但从不执行：enabled、wakeMode 和 delivery.to 配置排查 | Cron 任务不执行排查 | — |
配置 auth token 后 CLI 报 token_mismatch | 认证 / Token | #38617 |
| 切换网络后 Gateway 崩溃（AssertionError，IPv4 undefined） | 网络 / 崩溃 | #38628 |
| macOS VPN 断线重连后 Gateway 不自动恢复 | 网络 / 崩溃 | #38682 |
openclaw stop 超时，Gateway 进程无法干净退出 | 网络 / 崩溃 | #38721 |
| Windows 上 gateway 每约50分钟自动重启，日志 reason=none | Gateway 周期重启排查 | #48205 |
| macOS LaunchAgent bootout 后 bootstrap 未执行导致 Gateway 永久停止 | macOS LaunchAgent Bootstrap 失败 | #40089 |
| 升级 v2026.4.5 后 Gateway 进程 CPU 占用 100% 无法恢复 | Gateway CPU 100% 升级问题 | #61701 |
渠道连接
| 症状 | 页面 | 编号 |
|---|---|---|
| [社区] Telegram 群组 Bot 无响应：BotFather privacy mode 和 pairing 审批排查 | Telegram 群组 Bot 不响应 | — |
| Telegram 消息在模型失败时被错误消息替换（edit-in-place 竞态） | Telegram 消息覆盖问题 | #19982 |
| Telegram 消息被重复接收和处理 | Telegram | #38681 |
| Telegram 消息不触发 Agent（WebChat 正常） | Telegram | #38606 |
| Telegram sendChatAction 瞬态错误后每 3 秒刷 ERROR 日志 | Telegram 重试日志刷屏 | #55811 |
| WhatsApp 渠道显示 Connected 但消息发送失败 | #38734 | |
| WhatsApp 群组 Agent 回复触发无限循环（fromMe echo） | #53386 | |
| WhatsApp 发出的消息在聊天界面重复出现 | #53729 | |
| 飞书渠道有处理日志但回复消息未发送到飞书 | 飞书 | #38686 |
| 飞书渠道报错：invalid config: must NOT have additional properties | 飞书配置错误 | #56883 |
| Discord 线程内发消息路由到当前线程而非目标频道 | Discord 消息路由错误 | #55841 |
| Groq 推理模型报 400：reasoning_effort 值不被接受 | Groq reasoning 400 错误 | #32638 |
| v2026.4.8+ 通过 HTTP 代理下载 Telegram 媒体失败 | Telegram 代理媒体下载失败 | #66245 |
| WhatsApp 语音消息绕过 STT 转录管道 | WhatsApp 语音转录绕过 | #63677 |
| Signal 群组 requireMention 无效，回复群内所有消息 | Signal 群组配置 | #29214 |
| Matrix 渠道未记录非@提及消息历史（historyLimit 未设置） | Matrix 聊天历史不完整 | #61000 |
| Matrix 渠道新建 Agent 有日志但完全无响应（autoJoin 未启用） | Matrix Agent 无响应 | #61351 |
| Gemini 思维链以非标准格式（...N>thought）泄漏到 Telegram | Gemini thought 泄漏变种 | #61350 |
| Telegram 发起任务后子代理完成通知错误路由到 Webchat，父代理无法继续 | 子代理通知 Telegram 路由问题 | #57385 |
| Slack socket-mode 连接变陈旧，ping/pong 超时并反复重启 | Slack Socket-mode 重启 | #64009 |
| assistant 返回 content=[] 且 usage=0 导致静默无回复（DeepSeek/Qwen/本地模型） | assistant 空回复静默 | #63689 |
提供商配置
| 症状 | 页面 | 编号 |
|---|---|---|
| GPT-5.4 context window 重启后不一致（200k/272k/1050k 三值不统一） | GPT-5.4 Context Window 不一致 | #69453 |
| 自定义 Anthropic 兼容 Provider 的 cacheRetention: long 静默回退到 5 分钟缓存 | cacheRetention long TTL 回退 | #67164 |
| models auth login --provider openai-codex 写入错误 profile 并破坏 agents.defaults.models 配置 | openai-codex auth login profile 错误 | #69414 |
| Kimi/SGLang 流式 tool-call arguments 格式异常导致工具调用分发失败 | Kimi/SGLang 工具调用分发失败 | #69672 |
| opencode-go 插件缺少 Qwen3.5 Plus / Qwen3.6 Plus 模型，报 FailoverError: Unknown model | opencode-go 模型目录缺失 | #67232 |
| Ollama 本地模型在配置 UI 中无法保存 | 本地模型 | #38563 |
| Cron 任务或子 Agent 提示 provider 未配置 | 本地模型 | #29886 |
AWS Bedrock 部分模型报 text field is blank | 云端模型 | #30117 |
| Memory Search 功能超时失败（中国大陆） | 云端模型 | #38503 |
| Kimi K-2.5 持续报 401 Invalid Authentication | 云端模型 | #46957 |
| Google OpenAI-compat 接口返回 400（store 字段不支持） | 云端模型 | #53658 |
| Windows 下 Google Gemini 认证失败：client_secret missing | Google 认证失败 | #30403 |
| Kimi k2p5 报错：Unexpected event order | Kimi API 故障 | #57523 |
| SecretRef 渠道 token 启动正常但回复时失效 | 密钥管理 | #45838 |
| 升级 pi-* 到 0.63.0 后自定义 Provider 报 No API key | 自定义 Provider | #55816 |
工具类（edit / memory / web_fetch）
| 症状 | 页面 | 编号 |
|---|---|---|
| edit 工具损坏丹麦字符（æ、ø、å）：UTF-8 编码问题排查 | edit 工具 UTF-8 编码损坏 | #69636 |
| edit 工具报 "failed" 但文件已被成功修改 | 工具问题 | #45770 |
| edit 工具频繁报 "Missing required parameters" | 工具问题 | #52164 |
| logging.file 配置不生效，日志仍写入 /tmp/openclaw/ 默认路径 | logging.file 不生效 | #56456 |
openclaw memory status 始终显示 0 files / 0 chunks | 工具问题 | #53558 |
| web_fetch 在 Clash/Mihomo TUN 模式下被 SSRF 检查拦截 | 工具问题 | #44527 |
| memory search 搜不到历史：indexer 跳过 .jsonl.reset 和 .deleted 文件 | Memory Indexer 跳过归档文件 | #57334 |
| memory 在 session-start 重建索引时静默丢失会话数据，status 仍显示正常 | Memory 重建索引静默丢数据 | #44028 |
| tasks audit 大量误报 inconsistent_timestamps（startedAt < createdAt） | Tasks Audit 时间戳误报 | #69229 |
| image tool 使用 Minimax VLM 模型报 invalid api key (2049) | Image Tool Minimax VLM 失败 | #66625 |
| memory-wiki bridge 模式 0 exported artifacts（未安装 QMD） | Memory-wiki Bridge 需要 QMD | #68371 |
| 升级到 2026.4.11+ 后 LLM request failed: provider rejected schema（Ollama/vLLM/Copilot） | LLM Schema 兼容性问题 | #65603 |
Web 控制界面
| 症状 | 页面 | 编号 |
|---|---|---|
| Control UI 静置后发消息报 HTTP 401 | Web 问题 | #25663 |
| Control UI 显示 "assets not found"，界面无法加载 | Web 问题 | #53672 |
| Control UI Skills 搜索框默认显示 WebSocket 地址 | Web 问题 | #53648 |
升级后聊天界面出现 <relevant-memories> 内容块 | Web 问题 | #53696 |
自动化（Cron / Webhook）
| 症状 | 页面 | 编号 |
|---|---|---|
| CronCreate 设置时区后任务仍按错误时间执行 | 自动化问题 | #53669 |
| subagents.runTimeoutSeconds 配置被 LLM 覆盖导致子代理超时过短 | 子代理超时下限修复 | #25810 |
openclaw cron list 报 WebSocket 握手超时（openclaw-weixin 插件引起） | Cron List WebSocket 超时 | #61554 |
通用调试命令
bash
openclaw status --all # 最全面的只读调试报告
openclaw health # Gateway 健康快照
openclaw doctor # 环境检查如需提交 issue，建议附上 openclaw status --all 的输出（注意脱敏 API Key）。
- secrets audit 误报 codex-app-server apiKey 为 PLAINTEXT_FOUND
- ACP client 未归还连接池导致每次发送冷启动，acp.runtime.ttlMinutes 配置失效
- Gemini final/think 标签泄漏到消息中（流式 + Control UI 双路径）
- memory_search 向量查询全表扫描性能问题（sqlite-vec KNN 未生效，190 倍优化空间）
- OpenRouter provider 使用错误 base URL（/v1 而非 /api/v1），请求静默失败 payloads=0
- Slack 多工作区配置下第二个工作区入站 DM 无法到达（#58523）
- Subagent sessions 内存无限累积，gateway RSS 增长 3GB+（#69628）
- WhatsApp Web session 登出后监听器永久死亡，需重启 gateway 才能恢复（#49305）
- [社区] OpenClaw Docker 部署：容器卷权限错误与 Telegram polling/webhook 冲突
- [社区] OpenClaw agent 个性与记忆文件配置：SOUL.md、AGENTS.md、MEMORY.md 完整指南