11. 常见问题 (FAQ)

课程信息

作者：老金
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 社区寻求帮助。

一、安装和配置问题

这份 FAQ 是老金按真实卡点整理的，不是为了凑问题数；能定位问题，比背答案更重要。

2026-09-14 当前基线（v2026.9.4）：排障前先确认版本口径已经变了——latest 为 2026.9.4，extended-stable 为 2026.6.35（核查日：2026-09-14）。两条最容易踩的：从 2026.8.2 升级、机器上没有 service manager 的，先手动跑一次 openclaw update --no-restart；失败后只有数据库结构未变、旧包兼容且配置校验通过时才可能自动回滚，迁移后的恢复需要已验证的升级前备份和匹配版本。v2026.9.1 起升级失败会提供 triage 排障入口，并保留配置和 secret 引用；v2026.9.3 起核心和插件改动会先在隔离 candidate 状态预演。启动类问题也少了：畸形的旧 cron 行会被隔离而不是卡住启动，迁移告警会降级而不是拒绝启动，Windows Gateway 在 agent 重启后能保持在线。

2026-06-18 排障口径：当前稳定基线为 v2026.6.8。升级优先用 openclaw update，再用 openclaw doctor 和 channel / gateway 日志定位问题；repair 可修复插件、payload、registry 和部分本地状态，但不会替你重新安装 core 或重启 Gateway。

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

现象：安装完成后执行 openclaw 提示 command not found 或不是内部或外部命令。

原因： npm 全局安装的 bin 目录没有加入系统 PATH 环境变量。

解决方案：

# 第一步：确认是否真的安装了
npm list -g openclaw

# 第二步：找到 npm 全局 bin 目录
npm config get prefix
# 输出类似 /usr/local 或 /home/user/.npm-global

# 第三步：把 bin 目录加入 PATH
# Linux / macOS
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Windows PowerShell
# 把 npm prefix 路径加到系统环境变量 Path 中
# 或者直接用 npx openclaw 代替
npx openclaw --version

如果你用的是 pnpm，全局 bin 路径不同：

pnpm config get global-bin-dir
# 把输出的路径加入 PATH

Q2: Node.js 版本不兼容

现象：安装时报错 engine "node" is incompatible 或运行时出现语法错误。

原因： OpenClaw v2026.9.4 要求 >=24.16.0 <25 || >=26.1.0：24.x 至少 24.16.0，或 26.1.0 及以上；新装推荐 26.x。Node 22、25.x 和 26.0.x 不在这个范围内。来源：官方快速开始、指定版本的运行时要求（核查日：2026-09-14）。

解决方案：

# 检查当前版本
node --version

# 仅在当前版本不符合上述范围时升级
# 安装 nvm（如果还没装）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 重新打开终端，然后：
nvm install 26
nvm use 26
nvm alias default 26  # 设为默认版本

# 验证
node --version  # 确认 v26.x.x，且不低于 v26.1.0

Windows 用户推荐用 nvm-windows：

nvm install 26
nvm use 26

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

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

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

解决方案：

# 方案一：修改 npm 全局目录（推荐）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw

# 方案二：用 sudo（不推荐，但能快速解决）
sudo npm install -g openclaw

# 方案三：用 nvm 管理 Node.js（最佳实践）
# nvm 安装的 Node.js 不需要 sudo

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

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

原因： npm 默认从 registry.npmjs.org 下载，国内访问速度不稳定。

解决方案：

# 方案一：临时使用镜像（推荐）
npm install -g openclaw --registry=https://registry.npmmirror.com

# 方案二：永久切换镜像
npm config set registry https://registry.npmmirror.com
npm install -g openclaw

# 方案三：使用 cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install -g openclaw

# 验证镜像是否生效
npm config get registry

如果连 npm 镜像都访问不了，可以考虑 Docker 安装方式，提前拉取镜像：

# 使用 Docker Hub 镜像加速
docker pull openclaw/openclaw:latest

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

现象：安装过程中出现 gyp ERR! 或 node-gyp rebuild 失败。

原因：某些依赖包含原生 C++ 模块，需要编译工具链。

解决方案：

# Linux (Ubuntu/Debian)
sudo apt-get install -y build-essential python3

# macOS
xcode-select --install

# Windows
# 以管理员身份运行 PowerShell
npm install -g windows-build-tools
# 或者安装 Visual Studio Build Tools

Q6: openclaw onboard 引导向导报错

现象：运行 openclaw onboard 后，终端卡在某一步不动了（光标闪烁但没有输出），或者直接报错退出并显示 Error: network timeout 或 TypeError: Cannot read properties of undefined。

原因：可能是终端不支持交互式输入，或者网络问题导致无法验证 API Key。

解决方案：

# 方案一：确保用的是交互式终端（不是 IDE 内置终端）
# 打开系统自带的终端应用

# 方案二：跳过引导，手动配置
export OPENAI_API_KEY="sk-proj-xxxxx"
openclaw config set agents.defaults.model "openai/gpt-5.2"
openclaw gateway --port 18789

# 方案三：检查配置文件是否损坏
cat ~/.openclaw/openclaw.json
# 如果内容异常，删除后重新引导
rm ~/.openclaw/openclaw.json
openclaw onboard

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

现象：想直接编辑配置文件，但不知道在哪。

说明： OpenClaw 的所有配置都在 ~/.openclaw/ 目录下。

# 查看配置目录结构
ls -la ~/.openclaw/

# 主要文件：
# ~/.openclaw/openclaw.json    — 主配置文件（JSON5 格式）
# ~/.openclaw/workspace/      — 工作空间（记忆、技能等）
# ~/.openclaw/gateway/        — Gateway 运行时数据

# 用命令查看当前配置
openclaw config get agents.defaults.model

# 用命令修改配置（推荐，会自动验证格式）
openclaw config set <key> <value>

# 也可以直接编辑 JSON5 文件
nano ~/.openclaw/openclaw.json

Q8: 多个 API Key 怎么配置？

现象：想同时配置 OpenAI 和 Anthropic 的 Key，不知道怎么操作。

解决方案：

# 推荐：通过环境变量配置（优先级高于配置文件，更安全）
export OPENAI_API_KEY="sk-proj-xxxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export GEMINI_API_KEY="AIzaSy-xxxxx"

# 设置默认模型
openclaw config set agents.defaults.model "openai/gpt-5.2"

# OpenClaw 会自动读取环境变量，不需要在配置文件中写 Key

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

说明：优先级从高到低：

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

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

Q10: 升级 OpenClaw 后配置丢失了

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

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

解决方案：

