TOPIC / RESOURCE
OpenClaw 排障入口：先缩成一层，再判断哪里坏了
这页不是问题大全，而是一个 OpenClaw 故障分诊台。先把安装部署、模型配置、渠道接入、认证鉴权、doctor 检查、Docker 环境这些常见故障逐层归类，快速收敛问题范围后再决定下一步去哪里修，避免在大量报错信息里盲目搜索浪费时间。
适合谁
- 安装好了但不能用，或者不确定坏在哪一层
- 想先把问题缩成安装、模型、渠道、认证或 Docker
- 希望先用 doctor 和最小动作收敛，而不是直接重装
先别乱重装，先收敛问题层
第一次排障时最值的动作不是重装，而是先判断：坏在安装、模型、渠道、认证、doctor 还是 Docker。
一组最小排障命令
先把这组命令记住：
openclaw doctor
openclaw doctor --repair
openclaw gateway restart
openclaw logs --follow
再补两个很常见的基础检查：
node -v
npm -v
python3 -m json.tool openclaw.json
安装失败
常见表现：
- 依赖装不下来
- 版本不兼容
- Node 环境不对
第一步动作：
先回到系统要求和工具版本，不要直接往下猜。
端口被占用
常见表现：
- 服务起不来
- 启动日志里提示端口已被占用
第一步动作：
lsof -i :8080
先确认是不是旧进程还没停掉，再决定换端口还是清理旧进程。
版本不对
常见表现：
- 旧教程里的命令现在不适用
- 配置字段和你看到的不一样
第一步动作：
先核对当前版本和官方文档，而不是先沿用旧笔记。
环境变量没生效
常见表现：
- 模型 key 明明配过，但程序仍说没找到
第一步动作：
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY
如果输出为空，先解决环境变量，再继续看模型页。
模型没配好
常见表现：
- 机器人能聊天，但一做真实任务就失败
- 模型注册了，但调用不稳定
第一步动作：
先判断是“没有模型”还是“模型能见但不可用”。
渠道不触发
常见表现：
- 机器人在聊天列表里能看到
- 但消息不回，或者只偶尔回
第一步动作：
先把问题缩成最小消息闭环，不要同时测技能和复杂工作流。
认证问题
常见表现：
- 看起来服务起来了，但入口就是不稳
- 或者别人能碰到不该碰到的入口
第一步动作：
先回到认证模式和网关入口，不要先怪模型。
doctor 报错
更应该理解为：
- 它帮你缩范围
- 它帮你看当前哪一层最不对
而不是：
- 它一定会自动帮你修好一切
Docker 问题
Docker 相关问题最容易同时混入：
- 路径问题
- 环境变量问题
- 文件权限问题
这类问题第一步不要猜。
先确认容器里看到的路径和你以为的一样。
Docker 里访问宿主机服务失败
更常见的误区是继续写 localhost。
如果你在容器里访问宿主机数据库或服务，先确认自己是否应该改成：
host.docker.internal- 或当前宿主机桥接地址
文件规则没生效
常见表现：
- 你明明写了
AGENTS.md、SOUL.md - 但机器人还是像没看见一样
第一步动作：
- 先核对文件名大小写
- 先核对目录位置
- 先确认重启后是否重新加载
一份够用的排障顺序
排障顺序
1. 先缩成一层：安装 / 模型 / 渠道 / 认证 / Docker
2. 先跑最小命令：doctor
3. 再决定要不要 repair
4. 再看 gateway 是否需要重启
5. 只有都救不回来时，再考虑重装
下一步建议
相关链接
FAQ
本页常见问题
因为第一次排障最重要的是先收敛问题层级，而不是在一大堆报错里盲找相似句子。
不一定。它更像先帮你定位和收敛问题，而不是万能修复器。