Platform-specific install and permission failures
If an install works on one machine and fails on another, the difference is almost always the platform rather than OpenClaw. Each fault below is confined to a single operating system, so start by finding your platform in the list β the others will not apply to you.
Skill Install Fails: Homebrew Not Installed on Linux
Some OpenClaw skills (github, summarize) declare Homebrew as a dependency via their manifest. On Linux servers without Homebrew, the skill installer fails with 'brew not installed'. Here are your options.
β Fix 1 β Install Homebrew on Linux (Linuxbrew)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Add to PATH (add to ~/.bashrc or ~/.zshrc) echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" # Verify brew --version
β Fix 2 β Install Skill Dependencies Manually
# For 'github' skill β installs 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 # For 'summarize' skill β installs pandoc sudo apt install pandoc
β Fix 3 β Skip the Failing Skills
# In openclaw.yaml, disable skills that need Homebrew
skills:
disabled:
- github
- summarizeSome skills use Homebrew to install system-level tool binaries (like the GitHub CLI 'gh' or pandoc for summarize). Homebrew on Linux installs to /home/linuxbrew/.linuxbrew and doesn't require root.
Windows 11: QMD Memory Backend β tsx Module Not Found
QMD installed via Bun on Windows 11 fails with module resolution errors. The qmd binary can't find the tsx runtime injected by Bun.
- βError: Cannot find module 'tsx'
- βError [ERR_MODULE_NOT_FOUND]: Cannot find package 'tsx'
- βqmd: failed to resolve runtime β ensure tsx is installed globally
β Fix 1 β Use Node.js + npx instead of Bun
# Uninstall QMD via Bun bun uninstall -g qmd # Install via npm instead npm install -g @openclaw/qmd # Verify qmd --version
β Fix 2 β Install tsx globally via npm
# Install tsx globally npm install -g tsx # Verify it resolves tsx --version # Then re-install QMD bun install -g qmd
β Fix 3 β Specify the correct QMD binary path manually
# In openclaw.json, specify the full path:
{
"memory": {
"provider": "qmd",
"qmd": {
"bin": "C:\\Users\\YourUsername\\AppData\\Roaming\\bun\\bin\\qmd.exe"
}
}
}Raspberry Pi 5: Can't Read/Write Files or Install Skills
Fresh installs of OpenClaw on Raspberry Pi OS (64-bit) often leave the agent in a session-only permission mode. The agent reports it can't read/write files or install skills, even though the OS user has full access.
- β"I don't have permission to read or write files on your system."
- β"I'm unable to install skills β you'll need to do this yourself as I don't have the necessary permissions."
β Fix 1 β Set tools.profile to 'coding' (Same Fix as v2026.3.2)
# Edit ~/.openclaw/openclaw.json
{
"tools": {
"profile": "coding"
}
}
# Restart gateway
openclaw gateway restartβ Fix 2 β Verify OpenClaw is Running as the Correct User
# Check who is running the gateway process ps aux | grep openclaw # Should show your Pi user (e.g. 'pi'), NOT 'root' # If running as root, reinstall under your user account
β Fix 3 β Grant Workspace Access for File Operations
# In openclaw.yaml, set the workspace directory
workspace:
dir: /home/pi/openclaw-workspace
allow:
- read
- write
- executeπ₯§ Recommended Pi 5 Configuration
# Model: Raspberry Pi 5 (8GB) β strongly recommended # Storage: 64GB+ A2-rated microSD or NVMe SSD via PCIe HAT # Cooling: Active cooler (Raspberry Pi official) β critical for sustained inference # Models: Gemma 2B / Phi-3-mini / Qwen2-0.5B via Ollama # Install Ollama on Pi 5: curl -fsSL https://ollama.com/install.sh | sh ollama run phi3:mini
screen_record Blocked by Sandbox & system.which Fails
The screen_record tool is blocked by the 'session' tools profile, and system.which fails when the tool profile doesn't include exec permissions. Both are security-by-default behaviors in v2026.3.2.
β Fix 1 β Allow screen_record Explicitly
# In openclaw.json, whitelist screen_record
{
"tools": {
"profile": "session",
"allow": ["screen_record"]
}
}
# Or switch to a permissive profile:
# "profile": "coding" (includes exec + system tools)β Fix 2 β Fix system.which by Enabling exec Permission
# system.which requires 'exec' capability
{
"tools": {
"profile": "session",
"allow": ["system.which", "run_bash"]
}
}screen_record grants the agent ability to capture your screen. Only enable this in a trusted environment and with agents you control. On a headless server, this tool is not useful anyway.
Control UI: Tools Toggles Don't Persist on Windows (v2026.3.2)
On Windows with v2026.3.2, toggling tools in the Control UI (enable/disable read_file, run_bash, etc.) appears to save, but reverts on page refresh. This is a known regression in the Control UI's localStorage sync.
- βToggle a tool on/off in Control UI β Save β looks saved
- βRefresh the page β toggles revert to previous state
- βOnly happens on Windows β Mac and Linux are unaffected
β Fix 1 β Set Tool Permissions in openclaw.json Instead
# Edit ~/.openclaw/openclaw.json directly
{
"tools": {
"profile": "coding",
"deny": ["screen_record", "open_browser"]
}
}β Fix 2 β Clear Browser Cache and Storage
# In Chrome/Edge: # Open DevTools β Application β Storage β Clear Site Data # Then reload the Control UI # Or clear via address bar: chrome://settings/clearBrowserData
β Fix 3 β Use the CLI to Set Tool Profile
# Use the openclaw CLI to set profile openclaw config set tools.profile coding openclaw config set tools.deny screen_record # Verify openclaw config get tools
Tracked in Issue #35297. A fix is expected in v2026.3.3. The root cause is that the Control UI on Windows loses localStorage writes when the tab loses focus.