11. 常见问题 (FAQ)

课程信息
难度等级：🟢 入门
前置知识：无
遇到问题？ 这里收集了社区最常见的问题和解决方案。用 Ctrl+F（或 Cmd+F）搜索关键词，快速定位你的问题
最常见的 5 个问题： Q1: 命令找不到 | Q2: Node.js 版本不兼容 | Q26: API Key 无效 | Q12: Gateway 启动失败 | Q16: WhatsApp 连接问题

这篇 FAQ 收集了 OpenClaw 社区中最常见的问题和解决方案。按类别组织，方便你快速定位问题。

如果这里没有你遇到的问题，可以到 GitHub Issues 提问，或加入 Discord 社区寻求帮助。

一、安装和配置问题

📌 本节包含 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.14+ 仍然兼容。低于兼容线时，常见报错就是 engine incompatible、运行时语法错误或部分 API 不可用。

解决方案：

Windows 用户推荐用 nvm-windows：

nvm install 24
nvm use 24

Q3: npm install 报权限错误（EACCES）

现象： npm install -g openclaw 时报 EACCES: permission denied。

原因： npm 全局目录的权限不对，当前用户没有写入权限。

解决方案：

Q4: 中国网络环境安装慢或失败

现象： npm install 卡住不动，或者下载速度极慢，最终超时失败。

原因： npm 默认从 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: 环境变量和配置文件哪个优先？

说明： 优先级从高到低：

命令行参数 > 环境变量 > ~/.openclaw/openclaw.json > 默认值

也就是说，如果你同时在环境变量和配置文件里设了 API Key，环境变量的值会生效。

Q10: 升级 OpenClaw 后配置丢失了

现象： 更新到新版本后，之前的配置好像不见了。

原因： 正常情况下升级不会覆盖配置。但如果你用 Docker 部署且没有挂载数据卷，容器重建后数据会丢失。

解决方案：

Q11: 升级后功能异常怎么回滚？

现象： 执行 npm update -g openclaw 升级到新版本后，之前正常的功能出现报错、崩溃或行为异常，需要退回旧版本。

解决方案：

Q12: Windows 上安装后 Gateway 启动失败

现象： Windows 上执行 openclaw gateway start 后，终端窗口闪一下就关闭了（闪退），或者报错 EADDRINUSE、EACCES 等错误信息，Gateway 无法正常启动。

原因： Windows 的端口占用、防火墙或 WSL 兼容性问题。

解决方案：

# 检查端口是否被占用
netstat -an | findstr 18789

# 如果被占用，换一个端口
openclaw config set gateway.port 18790

# 检查防火墙是否放行
# Windows Defender 防火墙 → 高级设置 → 入站规则 → 新建规则 → 端口 18789

# 推荐：在 WSL2 中运行 OpenClaw
wsl --install
# 在 WSL 中按 Linux 方式安装

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: 图片文件处理

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 默认开启隐私模式，在群组中只能收到 @提及和 /命令。

解决方案：

在 @BotFather 中关闭隐私模式（见 Q17）

或者在群组中 @提及 Bot 来触发回复

在群组配置中设置激活模式（通过聊天命令 /activation mention 或 /activation always 切换）

Q19: Discord Bot 无法加入服务器

现象： 用邀请链接添加 Bot 时报错 Missing Permissions。

原因： Bot 的 OAuth2 权限配置不完整。

解决方案：

去 Discord Developer Portal

选择你的应用 → OAuth2 → URL Generator

勾选以下权限：

bot

applications.commands

Send Messages

Read Message History

Embed Links

Attach Files

用生成的新链接重新邀请 Bot

Q20: 消息延迟严重（发了好久才回复）

现象： 发消息后要等 10 秒甚至更久才收到回复。

原因： 延迟可能来自多个环节 — 网络、模型 API 响应时间、消息队列积压。

解决方案：

