The Problem
You see errors like:
EACCES: permission denied
Or:
Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
Or:
Permission denied: ~/.openclaw/config.yaml
What This Means
Your user account does not have permission to read or write to certain files or directories. This is common on Linux and macOS, especially when installing global npm packages.
Quick Fix for npm Installation Errors
If you see permission errors during npm install -g openclaw:
Option 1: Fix npm Permissions (Recommended)
This is the safest and best long-term solution.
Create a directory for global packages:
mkdir -p ~/.npm-global
Configure npm to use this directory:
npm config set prefix '~/.npm-global'
Add to your PATH:
For bash (most Linux and older macOS):
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
For zsh (newer macOS):
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
Now install OpenClaw:
npm install -g openclaw
Option 2: Use sudo (Quick but Not Recommended)
Not Recommended for Regular Use
Using sudo for npm can cause more permission problems later. Use Option 1 if possible.
sudo npm install -g openclaw
Permission Errors with OpenClaw Config Directory
If you see errors about ~/.openclaw/:
Check Current Permissions
ls -la ~/.openclaw
Expected Result
drwxr-xr-x user user .openclaw -rw-r--r-- user user config.yaml -rw------- user user auth-profiles.json
The owner should be your username, not root.
Fix Ownership
sudo chown -R $(whoami) ~/.openclaw
Fix Permission Mode
chmod -R u+rw ~/.openclaw
chmod 600 ~/.openclaw/auth-profiles.json
The auth-profiles.json should have restricted permissions (600) since it contains sensitive data.
Permission Errors with npm Cache
If you see errors about the npm cache:
sudo chown -R $(whoami) ~/.npm
Permission Errors on macOS
Homebrew Permissions
If Homebrew has permission issues:
sudo chown -R $(whoami) /usr/local/Cellar
sudo chown -R $(whoami) /usr/local/Homebrew
Apple Silicon (M1/M2/M3) Macs
On newer Macs, Homebrew installs to /opt/homebrew/:
sudo chown -R $(whoami) /opt/homebrew
Permission Errors on Linux
Global Node Modules
If /usr/local/lib/node_modules has permission issues:
Option 1: Change ownership (simple):
sudo chown -R $(whoami) /usr/local/lib/node_modules
Option 2: Use npm prefix (better):
See the "Quick Fix" section above for setting up ~/.npm-global.
Systemd Service Permissions
If the daemon cannot start:
Check the service status
systemctl --user status openclaw
Check logs for permission errors
journalctl --user -u openclaw -n 50
Fix user service directory:
mkdir -p ~/.config/systemd/user
chmod 755 ~/.config/systemd/user
/tmp Permission Issues
If OpenClaw has trouble with temporary files:
Check /tmp permissions
ls -la /tmp
Should show: drwxrwxrwt
The 't' (sticky bit) is important
Common Scenarios
Scenario 1: Installed with sudo, Now Getting Errors
If you previously used sudo npm install and now have permission problems:
Fix npm directory
sudo chown -R $(whoami) ~/.npm
Fix global modules (if you own them)
sudo chown -R $(whoami) /usr/local/lib/node_modules/openclaw
Fix OpenClaw config
sudo chown -R $(whoami) ~/.openclaw
Scenario 2: Multiple Users on Same Computer
If multiple users need OpenClaw, each should:
- Have their own
~/.openclawdirectory - Install OpenClaw in their own npm prefix
Or use Docker for isolation.
Scenario 3: Running as Root
Do Not Run as Root
Running OpenClaw as root is a security risk. Always run it as a regular user.
If you accidentally ran something as root:
Fix ownership
sudo chown -R $(whoami) ~/.openclaw
sudo chown -R $(whoami) ~/.npm
Checking Permissions
Understanding Permission Notation
When you run ls -la, permissions look like: -rw-r--r--
-
Position 1 - File type (- = file, d = directory)
-
Position 2-4 - Owner permissions (rwx)
-
Position 5-7 - Group permissions (rwx)
-
Position 8-10 - Others permissions (rwx)
-
r= read -
w= write -
x= execute (or access for directories)
Recommended Permissions for OpenClaw
~/.openclaw/- Permission 755 →chmod 755 ~/.openclawconfig.yaml- Permission 644 →chmod 644 ~/.openclaw/config.yamlauth-profiles.json- Permission 600 →chmod 600 ~/.openclaw/auth-profiles.json- Channel tokens - Permission 600 →
chmod 600 ~/.openclaw/channels/*
Security Audit
Run the built-in security check:
openclaw security audit --deep
This will warn you about permission issues.
Prevention Tips
-
Never use sudo with npm for package installation unless absolutely necessary
-
Set up npm prefix correctly from the start (see Quick Fix above)
-
Check ownership after system updates as updates can sometimes change permissions
-
Use a dedicated user for running OpenClaw on servers
-
Regular security audits:
openclaw security audit
Docker Alternative
If permission issues persist, consider using Docker:
docker run -d --name openclaw
-v openclaw_data:/root/.openclaw
-p 18789:18789
openclaw:local
Docker handles permissions within the container, avoiding most host permission issues.
See: Install OpenClaw with Docker
Still Having Issues?
- Gather diagnostic information:
ls -la ~/.openclaw
ls -la ~/.npm
id
whoami
- Check the logs:
openclaw logs --limit 50
- Try a fresh install with correct permissions:
Remove old installation
sudo npm uninstall -g openclaw
rm -rf ~/.openclaw
Set up npm correctly
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
Fresh install
npm install -g openclaw
openclaw onboard
Need Help?
If you run into problems not covered here, check our Troubleshooting guide or visit the official OpenClaw documentation.
Last updated: February 3, 2026 | Found an error? Contact us