21. 常见问题排查：启动失败、连不上、AI 变哑巴

本节目标：学会按”症状”快速定位 OpenClaw 的常见故障，拿起几条命令就能自己修好大部分问题。

OpenClaw 跑久了，难免遇到几种典型状况：网关起不来、渠道收不到消息、AI 突然不回话、改了配置没反应。这一章按症状来讲，你对着现象找对策就行。

Note

本书基于 2026.7.1-2 版本撰写。如果你手上的命令输出略有不同，以官方文档为准，必要时联网核对。

先跑这条命令阶梯

不管什么毛病，先按顺序敲这几条，能解决八成问题：

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

健康信号长这样：gateway status 显示 Runtime: running、Connectivity probe: ok；doctor 没有任何阻断项。如果一眼看不出问题，再往下翻对应小节。

启动失败：网关起不来

最常见的两种报错。

配置被拒（Invalid config）。 网关启动失败，日志出现 Invalid config at ...。先校验：

openclaw config file
openclaw config validate
openclaw doctor

OpenClaw 不会擅自改坏你的 openclaw.json。热重载时发现配置不合法，会跳过这次外部编辑、保留正在跑的配置。修复办法通常是 openclaw doctor --fix，它会把损坏的编辑另存为 .clobbered.* 文件，并恢复上一份可用配置。手改配置时，记得保留完整的 JSON，不要只贴其中一段。

服务装了但进程留不住。 gateway status 显示 Runtime: stopped。常见原因：

gateway.mode 没设成 local，配置被覆盖丢了这一项。
非回环绑定（lan / tailnet / custom）却没有配网关鉴权。
端口被占用，日志里有 EADDRINUSE。

Tip

端口冲突时，先 openclaw gateway status --deep 看是不是有残留的旧服务在占着 18789。必要时 openclaw gateway install --force 重装服务再 openclaw gateway restart。

渠道连不上：消息收不到

网关是好的，但某个聊天渠道一直连不上。先确认不是”插件没加载”：

openclaw status --all
openclaw doctor --fix
openclaw gateway restart

如果日志里有 plugin load failed: dependency tree corrupted，说明渠道配置还在，但插件依赖树坏了。doctor --fix 会清理过期的依赖软链和鉴权残留，重启后重新加载。

不同渠道有各自的典型症状，举几个常见的：

Telegram：getMe returned 401 多半是 BotFather 的 token 失效，重新填 botToken 或环境变量 TELEGRAM_BOT_TOKEN。
WhatsApp：QR 登录超时（408）常是代理环境变量（HTTP_PROXY / HTTPS_PROXY）不对。
Discord：机器人”在线但不回群”，检查服务器/频道是否在允许名单里，或者是否需要 @ 提及。

Note

渠道显示”已连接”但消息不流动，多半是策略问题，不是网络问题。看下面”AI 变哑巴”一节。

AI 变”哑巴”：有消息但没回复

渠道连上了，你发消息却没反应。先查路由和权限，别急着重连：

openclaw status
openclaw channels status --probe
openclaw pairing list <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

日志里几个关键词对应不同原因：

drop guild message (mention required → 群里没 @ 它，被忽略。
pairing request → 发消息的人还没通过配对审批。
blocked / allowlist → 发送者被策略过滤了。

解决思路：去 openclaw.json 里把 dmPolicy 设成 pairing 或收紧 allowFrom；群里设置 requireMention: false 或记得 @ 它；开放 DM 时优先用配对而非 open。

Tip

多人都能给机器人发私信时，把 session.dmScope 设成 per-channel-peer，让每个人的会话互不串台，也更安全。

配置改了不生效

你改了 openclaw.json，重启也试了，行为还是老样子。先确认配置本身合法：

openclaw config validate
openclaw doctor

如果校验通过但还不生效，可能是”配置被另一个二进制写入”。OpenClaw 会在配置里记下 meta.lastTouchedVersion：只读命令能读新配置，但用更老的 openclaw 二进制去改服务是被拒绝的。出现这种情况，检查 PATH 是否指向了更新的安装：

which openclaw
openclaw --version
openclaw config get meta.lastTouchedVersion

which 指向旧版本的话，修正 PATH，再 openclaw gateway install --force 重装服务。

profile 隔离的坑

OpenClaw 支持用 OPENCLAW_PROFILE 同时跑多套隔离环境。每套环境有独立的配置目录和网关端口：

OPENCLAW_PROFILE=dev openclaw gateway --dev --reset

--dev 全局标记会把状态目录隔离到 ~/.openclaw-dev，网关端口改用 19001。容易踩的坑：

你以为在改 A 环境的配置，其实 openclaw 命令解析到 B 环境的 OPENCLAW_CONFIG_PATH。
控制台（Control UI）打不开，因为连的是默认 18789，而 dev 网关在 19001。
两套网关同时跑，端口打架。

Tip

不确定当前用的是哪套环境，先看 openclaw status 里的 profile 和端口，再决定改哪个 openclaw.json。

升级后突然出错

升级完网关起不来、渠道空了、或模型调用报 401，多半是配置漂移或新版本默认更严了：

openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

重点查三处：gateway.mode 是不是被改成了 remote；非回环绑定现在要求必须有鉴权；配对和设备身份状态有没有变化。拿不准就 openclaw doctor --fix，它会修掉过期的鉴权残留和损坏的插件依赖。

小结

排错思路就三步：先跑命令阶梯看健康信号，再按”启动 / 连接 / 回话 / 配置 / 环境”对号入座，最后用 doctor --fix 兜底。实在搞不定时，把日志导出成诊断包（见下一章），照着报错关键词去官方文档搜，基本都能解决。