Q21: 消息发送失败，提示 "rate limited"

现象： 发消息时报错 429 Too Many Requests 或 rate limited。

原因： 消息平台有发送频率限制。WhatsApp 尤其严格，短时间内发太多消息会被限流。

解决方案：

Q22: 飞书（Feishu/Lark）接入后收不到消息

现象： 飞书 Bot 配置完成，但收不到用户消息。

原因： 飞书的事件订阅配置不完整，或者回调地址不可达。

解决方案：

Q23: 控制面板（Dashboard）打不开

现象： 浏览器访问 http://localhost:18789 显示无法连接。

原因： Gateway 没有运行，或者端口被防火墙拦截。

解决方案：

Q24: 同一个平台能接入多个账号吗？

说明： 可以。OpenClaw 支持同一平台的多个 Channel 实例。

每个 Channel 独立运行，有自己的配对状态和消息队列。

Q25: 消息中的图片/文件 AI 能处理吗？

说明： 取决于你使用的模型。支持多模态的模型（如 GPT-5.2、Claude Sonnet 4.6）可以处理图片。

不支持多模态的模型收到图片时，会提示用户发送文字。

三、模型和 AI 问题

📌 本节包含 10 个问题：
Q26: API 401 报错 | Q27: API 429 限流 | Q28: 模型回复慢 | Q29: Token 超限 | Q30: Ollama 连不上 | Q31: 本地模型质量差 | Q32: 国产模型配置 | Q33: 模型故障转移 | Q34: 控制 API 费用 | Q35: 不同对话用不同模型

Q26: API 调用报错 401 Unauthorized

现象： 发消息后 AI 不回复，日志中出现 401 Unauthorized 或 Invalid API Key。

原因： API Key 无效、过期、或者余额不足。

解决方案：

Q27: 报错 429 Too Many Requests（API 限流）

现象： 高频使用时出现 429 错误，AI 间歇性不回复。

原因： 超过了模型提供商的 API 调用频率限制（RPM/TPM）。

解决方案：

Q28: 模型回复很慢

现象： 发送消息后，AI 要等 10-30 秒甚至更久才开始回复。在终端日志中可以看到请求已发出，但响应迟迟不返回。

原因： 大模型本身推理就需要时间，加上网络延迟，响应时间会更长。

解决方案：

Q29: Token 超限报错（context length exceeded）

现象： 对话到一定长度后报错 maximum context length exceeded 或 token limit。

原因： 每个模型都有上下文窗口限制。对话历史 + 系统提示 + 记忆文件的总 Token 数超过了模型限制。

解决方案：

Q30: Ollama 本地模型连不上

现象： 配置了 Ollama 但 OpenClaw 报错 ECONNREFUSED 或 connection refused。

原因： Ollama 服务没有启动，或者监听地址配置不对。

解决方案：

Q31: 本地模型回复质量差

现象： 用 Ollama 跑本地模型，回复经常答非所问或质量很低。

原因： 小参数模型的能力有限，尤其是中文能力。

解决方案：

Q32: 怎么使用国产模型（通义千问、Kimi、智谱等）？

解决方案：

国产模型的优势：不需要代理、中文能力强、价格便宜。推荐中国用户优先考虑。

Q33: 怎么配置模型故障转移（Fallback）？

说明： 当主模型不可用时，自动切换到备用模型，保证服务不中断。

Q34: API 费用太高怎么控制成本？

解决方案：

Q35: 怎么让不同的对话用不同的模型？

说明： 可以为不同的 Agent 配置不同的模型，通过在配置文件中为每个 Agent 指定独立的模型。

四、技能和工具问题

📌 本节包含 10 个问题：
Q36: 技能不生效 | Q37: 自定义技能报错 | Q38: 工具执行失败 | Q39: 禁用工具 | Q40: 添加新工具 | Q41: 技能中途中断 | Q42: 查看工具调用 | Q43: 内置技能列表 | Q44: 技能冲突 | Q45: 分享技能