# 升级前先创建并校验备份（使用支持 backup 子命令的版本）
openclaw backup create --output ~/Backups/openclaw --verify

# 升级（优先内置升级；自动回滚须通过状态兼容检查）
openclaw update
# 内置升级不可用时再退回：npm update -g openclaw

# Docker 升级（确保挂载了数据卷）
# docker-compose.yml 中必须有：
# volumes:
#   - ./data:/home/node/.openclaw

旧版没有 backup 子命令时，先停止 Gateway 和其他写入者，再做覆盖配置、数据库和工作区的文件系统或卷快照。配置确实丢失时，先保存当前状态，再按官方备份恢复说明离线恢复；不要直接把旧目录叠加到正在运行的数据目录上。

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

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

解决方案：

v2026.9.4 的自动回滚有条件：数据库结构未变、旧包仍能读取当前状态，且配置校验通过。数据库迁移或激活后的人工配置修改会阻止回滚；不能因为它没有回滚，就直接用 npm 覆盖成旧包。回滚成功也仍表示本次升级失败，命令会保留非零退出码。先看 openclaw update status 和错误里的恢复指引。

# 查看当前版本
openclaw --version

# 查看所有可用版本
npm view openclaw versions --json

# 查看最近的升级结果和恢复提示
openclaw update status

# 先把 <known-good-version> 替换为你升级前验证过的具体版本
# 兼容检查通过后，才执行第二条，并按提示确认降级
openclaw update --tag <known-good-version> --dry-run
openclaw update --tag <known-good-version>

如果当前保存的通道是 extended-stable，指定一次性精确版本时按官方指引加 --channel stable。extended-stable 当日指向的版本不一定能读取你的当前数据，不能把通道名当成通用回滚答案。遇到 newer-schema 或 newer-config 拒绝时不要绕过；需要用已验证的升级前备份和匹配版本恢复，并在恢复期间停止 Gateway 和所有写入者。

Docker 换回旧镜像也不会撤销数据迁移。先确认备份与目标镜像匹配，再按 09 章恢复流程处理数据；官方固定镜像标签不带 v，例如 openclaw/openclaw:2026.6.35（仅示范标签格式，不是统一降级目标）。完整规则见官方回滚与恢复说明。

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

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

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

解决方案：

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

# 如果被占用，换一个端口
openclaw config set gateway.port 19789  # 不要用 18790-18899，那一段是 Bridge / Browser Control / Canvas / CDP 端口池（见 09 章端口表）

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

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

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

现象： macOS 上首次运行 openclaw 命令时，系统弹出对话框提示「无法验证开发者」或「无法打开，因为 Apple 无法检查其是否包含恶意软件」，命令被阻止执行。

解决方案：

# 方案一：在系统偏好设置中允许
# 系统偏好设置 → 隐私与安全性 → 仍然允许

# 方案二：通过命令行移除隔离属性
xattr -d com.apple.quarantine $(which openclaw)

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

现象：报错 EADDRINUSE: address already in use :::18789。

原因：端口 18789 已经被其他进程占用，或者上一次 Gateway 没有正常关闭。

解决方案：

# 找到占用端口的进程
# Linux / macOS
lsof -i :18789
# 记下 PID，然后 kill
# 先核对 PID 的程序、账号和实例；不要结束不认识的进程
# 若是当前 OpenClaw 后台服务，先运行 openclaw gateway stop
# 手动前台 Gateway 在原终端按 Ctrl+C；其他服务按自己的管理方式停止

# Windows
netstat -ano | findstr 18789
taskkill /PID <PID> /F

# 或者换一个端口
openclaw config set gateway.port 19789  # 不要用 18790-18899，那一段是 Bridge / Browser Control / Canvas / CDP 端口池（见 09 章端口表）
openclaw gateway start

Q15: 怎么完全卸载 OpenClaw？

现象：不再使用 OpenClaw，想彻底从系统中移除所有相关文件（包括程序、配置和数据）。

解决方案：

# 停止 Gateway
openclaw gateway stop

# 卸载 npm 包
npm uninstall -g openclaw

# 删除配置和数据（谨慎操作，不可恢复）
rm -rf ~/.openclaw

# Docker 方式
docker compose down -v
docker rmi openclaw/openclaw:latest

二、消息平台问题

Q16: WhatsApp 扫码后频繁断开

先查看 WhatsApp 通道状态和日志，区分连接网络、linked device 授权失效与 Gateway 退出：

openclaw gateway status
openclaw channels status
openclaw channels logs --channel whatsapp

需要重新配对时，按实际 account 执行 logout/login；不要删除整个 credentials。WhatsApp linked-device 模式不要求手机与 Gateway 在同一 Wi-Fi，也不是只能绑定一个 Web 客户端。手机需按 WhatsApp 当前 linked-device 规则定期使用主账号；具体上限和失效条件以平台说明及实际日志为准。

Q17: Telegram Bot 不响应消息

现象：给 Telegram Bot 发消息，没有任何回复。

原因：可能是 Bot Token 配置错误、Bot 没有接收消息的权限、或者 Gateway 没有正常运行。

解决方案：

# 第一步：确认 Gateway 在运行
openclaw status

# 第二步：确认 Bot Token 正确
openclaw config get channels.telegram.botToken
# 去 @BotFather 核对 Token 是否一致

# 第三步：确认 Bot 的隐私模式
# 在 @BotFather 中：
# /mybots → 选择你的 Bot → Bot Settings → Group Privacy → Turn off
# 关闭隐私模式后，Bot 才能接收群组中的所有消息

# 第四步：检查日志
openclaw logs --limit 50 | grep telegram

# 第五步：探测已配置的 Telegram Bot 认证与连接
openclaw channels status --channel telegram --probe
# Token 有误时，按 Telegram 接入章重新配置 Bot Token；不是扫码登录

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

# 配置 Discord Bot Token（注意：Discord 用的字段是 token，不是 botToken）
openclaw config set channels.discord.token "your-discord-bot-token"
openclaw channels status --channel discord --probe
# Discord 使用 Bot Token；按 Discord 接入章核对 token 与应用权限

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

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

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

解决方案：

# 第一步：排查是哪个环节慢
openclaw logs --limit 20
# 看日志中的时间戳，判断延迟发生在哪里

# 第二步：观察实际模型调用的请求时间、首 token 和总耗时
openclaw logs --follow
# health 只用于 Gateway 健康检查；模型延迟要从已授权的实际请求或 provider 记录判断

# 第三步：检查是否有消息积压
openclaw sessions list

