一、安装和配置问题
这份 FAQ 是老金按真实卡点整理的，不是为了凑问题数；能定位问题，比背答案更重要。
2026-06-18 排障口径：当前稳定基线为 v2026.6.8。升级优先用
openclaw update，再用openclaw doctor和 channel / gateway 日志定位问题；repair可修复插件、payload、registry 和部分本地状态，但不会替你重新安装 core 或重启 Gateway。
📌 本节包含 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 环境变量。
解决方案：
# 第一步：确认是否真的安装了
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
# 把输出的路径加入 PATHQ2: Node.js 版本不兼容
现象： 安装时报错 engine "node" is incompatible 或运行时出现语法错误。
原因： OpenClaw 当前官方建议使用 Node.js 24.x；22.19+ 仍然兼容。低于兼容线时，常见报错就是 engine incompatible、运行时语法错误或部分 API 不可用。
解决方案：
# 检查当前版本
node --version
# 如果低于 v22，用 nvm 升级
# 安装 nvm（如果还没装）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
# 重新打开终端，然后：
nvm install 24
nvm use 24
nvm alias default 24 # 设为默认版本
# 验证
node --version # 应该显示 v24.x.xWindows 用户推荐用 nvm-windows：
nvm install 24
nvm use 24Q3: 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="~/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw
# 方案二：用 sudo（不推荐，但能快速解决）
sudo npm install -g openclaw
# 方案三：用 nvm 管理 Node.js（最佳实践）
# nvm 安装的 Node.js 不需要 sudoQ4: 中国网络环境安装慢或失败
现象： 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:latestQ5: 安装时报 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 ToolsQ6: 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 onboardQ7: 配置文件在哪里？怎么手动编辑？
现象： 想直接编辑配置文件，但不知道在哪。
说明： OpenClaw 的所有配置都在 ~/.openclaw/ 目录下。
# 查看配置目录结构
ls -la ~/.openclaw/
# 主要文件：
# ~/.openclaw/openclaw.json — 主配置文件（JSON5 格式）
# ~/.openclaw/workspace/ — 工作空间（记忆、技能等）
# ~/.openclaw/gateway/ — Gateway 运行时数据
# 用命令查看当前配置
openclaw config get
# 用命令修改配置（推荐，会自动验证格式）
openclaw config set <key> <value>
# 也可以直接编辑 JSON5 文件
nano ~/.openclaw/openclaw.jsonQ8: 多个 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 会自动读取环境变量，不需要在配置文件中写 KeyQ9: 环境变量和配置文件哪个优先？
说明： 优先级从高到低：
命令行参数 > 环境变量 > ~/.openclaw/openclaw.json > 默认值也就是说，如果你同时在环境变量和配置文件里设了 API Key，环境变量的值会生效。
Q10: 升级 OpenClaw 后配置丢失了
现象： 更新到新版本后，之前的配置好像不见了。
原因： 正常情况下升级不会覆盖配置。但如果你用 Docker 部署且没有挂载数据卷，容器重建后数据会丢失。
解决方案：
# 升级前先备份
cp -r ~/.openclaw ~/.openclaw.backup
# npm 升级（配置不会丢）
npm update -g openclaw
# Docker 升级（确保挂载了数据卷）
# docker-compose.yml 中必须有：
# volumes:
# - ./data:/root/.openclaw
# 如果配置真的丢了，从备份恢复
cp -r ~/.openclaw.backup ~/.openclawQ11: 升级后功能异常怎么回滚？
现象： 执行 npm update -g openclaw 升级到新版本后，之前正常的功能出现报错、崩溃或行为异常，需要退回旧版本。
解决方案：
# 查看当前版本
openclaw --version
# 查看所有可用版本
npm view openclaw versions --json
# 回滚到指定版本
npm install -g openclaw@2026.3.28
# Docker 回滚
docker pull openclaw/openclaw:v2026.3.28
# 修改 docker-compose.yml 中的 image tag 后重启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 无法检查其是否包含恶意软件」，命令被阻止执行。
解决方案：
# 方案一：在系统偏好设置中允许
# 系统偏好设置 → 隐私与安全性 → 仍然允许
# 方案二：通过命令行移除隔离属性
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
kill -9 <PID>
# Windows
netstat -ano | findstr 18789
taskkill /PID <PID> /F
# 或者换一个端口
openclaw config set gateway.port 18790
openclaw gateway startQ15: 怎么完全卸载 OpenClaw？
现象： 不再使用 OpenClaw，想彻底从系统中移除所有相关文件（包括程序、配置和数据）。
解决方案：
# 停止 Gateway
openclaw gateway stop
# 卸载 npm 包
npm uninstall -g openclaw
# 删除配置和数据（谨慎操作，不可恢复）
rm -rf ~/.openclaw
# Docker 方式
docker compose down -v
docker rmi openclaw/openclaw:latest