Q36: 技能（Skill）不生效，AI 不执行

现象： 你发消息让 AI 执行某个技能（比如「帮我搜索 xxx」），但 AI 只是用文字回复了一段话，并没有真正调用工具去执行操作。日志中也看不到工具调用记录。

原因： 技能没有正确加载，或者触发条件不匹配。

解决方案：

Q37: 自定义技能报错

现象： 在 ~/.openclaw/workspace/skills/ 目录下创建了自定义技能的 .md 文件，但执行 openclaw skills list 时该技能未出现，或者出现 skill parse error、invalid skill format 等报错信息。

原因： 技能文件格式不对，或者引用了不存在的工具。

解决方案：

正确的技能文件结构：

Q38: 工具（Tool）执行失败

现象： AI 回复中显示「正在调用 xxx 工具」，但随后报错 tool execution failed、permission denied 或 tool not found，操作没有完成。

原因： 工具缺少必要的权限或依赖。

解决方案：

Q39: 怎么禁用某个工具？

说明： 出于安全考虑，你可能想禁用某些危险工具。

Q40: 怎么给 AI 添加新工具？

说明： OpenClaw 支持通过 MCP（Model Context Protocol）协议接入外部工具。

Q41: 技能执行到一半中断了

现象： AI 在执行一个多步骤技能时（比如「搜索 → 读取文件 → 生成报告」），执行到中间某一步后突然停下来，不再继续后续步骤，也没有给出完成提示。

原因： 可能是 Token 限制导致输出被截断，或者某个中间步骤失败了。

解决方案：

Q42: 怎么查看 AI 调用了哪些工具？

解决方案：

Q43: 内置技能列表在哪里看？

解决方案：

Q44: 技能之间会冲突吗？

说明： 如果多个技能的触发条件重叠，可能会出现冲突。OpenClaw 会按优先级选择。

Q45: 怎么分享自定义技能给别人？

解决方案：

五、部署和运维问题

📌 本节包含 10 个问题：
Q46: Docker 容器立即退出 | Q47: 容器内存过高 | Q48: 数据卷备份 | Q49: 自动重启 | Q50: 查看日志 | Q51: 监控运行状态 | Q52: 磁盘空间清理 | Q53: 多服务器部署 | Q54: 设置 HTTPS | Q55: 自动更新

Q46: Docker 容器启动后立即退出

现象： 执行 docker compose up -d 后，运行 docker ps 看不到 OpenClaw 容器，用 docker ps -a 查看发现容器状态为 Exited (1) 或其他非零退出码。

原因： 配置文件缺失、端口冲突、或者环境变量没设置。

解决方案：

Q47: Docker 容器内存占用过高

现象： 运行 docker stats 发现 OpenClaw 容器的内存使用量持续增长，从几百 MB 涨到好几 GB，甚至导致宿主机变卡或 OOM（Out of Memory）被系统杀掉。

原因： 连接了太多平台、会话数据积累、或者存在内存泄漏。

v2026.4.20+ 默认启用了会话维护（Sessions/Maintenance）的条目上限和基于时间的自动清理，可以有效防止 OOM。如果你从旧版本升级，建议确认此特性已启用。

解决方案：

Q48: Docker 数据卷怎么备份？

解决方案：

Q49: Gateway 进程崩溃后怎么自动重启？

解决方案：

Q50: 日志在哪里看？怎么排查问题？

解决方案：

Q51: 怎么监控 OpenClaw 的运行状态？

解决方案：

Q52: 磁盘空间不足怎么清理？

解决方案：

Q53: 怎么在多台服务器上部署？

说明： OpenClaw 目前是单实例架构，不支持原生集群部署。但你可以通过以下方式实现多节点：

Q54: 怎么设置 HTTPS？

解决方案：

Q55: 怎么配置自动更新？

解决方案：