# 第四步：优化措施
# 使用更快的模型
openclaw config set agents.defaults.model "openai/gpt-5.6-luna"
# 减少系统提示词长度（Token 越少，响应越快）
# 精简 ~/.openclaw/workspace/SOUL.md 的内容

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

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

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

解决方案：

# 消息平台的限流是平台侧限制，OpenClaw 没有内置速率限制配置
# 解决方案：
# 1. 减少消息发送频率，避免触发平台限流
# 2. 等待限流解除后自动重试
# 3. 如果是 API 限流（429），参考 Q27 配置模型故障转移

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

先确认已安装和启用官方 Feishu 插件，App ID/Secret、Bot 能力、权限及消息事件正确。默认连接方式是 WebSocket：在飞书开放平台选择长连接接收事件，不需要为了它开放 Gateway 公网端口。

openclaw channels status
openclaw channels logs --channel feishu

只有显式选择 webhook 模式时，才按所用插件版本配置回调。新配置默认路径为 /feishu/events，同时配置对应验证和签名凭据；不要照抄 /webhook/feishu。完整流程见官方 Feishu 指南。

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

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

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

解决方案：

# 第一步：确认 Gateway 在运行
openclaw status

# 如果没运行，启动它
openclaw gateway --port 18789

# 第二步：检查端口
# Linux / macOS
lsof -i :18789
# Windows
netstat -an | findstr 18789

# 第三步：如果是远程服务器，检查防火墙
# Ubuntu
sudo ufw allow 18789
# CentOS
sudo firewall-cmd --add-port=18789/tcp --permanent
sudo firewall-cmd --reload

# 第四步：重启 Gateway（停止后重新启动，或使用聊天命令 /restart）
openclaw gateway --port 18789

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

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

# 添加第二个 WhatsApp 账号
openclaw channels add --channel whatsapp --account work --name "Work"
openclaw channels add --channel whatsapp --account personal --name "Personal"

# 查看所有 Channel
openclaw channels list

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

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

说明：取决于你使用的模型和当前 provider 目录。支持多模态的模型可以处理图片；具体型号不要背教程，以 openclaw 当前 models / onboarding 显示为准。

# 多模态能力取决于你使用的模型，不需要额外配置
# 支持多模态的模型会自动处理图片；具体型号以当前模型目录为准
# 文件大小限制取决于消息平台本身的限制

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

三、模型和 AI 问题

Q26: API 调用报错 401 Unauthorized

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

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

解决方案：

# 第一步：检查 Key 是否配置正确
# 推荐通过环境变量设置：
[ -n "${OPENAI_API_KEY:-}" ] && echo "OPENAI_API_KEY 已设置" || echo "OPENAI_API_KEY 未设置"
# 确认 Key 没有多余的空格或换行

# 第二步：区分 Gateway 健康与模型认证
openclaw health
openclaw models status
# health 检查 Gateway/通道，status 展示模型与认证元数据；两者不证明模型请求成功
# 核对 provider 日志；需要真实探测时按 models status --probe 文档操作，先停止运行中的 Gateway，探测会发出请求并可能计费

# 第三步：去提供商后台检查
# OpenAI: https://platform.openai.com/account/api-keys
# Anthropic: https://console.anthropic.com/settings/keys
# 确认 Key 没有被撤销，账户余额充足

# 第四步：重新设置 Key
export OPENAI_API_KEY="sk-proj-new-key-here"
# 然后重启 Gateway

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

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

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

解决方案：

# 方案一：启用模型故障转移（推荐）
# 在 ~/.openclaw/openclaw.json 中配置：
# {
#   "agents": {
#     "defaults": {
#       "model": {
#         "primary": "openai/gpt-5.2",
#         "fallbacks": ["anthropic/claude-sonnet-5", "openai/gpt-5.6-luna"]
#       }
#     }
#   }
# }

# 方案二：使用 OpenRouter（聚合多个提供商，限流更宽松）
export OPENROUTER_API_KEY="sk-or-xxxxx"
openclaw config set agents.defaults.model "openrouter/openai/gpt-5.2"

# 方案三：升级 API 账户等级（更高的 RPM/TPM 限制）
# 去各提供商控制台升级

Q28: 模型回复很慢

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

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

解决方案：

# 方案一：换用更快的小模型
openclaw config set agents.defaults.model "openai/gpt-5.6-luna"
# 选择当前目录里可用的低成本模型；延迟以自己的代表性任务实测为准

# 方案二：流式响应默认已启用
# OpenClaw 默认使用流式输出（边生成边发送），无需额外配置

# 方案三：减少系统提示词长度
# 精简 SOUL.md 中不必要的指令，精简 MEMORY.md 内容
openclaw agents list
# 查看当前 Agent 列表

# 方案四：使用本地模型（延迟最低）
ollama pull llama3.1:8b
openclaw config set models.providers.ollama.baseUrl "http://127.0.0.1:11434"
openclaw config set agents.defaults.model "ollama/llama3.1:8b"

# 方案五：检查网络延迟
ping api.openai.com
# 如果延迟高，考虑使用代理或换区域更近的提供商

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

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

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

解决方案：

# 查看当前会话的 Token 使用情况
openclaw sessions list

# 方案一：使用 /compact 命令手动压缩上下文
# 在聊天界面中发送 /compact，OpenClaw 会自动压缩旧消息
# 自动压缩默认启用。若要调整压缩时保留的近期对话预算：
# 在 ~/.openclaw/openclaw.json 中设置：
# {
#   "agents": {
#     "defaults": {
#       "compaction": {
#         "keepRecentTokens": 20000
#       }
#     }
#   }
# }
# 这是近期对话保留预算，不是触发阈值；自动压缩还受输入、输出与工具预算约束。

# 方案二：使用上下文窗口更大的模型
# 不同 provider 的上下文窗口会随版本变化，先查当前 models 目录再设置
openclaw config set agents.defaults.model "anthropic/<current-long-context-model>"

# 方案三：手动清理会话
openclaw sessions cleanup
# 或让 AI 总结后开新会话（在聊天界面发送 /new）

Q30: Ollama 本地模型连不上

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

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

解决方案：

# 第一步：确认 Ollama 在运行
ollama serve
# 或者检查是否已经在后台运行
curl http://127.0.0.1:11434/api/tags

# 第二步：确认有可用的模型
ollama list
# 如果没有模型，先拉一个
ollama pull llama3.1:8b

# 第三步：配置 OpenClaw 连接 Ollama
openclaw config set models.providers.ollama.baseUrl "http://127.0.0.1:11434"
openclaw config set agents.defaults.model "ollama/llama3.1:8b"

