问题排查总索引 #
养龙虾遇到问题了？按症状找到对应排查页面。
编号格式 #NNNNN 对应 GitHub issue 原帖，文档已按编号去重。
如果你不是来查某个 issue，而是在配置 OpenClaw，可以先走这几个入口：
安装相关 #
| 症状 |
页面 |
编号 |
| 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 启动 / 运行 #
渠道连接 #
提供商配置 #
Provider 问题通常先分清三类：OpenAI 原生、OpenAI Codex OAuth、OpenRouter 兼容路由。配置步骤分别见 OpenAI provider 和 OpenRouter provider。
| 症状 |
页面 |
编号 |
| 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 |
| OpenRouter provider 使用错误 base URL（/v1 而非 /api/v1），请求静默失败 payloads=0 |
OpenRouter base URL 错误 |
— |
| 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 |
通用调试命令 #
openclaw status --all # 最全面的只读调试报告
openclaw health # Gateway 健康快照
openclaw doctor # 环境检查
如需提交 issue，建议附上 openclaw status --all 的输出（注意脱敏 API Key）。