【OpenClaw 从入门到精通】第 36 篇FAQ 与常见问题排查本系列定位零基础入门从安装配置到高级架构全覆盖。本篇你将学到最常见的问题与解决方案openclaw doctor诊断指南按类型分类的排查流程下面是本篇 FAQ 涵盖的问题分类总览OpenClaw FAQ安装问题Q1: command not foundQ2: Node.js 版本Q3: 端口占用模型/Provider 问题Q4: 401 / 不回复Q5: Failover 失效通道问题Q6: Telegram BotQ7: Discord BotQ8: Slack Bot沙箱问题Q9: 非 main 会话Gateway 问题Q10: 启动失败Q11: SSH 断开Q12: macOS 权限万能排查流程步骤 1-4一、安装问题Q1openclaw: command not found# 检查 PATHnpmconfig get prefixechoexport PATH$(npm config get prefix)/bin:$PATH~/.bashrcsource~/.bashrcQ2Node.js 版本太低node--version# 需要 24.15 / 22.22.3 / 25.9nvminstall24nvm use24Q3端口 18789 被占用lsof-i:18789# 查看占用openclaw gateway--port18790# 换端口二、模型/Provider 问题Q4模型不回复 / 401 错误openclaw doctor# 检查配置cat~/.openclaw/secrets/.env# 检查 API Keyopenclaw auth login--providerX# 重新 OAuth 登录Q5Failover 不工作openclaw auth list# 查看凭证池状态openclaw authadd# 添加新凭证三、通道问题Q6Telegram Bot 不回复openclaw gateway status# 检查通道连接greptelegram~/.openclaw/logs/gateway.log|tail-10openclaw gateway restartQ7Discord Bot 沉默检查 Developer PortalMESSAGE CONTENT INTENT 必须开启。Q8Slack Bot 只在 DM 中工作检查 Event Subscriptions必须订阅message.channels。四、沙箱问题Q9非 main 会话的工具不工作openclaw config get agents.defaults.sandbox# 检查 allow/deny 列表# 确认 Docker 可用docker ps五、Gateway 问题Q10Gateway 启动失败openclaw doctor--fix# 自动修复openclaw gateway--verbose# 前台查看错误Q11SSH 断开后 Gateway 停止sudologinctl enable-linger$USER# 启用 lingerQ12macOS 权限丢失macOS App 权限在重建后丢失 → 需要签名构建。使用官网正式版。六、万能排查流程# 步骤 1openclaw doctor# 步骤 2grep-ierror\|fail~/.openclaw/logs/*.log|tail-20# 步骤 3openclaw gateway restart# 步骤 4# 查看官方 FAQhttps://docs.openclaw.ai/help/faq下面是万能排查流程的可视化流程图是否是否是否遇到问题步骤 1: openclaw doctordoctor 是否报错?按 doctor 提示修复步骤 2: 检查日志grep error/fail 日志日志中有错误?根据日志定位修复步骤 3: 重启 Gatewayopenclaw gateway restart问题解决?✅ 问题解决步骤 4: 查阅官方 FAQdocs.openclaw.ai/help/faq社区/Issue 求助模块八总结篇主题核心收获31Gateway 运维Daemon / 日志 / doctor / Tailscale32安全加固DM Runbook / 沙箱 / 密钥 / 安全清单33远程访问Tailscale / WebChat / SSH 控制34开发实战编码 / 审查 / Git / Canvas35运维实战监控 / 日志 / Docker / Canvas 看板36FAQ分类排查 / 万能流程下篇预告附录 ACLI 命令完整速查手册如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。