# 第四步：如果 Ollama 和 OpenClaw 不在同一台机器
# 需要让 Ollama 监听所有网卡
OLLAMA_HOST=0.0.0.0 ollama serve
# 然后配置远程地址
openclaw config set models.providers.ollama.baseUrl "http://192.168.1.100:11434"

Q31: 本地模型回复质量差

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

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

解决方案：

# 方案一：换用更大的模型（需要更多内存/显存）
ollama pull llama3.1:70b    # 需要 64GB+ 内存
ollama pull qwen2.5:14b     # 中文能力更好

# 方案二：调整模型参数（在 API 调用时传入，非配置文件）
# temperature 和 topP 等参数取决于模型提供商
# 本地模型可以在 Ollama 的 Modelfile 中设置默认参数
# 例如创建自定义 Modelfile：
# FROM llama3.1:8b
# PARAMETER temperature 0.7
# PARAMETER top_p 0.9

# 方案三：优化系统提示词
# 本地小模型对提示词更敏感，要写得简洁明确
# 在 SOUL.md 中精简指令，避免复杂的多步骤指令

# 方案四：混合策略 — 简单任务用本地模型，复杂任务用云端
# 通过模型故障转移实现：本地模型作为默认，复杂任务手动切换
# 在 ~/.openclaw/openclaw.json 中配置：
# {
#   "agents": {
#     "defaults": {
#       "model": {
#         "primary": "ollama/llama3.1:8b",
#         "fallbacks": ["openai/gpt-5.2"]
#       }
#     }
#   }
# }

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

解决方案：

# 国产模型大多可以通过 OpenAI 兼容接口或 OpenRouter 接入

# 通义千问（阿里云 DashScope）— 通过 OpenAI 兼容接口
# 在 ~/.openclaw/openclaw.json 中配置：
# {
#   "models": {
#     "providers": {
#       "dashscope": {
#         "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
#       }
#     }
#   },
#   "agents": { "defaults": { "model": "dashscope/qwen-max" } }
# }
# API Key 通过环境变量设置（参考 DashScope 文档）

# Moonshot / Kimi — 通过 OpenAI 兼容接口
# baseUrl: "https://api.moonshot.cn/v1"

# DeepSeek — 通过 OpenAI 兼容接口
# baseUrl: "https://api.deepseek.com/v1"
# 具体 DeepSeek 模型名以当前 OpenClaw models / provider 目录为准

# 最简单的方式：通过 OpenRouter 统一接入各类国产模型
export OPENROUTER_API_KEY="sk-or-xxxxx"
openclaw config set agents.defaults.model "openrouter/deepseek/deepseek-chat"

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

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

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

# 在 ~/.openclaw/openclaw.json 中配置 Fallback 链：
# {
#   "agents": {
#     "defaults": {
#       "model": {
#         "primary": "openai/gpt-5.2",
#         "fallbacks": [
#           "anthropic/claude-sonnet-5",
#           "openai/gpt-5.6-luna"
#         ]
#       }
#     }
#   }
# }
# 当主模型返回 5xx、超时或 429 限流时，自动按顺序尝试备用模型

# 查看 Fallback 状态
openclaw models fallbacks list
openclaw models status

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

解决方案：

# 方案一：在模型提供商控制台设置预算上限
# OpenAI: Settings > Limits 设置月度上限
# Anthropic: Plans & Billing 查看用量
# Google Cloud: 设置 API 配额和预算提醒
# OpenClaw 本身没有内置预算控制配置

# 方案二：使用更便宜的模型
# 费用按所用账号、提供商当前价目与实际Token用量核算，不承诺固定比例
openclaw config set agents.defaults.model "openai/gpt-5.6-luna"

# 方案三：精简记忆文件减少 Token 消耗
# MEMORY.md 建议控制在 500 行以内
# 精简 SOUL.md 系统提示词

# 方案四：查看系统状态
openclaw status

# 方案五：本地模型零成本
ollama pull llama3.1:8b
openclaw config set agents.defaults.model "ollama/llama3.1:8b"

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

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

# 方案一：为不同 Agent 配置不同模型
# 在 ~/.openclaw/openclaw.json 中配置：
# {
#   "agents": {
#     "defaults": {
#       "model": "openai/gpt-5.6-luna"
#     },
#     "entries": {
#       "coding": { "default": true, "model": "anthropic/claude-sonnet-5" },
#       "casual": { "model": "openai/gpt-5.6-luna" }
#     }
#   }
# }

# 方案二：使用模型别名快速切换
openclaw models aliases add code-review "anthropic/claude-opus-4-8"
openclaw models aliases add quick-chat "openai/gpt-5.6-luna"

# 方案三：通过 bindings 将不同 Channel 路由到不同 Agent
# 每个 Agent 使用各自配置的模型
# 详见 08-多Agent协作指南.md

四、技能和工具问题

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

先查看 openclaw skills list、openclaw skills info <skill-name> 和 openclaw skills check，确认技能可见、依赖满足且未被禁用。模型根据技能的 description 决定是否读取正文；triggers 不是强制关键词匹配字段，skills check 也不会执行一个测试输入。

在新对话中明确说要使用该技能，并观察实际工具调用。模型只回复文字，不能证明它执行了工具。

Q37: 自定义技能报错

每个技能使用一个目录，核心文件叫 SKILL.md：

mkdir -p ~/.openclaw/workspace/skills/my-custom-skill
nano ~/.openclaw/workspace/skills/my-custom-skill/SKILL.md
openclaw skills list
openclaw skills info my-custom-skill
openclaw skills check

最小内容：

---
name: my-custom-skill
description: 用户要求整理一段记录为结构化草稿时使用。
---

## 步骤

只按用户给出的材料整理草稿，缺信息先指出，不创建定时任务或发送外部消息。

工具由 OpenClaw 或已安装插件提供；tools/ 里放文件不会自动注册工具，Skill 中列权限也不会产生运行时授权。

Q38: 工具（Tool）执行失败

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

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

解决方案：

# 第一步：检查工具状态
openclaw doctor
# 诊断安全和配置问题

# 第二步：检查技能依赖就绪状态（不执行工具）
openclaw skills check

# 第三步：检查工具依赖
openclaw skills info <skill-name>
# 看 dependencies 字段，确认依赖都已安装

# 第四步：常见工具问题
# web_search 需要网络连接
# write/edit 需要实际文件权限与 tools 策略允许
# exec 能否执行取决于工具策略、审批和目标环境；sandbox 默认关闭，不等于 exec 默认禁用

Q39: 怎么禁用某个工具？

使用 tools.deny 或按 Agent 配置工具允许列表，例如禁止文件写入和执行：

{ tools: { deny: ["write", "edit", "exec"] } }