六、记忆系统问题

📌 本节包含 3 个问题：
Q56: AI 不记得之前说的话 | Q57: 记忆文件太大 | Q58: 多 Agent 共享记忆

Q56: AI 不记得之前说的话

现象： 你之前告诉 AI「我叫小明」或「我喜欢用 Python」，但下次对话时 AI 完全不记得这些信息，像是第一次跟你聊天一样。

原因： OpenClaw 的记忆是基于 Markdown 文件的。如果信息没有被写入记忆文件，下次会话就不会加载。

解决方案：

Q57: 记忆文件太大导致 Token 超限

现象： 使用一段时间后，每次新对话刚开始就报错 token limit exceeded，或者发现 API 费用突然增加。检查发现 ~/.openclaw/workspace/MEMORY.md 文件已经有几百甚至上千行。

解决方案：

Q58: 怎么在多个 Agent 之间共享记忆？

说明： 默认情况下，所有 Agent 共享同一个 workspace 和记忆目录。如果你想隔离，在配置文件中为不同 Agent 指定独立的 workspace：

// ~/.openclaw/openclaw.json
{
  "agents": {
    "list": [
      {
        "id": "my-agent",
        "workspace": "~/.openclaw/workspace-my-agent"
      }
    ]
  }
}

每个 Agent 的 workspace 下有独立的 MEMORY.md 和 memory/ 目录，实现完全隔离。如果需要共享部分记忆，可以用符号链接指向同一个 MEMORY.md 文件。

七、安全和隐私问题

📌 本节包含 6 个问题：
Q59: API Key 泄露风险 | Q60: 聊天记录存储 | Q61: Gateway Token | Q62: 限制对话权限 | Q63: 防止危险操作 | Q64: 安全漏洞

Q59: API Key 会不会泄露？

说明： OpenClaw 把 API Key 存储在本地配置文件中（~/.openclaw/openclaw.json），不会上传到任何服务器。

安全建议：

Q60: 聊天记录存在哪里？会被发送到第三方吗？

说明： 聊天记录存储在本地 ~/.openclaw/ 目录中。消息内容只会发送到你配置的 AI 模型提供商（如 OpenAI、Anthropic）。

OpenClaw 本身不收集任何用户数据。但要注意：

你发给 AI 的消息会被模型提供商处理（参考各提供商的隐私政策）

如果你用 OpenRouter 等聚合服务，消息会经过中间层

本地模型（Ollama）的数据完全不出本机

Q61: Gateway Token 是什么？必须设置吗？

说明： Gateway Token 是访问 OpenClaw Gateway 的认证凭证。如果不设置，任何知道你 Gateway 地址的人都能连接并发送消息。

Q62: 怎么限制谁能跟 AI 对话？

解决方案：

Q63: 怎么防止 AI 执行危险操作？

解决方案：

Q64: OpenClaw 有已知的安全漏洞吗？

说明： OpenClaw 在 2026 年初曾披露过 CVE 安全漏洞，社区已经修复。v2026.4.x 系列持续加强了安全防护，主要包括：

SSRF 防护（v2026.4.2+）：集中化的请求传输策略，阻止对私有网络的导航重定向

环境变量清理（v2026.4.7+）：自动拦截危险的环境变量覆盖

Owner-Enforced Commands（v2026.4.5+）：白名单修改需要所有者身份验证

Shell Wrapper 检测（v2026.4.1+）：扩展了对 shell 包装命令的识别和 env-argv 注入拦截

Hook 失败模式（v2026.4.5+）：Hook 崩溃时采用 fail-closed 策略，不会默认放行

建议：

八、中国用户特别提示

📌 本节包含 3 个问题：
Q65: API 访问不了 | Q66: WhatsApp 能否使用 | Q67: npm 镜像问题

Q65: API 访问不了怎么办？

说明： OpenAI、Anthropic、Google 的 API 在中国大陆无法直接访问。

