Install OpenClaw on Linux

Linux provides an excellent foundation for running OpenClaw, offering stability, low overhead, and powerful system management tools. The combination of OpenClaw with Linux's systemd service manager enables robust, always-on operation with automatic restarts, logging, and resource management.

This guide covers installation on the most popular Linux distributions: Ubuntu and its derivatives, Debian, Fedora and RHEL-based systems, and Arch Linux. While the core OpenClaw installation is distribution-agnostic, package management, service configuration, and system-specific optimizations vary between distributions.

Why Linux for OpenClaw

Linux servers power the majority of cloud infrastructure, making Linux skills directly applicable to cloud OpenClaw deployments. The open-source ecosystem aligns with OpenClaw's philosophy. Low resource overhead means more headroom for conversations and channels. Native systemd integration provides enterprise-grade service management.

For always-on personal assistants, Linux on modest hardware (mini PCs, Raspberry Pi, old laptops) offers an economical alternative to cloud hosting. For enterprise deployments, Linux provides the security, stability, and manageability expected in production environments.

Architecture Support

OpenClaw supports both x86_64 and ARM64 Linux architectures. AMD and Intel processors use x86_64 builds. ARM64 supports Raspberry Pi 4/5, AWS Graviton, Apple Silicon (via Docker/VM), and other ARM servers. Verify your architecture with uname -m before installation.

This section provides installation instructions tailored to major Linux distributions. Node.js installation varies between distributions; OpenClaw installation itself is consistent once Node.js is available.

Ubuntu / Debian Installation

Ubuntu and Debian use apt for package management. Install Node.js 22 from the NodeSource repository, which provides current Node.js versions across Debian-based distributions. After adding the repository, install Node.js with apt.

The NodeSource setup script detects your distribution and version automatically. After installation, verify Node.js shows version 22.x.x before proceeding with OpenClaw installation.

Fedora / RHEL Installation

Fedora and RHEL-based distributions (CentOS Stream, Rocky Linux, AlmaLinux) use dnf for package management. Node.js 22 is available from NodeSource or the Fedora repositories depending on your distribution version.

For Fedora, the default repositories may have current Node.js versions. For RHEL-based systems, NodeSource provides the easiest path to Node.js 22. Enable the repository and install with dnf.

Arch Linux Installation

Arch Linux typically has the latest Node.js versions in official repositories. Install with pacman, which handles Node.js and npm together. Arch users often prefer the latest software versions, making it well-suited for OpenClaw.

The Arch User Repository (AUR) may contain OpenClaw packages maintained by the community. Check the AUR for simplified installation, though manual npm installation remains fully supported.

Other Distributions

For other distributions (openSUSE, Gentoo, Alpine, etc.), the general approach applies: install Node.js 22 using your distribution's package manager or NodeSource, then install OpenClaw via npm. Consult your distribution's documentation for Node.js installation specifics.

With Node.js installed, the OpenClaw installation process is consistent across all Linux distributions. This section covers global installation, onboarding, and verification.

Global npm Installation

Install OpenClaw as a global npm package. The installation downloads OpenClaw and all dependencies. On some systems, global npm installations require sudo; alternatively, configure npm to use a user-writable directory for global packages to avoid permission issues.

Verify the installation by checking the OpenClaw version. If the command isn't found, ensure npm's global bin directory is in your PATH. The typical location is ~/.npm-global/bin for user installations or /usr/local/bin for system-wide installations.

Running Onboarding

Execute the onboarding wizard to configure OpenClaw. The wizard creates configuration files, sets up the workspace directory, and offers to install the systemd service for daemon operation. On Linux, the daemon installs as a systemd user service.

During onboarding, configure your AI model provider and optionally connect messaging channels. API keys can be entered interactively or pre-configured as environment variables. The wizard validates connections and reports any issues.

Systemd User Service

The onboarding wizard installs a systemd user service for daemon operation. This service runs in your user context, starting when you log in and managed by systemctl --user commands. For server deployments where no user logs in interactively, enable lingering to start services at boot.

The service file installs at ~/.config/systemd/user/openclaw.service. User services don't require root privileges for management, aligning with the principle of least privilege.

Verification

After onboarding, verify the installation by checking Gateway status and accessing the WebChat interface. The status command reports daemon state. Open http://localhost:18789 in a browser to access WebChat. Send a test message to confirm AI connectivity.

systemd provides powerful service management for OpenClaw on Linux. Understanding systemd commands and configuration helps with troubleshooting and customization.

Basic Service Commands

Control the OpenClaw service with systemctl commands. The --user flag indicates a user-level service rather than system service. Start, stop, restart, and status commands work as expected. Enable and disable control automatic startup.

Viewing Logs

View service logs with journalctl. The -u flag filters by service unit, --user indicates user services, and -f follows logs in real-time. journalctl provides powerful filtering options for troubleshooting specific time ranges or message types.

Enable Lingering

By default, user services stop when the user logs out. For servers or headless systems, enable lingering to start services at boot regardless of login state. Use loginctl enable-linger to enable this for your user. This is essential for always-on server deployments.

Service File Customization

The service file at ~/.config/systemd/user/openclaw.service can be customized. Common modifications include adding environment variables, adjusting restart behavior, or setting resource limits. After editing, reload the daemon configuration with systemctl --user daemon-reload.

System-Level Service

For multi-user deployments or services that must start before any user login, a system-level service may be appropriate. This requires creating a dedicated openclaw user, placing the service file in /etc/systemd/system/, and configuring appropriate permissions. Most single-user deployments work well with user services.

OpenClaw configuration on Linux follows standard patterns with some platform-specific considerations for optimal operation.