还要核查已安装插件和外部服务的写入工具。Sandbox 改执行环境，不等于禁用某工具；non-main 指非主会话。SOUL.md 是辅助行为提示。

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

按官方工具插件说明注册插件工具，或通过 MCP连接实际服务。把 TypeScript 文件放进 workspace/tools 不会自动注册工具。安装或连接以后核对工具列表、凭据和权限，再测试。

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

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

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

解决方案：

# 第一步：查看会话日志，找到中断点
# 使用前台模式运行 Gateway 查看详细日志：
openclaw gateway --port 18789 --verbose

# 第二步：Token 限制导致截断的解决方案
# 不同模型有不同的最大输出限制，先查当前 models 输出和 provider 文档
# 换用输出限制更大的模型，或精简系统提示词

# 第三步：让 AI 继续
# 直接发消息 "继续" 或 "请继续执行"

# 第四步：如果是工具执行失败导致的中断
openclaw skills check
# 修复工具问题后重试

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

解决方案：

# 查看最近会话的工具调用记录
openclaw sessions list

# 实时查看工具调用（调试模式）
openclaw logs --follow
# 日志中会显示每次工具调用的详细信息

# 查看系统状态
openclaw status

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

解决方案：

# 列出所有技能（包括内置技能）
openclaw skills list

# 查看某个技能的详细说明
openclaw skills info <skill-name>

Q44: 技能之间会冲突吗？

说明：同名技能按目录来源优先级覆盖；不同名字的技能由模型根据 description 和任务选择，描述重叠可能使选择不稳定，但不是引擎按关键词优先级抢占。先核查来源与可见性，再用显式 $skill-name 测试。

# 查看技能列表
openclaw skills list

# 查看特定技能的详细信息
openclaw skills info <skill-name>

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

解决方案：

# 查看技能文件
openclaw skills list

# 技能文件位于 ~/.openclaw/workspace/skills/ 目录
# 可以直接复制 .md 文件来分享技能

# 查看社区技能库
# https://github.com/openclaw/openclaw-skills

五、部署和运维问题

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

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

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

解决方案：

# 第一步：查看容器退出日志
docker compose logs openclaw-gateway

# 第二步：常见原因排查
# 原因 1：配置文件不存在
ls ./data/openclaw.json  # 确认挂载的配置文件存在

# 原因 2：端口被占用
lsof -i :18789
# 如果被占用，修改 docker-compose.yml 中的端口映射

# 原因 3：环境变量缺失
# 确认 .env 文件存在且包含必要变量
ls -l .env  # 确认存在与权限；只在本地编辑，别把凭据打印到可分享输出

# 第三步：用前台模式启动，方便看日志
docker compose up  # 不加 -d

Q47: Docker 容器内存占用过高

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

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

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

解决方案：

# 查看容器资源使用
docker stats openclaw-gateway

# 方案一：限制容器内存
# 在 docker-compose.yml 中添加：
# deploy:
#   resources:
#     limits:
#       memory: 1G

# 方案二：清理会话数据
docker compose exec openclaw-gateway node dist/index.js sessions cleanup --dry-run --all-agents

# 方案三：减少同时连接的平台数量

# 方案四：定期重启容器（临时方案）
# 配置 crontab
# 0 4 * * * docker compose restart openclaw

Q48: Docker 数据卷怎么备份？

先识别当前 Compose 实际挂载的数据、workspace 和凭据密钥位置。SQLite 数据库不能靠运行中的 tar 保证一致；应使用支持的 openclaw backup create --verify，或停止 Gateway 和全部写入者后做完整卷快照。不要只备份示例中的 ./data 或猜测名为 openclaw_data 的卷。

完整脚本和恢复约束见 09 章备份与恢复。备份要连同匹配镜像版本保存，并在隔离环境实际恢复验证；校验归档可读不等于恢复成功。

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

解决方案：

# 方案一：安装为 systemd 服务（Linux 推荐）
openclaw onboard --install-daemon
# 这会创建 systemd service，崩溃后自动重启

# 查看服务状态
openclaw gateway status
# Linux 用户服务也可用 systemctl --user status openclaw-gateway

# 方案二：Docker 自动重启
# 在 docker-compose.yml 中设置：
# restart: unless-stopped

# 方案三：用 PM2 管理（Node.js 生态）
npm install -g pm2
pm2 start "openclaw gateway --port 18789" --name openclaw
pm2 save
pm2 startup  # 开机自启

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

解决方案：

# 最直接的方式：前台运行 Gateway 并开启 --verbose
openclaw gateway --port 18789 --verbose
# 所有日志实时输出到终端

# 按关键词过滤（通过管道 grep）
# openclaw gateway --port 18789 --verbose 2>&1 | grep "error"

# Docker 环境
docker compose logs -f openclaw-gateway
docker compose logs --tail 100 openclaw-gateway

# 日志文件位置（取决于 logging 配置）
# 默认日志输出到 stdout/stderr
# 可以通过 logging.file 配置写入文件

# 调整日志级别（排查问题时用 debug）
openclaw config set logging.level "debug"
# 排查完记得改回来
openclaw config set logging.level "info"

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

解决方案：

# 内置健康检查
curl http://localhost:18789/health

# 查看详细状态
openclaw status

# 输出示例：
# Gateway: running (uptime: 3d 12h)
# Channels: 3 connected, 0 error
# Sessions: 42 active
# Memory: 256 MB
# CPU: 2%

# 配置外部监控（推荐 UptimeRobot 或类似服务）
# 监控 URL: http://your-server:18789/health
# 检查间隔: 5 分钟

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

解决方案：

