11-常见问题FAQ

11 常见问题FAQ 11 常见问题FAQ Modified June 10 Code block Plain Text 在 GitHub 上创建一个仓库，或者提交到 OpenClaw 的技能市场 https://github.com/openclaw/openclaw skills ⠀ Q71: 有中文社区吗？ ⠀ 说明： 有的。 ⠀ • GitHub Discussions（中英文都可以）：github.com/openclaw/openclaw/discussions • Discord 社区（有中文频道） • 微信群：关注 OpenClaw 公众号获取入群二维码 ⠀ Q72: 文档有错误怎么反馈？ ⠀ 解决方案： ⠀ • 直接在 GitHub 上提 Issue，标注 docs 标签 • 或者直接提 PR 修改文档 • OpenClaw 官方 Markdown 文档位于其 GitHub 仓库的 docs/ 目录 十、其他常见问题 ⠀ 📌 本节包含 7 个问题： Q73: 和 ChatGPT 的区别 | Q74: 支持哪些语言 | Q75: 多实例运行 | Q76: 是否收费 | Q77: 查看所有配置 | Q78: Gateway 和 Agent 关系 | Q79: 获取帮助 ⠀ Q73: OpenClaw 和 ChatGPT 有什么区别？ ⠀ 说明： 它们是完全不同的东西： ⠀ ⠀ 简单说：ChatGPT 是一个产品，OpenClaw 是一个让你构建自己 AI 助手的工具。 ⠀ Q74: OpenClaw 支持哪些语言？ ⠀ 说明： OpenClaw 本身是英文项目，但 AI 的回复语言取决于你使用的模型和系统提示词。 ⠀ Code block Plain Text 在 SOUL.md 中指定语言（编辑 /.openclaw/workspace/SOUL.md） 添加内容： 语言 请始终用中文回复 代码注释也使用中文 ⠀ 大多数主流模型（GPT 5.2、Claude、Gemini）都支持中文。本地模型推荐用 Qwen（通义千问）系列，中文能力最好。 ⠀ Q75: 一台机器能跑多个 OpenClaw 实例吗？ ⠀ 解决方案： ⠀ Code block Plain Text 可以，但需要用不同的端口和数据目录 实例 1 OPENCLAW HOME= /.openclaw 1 openclaw config set gateway.port 18789 OPENCLAW HOME= /.openclaw 1 openclaw gateway port 18789 实例 2 OPENCLAW HOME= /.openclaw 2 openclaw config set gateway.port 18790 OPENCLAW HOME= /.openclaw 2 openclaw gateway port 18790 Docker 方式更简单：跑多个容器，映射不同端口 ⠀ Q76: OpenClaw 会收费吗？ ⠀ 说明： OpenClaw 是开源项目（MIT 协议），永久免费。你需要付费的只有 AI 模型的 API 调用费用（如果你用云端模型的话）。用本地模型（Ollama）则完全零成本。 ⠀ Q77: 怎么查看当前的所有配置？ ⠀ 解决方案： ⠀ Code block Plain Text 查看所有配置 openclaw config get 查看特定配置项 openclaw config get providers openclaw config get channels openclaw config get agents.defaults.model 导出完整配置（备份用） 直接备份配置文件 cp /.openclaw/openclaw.json my config backup.json 从备份恢复 cp my config backup.json /.openclaw/openclaw.json ⠀ Q78: Gateway 和 Agent 是什么关系？ ⠀ 说明： ⠀ • Gateway 是消息网关，负责连接各个消息平台（WhatsApp、Telegram 等），接收和发送消息 • Agent 是 AI 智能体，负责理解消息、调用工具、生成回复 ⠀ 消息流程：用户 → 消息平台 → Gateway → Agent → 模型 API → Agent → Gateway → 消息平台 → 用户 ⠀ Gateway 是基础设施层，Agent 是业务逻辑层。一个 Gateway 可以服务多个 Agent。 ⠀ Q79: 遇到问题怎么获取帮助？ ⠀ 获取帮助的渠道（按推荐顺序）： ⠀ 1. 查看本 FAQ 文档 2. 查看官方文档 3. 搜索 GitHub Issues（可能别人遇到过同样的问题） 4. 在 GitHub Discussions 提问 5. 加入 Discord 社区实时交流 ⠀ 提问时请附上： • OpenClaw 版本（openclaw version） • Node.js 版本（node version） • 操作系统信息 • 相关日志（前台运行 openclaw gateway port 18789 verbose 查看） 十一、版本升级与迁移（v2026.3.28 → v2026.5.27） ⠀ 📌 本节包含 4 个问题： Q80: 升级要点 | Q81: 反向代理配置变更 | Q82: 插件白名单变更 | Q83: 性能提升 ⠀ Q80: 从 v2026.3.2x 升级到 v2026.5.27 有哪些注意事项？ ⠀ v2026.5.27 新增关注点：除了 v2026.4.24 的 Google Meet、DeepSeek V4、浏览器坐标点击和模型目录 manifest 化，以及 v2026.5.22 的 Gateway 性能、Meeting Notes、shrinkwrap / runtime deps、protobufjs 8.4.0 和默认子 Agent bootstrap context 收窄之外，v2026.5.26 / v2026.5.27 还重点改进 Transcript 核心化、Control UI Activity、Talk / Discord voice、Telegram durable delivery、iMessage / WhatsApp / Signal reaction approvals、OpenAI compatible embedding provider、DeepInfra / Pixverse / VLLM 模型能力、Docker runtime workspace templates 和多项安全边界。升级后如果发现模型、通道或插件行为变化，先运行 openclaw doctor，再对照当前 release notes。 ⠀ 说明： 从 v2026.4.x 到 v2026.5.27 的升级包含多项安全加固、性能优化和通道能力更新。大部分配置向后兼容，但以下几点需要注意： ⠀ 1. Owner Enforced Commands（v2026.4.5+）：/allowlist add 和 /allowlist remove 现在需要 Owner 身份验证。如果你之前在自动化脚本中使用了这些命令，需要确保调用者具有 Owner 权限 2. 转发头安全检查（v2026.4.x+）：如果你使用反向代理，Gateway 现在会检查转发头的一致性（详见 Q81） 3. 环境变量过滤（v2026.4.7+）：Gateway 会自动拦截危险的环境变量覆盖，如果你的部署脚本依赖特定的环境变量传递，建议测试确认 4. Hook 失败模式变更（v2026.4.5+）：Hook 崩溃时从 fail open 改为 fail closed，如果你有自定义 Hook，升级后请确认它们运行正常 5. Cron 状态拆分（v2026.4.20+）：定时任务运行时状态拆分到独立的 jobs state.json 文件，升级后首次启动会自动迁移 ⠀ 升级步骤： ⠀ Code block Plain Text 1. 备份 cp r /.openclaw /.openclaw.backup $(date +%Y%m%d) 2. 升级 npm update g openclaw 3. 验证 openclaw version openclaw doctor openclaw security audit 4. 如果使用反向代理，检查转发头配置（见 Q81） ⠀ Q81: 升级后反向代理配置需要改吗？ ⠀ 说明： 如果你通过 Nginx 等反向代理暴露 Gateway，v2026.4.x 的转发头安全检查可能影响你的配置。 ⠀ 需要确认的事项： ⠀ 1. 反向代理的 X Forwarded For 头必须覆盖客户端值，不能追加 github.com/openclaw/openclaw/discussions 官方文档 GitHub Issues GitHub Discussions ⠀ Q71: 有中文社区吗？ ⠀ 说明： 有的。 ⠀ • GitHub Discussions（中英文都可以）：github.com/openclaw/openclaw/discussions github.com/openclaw/openclaw/discussions • Discord 社区（有中文频道） • 微信群：关注 OpenClaw 公众号获取入群二维码 ⠀ Q72: 文档有错误怎么反馈？ ⠀ 解决方案： ⠀ • 直接在 GitHub 上提 Issue，标注 docs 标签 • 或者直接提 PR 修改文档 • OpenClaw 官方 Markdown 文档位于其 GitHub 仓库的 docs/ 目录 十、其他常见问题 ⠀ 📌 本节包含 7 个问题： Q73: 和 ChatGPT 的区别 | Q74: 支持哪些语言 | Q75: 多实例运行 | Q76: 是否收费 | Q77: 查看所有配置 | Q78: Gateway 和 Agent 关系 | Q79: 获取帮助 📌 本节包含 7 个问题： Q73: 和 ChatGPT 的区别 | Q74: 支持哪些语言 | Q75: 多实例运行 | Q76: 是否收费 | Q77: 查看所有配置 | Q78: Gateway 和 Agent 关系 | Q79: 获取帮助 ⠀ Q73: OpenClaw 和 ChatGPT 有什么区别？ ⠀ 说明： 它们是完全不同的东西： ⠀ ⠀ 简单说：ChatGPT 是一个产品，OpenClaw 是一个让你构建自己 AI 助手的工具。 ⠀ Q74: OpenClaw 支持哪些语言？ ⠀ 说明： OpenClaw 本身是英文项目，但 AI 的回复语言取决于你使用的模型和系统提示词。 ⠀ ⠀ 大多数主流模型（GPT 5.2、Claude、Gemini）都支持中文。本地模型推荐用 Qwen（通义千问）系列，中文能力最好。 ⠀ Q75: 一台机器能跑多个 OpenClaw 实例吗？ ⠀ 解决方案： ⠀ ⠀ Q76: OpenClaw 会收费吗？ ⠀ 说明： OpenClaw 是开源项目（MIT 协议），永久免费。你需要付费的只有 AI 模型的 API 调用费用（如果你用云端模型的话）。用本地模型（Ollama）则完全零成本。 ⠀ Q77: 怎么查看当前的所有配置？ ⠀ 解决方案： ⠀ ⠀ Q78: Gateway 和 Agent 是什么关系？ ⠀ 说明： ⠀ • Gateway 是消息网关，负责连接各个消息平台（WhatsApp、Telegram 等），接收和发送消息 • Agent 是 AI 智能体，负责理解消息、调用工具、生成回复 ⠀ 消息流程：用户 → 消息平台 → Gateway → Agent → 模型 API → Agent → Gateway → 消息平台 → 用户 ⠀ Gateway 是基础设施层，Agent 是业务逻辑层。一个 Gateway 可以服务多个 Agent。 ⠀ Q79: 遇到问题怎么获取帮助？ ⠀ 获取帮助的渠道（按推荐顺序）： ⠀ 1. 查看本 FAQ 文档 2. 查看官方文档 官方文档 3. 搜索 GitHub Issues（可能别人遇到过同样的问题） GitHub Issues 4. 在 GitHub Discussions 提问 GitHub Discussions 5. 加入 Discord 社区实时交流 ⠀ 提问时请附上： • OpenClaw 版本（openclaw version） • Node.js 版本（node version） • 操作系统信息 • 相关日志（前台运行 openclaw gateway port 18789 verbose 查看） 十一、版本升级与迁移（v2026.3.28 → v2026.5.27） ⠀ 📌 本节包含 4 个问题： Q80: 升级要点 | Q81: 反向代理配置变更 | Q82: 插件白名单变更 | Q83: 性能提升 📌 本节包含 4 个问题： Q80: 升级要点 | Q81: 反向代理配置变更 | Q82: 插件白名单变更 | Q83: 性能提升 ⠀ Q80: 从 v2026.3.2x 升级到 v2026.5.27 有哪些注意事项？ ⠀ v2026.5.27 新增关注点：除了 v2026.4.24 的 Google Meet、DeepSeek V4、浏览器坐标点击和模型目录 manifest 化，以及 v2026.5.22 的 Gateway 性能、Meeting Notes、shrinkwrap / runtime deps、protobufjs 8.4.0 和默认子 Agent bootstrap context 收窄之外，v2026.5.26 / v2026.5.27 还重点改进 Transcript 核心化、Control UI Activity、Talk / Discord voice、Telegram durable delivery、iMessage / WhatsApp / Signal reaction approvals、OpenAI compatible embedding provider、DeepInfra / Pixverse / VLLM 模型能力、Docker runtime workspace templates 和多项安全边界。升级后如果发现模型、通道或插件行为变化，先运行 openclaw doctor，再对照当前 release notes。 v2026.5.27 新增关注点：除了 v2026.4.24 的 Google Meet、DeepSeek V4、浏览器坐标点击和模型目录 manifest 化，以及 v2026.5.22 的 Gateway 性能、Meeting Notes、shrinkwrap / runtime deps、protobufjs 8.4.0 和默认子 Agent bootstrap context 收窄之外，v2026.5.26 / v2026.5.27 还重点改进 Transcript 核心化、Control UI Activity、Talk / Discord voice、Telegram durable delivery、iMessage / WhatsApp / Signal reaction approvals、OpenAI compatible embedding provider、DeepInfra / Pixverse / VLLM 模型能力、Docker runtime workspace templates 和多项安全边界。升级后如果发现模型、通道或插件行为变化，先运行 openclaw doctor，再对照当前 release notes。 ⠀ 说明： 从 v2026.4.x 到 v2026.5.27 的升级包含多项安全加固、性能优化和通道能力更新。大部分配置向后兼容，但以下几点需要注意： ⠀ 1. Owner Enforced Commands（v2026.4.5+）：/allowlist add 和 /allowlist remove 现在需要 Owner 身份验证。如果你之前在自动化脚本中使用了这些命令，需要确保调用者具有 Owner 权限 2. 转发头安全检查（v2026.4.x+）：如果你使用反向代理，Gateway 现在会检查转发头的一致性（详见 Q81） 3. 环境变量过滤（v2026.4.7+）：Gateway 会自动拦截危险的环境变量覆盖，如果你的部署脚本依赖特定的环境变量传递，建议测试确认 4. Hook 失败模式变更（v2026.4.5+）：Hook 崩溃时从 fail open 改为 fail closed，如果你有自定义 Hook，升级后请确认它们运行正常 5. Cron 状态拆分（v2026.4.20+）：定时任务运行时状态拆分到独立的 jobs state.json 文件，升级后首次启动会自动迁移 ⠀ 升级步骤： ⠀ ⠀ Q81: 升级后反向代理配置需要改吗？ ⠀ 说明： 如果你通过 Nginx 等反向代理暴露 Gateway，v2026.4.x 的转发头安全检查可能影响你的配置。 ⠀ 需要确认的事项： ⠀ 1. 反向代理的 X Forwarded For 头必须覆盖客户端值，不能追加 ⠀ ⠀ 1. 如果使用 trusted proxy 认证模式，trustedProxies 中不能填 loopback 地址（127.0.0.1、::1） 2. 如果 Gateway 和代理在同一台机器上通过 loopback 通信，改用 token/password 认证模式 ⠀ Q82: 升级后 /allowlist 相关操作报权限错误 ⠀ 现象： 升级到 v2026.4.5+ 后，执行 /allowlist add 或 /allowlist remove 时提示权限不足。 ⠀ 原因： 这是 v2026.4.5 引入的 Owner Enforced Commands 特性。白名单修改现在需要 Gateway 所有者的实际身份验证，不再接受宽松的回退。 ⠀ 解决方案： ⠀ ⠀ Q83: 升级后启动变快了，是正常的吗？ ⠀ 说明： 是的，这是正常现象。v2026.4.20+ 包含了显著的启动性能优化： ⠀ • 插件启动：通过延迟加载和 manifest backed 模型行，bundled 依赖加载时间降低 82 90% • Doctor 诊断：插件延迟加载使冷启动时间降低约 74% • 模型目录：静态模型目录替代运行时加载，减少启动时的网络请求 ⠀ 这些优化在 v2026.4.24 中进一步改善（通过 provider 依赖的延迟加载和 manifest backed model rows）。 教程到这里就结束了！如果这份教程帮到了你，给个 Star 支持一下！ 教程到这里就结束了！如果这份教程帮到了你，给个 Star 支持一下！ 课程信息 ⠀ • 作者：老金 • GitHub：https://github.com/KimYx0207 • 公众号：老金带你玩AI • X（Twitter）：老金带你玩AI • 个人博客：https://aiking.dev • 难度等级：🟢 入门 • 前置知识：无 ⠀ 遇到问题？ 这里收集了社区最常见的问题和解决方案。用 Ctrl+F（或 Cmd+F）搜索关键词，快速定位你的问题 ⠀ 最常见的 5 个问题： Q1: 命令找不到 | Q2: Node.js 版本不兼容 | Q26: API Key 无效 | Q12: Gateway 启动失败 | Q16: WhatsApp 连接问题 ⠀ 这篇 FAQ 收集了 OpenClaw 社区中最常见的问题和解决方案。按类别组织，方便你快速定位问题。 ⠀ 如果这里没有你遇到的问题，可以到 GitHub Issues 提问，或加入 Discord 社区寻求帮助。 GitHub Issues 一、安装和配置问题 ⠀ 📌 本节包含 15 个问题： Q1: 命令找不到 | Q2: Node.js 版本不兼容 | Q3: npm 权限错误 | Q4: 中国网络安装慢 | Q5: node gyp 编译错误 | Q6: onboard 报错 | Q7: 配置文件位置 | Q8: 多 API Key 配置 | Q9: 配置优先级 | Q10: 升级后配置丢失 | Q11: 版本回滚 | Q12: Windows Gateway 失败 | Q13: macOS 安全提示 | Q14: 端口被占用 | Q15: 完全卸载 📌 本节包含 15 个问题： Q1: 命令找不到 | Q2: Node.js 版本不兼容 | Q3: npm 权限错误 | Q4: 中国网络安装慢 | Q5: node gyp 编译错误 | Q6: onboard 报错 | Q7: 配置文件位置 | Q8: 多 API Key 配置 | Q9: 配置优先级 | Q10: 升级后配置丢失 | Q11: 版本回滚 | Q12: Windows Gateway 失败 | Q13: macOS 安全提示 | Q14: 端口被占用 | Q15: 完全卸载 ⠀ Q1: openclaw 命令找不到（command not found） ⠀ 现象： 安装完成后执行 openclaw 提示 command not found 或 不是内部或外部命令。 ⠀ 原因： npm 全局安装的 bin 目录没有加入系统 PATH 环境变量。 ⠀ 解决方案： ⠀ ⠀ 如果你用的是 pnpm，全局 bin 路径不同： ⠀ ⠀ Q2: Node.js 版本不兼容 ⠀ 现象： 安装时报错 engine "node" is incompatible 或运行时出现语法错误。 ⠀ 原因： OpenClaw 当前官方建议使用 Node.js 24.x；22.19+ 仍然兼容。低于兼容线时，常见报错就是 engine incompatible、运行时语法错误或部分 API 不可用。 ⠀ 解决方案： ⠀ ⠀ Windows 用户推荐用 nvm windows： nvm windows ⠀ ⠀ Q3: npm install 报权限错误（EACCES） ⠀ 现象：npm install g openclaw 时报 EACCES: permission denied。 ⠀ 原因： npm 全局目录的权限不对，当前用户没有写入权限。 ⠀ 解决方案： ⠀ ⠀ Q4: 中国网络环境安装慢或失败 ⠀ 现象：npm install 卡住不动，或者下载速度极慢，最终超时失败。 ⠀ 原因： npm 默认从 registry.npmjs.org 下载，国内访问速度不稳定。 registry.npmjs.org ⠀ 解决方案： ⠀ ⠀ 如果连 npm 镜像都访问不了，可以考虑 Docker 安装方式，提前拉取镜像： ⠀ ⠀ Q5: 安装时报 node gyp 编译错误 ⠀ 现象： 安装过程中出现 gyp ERR! 或 node gyp rebuild 失败。 ⠀ 原因： 某些依赖包含原生 C++ 模块，需要编译工具链。 ⠀ 解决方案： ⠀ ⠀ Q6: openclaw onboard 引导向导报错 ⠀ 现象： 运行 openclaw onboard 后，终端卡在某一步不动了（光标闪烁但没有输出），或者直接报错退出并显示 Error: network timeout 或 TypeError: Cannot read properties of undefined。 ⠀ 原因： 可能是终端不支持交互式输入，或者网络问题导致无法验证 API Key。 ⠀ 解决方案： ⠀ ⠀ Q7: 配置文件在哪里？怎么手动编辑？ ⠀ 现象： 想直接编辑配置文件，但不知道在哪。 ⠀ 说明： OpenClaw 的所有配置都在 /.openclaw/ 目录下。 ⠀ ⠀ Q8: 多个 API Key 怎么配置？ ⠀ 现象： 想同时配置 OpenAI 和 Anthropic 的 Key，不知道怎么操作。 ⠀ 解决方案： ⠀ ⠀ Q9: 环境变量和配置文件哪个优先？ ⠀ 说明： 优先级从高到低： ⠀ ⠀ 也就是说，如果你同时在环境变量和配置文件里设了 API Key，环境变量的值会生效。 ⠀ Q10: 升级 OpenClaw 后配置丢失了 ⠀ 现象： 更新到新版本后，之前的配置好像不见了。 ⠀ 原因： 正常情况下升级不会覆盖配置。但如果你用 Docker 部署且没有挂载数据卷，容器重建后数据会丢失。 ⠀ 解决方案： ⠀ ⠀ Q11: 升级后功能异常怎么回滚？ ⠀ 现象： 执行 npm update g openclaw 升级到新版本后，之前正常的功能出现报错、崩溃或行为异常，需要退回旧版本。 ⠀ 解决方案： ⠀ ⠀ Q12: Windows 上安装后 Gateway 启动失败 ⠀ 现象： Windows 上执行 openclaw gateway start 后，终端窗口闪一下就关闭了（闪退），或者报错 EADDRINUSE、EACCES 等错误信息，Gateway 无法正常启动。 ⠀ 原因： Windows 的端口占用、防火墙或 WSL 兼容性问题。 ⠀ 解决方案： ⠀ ⠀ Q13: macOS 上安装提示"无法验证开发者" ⠀ 现象： macOS 上首次运行 openclaw 命令时，系统弹出对话框提示「无法验证开发者」或「无法打开，因为 Apple 无法检查其是否包含恶意软件」，命令被阻止执行。 ⠀ 解决方案： ⠀ ⠀ Q14: 安装完成但 openclaw gateway start 提示端口被占用 ⠀ 现象： 报错 EADDRINUSE: address already in use :::18789。 ⠀ 原因： 端口 18789 已经被其他进程占用，或者上一次 Gateway 没有正常关闭。 ⠀ 解决方案： ⠀ ⠀ Q15: 怎么完全卸载 OpenClaw？ ⠀ 现象： 不再使用 OpenClaw，想彻底从系统中移除所有相关文件（包括程序、配置和数据）。 ⠀ 解决方案： ⠀ 二、消息平台问题 ⠀ 📌 本节包含 10 个问题： Q16: WhatsApp 频繁断开 | Q17: Telegram Bot 不响应 | Q18: Telegram 群组不回复 | Q19: Discord Bot 无法加入 | Q20: 消息延迟严重 | Q21: rate limited | Q22: 飞书收不到消息 | Q23: 控制面板打不开 | Q24: 多账号接入 | Q25: 图片文件处理 📌 本节包含 10 个问题： Q16: WhatsApp 频繁断开 | Q17: Telegram Bot 不响应 | Q18: Telegram 群组不回复 | Q19: Discord Bot 无法加入 | Q20: 消息延迟严重 | Q21: rate limited | Q22: 飞书收不到消息 | Q23: 控制面板打不开 | Q24: 多账号接入 | Q25: 图片文件处理 ⠀ Q16: WhatsApp 扫码后频繁断开 ⠀ 现象： 扫码配对成功，但过一会儿就断开，需要反复扫码。 ⠀ 原因： WhatsApp Web 协议要求手机端保持在线。如果手机网络不稳定或 WhatsApp 应用被系统杀后台，连接就会断。 ⠀ 解决方案： ⠀ ⠀ 其他注意事项： • 确保手机上的 WhatsApp 没有被省电模式限制后台运行 • 一个 WhatsApp 账号只能同时连接一个 Web 客户端，如果你在浏览器里也开了 WhatsApp Web，会冲突 • 建议用一个专门的手机号来跑 OpenClaw ⠀ Q17: Telegram Bot 不响应消息 ⠀ 现象： 给 Telegram Bot 发消息，没有任何回复。 ⠀ 原因： 可能是 Bot Token 配置错误、Bot 没有接收消息的权限、或者 Gateway 没有正常运行。 ⠀ 解决方案： ⠀ ⠀ Q18: Telegram Bot 在群组中不回复 ⠀ 现象： Bot 在私聊中正常回复，但在群组中不响应。 ⠀ 原因： Telegram Bot 默认开启隐私模式，在群组中只能收到 @提及 和 /命令。 ⠀ 解决方案： ⠀ 1. 在 @BotFather 中关闭隐私模式（见 Q17） 2. 或者在群组中 @提及 Bot 来触发回复 3. 在群组配置中设置激活模式（通过聊天命令 /act