OpenClaw：踩坑与常见问题
目录
排障总览：先走这条路径
很多问题不是「OpenClaw 坏了」，而是「环境、权限或策略未对齐」。建议固定顺序：先 doctor → 再查渠道文档 → 再看日志。下面用一张流程图帮助自检：
权威排障入口：Channel troubleshooting、Logging。
安装与环境
Q：Node 版本不够新会怎样？
A：官方明确运行时版本要求；不满足时常见是安装成功但运行期报错。以 README 为准升级 Node，再重跑 openclaw doctor。若你在团队内推广，建议把「支持的 Node 版本」写进内部文档，避免同事用错版本。
Q：Windows 上路径很奇怪/脚本跑不通？
A：官方推荐 WSL2 作为 Windows 上的主路径；优先阅读 Getting started，不要在「未受支持组合」上硬扛。
Q：全局安装后命令找不到？
A：检查 PATH、是否多个包管理器混装、以及 shell 是否 reload。团队内建议统一用同一种全局安装方式。
Gateway 与守护进程
Q：Gateway 起不来或端口占用？
A：确认 --port 是否冲突；查看 verbose 日志；对照 Gateway 与 Logging。
Q：onboard 装了 daemon 但仍不常驻？
A：不同 OS 的 launchd/systemd 用户服务需要登录会话与权限；优先查官方 Updating 与排障文档，而不是先改业务配置。
Q：verbose 日志里信息太多，如何下手？
A：先截取「启动阶段」与「出错前 50 行」；同时记录：版本号、OS、Node 版本、最近是否改过配置。
渠道与配对
Q：陌生人能给 bot 发消息吗？
A：默认 DM 策略偏保守（配对/白名单）。若你发现「完全没响应」，先检查是否在等配对码，以及你是否执行了 openclaw pairing approve ...（见 README Security defaults）。
Q：群聊正常，私聊不正常？
A：群与 DM 的策略字段不同（Discord/Slack 等还有 legacy 字段名）；用 doctor 提示的风险项定位。
Q：为什么我建议“先不要急着开放 DM”？
A：DM 入站是典型攻击面：spam、钓鱼、诱导模型执行工具。若你业务确实需要开放，必须配套审计与工具白名单。
模型与鉴权
Q：提示无权限或模型不可用？
A：检查 openclaw.json 的 model 配置、provider OAuth/API Key，以及 failover 设置；以 Models 为准排查。
Q：回答质量忽高忽低？
A：先固定模型与 temperature/思考级别等参数，再谈提示词；个人助手场景下，工作区 AGENTS.md / Skills 往往比「单次 prompt 技巧」更有效。
工具权限与沙箱
Q：助手执行了危险操作？
A：默认安全叙事是「个人使用 main 会话可能等价于高权限」；引入他人前必须改策略，并启用/校验沙箱与工具白名单（见 README Security model）。
Q：沙箱里工具「少了」？
A：沙箱默认会限制高风险工具（README 给了典型 allow/deny 方向）；这是特性不是 bug，需要你显式评估风险后放开。
迁移与生态
Q：我和 Hermes-Agent 之间怎么选？
A：两者都是自托管助手生态，定位有重叠；Hermes 提供 hermes claw migrate 用于从 OpenClaw 迁移配置与数据（见 Hermes README）。建议先各自跑通最小闭环，再按「学习循环、工具链、渠道、运维习惯」做选型。
Q：资料以谁为准？
A：本知识库文章是学习地图；命令行、配置键、默认策略以你安装的版本 + 官方文档 + 仓库 README 为准。