# 查看 OpenClaw 占用的磁盘空间
du -sh ~/.openclaw/
du -sh ~/.openclaw/*/  # 分目录查看

# 清理会话日志（最占空间的部分）
openclaw sessions cleanup

# 清理旧的记忆日志
find ~/.openclaw/workspace/memory/ -name "*.md" -mtime +60 -delete

# Docker 环境清理
docker system prune -f          # 清理无用镜像和容器
docker volume prune -f          # 清理无用数据卷（谨慎）

# 查看清理后的空间
du -sh ~/.openclaw/

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

多台服务器可以各自运行独立 Gateway，使用各自的状态目录和通道账号，也可以让节点连接一个 Gateway。不要让两个 Gateway 同时写同一个 ~/.openclaw、SQLite 数据库或同一通道账户，再靠普通负载均衡冒充集群。故障接管需要明确单写入者、凭据接管和一致性备份流程。

参见官方多 Gateway 指南。

Q54: 怎么设置 HTTPS？

解决方案：

# 方案一：用反向代理（推荐）
# Nginx + Let's Encrypt
sudo apt install nginx certbot python3-certbot-nginx
sudo certbot --nginx -d openclaw.yourdomain.com

# Nginx 配置
# server {
#     listen 443 ssl;
#     server_name openclaw.yourdomain.com;
#     location / {
#         proxy_pass http://127.0.0.1:18789;
#         proxy_http_version 1.1;
#         proxy_set_header Upgrade $http_upgrade;
#         proxy_set_header Connection "upgrade";
#     }
# }

# 方案二：OpenClaw 内置 TLS
# 显式启用 Gateway TLS，并设置证书和私钥路径
openclaw config set gateway.tls.enabled true
openclaw config set gateway.tls.certPath "/path/to/cert.pem"
openclaw config set gateway.tls.keyPath "/path/to/key.pem"
# 重启 Gateway 使配置生效
openclaw gateway --port 18789

Q55: 怎么配置自动更新？

生产环境先自动检查更新，再按备份、版本选择和兼容检查决定何时升级：

openclaw update status
openclaw --version

可以定时提醒自己检查 release；不要直接把无条件 openclaw update 或 Watchtower 重建放进生产 cron，绕过备份和状态迁移。Docker 固定 9.4 tag 时 pull 仍是 9.4，需要显式切到已验证的目标 tag。完整步骤见 09 章更新与回滚工坊。Windows 从 9.4 升到 9.8 的特殊恢复路径见 02 章，新 updater 的重试不能替代停止旧数据库驱动。

六、记忆系统问题

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

Q56: AI 不记得之前说的话

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

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

解决方案：

# 第一步：检查记忆文件是否存在
ls ~/.openclaw/workspace/memory/
cat ~/.openclaw/workspace/MEMORY.md

# 第二步：主动让 AI 记住
# 发消息："记住：我喜欢用 Python，不喜欢 Java"
# AI 会把这条信息写入 MEMORY.md

# 第三步：确认记忆刷新机制（compaction 时自动保存重要信息）
openclaw config get agents.defaults.compaction.memoryFlush
# 确保 memoryFlush.enabled 是 true

# 第四步：手动编辑记忆文件
nano ~/.openclaw/workspace/MEMORY.md
# 把重要信息直接写进去

# 第五步（v2026.4.10+）：启用 Active Memory 插件
# Active Memory 提供按条件的主动召回；记忆整理和提升要区分Dreaming与实际启用的流程
# 通过 openclaw plugins 查看是否已启用

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

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

解决方案：

# 查看记忆文件大小
wc -l ~/.openclaw/workspace/MEMORY.md
du -sh ~/.openclaw/workspace/memory/

# 方案一：精简 MEMORY.md
# 删除过时的、不再需要的信息
nano ~/.openclaw/workspace/MEMORY.md

# 方案二：把不再检索的旧日志移到 memory 根目录及 extraPaths 之外
mkdir -p ~/openclaw-memory-archive
find ~/.openclaw/workspace/memory -maxdepth 1 -name "20*.md" -mtime +30 -exec mv {} ~/openclaw-memory-archive/ \;
# 归档后运行 openclaw memory index 重建索引

# 方案三：控制 MEMORY.md 大小（建议 500 行 / 3000 tokens 以内）
# MEMORY.md 每次会话都会加载到上下文，太大会挤占对话空间
wc -l ~/.openclaw/workspace/MEMORY.md

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

说明：用 openclaw agents add 创建 Agent 时，应核对各自的 workspace；多 Agent 可以分别拥有记忆，也可以被你显式配置为同一目录。共享 workspace 会共享该目录下的记忆，独立 workspace 则分开保存。下面演示明确指定独立目录：

// ~/.openclaw/openclaw.json
{
  "agents": {
    "entries": {
      "my-agent": {
        "workspace": "~/.openclaw/workspace-my-agent"
      }
    }
  }
}

每个 workspace 可以保存自己的 MEMORY.md 和 memory/。这是内容分离，不是操作系统权限隔离。共享内容宜用受控只读目录并配置检索路径；若有多个写入者，要另行安排同步和冲突处理。

七、安全和隐私问题

Q59: API Key 会不会泄露？

说明： OpenClaw 把 API Key 存储在本地配置文件中（~/.openclaw/openclaw.json）或环境变量里，不会集中保存到某个 OpenClaw 云端；但调用云端模型时，Key 会作为认证凭证发给你配置的 provider。

安全建议：

# 检查配置文件权限
ls -la ~/.openclaw/openclaw.json
# 应该是 600（只有当前用户可读写）

# 修复权限
chmod 600 ~/.openclaw/openclaw.json

# 更安全的方式：用环境变量代替配置文件
export OPENAI_API_KEY="sk-proj-xxxxx"
# 把环境变量写入 ~/.bashrc 或 ~/.zshrc
# 不要把 Key 写入任何会被 git 追踪的文件

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

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

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

你发给 AI 的消息会被模型提供商处理（参考各提供商的隐私政策）
如果你用 OpenRouter 等聚合服务，消息会经过中间层
本地模型（Ollama）的推理内容可以不出本机；外部插件、远程 channel 和更新检查要另行审查

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

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

# 必须设置！（注意：正确的配置路径是 gateway.auth.token）
openclaw config set gateway.auth.token "$(openssl rand -hex 32)"

# 或者手动设置一个强密码
openclaw config set gateway.auth.token "your-strong-random-token-here"

# 通过环境变量设置
export OPENCLAW_GATEWAY_TOKEN="your-strong-random-token-here"

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

解决方案：

# 方案一：配对系统（默认开启）
# 陌生人发消息需要你手动批准
openclaw pairing list          # 查看待批准的联系人
openclaw pairing approve whatsapp <code>  # 使用已核对身份的实际待审配对码 # 批准
# 不批准的联系人会保持在待审列表中

# 方案二：白名单模式（通过 channels 配置 allowFrom）
# 在 ~/.openclaw/openclaw.json 中配置：
# {
#   "channels": {
#     "whatsapp": { "dmPolicy": "pairing", "allowFrom": ["+15555550123"] },
#     "telegram": { "dmPolicy": "pairing", "allowFrom": ["123456789"] }
#   }
# }

# 方案三：查看和管理配对状态
openclaw pairing list --channel whatsapp  # 仅列待审批请求；已授权身份查看该通道的 allowFrom 配置

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

解决方案：

# 第一步：启用沙箱模式限制工具执行
# sandbox.mode 可选值："off"（关闭）| "non-main"（非主会话 隔离）| "all"（全部隔离）
openclaw config set agents.defaults.sandbox.mode "all"

# 第二步：通过 SOUL.md 明确告诉 AI 哪些操作不能做
# 编辑 ~/.openclaw/workspace/SOUL.md，添加安全规则：
# ## 安全规则
# - 不要执行任何删除文件的操作
# - 不要执行 shell 命令，除非用户明确要求
# - 涉及文件修改前必须先确认

# 第三步：追踪所有操作（用 Git 管理 workspace）
cd ~/.openclaw/workspace && git init && git add . && git commit -m "snapshot"
# 之后可以用 git diff 查看 AI 做了什么改动

# 第四步：查看会话日志中的工具调用记录
# 会话日志在 ~/.openclaw/agents/main/sessions/*.jsonl
# 记录了所有工具调用，包括参数和结果

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

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

SSRF 防护（v2026.1.20 起持续加固）：v2026.4.1 集中化请求传输策略（auth/proxy/TLS/header），v2026.4.10 起浏览器 SSRF 策略默认严格模式，未配置的安装也会阻止私有网络导航
环境变量清理（v2026.4.7+）：自动拦截危险的环境变量覆盖
Owner-Enforced Commands（v2026.4.5+）：白名单修改需要所有者身份验证
Shell Wrapper 检测（v2026.2.22 起，v2026.4.12 扩展）：v2026.4.12 扩大了 shell 包装命令的识别范围并拦截 env-argv 赋值注入
Hook 失败模式（v2026.4.5+）：Hook 崩溃时采用 fail-closed 策略，不会默认放行

建议：

# 始终保持最新版本（优先内置升级）
openclaw update
# 内置升级不可用时再退回：npm update -g openclaw

# 查看安全公告
# https://github.com/openclaw/openclaw/security/advisories

# 运行安全审计
openclaw security audit
openclaw security audit --deep  # 包含实时探测

# 检查当前版本是否有已知漏洞
openclaw --version
# 对照 GitHub Releases 页面的安全说明

八、中国用户特别提示

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

Q65: API 访问不了怎么办？

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

解决方案：

# 方案一：使用代理
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
openclaw gateway --port 18789

# 方案二：使用 OpenRouter（一个 Key 用所有模型，通过环境变量设置 Key）
export OPENROUTER_API_KEY="sk-or-xxxxx"
openclaw config set agents.defaults.model "openrouter/openai/gpt-5.2"

# 方案三：使用国产模型（通过 OpenAI 兼容接口或 OpenRouter 接入）
# DeepSeek、Moonshot 等可配置为 OpenAI 兼容提供商：
# 在 ~/.openclaw/openclaw.json 中：
# { "models": { "providers": { "deepseek": { "baseUrl": "https://api.deepseek.com/v1" } } } }
# 然后设置环境变量和模型
openclaw config set agents.defaults.model "deepseek/deepseek-chat"

# 方案四：本地模型（推理阶段可以离线；首次拉取模型通常需要网络）
ollama pull qwen2.5:7b
openclaw config set agents.defaults.model "ollama/qwen2.5:7b"

Q66: WhatsApp 在中国能用吗？

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

替代方案：

Telegram（需要代理，但 Bot API 可以通过代理访问）
飞书 / Lark（国内原生支持，OpenClaw 通过扩展支持飞书 Channel）
微信存在官方文档收录的腾讯外部插件路径 @tencent-weixin/openclaw-weixin，见 05 章微信说明；它不等于微信群或微信公众号能力，也不能套用标准 pairing。钉钉等其他集成按各自插件文档核对。

# 配置飞书（推荐中国用户）
openclaw channels add feishu
# 按提示配置飞书开放平台的 App ID 和 App Secret

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

解决方案：

# 清除 npm 缓存
npm cache clean --force

# 确认镜像生效
npm config get registry
# 应该显示 https://registry.npmmirror.com

# 如果还是不行，试试直接下载
# 去 GitHub Releases 页面下载预编译包
# https://github.com/openclaw/openclaw/releases

# 或者用 Docker（镜像可以从国内源拉取）
docker pull openclaw/openclaw:latest

九、社区和贡献问题

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

Q68: 怎么报告 Bug？

解决方案：

去 GitHub Issues 页面
点击 "New Issue"
选择 "Bug Report" 模板
填写以下信息：

## 环境信息
- OpenClaw 版本：（openclaw --version）
- Node.js 版本：（node --version）
- 操作系统：
- 安装方式：npm / Docker

## 问题描述
简要描述遇到的问题

## 复现步骤
1. ...
2. ...
3. ...

## 期望行为
你期望发生什么

## 实际行为
实际发生了什么

## 日志
（openclaw logs --limit 50）

Q69: 怎么贡献代码？

流程：

# 1. Fork 仓库
# 在 GitHub 上点击 Fork

# 2. 克隆到本地
git clone https://github.com/your-username/openclaw.git
cd openclaw

# 3. 创建功能分支
git checkout -b feat/my-new-feature

# 4. 安装依赖并构建
pnpm install
pnpm ui:build
pnpm build

# 5. 开发和测试
pnpm gateway:watch
pnpm test

# 6. 提交代码
git add .
git commit -m "feat: add my new feature"

# 7. 推送并创建 PR
git push origin feat/my-new-feature
# 在 GitHub 上创建 Pull Request

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

建立 <workspace>/skills/my-awesome-skill/SKILL.md，写 name、description frontmatter 和操作步骤，再用 skills list、skills info my-awesome-skill、skills check 核查加载。在新对话中实际测试，确认结果和工具行为。分享时复制整个技能目录，保留所需脚本和示例，排除凭据及个人文件；社区发布按 ClawHub 官方指南进行。

Q71: 有中文社区吗？

说明：有的。

GitHub Issues（中英文都可以）：github.com/openclaw/openclaw/issues
Discord 社区（有中文频道）
微信群：关注 OpenClaw 公众号获取入群二维码

Q72: 文档有错误怎么反馈？

解决方案：

直接在 GitHub 上提 Issue，标注 docs 标签
或者直接提 PR 修改文档
OpenClaw 官方 Markdown 文档位于其 GitHub 仓库的 docs/ 目录

十、其他常见问题

Q73: OpenClaw 和 ChatGPT 有什么区别？

说明：它们是完全不同的东西：

维度

ChatGPT

OpenClaw

本质

AI 聊天产品

AI Agent 框架

模型

只能用 OpenAI 的模型

支持多个主流提供商

平台

网页/App

WhatsApp/Telegram/Discord 等

工具

有限的插件

可扩展的工具和技能系统

记忆

平台管理

你自己控制（本地 Markdown）

数据

平台管理，具体看 OpenAI / ChatGPT 数据政策

配置、记忆和聊天记录默认在你机器上；云端模型调用仍会发送给所选 provider

价格

订阅制

开源免费（API 费用另算）

简单说：ChatGPT 是一个产品，OpenClaw 是一个让你构建自己 AI 助手的工具。

Q74: OpenClaw 支持哪些语言？

说明： OpenClaw 本身是英文项目，但 AI 的回复语言取决于你使用的模型和系统提示词。

# 在 SOUL.md 中指定语言（编辑 ~/.openclaw/workspace/SOUL.md）
# 添加内容：
# ## 语言
# - 请始终用中文回复
# - 代码注释也使用中文

大多数主流云端模型都支持中文；本地模型里 Qwen（通义千问）系列通常是中文优先选择之一。具体效果要用你当前安装的模型实际测试，不要只看名字。

Q75: 一台机器能跑多个 OpenClaw 实例吗？

可以，但每个实例需要独立状态、workspace 和端口。推荐用 profile 创建并分别初始化：

openclaw --profile personal onboard
openclaw --profile personal gateway --port 18789

# 在另一终端或另一服务中启动，勿复用同一通道账号
openclaw --profile work onboard
openclaw --profile work gateway --port 19789

OPENCLAW_HOME 是 home 根目录，不能直接等同于状态目录。自定义状态路径使用 OPENCLAW_STATE_DIR。不要仅映射不同宿主端口却让容器共享写入同一组卷。

Q76: OpenClaw 会收费吗？

说明： OpenClaw 是开源项目（MIT 协议），工具本身免费。你需要付费的通常是云端 AI 模型 API 调用费用；本地模型（Ollama）没有按 token 计费，但仍有机器、电费、显存、下载和维护成本。

Q77: 怎么查看当前的所有配置？

解决方案：

# 查看默认模型配置（这里只返回这个配置项）
openclaw config get agents.defaults.model

# 查看特定配置项
openclaw config get models.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: 遇到问题怎么获取帮助？

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

查看本 FAQ 文档
查看官方文档
搜索 GitHub Issues（可能别人遇到过同样的问题）
在 GitHub Issues 提问
加入 Discord 社区实时交流

提问时请附上：

OpenClaw 版本（openclaw --version）
Node.js 版本（node --version）
操作系统信息
相关日志（前台运行 openclaw gateway --port 18789 --verbose 查看）

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

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

Q80: 从 v2026.3.2x 升级到当前版本（v2026.9.4）有哪些注意事项？

v2026.9.4 升级口径（核查日：2026-09-14）：升级命令优先用 openclaw update；只有数据库结构未变、旧包兼容且配置校验通过时，失败后才可能自动恢复旧包、配置和服务（v2026.9.1 起提供 triage 排障入口，保留配置和 secret 引用；v2026.9.3 起核心和插件改动先在隔离 candidate 状态预演）。两条硬约束：从 2026.8.2 升上来、机器上没有 service manager 的，先手动跑一次 openclaw update --no-restart；自动回滚不能撤销数据库迁移，升级前的备份仍然要做，并且要验证能恢复。下面 v2026.6.8 的关注点保留作历史，跨版本升级时仍然适用。

v2026.6.8 新增关注点：除了 v2026.4.x 和 v2026.5.x 的安全、通道、Transcript、模型目录、Docker 和 release integrity 改动之外，v2026.6.x 还重点改进 Agents / CLI runtime 恢复、消息通道稳定性、Skill Workshop、插件安装索引、Workboard、provider/model 覆盖、Control UI、fail-closed 边界、agent run recovery、SecretRef、/usage 和 release / diagnostics 证据链。升级后如果发现模型、通道、插件、技能或多 Agent 行为变化，先运行 openclaw doctor，再对照当前 release notes。

说明：从 v2026.4.x 到 v2026.6.8 的升级包含多项安全加固、性能优化、通道能力、插件/技能和多 Agent 更新。大部分配置向后兼容，但以下几点需要注意：

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，升级后请确认它们运行正常
自动化状态（9.4 参考）：任务、运行状态和历史已存入共享 SQLite 状态数据库。旧 jobs.json、-state.json 和 runs/.jsonl 只作为一次性迁移来源；迁移后用 automations 命令管理，不直接编辑旧 JSON。

升级步骤：

如果你仍在 v2026.3.x，先检查本机是否支持 openclaw backup。不支持时，停止 Gateway 和其他写入者，制作包含配置、数据库和工作区的文件系统或卷快照，并做恢复演练；不要跳过备份直接运行下面的升级命令。当前支持备份命令的版本可以这样做：

# 1. 备份（自动回滚不覆盖数据库迁移，这一步不能省，备份完试着恢复一次）
openclaw backup create --output ~/Backups/openclaw --verify

# 2. 升级（优先内置升级，失败后的回滚受状态兼容条件限制）
openclaw update
# 从 2026.8.2 升上来且没有 service manager：先跑 openclaw update --no-restart
# 内置升级不可用时再退回：npm update -g openclaw

# 3. 验证
openclaw --version
openclaw doctor
openclaw security audit

# 4. 如果使用反向代理，检查转发头配置（见 Q81）

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

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

需要确认的事项：

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

# 正确：覆盖客户端的转发头
proxy_set_header X-Forwarded-For $remote_addr;

# 错误（旧写法）：追加模式，可能被客户端伪造
# proxy_set_header X-Forwarded-For $proxy_add_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 所有者的实际身份验证，不再接受宽松的回退。

解决方案：

# 确保你通过已认证的 Owner 身份操作
# 1. 如果使用 Token 认证，确保连接时提供了正确的 Token
# 2. 如果使用配对系统，确保你是已配对的 Owner 用户
# 3. 通过 CLI 直接管理白名单
openclaw approvals get
openclaw approvals set --file ./exec-approvals.json  # 先按官方格式准备并审查；命令allowlist也可用 approvals allowlist add

Q83: 升级后启动变快了，是正常的吗？

说明：是的，这是正常现象。v2026.4.22 包含了显著的启动性能优化：

插件启动：原生 Jiti 加载捆绑插件的 dist 模块，捆绑插件加载时间降低 82-90%
Doctor 诊断：延迟加载 doctor 插件路径，doctor --non-interactive 运行时间降低约 74%
模型目录：静态模型目录替代运行时加载，减少启动时的网络请求

这些优化在 v2026.4.24 中进一步改善（通过 provider 依赖的延迟加载和 manifest-backed model rows）。

教程到这里就结束了！如果这份教程帮到了你，给个 Star 支持一下！