常见问题
本文整理 OpenClaw 使用与部署过程中的常见问题与解决思路，便于快速排错。按主题分为：安装与环境、网关与通道、多 Agent 与路由、安全与配对、模型与调用、部署与运维、技术与设计。
安装与环境
Q1: Node.js 版本要求是什么？
A: OpenClaw CLI 需要 Node.js >= 22。请使用 node -v 检查版本，若不符合可到 Node.js 官网 下载 LTS 版本并安装。推荐使用 22.x LTS 以获得更好兼容性。
Q2: 安装 openclaw-cn 后命令找不到？
A: 可能是全局安装路径未加入 PATH。可尝试：
- 使用
npx openclaw-cn代替直接运行openclaw-cn。 - 检查 npm 的 global prefix：
npm config get prefix，将该路径下的bin加入环境变量 PATH。 - 若使用 nvm 等版本管理，确认当前 Node 版本下已正确安装全局包。
Q3: 入门向导执行失败或卡住？
A: 请确认：
- 网络可访问安装脚本或 npm 源；若在国内可考虑配置镜像或代理。
- 当前用户对安装目录有写权限。
- 若在代理环境下，需正确配置
HTTP_PROXY/HTTPS_PROXY（如需要）。
仍无法解决时，查看完整报错信息，并到官方仓库或文档反馈；可同时尝试在另一目录或另一台机器上执行以排除环境问题。
Q4: 是否支持 Windows / macOS / Linux？
A: 官方通常支持主流操作系统；具体以 官方文档 或仓库说明为准。部分通道（如 iMessage）可能在特定系统上才有完整支持。
网关与通道
Q5: 网关启动后无法收到消息？
A: 建议按下面排查：
- 通道配置：确认该通道的 Token、Webhook 或应用配置正确，且已在对应平台（如 Telegram、微信开放平台）完成开通与审核。
- 网络：若通道需要公网回调，确保网关所在机器可被访问（或已通过内网穿透/反向代理暴露正确 URL）；Webhook 需使用 HTTPS（多数平台要求）。
- 端口：确认
--port与配置一致，且未被其他进程占用；防火墙/安全组是否放行该端口。 - 日志：查看网关与通道相关日志，是否有连接错误、认证失败或消息格式错误。
Q6: 如何更换模型或 API Key？
A: 通过入门向导可重新配置；若已安装完毕，一般通过修改配置文件或环境变量中的模型与 API Key 即可。修改后需重启网关使配置生效。具体配置项名称以当前版本文档为准。建议 Key 通过环境变量注入，不写进配置文件。
Q7: 支持哪些消息通道？
A: 常见支持包括：WhatsApp、Telegram、Discord、iMessage、微信、钉钉、飞书等。具体以 官方文档 或仓库说明为准，不同版本可能略有差异。新通道可能通过社区适配器或自研扩展支持。
Q8: 通道断线后会自动重连吗？
A: 网关通常具备通道断线重连逻辑；具体行为与重试策略以版本文档为准。若使用自研适配器，需自行实现重连与退避。
多 Agent 与路由
Q9: 如何配置多 Agent 与路由规则？
A: 在配置文件中配置多个 Agent（模型、系统提示词等），并在路由规则中指定：哪些渠道/用户/群组使用哪个 Agent。具体语法以当前版本文档为准；可参考 开发指南 与 最佳实践 中的路由示例。
Q10: 消息被路由到错误的 Agent 怎么办？
A: 检查路由规则是否重叠或顺序不当；匹配规则通常按顺序生效，先匹配到的先使用。确认默认 Agent 设置是否符合预期；必要时为规则添加更精确的匹配条件并重启网关。
安全与配对
Q11: 如何开启私信配对审批？
A: 在配置或入门向导中查找「配对」「审批」「私信安全」等选项，按说明开启。开启后，新用户首次私信可能需你在控制台或配置的界面中通过审批，通过后才会正常对话。具体入口以当前版本文档为准。
Q12: API Key 泄露了怎么办？
A: 立即在对应模型提供商控制台撤销或轮换该 Key，并在 OpenClaw 中更新为新的 Key，重启网关。若 Key 已提交到公开仓库，除轮换外建议评估是否有未授权调用并联系厂商支持；同时将 Key 从仓库历史中清理或使用密钥管理服务替代硬编码。
Q13: 如何避免敏感信息被提交到仓库？
A: 使用环境变量或加密配置存储 API Key、Token 等；配置文件仅保留非敏感项或使用模板文件（如 config.example.yaml），并在 .gitignore 中忽略含敏感信息的本地配置文件。
模型与调用
Q14: 支持哪些大模型？
A: 常见支持包括：Anthropic Claude、OpenAI、MiniMax、Moonshot（Kimi）、GLM 等。具体以 官方文档 为准。不同 Agent 可配置不同模 型，便于按场景或成本选择。
Q15: 模型调用超时或失败如何处理？
A: 在配置中设置合理超时与重试（若支持）；检查网络与 API Key 是否有效、是否触发厂商限频。可为 Agent 配置备用模型或降级策略，减少单点故障影响。
部署与运维
Q16: 如何让网关在服务器上常驻运行？
A: 可使用：
- 官方推荐的
openclaw-cn onboard --install-daemon安装的守护进程； - 或 systemd / supervisor 等，将
openclaw-cn gateway --port xxx配置为服务并设置开机自启。
具体服务名与命令以官方文档为准。部署后建议配合日志与监控，确保异常时能及时发现与恢复。
Q17: 云服务器上如何部署？
A: 部分云厂商（如阿里云）提供 OpenClaw（原 Moltbot）相关镜像，可在控制台搜索并一键部署。也可在任意云主机上按 快速开始 安装 Node.js 与 CLI，再按上述方式常驻运行网关。注意安全组与防火墙仅开放必要端口，并使用环境变量或云厂商密钥管理注入敏感信息。
Q18: 如何备份与迁移？
A: 定期备份配置文件与持久化数据（若有）；迁移时在新环境安装 CLI、恢复配置与数据、重新配置或注入环境变量后启动网关。若使用容器，可将配置与数据挂载到卷，便于跨主机迁移。
技术与设计
Q19: OpenClaw 与 MCP / agent_skills 有什么关系？
A: OpenClaw 侧重「消息通道 + AI 代理」的一体化平台；MCP、agent_skills 侧重工具与技能协议。OpenClaw 的 Agent 可对接 MCP/agent_skills，将外部工具或技能暴露给大模型，三者可配合使用；详见 入门介绍 中「与其他技术 的关系」。
Q20: 如何参与贡献或反馈问题？
A: 在 GitHub 上查找 OpenClaw 官方仓库，阅读 CONTRIBUTING 与代码规范后提交 Issue 或 PR。反馈问题时请提供版本、环境与复现步骤，便于维护者排查。