解决方案：

Q66: WhatsApp 在中国能用吗？

说明： WhatsApp 在中国大陆需要代理才能使用。

替代方案：

Telegram（需要代理，但 Bot API 可以通过代理访问）

飞书 / Lark（国内原生支持，OpenClaw 通过扩展支持飞书 Channel）

注意：钉钉、微信公众号、个人微信均不受官方支持

Q67: npm 镜像配置后还是装不上

解决方案：

九、社区和贡献问题

📌 本节包含 5 个问题：
Q68: 报告 Bug | Q69: 贡献代码 | Q70: 分享自定义技能 | Q71: 中文社区 | Q72: 文档反馈

Q68: 怎么报告 Bug？

解决方案：

去 GitHub Issues 页面

点击 "New Issue"

选择 "Bug Report" 模板

填写以下信息：

Q69: 怎么贡献代码？

流程：

Q70: 怎么创建和分享自定义技能？

解决方案：

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 聊天产品	AI Agent 框架
模型	只能用 OpenAI 的模型	支持 29+ 提供商
平台	网页/App	WhatsApp/Telegram/Discord 等
工具	有限的插件	可扩展的工具和技能系统
记忆	平台管理	你自己控制（本地 Markdown）
数据	存在 OpenAI 服务器	存在你自己的机器上
价格	订阅制	开源免费（API 费用另算）

简单说：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: 遇到问题怎么获取帮助？

获取帮助的渠道（按推荐顺序）：

查看本 FAQ 文档

查看官方文档

搜索 GitHub Issues（可能别人遇到过同样的问题）

在 GitHub Discussions 提问

加入 Discord 社区实时交流

提问时请附上：

OpenClaw 版本（openclaw --version）

Node.js 版本（node --version）

操作系统信息

相关日志（前台运行 openclaw gateway --port 18789 --verbose 查看）

十一、版本升级与迁移（v2026.3.28 → v2026.4.24）

📌 本节包含 4 个问题：
Q80: 升级要点 | Q81: 反向代理配置变更 | Q82: 插件白名单变更 | Q83: 性能提升

Q80: 从 v2026.3.2x 升级到 v2026.4.2x 有哪些注意事项？

说明： v2026.4.x 系列包含多项安全加固和功能改进。大部分配置向后兼容，但以下几点需要注意：

Owner-Enforced Commands（v2026.4.5+）：/allowlist add 和 /allowlist remove 现在需要 Owner 身份验证。如果你之前在自动化脚本中使用了这些命令，需要确保调用者具有 Owner 权限

转发头安全检查（v2026.4.x+）：如果你使用反向代理，Gateway 现在会检查转发头的一致性（详见 Q81）

环境变量过滤（v2026.4.7+）：Gateway 会自动拦截危险的环境变量覆盖，如果你的部署脚本依赖特定的环境变量传递，建议测试确认

Hook 失败模式变更（v2026.4.5+）：Hook 崩溃时从 fail-open 改为 fail-closed，如果你有自定义 Hook，升级后请确认它们运行正常

Cron 状态拆分（v2026.4.20+）：定时任务运行时状态拆分到独立的 jobs-state.json 文件，升级后首次启动会自动迁移

升级步骤：

Q81: 升级后反向代理配置需要改吗？

说明： 如果你通过 Nginx 等反向代理暴露 Gateway，v2026.4.x 的转发头安全检查可能影响你的配置。

需要确认的事项：

反向代理的 X-Forwarded-For 头必须覆盖客户端值，不能追加

如果使用 trusted-proxy 认证模式，trustedProxies 中不能填 loopback 地址（127.0.0.1、::1）

如果 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 支持一下！

11-常见问题FAQ

11. 常见问题 (FAQ)#

一、安装和配置问题#

Q1: openclaw 命令找不到（command not found）#

Q2: Node.js 版本不兼容#