Configuration File Location

The main configuration file lives at ~/.openclaw/openclaw.json in your home directory. This location follows XDG conventions for user configuration. The workspace at ~/.openclaw/workspace/ contains agent files and skills. Data storage at ~/.openclaw/data/ holds session information.

Environment Variables

Set environment variables in your shell profile (~/.bashrc, ~/.zshrc) or in the systemd service file. For systemd services, the Environment directive in the service file sets variables for the daemon. Alternatively, create an EnvironmentFile with key-value pairs.

Sensitive values like API keys should be set as environment variables rather than stored in configuration files. This prevents accidental exposure through backups or configuration sharing.

Firewall Configuration

Most Linux distributions include firewall software (ufw on Ubuntu, firewalld on Fedora). Configure your firewall to allow OpenClaw ports if you need network access beyond localhost. Port 18789 handles WebSocket and WebChat; port 18793 serves Canvas files.

For local-only operation, no firewall changes are needed. For LAN access, allow the ports from your local network range. For internet access, consider a reverse proxy with authentication rather than direct exposure.

SELinux/AppArmor

Security modules like SELinux (Fedora/RHEL) or AppArmor (Ubuntu) may restrict OpenClaw operations. If you encounter permission denied errors not explained by file permissions, check security module logs. Creating appropriate policies or enabling permissive mode for troubleshooting can help identify issues.

Linux provides extensive security capabilities. This section covers security hardening appropriate for OpenClaw deployments.

User Isolation

Run OpenClaw as a dedicated non-root user for better isolation. Create an openclaw user with limited permissions. This user needs only write access to the OpenClaw directories and network access for messaging platforms and AI APIs. System-level service configurations should specify this dedicated user.

File Permissions

Set appropriate permissions on OpenClaw directories. The configuration file containing potential credentials should be readable only by the owner (chmod 600). Directories need execute permission for traversal (chmod 700). Avoid world-readable permissions on any OpenClaw files.

Firewall Rules

Configure iptables or your distribution's firewall frontend to restrict OpenClaw network access. Allow outbound HTTPS for API calls. Restrict inbound connections to necessary ports and source addresses. Drop all other traffic by default.

systemd Hardening

systemd provides security directives for service isolation. Add options like PrivateTmp, ProtectSystem, and NoNewPrivileges to the service file. These restrict what the service can access even if compromised. The official OpenClaw service file includes reasonable defaults; review and strengthen for high-security environments.

Automatic Updates

Enable unattended security updates for your distribution. Ubuntu's unattended-upgrades, Fedora's dnf-automatic, or equivalent tools ensure security patches apply promptly. Consider separate update strategies for the OS and OpenClaw itself, testing OpenClaw updates before automatic deployment.

Audit Logging

Enable auditd for detailed security logging on servers. Configure audit rules for OpenClaw directories and processes. This provides forensic capability if security issues occur. For personal systems, standard journald logging typically suffices.

Optimize OpenClaw performance on Linux through system tuning and configuration adjustments.

Resource Limits

Set appropriate resource limits to prevent runaway memory or CPU usage. systemd service files support MemoryMax and CPUQuota directives. ulimit settings in shell profiles affect interactive sessions. For production, set limits that allow normal operation while protecting system stability.

Swap Configuration

Configure appropriate swap space as a safety net for memory pressure. On SSDs, swap is fast enough to prevent hard out-of-memory situations. Set swappiness lower (10-30) to prefer keeping application memory in RAM while having swap available for emergencies.

I/O Optimization

For systems with SSDs, ensure TRIM is enabled for drive longevity. Place OpenClaw's data directory on fast storage for best database performance. If using spinning disks, consider a small SSD for the database while keeping bulk storage on HDD.

Network Tuning

For high-throughput deployments, tune network settings. Increase socket buffer sizes if handling many concurrent connections. Adjust TCP keepalive settings for long-lived WebSocket connections. Most personal deployments work well with defaults.

Container Deployment

For complex deployments, Docker or Podman containers provide consistent environments and resource isolation. Linux's native container support is efficient with minimal overhead. See our Docker guide for containerized deployment patterns.

This section addresses common issues encountered on Linux OpenClaw installations.

Permission Denied Errors

Permission errors often stem from incorrect file ownership or restrictive security modules. Check file ownership matches your user with ls -la. Review SELinux (getenforce, ausearch -m AVC) or AppArmor (aa-status, journalctl | grep apparmor) for denials. Temporarily disabling security modules can confirm if they're the cause.

Service Won't Start

If systemd service fails, check journalctl -u openclaw --user -n 50 for recent errors. Common causes include missing Node.js in PATH, configuration file errors, or port conflicts. The ExecStart path in the service file must correctly locate the openclaw binary.

Command Not Found

If openclaw command isn't found, npm's global bin directory isn't in PATH. Find it with npm list -g and add to your PATH in ~/.bashrc. On some distributions, logging out and back in applies PATH changes.

Network Connectivity Issues

Test connectivity to AI APIs and messaging platforms with curl. Check firewall rules allow outbound HTTPS. DNS resolution issues can block connections; verify with nslookup or dig. Corporate networks may require proxy configuration.

High Memory Usage

Memory growth over time may indicate conversation history accumulation or memory leaks. Restart the daemon to clear state. If issues persist, check for problematic skills and review configuration limits for conversation length and session count.

Service Stops After Logout

User services stop when the user logs out unless lingering is enabled. Run loginctl enable-linger $USER to enable, then systemctl --user enable openclaw to enable the service. This combination ensures the service starts at boot and runs continuously.