各平台专属的安装与权限故障
如果同一套安装在一台机器上正常、换一台就失败,差异几乎总是出在平台而不是 OpenClaw 本身。下面每个故障都只限于某一个操作系统,先在目录里找到你的平台即可——其余的与你无关。
技能安装失败:Linux 上未安装 Homebrew
某些 OpenClaw 技能(github、summarize)通过其清单将 Homebrew 声明为依赖项。在没有 Homebrew 的 Linux 服务器上,技能安装程序会失败并显示“brew not installed”。以下是您的选择。
✅ 修复方法 1 — 在 Linux 上安装 Homebrew(Linuxbrew)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 添加到 PATH(添加到 ~/.bashrc 或 ~/.zshrc) echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" # 验证 brew --version
✅ 修复方法 2 — 手动安装技能依赖项
# 对于 'github' 技能 — 安装 GitHub CLI curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo gpg --dearmor -o /usr/share/keyrings/githubcli-archive-keyring.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null sudo apt update && sudo apt install gh # 对于 'summarize' 技能 — 安装 pandoc sudo apt install pandoc
✅ 修复方法 3 — 跳过失败的技能
# 在 openclaw.yaml 中,禁用需要 Homebrew 的技能
skills:
disabled:
- github
- summarize某些技能使用 Homebrew 安装系统级工具二进制文件(如 GitHub CLI 'gh' 或 summarize 的 pandoc)。Linux 上的 Homebrew 安装到 /home/linuxbrew/.linuxbrew,不需要 root 权限。
Windows 11:QMD 内存后端 — tsx 模块找不到
在 Windows 11 上通过 Bun 安装的 QMD 因模块解析错误而失败。qmd 二进制文件找不到 Bun 注入的 tsx 运行时。
- →Error: Cannot find module 'tsx'
- →Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'tsx'
- →qmd: failed to resolve runtime — ensure tsx is installed globally
✅ 修复方法 1 — 使用 Node.js + npx 代替 Bun
# 通过 Bun 卸载 QMD bun uninstall -g qmd # 改用 npm 安装 npm install -g @openclaw/qmd # 验证 qmd --version
✅ 修复方法 2 — 通过 npm 全局安装 tsx
# 全局安装 tsx npm install -g tsx # 验证解析 tsx --version # 然后重新安装 QMD bun install -g qmd
✅ 修复方法 3 — 手动指定正确的 QMD 二进制路径
# 在 openclaw.json 中指定完整路径:
{
"memory": {
"provider": "qmd",
"qmd": {
"bin": "C:\\Users\\用户名\\AppData\\Roaming\\bun\\bin\\qmd.exe"
}
}
}树莓派 5:无法读写文件或安装技能
在树莓派 OS(64位)上全新安装 OpenClaw 后,代理通常会处于仅会话权限模式。即使 OS 用户拥有完全访问权限,代理也会报告无法读写文件或安装技能。
- →"我没有权限读取或写入您系统上的文件。"
- →"我无法安装技能 — 由于我没有必要的权限,您需要自己完成此操作。"
✅ 修复方法 1 — 将 tools.profile 设置为 'coding'(与 v2026.3.2 相同的修复)
# 编辑 ~/.openclaw/openclaw.json
{
"tools": {
"profile": "coding"
}
}
# 重启网关
openclaw gateway restart✅ 修复方法 2 — 验证 OpenClaw 以正确的用户运行
# 检查谁在运行网关进程 ps aux | grep openclaw # 应该显示您的 Pi 用户(例如 'pi'),而不是 'root' # 如果以 root 运行,请在您的用户账户下重新安装
✅ 修复方法 3 — 为文件操作授予工作区访问权限
# 在 openclaw.yaml 中设置工作区目录
workspace:
dir: /home/pi/openclaw-workspace
allow:
- read
- write
- execute🥧 推荐的树莓派 5 配置
# 型号:树莓派 5(8GB)— 强烈推荐 # 存储:64GB+ A2 级 microSD 或通过 PCIe HAT 连接的 NVMe SSD # 散热:主动散热器(树莓派官方)— 持续推理时至关重要 # 模型:通过 Ollama 使用 Gemma 2B / Phi-3-mini / Qwen2-0.5B # 在 Pi 5 上安装 Ollama: curl -fsSL https://ollama.com/install.sh | sh ollama run phi3:mini
screen_record 被沙箱阻止 & system.which 失败
screen_record 工具被 'session' 工具配置文件阻止,当工具配置文件不包含 exec 权限时 system.which 也会失败。这两者都是 v2026.3.2 中默认安全行为。
✅ 修复方法 1 — 明确允许 screen_record
# 在 openclaw.json 中,将 screen_record 加入白名单
{
"tools": {
"profile": "session",
"allow": ["screen_record"]
}
}
# 或切换到宽松配置文件:
# "profile": "coding" (包含 exec + 系统工具)✅ 修复方法 2 — 通过启用 exec 权限修复 system.which
# system.which 需要 'exec' 能力
{
"tools": {
"profile": "session",
"allow": ["system.which", "run_bash"]
}
}screen_record 授予代理捕获您屏幕的能力。只在受信任的环境中和您控制的代理中启用此功能。在无头服务器上,这个工具无论如何都没有用。
控制 UI:Windows 上工具开关不持久化(v2026.3.2)
在 Windows 上使用 v2026.3.2,在控制 UI 中切换工具(启用/禁用 read_file、run_bash 等)看起来已保存,但刷新页面后会恢复。这是控制 UI 的 localStorage 同步中的已知回归。
- →在控制 UI 中开/关工具 → 保存 → 看起来已保存
- →刷新页面 → 开关恢复到之前的状态
- →只在 Windows 上出现 — Mac 和 Linux 不受影响
✅ 修复方法 1 — 直接在 openclaw.json 中设置工具权限
# 直接编辑 ~/.openclaw/openclaw.json
{
"tools": {
"profile": "coding",
"deny": ["screen_record", "open_browser"]
}
}✅ 修复方法 2 — 清除浏览器缓存和存储
# 在 Chrome/Edge 中: # 打开开发者工具 → 应用程序 → 存储 → 清除站点数据 # 然后重新加载控制 UI # 或通过地址栏清除: chrome://settings/clearBrowserData
✅ 修复方法 3 — 使用 CLI 设置工具配置文件
# 使用 openclaw CLI 设置配置文件 openclaw config set tools.profile coding openclaw config set tools.deny screen_record # 验证 openclaw config get tools
在 Issue #35297 中追踪。预计在 v2026.3.3 中修复。根本原因是标签页失去焦点时,Windows 上的控制 UI 会丢失 localStorage 写入。