Q3: npm install 报权限错误（EACCES）#

Q4: 中国网络环境安装慢或失败#

Q5: 安装时报 node-gyp 编译错误#

Q6: openclaw onboard 引导向导报错#

Q7: 配置文件在哪里？怎么手动编辑？#

Q8: 多个 API Key 怎么配置？#

Q9: 环境变量和配置文件哪个优先？#

Q10: 升级 OpenClaw 后配置丢失了#

Q11: 升级后功能异常怎么回滚？#

Q12: Windows 上安装后 Gateway 启动失败#

Q13: macOS 上安装提示"无法验证开发者"#

Q14: 安装完成但 openclaw gateway start 提示端口被占用#

Q15: 怎么完全卸载 OpenClaw？#

二、消息平台问题#

Q16: WhatsApp 扫码后频繁断开#

Q17: Telegram Bot 不响应消息#

Q18: Telegram Bot 在群组中不回复#

Q19: Discord Bot 无法加入服务器#

Q20: 消息延迟严重（发了好久才回复）#

Q21: 消息发送失败，提示 "rate limited"#

Q22: 飞书（Feishu/Lark）接入后收不到消息#

Q23: 控制面板（Dashboard）打不开#

Q24: 同一个平台能接入多个账号吗？#

Q25: 消息中的图片/文件 AI 能处理吗？#

三、模型和 AI 问题#

Q26: API 调用报错 401 Unauthorized#

Q27: 报错 429 Too Many Requests（API 限流）#

Q28: 模型回复很慢#

Q29: Token 超限报错（context length exceeded）#

Q30: Ollama 本地模型连不上#

Q31: 本地模型回复质量差#

Q32: 怎么使用国产模型（通义千问、Kimi、智谱等）？#

Q33: 怎么配置模型故障转移（Fallback）？#

Q34: API 费用太高怎么控制成本？#

Q35: 怎么让不同的对话用不同的模型？#

四、技能和工具问题#

Q36: 技能（Skill）不生效，AI 不执行#

Q37: 自定义技能报错#

Q38: 工具（Tool）执行失败#

Q39: 怎么禁用某个工具？#

Q40: 怎么给 AI 添加新工具？#

Q41: 技能执行到一半中断了#

Q42: 怎么查看 AI 调用了哪些工具？#

Q43: 内置技能列表在哪里看？#

Q44: 技能之间会冲突吗？#

Q45: 怎么分享自定义技能给别人？#

五、部署和运维问题#

Q46: Docker 容器启动后立即退出#

Q47: Docker 容器内存占用过高#

Q48: Docker 数据卷怎么备份？#

Q49: Gateway 进程崩溃后怎么自动重启？#

Q50: 日志在哪里看？怎么排查问题？#

Q51: 怎么监控 OpenClaw 的运行状态？#

Q52: 磁盘空间不足怎么清理？#

Q53: 怎么在多台服务器上部署？#

Q54: 怎么设置 HTTPS？#

Q55: 怎么配置自动更新？#

六、记忆系统问题#

Q56: AI 不记得之前说的话#

Q57: 记忆文件太大导致 Token 超限#

Q58: 怎么在多个 Agent 之间共享记忆？#

七、安全和隐私问题#

Q59: API Key 会不会泄露？#

Q60: 聊天记录存在哪里？会被发送到第三方吗？#

Q61: Gateway Token 是什么？必须设置吗？#

Q62: 怎么限制谁能跟 AI 对话？#

Q63: 怎么防止 AI 执行危险操作？#

Q64: OpenClaw 有已知的安全漏洞吗？#

八、中国用户特别提示#

Q65: API 访问不了怎么办？#

Q66: WhatsApp 在中国能用吗？#

Q67: npm 镜像配置后还是装不上#

九、社区和贡献问题#

Q68: 怎么报告 Bug？#

Q69: 怎么贡献代码？#

11. 常见问题 (FAQ)

