跳到主要内容

常见问题

本文整理 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: 建议按下面排查：

  1. 通道配置：确认该通道的 Token、Webhook 或应用配置正确，且已在对应平台（如 Telegram、微信开放平台）完成开通与审核。
  2. 网络：若通道需要公网回调，确保网关所在机器可被访问（或已通过内网穿透/反向代理暴露正确 URL）；Webhook 需使用 HTTPS（多数平台要求）。
  3. 端口：确认 --port 与配置一致，且未被其他进程占用；防火墙/安全组是否放行该端口。
  4. 日志：查看网关与通道相关日志，是否有连接错误、认证失败或消息格式错误。

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。反馈问题时请提供版本、环境与复现步骤，便于维护者排查。

更多问题可查阅 官方文档 或项目 Issue；本站 开发指南、最佳实践 也可作为补充参考。