一、安装和配置问题

Q1: `openclaw` 命令找不到（command not found）

Q2: Node.js 版本不兼容

Q3: npm install 报权限错误（EACCES）

Q4: 中国网络环境安装慢或失败

Q5: 安装时报 `node-gyp` 编译错误

Q6: `openclaw onboard` 引导向导报错

Q7: 配置文件在哪里？怎么手动编辑？

Q8: 多个 API Key 怎么配置？

Q9: 环境变量和配置文件哪个优先？

Q10: 升级 OpenClaw 后配置丢失了

Q11: 升级后功能异常怎么回滚？

Q12: Windows 上安装后 Gateway 启动失败

Q13: macOS 上安装提示"无法验证开发者"

Q14: 安装完成但 `openclaw gateway start` 提示端口被占用

Q15: 怎么完全卸载 OpenClaw？

二、消息平台问题

Q16: WhatsApp 扫码后频繁断开

Q17: Telegram Bot 不响应消息

Q18: Telegram Bot 在群组中不回复

Q19: Discord Bot 无法加入服务器

Q20: 消息延迟严重（发了好久才回复）

Q21: 消息发送失败，提示 "rate limited"

Q22: 飞书（Feishu/Lark）接入后收不到消息

Q23: 控制面板（Dashboard）打不开

Q24: 同一个平台能接入多个账号吗？

Q25: 消息中的图片/文件 AI 能处理吗？

三、模型和 AI 问题

Q26: API 调用报错 401 Unauthorized

Q27: 报错 429 Too Many Requests（API 限流）

Q28: 模型回复很慢

Q29: Token 超限报错（context length exceeded）

Q30: Ollama 本地模型连不上

Q31: 本地模型回复质量差

Q32: 怎么使用国产模型（通义千问、Kimi、智谱等）？

Q33: 怎么配置模型故障转移（Fallback）？

Q34: API 费用太高怎么控制成本？

Q35: 怎么让不同的对话用不同的模型？

四、技能和工具问题

Q36: 技能（Skill）不生效，AI 不执行

Q37: 自定义技能报错

Q38: 工具（Tool）执行失败

Q39: 怎么禁用某个工具？

Q40: 怎么给 AI 添加新工具？

Q41: 技能执行到一半中断了

Q42: 怎么查看 AI 调用了哪些工具？

Q43: 内置技能列表在哪里看？

Q44: 技能之间会冲突吗？

Q45: 怎么分享自定义技能给别人？

五、部署和运维问题

Q46: Docker 容器启动后立即退出

Q47: Docker 容器内存占用过高

Q48: Docker 数据卷怎么备份？

Q49: Gateway 进程崩溃后怎么自动重启？

Q50: 日志在哪里看？怎么排查问题？

Q51: 怎么监控 OpenClaw 的运行状态？

Q52: 磁盘空间不足怎么清理？

Q53: 怎么在多台服务器上部署？

Q54: 怎么设置 HTTPS？

Q55: 怎么配置自动更新？

六、记忆系统问题

Q56: AI 不记得之前说的话

Q57: 记忆文件太大导致 Token 超限

Q58: 怎么在多个 Agent 之间共享记忆？

七、安全和隐私问题

Q59: API Key 会不会泄露？

Q60: 聊天记录存在哪里？会被发送到第三方吗？

Q61: Gateway Token 是什么？必须设置吗？

Q62: 怎么限制谁能跟 AI 对话？

Q63: 怎么防止 AI 执行危险操作？

Q64: OpenClaw 有已知的安全漏洞吗？

八、中国用户特别提示

Q65: API 访问不了怎么办？

Q66: WhatsApp 在中国能用吗？

Q67: npm 镜像配置后还是装不上

九、社区和贡献问题

Q68: 怎么报告 Bug？

Q69: 怎么贡献代码？

Q70: 怎么创建和分享自定义技能？